metacausal.aggregation.BootstrapResult

class metacausal.aggregation.BootstrapResult(ate, ate_ci_lower, ate_ci_upper, boot_ates, cate, cate_ci_lower, cate_ci_upper, boot_cates=None, component_boot_ates=<factory>, component_ate_estimates=<factory>, component_cate_estimates=None, n_boot=0, n_failed=0, alpha=0.05, aggregation='', ensemble_weights=None, method='nonparametric', subsample_m=None, n_train=0)[source]

Bases: object

Bootstrap inference results for both ATE and CATE.

Point estimates (ate, cate) come from the original fit(), not from averaging bootstrap replicates — consistent with standard bootstrap CI practice.

Variables:

  • ate (float) – Point estimate from the original fit.

  • ate_ci_lower (float) – Lower bound of bootstrap CI for ATE.

  • ate_ci_upper (float) – Upper bound of bootstrap CI for ATE.

  • boot_ates (np.ndarray) – Bootstrap distribution of ensemble ATEs, shape (B,).

  • cate (np.ndarray | None) – Point estimate from the original fit, shape (n,). None if no CATE-capable adapters are available.

  • cate_ci_lower (np.ndarray | None) – Pointwise lower CI bounds, shape (n,). None if no CATE-capable adapters.

  • cate_ci_upper (np.ndarray | None) – Pointwise upper CI bounds, shape (n,). None if no CATE-capable adapters.

  • boot_cates (np.ndarray | None) – Bootstrap CATE distributions, shape (B, n). None if no CATE-capable adapters.

  • component_boot_ates (dict[str, np.ndarray]) – Per-component ATE distributions, {adapter_name: shape (B,)}. Bootstrap samples, not point estimates — contrast with component_ate_estimates.

  • component_ate_estimates (dict[str, 'ComponentAteEstimate']) – Full-sample per-component ATE point estimates, {adapter_name: ComponentAteEstimate}. Carries the point ATE plus any native CI the method provides (e.g., EconML analytical CIs). Computed during the original fit(); distinct from the bootstrap distributions in component_boot_ates.

  • component_cate_estimates (dict[str, 'ComponentCateEstimate'] | None) – Full-sample per-component CATE point estimates, {adapter_name: ComponentCateEstimate}. None if no CATE-capable adapter is available. Each entry carries the point CATE array and any native per-grid-point CI.

  • n_boot (int) – Number of bootstrap replicates requested.

  • n_failed (int) – Number of replicates that failed entirely.

  • alpha (float) – Significance level used for CIs.

  • aggregation (str) – Strategy class name that produced these results.

  • ensemble_weights (EnsembleWeights | None) – Weights from the original fit (None for pointwise strategies).

  • method (str) – Bootstrap resampling scheme — "nonparametric" (n-out-of-n with replacement, the standard Efron bootstrap) or "subsample" (m-out-of-n without replacement, T-stratified; CIs use the Politis–Romano scaled-percentile correction).

  • subsample_m (int | None) – Subsample size used when method="subsample"; None for nonparametric.

  • n_train (int) – Original training sample size. Recorded so scale and ci_at() can reconstruct the Politis-Romano scale factor after the fact, without needing n passed back in.

Parameters:

  • ate (float)

  • ate_ci_lower (float)

  • ate_ci_upper (float)

  • boot_ates (np.ndarray)

  • cate (np.ndarray | None)

  • cate_ci_lower (np.ndarray | None)

  • cate_ci_upper (np.ndarray | None)

  • boot_cates (np.ndarray | None)

  • component_boot_ates (dict[str, np.ndarray])

  • component_ate_estimates (dict[str, 'ComponentAteEstimate'])

  • component_cate_estimates (dict[str, 'ComponentCateEstimate'] | None)

  • n_boot (int)

  • n_failed (int)

  • alpha (float)

  • aggregation (str)

  • ensemble_weights (EnsembleWeights | None)

  • method (str)

  • subsample_m (int | None)

  • n_train (int)

Methods

__init__

cate_profile

Ensemble CATE along one covariate, with bootstrap CI band.

ci_at

Confidence interval at an arbitrary level, reusing this bootstrap run's already-computed replicate distribution(s) -- no re-fit needed.

component_ate_summary

Tabular summary of per-component bootstrap ATE statistics.

forest

Forest plot of per-component and ensemble ATEs.

summary

Return a formatted, multi-line bootstrap summary.

Attributes

aggregation

alpha

boot_cates

component_cate_estimates

ensemble_weights

method

n_boot

n_failed

