Tutorial

A complete walkthrough is available as a Jupyter notebook in the repository: notebooks/tutorial.ipynb.

Below is the same tutorial transcribed for reading inline.

1. Generate synthetic data

import aridkpi

df = aridkpi.synth.synthetic_dataset(
    start="2026-01-15",
    days=14,
    typology="masonry_insulated",
    seed=42,
)

The typology argument selects one of four prototype envelopes:

• "adobe" — high mass, low attenuation, large phase lag

• "masonry_no_insulation" — medium mass

• "masonry_insulated" — current Argentine standard (IRAM 11605)

• "lightweight" — industrialised, low mass

2. Compute the 5 CORE KPIs

Indoor Overheating Degree (IOD)

iod_value = aridkpi.iod(df["T_in"], T_comf=26.0)

Maximum thermal change rate (dT/dt max)

peak_rate = aridkpi.max_thermal_change_rate(df["T_in"])

UDH during a 72-hour outage

outage_start = df["T_ext"].idxmax().normalize()
udh_value = aridkpi.udh(
    df["T_in"],
    outage_start=outage_start,
    window="72h",
    threshold=30.0,
)

CCOR (climate change overheating resistivity)

df_baseline = aridkpi.synth.synthetic_dataset(
    typology="lightweight", days=14, seed=42,
)
iod_baseline = aridkpi.iod(df_baseline["T_in"], T_comf=26.0)
iod_strategy = aridkpi.iod(df["T_in"], T_comf=26.0)
ccor_value = aridkpi.ccor(iod_baseline, iod_strategy, delta_T_climate=2.5)

ΔE/ΔT

import pandas as pd

ssp_results = pd.DataFrame({
    "T_mean": [16.5, 17.4, 18.2, 19.1, 21.0],
    "EUI":    [82.0, 86.5, 92.0, 98.0, 110.0],
})
sensitivity = aridkpi.energy_climate_sensitivity(ssp_results)
slope = sensitivity["slope"]   # kWh / m^2 / yr / deg-C

3. Loading real data

df_hobo = aridkpi.io.load_hobo_csv("logger_export.csv")
df_eplus = aridkpi.io.load_energyplus_csv("eplusout.csv")
df_csv = aridkpi.io.load_generic_csv("my_data.csv", timestamp_col="datetime")

aridkpi.io.ensure_valid(df_hobo["T"], max_gap_minutes=15.0)

4. Visualisation

ax = aridkpi.viz.plot_temperature_series(df["T_in"], df["T_ext"])
ax = aridkpi.viz.plot_overheating_diagnostic(df["T_in"], T_comf=26.0)