cleverly.Targeting

class cleverly.Targeting(fluctuation: Literal['logistic', 'linear'] = 'logistic', algorithm: Literal['iterative', 'one_step'] = 'iterative', g_bounds: Literal['auto'] | float | tuple[float, float] = 'auto', q_bounds: tuple[float, float] | None = None, nuisance_bound: float = 0.01, submodel_alpha: float = 0.9995, target_weights: bool = False, step_size: float = 0.001, max_iter: int = 20, tol: float = 1e-10, stopping: Literal['relative', 'scaled_var', 'sample_size'] = 'relative', step_bound: float | None = None, step_search: bool = True, iterate: Literal['last', 'best'] = 'last', isotonic: bool = False)

Configure fluctuation, nuisance bounds, and solver behavior.

Parameters:

fluctuation{“logistic”, “linear”}, default=”logistic”

Fluctuation submodel family.

algorithm{“iterative”, “one_step”}, default=”iterative”

Targeting algorithm.

g_bounds{“auto”}, float, or tuple of float, default=”auto”

Treatment or cumulative-mechanism bounds.

q_boundstuple of float or None, default=None

The known support of a continuous outcome. None widens the observed range by ten percent, which reads every observed outcome, so a cross-fitted fit of a continuous outcome requires the support here. Refused on a binary outcome, which the estimator does not rescale. cleverly.datasets.make_nonlinear_bounded draws a proportion, for which q_bounds=(0.0, 1.0) states a fact about the law.

nuisance_boundfloat, default=0.01

Lower bound used by auxiliary nuisance regressions.

submodel_alphafloat, default=0.9995

Logistic-submodel shrink bound.

target_weightsbool, default=False

Whether probability weights enter the targeting score.

step_sizefloat, default=1e-3

Step size for compatible targeting.

max_iterint, default=20

Maximum targeting iterations.

tolfloat, default=1e-10

Score-equation convergence tolerance. It is the bar of stopping="relative", and the tolerance of the inner Newton solve under every rule.

stopping{“relative”, “scaled_var”, “sample_size”}, default=”relative”

The rule that decides the score equation is solved. "relative" is the shipped test: the largest score over the mean absolute clever covariate is at most tol. "scaled_var" and "sample_size" are the tmle3 convergence_type rules. Each compares the score, in the outcome’s units, with sd / (sqrt(n_u) * min(log(n_u), 10)) or 1 / n_u, where n_u counts the distinct units among the rows the solver receives and sd is the sample SD of the column’s per-unit influence curve. A declared rule is refused beside fluctuation="linear", which has no iteration to stop.

step_boundfloat or None, default=None

The longest step of one targeting iteration, in the units of the fluctuation coefficient. None takes the full Newton step. A positive number replaces the Newton step by the tmle3 constrained step: the iteration moves along the normalised score vector s / ||s|| and goes no further than step_bound. It needs algorithm="iterative" and fluctuation="logistic". A bounded walk can stop short of tol. Then the fit warns, reports converged=False and failure="max_iter_reached", and score_check fails it. The tmle3 pairing is stopping="sample_size" with a larger max_iter. Under stopping="relative" the walk reaches tol=1e-10 only with step_search=True and well over the default max_iter: 25 to 190 iterations on the six arm-mean fits of tests/unit/test_step_bound.py::TestRelativeReachability. A fit whose initial regression already meets the rule takes no step.

step_searchbool, default=True

Under step_bound, True takes the length in (0, step_bound] that minimises the weighted mean quasi-loss along the step, as tmle3 does with optim_delta_epsilon. False takes the whole bound, as delta_epsilon does. It needs step_bound.

iterate{“last”, “best”}, default=”last”

Which iterate of the targeting walk the fit reports. "last" reports the iterate at which the walk stopped. "best" is use_best of tmle3: it reports the iterate k >= 1 whose raw score vector has the smallest 2-norm, the first of any tie. The initial fit is never reported while a step exists. The walk still stops by the rule, n_iter and trace describe the whole walk, and converged is judged at the reported iterate. Fluctuation.best_iterate records the index. The best iterate differs from the last on a walk that oscillates, such as step_search=False. On algorithm="one_step" the norm never rises, so the best iterate is the last. It is refused beside fluctuation="linear", which has no iterates.

isotonicbool, default=False

Whether a longitudinal survival fit projects each curve’s levels and band limits onto a non-decreasing curve; see LTMLE. A point-treatment fit refuses True.

See also

TMLEMethod

Method configuration this object is the targeting half of.

Inference

Interval settings, which own alpha rather than submodel_alpha.

cleverly.sensitivity.truncation_curve

What the estimate does across g_bounds.

Examples

Truncate the treatment mechanism at a fixed bound rather than the data-driven one:

>>> from cleverly import Targeting
>>> Targeting(g_bounds=0.025).g_bounds
0.025

>>> Targeting().g_bounds
'auto'

Stop the targeting step by the tmle3 scaled_var rule instead of the shipped relative score:

>>> Targeting(stopping="scaled_var").stopping
'scaled_var'

Methods

Attributes

Targeting.algorithm: Literal['iterative', 'one_step'] = 'iterative'

Targeting.fluctuation: Literal['logistic', 'linear'] = 'logistic'

Targeting.g_bounds: Literal['auto'] | float | tuple[float, float] = 'auto'

Targeting.isotonic: bool = False

Targeting.iterate: Literal['last', 'best'] = 'last'

Targeting.max_iter: int = 20

Targeting.nuisance_bound: float = 0.01

Targeting.q_bounds: tuple[float, float] | None = None

Targeting.step_bound: float | None = None

Targeting.step_search: bool = True

Targeting.step_size: float = 0.001

Targeting.stopping: Literal['relative', 'scaled_var', 'sample_size'] = 'relative'

Targeting.submodel_alpha: float = 0.9995

Targeting.target_weights: bool = False

Targeting.tol: float = 1e-10