pymc_forecast.data

Input normalization: everything becomes an xarray.DataArray with a leading "time" dim.

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).

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')

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 numpy arrays (integer-range time coord is attached).

Parameters:

• obj – The object to normalize.

• role – "data" or "covariates"; sets the default name of the second dim for 2-d pandas/numpy inputs ("series" / "covariate").

pymc_forecast.data.concat_covariates(covariates, future_covariates)

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, 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. Returns the full-horizon covariates.

Raises:

AlignmentError – On a time index that does not extend the training window, or on any dim/coord mismatch.

pymc_forecast.data.concat_time_index(index, future_index)

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. Returns the full observed + future index.

Parameters:

• index – Time coordinate values of the training window.

• future_index – Time coordinate values of the forecast horizon.

Raises:

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)

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 inferred frequency, a numeric index by its constant step. Returns the full observed + horizon index.

Raises:

AlignmentError – If a datetime frequency cannot be inferred, or the numeric spacing is not constant.

pymc_forecast.data.null_covariates(index)

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 – Time coordinate values spanning the full horizon (observed + future), e.g. a pandas.DatetimeIndex or an integer range.

pymc_forecast.data.validate_alignment(data, covariates)

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.