cleverly.assessment.SensitivityFacade#

class cleverly.assessment.SensitivityFacade(result: Any)[source]#

Access sensitivity analyses supported by a fitted causal result.

Parameters:
resultTMLEResult or LongitudinalResult

Fitted point-treatment or longitudinal result.

See also

DiagnosticsFacade

The checks that ask whether the fit itself is sound.

cleverly.AssessmentCapability

One row of capabilities.

cleverly.sensitivity.evalue.evalue

The same analysis as a free function.

Notes

Access this facade through result.sensitivity. Methods use the fitted estimate and nuisance artifacts as their first input. Their remaining arguments match the corresponding functions in cleverly.sensitivity. Inspect capabilities to distinguish an unsupported analysis from one that needs additional arguments or expensive work.

Examples

>>> from sklearn.linear_model import LinearRegression, LogisticRegression
>>> from cleverly import ATE, CausalStudy, PointTreatment
>>> from cleverly.datasets import make_linear_ate
>>> frame, _ = make_linear_ate(n=200, seed=0)
>>> study = CausalStudy(
...     frame,
...     design=PointTreatment(
...         outcome="Y", treatment="A", adjustment=("W1", "W2", "W3", "W4")
...     ),
... )
>>> result = study.identify(ATE()).estimate(
...     outcome_learner=LinearRegression(),
...     treatment_learner=LogisticRegression(max_iter=1000),
...     cross_fit=False,
...     random_state=0,
... )
>>> capability = result.sensitivity.capability("omitted_confounding")
>>> capability.available, capability.cost
(True, 'cheap')

Methods#

SensitivityFacade.benchmark(*args: Any, **kwargs: Any) → Any[source]#

Benchmark confounding strength against observed covariates.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.benchmark(), without its first argument, which this facade supplies from the fitted result.

Returns:
BenchmarkResult

Confounding strength expressed in units of the named observed covariates.

See also

cleverly.sensitivity.benchmark

The same benchmark as a free function.

Notes

A name the fit does not adjust for raises DataError before any refusal, as the free function raises it.

SensitivityFacade.contour(*args: Any, **kwargs: Any) → Any[source]#

Evaluate bias bounds over a confounding-strength grid.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.contour_data(), without its first argument, which this facade supplies from the fitted result.

Returns:
dataframe

Bias bounds over the requested grid of confounding strengths.

See also

cleverly.sensitivity.contour_data

The same grid as a free function.

SensitivityFacade.elements(*args: Any, **kwargs: Any) → Any[source]#

Return the variance elements used by omitted-variable bounds.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.sensitivity_elements(), without its first argument, which this facade supplies from the fitted result.

Returns:
SensitivityElements

The variance elements the omitted-variable bounds are built from.

See also

cleverly.sensitivity.sensitivity_elements

The same elements as a free function.

SensitivityFacade.evalue(*args: Any, **kwargs: Any) → Any[source]#

Return an E-value on the risk-ratio scale.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.evalue(), without its first argument, which this facade supplies from the fitted result.

Returns:
EValue

The minimum risk-ratio association that would explain the effect away.

See also

cleverly.sensitivity.evalue

The same E-value as a free function.

SensitivityFacade.missingness(*args: Any, **kwargs: Any) → Any[source]#

Vary unobserved-outcome odds under a missingness tilt.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.missingness_tilt(), without its first argument, which this facade supplies from the fitted result.

Returns:
dataframe

One row per tilt value and estimand.

See also

cleverly.sensitivity.missingness_tilt

The same tilt as a free function.

SensitivityFacade.omitted_confounding(*args: Any, **kwargs: Any) → Any[source]#

Bound omitted-confounder bias for a reported estimand.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.omitted_variable_bounds(), without its first argument, which this facade supplies from the fitted result.

Returns:
SensitivityBounds

Bias bounds for each requested estimand.

See also

cleverly.sensitivity.omitted_variable_bounds

The same bound as a free function.

Examples

>>> from sklearn.linear_model import LinearRegression, LogisticRegression
>>> from cleverly import ATE, CausalStudy, PointTreatment
>>> from cleverly.datasets import make_linear_ate
>>> frame, _ = make_linear_ate(n=80, seed=1)
>>> study = CausalStudy(
...     frame,
...     design=PointTreatment(
...         outcome="Y", treatment="A", adjustment=("W1", "W2", "W3", "W4")
...     ),
... )
>>> result = study.identify(ATE()).estimate(
...     outcome_learner=LinearRegression(),
...     treatment_learner=LogisticRegression(max_iter=1000),
...     cross_fit=False,
...     random_state=0,
... )
>>> bounds = result.sensitivity.omitted_confounding(cf_y=0.05, cf_d=0.05)
>>> bounds.lower < result["ate"].psi < bounds.upper
True
SensitivityFacade.robustness_value(*args: Any, **kwargs: Any) → Any[source]#

Return the confounding strength needed to cross the null.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.robustness_value(), without its first argument, which this facade supplies from the fitted result.

Returns:
dict of str to float

Null-crossing strengths for the estimate and confidence limit, plus the maximum-bias scale.

See also

cleverly.sensitivity.robustness_value

The same value as a free function.

SensitivityFacade.run_all(*, include_refits: bool = False, include_retargets: bool = False, arguments: Mapping[str, Mapping[str, Any]] | None = None, random_state: int | None = None) → DiagnosticReport[source]#

Run available sensitivity analyses that need no new arguments.

Parameters:
include_refitsbool

Include operations that refit nuisance models.

include_retargetsbool

Include moderate retargets; cheap E-value retargets run by default.

argumentsmapping or None

Per-operation keyword arguments.

random_stateint or None

Common seed for stochastic refit operations.

Returns:
DiagnosticReport

One item for every declared sensitivity operation.

SensitivityFacade.simulated_confounding(*args: Any, **kwargs: Any) → Any[source]#

Refit across a simulated common-cause strength grid.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.simulated_confounding(), without its first argument, which this facade supplies from the fitted result.

Returns:
SimulatedConfoundingResult

Qualitative estimate movements on the scale of the surface, and retained cell failures.

See also

cleverly.sensitivity.simulated_confounding

The same surface as a free function.

SensitivityFacade.tipping_gamma(*args: Any, **kwargs: Any) → Any[source]#

Find the missingness tilt at which the estimate crosses its null.

Parameters:
*args, **kwargs

Forwarded to cleverly.sensitivity.tipping_gamma(), without its first argument, which this facade supplies from the fitted result.

Returns:
float or None

The tilt at which the requested estimand reaches its null.

See also

cleverly.sensitivity.tipping_gamma

The same search as a free function.

Attributes#