Source code for energy_analysis.pv_failure_prediction

"""Database -> fleet audit -> temporal validation -> failure-event forecasts.

The demonstration uses a real published benchmark and explicitly synthetic
fleet observations. Counts concern repeat functional-failure events per at-risk
operating hour, not replacement dates or a calibrated OEM health score.
"""

from __future__ import annotations

import argparse
import hashlib
import json
from dataclasses import asdict
from itertools import pairwise
from pathlib import Path
from typing import Any

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
from scipy.stats import gamma

from energy_data_retrieval.pv_reliability_database import load_pv_reliability_evidence
from energy_methods.failure_rates import GammaRate, estimate_rate

REFERENCE_IDS = (
    "baschel_2018_reliability",
    "nist_failure_rate_estimation",
    "scipy_nbinom_reference",
)
BENCHMARK_ID = "baschel_2018:t1-29"
INPUT_NAMES = ("assets", "exposure", "events", "plan")


[docs] def select_benchmark(record_id: str = BENCHMARK_ID) -> dict[str, Any]: """Choose one unflagged operating-hour rate with attribution; never pool alternatives.""" database = load_pv_reliability_evidence() rows = database[database.record_id == record_id] if len(rows) != 1: raise ValueError(f"Unknown or ambiguous benchmark: {record_id}") row = rows.iloc[0] if ( row.metric != "failure_rate" or row.unit != "1/operating_hour" or row.quality_flags or not np.isfinite(row.value) or row.value <= 0 ): raise ValueError("Benchmark must be an unflagged positive rate per operating hour") return dict( record_id=record_id, device_class=row.device, rate_per_operating_hour=float(row.value), source_url=row.source_url, source_locator=row.source_locator, evidence_origin=row.evidence_origin, source_operating_hours_per_year=float(row.operating_hours_per_year), interpretation="Historical benchmark; review population and event-definition transfer.", )
[docs] def benchmark_prior(benchmark: dict[str, Any], strength: float = 2.0) -> GammaRate: """Match the published mean; strength is an assumed pseudo-event count. A point estimate cannot identify prior uncertainty. Effective prior exposure strength/rate is a modelling assumption, not the paper's sample exposure. """ return GammaRate(strength, strength / benchmark["rate_per_operating_hour"])
[docs] def make_demo_inputs(*, seed: int = 42, devices: int = 200) -> dict[str, pd.DataFrame]: """Synthetic 2023-2025 fixed cohort with a known illustrative generating rate. Rate = 26 events/million at-risk operating hours. Counts are conditional on supplied exposure; timestamps only locate events within each month. This is not a physical uptime/repair simulation. Include all never-failed devices. """ if isinstance(devices, bool) or not isinstance(devices, int) or devices < 1: raise ValueError("devices must be a positive integer") rng = np.random.default_rng(seed) ids = [f"INV-{i + 1:04d}" for i in range(devices)] assets = pd.DataFrame({"device_id": ids, "device_class": "String inverter"}) months = pd.date_range("2023-01-01", "2026-01-01", freq="MS", tz="UTC") monthly_hours = np.array([240, 250, 320, 360, 400, 440, 450, 410, 350, 300, 260, 235]) factors = rng.uniform(0.85, 1.0, devices) exposure, events = [], [] for device, factor in zip(ids, factors, strict=True): for start, end in pairwise(months): hours = round(float(monthly_hours[start.month - 1] * factor), 3) exposure.append([device, start, end, hours]) for _ in range(rng.poisson(26e-6 * hours)): time = start + (end - start) * float(rng.uniform(0.01, 0.99)) events.append([f"EV-{len(events) + 1:05d}", device, time, "functional_failure", 1]) if events: events.append(events[0].copy()) events.extend( [ ["ALARM-1", ids[0], months[3], "alarm", 1], ["PM-1", ids[0], months[4], "planned_maintenance", 1], ["UNCONFIRMED-1", ids[0], months[5], "functional_failure", 0], ] ) plan = [ [device, days, round(float(hours * factor), 3)] for device, factor in zip(ids, factors, strict=True) for days, hours in [(30, 240), (90, 810), (365, 4015)] ] return { "assets": assets, "exposure": pd.DataFrame( exposure, columns=["device_id", "period_start", "period_end", "at_risk_operating_hours"] ), "events": pd.DataFrame( events, columns=["event_id", "device_id", "occurred_at", "event_type", "confirmed"] ), "plan": pd.DataFrame(plan, columns=["device_id", "horizon_days", "operating_hours"]), }
def _require(frame: pd.DataFrame, columns: list[str], name: str, *, empty: bool = False) -> None: if (frame.empty and not empty) or not set(columns).issubset(frame): raise ValueError(f"{name} requires rows and columns {columns}") if frame[columns].isna().any().any(): raise ValueError(f"{name} has missing values; unknown exposure is not zero")
[docs] def prepare_fleet( inputs: dict[str, pd.DataFrame], *, device_class: str ) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, int]]: """Audit a complete fixed-cohort panel and attach verified, deduplicated events. Exposure windows must be contiguous, nonoverlapping and present for every registered asset. Known zero exposure is allowed; missing rows are rejected. Intervals are [start,end), timestamps UTC. Match the event-observation scope to measured at-risk operating hours, excluding downtime/unobserved time. Timestamp checks cannot prove complete reporting. Staggered commissioning needs explicit known-zero rows or separate cohorts, never guessed exposure. """ assets, exposure, events, plan = (inputs[name].copy() for name in INPUT_NAMES) _require(assets, ["device_id", "device_class"], "assets") _require( exposure, ["device_id", "period_start", "period_end", "at_risk_operating_hours"], "exposure" ) _require( events, ["event_id", "device_id", "occurred_at", "event_type", "confirmed"], "events", empty=True, ) _require(plan, ["device_id", "horizon_days", "operating_hours"], "plan") for name, frame in zip(INPUT_NAMES, [assets, exposure, events, plan], strict=True): if not frame.device_id.map(lambda x: isinstance(x, str) and bool(x.strip())).all(): raise ValueError(f"{name}: device IDs must be nonempty strings") if assets.device_id.duplicated().any() or not assets.device_class.eq(device_class).all(): raise ValueError("Require unique assets matching the selected benchmark device class") for name, frame in [("exposure", exposure), ("events", events), ("plan", plan)]: if not frame.device_id.isin(assets.device_id).all(): raise ValueError(f"{name} contains unknown device IDs") for col in ["period_start", "period_end"]: exposure[col] = pd.to_datetime(exposure[col], utc=True, errors="raise", format="ISO8601") events["occurred_at"] = pd.to_datetime( events.occurred_at, utc=True, errors="raise", format="ISO8601" ) if ( exposure[["period_start", "period_end"]].isna().any().any() or events.occurred_at.isna().any() ): raise ValueError("Empty or invalid timestamps") hours = pd.to_numeric(exposure.at_risk_operating_hours, errors="raise") maximum = (exposure.period_end - exposure.period_start).dt.total_seconds() / 3600 if ( not np.isfinite(hours).all() or (hours < 0).any() or (maximum <= 0).any() or (hours > maximum).any() ): raise ValueError("At-risk hours must be finite, nonnegative and within the interval") exposure["at_risk_operating_hours"] = hours if exposure.duplicated(["device_id", "period_start"]).any(): raise ValueError("Duplicate device exposure rows") windows = exposure[["period_start", "period_end"]].drop_duplicates() windows = windows.sort_values("period_start").reset_index(drop=True) if windows.period_start.duplicated().any() or not np.array_equal( windows.period_start.iloc[1:].to_numpy(), windows.period_end.iloc[:-1].to_numpy() ): raise ValueError("Exposure periods must form one contiguous, nonoverlapping grid") if len(exposure) != len(assets) * len(windows): raise ValueError("Missing device-period exposure rows; retain never-failed devices") before = len(events) events = events.drop_duplicates() if ( events.event_id.duplicated().any() or not events.event_id.map(lambda x: isinstance(x, str) and bool(x.strip())).all() ): raise ValueError("Conflicting or empty event IDs") if not events.event_type.isin(["functional_failure", "alarm", "planned_maintenance"]).all(): raise ValueError("Unknown event_type; map CMMS categories explicitly") if not events.confirmed.isin([0, 1]).all(): raise ValueError("confirmed must contain only 0/1") if ( (events.occurred_at < windows.period_start.min()) | (events.occurred_at >= windows.period_end.max()) ).any(): raise ValueError("Events fall outside the observed exposure window") selected = events[events.event_type.eq("functional_failure") & events.confirmed.eq(1)].copy() indices = ( np.searchsorted( windows.period_start.astype("int64"), selected.occurred_at.astype("int64"), side="right" ) - 1 ) selected["period_start"] = windows.period_start.iloc[indices].to_numpy() counts = selected.groupby(["device_id", "period_start"]).size().rename("failures") panel = exposure.join(counts, on=["device_id", "period_start"]) panel["failures"] = panel.failures.fillna(0).astype(int) if ((panel.failures > 0) & (panel.at_risk_operating_hours == 0)).any(): raise ValueError("Confirmed failure in a zero-exposure interval") planned = pd.to_numeric(plan.operating_hours, errors="raise") days = pd.to_numeric(plan.horizon_days, errors="raise") if ( not np.isfinite(planned).all() or not np.isfinite(days).all() or (planned < 0).any() or (days <= 0).any() or (days != np.floor(days)).any() or (planned > days * 24).any() ): raise ValueError("Invalid forecast exposure or horizon") plan["operating_hours"], plan["horizon_days"] = planned, days.astype(int) if plan.duplicated(["device_id", "horizon_days"]).any(): raise ValueError("Duplicate forecast device/horizon") audit = dict( assets=len(assets), device_periods=len(panel), duplicate_event_rows_removed=before - len(events), non_failure_or_unconfirmed_events_excluded=len(events) - len(selected), confirmed_events=len(selected), never_failed_devices=int(panel.groupby("device_id").failures.sum().eq(0).sum()), known_zero_exposure_rows=int(panel.at_risk_operating_hours.eq(0).sum()), ) return panel.sort_values(["period_start", "device_id"]).reset_index(drop=True), plan, audit
[docs] def split_history(panel: pd.DataFrame, train_end: str) -> tuple[pd.DataFrame, pd.DataFrame]: """Freeze at an exposure boundary, without prorating counts or future leakage.""" cutoff = pd.to_datetime(train_end, utc=True) if pd.isna(cutoff) or ((panel.period_start < cutoff) & (panel.period_end > cutoff)).any(): raise ValueError("train_end must coincide with an exposure boundary") training = panel[panel.period_end <= cutoff].copy() holdout = panel[panel.period_start >= cutoff].copy() if training.empty or holdout.empty or training.at_risk_operating_hours.sum() <= 0: raise ValueError("Need nonempty training/holdout and positive training exposure") return training, holdout
[docs] def update_from_panel(prior: GammaRate, panel: pd.DataFrame) -> GammaRate: """Update using summed exposure including every zero-event device-period.""" exposure = float(panel.at_risk_operating_hours.sum()) return prior.update(int(panel.failures.sum()), exposure) if exposure else prior
[docs] def forecast_table(model: GammaRate, plan: pd.DataFrame) -> pd.DataFrame: """Per-device expected repeat events and probability of at least one event.""" result = plan.copy() result["expected_events"] = result.operating_hours.map(model.expected_failures) result["probability_at_least_one_event"] = result.operating_hours.map( model.probability_at_least_one ) bounds = [model.predictive_count_interval(float(h)) for h in result.operating_hours] result["count_lower"], result["count_upper"] = np.asarray(bounds).T return result
[docs] def backtest( prior: GammaRate, fitted: GammaRate, holdout: pd.DataFrame ) -> tuple[pd.DataFrame, pd.DataFrame]: """Frozen-origin conditional-event evaluation, using realized holdout exposure. This does not validate future exposure forecasts. Periods share uncertainty in their common rate, so marginal interval coverage is descriptive only. Neither fitted model is updated with holdout events during evaluation. """ periods = holdout.groupby("period_start").agg( exposure=("at_risk_operating_hours", "sum"), observed=("failures", "sum") ) rows = [] for name, model in [("database_prior", prior), ("updated_from_training", fitted)]: for date, row in periods.iterrows(): exposure, observed = float(row.exposure), int(row.observed) low, high = model.predictive_count_interval(exposure) rows.append( dict( period_start=date, model=name, exposure_hours=exposure, observed_events=observed, expected_events=model.expected_failures(exposure), count_lower=low, count_upper=high, negative_log_probability=-model.predictive_log_probability(observed, exposure), ) ) result = pd.DataFrame(rows) result["absolute_error"] = abs(result.observed_events - result.expected_events) result["interval_covers_observed"] = result.observed_events.between( result.count_lower, result.count_upper ) scores = result.groupby("model", as_index=False).agg( periods=("observed_events", "size"), mean_absolute_error=("absolute_error", "mean"), mean_negative_log_probability=("negative_log_probability", "mean"), marginal_interval_coverage=("interval_covers_observed", "mean"), ) return result, scores
[docs] def run_prediction( inputs: dict[str, pd.DataFrame], *, train_end: str = "2025-01-01", benchmark_id: str = BENCHMARK_ID, prior_strength: float = 2.0, input_origin: str = "user_provided_unverified", ) -> dict[str, Any]: """Run the auditable workflow; refit only after completing holdout scoring.""" benchmark = select_benchmark(benchmark_id) panel, plan, audit = prepare_fleet(inputs, device_class=benchmark["device_class"]) training, holdout = split_history(panel, train_end) prior = benchmark_prior(benchmark, prior_strength) fitted = update_from_panel(prior, training) held, scores = backtest(prior, fitted, holdout) current = update_from_panel(fitted, holdout) device_forecasts = forecast_table(current, plan) forecasts = [] for _, group in device_forecasts.groupby("horizon_days"): exposure = float(group.operating_hours.sum()) low, high = current.predictive_count_interval(exposure) forecasts.append( dict( horizon_days=int(group.horizon_days.iloc[0]), devices=len(group), exposure_hours=exposure, expected_events=current.expected_failures(exposure), count_lower=low, count_upper=high, probability_any_fleet_event=current.probability_at_least_one(exposure), expected_devices_with_event=float(group.probability_at_least_one_event.sum()), ) ) longest = int(plan.horizon_days.max()) exposure = float(plan.loc[plan.horizon_days == longest, "operating_hours"].sum()) sensitivity = [] for strength in sorted({0.5, 2.0, 10.0, prior_strength}): model = update_from_panel(benchmark_prior(benchmark, strength), panel) low, high = model.predictive_count_interval(exposure) sensitivity.append( dict( prior_strength=strength, rate_per_million_hours=model.mean * 1e6, horizon_days=longest, expected_events=model.expected_failures(exposure), count_lower=low, count_upper=high, ) ) rate_rows = [] for name, model in [ ("database_prior", prior), ("training_posterior", fitted), ("as_of_posterior", current), ]: low, high = model.interval() rate_rows.append( dict( model=name, shape=model.shape, rate_parameter_hours=model.rate, mean_per_million_hours=model.mean * 1e6, lower_per_million_hours=low * 1e6, upper_per_million_hours=high * 1e6, ) ) metadata = dict( input_origin=input_origin, train_end=pd.to_datetime(train_end, utc=True).isoformat(), forecast_as_of=panel.period_end.max().isoformat(), confidence=0.95, benchmark=benchmark, assumed_prior_strength=prior_strength, training_events=int(training.failures.sum()), training_exposure_hours=float(training.at_risk_operating_hours.sum()), holdout_events=int(holdout.failures.sum()), holdout_exposure_hours=float(holdout.at_risk_operating_hours.sum()), training_mle=asdict( estimate_rate( int(training.failures.sum()), float(training.at_risk_operating_hours.sum()) ) ), audit=audit, limitations=[ "Synthetic results do not validate forecasts for real assets.", "Constant homogeneous rate; no ageing, condition scores or common-cause failures.", "Holdout uses realized exposure; forecasts depend on accurate planned exposure.", "Events can recur; counts are not unique failed units or replacement demand.", "Intervals condition on event definition, prior strength and model assumptions.", ], ) return dict( metadata=metadata, panel=panel, rates=pd.DataFrame(rate_rows), holdout=held, scores=scores, forecasts=pd.DataFrame(forecasts), devices=device_forecasts, sensitivity=pd.DataFrame(sensitivity), )
[docs] def plot_prediction(study: dict[str, Any]) -> plt.Figure: """Plot rate learning, frozen holdout, future counts and prior sensitivity.""" fig, axes = plt.subplots(2, 2, figsize=(13, 9), layout="constrained") fig.suptitle(f"Failure-event prediction | {study['metadata']['input_origin']}", weight="bold") x = np.linspace(0.001, float(study["rates"].upper_per_million_hours.max()) * 1.1, 300) for row in study["rates"].itertuples(): axes[0, 0].plot( x, gamma.pdf(x, row.shape, scale=1e6 / row.rate_parameter_hours), label=row.model.replace("_", " "), ) axes[0, 0].set( xlabel="Events per million at-risk operating hours", ylabel="Density", title="1. Database prior to fleet posterior", ) axes[0, 0].legend(fontsize=8) for name, frame in study["holdout"].groupby("model"): axes[0, 1].plot( frame.period_start, frame.expected_events, label=str(name).replace("_", " ") ) if name == "updated_from_training": axes[0, 1].fill_between( frame.period_start, frame.count_lower, frame.count_upper, alpha=0.18 ) axes[0, 1].scatter( frame.period_start, frame.observed_events, color="black", s=18, label="Held-out events", ) axes[0, 1].set(ylabel="Events per period", title="2. Frozen holdout; 95% predictive interval") axes[0, 1].tick_params(axis="x", rotation=25) axes[0, 1].legend(fontsize=8) forecast = study["forecasts"] axes[1, 0].bar(forecast.horizon_days.astype(str), forecast.expected_events, color="#117b88") axes[1, 0].vlines( np.arange(len(forecast)), forecast.count_lower, forecast.count_upper, color="black", lw=2, label="95% predictive interval", ) axes[1, 0].set( xlabel="Horizon (days; planned operating hours supplied)", ylabel="Fleet events", title="3. Future count, including event and rate uncertainty", ) axes[1, 0].legend(fontsize=8) sensitivity = study["sensitivity"] axes[1, 1].plot(sensitivity.prior_strength, sensitivity.expected_events, "o-", color="#bd6b2e") axes[1, 1].fill_between( sensitivity.prior_strength, sensitivity.count_lower, sensitivity.count_upper, color="#bd6b2e", alpha=0.18, ) axes[1, 1].set( xlabel="Assumed prior pseudo-events", ylabel="Expected count / predictive interval", title="4. Prior-strength sensitivity; longest horizon", ) for ax in axes.flat: ax.grid(axis="y", alpha=0.2) return fig
[docs] def export_prediction(study: dict[str, Any], inputs: dict[str, pd.DataFrame], output: Path) -> None: """Export exact inputs/checksums, audit, model parameters, forecasts and figure.""" (output / "inputs").mkdir(parents=True, exist_ok=True) checksums = {} for name in INPUT_NAMES: path = output / "inputs" / f"{name}.csv" inputs[name].to_csv(path, index=False) checksums[path.name] = hashlib.sha256(path.read_bytes()).hexdigest() for name in ["panel", "rates", "holdout", "scores", "forecasts", "devices", "sensitivity"]: study[name].to_csv(output / f"{name}.csv", index=False) metadata = dict( study["metadata"], input_sha256=checksums, forecasts=study["forecasts"].to_dict(orient="records"), ) (output / "run_manifest.json").write_text( json.dumps(metadata, indent=2, allow_nan=False) + "\n" ) figure = plot_prediction(study) figure.savefig(output / "failure_prediction.png", dpi=160) plt.close(figure)
[docs] def main() -> None: """Run the offline demo or replace its four input CSV files with your own.""" parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "--input-dir", type=Path, help="assets.csv, exposure.csv, events.csv, plan.csv" ) parser.add_argument("--output", type=Path, default=Path("artifacts/pv-failure-prediction")) parser.add_argument("--train-end", help="UTC holdout boundary; required with --input-dir") parser.add_argument("--benchmark-record", default=BENCHMARK_ID) parser.add_argument("--prior-strength", type=float, default=2) args = parser.parse_args() if args.input_dir and not args.train_end: parser.error("--train-end is required with user-provided inputs") inputs = ( { name: pd.read_csv( args.input_dir / f"{name}.csv", dtype={"device_id": str, "event_id": str} ) for name in INPUT_NAMES } if args.input_dir else make_demo_inputs() ) study = run_prediction( inputs, train_end=args.train_end or "2025-01-01", benchmark_id=args.benchmark_record, prior_strength=args.prior_strength, input_origin="user_provided_unverified" if args.input_dir else "synthetic_demo", ) if not args.input_dir: study["metadata"]["demo_generation"] = dict(seed=42, devices=200, rate_per_hour=26e-6) export_prediction(study, inputs, args.output) print("Input origin:", study["metadata"]["input_origin"]) print("Audit:", study["metadata"]["audit"]) print("Holdout scores:\n", study["scores"].to_string(index=False)) print("Future forecast:\n", study["forecasts"].to_string(index=False)) print("Output:", args.output)
if __name__ == "__main__": main()