Skip to content

cluster_spatial

cluster_spatial

cluster_spatial(info: DataFrame, *, method: str = 'hdbscan', min_cluster_size: int = 3, eps_m: float = 300.0) -> DataFrame

Group stations into spatial zones by physical proximity.

Returns info with a cluster column (-1 = noise/unclustered).

Parameters:

Name Type Description Default
method ('hdbscan', 'dbscan')

HDBSCAN auto-selects density scales; DBSCAN uses a fixed eps_m radius.

"hdbscan"
min_cluster_size int

Minimum stations to form a zone.

3
eps_m float

Neighbourhood radius in metres (DBSCAN only).

300.0
See Also

cluster_spectral : Topological instead of proximity zones. cluster_diurnal_profiles : Behavioural instead of spatial clusters.

Examples:

Two tight groups ~11 km apart resolve into two DBSCAN clusters:

>>> import pandas as pd
>>> info = pd.DataFrame({
...     "station_id": list("abcdef"),
...     "lat": [48.85, 48.8501, 48.8502, 48.95, 48.9501, 48.9502],
...     "lon": [2.35, 2.3501, 2.3502, 2.45, 2.4501, 2.4502],
... })
>>> sorted(int(c) for c in cluster_spatial(info, method="dbscan", eps_m=100, min_cluster_size=3)["cluster"].unique())
[0, 1]
Source code in src/gbfs_toolkit/analytics/clustering.py
def cluster_spatial(
    info: pd.DataFrame,
    *,
    method: str = "hdbscan",
    min_cluster_size: int = 3,
    eps_m: float = 300.0,
) -> pd.DataFrame:
    """Group stations into spatial zones by physical proximity.

    Returns ``info`` with a ``cluster`` column (``-1`` = noise/unclustered).

    Parameters
    ----------
    method : {"hdbscan", "dbscan"}
        HDBSCAN auto-selects density scales; DBSCAN uses a fixed ``eps_m`` radius.
    min_cluster_size : int
        Minimum stations to form a zone.
    eps_m : float
        Neighbourhood radius in metres (DBSCAN only).

    See Also
    --------
    [`cluster_spectral`][gbfs_toolkit.cluster_spectral] : Topological instead of proximity zones.
    [`cluster_diurnal_profiles`][gbfs_toolkit.cluster_diurnal_profiles] : Behavioural instead of spatial clusters.

    Examples
    --------
    Two tight groups ~11 km apart resolve into two DBSCAN clusters:

    >>> import pandas as pd
    >>> info = pd.DataFrame({
    ...     "station_id": list("abcdef"),
    ...     "lat": [48.85, 48.8501, 48.8502, 48.95, 48.9501, 48.9502],
    ...     "lon": [2.35, 2.3501, 2.3502, 2.45, 2.4501, 2.4502],
    ... })
    >>> sorted(int(c) for c in cluster_spatial(info, method="dbscan", eps_m=100, min_cluster_size=3)["cluster"].unique())
    [0, 1]
    """
    _require_sklearn()
    out = info.reset_index(drop=True).copy()
    if out.empty:
        out["cluster"] = pd.Series(dtype="int64")
        return out
    xy = _project_xy(out["lat"], out["lon"])  # Euclidean-safe metres, not raw lat/lon
    if method == "hdbscan":
        from sklearn.cluster import HDBSCAN

        labels = HDBSCAN(min_cluster_size=min_cluster_size).fit_predict(xy)
    elif method == "dbscan":
        from sklearn.cluster import DBSCAN

        labels = DBSCAN(eps=eps_m, min_samples=min_cluster_size).fit_predict(xy)
    else:
        raise ValueError(f"unknown method {method!r}; use 'hdbscan' or 'dbscan'")
    out["cluster"] = labels.astype("int64")
    return out