n_train

scale

sqrt(subsample_m / n_train) for method="subsample", 1.0 otherwise (including when n_train wasn't recorded, e.g. a hand-built BootstrapResult).

subsample_m

ate

ate_ci_lower

ate_ci_upper

boot_ates

cate

cate_ci_lower

cate_ci_upper

component_boot_ates

component_ate_estimates

Details

cate_profile(x, *, xlabel, ax=None, show_components=True, ylim=None, ensemble_label='Ensemble CATE')[source]

Ensemble CATE along one covariate, with bootstrap CI band.

Thin wrapper around metacausal.plots.cate_profile(); see there for the full parameter reference. Requires the plots extra (pip install 'metacausal[plots]').

Returns:

matplotlib Axes the plot was drawn on.

Parameters:
Return type:

Axes

ci_at(level=None, *, dist=None, point_estimate=None)[source]

Confidence interval at an arbitrary level, reusing this bootstrap run’s already-computed replicate distribution(s) – no re-fit needed.

By default, reproduces the ensemble’s own ATE CI (at level instead of the level fixed when bootstrap() was called), using the same Politis-Romano scaled-percentile formula (with the method="subsample" scale correction applied automatically via scale).

Pass dist to get a CI for any other 1-d bootstrap distribution carried by this result – e.g. component_boot_ates["BCF"] for a per-component CI – or one you’ve derived yourself (e.g. a per-replicate mean across components, for an aggregation strategy the ensemble was never actually fit with). dist and point_estimate must be overridden together: a bootstrap distribution can only be centered correctly on the point estimate of the same statistic it resamples, and there is no way to infer the right point estimate for an arbitrary distribution.

Parameters:

  • level (float | None) – Coverage level, e.g. 0.90 for a 90% CI. Defaults to 1 - self.alpha (the level this result was already constructed at).

  • dist (ndarray | None) – Bootstrap replicate distribution, shape (B,). Defaults to self.boot_ates.

  • point_estimate (float | None) – Center of the interval. Defaults to self.ate. Required (and only meaningful) together with dist.

Returns:

(ci_lower, ci_upper) tuple.

Raises:

ValueError – If exactly one of dist/point_estimate is given.

Return type:

tuple[float, float]

component_ate_summary()[source]

Tabular summary of per-component bootstrap ATE statistics.

Returns a DataFrame with one row per component adapter, in the insertion order of component_boot_ates. Each row reports the bootstrap-mean ATE and the 1 - alpha CI, via ci_at() (matching the CI convention used by the ensemble itself, including the method="subsample" scale correction).

Returns:

pandas.DataFrame – Columns:

  • name: adapter name.

  • mean: bootstrap-mean ATE.

  • lo: lower CI bound.

  • hi: upper CI bound.

Raises:

ValueError – If component_boot_ates is empty (bootstrap not run or no component distributions recorded).

Return type:

DataFrame

forest(*, ax=None, order='value', ensemble_label='Ensemble', show_zero=True)[source]

Forest plot of per-component and ensemble ATEs.

Thin wrapper around metacausal.plots.forest(); see there for the full parameter reference. Requires the plots extra (pip install 'metacausal[plots]').

Returns:

matplotlib Axes the plot was drawn on.

Parameters:

  • ax (Axes | None)

  • order (Literal['value', 'alpha', 'ci_width', 'input'])

  • ensemble_label (str)

  • show_zero (bool)

Return type:

Axes

summary(*, digits=None, signed=False)[source]

Return a formatted, multi-line bootstrap summary.

Parameters:

  • digits (int | None)

  • signed (bool)

Return type:

str

aggregation: str = ''
alpha: float = 0.05
ate: float
ate_ci_lower: float
ate_ci_upper: float
boot_ates: np.ndarray
boot_cates: np.ndarray | None = None
cate: np.ndarray | None
cate_ci_lower: np.ndarray | None
cate_ci_upper: np.ndarray | None
component_ate_estimates: dict[str, 'ComponentAteEstimate']
component_boot_ates: dict[str, np.ndarray]
component_cate_estimates: dict[str, 'ComponentCateEstimate'] | None = None
ensemble_weights: EnsembleWeights | None = None
method: str = 'nonparametric'
n_boot: int = 0
n_failed: int = 0
n_train: int = 0
property scale: float

sqrt(subsample_m / n_train) for method="subsample", 1.0 otherwise (including when n_train wasn’t recorded, e.g. a hand-built BootstrapResult).

Type:

Politis-Romano scale factor

subsample_m: int | None = None