HINT: hierarchical forecast reconciliation wrapper (port of neuralforecast.HINT).

A hierarchy of series is described by a summing matrix S of shape (n_total, n_bottom) whose rows list every node (aggregates first, then the bottom rows, which must form an identity block): y_total = S @ y_bottom. HINT trains ONE probabilistic base network on the windows of every series in the hierarchy (cross-learning with per-window scale decoupling), draws Monte-Carlo sample paths from each series' predictive mixture, and restores the aggregation constraints by projecting the sample tensor with SP = S @ P — bootstrap sample reconciliation. Coherence is a per-sample (joint) property: the reconciled mean is exactly coherent, while marginal quantiles of coherent samples do not sum across the hierarchy in general.

HINT

chronax.models.hint_model.HINT · inherits BaseForecaster

HINT: Hierarchical Mixture Network (flax.nnx port of neuralforecast.HINT).

Wraps a probabilistic base forecaster (an :class:~chronax.models.mlp.MLP with a distribution loss such as :class:~chronax.models.mlp.GMM) into a coherent hierarchical forecaster. fit expects y of shape (T, n_total) with columns ordered exactly as the rows of S (aggregates first, bottom identity block last); a 1-D series is accepted when S is 1x1. One network is trained on the pooled h-padded windows of all series (batch sampling is uniform over the pooled set), so the hierarchy is cross-learned with per-window scale decoupling. predict draws seeded Monte-Carlo sample paths per series, reconciles them with SP = S @ P, and emits the reconciled analytic mean plus native sample-quantile intervals; output arrays are (h,) for a 1-D fit and (h, n_total) otherwise. reconciliation="Identity" skips reconciliation entirely.

Conformal intervals follow the base-class contract on 1-D fits only; a hierarchical fit's intervals are the native reconciled-sample quantiles. Exogenous inputs are not supported. The passed model is used purely as a configuration carrier and is never fitted or mutated.

Attributes: * uses_exog: False * alias: str * conformal_params: ConformalIntervals | None * model_: Fitted base model parameters (nnx.Module)

__init__(self, h: int, S, model, reconciliation: str = 'BottomUp', alias: str = 'HINT')

Initializes the HINT wrapper, validating the forecast horizon h, the summing matrix S, and the base model.

Parameter	Type	Default	Description
h	int	-	Forecast horizon. Must match model.h.
S	-	-	Summing matrix of shape (n_total, n_bottom). The last n_bottom rows must form the identity block.
model	-	-	The probabilistic base forecaster configuration. Must be an MLP instance with a distribution loss.
reconciliation	str	"BottomUp"	The reconciliation method to use. Available options are "BottomUp", "MinTraceOLS", "MinTraceWLS", or "Identity" (no reconciliation).
alias	str	"HINT"	(undocumented)

fit(self, y, X=None) -> HINT

Trains a single base network over the pooled h-padded windows of all series in the hierarchy defined by S.

Parameter	Type	Default	Description
y	-	-	Input time series data. Expected shape (T, n_total) or (T,) if S is 1x1. Columns must be ordered as rows of S.
X	None	None	Exogenous inputs (not supported).

Returns: Self (the fitted forecaster; sets self.model_). Raises: ValueError if X is provided, or if y shape is incompatible with S.

predict(self, h, X=None, level=None) -> dict

Draws seeded Monte-Carlo sample paths, reconciles them using SP, and returns the reconciled mean and sample-quantile intervals if level is specified.

Parameter	Type	Default	Description
h	-	-	Forecast horizon. Must be less than or equal to the h used during initialization.
X	None	None	Exogenous inputs (not supported).
level	list[int] or None	None	Prediction interval coverage levels (e.g., [80, 95]).

Returns: dict containing forecasts. Keys include "mean", plus "lo-L" and "hi-L" for each level L requested. Output shape is (h,) for a 1-D fit and (h, n_total) otherwise. Raises: RuntimeError if not fitted. ValueError if X is provided or h is invalid.

forecast(self, y, h, X=None, X_future=None, level=None, fitted=False) -> dict

Stateless fit-then-predict on the hierarchy matrix y.

Parameter	Type	Default	Description
y	-	-	(undocumented)
h	-	-	(undocumented)
X	None	None	(undocumented)
X_future	None	None	(undocumented)
level	list[int] or None	None	(undocumented)
fitted	bool	False	(undocumented)

Returns: dict (as per predict). Raises: ValueError if X_future is provided. NotImplementedError if fitted=True.

conformity_scores(self, y, X=None) -> jnp.ndarray

Calculates conformity scores. Supported only for 1-D fits; hierarchical fits use native reconciled-sample quantiles instead of conformal intervals.

Parameter	Type	Default	Description
y	-	-	(undocumented)
X	None	None	(undocumented)

Returns: jnp.ndarray Raises: ValueError if y is not 1-D.