Skip to content

label_diurnal_typology

label_diurnal_typology

label_diurnal_typology(profiles: DataFrame, *, amplitude: float = 0.15) -> 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:

Name Type Description Default
profiles DataFrame

Output of cluster_diurnal_profiles / diurnal_profiles with h00..h23.

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",
    )