Core | NeuralForecast

NeuralForecast contains two main components, PyTorch implementations deep learning predictive models, as well as parallelization and distributed computation utilities. The first component comprises low-level PyTorch model estimator classes like models.NBEATS and models.RNN. The second component is a high-level core.NeuralForecast wrapper class that operates with sets of time series data stored in pandas DataFrames.

`NeuralForecast`

NeuralForecast(
    models, freq, local_scaler_type=None, local_static_scaler_type=None
)

The core.StatsForecast class allows you to efficiently fit multiple NeuralForecast models for large sets of time series. It operates with a pandas DataFrame df that identifies series and datestamps with the unique_id and ds columns. The y column denotes the target time series variable. Parameters:

Name	Type	Description	Default
`models`	`List[Any]`	Instantiated `neuralforecast.models` see collection here.	required
`freq`	`str or int`	Frequency of the data. Must be a valid pandas or polars offset alias, or an integer.	required
`local_scaler_type`	`str`	Scaler to apply per-serie to temporal features before fitting, which is inverted after predicting. Can be ‘standard’, ‘robust’, ‘robust-iqr’, ‘minmax’ or ‘boxcox’.	`None`
`local_static_scaler_type`	`str`	Scaler to apply to static exogenous features before fitting. Can be ‘standard’, ‘robust’, ‘robust-iqr’, ‘minmax’ or ‘boxcox’.	`None`

Returns:

Name	Type	Description
`NeuralForecast`		Returns instantiated `NeuralForecast` class.

`NeuralForecast.fit`

fit(
    df=None,
    static_df=None,
    val_size=0,
    val_df=None,
    use_init_models=False,
    verbose=False,
    id_col="unique_id",
    time_col="ds",
    target_col="y",
    distributed_config=None,
    prediction_intervals=None,
)

Fit the core.NeuralForecast Fit models to a large set of time series from DataFrame df and store fitted models for later inspection. Parameters:

Name	Type	Description	Default
`df`	`pandas, polars or spark DataFrame, or a list of parquet files containing the series`	DataFrame with columns [`unique_id`, `ds`, `y`] and exogenous variables. If None, a previously stored dataset is required.	`None`
`static_df`	`pandas, polars or spark DataFrame`	DataFrame with columns [`unique_id`] and static exogenous.	`None`
`val_size`	`int`	Size of validation set. Cannot be used together with `val_df`.	`0`
`val_df`	`pandas or polars DataFrame`	Explicit validation DataFrame with columns [`unique_id`, `ds`, `y`] and exogenous variables. `val_df` can be temporally independent (no requirement that it starts immediately after `df`). Cannot be used together with `val_size`. Only supported when `df` is a pandas or polars DataFrame. All series in `val_df` must have the same length.	`None`
`use_init_models`	`bool`	If True, discards any previously fitted weights and reinitializes the models from the configs passed at `NeuralForecast(__init__)`. Use this to start training from scratch. Defaults to False.	`False`
`verbose`	`bool`	Print processing steps.	`False`
`id_col`	`str`	Column that identifies each serie.	`‘unique_id’`
`time_col`	`str`	Column that identifies each timestep, its values can be timestamps or integers.	`‘ds’`
`target_col`	`str`	Column that contains the target.	`‘y’`
`distributed_config`	`DistributedConfig`	Configuration to use for DDP training. Currently only spark is supported.	`None`
`prediction_intervals`	`PredictionIntervals`	Configuration to calibrate prediction intervals (Conformal Prediction).	`None`

Returns:

Name	Type	Description
`NeuralForecast`	`None`	Returns `NeuralForecast` class with fitted `models`.

`NeuralForecast.predict`

predict(
    df=None,
    static_df=None,
    futr_df=None,
    verbose=False,
    engine=None,
    level=None,
    quantiles=None,
    h=None,
    **data_kwargs
)

Predict with core.NeuralForecast. Use stored fitted models to predict large set of time series from DataFrame df. Predicting with a different horizon than training The h argument can override the horizon each model was fitted with, but the allowed values depend on the model and the fit configuration:

