Skip to content

spatial_center_of_mass

spatial_center_of_mass

spatial_center_of_mass(panel: DataFrame, *, freq: str = '1h', weight_col: str = 'num_bikes_available', time_col: str = 'fetched_at') -> DataFrame

Fleet centre of gravity over time: the weighted-mean station coordinate per period.

Summarises the whole network's spatial dynamics as one moving point. In hilly or monocentric cities the centre of mass drifts downhill or toward the centre over the day, which is the signature of the pendular migration that forces heavy evening rebalancing.

Parameters:

Name Type Description Default
panel DataFrame

A panel joined with station coordinates: needs lat, lon, time_col and weight_col.

required
freq str

Aggregation bin (a pandas offset alias).

"1h"
weight_col str

Weight for the mean (e.g. available bikes).

"num_bikes_available"

Returns:

Type Description
DataFrame

period, center_lat, center_lon, total_weight.

See Also

spatial_entropy : Spread around this centre. coverage_stats : Areal coverage of the network.

Source code in src/gbfs_toolkit/spatial/analytics.py
def spatial_center_of_mass(
    panel: pd.DataFrame,
    *,
    freq: str = "1h",
    weight_col: str = "num_bikes_available",
    time_col: str = "fetched_at",
) -> pd.DataFrame:
    """Fleet centre of gravity over time: the weighted-mean station coordinate per period.

    Summarises the whole network's spatial dynamics as one moving point. In hilly or monocentric
    cities the centre of mass drifts downhill or toward the centre over the day, which is the
    signature of the pendular migration that forces heavy evening rebalancing.

    Parameters
    ----------
    panel : pandas.DataFrame
        A panel joined with station coordinates: needs ``lat, lon, time_col`` and ``weight_col``.
    freq : str, default "1h"
        Aggregation bin (a pandas offset alias).
    weight_col : str, default "num_bikes_available"
        Weight for the mean (e.g. available bikes).

    Returns
    -------
    pandas.DataFrame
        ``period, center_lat, center_lon, total_weight``.

    See Also
    --------
    [`spatial_entropy`][gbfs_toolkit.spatial_entropy] : Spread around this centre.
    [`coverage_stats`][gbfs_toolkit.coverage_stats] : Areal coverage of the network.
    """
    df = panel_frame(panel)
    require_columns(df, ["lat", "lon", time_col, weight_col], what="spatial_center_of_mass")
    w = pd.to_numeric(df[weight_col], errors="coerce").fillna(0.0).to_numpy()
    lat = pd.to_numeric(df["lat"], errors="coerce").to_numpy()
    lon = pd.to_numeric(df["lon"], errors="coerce").to_numpy()
    period = pd.to_datetime(df[time_col]).dt.floor(freq)
    work = pd.DataFrame({"period": period.to_numpy(), "_wlat": w * lat, "_wlon": w * lon, "_w": w})
    agg = work.groupby("period").sum()
    out = pd.DataFrame(
        {
            "period": agg.index,
            "center_lat": agg["_wlat"] / agg["_w"].where(agg["_w"] > 0),
            "center_lon": agg["_wlon"] / agg["_w"].where(agg["_w"] > 0),
            "total_weight": agg["_w"].to_numpy(),
        }
    ).reset_index(drop=True)
    return out