Step-by-step PV failure prediction#
The full runnable walkthrough contains 14 numbered steps, intermediate tables, equations, temporal validation, uncertainty and a four-panel figure. Its gallery page also offers Python and Jupyter notebook downloads. It uses a real published string-inverter benchmark and an explicitly synthetic 200-device fleet. No real customer fleet was supplied.
Run it#
uv sync --locked --all-packages
uv run python examples/analysis/plot_pv_failure_prediction.py
uv run python -m energy_analysis.pv_failure_prediction --output artifacts/pv-prediction
The module command writes inputs, forecasts and the manifest without opening a
GUI. For a headless environment set MPLBACKEND=Agg. No API keys are needed.
What happens at each step#
Steps |
Action |
What to inspect |
|---|---|---|
1–3 |
Define the event, select one source record, check units |
A historical functional-failure rate is neither a replacement probability nor an uptime percentage. |
4–5 |
Prepare and audit SCADA/CMMS tables |
Keep never-failed devices; reject unknown exposure and conflicting event IDs; exclude alarms and unconfirmed records. |
6 |
Split history chronologically |
Fit 2023–2024; withhold 2025. Never prorate monthly failure counts across a cutoff. |
7–8 |
Estimate the local rate and update a database-centred Gamma prior |
Prior strength is explicitly assumed, since the source point estimate cannot supply its uncertainty. |
9 |
Predict held-out events without updating the model |
Compare MAE, predictive log probability and descriptive interval coverage. |
10–11 |
Refit after validation and predict planned exposure |
Separate repeat events, expected affected devices, latent-rate intervals and predictive count intervals. |
12 |
Vary prior strength |
Check whether assumptions dominate the results; do not tune the prior on the held-out outcomes. |
13–14 |
Export and substitute your own CSVs |
Input checksums, source record, cutoff, assumptions, parameters and results remain traceable. |
Replace the synthetic data#
Create a directory containing these four files. Copy the demo files from
artifacts/pv-prediction/inputs as schema examples, then replace their contents.
File |
Required columns |
Contract |
|---|---|---|
|
|
One row per registered device; never-failed devices included. All classes must match the selected source, e.g. |
|
|
Complete contiguous period grid for every asset. Hours are known, finite, nonnegative, and no greater than elapsed hours. Exclude downtime and unobserved time, using the same observation scope as event collection. |
|
|
Stable incident IDs. Types: |
|
|
One row per future device/horizon, such as 30/90/365 days. Specify planned operating exposure rather than assuming calendar hours equal operation. |
Timestamps are parsed in UTC. Periods are [start,end); an event exactly at the
end belongs to the next period. Exact duplicate event rows are removed; duplicate
IDs with conflicting contents raise an error. Imported labels must be mapped
explicitly. Unknown IDs, missing exposure rows, invalid hours, overlapping periods,
wrong device classes and failures in zero-exposure periods stop the workflow.
The fixed-cohort contract requires explicit known-zero exposure rows before commissioning/after removal, or separately analysed cohorts. A missing record is not evidence of zero exposure. Ensure reporting coverage is matched between events and exposure: numerical validation cannot establish complete maintenance reporting or that a paper’s event definition matches yours.
uv run python -m energy_analysis.pv_failure_prediction \
--input-dir my_fleet \
--train-end 2025-01-01 \
--benchmark-record baschel_2018:t1-29 \
--prior-strength 2 \
--output artifacts/my-fleet-prediction
--train-end is mandatory for supplied data and must be an exposure boundary
with observations on both sides. Forecast origin is the last observed interval
end. All planned horizons start at that origin. Inputs are labelled
user_provided_unverified; importing a CSV does not certify data quality.
The equations behind the forecast#
For counts k and summed at-risk device-hours E, the empirical rate is k/E.
For a Gamma prior with shape a and rate parameter b, the update is
a_post=a+k, b_post=b+E. The prior mean a/b matches the selected benchmark;
default a=2 is an assumed pseudo-event count. b is effective prior exposure,
not an exposure denominator extracted from the paper.
For future exposure H, expected events are H*a_post/b_post and the probability
of at least one event is 1-(b_post/(b_post+H))**a_post. Integrating uncertain
rate over Poisson counts gives a negative-binomial predictive distribution with
n=a_post, p=b_post/(b_post+H). Its variance exceeds its mean by the contribution
from rate uncertainty. Predictive bounds include future event randomness;
rate credible bounds multiplied by H do not.
Fleet exposure is summed before calculating the predictive interval, because the uncertain common rate is shared. Expected numbers of affected devices are the sum of device-level event probabilities. Those differ from repeat-event counts. Per-device upper count bounds must not be added to obtain a fleet bound.
Reading the demonstration honestly#
With seed 42, the demo has 200 inverters, 7,200 device-period rows and 68 confirmed events. It removes one duplicate and three excluded records, and retains 139 never-failed devices. Its historical forecast origin is 1 January 2026. The 365-day result is approximately 22.02 repeat events, with a 95% predictive interval of 12–33, conditional on the example’s planned exposure. This is a synthetic workflow result, not a validated real-fleet forecast.
The holdout uses realized operating hours, so it tests conditional event prediction, not the accuracy of an exposure forecast. Twelve synthetic periods cannot establish field calibration. Evaluate multiple future windows/sites with verified observations before relying on a model operationally.
The constant homogeneous rate excludes ageing, condition covariates, weather damage, common-cause failures, changing maintenance practice and reporting bias. Different risks shown for otherwise identical devices reflect exposure alone. Event counts may inform work planning, but spare stock needs replacement probabilities, lead times and repair capacity. No costs are invented.
Outputs and sources#
The run writes inputs/*.csv, panel.csv, rates.csv, holdout.csv, scores.csv,
forecasts.csv, devices.csv, sensitivity.csv, run_manifest.json and
failure_prediction.png. The manifest records source attribution, audit counts,
cutoff, as-of date, prior assumptions, input checksums and limitations.
Source: Baschel et al. (2018), Table 1,
record baschel_2018:t1-29, 15.1 events per million operating hours, source
convention 4,015 operating hours/year. The evidence connector keeps alternative
rates and quality flags distinct; see the PV review.
Predictive parameterization follows the
SciPy negative-binomial documentation.
For age-dependent/competing-risk alternatives, see the
algorithm guide.