pymc_forecast.data#

Input normalization and time-index helpers for labeled time series.

The package is dims/coords-first: models, forecasts, and metrics all speak named dimensions. Users may still pass pandas or numpy objects at the API boundary; this module converts them once, attaching real time coordinates (a DatetimeIndex, periods, or a fallback integer range). Series inputs become xarray.DataArray objects with a leading "time" dim; the time-index helpers return pandas.Index objects.

pymc_forecast.data.CHAIN_DIM = 'chain'#

First posterior-sample dim on every prediction output.

pymc_forecast.data.DRAW_DIM = 'draw'#

Second posterior-sample dim on every prediction output.

pymc_forecast.data.FUTURE_DIM = 'time_future'#

Dim name of the forecast-horizon time dimension.

pymc_forecast.data.SAMPLE_DIMS = ('chain', 'draw')#

The ordered sample dims guaranteed to lead every prediction output.

pymc_forecast.data.TIME_DIM = 'time'#

Dim name of the observed (in-sample) time dimension.

pymc_forecast.data.as_dataarray(obj, *, role='data')[source]#

Normalize obj to a DataArray with "time" as the leading dim.

Accepted inputs:

  • xarray.DataArray with a "time" dim (transposed time-first);

  • pandas.Series (index becomes the time coord) or pandas.DataFrame (index → time coord, columns → "series"/"covariate" coord);

  • 1-d/2-d array-likes converted with np.asarray (integer-range time coord is attached).

Parameters:

  • obj (xarray.DataArray, pandas.Series, pandas.DataFrame or array_like) – The object to normalize.

  • role ({"data", "covariates"}, default "data") – Sets the default name of the second dim for 2-d pandas/array inputs ("series" / "covariate") and is used in error messages.

Returns:

xarray.DataArray – obj with "time" as the leading dim. Inputs without a time coord get an integer range 0..n-1; a pandas DatetimeIndex keeps its frequency.

Raises:
pymc_forecast.data.concat_covariates(covariates, future_covariates)[source]#

Append future covariate rows to training covariates along "time".

future_covariates covers only the forecast horizon (both inputs are normalized via as_dataarray() first); its time index must lie strictly after the training window and its non-time structure — dims in the same order, and covariate names in order — must match the training covariates, since models consume covariate columns positionally. Every mismatch is rejected explicitly, so xarray never silently aligns, reorders, or fills feature columns.

Parameters:
Returns:

xarray.DataArray – The full-horizon covariates, concatenated along "time".

Raises:

pymc_forecast.exceptions.AlignmentError – If an input cannot be normalized, the future time index does not extend the training window, or the dims (including their order), sizes, or coordinates of the non-time dims differ.

pymc_forecast.data.concat_time_index(index, future_index)[source]#

Concatenate a training time index with a predict-time future index.

The future index supplies the forecast horizon at predict time (its length need not be known when the model is fit). Its values must be strictly increasing and lie strictly after the last training value; gaps are allowed — forecast steps are labeled with the supplied coordinates.

Parameters:

  • index (array_like) – Time coordinate values of the training window (may be empty).

  • future_index (array_like) – Time coordinate values of the forecast horizon.

Returns:

pandas.Index – The full observed + future index.

Raises:

pymc_forecast.exceptions.AlignmentError – If the future index is empty, not strictly increasing, does not sort after the training index, or cannot be compared to it.

pymc_forecast.data.extend_time_index(index, horizon)[source]#

Extend a time index by horizon steps, inferring the spacing.

Used to build the forecast horizon for covariate-free models: a DatetimeIndex is extended at its stored or inferred frequency, a PeriodIndex at its stored frequency, and a numeric index by its constant step (step 1 for fewer than 2 values).

Parameters:

  • index (array_like) – Training time coordinate values (anything pandas.Index accepts): datetime, period, or numeric.

  • horizon (int) – Number of steps to append (non-negative; bool is rejected).

Returns:

pandas.Index – The full observed + horizon index. With horizon=0 the index is returned unchanged, without further checks.

Raises:

pymc_forecast.exceptions.AlignmentError – If horizon is not a non-negative integer, the index is empty or not strictly increasing, a datetime frequency cannot be inferred (no stored frequency and fewer than 3 values or an irregular index), the index is not numeric, datetime or period, or the numeric spacing is not constant.

pymc_forecast.data.null_covariates(index)[source]#

Zero-width covariates carrying only the time coord.

Covariates are the horizon carrier of the whole API (their time coord spans train + forecast). Models without real covariates use this helper: null_covariates(full_time_index).

Parameters:

index (array_like) – Time coordinate values spanning the full horizon (observed + future), e.g. a pandas.DatetimeIndex or an integer range.

Returns:

xarray.DataArray – Zeros of shape (len(index), 0) with dims ("time", "covariate") and only a "time" coord.

pymc_forecast.data.validate_alignment(data, covariates)[source]#

Require the covariate time coord to extend the data time coord.

covariates must be at least as long as data along "time", and the first len(data.time) coordinate values must match exactly — the surplus is the forecast horizon and must be strictly increasing after training. Shared non-time dimensions must have identical sizes and coordinates, so panel covariates cannot silently change series order.

Parameters:
Raises:

pymc_forecast.exceptions.AlignmentError – If covariates is shorter than data along "time", the leading covariate time coords differ from the data time coords, a shared non-time dim differs in size or coordinates (or is labeled on one side only), or the surplus time coords are not strictly increasing after training.