forecastscope 0.1.0__py3-none-any.whl

forecastscope/__init__.py

@@ -0,0 +1,5 @@
+"""Finite-prefix forecasts and causal historical forecast combinations."""
+from .api import METHOD_NAMES, combine, forecast
+
+__version__ = "0.1.0"
+__all__ = ["METHOD_NAMES", "combine", "forecast"]

forecastscope/api.py

@@ -0,0 +1,72 @@
+"""Validated entry points; legacy numerical kernels retain their original equations."""
+from __future__ import annotations
+
+from itertools import pairwise
+
+import numpy as np
+
+from .combinations.context_memory import MemoryFit, fit_context_memory
+from .combinations.validated import ValidatedFit, fit_validated
+from .forecasting import METHOD_FNS, gaussian_quantiles
+
+METHOD_NAMES = tuple(METHOD_FNS)
+
+
+def _request(history, seasonality, horizon, quantiles):
+    y = np.asarray(history, dtype=float)
+    if y.ndim != 1 or len(y) < 2 or not np.isfinite(y).all():
+        raise ValueError("A contiguous finite one-dimensional history of at least two observations is required")
+    for name, value in [("seasonality", seasonality), ("horizon", horizon)]:
+        if isinstance(value, (bool, np.bool_)) or not isinstance(value, (int, np.integer)) or value < 1:
+            raise ValueError(f"{name} must be a positive integer")
+    if seasonality >= len(y):
+        raise ValueError("seasonality must be smaller than the observed history length")
+    levels = tuple(float(q) for q in quantiles)
+    if not levels or not np.isfinite(levels).all() or not all(0 < q < 1 for q in levels) or not all(a < b for a, b in pairwise(levels)):
+        raise ValueError("Quantiles must be finite, strictly increasing probabilities between zero and one")
+    return y, int(seasonality), int(horizon), levels
+
+
+def _output(values, horizon, levels):
+    a = np.asarray(values, dtype=float)
+    if a.shape != (horizon, len(levels)) or not np.isfinite(a).all() or np.any(np.diff(a, axis=1) < 0):
+        raise ValueError("The method returned invalid forecast dimensions, nonfinite values or crossing columns")
+    return a
+
+
+def forecast(method: str, history, *, seasonality: int = 1, horizon: int = 1, quantiles=(.1, .5, .9)) -> np.ndarray:
+    """Return full-precision horizon-by-quantile Gaussian residual columns.
+
+    Inputs must be contiguous and finite; no imputation, source acquisition or
+    seasonal-period selection is performed. These approximate intervals carry no
+    calibration guarantee. Methods refit on the whole supplied prefix.
+    """
+    y, m, h, levels = _request(history, seasonality, horizon, quantiles)
+    if method not in METHOD_FNS:
+        raise ValueError(f"Unknown method {method!r}; choose from {METHOD_NAMES}")
+    point, sigma = METHOD_FNS[method](y, m, h)
+    return _output(gaussian_quantiles(point, sigma, levels), h, levels)
+
+
+def combine(method: str, history, *, seasonality: int = 1, horizon: int = 1, quantiles=(.1, .5, .9)) -> MemoryFit | ValidatedFit:
+    """Fit a five-expert combination without accepting a reserved future block.
+
+    The returned object retains weights and complete historical origins. The
+    validated variants additionally retain candidate scores and inner splits.
+    Their canonical probability grid is fixed; unsupported grids are refused.
+    """
+    y, m, h, levels = _request(history, seasonality, horizon, quantiles)
+    modes = {"ContextMemory": "context", "RecencyMean": "recency", "EqualMean": "uniform"}
+    if method in modes:
+        result = fit_context_memory(y, m, h, levels, mode=modes[method])
+    elif method in ("ContextMemoryCV", "ValidationMix"):
+        if levels != (.1, .5, .9):
+            raise ValueError("Temporally validated combinations require quantiles (0.1, 0.5, 0.9)")
+        result = fit_validated(y, m, h, stacking=method == "ValidationMix")
+    else:
+        raise ValueError(f"Unknown combination {method!r}")
+    _output(result.quantiles, h, levels)
+    weights = np.asarray(result.weights)
+    if weights.shape != (5,) or not np.isfinite(weights).all() or np.any(weights < 0) or not np.isclose(weights.sum(), 1):
+        raise ValueError("Invalid expert allocation")
+    return result

