tsagentkit 1.0.2__py3-none-any.whl

tsagentkit/features/versioning.py

@@ -0,0 +1,203 @@
+"""Feature versioning and hashing for provenance tracking."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+
+@dataclass(frozen=True)
+class FeatureConfig:
+    """Configuration for feature engineering.
+
+    Attributes:
+        engine: Feature backend selection ("auto", "native", "tsfeatures")
+        lags: List of lag periods to create (e.g., [1, 7, 14])
+        calendar_features: List of calendar features to create
+                         (e.g., ["dayofweek", "month", "quarter", "year"])
+        rolling_windows: Dict mapping window sizes to aggregation functions
+                        (e.g., {7: ["mean", "std"], 30: ["mean"]})
+        known_covariates: List of column names for known covariates
+        observed_covariates: List of column names for observed covariates
+        include_intercept: Whether to include an intercept column (all 1s)
+        tsfeatures_features: Optional list of tsfeatures function names
+        tsfeatures_freq: Optional season length to pass to tsfeatures
+        tsfeatures_dict_freqs: Optional dict mapping pandas freq -> season length
+        allow_fallback: Allow fallback to native when tsfeatures is unavailable
+
+    Example:
+        >>> config = FeatureConfig(
+        ...     lags=[1, 7, 14],
+        ...     calendar_features=["dayofweek", "month"],
+        ...     rolling_windows={7: ["mean", "std"], 30: ["mean"]},
+        ...     known_covariates=["holiday"],
+        ...     observed_covariates=["promotion"],
+        ... )
+        >>> print(compute_feature_hash(config))
+        abc123def456...
+    """
+
+    engine: Literal["auto", "native", "tsfeatures"] = "auto"
+    lags: list[int] = field(default_factory=list)
+    calendar_features: list[str] = field(default_factory=list)
+    rolling_windows: dict[int, list[str]] = field(default_factory=dict)
+    known_covariates: list[str] = field(default_factory=list)
+    observed_covariates: list[str] = field(default_factory=list)
+    include_intercept: bool = False
+    tsfeatures_features: list[str] = field(default_factory=list)
+    tsfeatures_freq: int | None = None
+    tsfeatures_dict_freqs: dict[str, int] = field(default_factory=dict)
+    allow_fallback: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate configuration after creation."""
+        if self.engine not in {"auto", "native", "tsfeatures"}:
+            raise ValueError(f"Invalid feature engine: {self.engine}")
+
+        # Validate lags are positive integers
+        for lag in self.lags:
+            if not isinstance(lag, int) or lag < 1:
+                raise ValueError(f"Lags must be positive integers, got {lag}")
+
+        # Validate calendar features
+        valid_calendar = {
+            "dayofweek", "month", "quarter", "year", "dayofmonth",
+            "dayofyear", "weekofyear", "hour", "minute", "is_month_start",
+            "is_month_end", "is_quarter_start", "is_quarter_end",
+        }
+        invalid = set(self.calendar_features) - valid_calendar
+        if invalid:
+            raise ValueError(f"Invalid calendar features: {invalid}. Valid: {valid_calendar}")
+
+        # Validate rolling aggregations
+        valid_aggs = {"mean", "std", "min", "max", "sum", "median"}
+        for window, aggs in self.rolling_windows.items():
+            if not isinstance(window, int) or window < 1:
+                raise ValueError(f"Window sizes must be positive integers, got {window}")
+            invalid_aggs = set(aggs) - valid_aggs
+            if invalid_aggs:
+                raise ValueError(f"Invalid aggregations: {invalid_aggs}. Valid: {valid_aggs}")
+
+        # Check for overlap in covariates
+        overlap = set(self.known_covariates) & set(self.observed_covariates)
+        if overlap:
+            raise ValueError(f"Covariates cannot be both known and observed: {overlap}")
+
+        if self.tsfeatures_freq is not None and self.tsfeatures_freq < 1:
+            raise ValueError("tsfeatures_freq must be a positive integer when provided")
+
+        for key, value in self.tsfeatures_dict_freqs.items():
+            if not isinstance(value, int) or value < 1:
+                raise ValueError(
+                    f"tsfeatures_dict_freqs must map to positive integers, got {key}={value}"
+                )
+
+
+def compute_feature_hash(config: FeatureConfig) -> str:
+    """Compute deterministic hash of feature configuration.
+
+    The hash includes all feature configuration parameters to ensure
+    that any change to the feature engineering setup results in a
+    different hash for provenance tracking.
+
+    Args:
+        config: Feature configuration to hash
+
+    Returns:
+        SHA-256 hash string (truncated to 16 characters)
+
+    Example:
+        >>> config = FeatureConfig(lags=[1, 7], calendar_features=["dayofweek"])
+        >>> h = compute_feature_hash(config)
+        >>> len(h)
+        16
+    """
+    # Build normalized configuration dict
+    config_dict = {
+        "engine": config.engine,
+        "lags": sorted(config.lags) if config.lags else [],
+        "calendar": sorted(config.calendar_features),
+        "rolling": [
+            {"window": w, "aggs": sorted(a)}
+            for w, a in sorted(config.rolling_windows.items())
+        ],
+        "known_covariates": sorted(config.known_covariates),
+        "observed_covariates": sorted(config.observed_covariates),
+        "include_intercept": config.include_intercept,
+        "tsfeatures_features": sorted(config.tsfeatures_features),
+        "tsfeatures_freq": config.tsfeatures_freq,
+        "tsfeatures_dict_freqs": {
+            k: config.tsfeatures_dict_freqs[k]
+            for k in sorted(config.tsfeatures_dict_freqs)
+        },
+        "allow_fallback": config.allow_fallback,
+    }
+
+    # Create deterministic JSON representation
+    json_str = json.dumps(config_dict, sort_keys=True, separators=(",", ":"))
+
+    # Compute hash
+    return hashlib.sha256(json_str.encode()).hexdigest()[:16]
+
+
+def configs_equal(config1: FeatureConfig, config2: FeatureConfig) -> bool:
+    """Check if two feature configurations are equivalent.
+
+    Args:
+        config1: First configuration
+        config2: Second configuration
+
+    Returns:
+        True if configurations produce identical features
+    """
+    return compute_feature_hash(config1) == compute_feature_hash(config2)
+
+
+def config_to_dict(config: FeatureConfig) -> dict[str, Any]:
+    """Convert feature config to dictionary for serialization.
+
+    Args:
+        config: Feature configuration
+
+    Returns:
+        Dictionary representation
+    """
+    return {
+        "engine": config.engine,
+        "lags": config.lags,
+        "calendar_features": config.calendar_features,
+        "rolling_windows": config.rolling_windows,
+        "known_covariates": config.known_covariates,
+        "observed_covariates": config.observed_covariates,
+        "include_intercept": config.include_intercept,
+        "tsfeatures_features": config.tsfeatures_features,
+        "tsfeatures_freq": config.tsfeatures_freq,
+        "tsfeatures_dict_freqs": config.tsfeatures_dict_freqs,
+        "allow_fallback": config.allow_fallback,
+    }
+
+
+def config_from_dict(data: dict[str, Any]) -> FeatureConfig:
+    """Create feature config from dictionary.
+
+    Args:
+        data: Dictionary with configuration values
+
+    Returns:
+        FeatureConfig instance
+    """
+    return FeatureConfig(
+        engine=data.get("engine", "auto"),
+        lags=data.get("lags", []),
+        calendar_features=data.get("calendar_features", []),
+        rolling_windows=data.get("rolling_windows", {}),
+        known_covariates=data.get("known_covariates", []),
+        observed_covariates=data.get("observed_covariates", []),
+        include_intercept=data.get("include_intercept", False),
+        tsfeatures_features=data.get("tsfeatures_features", []),
+        tsfeatures_freq=data.get("tsfeatures_freq"),
+        tsfeatures_dict_freqs=data.get("tsfeatures_dict_freqs", {}),
+        allow_fallback=data.get("allow_fallback", True),
+    )

