Skip to content

availability_synchrony

availability_synchrony

availability_synchrony(panel: DataFrame, *, value_col: str = 'num_bikes_available', freq: str = '1h', method: str = 'pearson', min_overlap: int = 24, threshold: float | None = None) -> DataFrame

Pairwise correlation of station availability series: a functional synchrony network.

Resamples each station to freq and correlates every pair over their common support (requiring min_overlap shared observations), returning the upper-triangle edge list. This is the descriptive adjacency that precedes community detection of co-fluctuating stations. It correlates observed availability only; it infers no trips and no direction (no OD). Bring your own graph library (NetworkX, igraph) for the network analysis itself.

Parameters:

Name Type Description Default
panel DataFrame

From build_availability_panel or a flat frame with station_id, fetched_at and value_col.

required
freq str

Resampling bin for the per-station series.

"1h"
method ('pearson', 'spearman', 'kendall')

Correlation method.

"pearson"
min_overlap int

Minimum shared observations for a pair to be reported.

24
threshold float

If given, keep only edges with abs(corr) >= threshold.

None

Returns:

Type Description
DataFrame

station_a, station_b, corr, n_overlap (upper triangle, unmatched pairs dropped).

References

O'Brien, Cheshire and Batty (2014); the functional-connectivity correlation-network idiom.

See Also

temporal_autocorrelation : Per-station rhythm regularity.

Examples:

>>> import pandas as pd
>>> idx = pd.date_range("2026-01-01", periods=3, freq="1h", tz="UTC")
>>> panel = pd.DataFrame({
...     "station_id": ["a"] * 3 + ["b"] * 3,
...     "fetched_at": list(idx) * 2,
...     "num_bikes_available": [1, 2, 3, 2, 4, 6],
... })
>>> round(float(availability_synchrony(panel, min_overlap=3)["corr"].iloc[0]), 1)
1.0
Source code in src/gbfs_toolkit/analytics/temporal.py
def availability_synchrony(
    panel: pd.DataFrame,
    *,
    value_col: str = "num_bikes_available",
    freq: str = "1h",
    method: str = "pearson",
    min_overlap: int = 24,
    threshold: float | None = None,
) -> pd.DataFrame:
    """Pairwise correlation of station availability series: a functional synchrony network.

    Resamples each station to ``freq`` and correlates every pair over their common support
    (requiring ``min_overlap`` shared observations), returning the upper-triangle **edge list**.
    This is the descriptive adjacency that precedes community detection of co-fluctuating stations.
    It correlates observed availability only; it infers no trips and no direction (no OD). Bring
    your own graph library (NetworkX, igraph) for the network analysis itself.

    Parameters
    ----------
    panel : pandas.DataFrame
        From [`build_availability_panel`][gbfs_toolkit.build_availability_panel] or a flat frame with ``station_id, fetched_at`` and
        ``value_col``.
    freq : str, default "1h"
        Resampling bin for the per-station series.
    method : {"pearson", "spearman", "kendall"}, default "pearson"
        Correlation method.
    min_overlap : int, default 24
        Minimum shared observations for a pair to be reported.
    threshold : float, optional
        If given, keep only edges with ``abs(corr) >= threshold``.

    Returns
    -------
    pandas.DataFrame
        ``station_a, station_b, corr, n_overlap`` (upper triangle, unmatched pairs dropped).

    References
    ----------
    O'Brien, Cheshire and Batty (2014); the functional-connectivity correlation-network idiom.

    See Also
    --------
    [`temporal_autocorrelation`][gbfs_toolkit.temporal_autocorrelation] : Per-station rhythm regularity.

    Examples
    --------
    >>> import pandas as pd
    >>> idx = pd.date_range("2026-01-01", periods=3, freq="1h", tz="UTC")
    >>> panel = pd.DataFrame({
    ...     "station_id": ["a"] * 3 + ["b"] * 3,
    ...     "fetched_at": list(idx) * 2,
    ...     "num_bikes_available": [1, 2, 3, 2, 4, 6],
    ... })
    >>> round(float(availability_synchrony(panel, min_overlap=3)["corr"].iloc[0]), 1)
    1.0
    """
    df = panel_frame(panel)
    require_columns(df, ["station_id", "fetched_at", value_col], what="availability_synchrony")
    wide = pd.DataFrame(
        {
            "_t": pd.to_datetime(df["fetched_at"]).dt.floor(freq).to_numpy(),
            "station_id": df["station_id"].to_numpy(),
            "_v": pd.to_numeric(df[value_col], errors="coerce").to_numpy(),
        }
    )
    mat = wide.pivot_table(index="_t", columns="station_id", values="_v", aggfunc="mean")
    cols = mat.columns.to_numpy()
    if cols.size < 2:
        return pd.DataFrame(columns=["station_a", "station_b", "corr", "n_overlap"])
    corr = mat.corr(method=method, min_periods=min_overlap).to_numpy()
    present = mat.notna().astype("int64")
    n_overlap = present.T.to_numpy() @ present.to_numpy()
    ii, jj = np.triu_indices(cols.size, k=1)
    edges = pd.DataFrame(
        {
            "station_a": cols[ii],
            "station_b": cols[jj],
            "corr": corr[ii, jj],
            "n_overlap": n_overlap[ii, jj],
        }
    ).dropna(subset=["corr"])
    if threshold is not None:
        edges = edges[edges["corr"].abs() >= threshold]
    return edges.reset_index(drop=True)