Nixtla · mintlify · Aug 31, 2026 · Aug 31, 2026
diff --git a/statsforecast/docs/how-to-guides/exogenous.html.mdx b/statsforecast/docs/how-to-guides/exogenous.html.mdx
@@ -1,8 +1,9 @@
 ---
 title: Exogenous Regressors
+description: Forecast with exogenous regressors in StatsForecast, pass future values through X_df, access fitted AutoARIMA coefficients, and fix common errors.
 ---
 
 > In this notebook, we’ll incorporate exogenous regressors to a
 > StatsForecast model.

 > **Prerequisites**
@@ -13,16 +14,16 @@

 ## Introduction

 **Exogenous regressors** are variables that can affect the values of a
 time series. They may not be directly related to the variable that is
 being forecasted, but they can still have an impact on it. Examples of
 exogenous regressors are weather data, economic indicators, or
 promotional sales. They are typically collected from external sources
 and by incorporating them into a forecasting model, they can improve the
 accuracy of our predictions.

 By the end of this tutorial, you’ll have a good understanding of how to
 incorporate exogenous regressors into
 [StatsForecast](../../src/core/models.html)’s models. Furthermore,
 you’ll see how to evaluate their performance and decide whether or not
 they can help enhance the forecast.
@@ -32,15 +33,17 @@
 1.  Install libraries
 2.  Load and explore the data
 3.  Split train/test set
 4.  Add exogenous regressors
 5.  Create future exogenous regressors
 6.  Train model
 7.  Evaluate results
+8.  Access the fitted coefficients
+9.  Troubleshooting
 
 > **Tip**
 >
 > You can use Colab to run this Notebook interactively
 > <a href="https://colab.research.google.com/github/Nixtla/statsforecast/blob/main/nbs/docs/how-to-guides/Exogenous.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>

 ## Install libraries

@@ -65,15 +68,15 @@
 dataset. This series represents the daily sales of a product in a
 Walmart store. The product-store combination that we’ll use in this
 notebook has `unique_id = FOODS_3_586_CA_3`. This time series was chosen
 because it is not intermittent and has exogenous regressors that will be
 useful for forecasting.

 We’ll load the following dataframes:

 -   `Y_ts`: (pandas DataFrame) The target time series with columns
    \[`unique_id`, `ds`, `y`\].
 -   `X_ts`: (pandas DataFrame) Exogenous time series with columns
    \[`unique_id`, `ds`, exogenous regressors\].

 ```python
 base_url = 'https://datasets-nixtla.s3.amazonaws.com'
@@ -88,8 +91,8 @@
 method has multiple parameters, and the required ones to generate the
 plots in this notebook are explained below.

 -   `df`: A pandas dataframe with columns \[`unique_id`, `ds`, `y`\].
 -   `forecasts_df`: A pandas dataframe with columns \[`unique_id`,
    `ds`\] and models.
 -   `engine`: str = `matplotlib`. It can also be `plotly`. `plotly`
    generates interactive plots, while `matplotlib` generates static
@@ -106,14 +109,14 @@

 ![](./Exogenous_files/figure-markdown_strict/cell-6-output-1.png)

 The M5 Competition included several exogenous regressors. Here we’ll use
 the following two.

 -   `sell_price`: The price of the product for the given store. The
    price is provided per week.
 -   `snap_CA`: A binary variable indicating whether the store allows
    SNAP purchases (1 if yes, 0 otherwise). SNAP stands for Supplement
    Nutrition Assitance Program, and it gives individuals and families
    money to help them purchase food products.

 ```python
@@ -121,7 +124,7 @@
 X_ts.head()
 ```

 |     | unique_id        | ds         | sell_price | snap_CA |
 |-----|------------------|------------|------------|---------|
 | 0   | FOODS_3_586_CA_3 | 2011-01-29 | 1.48       | 0       |
 | 1   | FOODS_3_586_CA_3 | 2011-01-30 | 1.48       | 0       |
@@ -136,7 +139,7 @@
 X_ts['unique_id'] = X_ts.unique_id.astype(str)
 ```

 We can plot the exogenous regressors using `plotly`. We could use
 `statsforecast.plot`, but then one of the regressors must be renamed
 `y`, and the name must be changed back to the original before generating
 the forecast.
@@ -169,16 +172,16 @@
 X_test = X_ts.query('ds in @dtest')
 ```

 ## Add exogenous regressors

 The exogenous regressors need to be place after the target variable `y`.

 ```python
 train = Y_train.merge(X_ts, how = 'left', on = ['unique_id', 'ds']) 
 train.head()
 ```

 |     | unique_id        | ds         | y    | sell_price | snap_CA |
 |-----|------------------|------------|------|------------|---------|
 | 0   | FOODS_3_586_CA_3 | 2011-01-29 | 56.0 | 1.48       | 0       |
 | 1   | FOODS_3_586_CA_3 | 2011-01-30 | 55.0 | 1.48       | 0       |
@@ -186,7 +189,7 @@
 | 3   | FOODS_3_586_CA_3 | 2011-02-01 | 57.0 | 1.48       | 1       |
 | 4   | FOODS_3_586_CA_3 | 2011-02-02 | 54.0 | 1.48       | 1       |

 ## Create future exogenous regressors

 We need to include the future values of the exogenous regressors so that
 we can produce the forecasts. Notice that we already have this
@@ -196,7 +199,7 @@
 X_test.head()
 ```

 |      | unique_id        | ds         | sell_price | snap_CA |
 |------|------------------|------------|------------|---------|
 | 1941 | FOODS_3_586_CA_3 | 2016-05-23 | 1.68       | 0       |
 | 1942 | FOODS_3_586_CA_3 | 2016-05-24 | 1.68       | 0       |
