Skip to content

to_wide_matrix

to_wide_matrix

to_wide_matrix(panel: DataFrame, *, value_col: str = 'num_bikes_available', time_col: str = 'fetched_at', station_col: str = 'station_id') -> DataFrame

Pivot a long panel into a time-by-station matrix.

The "long/tidy" panel is right for storage but most external tools (scikit-learn, a correlation matrix, a heatmap) want the "wide" form: rows are timestamps, columns are stations, cells are value_col. pivot_table does this but leaves fiddly column-index names to clean up; this returns a flat, ready-to-use matrix.

Parameters:

Name Type Description Default
panel DataFrame

Long panel/frame with time_col, station_col and value_col.

required
value_col str

The cell value, the row key and the column key.

'num_bikes_available'
time_col str

The cell value, the row key and the column key.

'num_bikes_available'
station_col str

The cell value, the row key and the column key.

'num_bikes_available'

Returns:

Type Description
DataFrame

Indexed by time_col, one column per station (duplicates averaged).

See Also

extract_snapshot_asof : Take a single row of this matrix. resample_panel : Put the rows on a regular grid first.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "station_id": ["a", "b", "a", "b"],
...     "fetched_at": pd.to_datetime(
...         ["2026-01-01T08:00Z"] * 2 + ["2026-01-01T09:00Z"] * 2),
...     "num_bikes_available": [5, 2, 3, 8],
... })
>>> to_wide_matrix(panel).shape
(2, 2)
Source code in src/gbfs_toolkit/io/timeseries.py
def to_wide_matrix(
    panel: pd.DataFrame,
    *,
    value_col: str = "num_bikes_available",
    time_col: str = "fetched_at",
    station_col: str = "station_id",
) -> pd.DataFrame:
    """Pivot a long panel into a time-by-station matrix.

    The "long/tidy" panel is right for storage but most external tools (scikit-learn,
    a correlation matrix, a heatmap) want the "wide" form: rows are timestamps, columns
    are stations, cells are ``value_col``. ``pivot_table`` does this but leaves fiddly
    column-index names to clean up; this returns a flat, ready-to-use matrix.

    Parameters
    ----------
    panel : pandas.DataFrame
        Long panel/frame with ``time_col``, ``station_col`` and ``value_col``.
    value_col, time_col, station_col : str
        The cell value, the row key and the column key.

    Returns
    -------
    pandas.DataFrame
        Indexed by ``time_col``, one column per station (duplicates averaged).

    See Also
    --------
    [`extract_snapshot_asof`][gbfs_toolkit.extract_snapshot_asof] : Take a single row of this matrix.
    [`resample_panel`][gbfs_toolkit.resample_panel] : Put the rows on a regular grid first.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "station_id": ["a", "b", "a", "b"],
    ...     "fetched_at": pd.to_datetime(
    ...         ["2026-01-01T08:00Z"] * 2 + ["2026-01-01T09:00Z"] * 2),
    ...     "num_bikes_available": [5, 2, 3, 8],
    ... })
    >>> to_wide_matrix(panel).shape
    (2, 2)
    """
    df = panel_frame(panel)
    require_columns(df, [time_col, station_col, value_col], what="to_wide_matrix")
    wide = df.pivot_table(index=time_col, columns=station_col, values=value_col, aggfunc="mean")
    wide.columns.name = None
    return wide