energykit.datasets

Dataset loaders for public energy datasets and synthetic data generation.

energykit.datasets — Loaders for public energy datasets.

energykit.datasets.load_sample_tou_prices(tariff: str = 'residential_us', periods: int = 24) → ndarray[source]

Return sample Time-of-Use electricity prices ($/kWh).

Parameters:

tariff (str) – Price profile to return: - "residential_us" — US residential TOU (3-block: off/mid/on peak) - "flat_us" — US average flat rate (~$0.16/kWh) - "wholesale_eu" — Simulated day-ahead European wholesale prices
periods (int, default 24) – Number of hourly periods to return (repeats if > 24).

Returns:

Electricity prices in $/kWh.

Return type:

np.ndarray, shape (periods,)

energykit.datasets.load_synthetic_load(start: str = '2025-01-01', periods: int = 8760, freq: str = 'h', base_kw: float = 2.5, peak_kw: float = 5.0, noise_std: float = 0.3, seed: int = 42, country: str | None = None) → Series[source]

Generate a synthetic hourly residential load profile.

The profile combines: - Annual seasonality (winter peak / summer AC peak) - Daily profile (morning ramp, evening peak) - Weekday/weekend differentiation - Random Gaussian noise

Parameters:

start (str) – Start date of the series (ISO format).
periods (int, default 8760) – Number of periods (8760 = 1 year of hourly data).
freq (str, default "h") – Data frequency.
base_kw (float) – Minimum (overnight) load in kW.
peak_kw (float) – Maximum (evening peak) load in kW.
noise_std (float) – Standard deviation of Gaussian noise (kW).
seed (int) – Random seed for reproducibility.
country (str or None) – Not currently used. Reserved for future holiday dip modelling.

Returns:

Synthetic load in kW with a DatetimeIndex.

Return type:

pd.Series

Examples

>>> load = load_synthetic_load(periods=8760)
>>> load.plot(title="Synthetic Load Profile")

energykit.datasets.load_uci_household(resample: str = 'h', cache_dir: Path | None = None, columns: list | None = None) → DataFrame[source]

Load the UCI Household Power Consumption dataset.

Downloads and caches the dataset on first call (~20 MB zip). Subsequent calls load from the local cache.

Parameters:

resample (str, default "h") – Resample frequency. "1min" returns raw minute-level data. Common options: "h", "15min", "30min", "D".
cache_dir (Path or None) – Override the default cache directory (~/.cache/energykit or $ENERGYKIT_CACHE).
columns (list or None) – Subset of columns to return. Available: Global_active_power, Global_reactive_power, Voltage, Global_intensity, Sub_metering_1, Sub_metering_2, Sub_metering_3.

Returns:

DataFrame with a DatetimeIndex resampled as requested.

Return type:

pd.DataFrame

Examples

>>> df = load_uci_household(resample="h")
>>> active_power = df["Global_active_power"]  # kW

Loaders