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)