tsagentkit/hierarchy/__init__.py

@@ -0,0 +1,39 @@
+"""Hierarchical time series forecasting and reconciliation.
+
+This module provides tools for working with hierarchical time series data,
+including structure definition, aggregation matrix operations, and multiple
+reconciliation methods (bottom-up, top-down, middle-out, OLS, MinT).
+
+Example:
+    >>> from tsagentkit.hierarchy import HierarchyStructure, Reconciler
+    >>> from tsagentkit.hierarchy import ReconciliationMethod
+    >>>
+    >>> # Define hierarchy
+    >>> structure = HierarchyStructure.from_dataframe(
+    ...     df=sales_data,
+    ...     hierarchy_columns=["region", "state", "store"]
+    ... )
+    >>>
+    >>> # Reconcile forecasts
+    >>> reconciler = Reconciler(ReconciliationMethod.MIN_TRACE, structure)
+    >>> reconciled = reconciler.reconcile(base_forecasts, residuals=residuals)
+"""
+
+from __future__ import annotations
+
+from .evaluator import CoherenceViolation, HierarchyEvaluationReport, HierarchyEvaluator
+from .reconciliation import Reconciler, ReconciliationMethod, reconcile_forecasts
+from .structure import HierarchyStructure
+
+__all__ = [
+    # Structure
+    "HierarchyStructure",
+    # Reconciliation
+    "Reconciler",
+    "ReconciliationMethod",
+    "reconcile_forecasts",
+    # Evaluation
+    "HierarchyEvaluator",
+    "HierarchyEvaluationReport",
+    "CoherenceViolation",
+]

