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