Skip to content

system_profile

system_profile

system_profile(availability: DataFrame) -> Series

A one-glance numeric profile of one availability snapshot: the bikeshare describe().

Parameters:

Name Type Description Default
availability DataFrame

An availability frame (e.g. from join_availability): needs num_bikes_available / num_docks_available; uses capacity, station_type, is_virtual_station, is_renting / is_returning, fetched_at / last_reported when present.

required

Returns:

Type Description
Series

Counts and rates: n_stations, total_capacity, total_bikes_available, total_docks_available, mean_occupancy, pct_<state> for each STATION_STATES, and staleness_min_median.

See Also

compare_systems : Stack this profile across many systems. concentration_metrics : Inequality of capacity behind the profile.

Examples:

>>> import pandas as pd
>>> av = pd.DataFrame({
...     "system_id": "s", "station_id": ["a", "b"], "capacity": [20, 20],
...     "num_bikes_available": [5, 15], "num_docks_available": [15, 5],
... })
>>> int(system_profile(av)["n_stations"])
2
Source code in src/gbfs_toolkit/analytics/distribution.py
def system_profile(availability: pd.DataFrame) -> pd.Series:
    """A one-glance numeric profile of one availability snapshot: the bikeshare ``describe()``.

    Parameters
    ----------
    availability : pandas.DataFrame
        An availability frame (e.g. from [`join_availability`][gbfs_toolkit.join_availability]): needs
        ``num_bikes_available`` / ``num_docks_available``; uses ``capacity``, ``station_type``,
        ``is_virtual_station``, ``is_renting`` / ``is_returning``, ``fetched_at`` /
        ``last_reported`` when present.

    Returns
    -------
    pandas.Series
        Counts and rates: ``n_stations``, ``total_capacity``, ``total_bikes_available``,
        ``total_docks_available``, ``mean_occupancy``, ``pct_<state>`` for each
        `STATION_STATES`, and ``staleness_min_median``.

    See Also
    --------
    [`compare_systems`][gbfs_toolkit.compare_systems] : Stack this profile across many systems.
    [`concentration_metrics`][gbfs_toolkit.concentration_metrics] : Inequality of capacity behind the profile.

    Examples
    --------
    >>> import pandas as pd
    >>> av = pd.DataFrame({
    ...     "system_id": "s", "station_id": ["a", "b"], "capacity": [20, 20],
    ...     "num_bikes_available": [5, 15], "num_docks_available": [15, 5],
    ... })
    >>> int(system_profile(av)["n_stations"])
    2
    """
    # Intentionally lenient: a profile/describe should work on any frame, so missing
    # count columns are read as empty (via num()) rather than rejected.
    df = availability
    bikes, docks = num(df, "num_bikes_available"), num(df, "num_docks_available")
    out: dict[str, float] = {"n_stations": int(len(df))}
    if "capacity" in df.columns:
        out["total_capacity"] = float(num(df, "capacity").sum())
    out["total_bikes_available"] = float(bikes.sum())
    out["total_docks_available"] = float(docks.sum())

    denom = bikes + docks
    occ = (bikes / denom).where(denom > 0)
    out["mean_occupancy"] = round(float(occ.mean()), 4) if occ.notna().any() else float("nan")

    if len(df):
        states = station_state(df).value_counts(normalize=True)
        for s in STATION_STATES:
            out[f"pct_{s}"] = round(float(states.get(s, 0.0)), 4)

    if "fetched_at" in df.columns and "last_reported" in df.columns:
        lag = (
            pd.to_datetime(df["fetched_at"], utc=True)
            - pd.to_datetime(df["last_reported"], utc=True)
        ).dt.total_seconds() / 60
        if lag.notna().any():
            out["staleness_min_median"] = round(float(lag.median()), 1)
    return pd.Series(out)