Skip to content

add_local_time

add_local_time

add_local_time(panel: DataFrame, tz_name: str, *, time_col: str = 'fetched_at', new_col: str = 'local_time') -> DataFrame

Add a local-time column to a panel, handling the index correctly.

Converting a UTC timestamp to local time is the first step of any diurnal analysis, and doing it on a MultiIndexed panel by hand (reset_index then tz_convert then set_index) is a recurring papercut. This flattens the panel and appends one tz-aware new_col in tz_name, leaving time_col (UTC) untouched.

Parameters:

Name Type Description Default
panel DataFrame

Any panel/frame with a tz-aware (or UTC-coercible) time_col.

required
tz_name str

An IANA zone, e.g. "Europe/Paris" or "America/New_York".

required
time_col str

Source UTC column and the local-time column to add.

'fetched_at'
new_col str

Source UTC column and the local-time column to add.

'fetched_at'

Returns:

Type Description
DataFrame

A flattened copy of panel with the added new_col.

See Also

build_availability_panel : Build a panel already in local time via target_tz. resample_panel : Put the panel on a fixed time grid.

Examples:

>>> import pandas as pd
>>> df = pd.DataFrame({"fetched_at": pd.to_datetime(["2026-01-01T08:00Z"])})
>>> int(add_local_time(df, "Europe/Paris")["local_time"].dt.hour.iloc[0])
9
Source code in src/gbfs_toolkit/io/timeseries.py
def add_local_time(
    panel: pd.DataFrame, tz_name: str, *, time_col: str = "fetched_at", new_col: str = "local_time"
) -> pd.DataFrame:
    """Add a local-time column to a panel, handling the index correctly.

    Converting a UTC timestamp to local time is the first step of any diurnal analysis,
    and doing it on a MultiIndexed panel by hand (``reset_index`` then ``tz_convert`` then
    ``set_index``) is a recurring papercut. This flattens the panel and appends one
    tz-aware ``new_col`` in ``tz_name``, leaving ``time_col`` (UTC) untouched.

    Parameters
    ----------
    panel : pandas.DataFrame
        Any panel/frame with a tz-aware (or UTC-coercible) ``time_col``.
    tz_name : str
        An IANA zone, e.g. ``"Europe/Paris"`` or ``"America/New_York"``.
    time_col, new_col : str
        Source UTC column and the local-time column to add.

    Returns
    -------
    pandas.DataFrame
        A flattened copy of ``panel`` with the added ``new_col``.

    See Also
    --------
    [`build_availability_panel`][gbfs_toolkit.build_availability_panel] : Build a panel already in local time via ``target_tz``.
    [`resample_panel`][gbfs_toolkit.resample_panel] : Put the panel on a fixed time grid.

    Examples
    --------
    >>> import pandas as pd
    >>> df = pd.DataFrame({"fetched_at": pd.to_datetime(["2026-01-01T08:00Z"])})
    >>> int(add_local_time(df, "Europe/Paris")["local_time"].dt.hour.iloc[0])
    9
    """
    df = panel_frame(panel)
    require_columns(df, [time_col], what="add_local_time")
    out = df.copy()
    out[new_col] = pd.to_datetime(out[time_col], utc=True).dt.tz_convert(tz_name)
    return out