Source code for space_pv_analytics.uncertainty

"""Chronological block-conformal V/I envelopes with coherent power bounds.

This is a transparent research baseline inspired by recent spacecraft-envelope
work, not an implementation of its complete algorithm. Exact conformal coverage
requires exchangeable block scores; real spacecraft time series may violate
that assumption. Report held-out coverage and interval width by regime.
"""

from __future__ import annotations

from dataclasses import dataclass
from math import ceil
from typing import cast

import numpy as np
import pandas as pd

from .calibration import _time_index


def _vi(values, name: str) -> np.ndarray:
    array = np.asarray(values, dtype=float)
    if array.ndim == 2 and array.shape[1] == 2:
        array = array[:, None, :]
    if (
        array.ndim != 3
        or array.shape[2] != 2
        or not array.shape[0]
        or not array.shape[1]
        or not np.isfinite(array).all()
    ):
        raise ValueError(f"{name} must be finite with axes (sample, horizon, voltage/current)")
    return array


[docs] def conformal_order_statistic(scores, *, coverage: float) -> float: """Finite-sample split-conformal quantile; returns infinity if insufficient. The order is ceil((n+1)*coverage), without clipping it to n. Clipping would silently advertise a confidence level unsupported by the calibration size. """ values = np.asarray(scores, dtype=float) if values.ndim != 1 or not len(values) or not np.isfinite(values).all() or (values < 0).any(): raise ValueError("scores must be a nonempty finite nonnegative vector") if not 0 < coverage < 1: raise ValueError("coverage must lie strictly between zero and one") rank = ceil((len(values) + 1) * coverage) return float("inf") if rank > len(values) else float(np.partition(values, rank - 1)[rank - 1])
[docs] @dataclass(frozen=True) class VIPredictionIntervals: """Joint V/I rectangles and sign-safe extrema of their products.""" prediction: np.ndarray lower: np.ndarray upper: np.ndarray power_prediction_w: np.ndarray power_lower_w: np.ndarray power_upper_w: np.ndarray coverage: float
[docs] def empirical_coverage(self, observed) -> dict[str, float]: """Measure simultaneous-horizon coverage, retaining unbounded widths.""" actual = _vi(observed, "observed") if actual.shape != self.prediction.shape: raise ValueError("Observed and predicted interval shapes must agree") within = (actual >= self.lower) & (actual <= self.upper) actual_power = actual[..., 0] * actual[..., 1] power_within = (actual_power >= self.power_lower_w) & (actual_power <= self.power_upper_w) return { "joint_vi_coverage": float(within.all(axis=(1, 2)).mean()), "joint_power_coverage": float(power_within.all(axis=1).mean()), "mean_voltage_width_v": float((self.upper[..., 0] - self.lower[..., 0]).mean()), "mean_current_width_a": float((self.upper[..., 1] - self.lower[..., 1]).mean()), "mean_power_width_w": float((self.power_upper_w - self.power_lower_w).mean()), }
[docs] @dataclass(frozen=True) class BlockConformalVI: """Maximum normalized residual over channels, horizons and each time block.""" quantile: float scales: np.ndarray coverage: float block_size: int calibration_blocks: int calibration_samples: int discarded_tail_samples: int trained_through: pd.Timestamp calibrated_through: pd.Timestamp horizons: int
[docs] def predict(self, predicted, *, origin_times) -> VIPredictionIntervals: """Apply frozen intervals after the last calibration target timestamp.""" prediction = _vi(predicted, "predicted") times = _time_index(origin_times, name="origin_times") if len(times) != len(prediction) or prediction.shape[1] != self.horizons: raise ValueError("Prediction shape/time specification differs from calibration") if times[0] <= self.calibrated_through: raise ValueError("Evaluation origins must follow all calibration target labels") half_width = self.quantile * self.scales lower, upper = prediction - half_width, prediction + half_width if np.isinf(self.quantile): power_lower = np.full(prediction.shape[:2], -np.inf) power_upper = np.full(prediction.shape[:2], np.inf) else: products = np.stack( [ lower[..., 0] * lower[..., 1], lower[..., 0] * upper[..., 1], upper[..., 0] * lower[..., 1], upper[..., 0] * upper[..., 1], ], axis=-1, ) power_lower, power_upper = products.min(axis=-1), products.max(axis=-1) return VIPredictionIntervals( prediction, lower, upper, prediction[..., 0] * prediction[..., 1], power_lower, power_upper, self.coverage, )
[docs] def calibrate_block_conformal_vi( observed, predicted, *, origin_times, target_end_times, trained_through, scales, coverage: float = 0.9, block_size: int = 20, ) -> BlockConformalVI: """Calibrate joint multi-horizon V/I envelopes on a later time partition. ``scales`` is positive (V, A) or (horizon, 2), selected on training data or independently, never tuned on this calibration/evaluation block. Blocks are nonoverlapping consecutive forecast records. The incomplete trailing block is discarded from scores but its labels remain inside the embargo boundary. This row-block method is not a proof of temporal independence. """ actual, prediction = _vi(observed, "observed"), _vi(predicted, "predicted") if actual.shape != prediction.shape: raise ValueError("Observed and predicted shapes must agree") origins = _time_index(origin_times, name="origin_times") ends = _time_index(target_end_times, name="target_end_times") trained = pd.Timestamp(trained_through) if not isinstance(trained, pd.Timestamp): raise ValueError("trained_through must be a valid timestamp") if len(origins) != len(actual) or len(ends) != len(actual): raise ValueError("Calibration clocks and observations must have equal lengths") if (ends < origins).any() or origins[0] <= trained: raise ValueError( "Calibration must follow training labels and targets cannot precede origins" ) scale = np.asarray(scales, dtype=float) if ( scale.shape not in {(2,), actual.shape[1:]} or not np.isfinite(scale).all() or (scale <= 0).any() ): raise ValueError("scales must be finite positive (V, A) or (horizon, 2)") if isinstance(block_size, bool) or not isinstance(block_size, int) or block_size < 1: raise ValueError("block_size must be a positive integer") blocks = len(actual) // block_size if not blocks: raise ValueError("Calibration must contain at least one complete block") residual = np.abs(actual - prediction) / scale sample_scores = residual.max(axis=(1, 2)) block_scores = sample_scores[: blocks * block_size].reshape(blocks, block_size).max(axis=1) quantile = conformal_order_statistic(block_scores, coverage=coverage) return BlockConformalVI( quantile, scale.copy(), float(coverage), block_size, blocks, len(actual), len(actual) % block_size, trained, cast(pd.Timestamp, ends[-1]), actual.shape[1], )
__all__ = [ "BlockConformalVI", "VIPredictionIntervals", "calibrate_block_conformal_vi", "conformal_order_statistic", ]