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})
|