rebalancing_tension¶
rebalancing_tension
¶
rebalancing_tension(panel: DataFrame, *, time_col: str = 'fetched_at', value_col: str = 'num_bikes_available', target: object = 'historical_mean') -> Series
Minimum-work spatial rebalancing tension per timestamp, in bike-kilometres.
At each timestamp, the Wasserstein-1 (earth-mover) distance between the spatial distribution of available bikes and a target distribution, scaled by the fleet size: the minimal bikes x kilometres of relocation that would bring the system to its target. A single scalar of instantaneous spatial fragmentation, purely descriptive: no trip, OD or movement is inferred, only the optimal-transport lower bound on the work an operator would need.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
panel
|
DataFrame
|
Availability panel with |
required |
time_col
|
str
|
Timestamp and the per-station available-bike column. |
'fetched_at'
|
value_col
|
str
|
Timestamp and the per-station available-bike column. |
'fetched_at'
|
target
|
'historical_mean' or Series
|
Reference state. |
'historical_mean'
|
Returns:
| Type | Description |
|---|---|
Series
|
Tension in bike-kilometres indexed by timestamp ( |
References
Rubner, Tomasi & Guibas (2000). The Earth Mover's Distance. IJCV, 40(2).
See Also
cumulative_imbalance : Per-station drift behind the tension.
flow_asymmetry_ratio : Structural source/sink roles.
calculate_net_flow : The observed flow this builds on.
Examples:
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "station_id": ["a", "b"], "lat": [48.85, 48.95], "lon": [2.35, 2.35],
... "fetched_at": pd.Timestamp("2026-01-01T08:00Z"),
... "num_bikes_available": [10, 0],
... })
>>> tension = rebalancing_tension(panel, target=pd.Series({"a": 5, "b": 5}))
>>> float(tension.iloc[0]) > 0
True