Skip to content

coverage_stats

coverage_stats

coverage_stats(info: DataFrame, *, zones: object = None) -> Series

Spatial coverage of a station network: density and dispersion.

Reports nearest-neighbour spacing and station density. The density denominator is the convex hull of the stations by default, or (far more accurate for free-floating / hybrid systems) the real service area if you pass the operator's geofencing zones (a GeoDataFrame from to_canonical_geofencing; needs the [geo] extra). Also reports the Clark–Evans index (observed mean NN distance ÷ the value expected under spatial randomness: <1 clustered, ≈1 random, >1 dispersed).

Returns:

Type Description
Series

n_stations, mean_nearest_neighbor_m, median_nearest_neighbor_m, hull_area_km2 or service_area_km2, stations_per_km2, clark_evans_index.

See Also

two_step_fca : Demand-weighted accessibility. zone_area_km2 : Area of a service polygon. spatial_center_of_mass : Centre of the served area.

Source code in src/gbfs_toolkit/spatial/analytics.py
def coverage_stats(info: pd.DataFrame, *, zones: object = None) -> pd.Series:
    """Spatial coverage of a station network: density and dispersion.

    Reports nearest-neighbour spacing and station density. The density denominator is the
    convex hull of the stations by default, or (far more accurate for free-floating / hybrid
    systems) the **real service area** if you pass the operator's geofencing ``zones``
    (a GeoDataFrame from [`to_canonical_geofencing`][gbfs_toolkit.to_canonical_geofencing]; needs the ``[geo]``
    extra). Also reports the **Clark–Evans index** (observed mean NN distance ÷ the value
    expected under spatial randomness: ``<1`` clustered, ``≈1`` random, ``>1`` dispersed).

    Returns
    -------
    pandas.Series
        ``n_stations``, ``mean_nearest_neighbor_m``, ``median_nearest_neighbor_m``,
        ``hull_area_km2`` *or* ``service_area_km2``, ``stations_per_km2``, ``clark_evans_index``.

    See Also
    --------
    [`two_step_fca`][gbfs_toolkit.two_step_fca] : Demand-weighted accessibility.
    [`zone_area_km2`][gbfs_toolkit.zone_area_km2] : Area of a service polygon.
    [`spatial_center_of_mass`][gbfs_toolkit.spatial_center_of_mass] : Centre of the served area.
    """
    require_columns(info, ["lat", "lon"], what="coverage_stats")
    lat, lon = num(info, "lat").to_numpy(), num(info, "lon").to_numpy()
    finite = np.isfinite(lat) & np.isfinite(lon)
    lat, lon = lat[finite], lon[finite]
    out: dict[str, float] = {"n_stations": int(lat.size)}
    if lat.size == 0:
        return pd.Series(out)

    if lat.size >= 2:
        dist, _ = GeoKDTree(lat, lon).query(lat, lon, k=2)
        nn = np.asarray(dist)[:, 1]
        out["mean_nearest_neighbor_m"] = round(float(nn.mean()), 1)
        out["median_nearest_neighbor_m"] = round(float(np.median(nn)), 1)

    area_km2: float | None = None
    if zones is not None:
        from gbfs_toolkit.spatial.geofencing import zone_area_km2

        area_km2 = float(zone_area_km2(zones).sum())
        out["service_area_km2"] = round(area_km2, 3)
    elif lat.size >= 3:
        area_km2 = _hull_area_km2(lat, lon)
        out["hull_area_km2"] = round(area_km2, 3)

    if area_km2 and area_km2 > 0 and np.isfinite(area_km2):
        out["stations_per_km2"] = round(lat.size / area_km2, 3)
        if "mean_nearest_neighbor_m" in out:
            density_m2 = lat.size / (area_km2 * 1e6)
            expected_nn = 1.0 / (2.0 * np.sqrt(density_m2))
            out["clark_evans_index"] = round(out["mean_nearest_neighbor_m"] / expected_nn, 3)
    return pd.Series(out)