tf-inference 0.1.0__py3-none-any.whl

tf_inference/__init__.py

@@ -0,0 +1,55 @@
+"""Numerically constructed tF inference for single-instrument IV models."""
+
+from functools import lru_cache
+
+from .calibration import Calibration, CalibrationDiagnostics, calibrate
+from .curve import ConvergenceError, Curve, construct_curve, validate_alpha
+from .probability import RejectionProbability, rejection_probability
+from .tables import available_alphas, export_table, load_table
+
+__all__ = [
+    "Calibration",
+    "CalibrationDiagnostics",
+    "ConvergenceError",
+    "Curve",
+    "RejectionProbability",
+    "available_alphas",
+    "calibrate",
+    "confidence_interval",
+    "construct_curve",
+    "critical_value",
+    "export_table",
+    "load_table",
+    "rejection_probability",
+]
+
+
+@lru_cache(maxsize=32)
+def _computed_calibration(alpha):
+    return calibrate(alpha)
+
+
+def _calibration(alpha, method):
+    if method == "table":
+        return load_table(alpha)
+    if method == "compute":
+        return _computed_calibration(alpha)
+    raise ValueError("method must be 'table' or 'compute'.")
+
+
+def critical_value(f_stat, alpha=0.05, *, method="table"):
+    """Return tF critical values for absolute t using a table or numerical construction.
+
+    The default requires an exact matching bundled alpha. Explicitly select
+    ``method="compute"`` for cached numerical calibration at another level.
+    No interpolation across significance levels is performed.
+    For custom numerical tolerances use ``calibrate`` and inspect its diagnostics.
+    """
+    return _calibration(validate_alpha(alpha), method).critical_value(f_stat)
+
+
+def confidence_interval(coefficient, se, f_stat, alpha=0.05, *, method="table"):
+    """Return tF confidence intervals with lower/upper bounds on the last axis."""
+    return _calibration(validate_alpha(alpha), method).confidence_interval(
+        coefficient, se, f_stat
+    )

tf_inference/calibration.py

