[FEAT] Covariance Estimation Module & Cross-Temporal Reconciliation

[elephaint]

Summary

Introduces a dedicated covariance estimation module with a pluggable registry, and adds support for temporal and cross-temporal forecast reconciliation methods.

New Features

Covariance Module (hierarchicalforecast/covariance.py)

• New covariance.py module with a registry-based architecture for covariance estimation methods
• register_covariance() — register custom covariance methods
• estimate_covariance() — unified entry point for all covariance estimation
• list_covariance_methods() / is_diagonal_method() — introspection helpers
• Cross-sectional methods: ols, wls_struct, wls_var, sam/mint_cov, shr/mint_shrink, bu, oasd
• Temporal methods (Athanasopoulos et al. 2017, Nystrup et al. 2020): wlsv, wlsh, acov, strar1, sar1, har1
• Cross-temporal methods (Di Fonzo & Girolimetto 2023): csstr, testr, bdshr, bdsam, sshr, ssam, hshr, hsam, hbshr, hbsam, bshr, bsam

Cross-Temporal Reconciliation (hierarchicalforecast/core.py)

• reconcile() now accepts cross_temporal=True with S_cs_df and S_te_df to build S_ct = S_cs ⊗ S_te automatically
• method_kwargs parameter for passing extra arguments to covariance estimators
• Auto-derives agg_order from the temporal summing matrix when temporal=True
• Removed artificial restriction blocking insample methods from temporal reconciliation

Utilities (hierarchicalforecast/utils.py)

• New build_cross_temporal_S() — constructs the cross-temporal summing matrix via Kronecker product with proper bottom-level reordering

Changes

MinTrace Refactor (hierarchicalforecast/methods.py)

• MinTrace._get_PW_matrices() now delegates covariance estimation to the new covariance module instead of inline logic
• Accepts method_kwargs for forwarding temporal/cross-temporal parameters
• Validates against the full registry of available methods
• Added shr alias support alongside mint_shrink

C++ Backend (src/reconciliation.cpp)

• Performance optimization in shrunk_covariance_ss_with_nans: thread-local vectors instead of per-pair heap allocations
• Input validation for set_num_threads(n) (must be >= 1)

Tests

• tests/test_covariance.py — 1356 lines of new tests covering all covariance methods (cross-sectional, temporal, cross-temporal), the registry API, edge cases, and NaN handling
• tests/test_methods.py — Extended with tests for new method names and temporal/cross-temporal reconciliation through MinTrace
• tests/test_core.py — End-to-end temporal reconciliation tests with insample data, parametrized across pandas/polars

Stats

• +3,674 lines added, -180 lines removed across 10 files

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB