Source code for pyrake

"""Balancing Weights and Raking."""

from __future__ import annotations

import logging
import os
import pathlib
from importlib.resources import files as _resource_files

import cvxium

from pyrake.calibration import (
    KNEE_GRID_POINTS,
    EfficientFrontier,
    EfficientFrontierResults,
    ExternalValidityVarianceFrontier,
    ExternalValidityVarianceFrontierResults,
    FallbackOptimizationResult,
    Huber,
    JointCalibrator,
    KLDivergence,
    Rake,
    SquaredL2,
    external_band,
    knee_external_scale,
    plot_balance,
    plot_balance_2_sample,
    relabel_for_the_chosen_band,
    solve_with_knee_fallback,
)
from pyrake.estimation import (
    AIPWEstimator,
    ATCEstimator,
    ATEEstimator,
    ATTEstimator,
    DoubleSamplingEstimand,
    Estimand,
    IPWEstimator,
    LinearCombinationEstimator,
    MeanEstimator,
    NonRespondentMean,
    PopulationMean,
    RatioEstimator,
    SAIPWEstimator,
    SampleMean,
    SimpleDifferenceEstimator,
    SIPWEstimator,
    TreatmentEffectEstimator,
    TreatmentEffectRatioEstimator,
    WeightingEstimator,
    meta_analysis,
)

__all__ = [
    "KNEE_GRID_POINTS",
    "AIPWEstimator",
    "ATCEstimator",
    "ATEEstimator",
    "ATTEstimator",
    "DoubleSamplingEstimand",
    "EfficientFrontier",
    "EfficientFrontierResults",
    "Estimand",
    "ExternalValidityVarianceFrontier",
    "ExternalValidityVarianceFrontierResults",
    "FallbackOptimizationResult",
    "Huber",
    "IPWEstimator",
    "JointCalibrator",
    "KLDivergence",
    "LinearCombinationEstimator",
    "MeanEstimator",
    "NonRespondentMean",
    "PopulationMean",
    "Rake",
    "RatioEstimator",
    "SAIPWEstimator",
    "SIPWEstimator",
    "SampleMean",
    "SimpleDifferenceEstimator",
    "SquaredL2",
    "TreatmentEffectEstimator",
    "TreatmentEffectRatioEstimator",
    "WeightingEstimator",
    "enable_logging",
    "external_band",
    "knee_external_scale",
    "meta_analysis",
    "plot_balance",
    "plot_balance_2_sample",
    "relabel_for_the_chosen_band",
    "solve_with_knee_fallback",
    "usage",
]


[docs] def usage() -> str: """Return the contents of USAGE.md.""" try: return ( _resource_files("pyrake").joinpath("USAGE.md").read_text(encoding="utf-8") ) except FileNotFoundError: # A source checkout keeps USAGE.md at the repository root; the wheel # force-includes it inside the package. return (pathlib.Path(__file__).parent.parent / "USAGE.md").read_text( encoding="utf-8" )
def __dir__() -> list[str]: return __all__ # A library must not configure logging for the application that imports it, so # the root of PyRake's namespace gets a NullHandler and a quiet level. Callers # opt in with ``enable_logging``. Mirrors what Cvxium does for ``cvxium``. logging.getLogger("pyrake").addHandler(logging.NullHandler()) # Only when nobody has chosen a level yet: `enable_logging` needs the logger's # NAME, not this module, so a caller may configure the namespace before # importing PyRake. An unconditional setLevel would undo that on import and # the log would come back empty with nothing to explain why. if logging.getLogger("pyrake").level == logging.NOTSET: logging.getLogger("pyrake").setLevel(logging.WARNING)
[docs] def enable_logging( path: str | os.PathLike[str] | None = None, level: int = logging.INFO, solver_level: int = logging.WARNING, mode: str = "w", ) -> logging.Handler: """Log PyRake's calibration narration, and Cvxium's solves beneath it. Wires ``pyrake`` and its dependency ``cvxium`` to one shared handler, so the inner solver's output lands underneath the line naming the stage that invoked it rather than in a separate file with separate timestamps. The two namespaces get separate thresholds because they are wanted at different volumes. The default is the narration alone -- one line per calibration, one per fallback stage, each with a timing -- which is a couple of dozen lines and answers "which stage, and where did the time go". Cvxium's own INFO is per-centering-step and runs to thousands of lines on a real problem, so it is off until asked for, and its DEBUG is per-Newton-iteration. Parameters ---------- path : str or PathLike, optional Log file. ``~`` is expanded. None logs to stderr. level : int, optional Threshold for ``pyrake``: the calibration narration. solver_level : int, optional Threshold for ``cvxium``: the solves underneath. Defaults to ``logging.WARNING``, i.e. silent unless something goes wrong. mode : str, optional File mode; ``"w"`` truncates per run. Returns ------- logging.Handler The attached handler. Examples -------- Narration only:: pyrake.enable_logging("~/calibration.log") A slow stage, and you want to see the solver work through it:: pyrake.enable_logging("~/calibration.log", solver_level=logging.INFO) """ # The handler is the floor for both, so it has to sit at the more # permissive of the two or it would filter out what the logger admitted. handler = cvxium.enable_logging( path, level=min(level, solver_level), namespaces=("cvxium", "pyrake"), mode=mode, ) logging.getLogger("pyrake").setLevel(level) logging.getLogger("cvxium").setLevel(solver_level) return handler