@@ -0,0 +1,228 @@
+"""Numerical plateau selection, audit records, and inference."""
+
+from dataclasses import asdict, dataclass
+from math import isfinite
+from typing import cast
+
+import numpy as np
+from numpy.typing import ArrayLike
+from scipy.optimize import OptimizeResult, brentq, minimize, minimize_scalar
+
+from .curve import ConvergenceError, Curve, construct_curve
+from .probability import rejection_probability
+
+
+@dataclass(frozen=True)
+class CalibrationDiagnostics:
+    """Finite numerical size search; this is not a uniform mathematical bound."""
+
+    alpha: float
+    plateau_f: float
+    plateau_critical: float
+    property_c_endpoint: float
+    maximum_rejection: float
+    worst_strength: float
+    worst_rho: float
+    integration_error: float
+    size_tolerance: float
+    strength_limit: float
+    evaluations: int
+    adjustments: int
+    correlations: tuple[float, ...]
+    strengths: tuple[float, ...]
+
+    def to_dict(self):
+        """Return serializable diagnostics."""
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class Calibration:
+    """A tF curve and a plateau checked by a finite numerical size search."""
+
+    curve: Curve
+    plateau_f: float
+    diagnostics: CalibrationDiagnostics
+
+    @property
+    def alpha(self):
+        """Two-sided significance level."""
+        return self.curve.alpha
+
+    @property
+    def boundary(self):
+        """F at or below which the confidence interval is unbounded."""
+        return self.curve.boundary
+
+    @property
+    def plateau(self):
+        """Critical value for absolute t on the plateau."""
+        return float(self.curve.critical(self.plateau_f))
+
+    def critical_value(self, f_stat: ArrayLike):
+        """Evaluate critical values, with infinity at and below the boundary."""
+        if np.iscomplexobj(f_stat):
+            raise ValueError("F must be real.")
+        values = np.asarray(f_stat, dtype=float)
+        if values.ndim == 0:
+            value = float(values)
+            if not isfinite(value) or value < 0:
+                raise ValueError("F must be finite and nonnegative.")
+            return self.curve.critical(min(value, self.plateau_f))
+        if np.any(~np.isfinite(values)) or np.any(values < 0):
+            raise ValueError("F must be finite and nonnegative.")
+        return self.curve.critical(np.minimum(values, self.plateau_f))
+
+    def confidence_interval(
+        self, coefficient: ArrayLike, se: ArrayLike, f_stat: ArrayLike
+    ):
+        """Construct intervals; broadcast inputs and put lower/upper bounds last."""
+        if any(np.iscomplexobj(value) for value in (coefficient, se, f_stat)):
+            raise ValueError("coefficient, se and F must be real.")
+        coefficient, se, f_stat = np.broadcast_arrays(coefficient, se, f_stat)
+        if (
+            np.any(~np.isfinite(coefficient))
+            or np.any(~np.isfinite(se))
+            or np.any(se <= 0)
+        ):
+            raise ValueError("coefficient must be finite and se finite and positive.")
+        width = self.critical_value(f_stat) * se
+        return np.stack([coefficient - width, coefficient + width], axis=-1)
+
+
+def calibrate(
+    alpha: float = 0.05,
+    *,
+    epsilon: float = 1e-4,
+    seeds: int = 256,
+    size_tolerance: float = 2e-7,
+    strength_limit: float = 80.0,
+    correlations: ArrayLike | None = None,
+    strengths: ArrayLike | None = None,
+    optimize: bool = True,
+) -> Calibration:
+    """Construct and numerically calibrate a tF curve at a requested alpha.
+
+    The initial plateau satisfies Property (C) and is at least the normal
+    critical value. A grid and local searches check rejection probabilities;
+    violations move the plateau earlier on the decreasing branch. Diagnostics
+    report the finite search domain and numerical tolerances. Neither a finite
+    grid nor local optimization certifies the supremum over all nuisance values.
+    """
+    if any(
+        value is not None and np.iscomplexobj(value)
+        for value in (size_tolerance, strength_limit, correlations, strengths)
+    ):
+        raise ValueError("Calibration settings must be real.")
+    if not np.isfinite(size_tolerance) or not 1e-9 <= size_tolerance <= 1e-3:
+        raise ValueError("size_tolerance must be between 1e-9 and 1e-3.")
+    if not np.isfinite(strength_limit) or strength_limit < 20:
+        raise ValueError("strength_limit must be finite and at least 20.")
+    curve = construct_curve(alpha, epsilon=epsilon, seeds=seeds)
+    stop = curve.minimum_plateau_f
+    if correlations is None:
+        correlations = [0, 0.25, 0.5, 0.75, 0.9, 0.95, 0.99, 0.995, 0.999, 0.9999, 1]
+    rho_grid = np.unique(np.r_[correlations, 0.0, 1.0]).astype(float)
+    if np.any(~np.isfinite(rho_grid)) or np.any((rho_grid < 0) | (rho_grid > 1)):
+        raise ValueError("correlations must be finite and lie in [0, 1].")
+    if strengths is None:
+        strengths = np.r_[0, 0.05, 0.1, 0.25, 0.5, np.geomspace(1, strength_limit, 32)]
+    m_grid = np.unique(np.r_[strengths, 0.0, strength_limit]).astype(float)
+    if np.any(~np.isfinite(m_grid)) or np.any((m_grid < 0) | (m_grid > strength_limit)):
+        raise ValueError("strengths must be finite and lie in [0, strength_limit].")
+    integration_tol = min(1e-9, size_tolerance / 50)
+    evaluations = 0
+    max_error = 0.0
+
+    def evaluate(m, rho, candidate):
+        nonlocal evaluations, max_error
+        result = rejection_probability(
+            curve, m, rho, plateau_f=candidate, atol=integration_tol
+        )
+        evaluations += 1
+        max_error = max(max_error, result.error)
+        if result.error > size_tolerance / 5:
+            raise ConvergenceError(
+                "Quadrature error is too large for size calibration."
+            )
+        return result.probability
+
+    def search(candidate):
+        records = [
+            (evaluate(m, rho, candidate), float(m), float(rho))
+            for m in m_grid
+            for rho in rho_grid
+        ]
+        if optimize:
+            # Refine each resolved peak along the singular boundary, including
+            # the post-plateau hump which a coarse strength grid can miss.
+            singular = sorted((p, m) for p, m, r in records if r == 1)
+            for _, m in singular[-3:]:
+                lo, hi = max(0.001, m / 1.5), min(strength_limit, max(m + 1, m * 1.5))
+                result = cast(
+                    "OptimizeResult",
+                    minimize_scalar(
+                        lambda x: -evaluate(x, 1.0, candidate),
+                        bounds=(lo, hi),
+                        method="bounded",
+                        options={"xatol": 1e-5},
+                    ),
+                )
+                if result.success:
+                    records.append((-float(result.fun), float(result.x), 1.0))
+            # Also search the interior; rho=1 is not assumed to be worst-case.
+            interior = sorted(record for record in records if record[2] < 0.999)
+            for _, m, rho in interior[-2:]:
+                result = minimize(
+                    lambda x: -evaluate(float(x[0]), float(x[1]), candidate),
+                    [m, rho],
+                    method="Nelder-Mead",
+                    bounds=[(0.0, strength_limit), (0.0, 0.99999)],
+                    options={
+                        "maxiter": 150,
+                        "xatol": 1e-4,
+                        "fatol": size_tolerance / 10,
+                    },
+                )
+                if not result.success:
+                    raise ConvergenceError("The interior size search did not converge.")
+                records.append(
+                    (-float(result.fun), float(result.x[0]), float(result.x[1]))
+                )
+        return max(records)
+
+    for adjustments in range(12):
+        worst, m, rho = search(stop)
+        if worst <= curve.alpha + size_tolerance:
+            diagnostics = CalibrationDiagnostics(
+                curve.alpha,
+                stop,
+                float(curve.critical(stop)),
+                curve.property_c_endpoint,
+                worst,
+                m,
+                rho,
+                max_error,
+                size_tolerance,
+                strength_limit,
+                evaluations,
+                adjustments,
+                tuple(rho_grid),
+                tuple(m_grid),
+            )
+            return Calibration(curve, stop, diagnostics)
+        target = curve.alpha - integration_tol * 10
+        lower = curve.boundary + epsilon
+        if evaluate(m, rho, lower) > target:
+            raise ConvergenceError("No admissible plateau resolves the size violation.")
+        stop = cast(
+            "float",
+            brentq(
+                lambda value, m=m, rho=rho, target=target: (
+                    evaluate(m, rho, value) - target
+                ),
+                lower,
+                stop,
+            ),
+        )
+    raise ConvergenceError("Plateau calibration exceeded 12 adjustments.")

