Skip to content

station_surroundings

station_surroundings

station_surroundings(info: DataFrame, *, transit: DataFrame | None = None, osm: Any = None, radius_m: float = 300.0, transit_radius_m: float | None = None, osm_category_col: str | None = None) -> DataFrame

One-shot "what's around each station": transit feeders + OSM features in a radius.

Combines link_transit_stops and enrich_with_osm / features_within into a single context frame.

Parameters:

Name Type Description Default
info DataFrame

Canonical station inventory.

required
transit DataFrame

GTFS stops-style frame; adds nearest_stop_dist_m, n_transit_within, is_transit_feeder.

None
osm GeoDataFrame or DataFrame

OSM features (GeoDataFrame → geometry reduced automatically) or a plain lat/lon frame; adds osm_within + per-category counts.

None
radius_m float

Radius for OSM features (and transit if transit_radius_m is not set).

300
transit_radius_m float

Separate radius for the transit feeder test (defaults to radius_m).

None
See Also

features_within : The buffer join behind it. enrich_with_osm : Add OSM amenity counts. link_transit_stops : Add transit access.

Source code in src/gbfs_toolkit/spatial/osm.py
def station_surroundings(
    info: pd.DataFrame,
    *,
    transit: pd.DataFrame | None = None,
    osm: Any = None,
    radius_m: float = 300.0,
    transit_radius_m: float | None = None,
    osm_category_col: str | None = None,
) -> pd.DataFrame:
    """**One-shot "what's around each station"**: transit feeders + OSM features in a radius.

    Combines [`link_transit_stops`][gbfs_toolkit.link_transit_stops] and [`enrich_with_osm`][gbfs_toolkit.enrich_with_osm] /
    [`features_within`][gbfs_toolkit.features_within] into a single context frame.

    Parameters
    ----------
    info : pandas.DataFrame
        Canonical station inventory.
    transit : pandas.DataFrame, optional
        GTFS ``stops``-style frame; adds ``nearest_stop_dist_m``, ``n_transit_within``,
        ``is_transit_feeder``.
    osm : geopandas.GeoDataFrame or pandas.DataFrame, optional
        OSM features (GeoDataFrame → geometry reduced automatically) or a plain lat/lon
        frame; adds ``osm_within`` + per-category counts.
    radius_m : float, default 300
        Radius for OSM features (and transit if ``transit_radius_m`` is not set).
    transit_radius_m : float, optional
        Separate radius for the transit feeder test (defaults to ``radius_m``).

    See Also
    --------
    [`features_within`][gbfs_toolkit.features_within] : The buffer join behind it.
    [`enrich_with_osm`][gbfs_toolkit.enrich_with_osm] : Add OSM amenity counts.
    [`link_transit_stops`][gbfs_toolkit.link_transit_stops] : Add transit access.
    """
    out = info.reset_index(drop=True).copy()
    if transit is not None:
        linked = link_transit_stops(out, transit, radius_m=transit_radius_m or radius_m)
        new = [c for c in linked.columns if c not in out.columns]
        out = pd.concat([out, linked[new]], axis=1)
    if osm is not None:
        if hasattr(osm, "geometry"):  # a GeoDataFrame
            enr = enrich_with_osm(out, osm, radius_m=radius_m, category_col=osm_category_col)
        else:  # already a lat/lon points frame
            enr = features_within(
                out, osm, radius_m=radius_m, category_col=osm_category_col, prefix="osm_"
            )
        new = [c for c in enr.columns if c not in out.columns]
        out = pd.concat([out, enr[new]], axis=1)
    return out