forecastscope/combinations/__init__.py

@@ -0,0 +1 @@
+"""Fixed-context and temporally validated combinations of five reference experts."""

forecastscope/combinations/context_memory.py

@@ -0,0 +1,127 @@
+"""ContextMemory: a within-series forecast-combination proposal and its ablations.
+
+Published feature-based averaging and dynamic ensembles motivate the proposal; this
+specific recurrence/recency rule is an experiment, with no claim of priority or superiority.
+All training targets end before the supplied history ends. The final holdout is never an input.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+
+import numpy as np
+
+from ..forecasting import METHODS, Forecaster, _clean, gaussian_quantiles
+
+CONFIG = {
+    "memory_origins": 12,
+    "half_life_origins": 6.0,
+    "global_shrinkage": 0.25,
+    "uniform_floor": 0.05,
+    "temperature": 1.0,
+    "kernel_bandwidth_floor": 0.25,
+}
+EXPERT_NAMES = tuple(name for name, _, _ in METHODS)
+
+
+@dataclass(frozen=True)
+class MemoryFit:
+    quantiles: np.ndarray
+    weights: np.ndarray
+    origins: tuple[int, ...]
+    context: np.ndarray
+
+
+def context_features(y: np.ndarray, m: int) -> np.ndarray:
+    """Four bounded, location-invariant and positive-scale-invariant summaries."""
+    w = min(len(y) // 2, max(8, min(2 * max(m, 1), 48)))
+    if w < 2:
+        return np.zeros(4)
+    recent, previous = y[-w:], y[-2 * w:-w]
+    scale = float(np.std(y[-2 * w:]))
+    if scale < 1e-12:
+        return np.zeros(4)
+    half = max(1, w // 2)
+    slope = (np.mean(recent[-half:]) - np.mean(recent[:half])) / scale
+    shift = (np.mean(recent) - np.mean(previous)) / scale
+    vr, vp = float(np.std(np.diff(recent))), float(np.std(np.diff(previous)))
+    volatility = np.log((vr + scale * 1e-6) / (vp + scale * 1e-6))
+    periodicity = 0.0
+    if m >= 2 and len(y) >= 2 * m + 2:
+        a, b = y[-2 * m:-m], y[-m:]
+        if np.std(a) > 1e-12 and np.std(b) > 1e-12:
+            periodicity = float(np.corrcoef(a, b)[0, 1])
+    return np.clip([slope, shift, volatility, periodicity], -4, 4)
+
+
+def _scale(y: np.ndarray, m: int) -> float:
+    lag = max(1, min(m, len(y) - 1))
+    value = float(np.mean(np.abs(y[lag:] - y[:-lag])))
+    return value if value > 1e-12 else max(float(np.std(y)), 1e-12)
+
+
+@lru_cache(maxsize=64)
+def _memory(values: tuple[float, ...], m: int, h: int):
+    y = np.asarray(values)
+    first, last = max(2 * m, 2 * h + 8, 24), len(y) - h
+    if last < first:
+        return (), np.empty((0, 4)), np.empty((0, len(METHODS)))
+    origins = tuple(int(o) for o in np.unique(np.linspace(first, last, CONFIG["memory_origins"], dtype=int)))
+    features, losses = [], []
+    for origin in origins:
+        history, truth = y[:origin], y[origin:origin + h]
+        features.append(context_features(history, m))
+        losses.append([
+            float(np.mean(np.abs(fn(history, m, h)[0] - truth))) / _scale(history, m)
+            for _, _, fn in METHODS
+        ])
+    return origins, np.asarray(features), np.asarray(losses)
+
+
+def fit_context_memory(y: np.ndarray, m: int, h: int, levels=(0.1, 0.5, 0.9), mode="context") -> MemoryFit:
+    """Fit from completed historical origins, then combine experts at the query origin.
+
+    The recency ablation removes the context kernel; the uniform ablation removes
+    both learning components. Configuration is fixed before the released holdout run.
+    Weighted quantiles are a quantile combination, not a calibrated mixture distribution.
+    """
+    y = _clean(np.asarray(y, dtype=float))
+    if len(y) < 2 or not np.isfinite(y).all() or h < 1 or m < 1:
+        raise ValueError("ContextMemory requires finite history, positive horizon and seasonality")
+    if mode not in {"context", "recency", "uniform"}:
+        raise ValueError(f"Unknown combination mode: {mode}")
+    origins, features, losses = _memory(tuple(float(v) for v in y), m, h)
+    query = context_features(y, m)
+    weights = np.full(len(METHODS), 1 / len(METHODS))
+    if len(origins) and mode != "uniform":
+        ages = np.arange(len(origins) - 1, -1, -1)
+        recency = np.exp2(-ages / CONFIG["half_life_origins"])
+        global_loss = np.average(losses, axis=0, weights=recency)
+        score = global_loss
+        if mode == "context":
+            distance = np.sqrt(np.mean((features - query) ** 2, axis=1))
+            bandwidth = max(float(np.median(distance)), CONFIG["kernel_bandwidth_floor"])
+            local = recency * np.exp(-0.5 * (distance / bandwidth) ** 2)
+            local_loss = np.average(losses, axis=0, weights=local)
+            shrink = CONFIG["global_shrinkage"]
+            score = (1 - shrink) * local_loss + shrink * global_loss
+        logits = -(score - np.min(score)) / CONFIG["temperature"]
+        weights = np.exp(np.clip(logits, -700, 0))
+        weights /= weights.sum()
+        floor = CONFIG["uniform_floor"]
+        weights = (1 - floor) * weights + floor / len(METHODS)
+    forecasts = []
+    for _, _, fn in METHODS:
+        point, sigma = fn(y, m, h)
+        forecasts.append(gaussian_quantiles(point, sigma, tuple(levels)))
+    combined = np.tensordot(weights, np.asarray(forecasts), axes=(0, 0))
+    return MemoryFit(combined, weights, origins, query)
+
+
+class ContextMemoryForecaster(Forecaster):
+    name = "ContextMemory"
+    family = "adaptive ensemble"
+    max_windows = 3
+
+    def quantiles(self, y, m, h, levels):
+        return fit_context_memory(y, m, h, levels).quantiles

forecastscope/combinations/validated.py

@@ -0,0 +1,144 @@
+"""Forecast combinations selected by validation wholly inside the observed prefix.
+
+No outer target is accepted by this API. Model selection compares completed
+historical blocks, and each inner fit excludes blocks not completed at its query.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from itertools import combinations
+
+import numpy as np
+
+from ..forecasting import METHODS, gaussian_quantiles
+from .context_memory import CONFIG, _scale, context_features
+
+CANDIDATES = (
+    ("recency", 1., 1.), ("equal", 0., 1.),
+    *(("context", shrink, temp) for shrink in (0., .5, 1.) for temp in (.15, .5, 1.)),
+    *(("stack", penalty, 1.) for penalty in (.01, .1, 1., 10.)),
+)
+
+
+@dataclass(frozen=True)
+class ValidatedFit:
+    quantiles: np.ndarray
+    weights: np.ndarray
+    selected: tuple[str, float, float]
+    candidates: tuple[dict, ...]
+    origins: tuple[int, ...]
+    validation_splits: tuple[dict, ...]
+
+
+def convex_weights(errors, penalty):
+    """Convex squared-error stacking with shrinkage toward uniform allocation."""
+    a = np.asarray(errors, dtype=float)
+    if a.ndim != 2 or not len(a) or not np.isfinite(a).all() or penalty <= 0:
+        raise ValueError("Stacking requires finite error rows and positive regularization")
+    k = a.shape[1]
+    uniform = np.full(k, 1 / k)
+    gram = a.T @ a / len(a)
+
+    def objective(w):
+        return float(w @ gram @ w + penalty * np.sum((w - uniform) ** 2))
+
+    # Five experts permit exhaustive active-set solutions (31 nonempty faces).
+    # Each face has a positive-definite regularized quadratic; the best feasible
+    # face is the constrained optimum, without iterative solver stopping rules.
+    best, value = uniform, objective(uniform)
+    for size in range(1, k + 1):
+        for active in combinations(range(k), size):
+            ids = list(active)
+            matrix = gram[np.ix_(ids, ids)] + penalty * np.eye(size)
+            rhs = np.column_stack((penalty * uniform[ids], np.ones(size)))
+            try:
+                solution = np.linalg.solve(matrix, rhs)
+            except np.linalg.LinAlgError:
+                continue
+            x, direction = solution[:, 0], solution[:, 1]
+            x = x + (1 - x.sum()) * direction / direction.sum()
+            if not np.isfinite(x).all() or np.min(x) < -1e-10:
+                continue
+            weights = np.zeros(k)
+            weights[ids] = np.maximum(x, 0.)
+            weights /= weights.sum()
+            score = objective(weights)
+            if score < value:
+                best, value = weights, score
+    return best
+
+
+def candidate_weights(candidate, features, losses, errors, query):
+    k = len(METHODS)
+    kind, shrink, temp = candidate
+    if not len(losses) or kind == "equal":
+        return np.full(k, 1 / k)
+    if kind == "stack":
+        weights = convex_weights(errors.reshape(-1, k), shrink)
+    else:
+        ages = np.arange(len(losses) - 1, -1, -1)
+        recency = np.exp2(-ages / CONFIG["half_life_origins"])
+        global_loss = np.average(losses, axis=0, weights=recency)
+        score = global_loss
+        if kind == "context":
+            distance = np.sqrt(np.mean((features - query) ** 2, axis=1))
+            bandwidth = max(float(np.median(distance)), CONFIG["kernel_bandwidth_floor"])
+            local = recency * np.exp(-.5 * (distance / bandwidth) ** 2)
+            score = (1 - shrink) * np.average(losses, axis=0, weights=local) + shrink * global_loss
+        weights = np.exp(np.clip(-(score - np.min(score)) / temp, -700, 0))
+        weights /= weights.sum()
+    return .95 * weights + .05 / k
+
+
+@lru_cache(maxsize=16)
+def memory(values, m, h):
+    y = np.asarray(values, dtype=float)
+    first, last = max(2 * m, 2 * h + 8, 24), len(y) - h
+    if first > last:
+        return (), np.empty((0, 4)), np.empty((0, len(METHODS))), np.empty((0, h, len(METHODS))), ()
+    origins = tuple(int(o) for o in np.unique(np.linspace(first, last, CONFIG["memory_origins"], dtype=int)))
+    features, losses, errors, paths = [], [], [], []
+    for origin in origins:
+        prefix, truth = y[:origin], y[origin:origin+h]
+        quantiles = np.array([gaussian_quantiles(*fn(prefix, m, h), (.1, .5, .9)) for _, _, fn in METHODS])
+        normalized_error = (quantiles[:, :, 1].T - truth[:, None]) / _scale(prefix, m)
+        features.append(context_features(prefix, m))
+        losses.append(np.mean(abs(normalized_error), axis=0))
+        errors.append(normalized_error)
+        paths.append(quantiles)
+    return origins, np.asarray(features), np.asarray(losses), np.asarray(errors), tuple(paths)
+
+
+def temporal_splits(origins, horizon):
+    """Training outcomes must be fully observed when an inner forecast is issued."""
+    return tuple({"query": query, "train": tuple(i for i, origin in enumerate(origins) if origin+horizon <= query)}
+                 for query in origins)
+
+
+def fit_validated(y, m, h, *, stacking=True):
+    y = np.asarray(y, dtype=float)
+    if y.ndim != 1 or len(y) < 2 or not np.isfinite(y).all() or m < 1 or h < 1:
+        raise ValueError("Finite contiguous history, positive seasonality and horizon are required")
+    origins, features, losses, errors, _paths = memory(tuple(y), m, h)
+    candidates = CANDIDATES if stacking else tuple(c for c in CANDIDATES if c[0] != "stack")
+    splits = tuple(s for s in temporal_splits(origins, h) if len(s["train"]) >= 3)
+    scores = []
+    for candidate in candidates:
+        values = []
+        for split in splits:
+            j = origins.index(split["query"])
+            train = list(split["train"])
+            w = candidate_weights(candidate, features[train], losses[train], errors[train], features[j])
+            values.append(float(np.mean(abs(errors[j] @ w))))
+        scores.append({"configuration": candidate, "mean_validation_mae_scaled": float(np.mean(values)) if values else None,
+                       "validation_blocks": len(values)})
+    if splits:
+        winner = min(range(len(candidates)), key=lambda i: (scores[i]["mean_validation_mae_scaled"], i))
+    else:
+        winner = 0  # explicit original recency-only fallback
+    selected = candidates[winner]
+    w = candidate_weights(selected, features, losses, errors, context_features(y, m))
+    experts = np.array([gaussian_quantiles(*fn(y, m, h), (.1, .5, .9)) for _, _, fn in METHODS])
+    combined = np.tensordot(w, experts, axes=(0, 0))
+    return ValidatedFit(combined, w, selected, tuple(scores), origins, splits)

