"""Competing risks, lifetime uncertainty, redundancy and repairable availability.
These algorithms complement ``failure_rates`` and ``pv_device_reliability``.
Inputs must be homogeneous, correctly censored observations or explicit scenario
assumptions. An anomaly score is not a failure count or calibrated probability.
"""
from __future__ import annotations
import numpy as np
import pandas as pd
from numpy.typing import ArrayLike, NDArray
from energy_methods.failure_rates import fit_weibull_censored
REFERENCE_IDS = (
"survival_competing_risks",
"scipy_bootstrap_reference",
"nist_reliability_series",
"nist_reliability_parallel",
"nasa_repairable_availability",
)
def _vector(value: ArrayLike, name: str) -> NDArray[np.float64]:
array = np.asarray(value, dtype=float)
if array.ndim != 1 or not array.size or not np.isfinite(array).all():
raise ValueError(f"{name} must be a nonempty finite one-dimensional vector")
return array
[docs]
def aalen_johansen(times: ArrayLike, event_type: ArrayLike) -> pd.DataFrame:
"""First-event cumulative incidence with mutually exclusive verified causes.
One row per device from commissioning: 0=censored, positive integer=cause.
At each age, ``F_j += S(previous)*d_j/n``, then ``S *= (1-sum(d_j)/n)``.
Tied events across devices precede censoring; no artificial jitter is used.
Independent censoring is assumed, but independent latent failure causes are
not required. No delayed entry, recurrent faults or interval censoring.
Unknown causes must have their own positive code, not be treated as censored.
Outputs point estimates, not confidence intervals or causal effects.
"""
age, cause = _vector(times, "times"), _vector(event_type, "event_type")
if (
age.shape != cause.shape
or np.any(age <= 0)
or np.any(cause < 0)
or np.any(cause != np.floor(cause))
):
raise ValueError("Positive ages must align with nonnegative integer cause codes")
causes = np.unique(cause[cause > 0])
cumulative = dict.fromkeys((int(c) for c in causes), 0.0)
survival = 1.0
records = []
for time in np.unique(age):
risk = int((age >= time).sum())
current = cause[age == time]
failures = int((current > 0).sum())
for c in cumulative:
cumulative[c] += survival * int((current == c).sum()) / risk
survival *= 1 - failures / risk
records.append(
dict(
age=float(time),
at_risk=risk,
failures=failures,
censored=int((current == 0).sum()),
survival=survival,
**{f"incidence_{c}": value for c, value in cumulative.items()},
)
)
return pd.DataFrame(records)
[docs]
def bootstrap_weibull_survival(
times: ArrayLike,
failed: ArrayLike,
evaluation_times: ArrayLike,
*,
resamples: int = 500,
confidence: float = 0.95,
seed: int = 0,
allow_extrapolation: bool = False,
) -> pd.DataFrame:
"""Paired device bootstrap and percentile pointwise Weibull survival bounds.
Resample (age, event) rows together and refit the right-censored MLE. This
assumes iid devices and independent censoring; shared site/weather cohorts
require a cluster bootstrap instead. It does not quantify model error.
Raises if ANY resample is unidentified: silently dropping failed fits can
bias intervals. Sparse cohorts should use KM/rate bounds instead.
Tail extrapolation beyond observed follow-up requires explicit opt-in and
remains an unvalidated model projection. Intervals are not simultaneous.
"""
age, events = _vector(times, "times"), _vector(failed, "failed")
grid = _vector(evaluation_times, "evaluation_times")
model = fit_weibull_censored(age, events)
if (
isinstance(resamples, bool)
or not isinstance(resamples, (int, np.integer))
or resamples < 100
or not np.isfinite(confidence)
or not 0 < confidence < 1
or np.any(grid < 0)
or np.any(np.diff(grid) <= 0)
):
raise ValueError(
"Need >=100 resamples, confidence in (0,1), and increasing nonnegative ages"
)
if grid[-1] > age.max() and not allow_extrapolation:
raise ValueError(
"Evaluation exceeds observed follow-up; extrapolation needs explicit opt-in"
)
rng = np.random.default_rng(seed)
curves = np.empty((resamples, grid.size))
for i in range(resamples):
index = rng.integers(0, age.size, size=age.size)
try:
fitted = fit_weibull_censored(age[index], events[index])
except ValueError as exc:
raise ValueError(
f"Unidentified bootstrap fit at resample {i + 1}; no interval reported"
) from exc
curves[i] = np.exp(fitted.log_survival(grid))
tail = (1 - confidence) / 2
lower, upper = np.quantile(curves, [tail, 1 - tail], axis=0)
result = pd.DataFrame(
dict(
age=grid,
survival=np.exp(model.log_survival(grid)),
lower=lower,
upper=upper,
extrapolated=grid > age.max(),
)
)
result.attrs.update(
shape=model.parameter1,
scale=model.parameter2,
resamples=int(resamples),
confidence=confidence,
seed=seed,
method="paired_device_percentile_bootstrap",
)
return result
[docs]
def k_out_of_n_reliability(component_reliability: ArrayLike, required: int) -> float:
"""Poisson-binomial dynamic program for independent active components.
At one common mission age, the system works if >= required components work.
required=n gives series; required=1 gives active parallel redundancy.
Probabilities must have matching horizons/definitions. Reusing this for
steady availability requires independent component states. No standby,
load sharing, common-cause events or proportional-capacity interpretation.
Compose disjoint blocks only; shared components must not appear twice.
"""
probabilities = _vector(component_reliability, "component_reliability")
if (
np.any((probabilities < 0) | (probabilities > 1))
or isinstance(required, bool)
or not isinstance(required, (int, np.integer))
or not 1 <= required <= probabilities.size
):
raise ValueError("Probabilities must be in [0,1], required an integer in [1,n]")
distribution = np.array([1.0])
for p in probabilities:
distribution = np.convolve(distribution, [1 - p, p])
return float(np.clip(distribution[required:].sum(), 0, 1))
[docs]
def repairable_availability(
failure_rate_per_hour: float,
mean_restore_hours: float,
interval_hours: ArrayLike,
expected_power_kw: ArrayLike,
*,
initial_availability: float = 1.0,
) -> pd.DataFrame:
"""Exact two-state Markov interval availability and expected energy at risk.
Constant up->down rate lambda and down->up rate mu=1/mean_restore_hours.
Both use the SAME clock: this function uses calendar hours while the unit
is in each state. Do not pass a daylight operating-hour rate unchanged.
Restoration duration is exponential; include logistics in its mean only
if this memoryless approximation is defensible. Initial state is explicit.
Expected power is the nonnegative, piecewise-constant counterfactual output
of the affected capacity when available, in kW. Down means zero output;
partial derating and overlapping parent/child losses need another model.
Assumes the counterfactual profile is independent of failures/restoration;
weather-correlated damage, shared repair crews and ageing are excluded.
Returns expectations, not confidence intervals or a stochastic trajectory.
"""
hours = _vector(interval_hours, "interval_hours")
power = _vector(expected_power_kw, "expected_power_kw")
if (
hours.shape != power.shape
or np.any(hours <= 0)
or np.any(power < 0)
or not np.isfinite(failure_rate_per_hour)
or failure_rate_per_hour < 0
or not np.isfinite(mean_restore_hours)
or mean_restore_hours <= 0
or not np.isfinite(initial_availability)
or not 0 <= initial_availability <= 1
):
raise ValueError("Require aligned positive hours, nonnegative power/rate and valid state")
repair_rate = 1 / mean_restore_hours
total_rate = failure_rate_per_hour + repair_rate
if not np.isfinite(total_rate) or not np.isfinite(hours.sum()):
raise ValueError("Rate or horizon exceeds numerical range")
stationary_down = failure_rate_per_hour / total_rate
down = 1 - initial_availability
start = 0.0
rows = []
for duration, baseline in zip(hours, power, strict=True):
z = total_rate * float(duration)
if not np.isfinite(z):
raise ValueError("Rate times duration exceeds numerical range")
decay = np.exp(-z)
# Stable 1 - (1-exp(-z))/z near zero avoids negative tiny downtime.
complement = z / 2 - z**2 / 6 + z**3 / 24 - z**4 / 120 if z < 1e-4 else 1 + np.expm1(-z) / z
mean_down = down * (1 - complement) + stationary_down * complement
downtime = float(duration * mean_down)
down = down * decay + stationary_down * (-np.expm1(-z))
rows.append(
dict(
start_hour=start,
end_hour=start + duration,
availability_end=float(1 - down),
mean_availability=float(1 - mean_down),
expected_downtime_hours=downtime,
expected_failures=float(failure_rate_per_hour * (duration - downtime)),
baseline_energy_kwh=float(baseline * duration),
expected_energy_loss_kwh=float(baseline * downtime),
)
)
start += float(duration)
result = pd.DataFrame(rows)
result.attrs.update(
failure_rate_per_hour=failure_rate_per_hour,
mean_restore_hours=mean_restore_hours,
initial_availability=initial_availability,
steady_availability=1 - stationary_down,
)
return result