G-Computation Mean-Difference Inference for Proportion Responses

Fits a fractional-logit working model, $\mathrm{logit}\,E[Y_i \mid x_i] = x_i^\top\hat\beta$ (via fast_logistic_regression_cpp, treating the continuous-in-$(0,1)$ proportion as a quasi-binomial mean model — the same mean-model idea as InferencePropFractionalLogit), for a proportion outcome using treatment and, optionally, all recorded covariates, then estimates the marginal mean difference by G-computation: standardizing predicted mean proportions under all-treated and all-control assignments over the empirical covariate distribution (see gcomp_fractional_logit_point_estimate_cpp for the exact standardization formula). Inference uses a Huber-White sandwich-robust covariance for the regression coefficients and the delta method (analytic gradient of the standardized mean-difference functional with respect to $\hat\beta$, by default) to propagate that covariance onto the mean-difference scale, $\widehat{\mathrm{Var}}(\widehat{\mathrm{md}}) = \nabla^\top \widehat{\mathrm{Var}}(\hat\beta) \nabla$.

The implementation is optimized for resampling-based inference. It utilizes a fast C++ IRLS solver for the underlying fractional logit regression. During resampling draws, it bypasses the calculation of the sandwich covariance matrix and delta-method standard errors, providing a significant speedup when computing bootstrap or randomization distributions.

Variance fallback cascade. If the primary analytic-gradient/sandwich-covariance variance is non-finite (e.g. near-boundary fitted probabilities), up to eight progressively more conservative fallback strategies are tried in order (see the variance_fallback_methods constructor argument for the full list and their individual definitions): stabilized (PSD-projected) sandwich covariance, model-based (Fisher information) covariance, finite-difference gradients in place of the analytic delta-method gradient, and combinations with progressively stronger probability clipping. The first strategy in the ordered list that yields a finite, positive variance is used; an empty variance_fallback_methods vector always returns NA variance rather than erroring.

Super class

Inference -> InferencePropGCompMeanDiff

Methods

Public methods

InferencePropGCompMeanDiff$new()
InferencePropGCompMeanDiff$compute_estimate()
InferencePropGCompMeanDiff$get_standard_error()
InferencePropGCompMeanDiff$compute_estimate_with_bootstrap_weights()
InferencePropGCompMeanDiff$compute_asymp_confidence_interval()
InferencePropGCompMeanDiff$compute_asymp_two_sided_pval()
InferencePropGCompMeanDiff$compute_wald_two_sided_pval()
InferencePropGCompMeanDiff$compute_wald_confidence_interval()
InferencePropGCompMeanDiff$compute_bootstrap_two_sided_pval()
InferencePropGCompMeanDiff$compute_bootstrap_confidence_interval()
InferencePropGCompMeanDiff$approximate_bootstrap_distribution_beta_hat_T()
InferencePropGCompMeanDiff$clone()

+ inherited public methods from Inference

`InferencePropGCompMeanDiff$new()`

Uses the shared randomization two-sided p-value contract; see InferenceRand.

Initialize the g-computation inference object.

Usage

InferencePropGCompMeanDiff$new(
  des_obj,
  model_formula = NULL,
  verbose = FALSE,
  prob_clip_eps = 1e-06,
  prob_clip_strong_eps = 1e-04,
  max_resample_attempts = 50L,
  smart_cold_start_default = NULL,
  harden = TRUE,
  variance_fallback_methods = c("robust", "stabilized_robust", "model_based",
    "stabilized_robust_fd", "model_based_fd", "stabilized_robust_strong_clip",
    "model_based_strong_clip", "model_based_fd_strong_clip")
)

Arguments

des_obj

A completed DesignSeqOneByOne object with a proportion response.

model_formula

Optional formula for covariate adjustment. If NULL (default), the formula from the design object is used and its pre-computed design matrix is reused. If a formula is provided, a new design matrix is constructed from the design's imputed covariates.

verbose

Whether to print progress messages.

prob_clip_eps

Primary probability clamp applied to fitted values during model-based variance computation. Predicted probabilities are clipped to [prob_clip_eps, 1 - prob_clip_eps] before computing IWLS weights. Must be in [0, 0.5). Default 1e-6.

prob_clip_strong_eps

Stronger clamp used as a fallback when the primary variance strategy fails. Predicted probabilities and gradients are clipped to [prob_clip_strong_eps, 1 - prob_clip_strong_eps]. Must be in [0, 0.5) and should be $\ge$ prob_clip_eps. Default 1e-4.