forecastscope/diagnostics/__init__.py

@@ -0,0 +1,236 @@
+"""Optional time-series diagnostics delegated to named scientific implementations.
+
+Results describe the supplied sequence. Retrospective use is distinct from
+prefix-only forecasting features; statistical assumptions remain method-specific.
+"""
+from __future__ import annotations
+
+from . import (
+    autocorrelation,
+    causality,
+    changepoints,
+    distribution,
+    filters,
+    fractal,
+    nonlinear,
+    seasonality,
+    stationarity,
+    volatility,
+)
+from .autocorrelation import (
+    Correlogram,
+    PortmanteauTest,
+    acf,
+    autocorrelation_report,
+    bartlett_band,
+    box_pierce,
+    durbin_watson,
+    lag_plot_pairs,
+    ljung_box,
+    pacf,
+)
+from .causality import (
+    CointegrationResult,
+    CrossCorrelation,
+    GrangerResult,
+    causality_report,
+    cointegration,
+    cross_correlation,
+    granger_causality,
+)
+from .changepoints import (
+    ChangePoints,
+    CusumResult,
+    RegimeFit,
+    binseg,
+    changepoints_report,
+    cusum_stability,
+    markov_regimes,
+    pelt,
+)
+from .distribution import (
+    ComplexitySummary,
+    DistributionSummary,
+    catch22_features,
+    complexity,
+    distribution_report,
+    kde_curve,
+    qq_points,
+    summary,
+)
+from .filters import (
+    EMDResult,
+    FilterResult,
+    Scalogram,
+    baxter_king,
+    ceemdan,
+    christiano_fitzgerald,
+    cwt_scalogram,
+    emd,
+    filters_report,
+    hodrick_prescott,
+)
+from .fractal import (
+    FractalDimension,
+    HurstResult,
+    MultifractalSpectrum,
+    dcca_coefficient,
+    fractal_dimension,
+    fractal_report,
+    hurst,
+    mfdfa,
+)
+from .nonlinear import (
+    RQA,
+    ChaosMeasures,
+    chaos_measures,
+    iaaft_surrogate,
+    nonlinear_report,
+    recurrence_quantification,
+    time_delay_embed,
+    zero_one_test,
+)
+from .seasonality import (
+    Decomp,
+    SeasonalSubseries,
+    Spectrum,
+    mstl_decompose,
+    periodogram,
+    seasonal_strength,
+    seasonal_subseries,
+    seasonality_report,
+    stl_decompose,
+    welch,
+)
+from .stationarity import (
+    TestResult,
+    adf,
+    combined_verdict,
+    dfgls,
+    kpss,
+    ndiffs,
+    nsdiffs,
+    phillips_perron,
+    stationarity_report,
+    zivot_andrews,
+)
+from .volatility import (
+    ArchTest,
+    BoxCoxResult,
+    GarchFit,
+    arch_lm,
+    box_cox,
+    garch,
+    rolling_volatility,
+    volatility_report,
+)
+
+__all__ = [
+    "RQA",
+    # volatility
+    "ArchTest",
+    "BoxCoxResult",
+    # changepoints
+    "ChangePoints",
+    # nonlinear
+    "ChaosMeasures",
+    "CointegrationResult",
+    "ComplexitySummary",
+    # autocorrelation
+    "Correlogram",
+    # causality
+    "CrossCorrelation",
+    "CusumResult",
+    "Decomp",
+    # distribution
+    "DistributionSummary",
+    "EMDResult",
+    # filters
+    "FilterResult",
+    "FractalDimension",
+    "GarchFit",
+    "GrangerResult",
+    # fractal
+    "HurstResult",
+    "MultifractalSpectrum",
+    "PortmanteauTest",
+    "RegimeFit",
+    "Scalogram",
+    "SeasonalSubseries",
+    # seasonality (seasonal_strength lives here as the canonical home)
+    "Spectrum",
+    # stationarity
+    "TestResult",
+    "acf",
+    "adf",
+    "arch_lm",
+    "autocorrelation",
+    "autocorrelation_report",
+    "bartlett_band",
+    "baxter_king",
+    "binseg",
+    "box_cox",
+    "box_pierce",
+    "catch22_features",
+    "causality",
+    "causality_report",
+    "ceemdan",
+    "changepoints",
+    "changepoints_report",
+    "chaos_measures",
+    "christiano_fitzgerald",
+    "cointegration",
+    "combined_verdict",
+    "complexity",
+    "cross_correlation",
+    "cusum_stability",
+    "cwt_scalogram",
+    "dcca_coefficient",
+    "dfgls",
+    "distribution",
+    "distribution_report",
+    "durbin_watson",
+    "emd",
+    "filters",
+    "filters_report",
+    "fractal",
+    "fractal_dimension",
+    "fractal_report",
+    "garch",
+    "granger_causality",
+    "hodrick_prescott",
+    "hurst",
+    "iaaft_surrogate",
+    "kde_curve",
+    "kpss",
+    "lag_plot_pairs",
+    "ljung_box",
+    "markov_regimes",
+    "mfdfa",
+    "mstl_decompose",
+    "ndiffs",
+    "nonlinear",
+    "nonlinear_report",
+    "nsdiffs",
+    "pacf",
+    "pelt",
+    "periodogram",
+    "phillips_perron",
+    "qq_points",
+    "recurrence_quantification",
+    "rolling_volatility",
+    "seasonal_strength",
+    "seasonal_subseries",
+    "seasonality",
+    "seasonality_report",
+    "stationarity",
+    "stationarity_report",
+    "stl_decompose",
+    "summary",
+    "time_delay_embed",
+    "volatility",
+    "volatility_report",
+    "welch",
+    "zero_one_test",
+    "zivot_andrews",
+]