h equal to the fitted horizon (the default when h=None): all models produce a single forward pass of length h.
h greater than the fitted horizon: supported, with restrictions.
- Direct (non-recurrent) models such as NHITS, NBEATS, NBEATSx, MLP, TFT, PatchTST, and other windows-based models produce the extended horizon by feeding their own forecasts back as inputs and running ceil(h / fitted_h) recursive rollouts. Accuracy is not guaranteed beyond the fitted horizon; errors compound across rollouts. Consider refitting with the target horizon (or using an Auto model) if quality matters.
- Recurrent models such as RNN, LSTM, GRU, DilatedRNN, TCN, and DeepAR extend the horizon natively by rolling the recurrent state forward.
- h > fitted_h is not supported when the fit was calibrated with prediction_intervals (raises ValueError) or when any model declares hist_exog_list (raises NotImplementedError).
h smaller than the fitted horizon: not supported and raises ValueError. Refit the model with the smaller horizon, or take the first h steps of the default forecast yourself.

Parameters:

Name	Type	Description	Default
`df`	`pandas, polars or spark DataFrame`	DataFrame with columns [`unique_id`, `ds`, `y`] and exogenous variables. If a DataFrame is passed, it is used to generate forecasts.	`None`
`static_df`	`pandas, polars or spark DataFrame`	DataFrame with columns [`unique_id`] and static exogenous.	`None`
`futr_df`	`pandas, polars or spark DataFrame`	DataFrame with [`unique_id`, `ds`] columns and `df`’s future exogenous.	`None`
`verbose`	`bool`	Print processing steps.	`False`
`engine`	`spark session`	Distributed engine for inference. Only used if df is a spark dataframe or if fit was called on a spark dataframe.	`None`
`level`	`list of ints or floats`	Confidence levels between 0 and 100.	`None`
`quantiles`	`list of floats`	Alternative to level, target quantiles to predict.	`None`
`h`	`int`	Forecasting horizon. If `None`, uses the horizon each model was fitted with. Must be greater than or equal to the fitted horizon; see the note above for the restrictions that apply when `h` exceeds it.	`None`
`data_kwargs`	`kwargs`	Extra arguments to be passed to the dataset within each model.

Returns:

Name	Type	Description
`fcsts_df`	`pandas or polars DataFrame`	DataFrame with insample `models` columns for point predictions and probabilistic predictions for all fitted `models`.

`NeuralForecast.cross_validation`

cross_validation(
    df=None,
    static_df=None,
    n_windows=1,
    step_size=1,
    val_size=0,
    test_size=None,
    use_init_models=False,
    use_fitted=False,
    verbose=False,
    refit=False,
    id_col="unique_id",
    time_col="ds",
    target_col="y",
    prediction_intervals=None,
    level=None,
    quantiles=None,
    h=None,
    **data_kwargs
)

Temporal Cross-Validation with core.NeuralForecast. core.NeuralForecast’s cross-validation efficiently fits a list of NeuralForecast models through multiple windows, in either chained or rolled manner. Parameters:

