"""
From a reliability database to PV failure predictions
================================================================================

This complete walkthrough turns a published string-inverter event rate into
30/90/365-day fleet forecasts. It shows the actual data preparation, equations,
out-of-time evaluation, uncertainty and exported files. Run it offline with::

    uv sync --locked --all-packages
    uv run python examples/analysis/plot_pv_failure_prediction.py

The published benchmark is real. The 200-device fleet is **synthetic**, because
the publications do not provide its underlying individual maintenance records.
Results demonstrate a workflow, not validated predictions for an actual plant.
The companion CLI accepts your own four CSV files; see the
`input guide <../../_generated/guides/pv-failure-prediction.html>`_.
"""

# %%
# 1. Decide exactly what is being predicted
# --------------------------------------------------------------------------------
# We predict recurring, confirmed functional-failure **events** during future
# at-risk operating exposure. A reset alarm is not automatically a failure.
# A failure does not necessarily mean an inverter replacement. The model will
# not identify an exact failure date or rank otherwise identical devices by
# health. Its rate is constant within this matched cohort.

from pathlib import Path
from tempfile import TemporaryDirectory

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd

from energy_analysis.pv_failure_prediction import (
    backtest,
    benchmark_prior,
    export_prediction,
    forecast_table,
    make_demo_inputs,
    plot_prediction,
    prepare_fleet,
    run_prediction,
    select_benchmark,
    split_history,
    update_from_panel,
)
from energy_data_retrieval.pv_reliability_database import load_pv_reliability_evidence
from energy_methods.failure_rates import estimate_rate

# %%
# 2. Inspect the source before using its number
# --------------------------------------------------------------------------------
# Filter by metric first. Availability, drift, survival and event rates have
# incompatible meanings. The alternative inverter rows are separate evidence,
# not independent observations to average. Inspect the source population,
# failure definition, quality flags and operating-hour convention.

rates = load_pv_reliability_evidence(metric="failure_rate")
candidate_rows = rates[rates.device == "String inverter"]
print(candidate_rows[["record_id", "value", "unit", "evidence_origin", "quality_flags"]])
benchmark = select_benchmark("baschel_2018:t1-29")
print("Selected benchmark:", benchmark)

# %%
# 3. Make the units explicit
# --------------------------------------------------------------------------------
# Baschel Table 1 supplies 15.1 events per million operating hours for the
# selected row. The connector stores 15.1e-6 per operating hour. Multiplying by
# exposure gives an expected number of events; converting to a probability
# requires a model. Never multiply by 8760 calendar hours when the input uses
# a daylight/operating clock. The paper uses 4015 operating hours/year.

source_rate = benchmark["rate_per_operating_hour"]
one_unit_hours = benchmark["source_operating_hours_per_year"]
print("Source rate per operating hour:", source_rate)
print("Expected events / source operating-year:", source_rate * one_unit_hours)
print("P(at least one event), fixed-rate Poisson:", -np.expm1(-source_rate * one_unit_hours))

# %%
# 4. Prepare the four tables you would obtain from SCADA and CMMS
# --------------------------------------------------------------------------------
# ``assets`` is the complete fixed-cohort asset register. ``exposure`` contains
# one row for every device and observation period, including never-failed units.
# ``events`` contains stable incident IDs, timestamps, event type and confirmation.
# ``plan`` contains future operating hours for each device/horizon.
#
# Here the generator creates three years of observations using a known assumed
# rate of 26 events/million operating hours. That hidden generating rate is NOT
# used by the estimator. One duplicate, one alarm, one maintenance record and one
# unconfirmed incident are inserted to demonstrate the audit. These are not
# source-paper observations.

inputs = make_demo_inputs(seed=42, devices=200)
for name, table in inputs.items():
    print(f"\n{name}: {len(table)} rows\n", table.head(3).to_string(index=False))

# %%
# 5. Audit the denominator and event identities
# --------------------------------------------------------------------------------
# The pipeline removes exact duplicates, rejects conflicting duplicate IDs,
# counts only confirmed functional failures, and retains zero-event devices.
# Missing exposure is rejected rather than filled with zero. Timestamps use
# UTC and half-open intervals [start,end), so boundary events are counted once.
# Operating exposure excludes down/unobservable time, with event ascertainment
# matched to that same scope. Software cannot verify that semantic requirement.

panel, plan, audit = prepare_fleet(inputs, device_class=benchmark["device_class"])
print("Audit:", audit)
print("Prepared panel:\n", panel.head().to_string(index=False))
print("Total at-risk device-hours:", panel.at_risk_operating_hours.sum())

# %%
# 6. Freeze a training window and hold out the future
# --------------------------------------------------------------------------------
# Fit only to 2023-2024, then evaluate on 2025. Do not randomly split rows: that
# would obscure whether a model would have worked at its forecast origin.
# The cutoff must coincide with an exposure boundary; monthly counts cannot be
# prorated accurately to an arbitrary date. The example uses a fixed historical
# as-of date, not a claim about the current state of a real fleet.

training, holdout = split_history(panel, "2025-01-01")
k_train = int(training.failures.sum())
e_train = float(training.at_risk_operating_hours.sum())
print("Training events / exposure:", k_train, e_train)
print(
    "Holdout events / exposure:", int(holdout.failures.sum()), holdout.at_risk_operating_hours.sum()
)

# %%
# 7. Compare the raw fleet estimate with an explicit database prior
# --------------------------------------------------------------------------------
# The empirical estimate is k/E, with an exact Poisson confidence interval.
# The Bayesian prior is Gamma(shape=a, RATE=b), using a=2 and b=a/source_rate.
# Its mean equals the published rate. **The strength a=2 is our assumption**,
# not two failures or a sample size reported by the paper. Sensitivity is checked
# later. A source point estimate alone cannot establish prior uncertainty.

