Skip to content

stations_near

stations_near

stations_near(points: DataFrame, info: DataFrame, *, radius_m: float = 300.0, point_lat: str = 'lat', point_lon: str = 'lon') -> DataFrame

For each external point, how many stations are nearby: the accessibility primitive.

The inverse of features_within: there you summarise things around stations; here you ask, for arbitrary places (clinics, schools, neighbourhood centroids), how well each is served by stations. Straight-line (great-circle) proximity only; no routing.

Parameters:

Name Type Description Default
points DataFrame

Places of interest with point_lat/point_lon columns.

required
info DataFrame

Canonical station inventory (lat/lon, optionally station_id).

required
radius_m float
300

Returns:

Type Description
DataFrame

points + n_stations_within, nearest_station_dist_m and (if info has station_id) nearest_station_id.

See Also

GeoKDTree : The spatial index underneath. find_nearest_stations : k-nearest instead of radius. features_within : Join external features in a buffer.

Source code in src/gbfs_toolkit/spatial/geometry.py
def stations_near(
    points: pd.DataFrame,
    info: pd.DataFrame,
    *,
    radius_m: float = 300.0,
    point_lat: str = "lat",
    point_lon: str = "lon",
) -> pd.DataFrame:
    """For each external point, how many stations are nearby: the accessibility primitive.

    The inverse of [`features_within`][gbfs_toolkit.features_within]: there you summarise things *around stations*; here
    you ask, for arbitrary places (clinics, schools, neighbourhood centroids), *how well each is
    served by stations*. Straight-line (great-circle) proximity only; no routing.

    Parameters
    ----------
    points : pandas.DataFrame
        Places of interest with ``point_lat``/``point_lon`` columns.
    info : pandas.DataFrame
        Canonical station inventory (``lat``/``lon``, optionally ``station_id``).
    radius_m : float, default 300

    Returns
    -------
    pandas.DataFrame
        ``points`` + ``n_stations_within``, ``nearest_station_dist_m`` and (if ``info`` has
        ``station_id``) ``nearest_station_id``.

    See Also
    --------
    [`GeoKDTree`][gbfs_toolkit.GeoKDTree] : The spatial index underneath.
    [`find_nearest_stations`][gbfs_toolkit.find_nearest_stations] : k-nearest instead of radius.
    [`features_within`][gbfs_toolkit.features_within] : Join external features in a buffer.
    """
    out = points.reset_index(drop=True).copy()
    if out.empty:
        out["n_stations_within"] = pd.Series(dtype="int64")
        out["nearest_station_dist_m"] = pd.Series(dtype="float64")
        return out
    if info.empty:
        out["n_stations_within"] = 0
        out["nearest_station_dist_m"] = np.inf
        if "station_id" in info.columns:
            out["nearest_station_id"] = None
        return out
    tree = GeoKDTree(info["lat"], info["lon"])
    lat, lon = out[point_lat].to_numpy(), out[point_lon].to_numpy()
    within = tree.query_radius(lat, lon, radius_m=radius_m)
    dist, idx = tree.query(lat, lon, k=1)
    out["n_stations_within"] = [len(h) for h in within]
    out["nearest_station_dist_m"] = np.asarray(dist).ravel()
    if "station_id" in info.columns:
        out["nearest_station_id"] = info["station_id"].to_numpy()[np.asarray(idx).ravel()]
    return out