cleverly.fluctuation.FoldFluctuation

class cleverly.fluctuation.FoldFluctuation(index: ndarray[tuple[Any, ...], dtype[int64]], epsilon: ndarray[tuple[Any, ...], dtype[float64]], score: ndarray[tuple[Any, ...], dtype[float64]], converged: bool, n_iter: int, trace: tuple[float, ...] = (), score_scale: ndarray[tuple[Any, ...], dtype[float64]] | None = None, thresholds: ndarray[tuple[Any, ...], dtype[float64]] | None = None, rule_ratio: float | None = None, best_iterate: int | None = None)

One validation fold’s contribution to a cross-validated targeting step.

Recorded so a CV-TMLE fit can be inspected fold by fold. A fluctuation coefficient that swings wildly across folds is the signature of an unstable clever covariate – something the pooled epsilon averages away and hides.

Parameters:

indexndarray

Row positions of this validation fold, into the fitted sample.

epsilonndarray

Fluctuation coefficients solved on this fold alone, one per clever-covariate column.

scorendarray

Solved score per column over this fold’s rows, the fold’s own estimating equation.

convergedbool

Whether this fold’s own solve reached its tolerance.

n_iterint

Solver iterations this fold took.

tracetuple of float

Relative score norm through this fold’s solve.

score_scalendarray or None

Per-column largest score this fold’s rows could produce, or None when the solver reported no scale.

thresholdsndarray or None

Under a declared stopping rule, the threshold of each score column on this fold’s rows, whose unit count is the fold’s own; None under "relative".

rule_ratiofloat or None

Under a declared rule, the largest score over its threshold on this fold; the fold met the rule when it is at most one. None under "relative".

best_iterateint or None

Under iterate="best", the index of the iterate this fold reports, as Fluctuation.best_iterate; None under iterate="last".

Attributes:

nint

How many rows this validation fold holds.

score_normfloat

Largest absolute score component, in the outcome’s own units.

relative_score_normfloat

Largest score component relative to its maximum possible magnitude.

See also

cleverly.fluctuation.Fluctuation

The targeting step these folds make up.

Methods

Attributes

FoldFluctuation.best_iterate: int | None = None

The index of the reported iterate under iterate="best".

FoldFluctuation.n

How many rows this validation fold holds.

FoldFluctuation.relative_score_norm

Largest score component relative to its maximum possible magnitude.

FoldFluctuation.rule_ratio: float | None = None

FoldFluctuation.score_norm

Largest absolute score component, in the outcome’s own units.

FoldFluctuation.score_scale: ndarray[tuple[Any, ...], dtype[float64]] | None = None

Component-wise scale used to decide whether this fold reached its score root.

FoldFluctuation.thresholds: ndarray[tuple[Any, ...], dtype[float64]] | None = None

The fold’s thresholds and rule ratio under a declared stopping rule.

FoldFluctuation.trace: tuple[float, ...] = ()

Complete relative-score trajectory for this fold. trace[0] is the score before its first update, under the same contract as Fluctuation.trace.

FoldFluctuation.index: ndarray[tuple[Any, ...], dtype[int64]]

FoldFluctuation.epsilon: ndarray[tuple[Any, ...], dtype[float64]]

FoldFluctuation.score: ndarray[tuple[Any, ...], dtype[float64]]

FoldFluctuation.converged: bool

FoldFluctuation.n_iter: int