cleverly.interventions.IncrementalSupport

class cleverly.interventions.IncrementalSupport(name: str, delta: tuple[tuple[str, float], ...], guaranteed: tuple[float, float], min_propensity: float, max_ratio: float, effective_sample_size: float, ess_ratio: float, score_load: _InterventionLoadRow | None = None, score_load_omission: str | None = None)

Overlap for one tilt – which for this estimand is a statement, not a warning.

The clever covariate is bounded by \(\min\delta/\max\delta\) and \(\max\delta/\min\delta\) however small the mechanism gets, so guaranteed is what the tilt promises before seeing any data and max_ratio is what it delivered. The two agreeing is the normal case; the report exists so that a reader can see the effective sample size stay near \(n\) where an arm-indexed fit’s would have collapsed.

This row is hashable and its two siblings are not, and that difference is deliberate. RegimeSupport and PolicySupport carry quantile mappings that are part of what makes one of their rows different from another, so neither has ever had a hash. This row’s identity is the declared tilt and what the data did with it, all of which was hashable until score_load was added. That field holds a dict, so adding it made every fitted row of this class raise TypeError: unhashable type: 'dict' while an omitted row, whose field is None, still hashed. Declaring the field hash=False restores the hash rather than preserving one. compare=False would have gone too far: two tilts that differ only in their fitted score load are different rows and still compare unequal, and only the dict leaves the hash.

Parameters:

namestr

Report label of the tilt.

deltatuple of tuple

(label, factor) for every level, in arm-code order: the resolved factors this row describes.

guaranteedtuple of float

(min factor / max factor, max factor / min factor): the bounds the clever covariate cannot leave, whatever the mechanism does. A property of the declared tilt alone: no data went into it.

min_propensityfloat

Smallest estimated \(g(a \mid W)\) over rows and levels, for comparison with an arm-indexed fit rather than because this estimand divides by it.

max_ratiofloat

Largest clever covariate the data produced.

effective_sample_sizefloat

Kish effective sample size of those weights.

ess_ratiofloat

That size as a share of n.

score_load_InterventionLoadRow or None

Concentration of the exact absolute score weights retained for this tilt’s outcome equation, and the cross-fitting draw it describes. None means the artifact did not supply a usable column. The twelve keys are equation, n_total, n_targeted, effective, targeted_ratio, total_ratio, top_1pct, top_5pct, max_load, zero_load, reported_repeat and n_repeats.

score_load_omissionstr or None

Machine-readable reason why score_load is unavailable.

Methods

IncrementalSupport.summary() → str

Return a printable summary.

Returns:

str

A printable table, one line per row of the report.

Attributes

IncrementalSupport.score_load: _InterventionLoadRow | None = None

Kept out of the generated __hash__ and left in __eq__, which is what gives this class its hash back. The class docstring says what adding the field broke and why the siblings are unhashable for a different reason.

IncrementalSupport.score_load_omission: str | None = None

IncrementalSupport.name: str

IncrementalSupport.delta: tuple[tuple[str, float], ...]

IncrementalSupport.guaranteed: tuple[float, float]

IncrementalSupport.min_propensity: float

IncrementalSupport.max_ratio: float

IncrementalSupport.effective_sample_size: float

IncrementalSupport.ess_ratio: float