tsagentkit/hierarchy/aggregation.py

@@ -0,0 +1,62 @@
+"""Deprecated aggregation helpers.
+
+This module previously contained projection-matrix implementations for
+hierarchical reconciliation. Those algorithms are now delegated to
+`hierarchicalforecast` to keep this package as a thin adapter.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+from .structure import HierarchyStructure
+
+_DEPRECATION_MESSAGE = (
+    "tsagentkit.hierarchy.aggregation is deprecated. "
+    "Use hierarchicalforecast methods directly instead."
+)
+
+
+def _deprecated(name: str) -> None:
+    warnings.warn(
+        f"{name} is deprecated. {_DEPRECATION_MESSAGE}",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+
+def create_bottom_up_matrix(structure: HierarchyStructure) -> np.ndarray:  # pragma: no cover
+    _deprecated("create_bottom_up_matrix")
+    raise NotImplementedError(_DEPRECATION_MESSAGE)
+
+
+def create_top_down_matrix(  # pragma: no cover
+    structure: HierarchyStructure,
+    proportions: dict[str, float] | None = None,
+    historical_data: np.ndarray | None = None,
+) -> np.ndarray:
+    _deprecated("create_top_down_matrix")
+    raise NotImplementedError(_DEPRECATION_MESSAGE)
+
+
+def create_middle_out_matrix(  # pragma: no cover
+    structure: HierarchyStructure,
+    middle_level: int,
+) -> np.ndarray:
+    _deprecated("create_middle_out_matrix")
+    raise NotImplementedError(_DEPRECATION_MESSAGE)
+
+
+def create_ols_matrix(structure: HierarchyStructure) -> np.ndarray:  # pragma: no cover
+    _deprecated("create_ols_matrix")
+    raise NotImplementedError(_DEPRECATION_MESSAGE)
+
+
+def create_wls_matrix(  # pragma: no cover
+    structure: HierarchyStructure,
+    weights: np.ndarray,
+) -> np.ndarray:
+    _deprecated("create_wls_matrix")
+    raise NotImplementedError(_DEPRECATION_MESSAGE)

tsagentkit/hierarchy/evaluator.py

@@ -0,0 +1,400 @@
+"""Hierarchy-aware evaluation metrics and coherence checking.
+
+Provides tools to evaluate hierarchical forecast quality and detect
+coherence violations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    from .structure import HierarchyStructure
+
+
+@dataclass(frozen=True)
+class CoherenceViolation:
+    """Single coherence violation record.
+
+    Records when forecasts violate the hierarchical aggregation constraint
+    (i.e., children don't sum to parent).
+
+    Attributes:
+        parent_node: Name of the parent node
+        child_nodes: List of child node names
+        expected_value: Expected value (sum of children)
+        actual_value: Actual value (parent forecast)
+        difference: Absolute difference between expected and actual
+        timestamp: Timestamp of the violation
+    """
+
+    parent_node: str
+    child_nodes: list[str]
+    expected_value: float
+    actual_value: float
+    difference: float
+    timestamp: str
+
+
+@dataclass(frozen=True)
+class HierarchyEvaluationReport:
+    """Evaluation report for hierarchical forecasts.
+
+    Contains metrics and diagnostics for hierarchical forecast quality.
+
+    Attributes:
+        level_metrics: Metrics aggregated by hierarchy level
+        coherence_violations: List of coherence violations found
+        coherence_score: Overall coherence score (0-1, higher is better)
+        reconciliation_improvement: Improvement vs base forecasts
+        total_violations: Total number of violations
+        violation_rate: Proportion of forecasts with violations
+    """
+
+    level_metrics: dict[int, dict[str, float]] = field(default_factory=dict)
+    coherence_violations: list[CoherenceViolation] = field(default_factory=list)
+    coherence_score: float = 0.0
+    reconciliation_improvement: dict[str, float] = field(default_factory=dict)
+    total_violations: int = 0
+    violation_rate: float = 0.0
+
+    def to_dict(self) -> dict:
+        """Convert report to dictionary."""
+        return {
+            "level_metrics": self.level_metrics,
+            "coherence_violations": [
+                {
+                    "parent_node": v.parent_node,
+                    "child_nodes": v.child_nodes,
+                    "expected_value": v.expected_value,
+                    "actual_value": v.actual_value,
+                    "difference": v.difference,
+                    "timestamp": v.timestamp,
+                }
+                for v in self.coherence_violations
+            ],
+            "coherence_score": self.coherence_score,
+            "reconciliation_improvement": self.reconciliation_improvement,
+            "total_violations": self.total_violations,
+            "violation_rate": self.violation_rate,
+        }
+
+
+class HierarchyEvaluator:
+    """Evaluate hierarchical forecast quality and coherence.
+
+    Provides methods to compute hierarchical metrics and detect
+    coherence violations.
+
+    Example:
+        >>> evaluator = HierarchyEvaluator(hierarchy_structure)
+        >>> report = evaluator.evaluate(forecasts, actuals)
+        >>> print(f"Coherence score: {report.coherence_score:.3f}")
+        Coherence score: 0.998
+    """
+
+    def __init__(self, structure: HierarchyStructure):
+        """Initialize evaluator.
+
+        Args:
+            structure: Hierarchy structure
+        """
+        self.structure = structure
+
+    def evaluate(
+        self,
+        forecasts: pd.DataFrame,
+        actuals: pd.DataFrame | None = None,
+        tolerance: float = 1e-6,
+    ) -> HierarchyEvaluationReport:
+        """Evaluate hierarchical forecasts.
+
+        Computes standard forecast metrics per level and checks coherence.
+
+        Args:
+            forecasts: Forecast DataFrame with columns [unique_id, ds, yhat]
+            actuals: Optional actual values for accuracy metrics
+            tolerance: Tolerance for coherence violations
+
+        Returns:
+            HierarchyEvaluationReport with metrics and violations
+        """
+        # Compute per-level metrics if actuals provided
+        level_metrics = {}
+        if actuals is not None:
+            level_metrics = self._compute_level_metrics(forecasts, actuals)
+
+        # Detect coherence violations
+        violations = self._detect_violations(forecasts, tolerance)
+
+        # Compute coherence score
+        coherence_score = self._compute_coherence_score(forecasts, tolerance)
+
+        # Compute violation rate
+        total_checks = self._count_total_checks(forecasts)
+        violation_rate = len(violations) / max(total_checks, 1)
+
+        return HierarchyEvaluationReport(
+            level_metrics=level_metrics,
+            coherence_violations=violations,
+            coherence_score=coherence_score,
+            total_violations=len(violations),
+            violation_rate=violation_rate,
+        )
+
+    def _compute_level_metrics(
+        self,
+        forecasts: pd.DataFrame,
+        actuals: pd.DataFrame,
+    ) -> dict[int, dict[str, float]]:
+        """Compute metrics aggregated by hierarchy level.
+
+        Args:
+            forecasts: Forecast DataFrame
+            actuals: Actual values DataFrame
+
+        Returns:
+            Dictionary mapping level to metrics dict
+        """
+        metrics_by_level: dict[int, dict[str, list[float]]] = {}
+
+        # Merge forecasts with actuals
+        merged = forecasts.merge(
+            actuals,
+            on=["unique_id", "ds"],
+            suffixes=("_forecast", "_actual"),
+        )
+
+        # Compute metrics per series
+        for _, row in merged.iterrows():
+            uid = row["unique_id"]
+            if uid not in self.structure.all_nodes:
+                continue
+
+            level = self.structure.get_level(uid)
+            if level not in metrics_by_level:
+                metrics_by_level[level] = {"mae": [], "mape": [], "rmse": []}
+
+            actual = row.get("y_actual", row.get("y", 0))
+            forecast = row["yhat"]
+            error = forecast - actual
+
+            metrics_by_level[level]["mae"].append(abs(error))
+            metrics_by_level[level]["rmse"].append(error ** 2)
+            if actual != 0:
+                metrics_by_level[level]["mape"].append(abs(error / actual) * 100)
+
+        # Aggregate
+        result = {}
+        for level, metrics in metrics_by_level.items():
+            result[level] = {
+                "mae": np.mean(metrics["mae"]) if metrics["mae"] else 0,
+                "rmse": np.sqrt(np.mean(metrics["rmse"])) if metrics["rmse"] else 0,
+                "mape": np.mean(metrics["mape"]) if metrics["mape"] else 0,
+                "count": len(metrics["mae"]),
+            }
+
+        return result
+
+    def _detect_violations(
+        self,
+        forecasts: pd.DataFrame,
+        tolerance: float = 1e-6,
+    ) -> list[CoherenceViolation]:
+        """Detect where forecasts violate hierarchical coherence.
+
+        A coherence violation occurs when the sum of child forecasts
+        doesn't equal the parent forecast (within tolerance).
+
+        Args:
+            forecasts: Forecast DataFrame
+            tolerance: Numerical tolerance for violations
+
+        Returns:
+            List of coherence violations
+        """
+        violations = []
+
+        # Pivot to wide format for easier computation
+        pivot = forecasts.pivot(index="unique_id", columns="ds", values="yhat")
+
+        for parent, children in self.structure.aggregation_graph.items():
+            if parent not in pivot.index:
+                continue
+
+            parent_forecast = pivot.loc[parent]
+
+            # Sum children forecasts
+            available_children = [c for c in children if c in pivot.index]
+            if not available_children:
+                continue
+
+            children_sum = pivot.loc[available_children].sum()
+
+            # Check for violations at each time point
+            for ds in parent_forecast.index:
+                parent_val = parent_forecast[ds]
+                children_val = children_sum[ds]
+                diff = abs(parent_val - children_val)
+
+                if diff > tolerance:
+                    violations.append(
+                        CoherenceViolation(
+                            parent_node=parent,
+                            child_nodes=available_children,
+                            expected_value=float(children_val),
+                            actual_value=float(parent_val),
+                            difference=float(diff),
+                            timestamp=str(ds),
+                        )
+                    )
+
+        return violations
+
+    def _compute_coherence_score(
+        self,
+        forecasts: pd.DataFrame,
+        tolerance: float = 1e-6,
+    ) -> float:
+        """Compute overall coherence score.
+
+        Score is 1.0 if perfectly coherent, decreases with violations.
+
+        Args:
+            forecasts: Forecast DataFrame
+            tolerance: Numerical tolerance
+
+        Returns:
+            Coherence score between 0 and 1
+        """
+        pivot = forecasts.pivot(index="unique_id", columns="ds", values="yhat")
+
+        total_abs_sum = 0.0
+        total_violation = 0.0
+
+        for parent, children in self.structure.aggregation_graph.items():
+            if parent not in pivot.index:
+                continue
+
+            parent_forecast = pivot.loc[parent]
+            available_children = [c for c in children if c in pivot.index]
+
+            if not available_children:
+                continue
+
+            children_sum = pivot.loc[available_children].sum()
+
+            for ds in parent_forecast.index:
+                parent_val = parent_forecast[ds]
+                children_val = children_sum[ds]
+
+                total_abs_sum += abs(parent_val)
+                violation = abs(parent_val - children_val)
+
+                if violation > tolerance:
+                    total_violation += violation
+
+        if total_abs_sum == 0:
+            return 1.0
+
+        # Score decreases as violation magnitude increases
+        return max(0.0, 1.0 - (total_violation / total_abs_sum))
+
+    def _count_total_checks(self, forecasts: pd.DataFrame) -> int:
+        """Count total number of coherence checks performed.
+
+        Args:
+            forecasts: Forecast DataFrame
+
+        Returns:
+            Total number of parent-timestamp pairs checked
+        """
+        pivot = forecasts.pivot(index="unique_id", columns="ds", values="yhat")
+
+        count = 0
+        for parent, children in self.structure.aggregation_graph.items():
+            if parent not in pivot.index:
+                continue
+
+            available_children = [c for c in children if c in pivot.index]
+            if available_children:
+                count += len(pivot.columns)
+
+        return count
+
+    def compute_improvement(
+        self,
+        base_forecasts: pd.DataFrame,
+        reconciled_forecasts: pd.DataFrame,
+        actuals: pd.DataFrame,
+    ) -> dict[str, float]:
+        """Compute improvement of reconciled vs base forecasts.
+
+        Args:
+            base_forecasts: Base (unreconciled) forecasts
+            reconciled_forecasts: Reconciled forecasts
+            actuals: Actual values
+
+        Returns:
+            Dictionary with improvement metrics
+        """
+        base_metrics = self._compute_overall_metrics(base_forecasts, actuals)
+        reconciled_metrics = self._compute_overall_metrics(
+            reconciled_forecasts, actuals
+        )
+
+        improvement = {}
+        for metric in ["mae", "rmse", "mape"]:
+            if metric in base_metrics and base_metrics[metric] > 0:
+                improvement[metric] = (
+                    (base_metrics[metric] - reconciled_metrics[metric])
+                    / base_metrics[metric]
+                ) * 100
+            else:
+                improvement[metric] = 0.0
+
+        return improvement
+
+    def _compute_overall_metrics(
+        self,
+        forecasts: pd.DataFrame,
+        actuals: pd.DataFrame,
+    ) -> dict[str, float]:
+        """Compute overall metrics for forecasts.
+
+        Args:
+            forecasts: Forecast DataFrame
+            actuals: Actual values DataFrame
+
+        Returns:
+            Dictionary of metrics
+        """
+        merged = forecasts.merge(
+            actuals,
+            on=["unique_id", "ds"],
+            suffixes=("_forecast", "_actual"),
+        )
+
+        if len(merged) == 0:
+            return {"mae": 0, "rmse": 0, "mape": 0}
+
+        actual_col = "y_actual" if "y_actual" in merged.columns else "y"
+        errors = merged["yhat"] - merged[actual_col]
+
+        mae = np.mean(np.abs(errors))
+        rmse = np.sqrt(np.mean(errors ** 2))
+
+        # Compute MAPE only for non-zero actuals
+        non_zero_mask = merged[actual_col] != 0
+        if non_zero_mask.any():
+            mape = np.mean(
+                np.abs(errors[non_zero_mask] / merged.loc[non_zero_mask, actual_col])
+            ) * 100
+        else:
+            mape = 0.0
+
+        return {"mae": mae, "rmse": rmse, "mape": mape}