cleverly.sensitivity.SimulatedConfoundingResult

class cleverly.sensitivity.SimulatedConfoundingResult(estimand: str, original_estimate: float, movement_scale: Literal['estimate_difference', 'log_ratio'], grid: ConfounderStrengthGrid, cells: tuple[SimulatedConfoundingCell, ...], calibrations: tuple[ObservedConfounderCalibration, ...], root_seed: int, latent_seed: int, refit_seed: int, n_repeats: int, repeat_aggregation: Literal['coordinatewise_median'], treatment_family: str, outcome_family: str, treatment_law: str, outcome_law: str, weight_report: WeightReport, backend: str | None = None, stratum: tuple[Any, ...] | None = None, strata_names: tuple[str, ...] = (), population: Literal['baseline', 'perturbed_treatment_group'] = 'baseline', conditioning_arm: Any = None, known_mechanism_carried: bool = False, treatment_components: tuple[str, ...] = ())

Store a qualitative simulated-confounding stress surface.

Parameters:

estimandstr

Binary-treatment ATE, ATT, ATC, counterfactual-mean, risk-ratio, odds-ratio, or population-attributable-contrast alias, named modified-policy mean alias, or named modified-policy contrast alias.

original_estimatefloat

Point estimate from the unperturbed fitted result.

movement_scale{“estimate_difference”, “log_ratio”}

Scale used for the signed displacement. Ratio estimates use their stored log value. Other estimates use their reported value.

gridConfounderStrengthGrid

Explicit strength pairs evaluated by the surface.

cellstuple of SimulatedConfoundingCell

Successful estimates and retained failures in grid order.

calibrationstuple of ObservedConfounderCalibration

Optional source-style comparisons against numeric observed covariates.

root_seedint

Seed resolved for the complete operation.

latent_seedint

Tagged child seed used to draw the shared latent vector.

refit_seedint

Seed reused by every estimator refit. It equals root_seed. A refit reuses the repeat seed sequence of the original fit only when this 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 the refits a different sequence, so movement near the anchor can carry a fold artifact. Perturbing a stratification variable can also change the realised folds.

n_repeatsint

Number of complete cross-fitting draws in the original and refitted estimates.

repeat_aggregation{“coordinatewise_median”}

Estimator-owned rule that names how the estimator aggregates the complete cross-fitting draws when there is more than one draw. The estimator applies no aggregation to a single draw.

treatment_familystr

Treatment family covered by the perturbation law.

outcome_familystr

Original outcome family.

treatment_lawstr

Human-readable treatment perturbation rule.

outcome_lawstr

Human-readable outcome perturbation rule.

weight_reportWeightReport

Provenance for the fixed empirical row-mass vector used by every cell.

backendstr or None

Dataframe backend used by frame methods.

stratumtuple or None

Selected baseline stratum values. None selects the full baseline population.

strata_namestuple of str

Names of the columns defining the selected baseline stratum.

population{“baseline”, “perturbed_treatment_group”}

Whether the target averages over its baseline population or its cell’s observed treatment group. ATT and ATC use the latter.

conditioning_armAny or None

Original treatment label defining the ATT or ATC population.

treatment_componentstuple of str

The component columns of a vector treatment, in the grid’s order, or (). Each cell’s treatment_strength and induced_treatment_association then hold one value per component in this order.

known_mechanism_carriedbool

Whether the fitted data declared a known treatment mechanism. The flip of strength \(s\) is drawn from a latent normal independent of \(W\), so the flipped treatment’s mechanism is known too: \(g_s(a \mid W) = (1 - s)\, g_0(a \mid W) + s\, g_0(1 - a \mid W)\). Every cell that moves the treatment declares \(g_s\), and its refit divides by it.

Attributes:

target_measure{“unweighted”, “fixed_empirical_tilt”}

Name the empirical measure on which every cell is evaluated.

association_population{“selected_baseline_stratum”, “full_fitted_population”}

Name the baseline rows used for the induced treatment association.

calibration_population{“full_fitted_population”}

Name the original rows used for observed-covariate calibration.

refit_population{“full_fitted_population”}

Name the rows perturbed together before every complete estimator refit.

See also

simulated_confounding

Build this result from a fitted estimator.

Methods

SimulatedConfoundingResult.calibration_frame() → Any

Return model-dependent observed-covariate comparisons.

Returns:

dataframe

One row per covariate and perturbed-variable role.

SimulatedConfoundingResult.population_lines() → tuple[str, ...]

Return the population provenance of this surface, one field to a line.

The single field list and label vocabulary that summary() prints and that the post-fit assessment row joins with "; ". Written twice the two reports drift, and a reader cannot tell which population a movement belongs to.

Returns:

tuple of str

One label: value line for each population field, in a fixed order.

SimulatedConfoundingResult.summary() → str

Return a qualitative text summary without an inferential verdict.

Returns:

str

Original estimate, seeds, perturbation laws, cell movements, and the induced treatment association of each cell.

SimulatedConfoundingResult.to_frame() → Any

Return one backend-native row per declared strength pair.

Returns:

dataframe

Estimates, the movement scale of the displacement, displacements, induced treatment associations, and retained failure details. Two population columns join a movement to the rows it belongs to. association_population repeats association_population on every row, which names the baseline rows the association was measured on. target_population_fraction carries SimulatedConfoundingCell.target_population_fraction, which is the conditioning-arm share that cell targets. A failed cell keeps its fraction, because the surface records it before the refit.

Attributes

SimulatedConfoundingResult.association_population

Name the baseline rows used for the induced treatment association.

SimulatedConfoundingResult.backend: str | None = None

SimulatedConfoundingResult.calibration_population

Name the original rows used for observed-covariate calibration.

SimulatedConfoundingResult.complete

Return whether every declared cell produced an estimate.

SimulatedConfoundingResult.conditioning_arm: Any = None

SimulatedConfoundingResult.failures

Return structured failures in grid order.

SimulatedConfoundingResult.known_mechanism_carried: bool = False

SimulatedConfoundingResult.population: Literal['baseline', 'perturbed_treatment_group'] = 'baseline'

SimulatedConfoundingResult.refit_population

Name the rows perturbed together before every complete estimator refit.

SimulatedConfoundingResult.strata_names: tuple[str, ...] = ()

SimulatedConfoundingResult.stratum: tuple[Any, ...] | None = None

SimulatedConfoundingResult.successful_cells

Return cells that produced estimates in grid order.

SimulatedConfoundingResult.target_measure

Name the empirical measure on which every cell is evaluated.

SimulatedConfoundingResult.treatment_components: tuple[str, ...] = ()

SimulatedConfoundingResult.estimand: str

SimulatedConfoundingResult.original_estimate: float

SimulatedConfoundingResult.movement_scale: Literal['estimate_difference', 'log_ratio']

SimulatedConfoundingResult.grid: ConfounderStrengthGrid

SimulatedConfoundingResult.cells: tuple[SimulatedConfoundingCell, ...]

SimulatedConfoundingResult.calibrations: tuple[ObservedConfounderCalibration, ...]

SimulatedConfoundingResult.root_seed: int

SimulatedConfoundingResult.latent_seed: int

SimulatedConfoundingResult.refit_seed: int

SimulatedConfoundingResult.n_repeats: int

SimulatedConfoundingResult.repeat_aggregation: Literal['coordinatewise_median']

SimulatedConfoundingResult.treatment_family: str

SimulatedConfoundingResult.outcome_family: str

SimulatedConfoundingResult.treatment_law: str

SimulatedConfoundingResult.outcome_law: str

SimulatedConfoundingResult.weight_report: WeightReport