xcausal.aggregation.BootstrapResult

class xcausal.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 subsampling with finite-population correction).

  • subsample_m (int | None) – Subsample size used when method="subsample"; None for nonparametric. Subsample CI reconstruction requires integer sizes satisfying 1 <= subsample_m < n_train.

  • n_train (int) – Original training sample size. Recorded so scale and ci_at() can reconstruct the finite-population 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 - subsample_m)) for subsampling with finite-population correction, and 1.0 for the nonparametric bootstrap, which needs no size metadata.

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 xcausal.plots.cate_profile(); see there for the full parameter reference. Requires the plots extra (pip install 'xcausal[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, reconstructs the ensemble’s ATE CI (at level instead of the level fixed when bootstrap() was called), using the same centered-percentile formula (with the finite-population method="subsample" scale correction applied automatically via scale).

Reconstruction uses the installed code. Subsample results saved before the finite-population correction retain their old stored ATE/CATE endpoints; recompute those endpoints consistently before mixing them with reconstructed intervals, summaries, or plots.

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, the method is unknown, or a subsampled result lacks valid integer subsample_m and n_train metadata.

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 xcausal.plots.forest(); see there for the full parameter reference. Requires the plots extra (pip install 'xcausal[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 - subsample_m)) for subsampling with finite-population correction, and 1.0 for the nonparametric bootstrap, which needs no size metadata.

The subsample scale can exceed 1 when more than half the training observations are retained. It is motivated by regular asymptotic linearity, not a general coverage guarantee for CATE or nonregular aggregation; see CausalEnsemble.bootstrap().

Raises:

ValueError – If the method is unknown, or a subsampled result lacks integer sizes satisfying 1 <= subsample_m < n_train.

Type:

CI scale

subsample_m: int | None = None