Name	Type	Description	Default
`df`	`pandas or polars DataFrame`	DataFrame with columns [`unique_id`, `ds`, `y`] and exogenous variables. If None, a previously stored dataset is required.	`None`
`static_df`	`pandas or polars DataFrame`	DataFrame with columns [`unique_id`] and static exogenous. Defaults to None.	`None`
`n_windows`	`(int, None)`	Number of windows used for cross validation. If None, define `test_size`.	`1`
`step_size`	`int`	Step size between each window.	`1`
`val_size`	`int`	Length of validation size. If passed, set `n_windows=None`. Defaults to 0.	`0`
`test_size`	`int`	Length of test size. If passed, set `n_windows=None`.	`None`
`use_init_models`	`bool`	If True, discards any previously fitted weights and reinitializes the models from the configs passed at `NeuralForecast(__init__)`. Use this to start cross-validation from scratch. Defaults to False.	`False`
`use_fitted`	`bool`	Evaluate the already-fitted model on `df` without retraining (transfer-learning cross-validation). Requires a previous `fit` call, `refit=False`, `use_init_models=False`, and `prediction_intervals=None`. Local scalers, if any, are refit per series on `df` and the fitted state (model weights, stored dataset, scalers) is restored after CV completes. Defaults to False.	`False`
`verbose`	`bool`	Print processing steps.	`False`
`refit`	`bool or int`	Retrain model for each cross validation window. If False, the models are trained at the beginning and then used to predict each window. If positive int, the models are retrained every `refit` windows.	`False`
`id_col`	`str`	Column that identifies each serie.	`‘unique_id’`
`time_col`	`str`	Column that identifies each timestep, its values can be timestamps or integers. Defaults to ‘ds’.	`‘ds’`
`target_col`	`str`	Column that contains the target.	`‘y’`
`prediction_intervals`	`PredictionIntervals`	Configuration to calibrate prediction intervals (Conformal Prediction). Defaults to None.	`None`
`level`	`list of ints or floats`	Confidence levels between 0 and 100.	`None`
`quantiles`	`list of floats`	Alternative to level, target quantiles to predict.	`None`
`h`	`int`	Forecasting horizon. If `None`, uses the horizon each model was fitted with. The same rules as `NeuralForecast.predict` apply: `h` must be greater than or equal to the fitted horizon, and the restrictions on `h > fitted_h` (recursive rollout for direct models, no `prediction_intervals`, no `hist_exog_list`) apply here too.	`None`
`data_kwargs`	`kwargs`	Extra arguments to be passed to the dataset within each model.

Returns:

Name	Type	Description
`fcsts_df`	`pandas or polars DataFrame`	DataFrame with insample `models` columns for point predictions and probabilistic predictions for all fitted `models`.

`NeuralForecast.predict_insample`

predict_insample(step_size=1, level=None, quantiles=None)

Predict insample with core.NeuralForecast. core.NeuralForecast’s predict_insample uses stored fitted models to predict historic values of a time series from the stored dataframe. Parameters:

Name	Type	Description	Default
`step_size`	`int`	Step size between each window.	`1`
`level`	`list of ints or floats`	Confidence levels between 0 and 100.	`None`
`quantiles`	`list of floats`	Alternative to level, target quantiles to predict.	`None`

Returns:

Name	Type	Description
`fcsts_df`	`DataFrame`	DataFrame with insample predictions for all fitted `models`.

`NeuralForecast.save`

save(path, model_index=None, save_dataset=True, overwrite=False)

Save NeuralForecast core class. core.NeuralForecast’s method to save current status of models, dataset, and configuration. Note that by default the models are not saving training checkpoints to save disk memory, to get them change the individual model **trainer_kwargs to include enable_checkpointing=True. Parameters:

Name	Type	Description	Default
`path`	`str`	Directory to save current status.	required
`model_index`	`list`	List to specify which models from list of self.models to save.	`None`
`save_dataset`	`bool`	Whether to save dataset or not.	`True`
`overwrite`	`bool`	Whether to overwrite files or not.	`False`

`NeuralForecast.load`

load(path, verbose=False, **kwargs)

Load NeuralForecast core.NeuralForecast’s method to load checkpoint from path. Parameters:

Name	Type	Description	Default
`path`	`str`	Directory with stored artifacts.	required
`verbose`	`bool`	Defaults to False.	`False`
`**kwargs`		Additional keyword arguments to be passed to the function `load_from_checkpoint`.

Returns:

Name	Type	Description
`result`	`NeuralForecast`	Instantiated `NeuralForecast` class.

Getting Started

Capabilities

Tutorials

Use cases

API Reference

Core | NeuralForecast

`NeuralForecast`

`NeuralForecast.fit`

`NeuralForecast.predict`

`NeuralForecast.cross_validation`

`NeuralForecast.predict_insample`

`NeuralForecast.save`

`NeuralForecast.load`

​

​NeuralForecast

​NeuralForecast.fit

​NeuralForecast.predict

​NeuralForecast.cross_validation

​NeuralForecast.predict_insample

​NeuralForecast.save

​NeuralForecast.load

`NeuralForecast`

`NeuralForecast.fit`

`NeuralForecast.predict`

`NeuralForecast.cross_validation`

`NeuralForecast.predict_insample`

`NeuralForecast.save`

`NeuralForecast.load`