cleverly.sensitivity.simulated_confounding

cleverly.sensitivity.simulated_confounding(result: TMLEResult, estimand: str = 'ate', *, grid: ConfounderStrengthGrid, benchmark_covariates: tuple[str, ...] = (), random_state: int | None = None) → SimulatedConfoundingResult

Refit a selected parameter across a simulated common-cause strength grid.

Parameters:

resultTMLEResult

Replayable backdoor-identified binary-treatment ATE, ATT, ATC, counterfactual mean, risk ratio, odds ratio, population attributable contrast, or continuous modified-policy fit. Ordinary binary TMLE also supports fixed regime means, regime contrasts, and incremental means and contrasts. Ordinary TMLE also supports binary and continuous MSM coefficients under built-in links. Baseline strata require estimator support for their targeting.

estimandstr

Parameter alias to report. The free function needs an explicit ey1, ey0, or ey[...] alias for a binary counterfactual mean. Binary ratio fits use rr or or. Population attributable contrasts use par or paf. A continuous fit requires an explicit ey_policy[...] alias of a nonzero-delta policy, an ate_policy[...] alias, or an msm[...] coefficient. Fixed regimes use ey_regime[...] or ate_regime[...]. An MSM uses msm[term]. Incremental targets use ey_ipsi[...] or ate_ipsi[...]; a multiplier-one mean is refused. A conditional target requires its complete reported stratum alias.

gridConfounderStrengthGrid

Explicit treatment and outcome perturbation strengths.

benchmark_covariatestuple of str

Numeric observed covariates for optional calibration on the full original population.

random_stateint or None

Root seed. None uses the fitted estimator’s seed or draws a recorded seed.

Returns:

SimulatedConfoundingResult

Estimate movements on the scale movement_scale names, the induced treatment association of each cell, fixed-weight provenance, and retained cell failures. The result has no verdict or sensitivity-adjusted inference.

See also

ConfounderStrengthGrid

The explicit strength declaration.

cleverly.sensitivity.omitted_variable_bounds

A non-refit bias-bound analysis.

Notes

Every non-anchor cell refits under the resolved root seed, and the zero-strength anchor is the original fit itself. The root seed does not promise identical realised folds, for two reasons. First, a refit reuses the repeat seed sequence of the original fit only when the root seed equals the seed of that fit. random_state=None resolves to the seed of the fit when the fit declared one. An unseeded fit, or an explicit random_state other than the seed of the fit, gives every non-anchor cell a different sequence, so movement near the anchor can carry a fold artifact. Second, treatment-stratified or outcome-stratified splitting can change assignments after the surface perturbs that variable.

An ordinary-TMLE fit can declare fixed probability weights. Binary complete-outcome collaborative-TMLE and DR-TMLE fits can also declare them. Every replacement and refit keeps the normalized weight on its original row. The induced association conditions this empirical law on the selected baseline stratum. Numeric calibration uses the full original population. Longitudinal, multi-arm, missing-outcome, intermediate, estimated-weight, and clustered fits are refused before calibration, a draw, or a refit. Execution and the assessment capability share the same ordered reasons.

All strata share the same full-row latent draw and complete estimator refit. Baseline stratum membership stays fixed. ATT and ATC instead recompute their observed-treatment membership from each cell’s replaced treatment, within the selected baseline population. Their movement therefore includes composition changes. Their induced association still includes both treatment arms, because treatment is constant within one treatment group. Each cell records that group’s weighted fraction of its baseline population.

PAR cells recompute the observed outcome mean minus the reference counterfactual mean. PAF cells recompute one minus the reference mean divided by the observed outcome risk. Both use estimate differences for movement. PAF keeps negative fractions without a log transform or clipping. A zero observed risk leaves a retained failed PAF cell. PAR and PAF support ordinary TMLE only. The identified effect’s method catalog evidences no collaborative score and no reduced-dimension correction for these observed-law contrasts, so it offers neither C-TMLE nor DR-TMLE for them.

Binary ordinary TMLE supports fixed Static, Rule, and Stochastic regimes. The operation validates declared policy arrays against every stored cross-fitting draw and freezes those arrays on the original baseline rows. MSMs support built-in identity, log, and logit links for binary and continuous treatments. Grid designs and raw projection weights stay fixed. Continuous MSMs reevaluate the declared deterministic functions at each perturbed observed dose; the estimator rebuilds observed weights and the integration-support mask. Coefficient movement is a difference on the stored coefficient scale, including log and logit coefficients. The operation does not exponentiate that difference.

Incremental means and contrasts keep their odds multipliers, names, and reference. Complete refits rebuild intervention densities from the refitted treatment mechanism and retain its targeting contribution. Movement includes this intervention change. A multiplier-one mean is the natural course and is refused before a draw; contrasts against that reference remain supported. Custom intervention types and MSM links remain refused. All these extensions use exact ordinary TMLE only. Incremental targets and nonlinear or continuous MSMs refuse baseline strata upstream.

Each cell reports induced_treatment_association. It is the correlation between the shared latent vector and the treatment of that cell. For binary treatment, the flip is non-differential misclassification. Its induced association depends on the treated fraction. A balanced design reports an association near zero. For continuous treatment, the operation applies A' = A + k_A U and reports the correlation that linear perturbation achieves on the analysis data. That association grows with the treatment strength by construction, so it is not on its own evidence of confounding. A confounding path also needs the latent vector in the outcome, which happens only at a nonzero outcome strength. A cell whose outcome strength is zero therefore has no confounding path, whatever its association, and its movement reports dose perturbation alone.

The zero treatment-strength column carries no confounding path either, because the latent vector never reaches the treatment there. For a Gaussian outcome that column reports the level shift Y' = Y - k_Y U alone. The level shift largely cancels in an ate_policy contrast. A policy mean keeps it, so read the zero treatment-strength column of an ey_policy surface as an artifact of the outcome law.

A zero-delta shift is the natural course, its policy mean is E[Y], and it has no counterfactual treatment dependence. simulated_confounding refuses that mean before it draws the latent vector. It still accepts an ate_policy contrast that uses the natural course as its reference. The same refusal applies to NaturalCourseMean. PAR and PAF retain counterfactual treatment dependence through their reference intervention.