Skip to content

ripley_k

ripley_k

ripley_k(info: DataFrame, radii: object, *, area_km2: float | None = None) -> DataFrame

Ripley's K / L: multi-scale clustering of station locations.

For each radius, K(r) is proportional to the mean number of other stations within r; L(r) = sqrt(K(r)/π) − r linearises it: L(r) > 0 ⇒ clustering at scale r, < 0 ⇒ dispersion. Density uses the convex hull by default, or area_km2 (e.g. the geofencing service area) if given.

.. warning:: No edge correction. This estimator has no isotropic/translation boundary correction, so it is biased downward at radii approaching the study-area size and is unreliable for irregular real-world boundaries (coastlines, rivers, city limits). Use it for relative comparison at small radii, and prefer the boundary-robust Clark–Evans index in coverage_stats for an overall dispersion verdict.

Parameters:

Name Type Description Default
radii array - like

Distances in metres at which to evaluate K/L.

required

Returns:

Type Description
DataFrame

radius_m, k, l (one row per radius).

See Also

morans_i : Single-scale spatial autocorrelation. spatial_entropy : Concentration of the point pattern.

Source code in src/gbfs_toolkit/spatial/analytics.py
def ripley_k(info: pd.DataFrame, radii: object, *, area_km2: float | None = None) -> pd.DataFrame:
    """**Ripley's K / L**: multi-scale clustering of station locations.

    For each radius, ``K(r)`` is proportional to the mean number of other stations within
    ``r``; ``L(r) = sqrt(K(r)/π) − r`` linearises it: ``L(r) > 0`` ⇒ clustering at scale ``r``,
    ``< 0`` ⇒ dispersion. Density uses the convex hull by default, or ``area_km2`` (e.g. the
    geofencing service area) if given.

    .. warning::
       **No edge correction.** This estimator has no isotropic/translation boundary correction,
       so it is biased downward at radii approaching the study-area size and is unreliable for
       irregular real-world boundaries (coastlines, rivers, city limits). Use it for *relative*
       comparison at small radii, and prefer the boundary-robust Clark–Evans index in
       [`coverage_stats`][gbfs_toolkit.coverage_stats] for an overall dispersion verdict.

    Parameters
    ----------
    radii : array-like
        Distances in metres at which to evaluate K/L.

    Returns
    -------
    pandas.DataFrame
        ``radius_m``, ``k``, ``l`` (one row per radius).

    See Also
    --------
    [`morans_i`][gbfs_toolkit.morans_i] : Single-scale spatial autocorrelation.
    [`spatial_entropy`][gbfs_toolkit.spatial_entropy] : Concentration of the point pattern.
    """
    require_columns(info, ["lat", "lon"], what="ripley_k")
    lat, lon = num(info, "lat").to_numpy(), num(info, "lon").to_numpy()
    finite = np.isfinite(lat) & np.isfinite(lon)
    lat, lon = lat[finite], lon[finite]
    radii = np.asarray(radii, dtype="float64")
    n = lat.size
    if n < 2:
        return pd.DataFrame({"radius_m": radii, "k": np.nan, "l": np.nan})

    area_m2 = (area_km2 * 1e6) if area_km2 is not None else _hull_area_km2(lat, lon) * 1e6

    tree = GeoKDTree(lat, lon)
    ks = []
    for r in radii:
        hits = tree.query_radius(lat, lon, radius_m=float(r))
        pairs = sum(len(h) - 1 for h in hits)  # exclude self
        ks.append(area_m2 * pairs / (n * (n - 1)) if np.isfinite(area_m2) else np.nan)
    k_arr = np.asarray(ks)
    l_arr = np.sqrt(k_arr / np.pi) - radii
    return pd.DataFrame({"radius_m": radii, "k": k_arr, "l": l_arr})