module hierarchicalforecast.methods


class HReconciler


method fit

fit(*args, **kwargs)

method fit_predict

fit_predict(*args, **kwargs)

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class BottomUp

Bottom Up Reconciliation Class. The most basic hierarchical reconciliation is performed using an Bottom-Up strategy. It was proposed for the first time by Orcutt in 1968. The corresponding hierarchical โ€œprojectionโ€ matrix is defined as: PBU=[0[b],[a]โ€…โ€Šโˆฃโ€…โ€ŠI[b][b]]\mathbf{P}_{\text{BU}} = [\mathbf{0}_{\mathrm{[b],[a]}}\;|\;\mathbf{I}_{\mathrm{[b][b]}}] Args: None References:
  • [Orcutt, G.H., Watts, H.W., & Edwards, J.B.(1968). โ€œData aggregation and information lossโ€. The American
  • Economic Review, 58 , 773(787)](http: //www.jstor.org/stable/1815532).

method fit

fit(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
Bottom Up Fit Method. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • idx_bottom (np.ndarray): Indices corresponding to the bottom level of S, size (bottom).
  • y_insample (Optional[np.ndarray], optional): In-sample values of size (base, horizon). Default is None.
  • y_hat_insample (Optional[np.ndarray], optional): In-sample forecast values of size (base, horizon). Default is None.
  • sigmah (Optional[np.ndarray], optional): Estimated standard deviation of the conditional marginal distribution. Default is None.
  • intervals_method (Optional[str], optional): Sampler for prediction intervals, one of normality, bootstrap, permbu. Default is None.
  • num_samples (Optional[int], optional): Number of samples for probabilistic coherent distribution. Default is None.
  • seed (Optional[int], optional): Seed for reproducibility. Default is None.
  • tags (Optional[dict[str, np.ndarray]], optional): Tags for hierarchical structure. Default is None.
Returns:
  • BottomUp: object, fitted reconciler.

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
BottomUp Reconciliation Method. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • idx_bottom (np.ndarray): Indices corresponding to the bottom level of S, size (bottom).
  • y_insample (Optional[np.ndarray], optional): In-sample values of size (base, insample_size). Default is None.
  • y_hat_insample (Optional[np.ndarray], optional): In-sample forecast values of size (base, insample_size). Default is None.
  • sigmah (Optional[np.ndarray], optional): Estimated standard deviation of the conditional marginal distribution. Default is None.
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
  • intervals_method (Optional[str], optional): Sampler for prediction intervals, one of normality, bootstrap, permbu. Default is None.
  • num_samples (Optional[int], optional): Number of samples for probabilistic coherent distribution. Default is None.
  • seed (Optional[int], optional): Seed for reproducibility. Default is None.
  • tags (Optional[dict[str, np.ndarray]], optional): Tags for hierarchical structure. Default is None.
Returns:
  • dict: y_tilde: Reconciliated y_hat using the Bottom Up approach.

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class BottomUpSparse

BottomUpSparse Reconciliation Class. This is the implementation of a Bottom Up reconciliation using the sparse matrix approach. It works much more efficient on datasets with many time series. [makoren: At least I hope so, I only checked up until ~20k time series, and thereโ€™s no real improvement, it would be great to check for smth like 1M time series, where the dense S matrix really stops fitting in memory] See the parent class for more details.

method fit

fit(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
Bottom Up Fit Method. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • idx_bottom (np.ndarray): Indices corresponding to the bottom level of S, size (bottom).
  • y_insample (Optional[np.ndarray], optional): In-sample values of size (base, horizon). Default is None.
  • y_hat_insample (Optional[np.ndarray], optional): In-sample forecast values of size (base, horizon). Default is None.
  • sigmah (Optional[np.ndarray], optional): Estimated standard deviation of the conditional marginal distribution. Default is None.
  • intervals_method (Optional[str], optional): Sampler for prediction intervals, one of normality, bootstrap, permbu. Default is None.
  • num_samples (Optional[int], optional): Number of samples for probabilistic coherent distribution. Default is None.
  • seed (Optional[int], optional): Seed for reproducibility. Default is None.
  • tags (Optional[dict[str, np.ndarray]], optional): Tags for hierarchical structure. Default is None.
Returns:
  • BottomUp: object, fitted reconciler.

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
BottomUp Reconciliation Method. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • idx_bottom (np.ndarray): Indices corresponding to the bottom level of S, size (bottom).
  • y_insample (Optional[np.ndarray], optional): In-sample values of size (base, insample_size). Default is None.
  • y_hat_insample (Optional[np.ndarray], optional): In-sample forecast values of size (base, insample_size). Default is None.
  • sigmah (Optional[np.ndarray], optional): Estimated standard deviation of the conditional marginal distribution. Default is None.
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
  • intervals_method (Optional[str], optional): Sampler for prediction intervals, one of normality, bootstrap, permbu. Default is None.
  • num_samples (Optional[int], optional): Number of samples for probabilistic coherent distribution. Default is None.
  • seed (Optional[int], optional): Seed for reproducibility. Default is None.
  • tags (Optional[dict[str, np.ndarray]], optional): Tags for hierarchical structure. Default is None.
Returns:
  • dict: y_tilde: Reconciliated y_hat using the Bottom Up approach.

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class TopDown

Top Down Reconciliation Class. The Top Down hierarchical reconciliation method, distributes the total aggregate predictions and decomposes it down the hierarchy using proportions p[b]\mathbf{p}_{\mathrm{[b]}} that can be actual historical values or estimated. P=[p[b]โ€…โ€Šโˆฃโ€…โ€Š0[b][a,bโ€…โ€Šโˆ’1]]\mathbf{P}=[\mathbf{p}_{\mathrm{[b]}}\;|\;\mathbf{0}_{\mathrm{[b][a,b\;-1]}}] Args:
  • method: One of forecast_proportions, average_proportions and proportion_averages.
References:
  • [CW. Gross (1990). โ€œDisaggregation methods to expedite product line forecastingโ€. Journal of Forecasting, 9 , 233โ€“254.
  • doi: 10.1002/for.3980090304](https://onlinelibrary.wiley.com/doi/abs/10.1002/for.3980090304).
    • [G. Fliedner (1999). โ€œAn investigation of aggregate variable time series forecast strategies with specific subaggregate time series statistical correlationโ€. Computers and Operations Research, 26 , 1133โ€“1149.
  • doi: 10.1016/S0305-0548(99)00017-9](https://doi.org/10.1016/S0305-0548(99)00017-9).

method __init__

__init__(method: str)

method fit

fit(
    S,
    y_hat,
    y_insample: ndarray,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None,
    idx_bottom: Optional[ndarray] = None
)
TopDown Fit Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • y_insample: Insample values of size (base, insample_size). Optional for forecast_proportions method.
  • y_hat_insample: Insample forecast values of size (base, insample_size). Optional for forecast_proportions method.
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • interval_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
Returns:
  • self: object, fitted reconciler.

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    tags: dict[str, ndarray],
    idx_bottom: ndarray = None,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None
)
Top Down Reconciliation Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • tags: Each key is a level and each value its S indices.
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
  • y_insample: Insample values of size (base, insample_size). Optional for forecast_proportions method.
  • y_hat_insample: Insample forecast values of size (base, insample_size). Optional for forecast_proportions method.
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • level: float list 0-100, confidence levels for prediction intervals.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
Returns:
  • y_tilde: Reconciliated y_hat using the Top Down approach.

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class TopDownSparse

TopDownSparse Reconciliation Class. This is an implementation of top-down reconciliation using the sparse matrix approach. It works much more efficiently on data sets with many time series. See the parent class for more details.

method __init__

__init__(method: str)

method fit

fit(
    S,
    y_hat,
    y_insample: ndarray,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None,
    idx_bottom: Optional[ndarray] = None
)
TopDown Fit Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • y_insample: Insample values of size (base, insample_size). Optional for forecast_proportions method.
  • y_hat_insample: Insample forecast values of size (base, insample_size). Optional for forecast_proportions method.
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • interval_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
Returns:
  • self: object, fitted reconciler.

method fit_predict

fit_predict(
    S: csr_matrix,
    y_hat: ndarray,
    tags: dict[str, ndarray],
    idx_bottom: ndarray = None,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None
) โ†’ dict[str, ndarray]

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class MiddleOut

Middle Out Reconciliation Class. This method is only available for strictly hierarchical structures. It anchors the base predictions in a middle level. The levels above the base predictions use the Bottom-Up approach, while the levels below use a Top-Down. Args:
  • middle_level: Middle level.
  • top_down_method: One of forecast_proportions, average_proportions and proportion_averages.
References:
  • [Hyndman, R.J., & Athanasopoulos, G. (2021). โ€œForecasting: principles and practice, 3rd edition:
  • Chapter 11: Forecasting hierarchical and grouped series.โ€. OTexts: Melbourne, Australia. OTexts.com/fpp3
  • Accessed on July 2022.](https: //otexts.com/fpp3/hierarchical.html)

method __init__

__init__(middle_level: str, top_down_method: str)

method fit

fit(**kwargs)

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    tags: dict[str, ndarray],
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None
)
Middle Out Reconciliation Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • tags: Each key is a level and each value its S indices.
  • y_insample: Insample values of size (base, insample_size). Only used for forecast_proportions
  • y_hat_insample: In-sample forecast values of size (base, insample_size).
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • level: float list 0-100, confidence levels for prediction intervals.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
Returns:
  • y_tilde: Reconciliated y_hat using the Middle Out approach.

method predict

predict(**kwargs)

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class MiddleOutSparse

MiddleOutSparse Reconciliation Class. This is an implementation of middle-out reconciliation using the sparse matrix approach. It works much more efficiently on data sets with many time series. See the parent class for more details.

method __init__

__init__(middle_level: str, top_down_method: str)

method fit

fit(**kwargs)

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    tags: dict[str, ndarray],
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None
) โ†’ dict[str, ndarray]

method predict

predict(**kwargs)

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class MinTrace

MinTrace Reconciliation Class. This reconciliation algorithm proposed by Wickramasuriya et al. depends on a generalized least squares estimator and an estimator of the covariance matrix of the coherency errors Wh\mathbf{W}_{h}. The Min Trace algorithm minimizes the squared errors for the coherent forecasts under an unbiasedness assumption; the solution has a closed form.
PMinT=(SโŠบWhS)โˆ’1SโŠบWhโˆ’1\mathbf{P}_{\text{MinT}}=\left(\mathbf{S}^{\intercal}\mathbf{W}_{h}\mathbf{S}\right)^{-1} \mathbf{S}^{\intercal}\mathbf{W}^{-1}_{h} Args:
  • method: str, one of ols, wls_struct, wls_var, mint_shrink, mint_cov.
  • nonnegative: bool, reconciled forecasts should be nonnegative?
  • mint_shr_ridge: float=2e-8, ridge numeric protection to MinTrace-shr covariance estimator.
  • num_threads: int=1, number of threads to use for solving the optimization problems (when nonnegative=True).
References:
  • [Wickramasuriya, S. L., Athanasopoulos, G., & Hyndman, R. J. (2019). โ€œOptimal forecast reconciliation for hierarchical and grouped time series through trace minimizationโ€. Journal of the American Statistical Association,
  • 114 , 804โ€“819. doi: 10.1080/01621459.2018.1448825.](https://robjhyndman.com/publications/mint/).
    • [Wickramasuriya, S.L., Turlach, B.A. & Hyndman, R.J. (2020). โ€œOptimal non-negative forecast reconciliationโ€. Stat Comput 30, 1167โ€“1182,
  • https: //doi.org/10.1007/s11222-020-09930-0](https://robjhyndman.com/publications/nnmint/).

method __init__

__init__(
    method: str,
    nonnegative: bool = False,
    mint_shr_ridge: Optional[float] = 2e-08,
    num_threads: int = 1
)

method fit

fit(
    S,
    y_hat,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None,
    idx_bottom: Optional[ndarray] = None
)
MinTrace Fit Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • y_insample: Insample values of size (base, insample_size). Only used with โ€œwls_varโ€, โ€œmint_covโ€, โ€œmint_shrinkโ€.
  • y_hat_insample: Insample forecast values of size (base, insample_size). Only used with โ€œwls_varโ€, โ€œmint_covโ€, โ€œmint_shrinkโ€
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
Returns:
  • self: object, fitted reconciler.

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray = None,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
MinTrace Reconciliation Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
  • y_insample: Insample values of size (base, insample_size). Only used by wls_var, mint_cov, mint_shrink
  • y_hat_insample: Insample fitted values of size (base, insample_size). Only used by wls_var, mint_cov, mint_shrink
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • level: float list 0-100, confidence levels for prediction intervals.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
Returns:
  • y_tilde: Reconciliated y_hat using the MinTrace approach.

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class MinTraceSparse

MinTraceSparse Reconciliation Class. This is the implementation of OLS and WLS estimators using sparse matrices. It is not guaranteed to give identical results to the non-sparse version, but works much more efficiently on data sets with many time series.
See the parent class for more details.
Parameters:
method: str, one of ols, wls_struct, or wls_var.
nonnegative: bool, return non-negative reconciled forecasts.
num_threads: int, number of threads to execute non-negative quadratic programming calls.
qp: bool, implement non-negativity constraint with a quadratic programming approach. Setting this to True generally gives better results, but at the expense of higher cost to compute.

method __init__

__init__(
    method: str,
    nonnegative: bool = False,
    num_threads: int = 1,
    qp: bool = True
) โ†’ None

method fit

fit(
    S: csr_matrix,
    y_hat: ndarray,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None,
    idx_bottom: Optional[ndarray] = None
) โ†’ MinTraceSparse
MinTraceSparse Fit Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • y_insample: Insample values of size (base, insample_size). Only used with โ€œwls_varโ€.
  • y_hat_insample: Insample forecast values of size (base, insample_size). Only used with โ€œwls_varโ€
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
Returns:
  • self: object, fitted reconciler.

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray = None,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
MinTrace Reconciliation Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
  • y_insample: Insample values of size (base, insample_size). Only used by wls_var, mint_cov, mint_shrink
  • y_hat_insample: Insample fitted values of size (base, insample_size). Only used by wls_var, mint_cov, mint_shrink
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • level: float list 0-100, confidence levels for prediction intervals.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
Returns:
  • y_tilde: Reconciliated y_hat using the MinTrace approach.

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class OptimalCombination

Optimal Combination Reconciliation Class. This reconciliation algorithm was proposed by Hyndman et al. 2011, the method uses generalized least squares estimator using the coherency errors covariance matrix. Consider the covariance of the base forecast Var(ฯตh)=ฮฃh\textrm{Var}(\epsilon_{h}) = \Sigma_{h}, the P\mathbf{P} matrix of this method is defined by: P=(SโŠบฮฃhโ€ S)โˆ’1SโŠบฮฃhโ€  \mathbf{P} = \left(\mathbf{S}^{\intercal}\Sigma_{h}^{\dagger}\mathbf{S}\right)^{-1}\mathbf{S}^{\intercal}\Sigma^{\dagger}_{h} where ฮฃhโ€ \Sigma_{h}^{\dagger} denotes the variance pseudo-inverse. The method was later proven equivalent to MinTrace variants. Args:
  • method: str, allowed optimal combination methods: โ€˜olsโ€™, โ€˜wls_structโ€™.
  • nonnegative: bool, reconciled forecasts should be nonnegative?
References:
  • [Rob J. Hyndman, Roman A. Ahmed, George Athanasopoulos, Han Lin Shang (2010). โ€œOptimal Combination Forecasts for
  • Hierarchical Time Series".](https: //robjhyndman.com/papers/Hierarchical6.pdf).
    • [Shanika L. Wickramasuriya, George Athanasopoulos and Rob J. Hyndman (2010). โ€œOptimal Combination Forecasts for
  • Hierarchical Time Series".](https: //robjhyndman.com/papers/MinT.pdf).
    • [Wickramasuriya, S.L., Turlach, B.A. & Hyndman, R.J. (2020). โ€œOptimal non-negative forecast reconciliationโ€. Stat Comput 30, 1167โ€“1182,
  • https: //doi.org/10.1007/s11222-020-09930-0](https://robjhyndman.com/publications/nnmint/).

method __init__

__init__(method: str, nonnegative: bool = False, num_threads: int = 1)

method fit

fit(
    S,
    y_hat,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None,
    idx_bottom: Optional[ndarray] = None
)
MinTrace Fit Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • y_insample: Insample values of size (base, insample_size). Only used with โ€œwls_varโ€, โ€œmint_covโ€, โ€œmint_shrinkโ€.
  • y_hat_insample: Insample forecast values of size (base, insample_size). Only used with โ€œwls_varโ€, โ€œmint_covโ€, โ€œmint_shrinkโ€
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
Returns:
  • self: object, fitted reconciler.

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray = None,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
MinTrace Reconciliation Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
  • y_insample: Insample values of size (base, insample_size). Only used by wls_var, mint_cov, mint_shrink
  • y_hat_insample: Insample fitted values of size (base, insample_size). Only used by wls_var, mint_cov, mint_shrink
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • level: float list 0-100, confidence levels for prediction intervals.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
Returns:
  • y_tilde: Reconciliated y_hat using the MinTrace approach.

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).

class ERM

Empirical Risk Minimization Reconciliation Class. The Empirical Risk Minimization reconciliation strategy relaxes the unbiasedness assumptions from previous reconciliation methods like MinT and optimizes square errors between the reconciled predictions and the validation data to obtain an optimal reconciliation matrix P. The exact solution for P\mathbf{P} (method='closed') follows the expression: Pโˆ—=(SโŠบS)โˆ’1YโŠบY^(Y^Y^)โˆ’1\mathbf{P}^{*} = \left(\mathbf{S}^{\intercal}\mathbf{S}\right)^{-1}\mathbf{Y}^{\intercal}\hat{\mathbf{Y}}\left(\hat{\mathbf{Y}}\hat{\mathbf{Y}}\right)^{-1} The alternative Lasso regularized P\mathbf{P} solution (method='reg_bu') is useful when the observations of validation data is limited or the exact solution has low numerical stability. Pโˆ—=argminPโˆฃโˆฃYโˆ’SPY^โˆฃโˆฃ22+ฮปโˆฃโˆฃPโˆ’PBUโˆฃโˆฃ1\mathbf{P}^{*} = \text{argmin}_{\mathbf{P}} ||\mathbf{Y}-\mathbf{S} \mathbf{P} \hat{Y} ||^{2}_{2} + \lambda ||\mathbf{P}-\mathbf{P}_{\text{BU}}||_{1} Args:
  • method: str, one of closed, reg and reg_bu.
  • lambda_reg: float, l1 regularizer for reg and reg_bu.
References:
  • [Ben Taieb, S., & Koo, B. (2019). Regularized regression for hierarchical forecasting without unbiasedness conditions. In Proceedings of the 25th ACM SIGKDD International Conference on Knowledge
  • Discovery & Data Mining KDD โ€™19 (p. 1337-1347). New York, NY, USA: Association for Computing Machinery.](https://doi.org/10.1145/3292500.3330976).

method __init__

__init__(method: str, lambda_reg: float = 0.01)

method fit

fit(
    S,
    y_hat,
    y_insample,
    y_hat_insample,
    sigmah: Optional[ndarray] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None,
    idx_bottom: Optional[ndarray] = None
)
ERM Fit Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • y_insample: Train values of size (base, insample_size).
  • y_hat_insample: Insample train predictions of size (base, insample_size).
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
Returns:
  • self: object, fitted reconciler.

method fit_predict

fit_predict(
    S: ndarray,
    y_hat: ndarray,
    idx_bottom: ndarray = None,
    y_insample: Optional[ndarray] = None,
    y_hat_insample: Optional[ndarray] = None,
    sigmah: Optional[ndarray] = None,
    level: Optional[list[int]] = None,
    intervals_method: Optional[str] = None,
    num_samples: Optional[int] = None,
    seed: Optional[int] = None,
    tags: Optional[dict[str, ndarray]] = None
)
ERM Reconciliation Method. Args:
  • S: Summing matrix of size (base, bottom).
  • y_hat: Forecast values of size (base, horizon).
  • idx_bottom: Indices corresponding to the bottom level of S, size (bottom).
  • y_insample: Train values of size (base, insample_size).
  • y_hat_insample: Insample train predictions of size (base, insample_size).
  • sigmah: Estimated standard deviation of the conditional marginal distribution.
  • level: float list 0-100, confidence levels for prediction intervals.
  • intervals_method: Sampler for prediction intervals, one of normality, bootstrap, permbu.
  • num_samples: Number of samples for probabilistic coherent distribution.
  • seed: Seed for reproducibility.
  • tags: Each key is a level and each value its S indices.
Returns:
  • y_tilde: Reconciliated y_hat using the ERM approach.

method predict

predict(S: ndarray, y_hat: ndarray, level: Optional[list[int]] = None)
Predict using reconciler. Predict using fitted mean and probabilistic reconcilers. Args:
  • S (np.ndarray): Summing matrix of size (base, bottom).
  • y_hat (np.ndarray): Forecast values of size (base, horizon).
  • level (Optional[list[int]], optional): float list 0-100, confidence levels for prediction intervals. Default is None.
Returns:
  • dict: y_tilde: Reconciliated predictions.

method sample

sample(num_samples: int)
Sample probabilistic coherent distribution. Generates n samples from a probabilistic coherent distribution. The method uses fitted mean and probabilistic reconcilers, defined by the intervals_method selected during the reconcilerโ€™s instantiation. Currently available: normality, bootstrap, permbu. Args:
  • num_samples (int): number of samples generated from coherent distribution.
Returns:
  • np.ndarray: samples: Coherent samples of size (num_series, horizon, num_samples).