Forecast

Forecast projects selected variables forward in time, returning a trajectory for each with a confidence band that widens further into the future. It is the temporal counterpart of Prediction: where Prediction answers "what outcome is most likely for this input?", Forecast answers "how will these variables evolve over the next n steps?"

Forecast is available on temporal Digital Twins — those built on time-series data. The system auto-detects a time column and sets the twin's type to Temporal when you create it; no separate setup is needed. For the workflow that produces a twin in the first place, see Step 5: Build Digital Twin.

---

Starting a simulation

Open a temporal Digital Twin, open its Simulations row (or click Run Simulation in the toolbar), then click New Simulation. The type picker for a temporal twin differs from the static one: it offers the time-aware family, with Forecast in Prediction's place and the temporal-only Causal Health Monitor alongside the counterparts of the other static types (see Temporal Simulations).

The temporal twin's simulation menu, with generated Quick Start suggestions above the type cards. Choose Forecast to project variables forward in time.

Choose Forecast to open the setup.

---

Step 1: Select forecast targets

The forecast targets are the time-series variables you want projected forward. Each selected target is forecast independently across the horizon. Pick as many as you need; the result charts one at a time, and you switch between them from the Forecast Summary table.

---

Step 2: Forecast from (optional)

By default the forecast begins at the last date in the training data. Set a start time here — relative steps, or a custom date — to begin the projection later. It cannot begin earlier: both inputs are floored at the training end, and an earlier value is adjusted back up. To anchor the forecast before the end of training, use the Origin in Step 3. A timeline on this step shows your training range against the forecast range, so you can see how far past the data you are projecting.

---

Step 3: Origin (as-of) (optional)

Anchor the forecast to an earlier point in the data and project forward from there, which is how a backtest aligns a forecast against periods the model never saw.

---

Step 4: Forecast horizon

The horizon sets how many time steps ahead the simulation covers: a count and a time unit, with a readout of the date range it covers and how much observed training data the model holds. A horizon of 60 days on a model trained over 364 days, for example, extends two months beyond the last observation.

Forecasting far beyond the training range is possible, but the confidence band widens the further out you go — the model is honest about growing uncertainty.

---

Step 5: Confidence level

The default of 0.95 means the model is 95% confident the actual value will fall within the shown band. Higher confidence widens the band; lower narrows it. Leave the default unless you have a specific reason to change it.

The start of the Forecast setup: pick the targets to project — the result charts whichever one is selected.

---

Running the forecast

Select the twin versions to run on, review the configuration summary, and click Run Simulation. Validate checks the setup without running it.

The configuration summary confirms what is being forecast, over what horizon, at what confidence — the last check before running.

---

Reading the result

The result page opens with one chart, for the target you have selected, then the Forecast Summary table of net change per target — select a row to chart that variable above — and the Forecast Results table below it. Every target you selected is a row in the Forecast Summary; select its row to chart it. Additional variables collapses the extra variables the model forecast alongside your targets, because they are causally connected to them.

A completed Forecast. The selected target is charted with its projected trajectory and confidence band; the summary table reports the net change over the horizon, and selecting a row charts that variable instead.

The chart plots the variable's history up to the forecast start, then the projected trajectory with its confidence band shaded around it. The band widens with the horizon, reflecting accumulating uncertainty. Per-chart controls surface the underlying reasoning:

• Changepoints — the points where the trajectory shifts direction or slope.

• Why — the causal drivers behind the projected movement.

• Bounds — toggle the confidence band on and off.

The Forecast Summary reports the net change for each target over the horizon, and the Forecast Results Table holds the underlying values for export. The whole run can be exported as a report, and the report to PDF.

---

Outside the UI

This simulation runs from the Python SDK and from the REST API, with the same configuration the wizard collects.

>>> twin.forecast(horizon=24, targets=["revenue"])

Over REST it is a scenario on POST /api/v1/workspaces/{workspaceId}/simulations with "type": "forecast", or panel_forecast on a multi-environment twin. Each step of a numeric target can carry an attribution breaking the prediction into trend, seasonal, level and drift components and a per-parent contribution. Categorical targets return probabilities and carry no attribution.

See Working with Digital Twins for the SDK, and Running Simulations over REST for the request body.

---

Other Simulation Types

Forecast is the temporal analogue of Prediction; a temporal twin's menu offers time-aware versions of the other types too — see Temporal Simulations. The static types are:

• Prediction — the most likely outcome for a specific input.

• Intervention — change a variable and observe propagation.

• Optimization — find the input combination that best meets a goal.

• Best Action — the minimum change needed to reach a target.

• Explanation — the drivers and impacts behind an outcome.

See Simulation Types for the full picture and Step 6: Run Simulations for the general overview.