cleverly.interventions.Incremental

class cleverly.interventions.Incremental(delta: float | Mapping[Hashable, float] | tuple[tuple[Hashable, float], ...], name: str = '')

Multiply the odds of treatment levels by declared factors.

Parameters:

deltafloat or mapping

On a treatment with two levels, the odds multiplier of the second sorted level, strictly positive. 1.0 is the natural course – the intervention that changes nothing, since \(q = g\) exactly – whose mean is \(E[Y]\) and which is the usual reference. Above one shifts the population toward the second level, below one away from it.

On a treatment with more than two levels, and optionally on two, a mapping from a treatment label (as the data reports it) to its strictly positive factor \(\delta_a\). The odds of level \(a\) against level \(b\) are multiplied by \(\delta_a/\delta_b\). A level the mapping does not name keeps the factor 1. The family is scale free: multiplying every factor by one constant changes nothing. {level1: d} equals d on two levels. The labels of an all-categorical vector treatment are the tuples of its observed levels.

Unlike a Shift’s cap, nothing here has to be declared to keep the parameter well defined: \(q_\delta\) is a probability for any positive factors and any \(g\), which is the whole appeal.

namestr

What this intervention is called in reported parameter names. Defaults to "odds x2.5" style for a scalar, "odds high x2, low x0.5" for a mapping, and "natural course" when every declared factor is 1. The default echoes each key as written: {1: 2.0} and {1.0: 2.0} resolve to the same factors and carry the names "odds 1 x2" and "odds 1.0 x2".

Examples

>>> from cleverly.interventions import Incremental
>>> Incremental(2.0).name
'odds x2'
>>> Incremental({"high": 2.0, "low": 0.5}).name
'odds high x2, low x0.5'
>>> Incremental({"high": 2.0, "low": 0.5}).factors(("high", "low", "mid")).tolist()
[2.0, 0.5, 1.0]

Methods

Incremental.factors(levels: Sequence[Any], *, subject: str = 'the treatment') → ndarray[tuple[Any, ...], dtype[float64]]

The factor of every level, in the order of levels.

Parameters:

levelssequence

The treatment labels in arm-code order, as treatment_levels reports them.

subjectstr

What the refusals call the treatment.

Returns:

ndarray

(K,), strictly positive. A scalar on two levels gives (1, delta).

Raises:

DataError

If a scalar names a treatment with other than two levels, or a mapping key is not a level.

Attributes

Incremental.name: str = ''

Incremental.delta: float | Mapping[Hashable, float] | tuple[tuple[Hashable, float], ...]