simulate.DoResult

Container for propagated posterior draws under an intervention.

Usage

simulate.DoResult(
    *,
    ds,
    scenario="do",
    evidence=None,
    observed_by_time=None,
)

Supports .mean(var), .hdi(var), and contrast arithmetic via subtraction (scenario - baseline).

For panel do(simulate_over="time"), the result also stores per-time-step draws accessible via by_time().

Internal storage is an xarray.Dataset exposed as dataset with named dims ("chain", "draw") for cross-sectional draws and an additional "time" dim for panel per-time draws. Public accessors such as draws() flatten chain/draw (and unit when present) into a 1-D numpy sample vector.

Parameters

ds: xr.Dataset

Labelled posterior draws with dims ("chain", "draw") and, optionally, "unit" or "time".

scenario: str = "do"

Result origin. Internal metadata prevents contrasts between population-level and unit-level counterfactual simulations.

evidence: Mapping[str, float] | None = None

Individual evidence associated with a counterfactual result.

observed_by_time: Mapping[str, np.ndarray] | None = None
Unit-mean observed series per variable, aligned to time_index.

Attributes

Name Description
dataset Labeled posterior draws as an xarray.Dataset.

dataset

Labeled posterior draws as an xarray.Dataset.

dataset: xr.Dataset

Cross-sectional results use dims ("chain", "draw"); panel do(simulate_over="time") results add "time". For a flat (n_samples,) numpy view, use draws().

Methods

Name Description
__sub__() Element-wise contrast between two DoResults.
by_time() Return per-time-step posterior draws, shape (n_times, n_samples).
draws() Return raw posterior draws for var under this intervention.
hdi() Return the highest-density interval for var.
mean() Return the posterior mean of var under this intervention.
plot() Plot a per-time trajectory with an HDI band.

__sub__()

Element-wise contrast between two DoResults.

Usage

__sub__(other)

by_time()

Return per-time-step posterior draws, shape (n_times, n_samples).

Usage

by_time(var)

Only available for panel do(simulate_over="time") results. The time axis corresponds to time_index.

Parameters
var: str
Variable name.
Returns
np.ndarray
Shape (n_times, n_samples).
Raises
ValueError
If per-time data is not available (cross-sectional do).

draws()

Return raw posterior draws for var under this intervention.

Usage

draws(var)
Parameters
var: str
Variable name.
Returns
np.ndarray
1-D array of posterior draws, shape (n_samples,).

hdi()

Return the highest-density interval for var.

Usage

hdi(var, prob=DEFAULT_HDI_PROB)
Parameters
var: str

Variable name.

prob: float = DEFAULT_HDI_PROB
Probability mass of the interval (default 0.94).
Returns
np.ndarray
Array of [lower, upper].

mean()

Return the posterior mean of var under this intervention.

Usage

mean(var)

plot()

Plot a per-time trajectory with an HDI band.

Usage

plot(var, *, vs=None, observed=None, ax=None, prob=DEFAULT_HDI_PROB)

For panel do(simulate_over="time") results, draws the posterior mean over time_index with a shaded HDI band. Optionally overlays an observed series when vs="observed" or observed= is passed.

Parameters
var: str

Variable to plot.

vs: str | None = None

When "observed", overlay the unit-mean observed series attached at construction or supplied via observed=.

observed: np.ndarray | None = None

Optional length-n_times observed series; overrides attached metadata for the overlay.

ax: matplotlib.axes.Axes | None = None

Axes to plot on. Creates a new figure if None.

prob: float = DEFAULT_HDI_PROB
Probability mass of the HDI band (default 0.94).
Returns
matplotlib.figure.Figure
The figure containing the trajectory plot.
Raises
KeyError

If var is not stored on this result.

ValueError
If per-time data is unavailable (cross-sectional result), if vs="observed" is requested without a series, or if observed has the wrong length.