max_resample_attempts

Maximum number of times a single bootstrap replicate may be redrawn when the drawn sample fails validity screening (e.g. near-perfect separation, too few observations per arm, excessive boundary mass). If all attempts fail the replicate is recorded as NA, silently reducing the effective B. Can be overridden per-call in approximate_bootstrap_distribution_beta_hat_T. Must be a positive integer. Default 50L.

smart_cold_start_default

Whether to use smart cold start values.

harden

Whether to apply robustness measures.

variance_fallback_methods

Ordered character vector of variance strategies to attempt in sequence. Each name corresponds to a (gradient, covariance-matrix) pair; the first strategy that yields a finite, positive variance is used. Allowed values (in their default order) are:

"robust": Analytic delta-method gradient with the sandwich (HC) covariance.
"stabilized_robust": Same gradient; covariance projected to the nearest PSD matrix.
"model_based": Same gradient; Fisher-information (IWLS) covariance. Fitted probabilities are first clipped to [prob_clip_eps, 1 - prob_clip_eps], then the binomial variance weight $w_i = \hat\mu_i(1-\hat\mu_i)$ is further capped at 0.25. The cap is the global maximum of $p(1-p)$, attained at $p = 0.5$; it prevents a near-boundary fitted probability that slips through the clip from inflating the information matrix, which is mathematically correct because no Bernoulli variance can exceed 0.25.
"stabilized_robust_fd": Finite-difference (central-difference) gradient; stabilized sandwich covariance. The step size for coefficient $j$ is $h_j = \varepsilon^{1/3}(|\hat\beta_j| + 1)$, where $\varepsilon = $ .Machine$double.eps. The cube-root of machine epsilon is the theoretically optimal step that balances truncation error ($O(h^2)$ for central differences) against floating-point cancellation ($O(\varepsilon / h)$), giving a total error of $O(\varepsilon^{2/3})$.
"model_based_fd": Finite-difference gradient (same step rule as "stabilized_robust_fd"); model-based covariance with the 0.25 weight cap.
"stabilized_robust_strong_clip": Strong-clipped analytic gradient; stabilized sandwich covariance.
"model_based_strong_clip": Strong-clipped analytic gradient; model-based covariance (strong-clipped) with the 0.25 weight cap.
"model_based_fd_strong_clip": Strong-clipped finite-difference gradient (same step rule); model-based covariance (strong-clipped) with the 0.25 weight cap.

Pass a shorter vector or a single string to restrict which strategies are tried. An empty vector always returns NA variance.

`InferencePropGCompMeanDiff$compute_estimate()`

Computes the g-computation treatment-effect estimate.

Usage

InferencePropGCompMeanDiff$compute_estimate(estimate_only = FALSE)

Arguments

estimate_only: If TRUE, skip variance component calculations.

`InferencePropGCompMeanDiff$get_standard_error()`

Usage

InferencePropGCompMeanDiff$get_standard_error()

`InferencePropGCompMeanDiff$compute_estimate_with_bootstrap_weights()`

Usage

InferencePropGCompMeanDiff$compute_estimate_with_bootstrap_weights(
  subject_or_block_weights,
  estimate_only = FALSE
)

`InferencePropGCompMeanDiff$compute_asymp_confidence_interval()`

Computes a 1 - alpha confidence interval.

Usage

InferencePropGCompMeanDiff$compute_asymp_confidence_interval(alpha = 0.05)

Arguments

alpha: The confidence level in the computed confidence interval is 1 - alpha.

`InferencePropGCompMeanDiff$compute_asymp_two_sided_pval()`

Uses the shared asymptotic two-sided p-value contract; see InferenceAsymp.

Usage

InferencePropGCompMeanDiff$compute_asymp_two_sided_pval(delta = 0)

Arguments

delta: The null mean difference. Defaults to 0.

`InferencePropGCompMeanDiff$compute_wald_two_sided_pval()`

Computes a Wald two-sided p-value for the treatment effect.

Usage

InferencePropGCompMeanDiff$compute_wald_two_sided_pval(delta = 0)

Arguments

delta: The null mean difference. Defaults to 0.

`InferencePropGCompMeanDiff$compute_wald_confidence_interval()`

Computes a Wald confidence interval for the treatment effect.

Usage

