cleverly 0.1.0__py3-none-any.whl

cleverly/__init__.py

@@ -0,0 +1,162 @@
+"""cleverly: targeted maximum likelihood estimation for Python.
+
+Quickstart
+----------
+>>> from cleverly import ATE, CausalStudy, PointTreatment
+>>> from cleverly.datasets import make_nonlinear_ate
+>>> from sklearn.linear_model import LinearRegression, LogisticRegression
+>>> frame, _ = make_nonlinear_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),
+...     n_folds=2,
+...     random_state=0,
+... )
+>>> sorted(result.estimates)
+['ate']
+
+The estimator takes pandas or polars dataframes interchangeably and returns results
+in whichever backend it was given. Every result carries the fitted artifacts used by
+its cache-only validation and diagnostic operations. Other assessments declare when
+they retarget or refit.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .assessment import (
+    AssessmentCapability,
+    AssessmentStatus,
+    DiagnosticReport,
+    Replayability,
+    ValidationReport,
+)
+from .estimators.serialize import load
+from .exceptions import (
+    CapabilityError,
+    CleverlyError,
+    ConvergenceWarning,
+    DataError,
+    MethodConfigurationError,
+    NotFittedError,
+    PositivityWarning,
+    WeightingWarning,
+)
+from .inference import ParameterEstimate
+from .learners import SuperLearner
+from .methods import (
+    CollaborativeTMLEMethod,
+    CrossFitting,
+    DRTMLEMethod,
+    EstimationMethod,
+    Inference,
+    MethodAvailability,
+    ModelSpec,
+    Runtime,
+    Targeting,
+    TMLEMethod,
+)
+from .provenance import Provenance
+from .study import (
+    ATC,
+    ATE,
+    ATT,
+    BackdoorMeanContrast,
+    CausalResult,
+    CausalStudy,
+    ControlledDirectEffect,
+    CounterfactualMean,
+    Estimand,
+    ExplicitAdjustmentProvider,
+    IdentificationProvider,
+    IdentifiedEffect,
+    IncrementalEffect,
+    IncrementalMean,
+    LongitudinalTreatment,
+    ModifiedTreatmentPolicy,
+    ModifiedTreatmentPolicyEffect,
+    MSMProjection,
+    NaturalCourseMean,
+    OddsRatio,
+    ParameterKey,
+    PointTreatment,
+    PopulationAttributableFraction,
+    PopulationAttributableRisk,
+    RegimeContrast,
+    RegimeMean,
+    RiskRatio,
+)
+from .variable_importance import (
+    VariableImportanceEntry,
+    VariableImportanceResult,
+    variable_importance,
+)
+
+__all__ = [
+    "ATC",
+    "ATE",
+    "ATT",
+    "AssessmentCapability",
+    "AssessmentStatus",
+    "BackdoorMeanContrast",
+    "CapabilityError",
+    "CausalResult",
+    "CausalStudy",
+    "CleverlyError",
+    "CollaborativeTMLEMethod",
+    "ControlledDirectEffect",
+    "ConvergenceWarning",
+    "CounterfactualMean",
+    "CrossFitting",
+    "DRTMLEMethod",
+    "DataError",
+    "DiagnosticReport",
+    "Estimand",
+    "EstimationMethod",
+    "ExplicitAdjustmentProvider",
+    "IdentificationProvider",
+    "IdentifiedEffect",
+    "IncrementalEffect",
+    "IncrementalMean",
+    "Inference",
+    "LongitudinalTreatment",
+    "MSMProjection",
+    "MethodAvailability",
+    "MethodConfigurationError",
+    "ModelSpec",
+    "ModifiedTreatmentPolicy",
+    "ModifiedTreatmentPolicyEffect",
+    "NaturalCourseMean",
+    "NotFittedError",
+    "OddsRatio",
+    "ParameterEstimate",
+    "ParameterKey",
+    "PointTreatment",
+    "PopulationAttributableFraction",
+    "PopulationAttributableRisk",
+    "PositivityWarning",
+    "Provenance",
+    "RegimeContrast",
+    "RegimeMean",
+    "Replayability",
+    "RiskRatio",
+    "Runtime",
+    "SuperLearner",
+    "TMLEMethod",
+    "Targeting",
+    "ValidationReport",
+    "VariableImportanceEntry",
+    "VariableImportanceResult",
+    "WeightingWarning",
+    "__version__",
+    "load",
+    "variable_importance",
+]

cleverly/_typing.py

@@ -0,0 +1,121 @@
+"""Shared type aliases.
+
+Kept in a private module so the public namespace stays focused on estimators.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = [
+    "Backend",
+    "BoolArray",
+    "CumulativeGBounds",
+    "EstimandName",
+    "Family",
+    "FloatArray",
+    "FluctuationKind",
+    "FoldStrata",
+    "GBounds",
+    "IntArray",
+    "Learner",
+    "ParameterAxis",
+    "TargetingMethod",
+    "TargetingScheme",
+]
+
+FloatArray = NDArray[np.float64]
+IntArray = NDArray[np.int64]
+BoolArray = NDArray[np.bool_]
+
+#: Anything implementing the scikit-learn ``fit``/``predict`` (or
+#: ``predict_proba``) protocol, including :class:`cleverly.SuperLearner`,
+#: :class:`sklearn.pipeline.Pipeline`, and grid-search wrappers.  Typed as
+#: ``Any`` deliberately: scikit-learn estimators are structurally, not
+#: nominally, typed and requiring a Protocol here would reject valid learners.
+Learner = Any
+
+Backend = Literal["pandas", "polars"]
+Family = Literal["gaussian", "binomial", "auto"]
+FluctuationKind = Literal["logistic", "linear"]
+TargetingMethod = Literal["iterative", "one_step"]
+TargetingScheme = Literal["pooled", "fold"]
+
+#: What the outer cross-fitting folds are balanced on.  ``"treatment"`` is the
+#: long-standing behaviour and the default; ``"treatment+outcome"`` crosses in the
+#: outcome so that a rare event cannot leave a fold with none of them.
+FoldStrata = Literal["treatment", "treatment+outcome"]
+#: Every estimand *name* :class:`~cleverly.estimators.TMLE`'s ``estimands=`` accepts, which is
+#: every key of the target registry.  Which of them a *particular* fit can report depends on
+#: its outcome family, its arm count and which parameter axis it declared, and that is
+#: checked at runtime by :func:`~cleverly.targets.resolve_estimands` against the registry
+#: itself.  This alias is the static half of the same statement and cannot be derived from
+#: the registry: a ``Literal`` has to be written out, and importing ``cleverly.targets`` here
+#: would invert the dependency of the type aliases on the package.
+#:
+#: So it is a hand-maintained copy, and the way a hand-maintained copy stays honest is a gate
+#: rather than care -- ``tests/unit/test_registry.py`` compares its members with ``TARGETS``
+#: in both directions.  It had already drifted once without one: ``ey``, ``ey_obs``, ``par``
+#: and ``paf`` were reportable and absent from here, as was every non-arm axis, so annotating
+#: a correct call was a type error.
+#:
+#: Named ``EstimandName`` rather than ``Estimand`` because :class:`cleverly.Estimand` is a
+#: different thing entirely -- the :class:`~typing.Protocol` in :mod:`cleverly.study` that a
+#: question like :class:`~cleverly.ATE` satisfies.  The two shared a name while meaning a
+#: string and an object, and the public export won, so this one could not be reached under
+#: its own name from outside the package.
+#:
+#: It covers the *built-in* registry only.  A target registered at runtime -- see
+#: ``tests/unit/test_registry.py``'s ``TestRegistration`` -- is a name no ``Literal`` written
+#: here can know, so passing one is a legitimate ``cast``.  That is a reason to keep this
+#: narrow rather than to widen it to ``str``: the annotation exists to catch a misspelt
+#: built-in name, and the registry still validates every name at runtime either way.
+EstimandName = Literal[
+    "ate",
+    "att",
+    "atc",
+    "ey",
+    "ey1",
+    "ey0",
+    "ey_obs",
+    "par",
+    "paf",
+    "rr",
+    "or",
+    "ey_regime",
+    "ate_regime",
+    "ey_ipsi",
+    "ate_ipsi",
+    "ey_shift",
+    "ate_shift",
+    "msm",
+]
+
+#: What a fit's parameters are indexed *by*: a treatment arm, a declared regime, a
+#: declared shift, a declared tilt of the mechanism, or a coefficient of a declared
+#: working model.  The five partition the target registry -- see
+#: :attr:`cleverly.Target.parameter_axis` for why they are exclusive rather than
+#: cumulative.
+#:
+#: The first four also declare what "counterfactual" means for the fit.  ``"msm"`` does
+#: not: its counterfactuals are still the arms, and what moves is the *summary* the fit
+#: reports of them.  It is an axis all the same, because a summary's coefficients are not
+#: indexed by anything the other four name.
+#:
+#: ``"ipsi"`` is the one whose intervention is a functional of the observed-data law: its
+#: ``q_delta`` is built out of the estimated mechanism, so it carries an extra influence
+#: curve term and a second score equation.  That is why it is not a kind of ``"regime"``.
+ParameterAxis = Literal["arm", "regime", "shift", "ipsi", "msm"]
+
+#: Propensity-score truncation: ``"auto"`` for the sample-size dependent
+#: default, a single float ``lo`` meaning ``[lo, 1 - lo]``, or an explicit pair.
+GBounds = Literal["auto"] | float | tuple[float, float]
+
+#: Bounds on an estimated cumulative longitudinal treatment-and-censoring
+#: probability.  There is deliberately no ``"auto"`` member: cleverly has no
+#: data-adaptive or depth-adaptive rule for choosing this bound.  LTMLE's package
+#: default is an explicit fixed pair, recorded in :mod:`cleverly.utils.bounds`.
+CumulativeGBounds = float | tuple[float, float]

cleverly/_version.py

@@ -0,0 +1,5 @@
+"""Single source of truth for the package version."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"