preprocessing.exog_providers.FootballMatchWindowProvider

preprocessing.exog_providers.FootballMatchWindowProvider(
    data_home=None,
    csv_path=None,
    column=None,
    max_gap=0,
    max_tail_gap=0,
    provider_window=None,
)

German football match event-window provider.

Produces a single float32 column football_match_window whose value is 1.0 during configured match windows (pre-kickoff to post-final-whistle including overtime allowance) and 0.0 otherwise. The bundled CSV covers all German national-team matches and every tournament final from UEFA Euro 2016 through FIFA World Cup 2026.

Row-selection rule: every match involving the German national team plus every tournament final (Euro 2016 → WC 2026). Window rule: [kickoff − 30 min floored to the hour, kickoff + D + 60 min ceiled to the hour] where D = 120 min for group-stage matches and D = 165 min for knockout matches.

Rows with provisional = 1 mark WC-2026 knockout slots on Germany’s two potential bracket paths (slot times fixed, teams unresolved at the time of publication). The provider uses these rows identically to resolved rows. They may be revised when the bracket is finalised; the provisional column is documentation only and is not read by the provider.

Parameters

Name Type Description Default
data_home DataHome Unused (kept for a uniform provider signature). None
csv_path Optional[Union[str, Path]] Optional explicit path to the football-match CSV, overriding the bundled football_match_windows_de.csv. None
column Optional[str] Output column name. Defaults to "football_match_window". None
max_gap int Accepted for provider-factory API uniformity; has no effect. 0
max_tail_gap int Accepted for provider-factory API uniformity; has no effect. 0
provider_window Optional[pd.DatetimeIndex] Accepted for provider-factory API uniformity; has no effect. None

Examples

import pandas as pd
from spotforecast2_safe.preprocessing.exog_providers import (
    FootballMatchWindowProvider,
)

# EURO 2024: Germany vs Scotland kicked off 2024-06-14 21:00 CEST
# = 2024-06-14 19:00 UTC; window 18:00–22:00 UTC.
idx = pd.date_range("2024-06-14", periods=48, freq="h", tz="UTC")
out = FootballMatchWindowProvider().build(idx)
print(out.columns.tolist(), out.shape, out.dtypes.iloc[0].name)
assert out.loc["2024-06-14T19:00:00Z", "football_match_window"] == 1.0
assert out.loc["2024-06-14T17:00:00Z", "football_match_window"] == 0.0
['football_match_window'] (48, 1) float32

Methods

Name Description
build Return a single-column float32 frame with event-window values.

build

preprocessing.exog_providers.FootballMatchWindowProvider.build(index)

Return a single-column float32 frame with event-window values.

For each timestamp t in index the value is max(intensity) over all rows whose window contains t (start_utc <= t <= end_utc), or 0.0 when no row covers t.

Parameters

Name Type Description Default
index pd.DatetimeIndex DatetimeIndex (any cadence, tz-aware or tz-naive) covering the training-plus-forecast window. required

Returns

Name Type Description
pd.DataFrame pd.DataFrame: One column (named by self.column), float32, indexed exactly by index. NaN-free; 0.0 outside all event windows.

Raises

Name Type Description
ExogProviderError If the bundled CSV is absent or malformed.

Examples

import pandas as pd
from spotforecast2_safe.preprocessing.exog_providers import (
    FootballMatchWindowProvider,
)

idx = pd.date_range("2024-06-14", periods=48, freq="h", tz="UTC")
provider = FootballMatchWindowProvider()
out = provider.build(idx)
print(out.columns.tolist(), out.shape, out.dtypes.iloc[0].name)
assert out.shape == (48, 1)
assert not out.isna().any().any()
assert out.loc["2024-06-14T19:00:00Z", "football_match_window"] == 1.0
['football_match_window'] (48, 1) float32