DOC: Improve explanation for exog forecasts

Add additional section to example notebook

Author: bashtage

arch/tests/univariate/test_forecast.py

@@ -1205,3 +1205,22 @@ def test_forecast_simulation_horizon_1():
     res = mod.fit(first_obs=0, last_obs=98)
     res.forecast(start=1, x=x, method="simulation", simulations=2)
     res.forecast(start=1, x=x, method="simulation", simulations=1)
+
+
+def test_forecast_start():
+    rg = np.random.default_rng(0)
+    y = rg.standard_normal(10)
+    x = pd.DataFrame(rg.standard_normal((10, 1)), columns=["x"])
+    mod = ARX(y, x=x, lags=3)
+    res = mod.fit(first_obs=0, last_obs=98)
+    fcast = res.forecast(start=2, x=x)
+    fcast2 = res.forecast(start=2, method="simulation", simulations=1, x=x)
+    assert_allclose(fcast.mean, fcast2.mean)
+
+    c, p1, p2, p3, b, _ = res.params
+    oos = np.full((8, 1), np.nan)
+    for i in range(2, 9):
+        oos[i - 2, 0] = (
+            c + p1 * y[i] + p2 * y[i - 1] + p3 * y[i - 2] + b * x.iloc[i + 1, 0]
+        )
+    assert_allclose(fcast.mean, oos)

arch/univariate/base.py

@@ -1003,6 +1003,8 @@ def forecast(
               with a horizon of 10, then the input can be (1, 10). Alternatively,
               if the original data had 1000 observations, then the input can be
               (1000, 10), and only the final row is used to produce forecasts.
+              When using an (nobs, horizon) array, the values much be aligned
+              so that all values in row t are all out-of-sample at time-t.
             * A dictionary of 2-d array-like: This format is identical to the
               previous except that the dictionary keys must match the names of
               the exog variables.  Requires that the exog variables were
@@ -1014,7 +1016,7 @@ def forecast(
 
             Due to the complexity required to accommodate all scenarios, please
             see the example notebook that demonstrates the valid formats for
-            x.
+            x, and discusses alignment.
 
             .. versionadded:: 4.19
 

examples/univariate_forecasting_with_exogenous_variables.ipynb

@@ -711,7 +711,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.7"
+   "version": "3.9.20"
   }
  },
  "nbformat": 4,