empirical = estimate_rate(k_train, e_train)
prior = benchmark_prior(benchmark, strength=2)
print("Empirical training estimate:", empirical)
print("Prior shape / rate parameter in device-hours:", prior.shape, prior.rate)
print("Prior mean and 95% rate interval:", prior.mean, prior.interval())

# %%
# 8. Update the rate without counting evidence twice
# --------------------------------------------------------------------------------
# Conjugate update: a_post=a+k and b_post=b+E. This combines an assumed external
# prior with NEW independent observations from the matched fleet. Do not also
# add the published table's underlying incidents to these local observations.

fitted = update_from_panel(prior, training)
assert fitted.shape == prior.shape + k_train
assert fitted.rate == prior.rate + e_train
print("Training posterior:", fitted)
print("Updated events/million hours:", fitted.mean * 1e6)
print("Updated 95% rate interval per million hours:", np.array(fitted.interval()) * 1e6)

# %%
# 9. Predict the withheld year before looking at its outcomes
# --------------------------------------------------------------------------------
# Compare the unchanged database prior against the training-updated model.
# Neither sees any 2025 outcomes during prediction. We report count MAE,
# mean negative log predictive probability (lower is better), and descriptive
# coverage of marginal 95% intervals. Twelve synthetic periods are not proof
# of field calibration. The test uses REALIZED holdout operating exposure, so
# it evaluates event prediction conditional on exposure, not exposure forecasting.

held_predictions, scores = backtest(prior, fitted, holdout)
print("Frozen holdout predictions:\n", held_predictions.head(6).to_string(index=False))
print("Holdout comparison:\n", scores.to_string(index=False))

# %%
# 10. Refit as of 1 January 2026, then forecast planned exposure
# --------------------------------------------------------------------------------
# Only now do we incorporate 2025 into the posterior. Planned hours, not just a
# calendar horizon, drive each forecast. A shared cohort rate means device
# differences below come only from planned exposure, not inferred health.

current = update_from_panel(fitted, holdout)
device_forecasts = forecast_table(current, plan)
print("Per-device forecasts:\n", device_forecasts.head(6).to_string(index=False))

# %%
# 11. Distinguish expected events, affected devices and uncertainty
# --------------------------------------------------------------------------------
# For total future exposure H, expected events are H*a/b. The chance of at least
# one event is 1-(b/(b+H))**a. The full predictive event-count distribution is
# negative-binomial: it includes BOTH uncertain rate and random future events.
# Multiplying rate credible limits by H does not produce a count prediction
# interval. For the fleet, sum H first because all devices share rate uncertainty.
# Do not add per-device upper bounds or assume marginal independence.

annual = device_forecasts[device_forecasts.horizon_days == 365]
future_hours = float(annual.operating_hours.sum())
print("Database-only fixed-rate expected events:", source_rate * future_hours)
print("Updated expected repeat events:", current.expected_failures(future_hours))
print("Updated 95% predictive count interval:", current.predictive_count_interval(future_hours))
print("Expected devices with >=1 event:", annual.probability_at_least_one_event.sum())
print("P(at least one event in the whole fleet):", current.probability_at_least_one(future_hours))

# %%
# 12. Check sensitivity and turn the numbers into a bounded decision
# --------------------------------------------------------------------------------
# Re-run assumed prior strengths 0.5, 2 and 10, holding the chosen source fixed.
# A strong dependence on prior strength means the local evidence is still weak.
# Predictions can inform inspection workload or scenario budgets. They do NOT
# directly specify spare-inverter stock: failures may be resettable/repairable,
# and procurement needs repair times, lead times and replacement probabilities.
# If monitoring completeness, cohort homogeneity or the constant-rate assumption
# fails, repair the data/model before treating the forecasts as operational.

study = run_prediction(inputs, train_end="2025-01-01", input_origin="synthetic_demo")
print("Prior-strength sensitivity:\n", study["sensitivity"].to_string(index=False))
print("Fleet forecasts:\n", study["forecasts"].to_string(index=False))
figure = plot_prediction(study)
plt.show()

# %%
# 13. Save the inputs, audit trail and predictions
# --------------------------------------------------------------------------------
# The CLI writes persistent artifacts; this gallery uses a temporary directory
# to avoid changing the repository while its examples run. Four CSV inputs,
# seven result tables, a JSON manifest with input SHA-256 checksums, and a figure
# make every quantity traceable. The source record and assumed prior strength
# remain in the manifest. No credentials or live network calls are required.

with TemporaryDirectory() as temporary:
    output = Path(temporary)
    export_prediction(study, inputs, output)
    print(
        "Exported files:",
        sorted(str(p.relative_to(output)) for p in output.rglob("*") if p.is_file()),
    )
    reloaded = {name: pd.read_csv(output / "inputs" / f"{name}.csv") for name in inputs}
    repeated = run_prediction(reloaded, train_end="2025-01-01")
    pd.testing.assert_frame_equal(study["forecasts"], repeated["forecasts"])
    print("CSV round-trip reproduces every forecast.")

# %%
# 14. Replace the synthetic fleet with your own records
# --------------------------------------------------------------------------------
# First generate editable example input files and persistent results::
#
#     uv run python -m energy_analysis.pv_failure_prediction --output artifacts/pv-prediction
#
# Replace all four files in a separate input directory, review the benchmark
# definition/population, then run with an explicit holdout boundary::
#
#     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
#
# Run separate matched cohorts for different device classes. Do not transfer
# inverter rates to tracker motors or pyranometers. If individual first-failure
# ages are available, the repository also provides Kaplan-Meier, censored Weibull
# and conditional lifetime risk; a published point rate cannot identify ageing.