tf_inference/cli.py

@@ -0,0 +1,57 @@
+"""Command-line evaluation and reproducible table generation."""
+
+import argparse
+import json
+
+import numpy as np
+
+from . import calibrate, critical_value, export_table
+
+
+def main(argv=None):
+    """Evaluate critical values or generate portable calibration files."""
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    evaluate = commands.add_parser("critical", help="Evaluate tF critical values")
+    evaluate.add_argument("F", nargs="+", type=float)
+    evaluate.add_argument("--alpha", type=float, default=0.05)
+    evaluate.add_argument("--method", choices=["table", "compute"], default="table")
+    generate = commands.add_parser(
+        "generate", help="Construct and export numerical tables"
+    )
+    generate.add_argument("--alpha", nargs="+", type=float, required=True)
+    generate.add_argument("--output", required=True)
+    generate.add_argument("--points", type=int, default=16385)
+    generate.add_argument("--csv", action="store_true", help="Also export gzip CSV")
+    generate.add_argument("--epsilon", type=float, default=1e-4)
+    generate.add_argument("--seeds", type=int, default=256)
+    generate.add_argument("--size-tolerance", type=float, default=2e-7)
+    generate.add_argument("--strength-limit", type=float, default=80)
+    args = parser.parse_args(argv)
+    if args.command == "critical":
+        try:
+            values = np.atleast_1d(
+                critical_value(args.F, args.alpha, method=args.method)
+            )
+        except ValueError as error:
+            parser.error(str(error))
+        print("F,critical_value")
+        for f_stat, value in zip(args.F, values, strict=True):
+            print(f"{f_stat:.17g},{value:.17g}")
+    else:
+        for alpha in args.alpha:
+            calibration = calibrate(
+                alpha,
+                epsilon=args.epsilon,
+                seeds=args.seeds,
+                size_tolerance=args.size_tolerance,
+                strength_limit=args.strength_limit,
+            )
+            metadata = export_table(
+                calibration, args.output, points=args.points, include_csv=args.csv
+            )
+            print(json.dumps(metadata), flush=True)
+
+
+if __name__ == "__main__":
+    main()

