Assign a human-readable behavioural type to each station from its 24-h profile.
Interprets the occupancy curve (columns h00 … h23) into named types, far more useful
than integer cluster ids:
morning_origin: empties in the morning (commuters depart): a residential origin.
morning_destination: fills in the morning (commuters arrive): a job/transit hub.
evening_origin: empties in the evening.
recreational: midday/afternoon peak.
mostly_empty / mostly_full: chronically saturated either way.
stable: little diurnal variation.
Parameters:
| Name |
Type |
Description |
Default |
profiles
|
DataFrame
|
|
required
|
amplitude
|
float
|
Minimum morning/evening swing (fraction of capacity) to call a directional type.
|
0.15
|
Returns:
| Type |
Description |
Series
|
Categorical typology, aligned to profiles rows.
|
See Also
cluster_diurnal_profiles : The clustering this labels.
diurnal_profiles : The profiles being interpreted.
Examples:
A station that empties during the morning commute is a residential origin:
>>> import pandas as pd
>>> profile = {f"h{h:02d}": (0.1 if 7 <= h <= 10 else 0.8) for h in range(24)}
>>> profiles = pd.DataFrame([profile], index=["a"])
>>> label_diurnal_typology(profiles).iloc[0]
'morning_origin'
Source code in src/gbfs_toolkit/analytics/clustering.py
| def label_diurnal_typology(profiles: pd.DataFrame, *, amplitude: float = 0.15) -> pd.Series:
"""Assign a **human-readable behavioural type** to each station from its 24-h profile.
Interprets the occupancy curve (columns ``h00 … h23``) into named types, far more useful
than integer cluster ids:
* ``morning_origin``: empties in the morning (commuters depart): a residential origin.
* ``morning_destination``: fills in the morning (commuters arrive): a job/transit hub.
* ``evening_origin``: empties in the evening.
* ``recreational``: midday/afternoon peak.
* ``mostly_empty`` / ``mostly_full``: chronically saturated either way.
* ``stable``: little diurnal variation.
Parameters
----------
profiles : pandas.DataFrame
Output of [`cluster_diurnal_profiles`][gbfs_toolkit.cluster_diurnal_profiles] / [`diurnal_profiles`][gbfs_toolkit.diurnal_profiles] with ``h00..h23``.
amplitude : float, default 0.15
Minimum morning/evening swing (fraction of capacity) to call a directional type.
Returns
-------
pandas.Series
Categorical typology, aligned to ``profiles`` rows.
See Also
--------
[`cluster_diurnal_profiles`][gbfs_toolkit.cluster_diurnal_profiles] : The clustering this labels.
[`diurnal_profiles`][gbfs_toolkit.diurnal_profiles] : The profiles being interpreted.
Examples
--------
A station that empties during the morning commute is a residential origin:
>>> import pandas as pd
>>> profile = {f"h{h:02d}": (0.1 if 7 <= h <= 10 else 0.8) for h in range(24)}
>>> profiles = pd.DataFrame([profile], index=["a"])
>>> label_diurnal_typology(profiles).iloc[0]
'morning_origin'
"""
hours = [f"h{h:02d}" for h in range(24)]
missing = [h for h in hours if h not in profiles.columns]
if missing:
raise KeyError(f"label_diurnal_typology needs 24-hour columns; missing {missing[:3]}…")
p = profiles[hours].to_numpy(dtype="float64")
night = p[:, list(range(0, 5))].mean(axis=1)
morning = p[:, list(range(7, 11))].mean(axis=1)
midday = p[:, list(range(11, 16))].mean(axis=1)
evening = p[:, list(range(17, 21))].mean(axis=1)
mean_occ = p.mean(axis=1)
morning_delta = morning - night
evening_delta = evening - midday
out = np.full(p.shape[0], "stable", dtype=object)
for i in range(p.shape[0]):
if mean_occ[i] < 0.1:
out[i] = "mostly_empty"
elif mean_occ[i] > 0.9:
out[i] = "mostly_full"
elif morning_delta[i] <= -amplitude:
out[i] = "morning_origin"
elif morning_delta[i] >= amplitude:
out[i] = "morning_destination"
elif evening_delta[i] <= -amplitude:
out[i] = "evening_origin"
elif midday[i] - (night[i] + evening[i]) / 2 >= amplitude:
out[i] = "recreational"
return pd.Series(
pd.Categorical(out, categories=list(DIURNAL_TYPOLOGIES)),
index=profiles.index,
name="typology",
)
|