cleverly.variable_importance

cleverly.variable_importance(data: Any, *, outcome: str, candidates: Sequence[str], covariates: Sequence[str], estimand: str = 'ate', estimator: TMLE | None = None, adjust_for_other_candidates: bool = True, delta: str | None = None, weights: str | None = None, weights_type: str = 'probability', weights_estimated: bool = False, id: str | None = None) → VariableImportanceResult

Estimate one causal importance parameter per candidate exposure.

Each candidate is fitted as the treatment. With adjust_for_other_candidates=True (the default), the other candidates join the supplied baseline covariates, matching the interpretation “intervene on this exposure while adjusting for the others.” Set it false when the other candidates are descendants, colliders, or otherwise should not be conditioned on.

Tests are two-sided on each parameter’s native null (zero for differences/levels, one for ratios), then adjusted jointly by Benjamini–Hochberg. This corrects the one-tail normal probability used by the historical tmle3_vim helper.

Refuses, before the first fit, when the estimator’s inference status on any candidate’s prepared data supplies no inference. A CTMLE whose strategy is "greedy", "ordered", "discrete", "lasso" or "learners" is one such case, and the inference reference lists each status. The adjustment above needs one p-value per candidate, and such a fit supplies none, so this procedure has no diagnostic form to fall back to. A "derivative" fit (C-TMLE0) supplies inference and is admitted, unless it declares propensity arrays, which describe one treatment only. Before that check, an estimator with a rule, a regime density or an MSM function that is not declared known meets the refusal that its own fit gives.

Parameters:

datadataframe

Observed study data.

outcomestr

Outcome column.

candidatessequence of str

Columns to fit as the treatment, one at a time.

covariatessequence of str

Baseline adjustment columns, shared by every candidate.

estimandstr

Alias targeted for each candidate.

estimatorTMLE or None

Configured estimator to reuse. None builds one with the defaults. An estimator whose status supplies no inference is refused here, because it reports no p-value.

adjust_for_other_candidatesbool

Whether the other candidates join the baseline covariates. Set it false when they are descendants, colliders, or otherwise should not be conditioned on.

deltastr or None

Outcome-observation indicator column.

weightsstr or None

Probability-weight column.

weights_type{“probability”}

Interpretation of weights.

weights_estimatedbool

Whether the supplied weights were estimated from these data.

idstr or None

Independent-cluster identifier used for variance estimation.

Returns:

VariableImportanceResult

One entry per candidate, with its estimate and adjusted p-value.