Population Means#
Estimands#
Base classes for estimation.
- class pyrake.estimation.base_classes.Estimand[source]#
Bases:
ABCBase class for things that can be estimated.
- abstract property weights#
Calculate weights based on propensity scores.
- Returns:
weights – Weight for each of the
Msample members.- Return type:
(M,)
npt.NDArray[np.float64]
- abstractmethod sensitivity_region(gamma)[source]#
Calculate a sensitivity region around baseline weights.
- Parameters:
gamma (float) – The Gamma factor. Must be >= 1.0.
- Returns:
lower, upper – Elementwise lower and upper weight bounds.
- Return type:
(M,)
npt.NDArray[np.float64]
- abstractmethod resample(bootstrap_indices)[source]#
Create a new Estimand object based on resampled indices.
- Parameters:
bootstrap_indices ((B,)
npt.NDArray[np.int64]) – Row positions to retain in the resampled estimand.- Returns:
estimand – New estimand built from the indexed rows.
- Return type:
Estimand
- class pyrake.estimation.base_classes.SimpleEstimand(propensity_scores)[source]#
Bases:
EstimandEstimand determined by a single vector of propensity scores.
- Parameters:
propensity_scores ((M,)
npt.NDArray[np.float64]) – Estimated response propensity for each of theMsample members.
- resample(bootstrap_indices)[source]#
Create a new Estimand object based on resampled indices.
- Parameters:
bootstrap_indices ((B,)
npt.NDArray[np.int64]) – Row positions to retain in the resampled estimand.- Returns:
estimand – New estimand of the same class built from the indexed rows.
- Return type:
SimpleEstimand
- class pyrake.estimation.base_classes.WeightingEstimator[source]#
Bases:
ABCEstimator that reweights sample members to a target population.
- abstractmethod point_estimate()[source]#
Calculate a point estimate.
- Returns:
estimate – Estimated value of the target quantity.
- Return type:
- abstractmethod variance()[source]#
Calculate the variance.
- Returns:
variance – Sampling variance of the point estimate.
- Return type:
- abstractmethod sensitivity_analysis(gamma=6.0, outcome_proxies=None, proxy_mean=None, alpha=0.1)[source]#
Perform a sensitivity analysis.
Calculate a range of point estimates implied by the Gamma factor.
- Parameters:
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes.
outcome_proxies (array_like, optional) – A proxy for the outcome with a known population mean. When supplied together with
proxy_mean, the sensitivity region gains a constraint keeping the proxy estimate within tolerance ofproxy_mean, which typically narrows the interval. Defaults to None (no proxy constraint).proxy_mean (float, optional) – Known population mean of the outcome proxy. Must be supplied together with
outcome_proxies. Defaults to None.alpha (float, optional) – Significance level for the proxy tolerance. Defaults to 0.10.
- Returns:
lb, ub – Lower and upper bounds on the point estimate.
- Return type:
- Raises:
ValueError – Raised by implementations when
gamma< 1, when only one ofoutcome_proxiesandproxy_meanis supplied, or when the proxy constraints admit no feasible weights.
Notes
(Zhao, Small, and Bhattarcharya 2019) posits a model:
1/Λ < (πᵢ / (1 - πᵢ)) / (π̂ᵢ / (1 - π̂ᵢ)) < Λ,
where πᵢ is the true (unknown) propensity score for person i and π̂ᵢ is its estimate. That is, Λ controls how “wrong” the estimated propensity scores are. For sufficiently large values of Λ, this model will always hold, but we have no way of knowing what value of Λ is “good enough”. So instead we recommend trying a variety of Λ values and plot the results.
As discussed in (Fogarty 2023), this model is connected to Rosenbaum’s sensitivity analysis via Λ = √Γ. To foster connection with that work (and because
lambdais a reserved keyword in python!), we take Gamma as input to this calculation, and then calculate Λ as √Γ.While no value of Gamma is guaranteed to be good enough, a value of Gamma=6 is a good candidate for default reporting. In his work on sensitivity analysis, Paul Rosenbaum often cites Hammond’s meta-analysis on the connection between smoking and cancer, which was sensitive to biases above Gamma = 6, yet was persuasive in establishing that smoking causes cancer. While biases may exceed Gamma = 6, this value balances rigor and practicality.
The constraint on the propensity scores translates into a constraint on the weights, but this depends on the estimator. The “true” weights satisfy:
wlᵢ ≤ wᵢ ≤ wuᵢ.
(Zhao, Small, and Bhattarcharya 2019) calculates the infimum and supremum of the estimator over this range of weights. Details vary depending on the estimator.
References
Zhao, Qingyuan, Dylan S Small, and Bhaswar B Bhattacharya. 2019. “Sensitivity Analysis for Inverse Probability Weighting Estimators via the Percentile Bootstrap.” Journal of the Royal Statistical Society Series B: Statistical Methodology 81 (4). Oxford University Press: pg. 735–61.
Fogarty, Colin. 2023. “Sensitivity Analysis.” In Handbook of Matching and Weighting Adjustments for Causal Inference, , pg. 553–82. Chapman and Hall/CRC.
- abstractmethod resample(B, seed=None)[source]#
Yield a sequence of B bootstrap-resampled estimators.
- expanded_confidence_interval(alpha=0.1, gamma=6.0, alternative='two-sided', bootstrap=True, B=1000, seed=None)[source]#
Calculate an expanded confidence interval.
The expanded confidence interval combines uncertainty from stochastic sampling and from propensity scores estimated with error.
- Parameters:
alpha (float, optional) – P-value threshold, e.g. specify alpha=0.05 for a 95% confidence interval. Defaults to 0.10, corresponding to a 90% confidence interval.
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes in
sensitivity_analysis.alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: theta =
null_valuevs Halt: theta <>null_value.”greater”: H0: theta <=
null_valuevs Halt: theta >null_value.”less”: H0: theta >=
null_valuevs Halt: theta <null_value.
Defaults to “two-sided”.
bootstrap (bool, optional) – If True (default), use the percentile bootstrap (Zhao, Small, and Bhattacharya, 2019) to account for sampling variability in the sensitivity bounds. If False, use the normal approximation: the ECI is the sensitivity interval expanded by a multiple of the standard error on each side, where the standard error is evaluated at the worst-case sensitivity weights (the heuristic from Wilson 2025, §3). See
adjusted_pvaluefor additional notes.B (int, optional) – Number of bootstrap replications to run. Ignored when
bootstrap=False. Defaults to 1_000.seed (int, list_like, etc) – A seed for
numpy.random.default_rng. Ignored whenbootstrap=False. See that documentation for details.
- Returns:
lb, ub – Lower and upper bounds on the confidence interval. For one-sided intervals, only one of these will be finite:
”two-sided”: lb and ub both finite
”greater”: lb finite, ub = np.inf
”less”: lb = -np.inf, ub finite
- Return type:
- Raises:
ValueError – If
gamma< 1 oralternativeis not recognized.
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
Zhao, Qingyuan, Dylan S Small, and Bhaswar B Bhattacharya. 2019. “Sensitivity Analysis for Inverse Probability Weighting Estimators via the Percentile Bootstrap.” Journal of the Royal Statistical Society Series B: Statistical Methodology 81 (4). Oxford University Press: pg. 735–61.
- pvalue(null_value, alternative='two-sided')[source]#
Calculate a p-value.
Computes a p-value against the null hypothesis:
H0: theta = null_value,
where theta is the quantity being estimated
- Parameters:
null_value (float) – The hypothesized theta.
alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: theta =
null_valuevs Halt: theta <>null_value.”greater”: H0: theta <=
null_valuevs Halt: theta >null_value.”less”: H0: theta >=
null_valuevs Halt: theta <null_value.
For example, specifying alternative = “greater” returns a p-value that quantifies the strength of evidence against the null hypothesis that theta is less than
null_value, in favor of the alternative hypothesis that theta is actually greater thannull_value. Defaults to “two-sided”.
- Returns:
p – P-value.
- Return type:
- Raises:
ValueError – If
alternativeis not recognized.
- adjusted_pvalue(null_value, gamma=6.0, alternative='two-sided', bootstrap=True, B=1000, seed=None)[source]#
Calculate a p-value adjusted for hidden bias.
The adjusted p-value accounts for both sampling uncertainty and uncertainty from propensity scores estimated with error. It is the smallest alpha for which the expanded confidence interval at level alpha excludes
null_value, making it the dual ofexpanded_confidence_intervalin the same sense thatpvalueis the dual ofconfidence_interval.- Parameters:
null_value (float) – The hypothesized theta.
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes in
sensitivity_analysis.alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: theta =
null_valuevs Halt: theta <>null_value.”greater”: H0: theta <=
null_valuevs Halt: theta >null_value.”less”: H0: theta >=
null_valuevs Halt: theta <null_value.
Defaults to “two-sided”.
bootstrap (bool, optional) – If True (default), use the percentile bootstrap to account for sampling variability in the sensitivity bounds. If False, use the normal approximation: the test statistic is formed from the sensitivity bound and the standard error evaluated at the worst-case sensitivity weights (the heuristic from Wilson 2025, §3). This provides a lower bound on the adjusted p-value, but simulations suggest it’s tight enough to be practically useful.
B (int, optional) – Number of bootstrap replications to run. Ignored when
bootstrap=False. Defaults to 1_000.seed (int, list_like, etc) – A seed for
numpy.random.default_rng. Ignored whenbootstrap=False. See that documentation for details.
- Returns:
p – Adjusted p-value.
- Return type:
- Raises:
ValueError – If
gamma< 1 oralternativeis not recognized.
Notes
When
bootstrap=True, B bootstrap replicates are drawn. For each replicate,sensitivity_analysiscomputes the range of point estimates consistent with gamma-level hidden bias. The adjusted p-value is then the fraction of bootstrap replicates whose sensitivity interval does not rule outnull_value:“greater”: fraction of bootstrap lower bounds that do not exceed
null_value, i.e. mean(lb_bootstrap <=null_value).“less”: fraction of bootstrap upper bounds not below
null_value, i.e. mean(ub_bootstrap >null_value).“two-sided”: twice the minimum of the two one-sided adjusted p-values, capped at 1.
When
bootstrap=False, the normal approximation is used instead: the test statistic is formed from the sensitivity bound in the numerator and the standard error at the worst-case weights in the denominator. Because the true infimum of the test statistic is intractable (the statistic is not convex in the weights), this uses the heuristic from (Wilson 2025, §3): find the weights that minimize the numerator, then evaluate the standard error at those same weights. Simulations show this closely tracks the bootstrap-based adjusted p-value.When gamma=1 the sensitivity interval collapses to the point estimate, and the adjusted p-value reduces to the standard p-value.
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
Zhao, Qingyuan, Dylan S Small, and Bhaswar B Bhattacharya. 2019. “Sensitivity Analysis for Inverse Probability Weighting Estimators via the Percentile Bootstrap.” Journal of the Royal Statistical Society Series B: Statistical Methodology 81 (4): 735–61.
- gamma_star(null_value, alpha=0.05, alternative='two-sided', bootstrap=True, B=1000, seed=None, gamma_upper=6.0, tol=0.001)[source]#
Find the smallest Gamma at which the result is no longer significant.
Searches for the smallest Gamma >= 1 such that the adjusted p-value is >=
alpha(i.e., the result is no longer statistically significant).- Parameters:
null_value (float) – The hypothesized theta.
alpha (float, optional) – Significance threshold. Defaults to 0.05.
alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: theta =
null_valuevs Halt: theta <>null_value.”greater”: H0: theta <=
null_valuevs Halt: theta >null_value.”less”: H0: theta >=
null_valuevs Halt: theta <null_value.
Defaults to “two-sided”.
bootstrap (bool, optional) – If True (default), use the percentile bootstrap. If False, use the normal approximation. See
adjusted_pvaluefor details.B (int, optional) – Number of bootstrap replications. Ignored when
bootstrap=False. Defaults to 1_000.seed (int, list_like, etc, optional) – A seed for
numpy.random.default_rng. Ignored whenbootstrap=False. Passing a fixed seed is recommended whenbootstrap=Truebecause it ensures the adjusted p-value is monotone in Gamma, which makes the binary search more reliable.gamma_upper (float, optional) – Initial upper bound for the exponential search phase. If the adjusted p-value is still significant here, the search doubles this value repeatedly until a bracket is found. Defaults to 6.
tol (float, optional) – Convergence tolerance on Gamma. The returned value is accurate to within
tol. Defaults to 1e-3.
- Returns:
gamma_star – The smallest Gamma >= 1 at which the result is not statistically significant. Returns 1.0 if the result is already not significant at Gamma=1.
- Return type:
- Raises:
ValueError – If
gamma_upper< 1, or ifalternativeis not recognized (propagated frompvalueandadjusted_pvalue).
Notes
The adjusted p-value is monotonically non-decreasing in Gamma: larger Gamma widens the sensitivity interval, making it harder to reject the null hypothesis. This guarantees that a unique crossing point exists and that binary search converges reliably.
The search proceeds in two phases. First, an exponential search starting at
gamma_upperdoubles the candidate until a Gamma is found where the adjusted p-value exceedsalpha. Then bisection narrows the bracket to withintol.When
bootstrap=True, pass a fixedseedto ensure reproducible results and to preserve monotonicity across binary search iterations.References
Zhao, Qingyuan, Dylan S Small, and Bhaswar B Bhattacharya. 2019. “Sensitivity Analysis for Inverse Probability Weighting Estimators via the Percentile Bootstrap.” Journal of the Royal Statistical Society Series B: Statistical Methodology 81 (4): 735–61.
- confidence_interval(alpha=0.1, alternative='two-sided')[source]#
Calculate confidence interval on a quantity, theta.
- Parameters:
alpha (float, optional) – P-value threshold, e.g. specify alpha=0.05 for a 95% confidence interval. Defaults to 0.10, corresponding to a 90% confidence interval.
alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: theta =
null_valuevs Halt: theta <>null_value.”greater”: H0: theta <=
null_valuevs Halt: theta >null_value.”less”: H0: theta >=
null_valuevs Halt: theta <null_value.
Defaults to “two-sided”.
- Returns:
lb, ub – Lower and upper bounds on the confidence interval. For one-sided intervals, only one of these will be finite:
”two-sided”: lb and ub both finite
”greater”: lb finite, ub = np.inf
”less”: lb = -np.inf, ub finite
- Return type:
- Raises:
ValueError – If
alternativeis not recognized.
- plot_sensitivity(gamma_lower=1.0, gamma_upper=6.0, num_points=50, alpha=0.1, alternative='two-sided', bootstrap=True, B=1000, null_value=None, title=None, ylabel='Sensitivity Interval', ytick_format='.0%', axis_label_size=None, tick_label_size=None, legend_label_size=None, legend_placement=None, ax=None)[source]#
Plot sensitivity of estimates to hidden biases.
- Parameters:
gamma_lower (float, optional) – Range of Gamma values to test. Defaults to 1 and 6 resp.
gamma_upper (float, optional) – Range of Gamma values to test. Defaults to 1 and 6 resp.
num_points (int, optional) – Number of Gammas to simulate and plot. Defaults to 50.
alpha (float, optional) – P-value threshold, e.g. specify alpha=0.05 for a 95% confidence interval. Defaults to 0.10, corresponding to a 90% confidence interval.
alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: Ȳ =
null_valuevs Halt: Ȳ <>null_value.”greater”: H0: Ȳ <=
null_valuevs Halt: Ȳ >null_value.”less”: H0: Ȳ >=
null_valuevs Halt: Ȳ <null_value.
bootstrap (bool, optional) – Passed to
expanded_confidence_interval. If True (default), use the percentile bootstrap. If False, use the normal approximation (much faster, especially when plotting many gamma values).B (int, optional) – Number of bootstrap replications per gamma value. Ignored when
bootstrap=False. Defaults to 1_000.null_value (float, optional) – If specified, compute
gamma_star(the smallest Gamma at which the result is no longer significant against this null) and annotate the plot with a vertical line at that point. No annotation is added if the result is already non-significant at Gamma=1 (gamma_star== 1) or ifgamma_starexceedsgamma_upper.title (str, optional) – Title/ylabel for plot. If not specified, no title is included.
ylabel (str, optional) – Title/ylabel for plot. If not specified, no title is included.
ytick_format (str, optional) – How to format the y-axis tick labels. Defaults to “.0%”, corresponding to a percentage.
axis_label_size (int, optional) – Font size for axis labels and title; tick mark labels; and legend entries, resp.
tick_label_size (int, optional) – Font size for axis labels and title; tick mark labels; and legend entries, resp.
legend_label_size (int, optional) – Font size for axis labels and title; tick mark labels; and legend entries, resp.
legend_placement (str, optional) – Legend placement. Chosen automatically if not specified.
ax (Axes, optional) – If specified, plot everything on these axes.
- Returns:
df (pandas DataFrame) – A DataFrame with the lower and upper bounds corresponding to each gamma.
ax (Axes) – The plot axes.
- Raises:
ValueError – If the gamma range is empty, fewer than two points are requested, or
alternativeis not recognized.
- min_ess_bound(gamma, method='floor')[source]#
Worst-case effective sample size over the Gamma sensitivity region.
Returns the smallest Kish effective sample size attainable anywhere in the Gamma sensitivity region (
method="exact"), or a cheap conservative lower bound on it (method="floor"). The default raises, since this is only defined for estimators whose sensitivity region is a box of weights. SeeMeanEstimator.min_ess_boundfor the implementation.- Parameters:
gamma (float) – The Gamma factor. Must be >= 1.0. See
sensitivity_analysis.method (["floor", "exact"], optional) – “floor” (default) returns the conservative closed-form lower bound; “exact” returns the actual worst-case minimum via a vertex sweep.
- Returns:
ess – The worst-case effective sample size over the region (or a lower bound).
- Return type:
- Raises:
NotImplementedError – Always raised here; only mean estimators implement this method.
- plot_min_ess(gamma_lower=1.0, gamma_upper=6.0, num_points=50, method='floor', reference_ess=None, title=None, ylabel='Minimum Effective Sample Size', ytick_format=',.0f', axis_label_size=None, tick_label_size=None, legend_label_size=None, legend_placement=None, ax=None)[source]#
Plot the worst-case effective sample size against hidden bias.
Plots the conservative lower bound on the smallest Kish effective sample size ESS(w) = (1ᵀw)²/‖w‖² attainable anywhere in the Gamma sensitivity region, as a function of Gamma. This is the effective-sample-size analogue of
plot_sensitivity: it shows how much the leverage of the weights can collapse across the region as the assumed hidden bias grows.At
gamma_lower = 1the region collapses to a point, so the curve begins at the exact effective sample size of the nominal weights; as Gamma grows the region widens and the bound decreases. The bound is computed bymin_ess_bound, which uses the conservative floor derived in (Wilson 2025): the numerator at the region’s lowest corner over the denominator at its highest.- Parameters:
gamma_lower (float, optional) – Range of Gamma values to plot. Defaults to 1 and 6 resp.
gamma_upper (float, optional) – Range of Gamma values to plot. Defaults to 1 and 6 resp.
num_points (int, optional) – Number of Gammas to evaluate and plot. Defaults to 50.
method (["floor", "exact"], optional) – Passed to
min_ess_bound. “floor” (default) plots the conservative closed-form lower bound; “exact” plots the actual worst-case minimum.reference_ess (float, optional) – If specified, draw a horizontal dashed line at this effective sample size (e.g. a reliability floor below which the normal approximation is suspect). No line is drawn if not specified.
title (str, optional) – Title/ylabel for plot. If
titleis not specified, no title is included.ylabel (str, optional) – Title/ylabel for plot. If
titleis not specified, no title is included.ytick_format (str, optional) – How to format the y-axis tick labels. Defaults to “,.0f” (integer counts with thousands separators).
axis_label_size (int, optional) – Font size for axis labels and title; tick mark labels; and legend entries, resp.
tick_label_size (int, optional) – Font size for axis labels and title; tick mark labels; and legend entries, resp.
legend_label_size (int, optional) – Font size for axis labels and title; tick mark labels; and legend entries, resp.
legend_placement (str, optional) – Legend placement. Defaults to “upper right”.
ax (Axes, optional) – If specified, plot everything on these axes.
- Returns:
df (pandas DataFrame) – A DataFrame with the minimum effective sample size bound for each gamma.
ax (Axes) – The plot axes.
- Raises:
ValueError – If the gamma range is empty or fewer than two points are requested.
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
Population estimators.
- class pyrake.estimation.population.PopulationMean(propensity_scores)[source]
Bases:
SimpleEstimandMean over the full target population.
- Parameters:
propensity_scores ((M,)
npt.NDArray[np.float64]) – Estimated response propensity for each of theMsample members.
- property weights
Calculate weights based on propensity scores.
- Returns:
weights – Inverse propensity weight for each of the
Msample members.- Return type:
(M,)
npt.NDArray[np.float64]
- class pyrake.estimation.population.NonRespondentMean(propensity_scores)[source]
Bases:
SimpleEstimandMean among everyone who did not respond.
The non-respondent mean is the mean response among everyone who did not respond. The weights for this estimand are (1 - π) / π, where π are the propensity scores.
- Parameters:
propensity_scores ((M,)
npt.NDArray[np.float64]) – Estimated response propensity for each of theMsample members.
- property weights
Calculate weights based on propensity scores.
- Returns:
weights – Non-response weight for each of the
Msample members.- Return type:
(M,)
npt.NDArray[np.float64]
- sensitivity_region(gamma)[source]
Calculate a sensitivity region around baseline weights.
- Parameters:
gamma (float) – The Gamma factor. Must be >= 1.0.
- Returns:
lower, upper – Elementwise lower and upper weight bounds.
- Return type:
(M,)
npt.NDArray[np.float64]
- static normalizing_factor(sample_size, population_size)[source]
Calculate normalizing factor.
- class pyrake.estimation.population.SampleMean(propensity_scores)[source]
Bases:
SimpleEstimandMean among the population of respondents.
The sample mean is the mean response among the population of respondents. The weights are simply 1, and thus involve no uncertainty.
- Parameters:
propensity_scores ((M,)
npt.NDArray[np.float64]) – Estimated response propensity for each of theMsample members.
- property weights
Calculate weights based on propensity scores.
- Returns:
weights – Unit weight for each of the
Msample members.- Return type:
(M,)
npt.NDArray[np.float64]
Estimators#
Population estimators.
- class pyrake.estimation.population.MeanEstimator(propensity_scores, outcomes, estimand=None, estimand_class=None, **kwargs)[source]#
Bases:
WeightingEstimatorBase class for estimating a mean in some population.
- Parameters:
propensity_scores (list_like) – Propensity scores.
outcomes (list_like) – Outcomes or responses. Should have the same length as
propensity_scores.estimand (Estimand, optional) – An
Estimandobject representing the thing to be estimated. Defaults toPopulationMean.estimand_class (type, optional) – Estimand class to construct from
propensity_scoreswhenestimandis not given. Defaults toPopulationMean.kwargs (dict, optional) – Extra arguments forwarded to the estimator constructor.
- min_ess_bound(gamma, method='floor')[source]#
Worst-case effective sample size over the Gamma sensitivity region.
Returns the smallest Kish effective sample size
ESS(w) = (1ᵀw)²/‖w‖²
attainable anywhere in the Gamma sensitivity region [
wl,wu]. The Kish effective sample size measures how evenly the weights spread the estimate’s leverage; the normal approximation behind the sensitivity bounds leans on its being large. Its worst case over the region is a ratio with a rank-one numerator over a separable denominator, so the minimizer is a vertex of the box: heavy units raised towuand light units lowered towl, the arrangement that most concentrates the weights. Because bothwlandwuincrease with the nominal weight, the optimal split is a threshold on the sorted weights, found by sweeping all thresholds in a single pass (method="exact").A coarser bound needs no search at all, taking the numerator at the region’s lowest corner and the denominator at its highest (
method="floor"):min over wl ≤ w ≤ wu of ESS(w) ≥ (Σᵢ wlᵢ)²/Σᵢ wuᵢ².
Both are computable before any outcome is examined. At gamma=1 the region collapses to a point and either method returns the exact effective sample size of the nominal weights; as gamma grows the region widens and the value decreases.
- Parameters:
gamma (float) – The Gamma factor. Must be >= 1.0. See
sensitivity_analysis.method (["floor", "exact"], optional) – “floor” (default) returns the conservative closed-form lower bound; “exact” returns the actual worst-case minimum via the threshold sweep.
- Returns:
ess – The worst-case effective sample size over the region (a lower bound when
method="floor").- Return type:
- Raises:
ValueError – If
gamma< 1 ormethodis not recognized.
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
- pvalue(null_value, alternative='two-sided')[source]#
Calculate a p-value.
Computes a p-value against the null hypothesis:
H0: Ȳ = ``null_value``,
where Ȳ is the mean in the target population.
- Parameters:
null_value (float) – The hypothesized mean.
alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: Ȳ =
null_valuevs Halt: Ȳ <>null_value.”greater”: H0: Ȳ <=
null_valuevs Halt: Ȳ >null_value.”less”: H0: Ȳ >=
null_valuevs Halt: Ȳ <null_value.
For example, specifying alternative = “greater” returns a p-value that quantifies the strength of evidence against the null hypothesis that the mean is less than
null_value, in favor of the alternative hypothesis that the mean is actually greater thannull_value. Defaults to “two-sided”.
- Returns:
p – P-value.
- Return type:
- Raises:
ValueError – If
alternativeis not recognized (propagated frompvalue).
- confidence_interval(alpha=0.1, alternative='two-sided')[source]#
Calculate confidence interval on mean in target population.
- Parameters:
alpha (float, optional) – P-value threshold, e.g. specify alpha=0.05 for a 95% confidence interval. Defaults to 0.10, corresponding to a 90% confidence interval.
alternative (["two-sided", "less", "greater"], optional) –
What kind of test:
”two-sided”: H0: Ȳ =
null_valuevs Halt: Ȳ <>null_value.”greater”: H0: Ȳ <=
null_valuevs Halt: Ȳ >null_value.”less”: H0: Ȳ >=
null_valuevs Halt: Ȳ <null_value.
Defaults to “two-sided”.
- Returns:
lb, ub – Lower and upper bounds on the confidence interval. For one-sided intervals, only one of these will be finite:
”two-sided”: lb and ub both finite
”greater”: lb finite, ub = np.inf
”less”: lb = -np.inf, ub finite
- Return type:
- Raises:
ValueError – If
alternativeis not recognized (propagated fromconfidence_interval).
- class pyrake.estimation.population.IPWEstimator(propensity_scores, outcomes, population_size, estimand=None, estimand_class=None, **kwargs)[source]#
Bases:
MeanEstimatorInverse Propensity Weighted Estimator.
- Parameters:
propensity_scores (list_like) – Propensity scores.
outcomes (list_like) – Outcomes or responses. Should have the same length as
propensity_scores.population_size (int) – Size of target population.
estimand (Estimand, optional) – An
Estimandobject representing the thing to be estimated. Defaults toPopulationMean.estimand_class (type, optional) – Estimand class to construct from
propensity_scoreswhenestimandis not given. Defaults toPopulationMean.kwargs (dict, optional) – Extra arguments forwarded to the estimator constructor.
Notes
The IPW estimator is:
Ŷ_IPW = (1/N) Σᵢ wᵢyᵢ,
where wᵢ = 1/πᵢ, N is the target population size, and πᵢ is the propensity score.
Details on this estimator, including sensitivity analysis and links to academic resources, can be found in (Wilson, 2025)
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
- point_estimate()[source]#
Calculate a point estimate.
- Returns:
estimate – Inverse-propensity-weighted estimate of the population total divided by the normalizing factor.
- Return type:
- variance()[source]#
Calculate the variance.
Per (Wilson 2025, §2), an estimator for the variance is:
Σᵢ(((n/N)/πᵢ) × yᵢ − pe)² / (n × (n − 1)),
where pe is the point estimate and n is the sample size.
- Returns:
variance – Estimated sampling variance of the point estimate.
- Return type:
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
- sensitivity_analysis(gamma=6.0, outcome_proxies=None, proxy_mean=None, alpha=0.1)[source]#
Perform a sensitivity analysis.
Calculate a range of point estimates implied by the Gamma factor.
- Parameters:
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes.
outcome_proxies (array_like, optional) – A proxy for the outcome, observed for every unit in the sample. When supplied together with
proxy_mean, an additional constraint is added to the sensitivity region: the IPW estimate of the proxy mean must lie withintolofproxy_mean, wheretolis the half-width fromconfidence_interval. Weights that violate this constraint are excluded from the sensitivity region, typically reducing the width of the sensitivity interval. Must have the same length asoutcomes. Requiresproxy_meanto also be specified.proxy_mean (float, optional) – Known population mean of the outcome proxy. Requires
outcome_proxiesto also be specified.alpha (float, optional) – Significance level used to compute the proxy tolerance
tolviascipy.stats.norm.isfand the point-estimate variance. Defaults to 0.10, matching the default ofconfidence_interval.
- Returns:
lb, ub – Lower and upper bounds on the point estimate.
- Return type:
- Raises:
ValueError – If only one of
outcome_proxiesandproxy_meanis supplied, ifgamma< 1, or if the proxy constraints admit no feasible weights.
Notes
See the Notes in
WeightingEstimatorfor overall context. Without an outcome proxy there is a simple closed-form calculation for the sensitivity interval. See (Wilson 2025) for details. When an outcome proxy is supplied, the constrained optimisation is solved as a linear programme viascipy.optimize.linprog.References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
- class pyrake.estimation.population.AIPWEstimator(propensity_scores, outcomes, predicted_outcomes, mean_predicted_outcome, population_size, estimand=None, estimand_class=None, **kwargs)[source]#
Bases:
IPWEstimatorAugmented Inverse Propensity Weighted Estimator.
- Parameters:
propensity_scores (list_like) – Propensity scores.
outcomes (list_like) – Outcomes or responses. Should have the same length as
propensity_scores.predicted_outcomes (list_like) – Predicted outcomes corresponding to each response. Should have the same length as
propensity_scores.mean_predicted_outcome (float) – Mean of predicted outcomes in target population.
population_size (int) – Size of target population.
estimand (Estimand, optional) – An
Estimandobject representing the thing to be estimated. Defaults toPopulationMean.estimand_class (type, optional) – Estimand class to construct from
propensity_scoreswhenestimandis not given. Defaults toPopulationMean.kwargs (dict, optional) – Extra arguments forwarded to the estimator constructor.
Notes
The AIPW estimator for a mean is:
Ŷ_AIPW = μ̄ + (1/N) Σᵢ wᵢ × (yᵢ − μ(xᵢ)),
where wᵢ = 1/πᵢ, N is the target population size, and πᵢ is the propensity score (as in
IPWEstimator). μ(xᵢ) is a prediction of the outcome, yᵢ, for individual i, made on the basis of covariates, x, observed for everyone in the target population (including everyone in the sample), and μ̄ is the average predicted outcome in the target population. (Since we observe x for everyone in the target population, we can predict the outcome for everyone in the population, and μ̄ is the average of these predictions.)The intuition is, if we have a good model for the outcome, we can use it to predict the target population mean directly, then adjust this prediction with an estimator based on the residuals in the sample. Details on this estimator, including sensitivity analysis and links to academic resources, can be found in (Wilson, 2025)
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
- point_estimate()[source]#
Calculate a point estimate.
- Returns:
estimate – Mean predicted outcome plus the IPW estimate of the mean residual.
- Return type:
- variance()[source]#
Calculate the variance.
Per (Wilson 2025, §2), an estimator for the variance is:
Σᵢ(wᵢ × yᵢ − pe)² / (n × (n − 1)),
where pe is the point estimate and n is the sample size.
- Returns:
variance – Estimated sampling variance of the point estimate.
- Return type:
References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
- sensitivity_analysis(gamma=6.0, outcome_proxies=None, proxy_mean=None, alpha=0.1)[source]#
Perform a sensitivity analysis.
Calculate a range of point estimates implied by the Gamma factor.
- Parameters:
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes.
outcome_proxies (array_like, optional) – A proxy for the outcome with a known population mean. See
IPWEstimator.sensitivity_analysisfor details. The proxy constraint applies to the same (AIPW) weights.proxy_mean (float, optional) – Known population mean of the outcome proxy.
alpha (float, optional) – Significance level for the proxy tolerance. Defaults to 0.10.
- Returns:
lb, ub – Lower and upper bounds on the point estimate.
- Return type:
- Raises:
ValueError – If
gamma< 1, if only one ofoutcome_proxiesandproxy_meanis supplied, or if the proxy constraints admit no feasible weights (propagated fromIPWEstimator.sensitivity_analysis).
Notes
See the Notes in
WeightingEstimatorfor overall context. In our case, there is a simple closed-form calculation for the sensitivity interval. See (Wilson 2025) for details.References
Wilson, Bob. 2025. “Design-Based Inference and Sensitivity Analysis for Survey Sampling.” https://adventuresinwhy.com/post/survey_sampling/
- class pyrake.estimation.population.SIPWEstimator(propensity_scores, outcomes, estimand=None, estimand_class=None, binary_outcomes=True, **kwargs)[source]#
Bases:
MeanEstimatorStabilized Inverse Propensity Weighted Estimator.
- Parameters:
propensity_scores (list_like) – Propensity scores.
outcomes (list_like) – Outcomes or responses. Should have the same length as
propensity_scores.binary_outcomes (bool, optional) – Indicates whether the outcomes are binary. If
outcomescontains values other than 0 and 1, we conclude the outcomes are not binary; if all values are 0 and 1 we conclude outcomes are binary. The only place this matters is in the sensitivity analysis, which is faster for binary outcomes than in general.estimand (Estimand, optional) – An
Estimandobject representing the thing to be estimated. Defaults toPopulationMean.estimand_class (type, optional) – Estimand class to construct from
propensity_scoreswhenestimandis not given. Defaults toPopulationMean.kwargs (dict, optional) – Extra arguments forwarded to the estimator constructor.
Notes
The SIPW estimator is:
Ŷ_SIPW = Σᵢ wᵢyᵢ / Σᵢ wᵢ.
This is literally the first thing people think of when they hear “weighted average”, fancy name notwithstanding. The weights are the inverse propensity scores. Since we divide by the sum of the weights, we can scale them by an arbitrary multiplicative constant without changing point estimates or p-values, but this does affect sensitivity analysis, so it is best to use unscaled weights. More details about this estimator, including its variance, may be found in (Sarig, Galili, and Eilat 2023).
For details on sensitivity analysis for this estimator, see (Zhao, Small, and Bhattarcharya 2019).
References
Sarig, Tal, Tal Galili, and Roee Eilat. “balance–a Python package for balancing biased data samples.” arXiv preprint arXiv:2307.06024 (2023).
Zhao, Qingyuan, Dylan S Small, and Bhaswar B Bhattacharya. 2019. “Sensitivity Analysis for Inverse Probability Weighting Estimators via the Percentile Bootstrap.” Journal of the Royal Statistical Society Series B: Statistical Methodology 81 (4). Oxford University Press: pg. 735–61.
- point_estimate()[source]#
Calculate a point estimate.
- Returns:
estimate – Self-normalized weighted mean of the outcomes.
- Return type:
- variance()[source]#
Calculate the variance.
Per (Sarig, Galili, Eilat 2023, Appendix D.2), an estimator for the variance is:
Σᵢ wᵢ² × (yᵢ − pe)² / (Σᵢ wᵢ)²,
where pe is the point estimate.
- Returns:
variance – Estimated sampling variance of the point estimate.
- Return type:
- sensitivity_analysis(gamma=6.0, outcome_proxies=None, proxy_mean=None, alpha=0.1)[source]#
Perform a sensitivity analysis.
Calculate a range of point estimates implied by the Gamma factor. See
_sensitivity_weightsfor the unconstrained algorithm.- Parameters:
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes in
WeightingEstimator.outcome_proxies (array_like, optional) – A proxy for the outcome with a known population mean. When supplied together with
proxy_mean, an additional constraint is added to the sensitivity region: the SIPW estimate of the proxy mean must lie withintolofproxy_mean, wheretolis the half-width fromconfidence_interval. For the SIPW estimator this is(wᵀproxy)/(wᵀ1)in [pm − tol, pm + tol], which is linear after the Charnes-Cooper transformation. Weights that violate this constraint are excluded from the sensitivity region, typically reducing the width of the sensitivity interval. Must have the same length asoutcomes. Requiresproxy_meanto also be specified.proxy_mean (float, optional) – Known population mean of the outcome proxy. Requires
outcome_proxiesto also be specified.alpha (float, optional) – Significance level for the proxy tolerance
tolviascipy.stats.norm.isfand the point-estimate variance. Defaults to 0.10, matching the default ofconfidence_interval.
- Returns:
lb, ub – Lower and upper bounds on the point estimate.
- Return type:
- Raises:
ValueError – If only one of
outcome_proxiesandproxy_meanis supplied, ifgamma< 1, or if the proxy constraints admit no feasible weights.
- class pyrake.estimation.population.SAIPWEstimator(propensity_scores, outcomes, predicted_outcomes, mean_predicted_outcome, estimand=None, estimand_class=None, binary_outcomes=True, **kwargs)[source]#
Bases:
SIPWEstimatorStabilized Augmented Inverse Propensity Weighted Estimator.
- Parameters:
propensity_scores (list_like) – Propensity scores.
outcomes (list_like) – Outcomes or responses. Should have the same length as
propensity_scores.predicted_outcomes (list_like) – Predicted outcomes corresponding to each response. Should have the same length as
propensity_scores.mean_predicted_outcome (float) – Mean of predicted outcomes in target population.
binary_outcomes (bool, optional) – Indicates whether the outcomes are binary. If
outcomescontains values other than 0 and 1, we conclude the outcomes are not binary; if all values are 0 and 1 we conclude outcomes are binary. The only place this matters is in the sensitivity analysis, which is faster for binary outcomes than in general.estimand (Estimand, optional) – An
Estimandobject representing the thing to be estimated. Defaults toPopulationMean.estimand_class (type, optional) – Estimand class to construct from
propensity_scoreswhenestimandis not given. Defaults toPopulationMean.kwargs (dict, optional) – Extra arguments forwarded to the estimator constructor.
Notes
The SAIPW estimator augments the SIPW estimator with a model for the outcome, just as the AIPW estimator does. See notes from those two estimators.
- point_estimate()[source]#
Calculate a point estimate.
- Returns:
estimate – Mean predicted outcome plus the SIPW estimate of the mean residual.
- Return type:
- variance()[source]#
Calculate the variance.
Per (Sarig, Galili, Eilat 2023, Appendix D.2), an estimator for the variance is:
Σᵢ wᵢ² × (yᵢ − pe)² / (Σᵢ wᵢ)²,
where pe is the point estimate.
- Returns:
variance – Estimated sampling variance of the point estimate.
- Return type:
- sensitivity_analysis(gamma=6.0, outcome_proxies=None, proxy_mean=None, alpha=0.1)[source]#
Perform a sensitivity analysis.
Calculate a range of point estimates implied by the Gamma factor.
- Parameters:
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes.
outcome_proxies (array_like, optional) – A proxy for the outcome with a known population mean. See
SIPWEstimator.sensitivity_analysisfor details. The proxy constraint applies to the same (SAIPW) weights.proxy_mean (float, optional) – Known population mean of the outcome proxy.
alpha (float, optional) – Significance level for the proxy tolerance. Defaults to 0.10.
- Returns:
lb, ub – Lower and upper bounds on the point estimate.
- Return type:
- Raises:
ValueError – If
gamma< 1, if only one ofoutcome_proxiesandproxy_meanis supplied, or if the proxy constraints admit no feasible weights (propagated fromSIPWEstimator.sensitivity_analysis).
Notes
See the Notes in
WeightingEstimatorandSIPWEstimatorfor overall context.
- class pyrake.estimation.population.RatioEstimator(propensity_scores, numerator_outcomes, denominator_outcomes, estimand=None, estimand_class=None, estimator_class='SIPW', numerator_estimator_class=None, denominator_estimator_class=None, numerator_kwargs=None, denominator_kwargs=None, **kwargs)[source]#
Bases:
WeightingEstimatorEstimate the ratio of two means in some population.
- Parameters:
propensity_scores (list_like) – Propensity scores.
numerator_outcomes (list_like) – Outcomes or responses corresponding to numerator and denominator. Should have the same length as
propensity_scores.denominator_outcomes (list_like) – Outcomes or responses corresponding to numerator and denominator. Should have the same length as
propensity_scores.estimand (Estimand, optional) – An
Estimandobject representing the thing to be estimated. Defaults toPopulationMean.estimand_class (type, optional) – Estimand class to construct from
propensity_scoreswhenestimandis not given. Defaults toPopulationMean.estimator_class (["IPW", "AIPW", "SIPW", "SAIPW"], optional) – What kind of estimator to use. Defaults to “SIPW”. Currently only “SIPW” is supported.
numerator_estimator_class (["IPW", "AIPW", "SIPW", "SAIPW"], optional) – If you really want to use different estimator classes for numerator vs denominator, you can. Defaults to
estimator_class. Currently only “SIPW” is supported.denominator_estimator_class (["IPW", "AIPW", "SIPW", "SAIPW"], optional) – If you really want to use different estimator classes for numerator vs denominator, you can. Defaults to
estimator_class. Currently only “SIPW” is supported.numerator_kwargs (dict_like) – Extra kwargs to pass to the estimators.
denominator_kwargs (dict_like) – Extra kwargs to pass to the estimators.
kwargs (dict_like) – Extra kwargs to pass to the estimators.
- property weights#
Weights from the numerator estimator.
- Returns:
weights – Weight for each of the
Msample members.- Return type:
(M,)
npt.NDArray[np.float64]
- property propensity_scores#
Propensity scores from the numerator estimator.
- Returns:
propensity_scores – Estimated response propensity for each sample member.
- Return type:
(M,)
npt.NDArray[np.float64]
- point_estimate()[source]#
Calculate a point estimate.
- Returns:
estimate – Ratio of the numerator and denominator point estimates.
- Return type:
- variance()[source]#
Calculate the variance.
Uses the delta method to calculate the variance.
- Returns:
variance – Estimated sampling variance of the ratio estimate.
- Return type:
- sensitivity_analysis(gamma=6.0, outcome_proxies=None, proxy_mean=None, alpha=0.1)[source]#
Perform a sensitivity analysis.
Calculate a range of point estimates implied by the Gamma factor.
- Parameters:
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See Notes.
outcome_proxies (array_like, optional) – Ignored by this estimator; proxy constraints are not supported here.
proxy_mean (float, optional) – Ignored by this estimator.
alpha (float, optional) – Ignored by this estimator.
- Returns:
lb, ub – Lower and upper bounds on the point estimate.
- Return type:
- Raises:
ValueError – If
gamma< 1.
Notes
See the Notes in
WeightingEstimatorfor overall context.We calculate
inf Σᵢwᵢxᵢ/Σᵢwᵢyᵢ
over wlᵢ ≤ wᵢ ≤ wuᵢ as the lower bound of the sensitivity interval, and the supremum as the upper bound. These are linear fractional programs subject to linear inequality constraints. They may be transformed to equivalent linear programs and solved efficiently, as described in Boyd and Vandenberghe (2004).
References
Boyd, Stephen and Vandenberghe, Lieven, Convex Optimization, Cambridge University Press, 2004.
Linear Combinations#
Linear combination estimator.
- class pyrake.estimation.linear_combination.LinearCombinationEstimator(terms, affine=0.0)[source]#
Bases:
WeightingEstimatorAffine combination of WeightingEstimators.
Estimates:
θ = affine + Σᵢ cᵢθᵢ,
where each θᵢ is estimated by the corresponding component estimator. Component estimators may be
MeanEstimator,TreatmentEffectEstimator, or otherLinearCombinationEstimatorobjects.Sensitivity analysis is valid because the objective is separable across components: hidden bias in each component contributes independently, and the worst-case bounds combine linearly (with sign-aware bound selection).
- Parameters:
terms (list of (float, WeightingEstimator) pairs) – Coefficients and their associated estimators.
affine (float, optional) – Constant offset. Defaults to 0.0.
Notes
Variance is computed assuming independence across component estimators:
var(θ) = Σᵢ cᵢ²var(θᵢ).
This is exact when components are fit on disjoint datasets (e.g. different treatment arms or independent studies). If components share data, variance will be understated and variance-based methods (
confidence_interval,pvalue) will be anti-conservative. Bootstrap-based methods (expanded_confidence_interval) carry the same independence assumption since each component is resampled independently.- point_estimate()[source]#
Calculate the point estimate.
- Returns:
estimate – Offset plus the coefficient-weighted sum of component estimates.
- Return type:
- variance()[source]#
Calculate the variance.
Assumes independence across component estimators. See class docstring.
- Returns:
variance – Coefficient-weighted sum of component variances.
- Return type:
- sensitivity_analysis(gamma=6.0, outcome_proxies=None, proxy_mean=None, alpha=0.1, *, proxy_kwargs=None, **kwargs)[source]#
Perform a sensitivity analysis.
The analysis is separable across components. For coefficient c and component sensitivity interval [lb_i, ub_i]:
c >= 0: contributes c * lb_i to the overall lower bound and c * ub_i to the overall upper bound.
c < 0: contributes c * ub_i to the overall lower bound and c * lb_i to the overall upper bound.
The affine term shifts both bounds by the same constant.
- Parameters:
gamma (float, optional) – The Gamma factor. Must be >= 1.0, with 1.0 indicating perfect propensity scores. Defaults to 6. See
WeightingEstimator.outcome_proxies (array_like, optional) – Accepted for override compatibility with
WeightingEstimator; must be None. Useproxy_kwargsinstead.proxy_mean (float, optional) – Accepted for override compatibility with
WeightingEstimator; must be None. Useproxy_kwargsinstead.alpha (float, optional) – Significance level for the proxy tolerance. Defaults to 0.10.
proxy_kwargs (list of dict, optional) – Per-component keyword arguments forwarded to each component’s
sensitivity_analysis. Must have the same length asterms. Each dict is unpacked into the corresponding component’s call, so the keys must match that component’s signature. Use an empty dict{}for components that need no proxy arguments. For example, aMeanEstimatorcomponent acceptsoutcome_proxiesandproxy_mean, while aTreatmentEffectEstimatoracceptscontrol_outcome_proxies,treated_outcome_proxies, andproxy_mean.kwargs (dict, optional) – Accepted for override compatibility with
WeightingEstimator; must be empty.
- Returns:
lb, ub – Lower and upper bounds on the point estimate.
- Return type:
- Raises:
TypeError – If
outcome_proxies,proxy_mean, or unexpected keyword arguments are supplied.ValueError – If
proxy_kwargsdisagrees withtermsin length, or ifgamma< 1 (propagated from the componentsensitivity_analysiscalls).
- resample(B, seed=None)[source]#
Yield a sequence of resampled estimators.
Each of the B bootstrap iterations yields a new LinearCombinationEstimator whose components are independently resampled from their respective component estimators.
- expanded_confidence_interval(alpha=0.1, gamma=6.0, alternative='two-sided', bootstrap=True, B=1000, seed=None)[source]#
Calculate an expanded confidence interval.
Each bootstrap replicate independently resamples every component estimator and recomputes the sensitivity interval for the resulting linear combination (exploiting the separability property). Percentiles of those bootstrap sensitivity bounds are returned as the expanded confidence interval. With
bootstrap=Falsethe normal approximation is used instead: the sensitivity interval is expanded by a multiple of the standard error on each side, with no resampling required.- Parameters:
alpha (float, optional) – P-value threshold. Defaults to 0.10 (90% interval).
gamma (float, optional) – The Gamma factor. Must be >= 1.0. Defaults to 6.
alternative (["two-sided", "less", "greater"], optional) – Defaults to “two-sided”.
bootstrap (bool, optional) – If True (default), use the percentile bootstrap. If False, use the normal approximation (no resampling).
B (int, optional) – Number of bootstrap replications. Ignored when
bootstrap=False. Defaults to 1_000.seed (int, list_like, etc) – A seed for
numpy.random.default_rng. Ignored whenbootstrap=False.
- Returns:
lb, ub – Lower and upper bounds on the confidence interval. For one-sided intervals, only one of these will be finite.
- Return type:
- Raises:
ValueError – If
gamma< 1 oralternativeis not recognized.