cleverly.interventions.Stochastic

class cleverly.interventions.Stochastic(density_fn: Callable[[Any], Any], name: str, density_kind: Literal['known', 'estimated'] | None = None)

A known stochastic regime: assign arm \(a\) with probability \(g^\star(a \mid W)\).

density_fn is handed the covariate frame and returns an (n, K) array whose columns are in arm_codes order and whose rows sum to one.

The same class is a node of a longitudinal plan, inside a DynamicRegimen. There the unit draws its arm at that node with probability \(q_t(a \mid H_t)\).

Known is the load-bearing word, and density_kind="known" declares it. \(g^\star\) must be a fixed function of \(W\), chosen independently of the analysis sample. For a population-mechanism-indexed odds tilt, the regime influence curve omits the pathwise derivative through the mechanism. A realized learned density defines a different, data-adaptive target; inference for it needs conditions this API does not check. A callable can close over any estimate and no code can inspect a closure, so the declaration is the check. refuse_regime_densities() refuses None and "estimated" when the regime is built, and TMLE refuses them again before any learner. For the population odds-tilt target, use Incremental, whose curve carries the mechanism term.

Parameters:

density_fncallable()

Maps the covariate frame to an (n, K) array of arm probabilities. At a longitudinal node it is handed the policy frame (policy_frame()): the history \([W, L_1, \ldots, L_t]\) and the earlier treatments, as labels. It returns an (n, K_t) array whose columns follow treatment_levels[t - 1], or a dataframe whose columns are exactly those levels.

namestr

Label used in reported parameter names. At a longitudinal node the settings report prints it as q:name.

density_kind{“known”, “estimated”} or None

The declaration that density_fn is a known function of the covariates, or at a longitudinal node of the node history. "known" is the one value a fit accepts. None, the default, and "estimated" raise CapabilityError, and any other value raises DataError. It is the last field, so Stochastic(density_fn, name) keeps its positional order.

Methods

Stochastic.density(data: CausalData) → ndarray[tuple[Any, ...], dtype[float64]]

Evaluate this regime’s arm probabilities for every row.

Parameters:

dataCausalData

Validated study data, which supplies the covariates and the arm order.

Returns:

ndarray

(n, K) density, columns in arm-code order.

Notes

It runs refuse_regime_densities() before it calls density_fn, because a modified regime can reach it directly with a declaration this version refuses.

Attributes

Stochastic.density_kind: Literal['known', 'estimated'] | None = None

Stochastic.density_fn: Callable[[Any], Any]

Stochastic.name: str