tessl/pypi-hierarchicalforecast

Hierarchical Methods Time series forecasting

—

Pending

Overview

Eval results

Files

Core Reconciliation

Name: tessl/pypi-hierarchicalforecast
Author: tessl

The core reconciliation functionality provides the main orchestration for applying multiple hierarchical reconciliation methods to base forecasts. The HierarchicalReconciliation class serves as the primary interface for coordinating different reconciliation algorithms and ensuring coherence across hierarchy levels.

Capabilities

HierarchicalReconciliation Class

Main orchestrator class that applies multiple reconciliation methods to hierarchical time series forecasts, ensuring coherent predictions across all levels of the hierarchy.

class HierarchicalReconciliation:
    """
    Hierarchical Reconciliation Class.
    
    Efficiently fits multiple HierarchicalForecast methods for a collection of 
    time series and base predictions stored in pandas DataFrames.
    """
    
    def __init__(self, reconcilers: list[HReconciler]):
        """
        Initialize the reconciliation object.
        
        Parameters:
        - reconcilers: list of HReconciler instances
            List of reconciliation methods to apply (e.g., BottomUp, TopDown, MinTrace)
        """

Main Reconciliation Method

Core reconciliation functionality that applies all configured methods to base forecasts and returns coherent predictions.

def reconcile(
    self,
    Y_hat_df: Frame,
    S: Frame,
    tags: dict[str, np.ndarray],
    Y_df: Optional[Frame] = None,
    level: Optional[list[int]] = None,
    intervals_method: str = 'normality',
    num_samples: int = -1,
    seed: int = 0,
    is_balanced: bool = False,
    id_col: str = 'unique_id',
    time_col: str = 'ds',
    target_col: str = 'y',
    id_time_col: str = 'temporal_id',
    temporal: bool = False
) -> FrameT:
    """
    Apply reconciliation methods to base forecasts.
    
    Parameters:
    - Y_hat_df: DataFrame with base forecasts containing id, time, and model columns
    - S: DataFrame or scipy.sparse matrix representing the summing matrix
    - tags: dict mapping hierarchy levels to series indices
    - Y_df: DataFrame with historical data (required for some methods)
    - level: list of confidence levels for prediction intervals (e.g., [80, 95])
    - intervals_method: str, method for generating prediction intervals ('normality', 'bootstrap')
    - num_samples: int, number of samples for probabilistic reconciliation (-1 for default)
    - seed: int, random seed for reproducibility
    - is_balanced: bool, whether the hierarchy is balanced
    - id_col: str, name of the unique identifier column
    - time_col: str, name of the time column
    - target_col: str, name of the target variable column
    - id_time_col: str, name of the temporal hierarchy identifier column
    - temporal: bool, whether to perform temporal reconciliation
    
    Returns:
    DataFrame with reconciled forecasts including all method results
    """

Bootstrap Reconciliation

Alternative reconciliation method using bootstrap sampling for uncertainty quantification in hierarchical forecasts.

def bootstrap_reconcile(
    self,
    Y_hat_df: Frame,
    S_df: Frame,
    tags: dict[str, np.ndarray],
    Y_df: Optional[Frame] = None,
    level: Optional[list[int]] = None,
    intervals_method: str = 'normality',
    num_samples: int = -1,
    num_seeds: int = 1,
    id_col: str = 'unique_id',
    time_col: str = 'ds',
    target_col: str = 'y'
) -> FrameT:
    """
    Perform bootstrap reconciliation for uncertainty estimation.
    
    Parameters:
    - Y_hat_df: DataFrame with base forecasts
    - S_df: DataFrame representing the summing matrix
    - tags: dict mapping hierarchy levels to series indices
    - Y_df: DataFrame with historical data
    - level: list of confidence levels for intervals
    - intervals_method: str, method for interval generation
    - num_samples: int, number of bootstrap samples
    - num_seeds: int, number of bootstrap seeds
    - id_col: str, unique identifier column name
    - time_col: str, time column name
    - target_col: str, target variable column name
    
    Returns:
    DataFrame with bootstrap reconciled forecasts
    """

Usage Examples

Basic Reconciliation

import pandas as pd
from hierarchicalforecast import HierarchicalReconciliation
from hierarchicalforecast.methods import BottomUp, MinTrace

# Initialize reconcilers
reconcilers = [
    BottomUp(),
    MinTrace(method='ols')
]

# Create reconciliation object
hrec = HierarchicalReconciliation(reconcilers=reconcilers)

# Apply reconciliation
results = hrec.reconcile(
    Y_hat_df=forecasts_df,
    S=summing_matrix,
    tags=hierarchy_tags,
    Y_df=historical_data
)

Reconciliation with Prediction Intervals

# Generate reconciled forecasts with 80% and 95% prediction intervals  
results = hrec.reconcile(
    Y_hat_df=forecasts_df,
    S=summing_matrix,
    tags=hierarchy_tags,
    Y_df=historical_data,
    level=[80, 95],
    intervals_method='normality',
    seed=42
)

# Results will include columns like:
# - BottomUp
# - MinTrace  
# - BottomUp-lo-80, BottomUp-hi-80
# - MinTrace-lo-80, MinTrace-hi-80
# etc.

Bootstrap Reconciliation

# Use bootstrap for uncertainty quantification
bootstrap_results = hrec.bootstrap_reconcile(
    Y_hat_df=forecasts_df,
    S_df=summing_matrix,
    tags=hierarchy_tags,
    Y_df=historical_data,
    level=[90],
    num_samples=1000,
    num_seeds=10
)

Attributes

After reconciliation, the HierarchicalReconciliation object provides access to execution metadata:

# Execution times for each reconciliation method
hrec.execution_times: dict[str, float]

# Prediction interval column name mappings
hrec.level_names: dict[str, list[str]]

# Sample column name mappings  
hrec.sample_names: dict[str, list[str]]

Install with Tessl CLI

npx tessl i tessl/pypi-hierarchicalforecast

docs

core-reconciliation.md

data-utilities.md

evaluation.md

index.md

probabilistic-methods.md

reconciliation-methods.md

visualization.md

tile.json

tessl/pypi-hierarchicalforecast