data.fetch_data.load_timeseries

data.fetch_data.load_timeseries(data_home=None, on_missing='raise')

Load the actual-load time series from interim/energy_load.csv.

Reads the Actual Load column and converts the index to a UTC DatetimeIndex with hourly frequency. Missing values are rejected by default so callers cannot accidentally feed imputed values into downstream safety-critical pipelines. Pass on_missing='ffill_bfill' to opt into the legacy forward/backward fill behavior that was the default before the 1.0 major release.

Parameters

Name	Type	Description	Default
data_home	Optional[Union[str, Path]]	Root data directory. If None, resolved via `get_data_home()`.	`None`
on_missing	`OnMissing`	How to handle NaN rows in `Actual Load`. `'raise'` (default) fails fast with the gap timestamps; `'ffill_bfill'` forward- then back-fills.	`'raise'`

Returns

Name	Type	Description
	pd.Series	pd.Series: Hourly actual-load series indexed by UTC timestamps.

Raises

Name	Type	Description
	FileNotFoundError	If `interim/energy_load.csv` does not exist.
	ValueError	If `on_missing='raise'` and the series has NaNs.

Examples

import os
import shutil
import tempfile

import pandas as pd

from spotforecast2_safe.data.fetch_data import (
    get_package_data_home,
    load_timeseries,
)

tmp = tempfile.mkdtemp()
os.environ["SPOTFORECAST2_DATA"] = tmp
interim = os.path.join(tmp, "interim")
os.makedirs(interim, exist_ok=True)

demo = get_package_data_home() / "demo01.csv"
df = pd.read_csv(demo).rename(
    columns={
        "Time": "Time (UTC)",
        "Actual": "Actual Load",
        "Forecast": "Forecasted Load",
    }
)
df.to_csv(os.path.join(interim, "energy_load.csv"), index=False)

# demo01.csv has gaps on Jan 1 of each year, so we opt into the
# legacy ffill/bfill behavior here.  Production callers should
# leave on_missing='raise' (the default) and surface the gaps.
y = load_timeseries(on_missing="ffill_bfill")
print(isinstance(y, pd.Series), y.index.tz is not None)

shutil.rmtree(tmp)
del os.environ["SPOTFORECAST2_DATA"]

True True