@@ -206,8 +209,8 @@

 > **Important**
 >
 > If the future values of the exogenous regressors are not available,
 > then they must be forecasted or the regressors need to be eliminated
 > from the model. Without them, it is not possible to generate the
 > forecast.

@@ -233,7 +236,7 @@
 Next, we need to instantiate a new StatsForecast object, which has the
 following parameters.

 -   `df`: The dataframe with the training data.
 -   `models`: The list of models defined in the previous step.
 -   `freq`: A string indicating the frequency of the data. See [pandas’
    available
@@ -254,7 +257,7 @@

 -   `h`: An integer that represents the forecast horizon. In this case,
    we’ll forecast the next 28 days.
 -   `X_df`: A pandas dataframe with the future values of the exogenous
    regressors.
 -   `level`: A list of floats with the confidence levels of the
    prediction intervals. For example, `level=[95]` means that the range
@@ -269,7 +272,7 @@
 fcst.head()
 ```

 |     | unique_id        | ds         | AutoARIMA | AutoARIMA-lo-95 | AutoARIMA-hi-95 |
 |-----|------------------|------------|-----------|-----------------|-----------------|
 | 0   | FOODS_3_586_CA_3 | 2016-05-23 | 72.956276 | 44.109070       | 101.803482      |
 | 1   | FOODS_3_586_CA_3 | 2016-05-24 | 71.138611 | 40.761467       | 101.515747      |
@@ -297,7 +300,7 @@
 res.head()
 ```

 |     | unique_id        | ds         | y    | AutoARIMA | AutoARIMA-lo-95 | AutoARIMA-hi-95 |
 |-----|------------------|------------|------|-----------|-----------------|-----------------|
 | 0   | FOODS_3_586_CA_3 | 2016-05-23 | 66.0 | 72.956276 | 44.109070       | 101.803482      |
 | 1   | FOODS_3_586_CA_3 | 2016-05-24 | 62.0 | 71.138611 | 40.761467       | 101.515747      |
@@ -314,9 +317,9 @@
 The MAE with exogenous regressors is 11.42
 ```

 To check whether the exogenous regressors were useful or not, we need to
 generate the forecast again, now without them. To do this, we simply
 pass the dataframe without exogenous variables to the `forecast` method.
 Notice that the data only includes `unique_id`, `ds`, and `y`. The
 `forecast` method no longer requires the future values of the exogenous
 regressors `X_df`.
@@ -339,5 +342,62 @@
 ```

 Hence, we can conclude that using `sell_price` and `snap_CA` as external
 regressors helped improve the forecast.
 
+## Access the fitted coefficients
+
+ARIMA-family models with exogenous regressors are *regressions with
+ARIMA errors*. The exogenous regressors enter the model linearly and
+additively:
+
+$$\hat{y}_t = \text{ARMA part} + C_1 x_{1,t} + C_2 x_{2,t} + \dots + C_N x_{N,t}$$
+
+This means the contribution of each regressor to a given prediction is
+its coefficient multiplied by its value at that point.
+
+To inspect the coefficients, train the model with the `fit` method
+(rather than `forecast`) and access the fitted model of each series
+through the `fitted_` attribute. `fitted_` is an array of shape
+(number of series, number of models).
+
+```python
+sf.fit(df=train)
+
+result = sf.fitted_[0, 0].model_  # first series, first model
+print(result['coef'])
+```
+
+`result['coef']` is a dictionary. The AR and MA terms use keys like
+`ar1`, `ma1`, `sar1`, and `sma1`. The exogenous regressors use the keys
+`ex_1`, `ex_2`, and so on, in the same order as the columns of the
+training dataframe. When the model includes a constant, the dictionary
+also contains an `intercept` or `drift` key.
+
+## Troubleshooting
+
+Common errors when forecasting with exogenous regressors:
+
+**`ValueError: xreg is rank deficient`**. `AutoARIMA` checks that the
+training exogenous regressors are linearly independent before fitting.
+The check drops constant columns and then stacks the remaining columns
+with a linear trend, so it fails when one column is a linear combination
+of the others or of a linear time trend. To fix it, remove redundant
+columns. For example, drop one category from a full set of one-hot
+encoded dummies, or remove a column that increases linearly with time.
+This check only applies to the training data. The future values in
+`X_df` are only multiplied by the fitted coefficients, so linear
+dependence that appears only in the forecast horizon does not raise this
+error.
+
+**`ValueError: Expected X to have shape (a, b), but got (c, d)`**.
+`X_df` must contain the `unique_id` and `ds` columns plus exactly the
+same exogenous columns used in training, with one row per series for
+each timestamp in the forecast horizon. An extra column (such as a
+leftover `y`) or a missing column changes the shape and raises this
+error.
+
+**`Models require the following exogenous features ...`**. If the
+training data contains exogenous columns and a model that supports them
+is used, the `forecast` method requires their future values through
+`X_df`.
+
diff --git a/statsforecast/docs/tutorials/simulation.html.mdx b/statsforecast/docs/tutorials/simulation.html.mdx
@@ -1,5 +1,6 @@
 ---
 title: Trajectory Simulation
+description: Generate simulated future trajectories with the StatsForecast simulate method, choose error distributions, and speed up large AutoARIMA simulations.
 ---
 
 > This tutorial demonstrates how to generate sample trajectories
@@ -45,7 +46,7 @@
 > **Tip**
 >
 > You can use Colab to run this Notebook interactively
 > <a href="https://colab.research.google.com/github/Nixtla/statsforecast/blob/main/nbs/docs/tutorials/Simulation.ipynb" target="_parent"><img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/></a>

 ## Install libraries

@@ -79,7 +80,7 @@
 df.head()
 ```

 |     | unique_id | ds  | y     |
 |-----|-----------|-----|-------|
 | 0   | H1        | 1   | 605.0 |
 | 1   | H1        | 2   | 586.0 |
@@ -107,7 +108,7 @@
 sims.head()
 ```

 |     | unique_id | ds  | sample_id | AutoARIMA  |
 |-----|-----------|-----|-----------|------------|
 | 0   | H1        | 749 | 0         | 610.915688 |
 | 0   | H1        | 750 | 0         | 563.314544 |
@@ -133,11 +134,11 @@
 -   **‘normal’**: Standard normal distribution (default)
 -   **‘t’**: Student’s t-distribution (heavy tails, good for financial
    data)
 -   **‘bootstrap’**: Resample from empirical residuals (non-parametric)
 -   **‘laplace’**: Laplace distribution (sharper peak, heavier tails)
 -   **‘skew-normal’**: Skewed normal distribution (for asymmetric
    errors)
 -   **‘ged’**: Generalized Error Distribution (flexible shape)

 Let’s demonstrate with different distributions. Note that parameters are
 automatically estimated from residuals.
@@ -188,7 +189,7 @@
    (lower = heavier tails)
 -   **‘skew-normal’**: `{'skewness': alpha}` - Controls asymmetry
    (negative = left skew, positive = right skew)
 -   **‘ged’**: `{'shape': beta}` - Controls tail behavior (1 = Laplace,
    2 = Normal, higher = lighter tails)

 ```python
@@ -241,7 +242,7 @@
 2.  **t-distribution (automatic)** - Parameters estimated from residuals
 3.  **t-distribution (df=3)** - User-specified heavy tails for stress
    testing
 4.  **Bootstrap** - Non-parametric resampling from actual residuals

 ```python
 def plot_sims(df, sims, title, color='blue'):
@@ -367,6 +368,51 @@
    Bootstrap 669.94  165.51 324.97 1059.47         429.79          913.07
 ```
 
+## Handling Large Simulations
+
+The output of `simulate` contains one row per series, per path, per
+horizon step, so its size grows as `n_series * n_paths * h`. When this
+product exceeds 100,000 points, StatsForecast emits a warning:
+
+``` text
+Generating 4,800,000 simulation points. Large simulations may consume significant memory and time.
+```
+
+If a simulation is slow or consumes too much memory, consider the
+following.
+
+**Fitting dominates the runtime for `AutoARIMA`.** Each call to
+`StatsForecast.simulate` fits the models before generating paths. For
+`AutoARIMA`, this includes the full model order search for every
+series, which is often more expensive than the path generation itself.
+There are two ways to avoid paying this cost repeatedly:
+
+-   Fit once and simulate many times using the model-level API. When
+    `y` is not passed to the model’s `simulate` method, it reuses the
+    already fitted model instead of fitting a new one:
+
+    ```python
+    model = AutoARIMA(season_length=24)
+    model.fit(y=df['y'].values)
+
+    # Reuses the fitted model; no new order search is performed
+    paths = model.simulate(h=48, n_paths=100, seed=42)  # shape (n_paths, h)
+    ```
+
+-   Skip the order search entirely by using the
+    [ARIMA](../../src/core/models.html) model with a fixed order
+    instead of `AutoARIMA`.
+
+**Parallelism is across series, not paths.** Setting `n_jobs=-1` in
+`StatsForecast` distributes the work across series. It speeds up
+simulations over many series, but it does not help when simulating many
+paths for a single series.
+
+**Reduce the number of points.** Lowering `n_paths` or `h`, or
+simulating a subset of series at a time, reduces memory usage and
+runtime proportionally. Passing a `seed` keeps results reproducible
+across runs, including when `n_jobs > 1`.
+
 ## References
 
 [Rob J. Hyndman and George Athanasopoulos (2018). “Forecasting