Skip to content

cluster_diurnal_profiles

cluster_diurnal_profiles

cluster_diurnal_profiles(panel: DataFrame, *, n_clusters: int | str = 'auto', method: str = 'kmeans', normalize: str = 'none', split_weekday: bool = False, min_obs: int = 12, k_range: tuple[int, int] = (2, 8), time_col: str = 'fetched_at', random_state: int = 0) -> DataFrame

Cluster stations by their daily rhythm (the crown jewel of the longitudinal layer).

Builds each station's occupancy-by-hour profile, then clusters into typologies (commuter origin, recreational, always-full, …).

Parameters:

Name Type Description Default
panel DataFrame

A panel from build_availability_panel (or a flat frame with system_id, station_id, num_bikes_available + a timestamp). Pass a local-time panel (GBFSFeed.to_local_time) for local diurnal phase; else hours are UTC.

required
n_clusters int or 'auto'

Fixed k, or "auto" to pick the best k by silhouette over k_range.

"auto"
method ('kmeans', 'gmm', 'dtw')

gmm = soft Gaussian-mixture (adds a cluster_confidence column); dtw = shape-aware time-series k-means (needs tslearn).

"kmeans"
normalize ('none', 'zscore')

zscore clusters by rhythm shape (per-station standardised), ignoring the average occupancy level, usually what you want for "commuter vs leisure".

"none"
split_weekday bool

Profile weekday and weekend separately (48-dim).

False
min_obs int

Minimum observations for a station to be profiled.

12

Returns:

Type Description
DataFrame

system_id, station_id, cluster, n_obs (+ cluster_confidence for gmm) and the profile columns.

See Also

diurnal_profiles : The profiles this clusters. label_diurnal_typology : Name the resulting clusters. cluster_spatial : Cluster by location instead of rhythm.

Examples:

Two low-occupancy and two high-occupancy stations split into two typologies:

