simulate.EstimandResult

Posterior draws for a causal estimand (ATE, CATE, ATT, ATU).

Usage

simulate.EstimandResult(
    *,
    ds,
    outcome,
    treatment,
    estimand,
    estimator="structural",
    causal=True,
    interventional=True,
    identifiable=None
)

Unlike DoResult, which describes the whole system under an intervention, an EstimandResult knows which outcome was asked about, so its accessors default to that variable and no longer require the outcome to be re-specified.

The same per-variable draws are retained, so mean(other_var) still works for any variable in the contrast.

Internal storage mirrors DoResult: an xarray.Dataset exposed as dataset with dims ("chain", "draw") (and "time" for panel estimands).

Parameters

ds: xr.Dataset

Labelled contrast draws.

outcome: str

The outcome variable; the default target of all accessors.

treatment: str

The treatment variable that was intervened on.

estimand: str

Estimand label, e.g. "ATE", "CATE", "ATT", "ATU".

estimator: str = "structural"

Estimator label, e.g. "structural" or "regression_adjustment".

causal: bool = True

Whether the estimand is causal.

interventional: bool = True

Whether the estimand is interventional.

identifiable: bool | None = None
Whether the effect was identifiable; None when unknown.

Attributes

Name Description
causal Whether this estimand is causal.
dataset Labeled contrast draws as an xarray.Dataset.
estimator Estimator label (e.g. "structural", "regression_adjustment").
identifiable Whether the effect was identifiable; None when unknown.
interventional Whether graph surgery / do() was used.
outcome The outcome variable this estimand targets.
treatment The treatment variable that was intervened on.

causal

Whether this estimand is causal.

causal: bool

dataset

Labeled contrast draws as an xarray.Dataset.

dataset: xr.Dataset

Dims are ("chain", "draw"), plus "time" for panel estimands. For a flat (n_samples,) numpy view, use draws().

estimator

Estimator label (e.g. "structural", "regression_adjustment").

estimator: str

identifiable

Whether the effect was identifiable; None when unknown.

identifiable: bool | None

interventional

Whether graph surgery / do() was used.

interventional: bool

outcome

The outcome variable this estimand targets.

outcome: str

treatment

The treatment variable that was intervened on.

treatment: str

Methods

Name Description
__float__() Posterior mean of the estimand (outcome variable).
__sub__() Element-wise contrast between two estimands, preserving the outcome.
by_time() Return per-time-step contrast draws, shape (n_times, n_samples).
draws() Return raw contrast draws, defaulting to the outcome variable.
from_contrast() Wrap a DoResult contrast as a focused estimand result.
hdi() Return the highest-density interval, defaulting to the outcome.
mean() Return the posterior mean, defaulting to the outcome variable.
prob() Return the posterior probability that the estimand satisfies expr.
summary() Return a one-row tidy summary of the estimand.

__float__()

Posterior mean of the estimand (outcome variable).

Usage

__float__()

__sub__()

Element-wise contrast between two estimands, preserving the outcome.

Usage

__sub__(other)

by_time()

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

Usage

by_time(var=None)

Only available for panel simulate_over="time" estimands.

Parameters
var: str | None = None
Variable name. Defaults to the outcome.
Returns
np.ndarray
Shape (n_times, n_samples).
Raises
ValueError
If per-time data is not available (cross-sectional estimand).

draws()

Return raw contrast draws, defaulting to the outcome variable.

Usage

draws(var=None)
Parameters
var: str | None = None
Variable name. Defaults to the outcome.
Returns
np.ndarray
1-D array of posterior draws, shape (n_samples,).

from_contrast()

Wrap a DoResult contrast as a focused estimand result.

Usage

from_contrast(
    contrast,
    outcome,
    treatment,
    estimand,
    estimator="structural",
    causal=True,
    interventional=True,
    identifiable=None
)

hdi()

Return the highest-density interval, defaulting to the outcome.

Usage

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

Variable name. Defaults to the outcome.

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, defaulting to the outcome variable.

Usage

mean(var=None)

prob()

Return the posterior probability that the estimand satisfies expr.

Usage

prob(expr, var=None)

expr is a comparison applied to the (outcome) estimand draws, e.g. "> 0" returns P(estimand > 0).

Parameters
expr: str

A comparison such as "> 0", ">= 1", or "< -0.5".

var: str | None = None
Variable name. Defaults to the outcome.
Returns
float
Fraction of draws satisfying expr.

summary()

Return a one-row tidy summary of the estimand.

Usage

summary(prob=DEFAULT_HDI_PROB)

Columns: outcome, treatment, mean, sd, hdi_3%, hdi_97%, p(>0). The index holds the estimand label.

Parameters
prob: float = DEFAULT_HDI_PROB
Probability mass of the reported HDI (default 0.94).
Returns
pd.DataFrame
Single-row summary indexed by the estimand label.