tf_inference/curve.py

@@ -0,0 +1,195 @@
+"""The Appendix B.3 inverse map and the Property (C) endpoint."""
+
+from dataclasses import dataclass
+from math import isfinite
+from typing import cast
+
+import numpy as np
+from numpy.typing import ArrayLike
+from scipy.interpolate import PchipInterpolator
+from scipy.optimize import OptimizeResult, brentq, minimize_scalar
+from scipy.special import ndtr, ndtri
+
+
+class ConvergenceError(RuntimeError):
+    """A numerical construction or calibration did not converge."""
+
+
+def validate_alpha(alpha: float) -> float:
+    """Validate the numerical implementation's significance-level domain."""
+    if np.iscomplexobj(alpha):
+        raise ValueError("alpha must be real.")
+    alpha = float(alpha)
+    if not np.isfinite(alpha) or not 0.0001 <= alpha <= 0.25:
+        raise ValueError("alpha must be finite and between 0.0001 and 0.25.")
+    return alpha
+
+
+def inverse_map(f_stat: ArrayLike, critical: ArrayLike, alpha: float):
+    """Extend the decreasing branch using Appendix B.3, step 2."""
+    f_stat, critical = np.broadcast_arrays(f_stat, critical)
+    strength = f_stat / (critical - np.sqrt(f_stat))
+    # Survival probabilities avoid subtracting a small tail from one.
+    normal_quantile = -ndtri(alpha - ndtr(-np.sqrt(f_stat) - strength))
+    root_f = strength + normal_quantile
+    return root_f**2, root_f * normal_quantile / strength
+
+
+@dataclass(frozen=True)
+class Curve:
+    """A numerically constructed decreasing branch, before plateau calibration.
+
+    ``critical`` returns the threshold for absolute t, not for t squared.
+    The interpolated quantity is (F - boundary) * critical(F)**2.
+    """
+
+    alpha: float
+    boundary: float
+    f: np.ndarray
+    regularized: np.ndarray
+    epsilon: float
+    seeds: int
+    property_c_endpoint: float
+    minimum_plateau_f: float
+    _spline: PchipInterpolator
+
+    def regularized_squared(self, f_stat: ArrayLike):
+        """Evaluate the finite regularized squared critical value.
+
+        Args:
+            f_stat: Real F values between the boundary and the branch endpoint.
+
+        Returns:
+            Values of (F - boundary) times the squared critical value.
+
+        Raises:
+            ValueError: If F is non-real, nonfinite, or outside the branch.
+        """
+        if np.iscomplexobj(f_stat):
+            raise ValueError("F must be real.")
+        values = np.asarray(f_stat, dtype=float)
+        if (
+            np.any(~np.isfinite(values))
+            or np.any(values < self.boundary)
+            or np.any(values > self.f[-1])
+        ):
+            raise ValueError("F lies outside the constructed decreasing branch.")
+        return self._spline(values)
+
+    def critical(self, f_stat: ArrayLike):
+        """Evaluate the decreasing branch within its constructed domain."""
+        if np.iscomplexobj(f_stat):
+            raise ValueError("F must be real.")
+        values = np.asarray(f_stat, dtype=float)
+        if values.ndim == 0:
+            value = float(values)
+            if not isfinite(value) or value < 0:
+                raise ValueError("F must be finite and nonnegative.")
+            if value > self.f[-1]:
+                raise ValueError("F lies outside the constructed decreasing branch.")
+            if value <= self.boundary:
+                return float("inf")
+            return float(np.sqrt(self._spline(value) / (value - self.boundary)))
+        if np.any(~np.isfinite(values)) or np.any(values < 0):
+            raise ValueError("F must be finite and nonnegative.")
+        if np.any(values > self.f[-1]):
+            raise ValueError("F lies outside the constructed decreasing branch.")
+        result = np.full(values.shape, np.inf)
+        finite = values > self.boundary
+        result[finite] = np.sqrt(
+            self._spline(values[finite]) / (values[finite] - self.boundary)
+        )
+        return float(result) if result.ndim == 0 else result
+
+
+def construct_curve(
+    alpha: float = 0.05, *, epsilon: float = 1e-4, seeds: int = 256
+) -> Curve:
+    """Construct Appendix B.3's decreasing branch and its admissible endpoint.
+
+    Args:
+        alpha: Two-sided significance level, between 0.0001 and 0.25.
+        epsilon: Initialization distance from the chi-square boundary.
+        seeds: Number of starting points across one inverse-map interval.
+
+    Returns:
+        Candidate decreasing curve and its admissible endpoint. Use ``calibrate``
+        to check a plateau before using the curve for inference.
+
+    Raises:
+        ValueError: If the significance level or construction settings are invalid.
+        ConvergenceError: If the recurrence or tangency calculation fails.
+    """
+    alpha = validate_alpha(alpha)
+    if np.iscomplexobj(epsilon):
+        raise ValueError("epsilon must be real.")
+    if not np.isfinite(epsilon) or not 1e-6 <= epsilon <= 1e-3:
+        raise ValueError("epsilon must be between 1e-6 and 1e-3.")
+    if isinstance(seeds, bool) or not isinstance(seeds, int) or seeds < 32:
+        raise ValueError("seeds must be an integer of at least 32.")
+    q = float(ndtri(alpha / 2) ** 2)
+    b = 3 * q - q**2 / 2 + q**3 / 6
+    start = q + epsilon
+    end = float(inverse_map(start, np.sqrt(q**3 / (start - q) - b), alpha)[0])
+    f = np.linspace(start, end, seeds, endpoint=False)
+    critical = np.sqrt(q**3 / (f - q) - b)
+    f_parts, c_parts = [], []
+    for _ in range(10000):
+        f_parts.append(f)
+        c_parts.append(critical)
+        valid = (critical > np.sqrt(f)) & (f < 1e5)
+        if not np.any(valid):
+            break
+        next_f, next_c = inverse_map(f[valid], critical[valid], alpha)
+        if np.any(~np.isfinite(next_f)) or np.any(next_f <= f[valid]):
+            raise ConvergenceError("The inverse map failed to extend its domain.")
+        f, critical = next_f, next_c
+    else:
+        raise ConvergenceError("The inverse map exceeded 10000 iterations.")
+    f, critical = np.concatenate(f_parts), np.concatenate(c_parts)
+    order = np.argsort(f)
+    f, critical = f[order], critical[order]
+    unique = np.r_[True, np.diff(f) > 0]
+    f, critical = f[unique], critical[unique]
+    if np.any(np.diff(critical) > 1e-8 * critical[:-1]):
+        raise ConvergenceError(
+            "The constructed critical-value branch is not decreasing."
+        )
+    regularized = np.r_[q**3, (f - q) * critical**2]
+    f = np.r_[q, f]
+    spline = PchipInterpolator(f, regularized, extrapolate=False)
+
+    def cv(value):
+        return np.sqrt(spline(value) / (value - q))
+
+    # An interior rejection interval appears when strength exceeds min_F
+    # F / (sqrt(F) - critical(F)). This is the tangency in Property (C).
+    lower = f[1:][f[1:] > critical**2][0]
+    upper = min(1e4, f[-1])
+    contact = cast(
+        "OptimizeResult",
+        minimize_scalar(
+            lambda value: value / (np.sqrt(value) - cv(value)),
+            bounds=(lower, upper),
+            method="bounded",
+            options={"xatol": 1e-9},
+        ),
+    )
+    if not contact.success:
+        raise ConvergenceError("Could not locate the Property (C) tangency.")
+    endpoint = cast(
+        "float",
+        brentq(
+            lambda value: value / (np.sqrt(value) + cv(value)) - contact.fun,
+            contact.x,
+            upper,
+        ),
+    )
+    plateau_f = endpoint
+    if cv(endpoint) < np.sqrt(q):
+        plateau_f = cast(
+            "float", brentq(lambda value: cv(value) - np.sqrt(q), q + epsilon, endpoint)
+        )
+    f.setflags(write=False)
+    regularized.setflags(write=False)
+    return Curve(alpha, q, f, regularized, epsilon, seeds, endpoint, plateau_f, spline)

tf_inference/data/calibrations.json

@@ -0,0 +1,4 @@
+{
+  "schema_version": 2,
+  "parquet_sha256": "10a3d5ede0ab6e75c0559bb1e4bc8f1df9033ba949f6b0f53518185864d39933"
+}