Source code for energy_methods.thermal_counterfactual
"""Comfort-event and paired intervention scoring, independent of predictor type."""
from __future__ import annotations
import numpy as np
from numpy.typing import ArrayLike
REFERENCE_IDS = ("galataud_2026_thermal_counterfactual",)
[docs]
def comfort_time(
minutes: ArrayLike,
temperature: ArrayLike,
*,
threshold_c: float = 20.75,
consecutive: int = 2,
not_before_min: float | None = None,
) -> float | None:
"""First sustained heating-threshold crossing, linearly interpolated in minutes.
Require ``consecutive`` samples at or above threshold. Return None if the
event is right-censored by the horizon; never substitute the horizon as an
observed event. If already comfortable at the first sample, return that
sample's time (left-censored). Inputs must be finite and strictly ordered.
``not_before_min`` restricts scoring to samples at/after an eligibility
time, reproducing the source's start-gated metric. This is a heating criterion,
not a two-sided comfort band or cooling metric.
"""
x, y = np.asarray(minutes, dtype=float), np.asarray(temperature, dtype=float)
if (
x.ndim != 1
or y.shape != x.shape
or x.size == 0
or not np.isfinite(x).all()
or not np.isfinite(y).all()
or not np.isfinite(threshold_c)
or not np.all(np.diff(x) > 0)
):
raise ValueError("Times and temperatures must be finite, aligned, and ordered")
if isinstance(consecutive, bool) or not isinstance(consecutive, int) or consecutive < 1:
raise ValueError("consecutive must be a positive integer")
if not_before_min is not None:
if not np.isfinite(not_before_min):
raise ValueError("not_before_min must be finite")
eligible = x >= not_before_min
x, y = x[eligible], y[eligible]
for i in range(max(0, len(y) - consecutive + 1)):
if np.all(y[i : i + consecutive] >= threshold_c):
if i == 0:
return float(x[0])
return float(
x[i - 1] + (x[i] - x[i - 1]) * (threshold_c - y[i - 1]) / (y[i] - y[i - 1])
)
return None
[docs]
def paired_shift_error(
predicted: float | None,
reference: float | None,
actual: float | None,
actual_reference: float | None,
) -> float | None:
"""Predicted minus simulated change, in minutes; positive means overresponse.
All four comfort events must be observed. Missing events remain censored.
"""
values = (predicted, reference, actual, actual_reference)
if any(v is None for v in values):
return None
array = np.asarray(values, dtype=float)
if not np.isfinite(array).all():
raise ValueError("Comfort times must be finite or None")
return float(array[0] - array[1] - array[2] + array[3])