0
# Core Reconciliation
1
2
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.
3
4
## Capabilities
5
6
### HierarchicalReconciliation Class
7
8
Main orchestrator class that applies multiple reconciliation methods to hierarchical time series forecasts, ensuring coherent predictions across all levels of the hierarchy.
9
10
```python { .api }
11
class HierarchicalReconciliation:
12
"""
13
Hierarchical Reconciliation Class.
14
15
Efficiently fits multiple HierarchicalForecast methods for a collection of
16
time series and base predictions stored in pandas DataFrames.
17
"""
18
19
def __init__(self, reconcilers: list[HReconciler]):
20
"""
21
Initialize the reconciliation object.
22
23
Parameters:
24
- reconcilers: list of HReconciler instances
25
List of reconciliation methods to apply (e.g., BottomUp, TopDown, MinTrace)
26
"""
27
```
28
29
### Main Reconciliation Method
30
31
Core reconciliation functionality that applies all configured methods to base forecasts and returns coherent predictions.
32
33
```python { .api }
34
def reconcile(
35
self,
36
Y_hat_df: Frame,
37
S: Frame,
38
tags: dict[str, np.ndarray],
39
Y_df: Optional[Frame] = None,
40
level: Optional[list[int]] = None,
41
intervals_method: str = 'normality',
42
num_samples: int = -1,
43
seed: int = 0,
44
is_balanced: bool = False,
45
id_col: str = 'unique_id',
46
time_col: str = 'ds',
47
target_col: str = 'y',
48
id_time_col: str = 'temporal_id',
49
temporal: bool = False
50
) -> FrameT:
51
"""
52
Apply reconciliation methods to base forecasts.
53
54
Parameters:
55
- Y_hat_df: DataFrame with base forecasts containing id, time, and model columns
56
- S: DataFrame or scipy.sparse matrix representing the summing matrix
57
- tags: dict mapping hierarchy levels to series indices
58
- Y_df: DataFrame with historical data (required for some methods)
59
- level: list of confidence levels for prediction intervals (e.g., [80, 95])
60
- intervals_method: str, method for generating prediction intervals ('normality', 'bootstrap')
61
- num_samples: int, number of samples for probabilistic reconciliation (-1 for default)
62
- seed: int, random seed for reproducibility
63
- is_balanced: bool, whether the hierarchy is balanced
64
- id_col: str, name of the unique identifier column
65
- time_col: str, name of the time column
66
- target_col: str, name of the target variable column
67
- id_time_col: str, name of the temporal hierarchy identifier column
68
- temporal: bool, whether to perform temporal reconciliation
69
70
Returns:
71
DataFrame with reconciled forecasts including all method results
72
"""
73
```
74
75
### Bootstrap Reconciliation
76
77
Alternative reconciliation method using bootstrap sampling for uncertainty quantification in hierarchical forecasts.
78
79
```python { .api }
80
def bootstrap_reconcile(
81
self,
82
Y_hat_df: Frame,
83
S_df: Frame,
84
tags: dict[str, np.ndarray],
85
Y_df: Optional[Frame] = None,
86
level: Optional[list[int]] = None,
87
intervals_method: str = 'normality',
88
num_samples: int = -1,
89
num_seeds: int = 1,
90
id_col: str = 'unique_id',
91
time_col: str = 'ds',
92
target_col: str = 'y'
93
) -> FrameT:
94
"""
95
Perform bootstrap reconciliation for uncertainty estimation.
96
97
Parameters:
98
- Y_hat_df: DataFrame with base forecasts
99
- S_df: DataFrame representing the summing matrix
100
- tags: dict mapping hierarchy levels to series indices
101
- Y_df: DataFrame with historical data
102
- level: list of confidence levels for intervals
103
- intervals_method: str, method for interval generation
104
- num_samples: int, number of bootstrap samples
105
- num_seeds: int, number of bootstrap seeds
106
- id_col: str, unique identifier column name
107
- time_col: str, time column name
108
- target_col: str, target variable column name
109
110
Returns:
111
DataFrame with bootstrap reconciled forecasts
112
"""
113
```
114
115
## Usage Examples
116
117
### Basic Reconciliation
118
119
```python
120
import pandas as pd
121
from hierarchicalforecast import HierarchicalReconciliation
122
from hierarchicalforecast.methods import BottomUp, MinTrace
123
124
# Initialize reconcilers
125
reconcilers = [
126
BottomUp(),
127
MinTrace(method='ols')
128
]
129
130
# Create reconciliation object
131
hrec = HierarchicalReconciliation(reconcilers=reconcilers)
132
133
# Apply reconciliation
134
results = hrec.reconcile(
135
Y_hat_df=forecasts_df,
136
S=summing_matrix,
137
tags=hierarchy_tags,
138
Y_df=historical_data
139
)
140
```
141
142
### Reconciliation with Prediction Intervals
143
144
```python
145
# Generate reconciled forecasts with 80% and 95% prediction intervals
146
results = hrec.reconcile(
147
Y_hat_df=forecasts_df,
148
S=summing_matrix,
149
tags=hierarchy_tags,
150
Y_df=historical_data,
151
level=[80, 95],
152
intervals_method='normality',
153
seed=42
154
)
155
156
# Results will include columns like:
157
# - BottomUp
158
# - MinTrace
159
# - BottomUp-lo-80, BottomUp-hi-80
160
# - MinTrace-lo-80, MinTrace-hi-80
161
# etc.
162
```
163
164
### Bootstrap Reconciliation
165
166
```python
167
# Use bootstrap for uncertainty quantification
168
bootstrap_results = hrec.bootstrap_reconcile(
169
Y_hat_df=forecasts_df,
170
S_df=summing_matrix,
171
tags=hierarchy_tags,
172
Y_df=historical_data,
173
level=[90],
174
num_samples=1000,
175
num_seeds=10
176
)
177
```
178
179
## Attributes
180
181
After reconciliation, the `HierarchicalReconciliation` object provides access to execution metadata:
182
183
```python { .api }
184
# Execution times for each reconciliation method
185
hrec.execution_times: dict[str, float]
186
187
# Prediction interval column name mappings
188
hrec.level_names: dict[str, list[str]]
189
190
# Sample column name mappings
191
hrec.sample_names: dict[str, list[str]]
192
```