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

# Read the forecast distribution

> Interpret joint probabilities, numeric quantiles, omitted mass, and transport diagnostics.

Use the joint atoms when your decision depends on a combination of outcomes, such as high demand and low generation. Use `marginals` for a summary of one target. The `branches` list is limited by `max_branches`. Use `receipt.atoms` when you need the full retained forecast support.

| Field inside `transition_prediction.futures` | Meaning |
| - | - |
| `status` | `predicted` or `abstained` for an enabled futures learner. |
| `abstention_reason` | Why support was insufficient or the request could not be forecast. |
| `branches` | Displayed joint target values and probabilities. Each `path_values` map uses full target paths. |
| `receipt.atoms` | Retained joint outcomes for the issued forecast, including atoms past the display cap. Each atom can expose its issued `probability` and the corresponding `prior` and `conditional` weights. |
| `branch_count` | Total distinct joint outcomes represented before display truncation. |
| `omitted_probability` | Mass not displayed because of the branch limit. |
| `support_count` | Historical support used to construct this forecast. |
| `observed_paths` | Declared inputs actually available in this request. |
| `marginals` | Per-target summaries derived from the joint distribution. |
| `conditioning_weight` | Current weight given to evidence-conditioned rather than unconditioned probabilities. It is not the probability that the forecast is correct. |
| `resolved_support` | Calibration observations for the relevant evidence mask/group/action. |
| `calibration_status` | `unvalidated` or `prequentially_scored`. The latter means issued forecasts have been scored, not that accuracy is guaranteed. |
| `numeric_transport` | Whether numeric transport was active and its validation diagnostics. |
| `model_version` | Version associated with the forecast. |

Numeric marginals contain `mean` and `quantiles` with keys `"0.05"`, `"0.5"`,
and `"0.95"`. Categorical marginals contain `probabilities`. Category keys are
canonical JSON: a boolean key is `"true"`, while a string category's key includes
its JSON quotes. Use `json.loads(key)` when decoding those labels in Python.

The displayed branch probabilities plus `omitted_probability` should sum to one,
within floating-point tolerance. Do not rescale the visible branches to one and
silently discard omitted mass. Numeric branches are distribution representatives,
not a statement that only those exact physical values can occur.

## Read the joint atoms

Read `transition_prediction.futures.receipt.atoms` when `status` is `predicted`. The atom list describes the support used for this forecast, which is bounded by `max_support`. Check that the returned weights sum to one within rounding tolerance before calculating a joint event or expected cost. When your response contains only displayed branches, carry `omitted_probability` into any calculation that depends on the missing mass.

This example calculates the probability of high demand and low generation in the same interval. Use thresholds in the same units as the atoms. The issued distribution uses `probability`. To compare conditioning with its prior after the outcome arrives, score the same support with `prior` and `conditional` separately. Both sets of weights are available in the receipt, so that comparison needs no additional query.

```python theme={null}
from math import fsum, isclose


def joint_event_probability(futures, event, weight="probability"):
    if futures["status"] != "predicted":
        raise ValueError("The forecast abstained.")

    atoms = (futures.get("receipt") or {}).get("atoms")
    if not atoms:
        raise ValueError("The forecast receipt has no atoms.")

    weights = [float(atom[weight]) for atom in atoms]
    if not isclose(fsum(weights), 1.0, rel_tol=1e-6):
        raise ValueError("The atom weights do not sum to one.")

    return fsum(
        probability
        for atom, probability in zip(atoms, weights)
        if event(atom.get("path_values") or atom["values"])
    )


forecast = reply["transition_prediction"]["futures"]
breach_probability = joint_event_probability(
    forecast,
    lambda values: (
        values["values.next_load_mw"] > 40
        and values["values.next_wind_mw"] < 10
    ),
)
```

The [joint demand and generation recipe](https://docs.reilabs.org/docs/neuroadapt/futures/examples.md#forecast-joint-demand-and-generation) uses these target paths. For its physical-unit thresholds, restore any scaling before calling the event predicate or express the thresholds on the sent scale.

## Forecast a changing numeric level

Set this inside the transition declaration:

```json theme={null}
{
  "numeric_min_skill": 0.0,
  "numeric_ridge": 0.00000001,
  "futures": {
    "enabled": true,
    "numeric_transport": "linear_residual"
  }
}
```

Put this fragment under `learning.transition` in the Domain declaration. To tune a fit that is sensitive to large or collinear inputs, see [Tune a Domain for your stream](https://docs.reilabs.org/docs/neuroadapt/futures/configuration.md#tune-a-domain-for-your-stream).

The mode learns how the numeric outcome's typical level depends on current
inputs, then carries the observed residual uncertainty around that level.
It is useful when returning only absolute historical outcomes would miss a
changing numeric level. Multiple targets still form a joint forecast.

Inspect `futures.numeric_transport.status`:

* `active`: one or more numeric targets passed the transport validation gate.
* `inactive`: no applicable transport was requested or available for these inputs.
* `unavailable`: a transport fit could not pass the support/validation conditions.

If transport cannot be used, the empirical futures forecast can still be returned.
Check `target_paths` to see which numeric targets were transported.

`linear_residual` is not a feedback-policy model class. It does not mean
`learning.training.model_type: "linear_residual"`, which is invalid.
The transition's existing `numeric_model` setting separately controls the point
predictor. Selecting numeric transport does not silently switch that predictor.

Quantile bounds are forecast summaries, not guaranteed real-world coverage.
Transport does not automatically enforce physical limits on predicted values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.