Skip to content

link_transit_stops

link_transit_stops(info: DataFrame, stops: DataFrame, *, radius_m: float = 200.0) -> DataFrame

Attach transit-proximity metrics to each station.

Parameters:

Name Type Description Default
info DataFrame

Canonical station inventory (needs lat, lon).

required
stops DataFrame

Transit stops (GTFS stops.txt style): a stop_id and lat/lon columns (stop_lat/stop_lon or common aliases).

required
radius_m float

First/last-mile threshold: a station is a feeder if a stop is within this distance.

200

Returns:

Type Description
DataFrame

info plus nearest_stop_id, nearest_stop_dist_m, n_transit_within (stops within radius_m) and is_transit_feeder (bool).

See Also

station_surroundings : Generic buffer summary. two_step_fca : Turn transit access into accessibility.

Source code in src/gbfs_toolkit/spatial/multimodal.py
def link_transit_stops(
    info: pd.DataFrame,
    stops: pd.DataFrame,
    *,
    radius_m: float = 200.0,
) -> pd.DataFrame:
    """Attach transit-proximity metrics to each station.

    Parameters
    ----------
    info : pandas.DataFrame
        Canonical station inventory (needs ``lat``, ``lon``).
    stops : pandas.DataFrame
        Transit stops (GTFS ``stops.txt`` style): a ``stop_id`` and lat/lon columns
        (``stop_lat``/``stop_lon`` or common aliases).
    radius_m : float, default 200
        First/last-mile threshold: a station is a *feeder* if a stop is within this distance.

    Returns
    -------
    pandas.DataFrame
        ``info`` plus ``nearest_stop_id``, ``nearest_stop_dist_m``,
        ``n_transit_within`` (stops within ``radius_m``) and ``is_transit_feeder`` (bool).

    See Also
    --------
    [`station_surroundings`][gbfs_toolkit.station_surroundings] : Generic buffer summary.
    [`two_step_fca`][gbfs_toolkit.two_step_fca] : Turn transit access into accessibility.
    """
    require_columns(info, ["lat", "lon"], what="link_transit_stops(info)")
    out = info.reset_index(drop=True).copy()
    if out.empty:
        out["nearest_stop_id"] = pd.Series(dtype="object")
        out["nearest_stop_dist_m"] = pd.Series(dtype="float64")
        out["n_transit_within"] = pd.Series(dtype="int64")
        out["is_transit_feeder"] = pd.Series(dtype="bool")
        return out
    if stops.empty:
        out["nearest_stop_id"] = None
        out["nearest_stop_dist_m"] = np.inf
        out["n_transit_within"] = 0
        out["is_transit_feeder"] = False
        return out

    lat_c = _pick(stops, _LAT_ALIASES, "latitude")
    lon_c = _pick(stops, _LON_ALIASES, "longitude")
    id_c = next((a for a in _ID_ALIASES if a in stops.columns), None)
    stop_ids = stops[id_c].to_numpy() if id_c else np.arange(len(stops))

    tree = GeoKDTree(stops[lat_c], stops[lon_c])
    dist, idx = tree.query(out["lat"].to_numpy(), out["lon"].to_numpy(), k=1)
    dist, idx = np.asarray(dist).ravel(), np.asarray(idx).ravel()
    within = tree.query_radius(out["lat"].to_numpy(), out["lon"].to_numpy(), radius_m=radius_m)

    out["nearest_stop_id"] = stop_ids[idx]
    out["nearest_stop_dist_m"] = dist
    out["n_transit_within"] = [len(h) for h in within]
    out["is_transit_feeder"] = out["nearest_stop_dist_m"] <= radius_m
    return out