InferencePropGCompMeanDiff$compute_wald_confidence_interval(alpha = 0.05)

Arguments

alpha: The significance level. Default 0.05.

`InferencePropGCompMeanDiff$compute_bootstrap_two_sided_pval()`

Computes a bootstrap two-sided p-value for the treatment effect.

Usage

InferencePropGCompMeanDiff$compute_bootstrap_two_sided_pval(
  delta = 0,
  B = 501,
  type = "symmetric",
  na.rm = FALSE,
  boundary_tol = 0.02,
  max_boundary_mass = 0.95,
  sep_tol = 0.02,
  min_group_n = 5L,
  show_progress = TRUE,
  min_number_usable_samples = 5L
)

Arguments

delta: The null mean difference. Defaults to 0.
B: Number of bootstrap samples.
type: Bootstrap p-value type. See InferenceNonParamBootstrap$compute_bootstrap_two_sided_pval.
na.rm: Whether to remove non-finite bootstrap replicates.
boundary_tol: Resample screening threshold for boundary mass near 0/1.
max_boundary_mass: Reject a resample when at least this fraction is near the boundary.
sep_tol: Separation tolerance used to reject nearly perfectly separated resamples.
min_group_n: Minimum number of observations required in each treatment arm.
min_number_usable_samples: Minimum number of finite bootstrap samples required.

`InferencePropGCompMeanDiff$compute_bootstrap_confidence_interval()`

Generic (non-screening-modified) bootstrap two-sided p-value, aliased directly from `InferenceNonParamBootstrap` so `compute_bootstrap_two_sided_pval()` can dispatch to it without relying on `super$`, which does not resolve under flat component composition.

Computes a bootstrap confidence interval.

Usage

InferencePropGCompMeanDiff$compute_bootstrap_confidence_interval(
  alpha = 0.05,
  B = 501,
  type = NULL,
  na.rm = TRUE,
  show_progress = TRUE,
  boundary_tol = 0.02,
  max_boundary_mass = 0.95,
  sep_tol = 0.02,
  min_group_n = 5L,
  min_number_usable_samples = 5L
)

Arguments

alpha: The confidence level 1 - alpha.
B: Number of bootstrap samples.
type: Bootstrap CI type.
na.rm: Whether to remove non-finite bootstrap replicates.
show_progress: Whether to show bootstrap progress.
boundary_tol: Resample screening threshold for boundary mass near 0/1.
max_boundary_mass: Reject a resample when at least this fraction is near the boundary.
sep_tol: Separation tolerance used to reject nearly perfectly separated resamples.
min_group_n: Minimum number of observations required in each treatment arm.
min_number_usable_samples: Minimum number of finite bootstrap samples required.

`InferencePropGCompMeanDiff$approximate_bootstrap_distribution_beta_hat_T()`

Generic (non-screening-modified) bootstrap confidence interval; see `compute_bootstrap_two_sided_pval_generic`.

Abbreviated bootstrap sampler that reuses a bootstrap worker.

Usage

InferencePropGCompMeanDiff$approximate_bootstrap_distribution_beta_hat_T(
  B = 501,
  show_progress = TRUE,
  max_resample_attempts = NULL,
  boundary_tol = 0.02,
  max_boundary_mass = 0.95,
  sep_tol = 0.02,
  min_group_n = 5L,
  debug = FALSE
)

Arguments

B: The number of bootstrap samples (default 501).
show_progress: Whether to show a progress bar.
max_resample_attempts: Maximum redraw attempts per bootstrap replicate before the replicate is recorded as NA. NULL (default) uses the value set at construction time.
boundary_tol: Resample screening threshold for boundary mass near 0/1.
max_boundary_mass: Reject a resample when at least this fraction is near the boundary.
sep_tol: Separation tolerance used to reject nearly perfectly separated resamples.
min_group_n: Minimum number of observations required in each treatment arm.

`InferencePropGCompMeanDiff$clone()`

The objects of this class are cloneable with this method.

Usage

InferencePropGCompMeanDiff$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.

Examples

# \donttest{
seq_des = DesignSeqOneByOneBernoulli$new(n = 10, response_type = 'proportion')
for (i in 1:10) {
  seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1)))
}
seq_des$add_all_subject_responses(runif(10))
inf = InferencePropGCompMeanDiff$new(seq_des)
inf$compute_estimate()
#> [1] 0.1160218
# }