> ## Documentation Index
> Fetch the complete documentation index at: https://nixtlaverse.nixtla.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Full pipeline encapsulation

# MLForecast

##

### `MLForecast`

```python theme={null}
MLForecast(
    models,
    freq,
    lags=None,
    lag_transforms=None,
    date_features=None,
    num_threads=1,
    target_transforms=None,
    lag_transforms_namer=None,
)
```

Forecasting pipeline

**Parameters:**

| Name                   | Type                                                                            | Description                                                                                                                                 | Default           |
| ---------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `models`               | <code>regressor or list of regressors</code>                                    | Models that will be trained and used to compute the forecasts.                                                                              | *required*        |
| `freq`                 | <code>[str](#str) or [int](#int) or [BaseOffset](#pd.offsets.BaseOffset)</code> | Pandas offset, pandas offset alias, e.g. 'D', 'W-THU' or integer denoting the frequency of the series.                                      | *required*        |
| `lags`                 | <code>list of int</code>                                                        | Lags of the target to use as features. Defaults to None.                                                                                    | <code>None</code> |
| `lag_transforms`       | <code>dict of int to list of functions</code>                                   | Mapping of target lags to their transformations. Defaults to None.                                                                          | <code>None</code> |
| `date_features`        | <code>list of str or callable</code>                                            | Features computed from the dates. Can be pandas date attributes or functions that will take the dates as input. Defaults to None.           | <code>None</code> |
| `num_threads`          | <code>[int](#int)</code>                                                        | Number of threads to use when computing the features. Use -1 to use all available CPU cores. Defaults to 1.                                 | <code>1</code>    |
| `target_transforms`    | <code>list of transformers</code>                                               | Transformations that will be applied to the target before computing the features and restored after the forecasting step. Defaults to None. | <code>None</code> |
| `lag_transforms_namer` | <code>[callable](#callable)</code>                                              | Function that takes a transformation (either function or class), a lag and extra arguments and produces a name. Defaults to None.           | <code>None</code> |

#### `MLForecast.fit`

```python theme={null}
fit(
    df,
    id_col="unique_id",
    time_col="ds",
    target_col="y",
    static_features=None,
    dropna=True,
    keep_last_n=None,
    max_horizon=None,
    horizons=None,
    prediction_intervals=None,
    fitted=False,
    as_numpy=False,
    weight_col=None,
    models_fit_kwargs=None,
    validate_data=True,
)
```

Apply the feature engineering and train the models.

**Parameters:**

| Name                   | Type                                                                      | Description                                                                                                                                                                         | Default                   |
| ---------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `df`                   | <code>pandas or polars DataFrame</code>                                   | Series data in long format.                                                                                                                                                         | *required*                |
| `id_col`               | <code>[str](#str)</code>                                                  | Column that identifies each serie. Defaults to 'unique\_id'.                                                                                                                        | <code>'unique\_id'</code> |
| `time_col`             | <code>[str](#str)</code>                                                  | Column that identifies each timestep, its values can be timestamps or integers. Defaults to 'ds'.                                                                                   | <code>'ds'</code>         |
| `target_col`           | <code>[str](#str)</code>                                                  | Column that contains the target. Defaults to 'y'.                                                                                                                                   | <code>'y'</code>          |
| `static_features`      | <code>list of str</code>                                                  | Names of the features that are static and will be repeated when forecasting. If `None`, will consider all columns (except id\_col and time\_col) as static. Defaults to None.       | <code>None</code>         |
| `dropna`               | <code>[bool](#bool)</code>                                                | Drop rows with missing values produced by the transformations. Defaults to True.                                                                                                    | <code>True</code>         |
| `keep_last_n`          | <code>[int](#int)</code>                                                  | Keep only these many records from each serie for the forecasting step. Can save time and memory if your features allow it. Defaults to None.                                        | <code>None</code>         |
| `max_horizon`          | <code>[int](#int)</code>                                                  | Train this many models, where each model will predict a specific horizon. Defaults to None.                                                                                         | <code>None</code>         |
| `horizons`             | <code>list of int</code>                                                  | Train models only for specific horizons (1-indexed). For example, `horizons=[7, 14]` trains models only for steps 7 and 14. Mutually exclusive with max\_horizon. Defaults to None. | <code>None</code>         |
| `prediction_intervals` | <code>[PredictionIntervals](#mlforecast.utils.PredictionIntervals)</code> | Configuration to calibrate prediction intervals (Conformal Prediction). Defaults to None.                                                                                           | <code>None</code>         |
| `fitted`               | <code>[bool](#bool)</code>                                                | Save in-sample predictions. Defaults to False.                                                                                                                                      | <code>False</code>        |
| `as_numpy`             | <code>[bool](#bool)</code>                                                | Cast features to numpy array. Defaults to True.                                                                                                                                     | <code>False</code>        |
| `weight_col`           | <code>[str](#str)</code>                                                  | Column that contains the sample weights. Defaults to None.                                                                                                                          | <code>None</code>         |
| `models_fit_kwargs`    | <code>[dict](#dict)</code>                                                | Keyword arguments for each model's fit method. Defaults to None.                                                                                                                    | <code>None</code>         |
| `validate_data`        | <code>[bool](#bool)</code>                                                | Run data quality validations before fitting. Warns about missing dates and raises on duplicate rows. Defaults to True.                                                              | <code>True</code>         |

**Returns:**

| Name         | Type                                                       | Description                                            |
| ------------ | ---------------------------------------------------------- | ------------------------------------------------------ |
| `MLForecast` | <code>[MLForecast](#mlforecast.forecast.MLForecast)</code> | Forecast object with series values and trained models. |

#### `MLForecast.save`

```python theme={null}
save(path)
```

Save forecast object

**Parameters:**

| Name   | Type                                              | Description                               | Default    |
| ------ | ------------------------------------------------- | ----------------------------------------- | ---------- |
| `path` | <code>[str](#str) or [Path](#pathlib.Path)</code> | Directory where artifacts will be stored. | *required* |

#### `MLForecast.load`

```python theme={null}
load(path)
```

Load forecast object

**Parameters:**

| Name   | Type                                              | Description                     | Default    |
| ------ | ------------------------------------------------- | ------------------------------- | ---------- |
| `path` | <code>[str](#str) or [Path](#pathlib.Path)</code> | Directory with saved artifacts. | *required* |

#### `MLForecast.update`

```python theme={null}
update(df, validate_new_data=False)
```

Update the values of the stored series.

**Parameters:**

| Name                | Type                                    | Description                                               | Default            |
| ------------------- | --------------------------------------- | --------------------------------------------------------- | ------------------ |
| `df`                | <code>pandas or polars DataFrame</code> | Dataframe with new observations.                          | *required*         |
| `validate_new_data` | <code>[bool](#bool)</code>              | If True, validate continuity, start dates, and frequency. | <code>False</code> |

#### `MLForecast.make_future_dataframe`

```python theme={null}
make_future_dataframe(h)
```

Create a dataframe with all ids and future times in the forecasting horizon.

**Parameters:**

| Name | Type                     | Description                   | Default    |
| ---- | ------------------------ | ----------------------------- | ---------- |
| `h`  | <code>[int](#int)</code> | Number of periods to predict. | *required* |

**Returns:**

| Type                                                      | Description                                                              |
| --------------------------------------------------------- | ------------------------------------------------------------------------ |
| <code>[DataFrame](#utilsforecast.compat.DataFrame)</code> | pandas or polars DataFrame: DataFrame with expected ids and future times |

#### `MLForecast.get_missing_future`

```python theme={null}
get_missing_future(h, X_df)
```

Get the missing id and time combinations in `X_df`.

**Parameters:**

| Name   | Type                                    | Description                                                                                  | Default    |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- |
| `h`    | <code>[int](#int)</code>                | Number of periods to predict.                                                                | *required* |
| `X_df` | <code>pandas or polars DataFrame</code> | Dataframe with the future exogenous features. Should have the id column and the time column. | *required* |

**Returns:**

| Type                                                | Description                                                                                |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| <code>[DFType](#utilsforecast.compat.DFType)</code> | pandas or polars DataFrame: DataFrame with expected ids and future times missing in `X_df` |

#### `MLForecast.predict`

```python theme={null}
predict(
    h,
    before_predict_callback=None,
    after_predict_callback=None,
    new_df=None,
    level=None,
    X_df=None,
    ids=None,
)
```

Compute the predictions for the next `h` steps.

**Parameters:**

| Name                      | Type                                    | Description                                                                                                                                                                                                                                                                                                   | Default           |
| ------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `h`                       | <code>[int](#int)</code>                | Number of periods to predict.                                                                                                                                                                                                                                                                                 | *required*        |
| `before_predict_callback` | <code>[callable](#callable)</code>      | Function to call on the features before computing the predictions. This function will take the input dataframe that will be passed to the model for predicting and should return a dataframe with the same structure. The series identifier is on the index. Defaults to None.                                | <code>None</code> |
| `after_predict_callback`  | <code>[callable](#callable)</code>      | Function to call on the predictions before updating the targets. This function will take a pandas Series with the predictions and should return another one with the same structure. The series identifier is on the index. Defaults to None.                                                                 | <code>None</code> |
| `new_df`                  | <code>pandas or polars DataFrame</code> | Series data of new observations for which forecasts are to be generated. This dataframe should have the same structure as the one used to fit the model, including any features and time series data. If `new_df` is not None, the method will generate forecasts for the new observations. Defaults to None. | <code>None</code> |
| `level`                   | <code>list of ints or floats</code>     | Confidence levels between 0 and 100 for prediction intervals. Defaults to None.                                                                                                                                                                                                                               | <code>None</code> |
| `X_df`                    | <code>pandas or polars DataFrame</code> | Dataframe with the future exogenous features. Should have the id column and the time column. Defaults to None.                                                                                                                                                                                                | <code>None</code> |
| `ids`                     | <code>list of str</code>                | List with subset of ids seen during training for which the forecasts should be computed. Defaults to None.                                                                                                                                                                                                    | <code>None</code> |

**Returns:**

| Type                                                | Description                                                                                     |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| <code>[DFType](#utilsforecast.compat.DFType)</code> | pandas or polars DataFrame: Predictions for each serie and timestep, with one column per model. |

#### `MLForecast.preprocess`

```python theme={null}
preprocess(
    df,
    id_col="unique_id",
    time_col="ds",
    target_col="y",
    static_features=None,
    dropna=True,
    keep_last_n=None,
    max_horizon=None,
    horizons=None,
    return_X_y=False,
    as_numpy=False,
    weight_col=None,
    validate_data=True,
)
```

Add the features to `data`.

**Parameters:**

| Name              | Type                          | Description                                                                                                                                  | Default                   |
| ----------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `df`              | <code>pandas DataFrame</code> | Series data in long format.                                                                                                                  | *required*                |
| `id_col`          | <code>[str](#str)</code>      | Column that identifies each serie. Defaults to 'unique\_id'.                                                                                 | <code>'unique\_id'</code> |
| `time_col`        | <code>[str](#str)</code>      | Column that identifies each timestep, its values can be timestamps or integers. Defaults to 'ds'.                                            | <code>'ds'</code>         |
| `target_col`      | <code>[str](#str)</code>      | Column that contains the target. Defaults to 'y'.                                                                                            | <code>'y'</code>          |
| `static_features` | <code>list of str</code>      | Names of the features that are static and will be repeated when forecasting. Defaults to None.                                               | <code>None</code>         |
| `dropna`          | <code>[bool](#bool)</code>    | Drop rows with missing values produced by the transformations. Defaults to True.                                                             | <code>True</code>         |
| `keep_last_n`     | <code>[int](#int)</code>      | Keep only these many records from each serie for the forecasting step. Can save time and memory if your features allow it. Defaults to None. | <code>None</code>         |
| `max_horizon`     | <code>[int](#int)</code>      | Train this many models, where each model will predict a specific horizon. Defaults to None.                                                  | <code>None</code>         |
| `horizons`        | <code>list of int</code>      | Train models only for specific horizons (1-indexed). Mutually exclusive with max\_horizon. Defaults to None.                                 | <code>None</code>         |
| `return_X_y`      | <code>[bool](#bool)</code>    | Return a tuple with the features and the target. If False will return a single dataframe. Defaults to False.                                 | <code>False</code>        |
| `as_numpy`        | <code>[bool](#bool)</code>    | Cast features to numpy array. Only works for `return_X_y=True`. Defaults to True.                                                            | <code>False</code>        |
| `weight_col`      | <code>[str](#str)</code>      | Column that contains the sample weights. Defaults to None.                                                                                   | <code>None</code>         |
| `validate_data`   | <code>[bool](#bool)</code>    | Run data quality validations before preprocessing. Warns about missing dates and raises on duplicate rows. Defaults to True.                 | <code>True</code>         |

**Returns:**

| Type                                                                                                                                                                     | Description                                                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| <code>[Union](#typing.Union)\[[DFType](#utilsforecast.compat.DFType), [Tuple](#typing.Tuple)\[[DFType](#utilsforecast.compat.DFType), [ndarray](#numpy.ndarray)]]</code> | DataFrame or tuple of pandas Dataframe and a numpy array: `df` plus added features and target(s). |

#### `MLForecast.fit_models`

```python theme={null}
fit_models(X=None, y=None, models_fit_kwargs=None, generator_factory=None)
```

Manually train models. Use this if you called `MLForecast.preprocess` beforehand.

**Parameters:**

| Name                | Type                                                   | Description                                                                            | Default           |
| ------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------- |
| `X`                 | <code>pandas or polars DataFrame or numpy array</code> | Features (for recursive forecasting).                                                  | <code>None</code> |
| `y`                 | <code>numpy array</code>                               | Target (for recursive forecasting).                                                    | <code>None</code> |
| `models_fit_kwargs` | <code>[dict](#dict)</code>                             | Keyword arguments for each model's fit method.                                         | <code>None</code> |
| `generator_factory` | <code>[callable](#callable)</code>                     | Factory function that returns an iterator yielding (h, X\_h, y\_h) tuples per horizon. | <code>None</code> |

**Returns:**

| Name         | Type                                                       | Description                          |
| ------------ | ---------------------------------------------------------- | ------------------------------------ |
| `MLForecast` | <code>[MLForecast](#mlforecast.forecast.MLForecast)</code> | Forecast object with trained models. |

#### `MLForecast.cross_validation`

```python theme={null}
cross_validation(
    df,
    n_windows,
    h,
    id_col="unique_id",
    time_col="ds",
    target_col="y",
    step_size=None,
    static_features=None,
    dropna=True,
    keep_last_n=None,
    refit=True,
    max_horizon=None,
    horizons=None,
    before_predict_callback=None,
    after_predict_callback=None,
    prediction_intervals=None,
    level=None,
    input_size=None,
    fitted=False,
    as_numpy=False,
    weight_col=None,
    validate_data=True,
)
```

Perform time series cross validation.
Creates `n_windows` splits where each window has `h` test periods,
trains the models, computes the predictions and merges the actuals.

**Parameters:**

| Name                      | Type                                                                      | Description                                                                                                                                                                                                                                                                    | Default                   |
| ------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| `df`                      | <code>pandas or polars DataFrame</code>                                   | Series data in long format.                                                                                                                                                                                                                                                    | *required*                |
| `n_windows`               | <code>[int](#int)</code>                                                  | Number of windows to evaluate.                                                                                                                                                                                                                                                 | *required*                |
| `h`                       | <code>[int](#int)</code>                                                  | Forecast horizon.                                                                                                                                                                                                                                                              | *required*                |
| `id_col`                  | <code>[str](#str)</code>                                                  | Column that identifies each serie. Defaults to 'unique\_id'.                                                                                                                                                                                                                   | <code>'unique\_id'</code> |
| `time_col`                | <code>[str](#str)</code>                                                  | Column that identifies each timestep, its values can be timestamps or integers. Defaults to 'ds'.                                                                                                                                                                              | <code>'ds'</code>         |
| `target_col`              | <code>[str](#str)</code>                                                  | Column that contains the target. Defaults to 'y'.                                                                                                                                                                                                                              | <code>'y'</code>          |
| `step_size`               | <code>[int](#int)</code>                                                  | Step size between each cross validation window. If None it will be equal to `h`. Defaults to None.                                                                                                                                                                             | <code>None</code>         |
| `static_features`         | <code>list of str</code>                                                  | Names of the features that are static and will be repeated when forecasting. Defaults to None.                                                                                                                                                                                 | <code>None</code>         |
| `dropna`                  | <code>[bool](#bool)</code>                                                | Drop rows with missing values produced by the transformations. Defaults to True.                                                                                                                                                                                               | <code>True</code>         |
| `keep_last_n`             | <code>[int](#int)</code>                                                  | Keep only these many records from each serie for the forecasting step. Can save time and memory if your features allow it. Defaults to None.                                                                                                                                   | <code>None</code>         |
| `max_horizon`             | <code>[int](#int)</code>                                                  | Train this many models, where each model will predict a specific horizon. Defaults to None.                                                                                                                                                                                    | <code>None</code>         |
| `horizons`                | <code>list of int</code>                                                  | Train models only for specific horizons (1-indexed). Mutually exclusive with max\_horizon. Defaults to None.                                                                                                                                                                   | <code>None</code>         |
| `refit`                   | <code>[bool](#bool) or [int](#int)</code>                                 | 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. Defaults to True.                                                     | <code>True</code>         |
| `before_predict_callback` | <code>[callable](#callable)</code>                                        | Function to call on the features before computing the predictions. This function will take the input dataframe that will be passed to the model for predicting and should return a dataframe with the same structure. The series identifier is on the index. Defaults to None. | <code>None</code>         |
| `after_predict_callback`  | <code>[callable](#callable)</code>                                        | Function to call on the predictions before updating the targets. This function will take a pandas Series with the predictions and should return another one with the same structure. The series identifier is on the index. Defaults to None.                                  | <code>None</code>         |
| `prediction_intervals`    | <code>[PredictionIntervals](#mlforecast.utils.PredictionIntervals)</code> | Configuration to calibrate prediction intervals (Conformal Prediction). Defaults to None.                                                                                                                                                                                      | <code>None</code>         |
| `level`                   | <code>list of ints or floats</code>                                       | Confidence levels between 0 and 100 for prediction intervals. Defaults to None.                                                                                                                                                                                                | <code>None</code>         |
| `input_size`              | <code>[int](#int)</code>                                                  | Maximum training samples per serie in each window. If None, will use an expanding window. Defaults to None.                                                                                                                                                                    | <code>None</code>         |
| `fitted`                  | <code>[bool](#bool)</code>                                                | Store the in-sample predictions. Defaults to False.                                                                                                                                                                                                                            | <code>False</code>        |
| `as_numpy`                | <code>[bool](#bool)</code>                                                | Cast features to numpy array. Defaults to True.                                                                                                                                                                                                                                | <code>False</code>        |
| `weight_col`              | <code>[str](#str)</code>                                                  | Column that contains the sample weights. Defaults to None.                                                                                                                                                                                                                     | <code>None</code>         |
| `validate_data`           | <code>[bool](#bool)</code>                                                | Run data quality validations on the full dataset before cross-validation. Warns about missing dates and raises on duplicate rows. Defaults to True.                                                                                                                            | <code>True</code>         |

**Returns:**

| Type                                                | Description                                                                                                                                           |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| <code>[DFType](#utilsforecast.compat.DFType)</code> | pandas or polars DataFrame: Predictions for each window with the series id, timestamp, last train date, target value and predictions from each model. |

#### `MLForecast.from_cv`

```python theme={null}
from_cv(cv)
```