Prepare a forecast without changing its time axis

TimesFM 2.5 sees positions, not timestamps. Give a list of finite one-dimensional float arrays, one regular univariate history per array. Variable lengths are allowed; each series needs its own known cadence and forecast origin. A batch horizon of 12 means 12 steps, not a shared wall-clock duration across cadences.

CSV/DataFrame recipe

The bundled helper sorts dates, validates uniqueness and checks the full grid. Use it directly for CSVs; when adapting DataFrames apply the same checks.

# Run from the skill scripts directory, or put that directory on sys.path.
from forecast_csv import load_csv, prepare_inputs
frame, columns, date_column = load_csv(
    "monthly_sales.csv", date_col="date", value_cols=["sales"], freq="MS"
)
inputs = prepare_inputs(frame, columns, missing="error")

Select target columns explicitly when numeric IDs/metadata exist. Two or fewer dates cannot establish a unique frequency, so declare it. Do not silently resample: a sum for counts, mean for intensities and last value for stock levels represent different targets. Record timezone and daylight-saving decisions. For long-format data, group by series ID, validate each grid separately and retain a parallel ordered ID list. Do not use .dropna() to build histories.

Pandas input adapters: read_excel(..., engine="openpyxl") needs openpyxl; read_parquet(..., engine="pyarrow") needs pyarrow. These optional adapters were source-checked, not exercised in this refresh. JSON/NumPy input must still be checked for finite values, shape, cadence and origin.

Missing values and transformations

The release's base forecast strips leading NaNs and interpolates later NaNs, including trailing last-value extension. This is computational convenience, not a missing-data model. Reject all-missing, empty, infinite or overflowed float32 inputs. Choose a documented missingness policy before forecasting.

The CLI rejects missing data by default. --missing interpolate fills internal gaps only and retains the same array length; leading/trailing gaps fail because they make the forecast origin or observed history ambiguous. Impute separately inside each training cutoff. Interpolation across a held-out target leaks future information. Imputed observations should not become “actuals” for coverage.

Validate clipping/outlier handling scientifically; do not erase real events to improve a score. Fit scalers, detrending and feature selection on training data only, reverse transformations for evaluation, and retain units. Constant or short series deserve a naive baseline; there is no universal 32-point model minimum or guarantee that more history improves accuracy.

XReg inputs

For each series i with context length Li and requested horizon H:

• target is (Li,), containing only observations available at origin;
• each dynamic feature is (Li+H,), with the future segment known at origin;
• each static feature supplies one value per series;
• feature names, series order, time positions and inferred horizons agree.

A weather forecast issued at origin can be a future covariate; the weather later observed at that date cannot be used for a realistic backtest. Planned prices and holiday schedules are conditional assumptions, not causal effects. Numeric and categorical covariates are processed by pooled linear XReg, not native multivariate target attention. The distinct 3.0 API supports past-only features.