temporal_context_features¶
temporal_context_features
¶
temporal_context_features(panel: DataFrame, *, time_col: str = 'fetched_at', holidays: Any = None) -> DataFrame
Add standard calendar context columns for descriptive temporal analysis.
Every descriptive model or test on bike-share data needs to isolate peaks, weekends and
holidays. This adds them once, consistently, from a tz-aware timestamp, so each study does not
re-derive error-prone dt.dayofweek and pd.cut rules (and the UTC-versus-local traps
that come with them). Convert to local time first for local-calendar semantics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
panel
|
DataFrame
|
Any frame with a tz-aware datetime in |
required |
time_col
|
str
|
The timestamp to derive context from. |
"fetched_at"
|
holidays
|
optional
|
A collection of dates (anything |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
A copy of |
See Also
cyclical_time_features : Smooth sin/cos calendar encodings.
join_exogenous_timeseries : Attach an external series (weather).
Examples:
>>> import pandas as pd
>>> from gbfs_toolkit import temporal_context_features
>>> df = pd.DataFrame({"fetched_at": pd.to_datetime(
... ["2026-06-27 08:30", "2026-06-29 23:00"], utc=True)})
>>> out = temporal_context_features(df)
>>> list(out["time_block"])
['am_peak', 'evening']
>>> out["is_weekend"].tolist()
[True, False]