>>> import pandas as pd
>>> idx = pd.date_range("2026-01-01", periods=24, freq="1h", tz="UTC")
>>> rows = []
>>> for sid, bikes in [("a", 2), ("b", 2), ("c", 8), ("d", 8)]:
...     for t in idx:
...         rows.append({"system_id": "s", "station_id": sid, "fetched_at": t,
...                      "num_bikes_available": bikes, "num_docks_available": 10 - bikes})
>>> panel = pd.DataFrame(rows)
>>> int(cluster_diurnal_profiles(panel, n_clusters=2, min_obs=12)["cluster"].nunique())
2
Source code in src/gbfs_toolkit/analytics/clustering.py
def cluster_diurnal_profiles(
    panel: pd.DataFrame,
    *,
    n_clusters: int | str = "auto",
    method: str = "kmeans",
    normalize: str = "none",
    split_weekday: bool = False,
    min_obs: int = 12,
    k_range: tuple[int, int] = (2, 8),
    time_col: str = "fetched_at",
    random_state: int = 0,
) -> pd.DataFrame:
    """Cluster stations by their **daily rhythm** (the crown jewel of the longitudinal layer).

    Builds each station's occupancy-by-hour profile, then clusters into typologies
    (commuter origin, recreational, always-full, …).

    Parameters
    ----------
    panel : pandas.DataFrame
        A panel from [`build_availability_panel`][gbfs_toolkit.build_availability_panel] (or a flat frame with
        ``system_id, station_id, num_bikes_available`` + a timestamp). Pass a *local-time*
        panel (``GBFSFeed.to_local_time``) for local diurnal phase; else hours are UTC.
    n_clusters : int or "auto", default "auto"
        Fixed k, or ``"auto"`` to pick the best k by silhouette over ``k_range``.
    method : {"kmeans", "gmm", "dtw"}, default "kmeans"
        ``gmm`` = soft Gaussian-mixture (adds a ``cluster_confidence`` column);
        ``dtw`` = shape-aware time-series k-means (needs ``tslearn``).
    normalize : {"none", "zscore"}, default "none"
        ``zscore`` clusters by rhythm *shape* (per-station standardised), ignoring the
        average occupancy level, usually what you want for "commuter vs leisure".
    split_weekday : bool, default False
        Profile weekday and weekend separately (48-dim).
    min_obs : int, default 12
        Minimum observations for a station to be profiled.

    Returns
    -------
    pandas.DataFrame
        ``system_id, station_id, cluster, n_obs`` (+ ``cluster_confidence`` for gmm) and the
        profile columns.

    See Also
    --------
    [`diurnal_profiles`][gbfs_toolkit.diurnal_profiles] : The profiles this clusters.
    [`label_diurnal_typology`][gbfs_toolkit.label_diurnal_typology] : Name the resulting clusters.
    [`cluster_spatial`][gbfs_toolkit.cluster_spatial] : Cluster by location instead of rhythm.

    Examples
    --------
    Two low-occupancy and two high-occupancy stations split into two typologies:

    >>> import pandas as pd
    >>> idx = pd.date_range("2026-01-01", periods=24, freq="1h", tz="UTC")
    >>> rows = []
    >>> for sid, bikes in [("a", 2), ("b", 2), ("c", 8), ("d", 8)]:
    ...     for t in idx:
    ...         rows.append({"system_id": "s", "station_id": sid, "fetched_at": t,
    ...                      "num_bikes_available": bikes, "num_docks_available": 10 - bikes})
    >>> panel = pd.DataFrame(rows)
    >>> int(cluster_diurnal_profiles(panel, n_clusters=2, min_obs=12)["cluster"].nunique())
    2
    """
    _require_sklearn()

    prof, n_obs = diurnal_profiles(
        panel, time_col=time_col, split_weekday=split_weekday, min_obs=min_obs
    )
    cols = list(prof.columns)
    if prof.empty:
        return pd.DataFrame(columns=["system_id", "station_id", "cluster", "n_obs", *cols])

    x = prof.to_numpy(dtype="float64")
    if normalize == "zscore":  # cluster by shape, not level
        mu = x.mean(axis=1, keepdims=True)
        sd = x.std(axis=1, keepdims=True)
        x = (x - mu) / np.where(sd > 0, sd, 1.0)

    k = (
        _select_k(x, k_range, random_state)
        if n_clusters == "auto"
        else min(int(n_clusters), len(x))
    )

    confidence = None
    if method == "kmeans":
        from sklearn.cluster import KMeans

        labels = KMeans(n_clusters=k, n_init=10, random_state=random_state).fit_predict(x)
    elif method == "gmm":
        from sklearn.mixture import GaussianMixture

        gmm = GaussianMixture(n_components=k, random_state=random_state).fit(x)
        labels = gmm.predict(x)
        confidence = gmm.predict_proba(x).max(axis=1)
    elif method == "dtw":
        try:
            from tslearn.clustering import TimeSeriesKMeans
        except ImportError as e:  # pragma: no cover
            raise ImportError("method='dtw' requires tslearn (`pip install tslearn`).") from e
        labels = TimeSeriesKMeans(
            n_clusters=k, metric="dtw", random_state=random_state
        ).fit_predict(x.reshape(x.shape[0], x.shape[1], 1))
    else:
        raise ValueError(f"unknown method {method!r}; use 'kmeans', 'gmm' or 'dtw'")

    out = prof.copy()
    out["cluster"] = np.asarray(labels).astype("int64")
    if confidence is not None:
        out["cluster_confidence"] = confidence
    out = out.reset_index()
    out["n_obs"] = out.set_index(["system_id", "station_id"]).index.map(n_obs).to_numpy()
    front = ["system_id", "station_id", "cluster", "n_obs"]
    if confidence is not None:
        front.append("cluster_confidence")
    return out[front + [c for c in out.columns if c not in front]]