multivariate-probit 0.3.2__tar.gz → 0.3.3__tar.gz

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/CITATION.cff

@@ -6,8 +6,8 @@ authors:
   - family-names: Shipman
     given-names: Mark
     orcid: "https://orcid.org/0009-0008-7193-1263"
-version: 0.3.0
-date-released: 2026-10-06
+version: 0.3.3
+date-released: 2026-10-29
 license: MIT
 repository-code: "https://github.com/sign-of-fourier/multivariate-probit"
 url: "https://quantecarlo.com/multivariate-probit"

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: multivariate-probit
-Version: 0.3.2
+Version: 0.3.3
 Summary: Joint probabilities for correlated binary outcomes: P(any), P(all), patterns and conditionals that agree. Any classifier per outcome; scikit-learn-style API.
 Project-URL: Homepage, https://quantecarlo.com/multivariate-probit
 Project-URL: Source, https://github.com/sign-of-fourier/multivariate-probit

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/docs/api.md

@@ -35,10 +35,10 @@ MultivariateProbit(
 | `optimizer` | `"Nelder-Mead"` | Passed to `scipy.optimize.minimize` for `dependence="joint"`. Derivative-free by design. |
 | `project_correlation` | `True` | Project a pairwise estimate onto the nearest positive-definite correlation matrix. No effect when `dependence="joint"`. |
 | `random_state` | `None` | Controls the cross-fitting split and `sample`. |
-| `evaluator` | `"quadrature"` | Backend for the orthant probabilities behind `dependence="joint"` and every joint query: `"quadrature"`, `"scipy"` or `"orthant"`. See [Evaluators](#evaluators). |
+| `evaluator` | `"quadrature"` | Backend for the orthant probabilities behind `dependence="joint"` and every joint query: `"quadrature"`, `"scipy"`, `"orthant"` or `"ghk"`. See [Evaluators](#evaluators). |
 | `resolution` | `"high"` | Passed to `evaluator="orthant"`; ignored otherwise. `"high"`, `"highest"` (most accurate, about 2–3× the time of `"high"`: median error under 0.00005 on an equicorrelated Σ against up to 0.0001 at `"high"`, and 0.0001–0.0031 on a near-singular Σ against 0.0006–0.0061; see [benchmarks.md](benchmarks.md)), `"smooth"` (the cost of `"highest"`, continuous in the parameters with no threshold where the method changes, for gradient-based fitting; not uniformly more accurate than `"high"`) or `"low"` (cheapest). |
 | `fitter` | `"ifm"` | `"ifm"`: the local two-stage fit. `"modal"`: full maximum likelihood on a hosted GPU service ([fiml.md](fiml.md)) — `inner="linear"` only, `inner_params` may set only `alpha`; `dependence`, `cv`, `optimizer` and `project_correlation` do not apply. Uploads X, Y and `sample_weight`. An int `random_state` seeds its Sobol draws (default seed 0). |
-| `n_draws` | `512` | Sobol draws per row for `fitter="modal"`; ignored otherwise. |
+| `n_draws` | `512` | Sobol draws per row for `fitter="modal"` and `evaluator="ghk"`; ignored otherwise. Powers of 2 keep the Sobol set balanced. |
 
 > **Reading `calibration_`.** This is the Cox calibration slope, a deliberately
 > simple scale check: a probit of each outcome on its own fitted index. A slope
@@ -78,6 +78,7 @@ queries on a pairwise fit still use the chosen backend.
 | `"quadrature"` | Genz's recursive conditioning with a fixed Gauss-Legendre rule of order `n_quad` (see [implementation.md](implementation.md)). | Deterministic and accurate. Cost grows as `n_quad ** (d - 2)`, so it becomes impractical well before d = 10. |
 | `"scipy"` | `scipy.stats.multivariate_normal.cdf`, one row at a time. | Reaches any d, but is slow per row and randomised: a `dependence="joint"` fit is not exactly reproducible, and its noisy objective can stall the simplex. |
 | `"orthant"` | An optional compiled package bundled as `multivariate_probit.orthant`. Install with `pip install multivariate-probit[orthant]`. | Built for CPython 3.11 and 3.12 on x86-64 Linux only; elsewhere it raises `ImportError`. Without a key it accepts d ≤ 3 at `resolution="low"` only, and raises `ValueError` outside that. A key is read from `$ORTHANT_KEY` or `~/.orthant/key` at import, or passed at any time with `orthant.activate(key)` (returns `"paid"`; a wrong key raises `ValueError`). Each process needs its own key: on Spark, call `activate` inside the function the workers run, or set the variable in the cluster environment; see https://quantecarlo.com/orthant_key. Accuracy and speed against GHK and SciPy: [studies/ghk.md](studies/ghk.md). |
+| `"ghk"` | The GHK simulator: per row, variables ordered by ascending limit, sequential truncated-normal conditioning on `n_draws` scrambled Sobol points shared by all rows (fixed seed). Pure NumPy, no key. | Deterministic and smooth in the parameters, reaches any d, vectorised over rows. Error falls with `n_draws` (roughly 1e-3 max, 1e-5 median at 128-512 draws, d 3-5); cost is linear in `n_draws` and about quadratic in d. |
 
 For test sets too large for one machine, the same evaluator runs as a hosted
 GPU service, `quantecarlo.orthant_cdf`: about a second per million rows at

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "multivariate-probit"
-version = "0.3.2"
+version = "0.3.3"
 description = "Joint probabilities for correlated binary outcomes: P(any), P(all), patterns and conditionals that agree. Any classifier per outcome; scikit-learn-style API."
 readme = "README.md"
 license = { file = "LICENSE" }

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/src/multivariate_probit/__init__.py

@@ -34,7 +34,7 @@ from .linear import ProbitRegressor
 from .model import MultivariateProbit
 from .results import MultivariateProbitProba
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 
 __all__ = [
     "MultivariateProbit",

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/src/multivariate_probit/_mvn.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 from functools import lru_cache
 
 import numpy as np
+from scipy.special import log_ndtr, ndtr, ndtri
 from scipy.stats import norm
 
 __all__ = [
@@ -36,9 +37,11 @@ _EPS = 1e-12
 # The backends that can evaluate a lower-orthant probability. The choice is a
 # speed/accuracy trade-off left to the caller: "quadrature" is the
 # deterministic evaluator below, "scipy" is scipy.stats.multivariate_normal.cdf
-# (randomised quasi-Monte Carlo, one row at a time), and "orthant" is the
-# optional compiled package bundled under ``multivariate_probit.orthant``.
-EVALUATORS = ("quadrature", "scipy", "orthant")
+# (randomised quasi-Monte Carlo, one row at a time), "orthant" is the
+# optional compiled package bundled under ``multivariate_probit.orthant``, and
+# "ghk" is the GHK simulator below with fixed scrambled Sobol draws
+# (deterministic, vectorised, any d).
+EVALUATORS = ("quadrature", "scipy", "orthant", "ghk")
 
 
 @lru_cache(maxsize=8)
@@ -136,6 +139,50 @@ def _scipy_orthant(A, corr_stack):
     return out
 
 
+@lru_cache(maxsize=8)
+def _sobol(dim, n_draws, seed):
+    """Scrambled Sobol points in (0, 1)^dim, cached so repeated calls (an
+    optimizer's objective) reuse the same draws."""
+    from scipy.stats import qmc
+
+    return qmc.Sobol(dim, scramble=True, seed=seed).random(n_draws)
+
+
+def _ghk_orthant(A, corr_stack, n_draws=512, seed=0, max_cells=2_000_000):
+    """GHK (Geweke-Hajivassiliou-Keane) estimate of the lower orthant, row by row.
+
+    Per row the variables are reordered by ascending limit, the correlation is
+    Cholesky-factored, and each draw samples the variables in sequence from
+    their truncated conditionals; the estimate is the mean over draws of the
+    product of the conditional probabilities. The draws are one scrambled
+    Sobol set shared by all rows (seed fixed), so the result is deterministic
+    and smooth in A and the correlations. Error falls with ``n_draws``.
+    """
+    n, d = A.shape
+    if d == 1:
+        return norm.cdf(A[:, 0])
+    S = np.moveaxis(corr_stack, 2, 0)
+    order = np.argsort(A, axis=1)
+    A = np.take_along_axis(A, order, axis=1)
+    S = S[np.arange(n)[:, None, None], order[:, :, None], order[:, None, :]]
+    L = np.linalg.cholesky(S)
+    U = _sobol(d - 1, int(n_draws), seed)
+    out = np.empty(n)
+    step = max(1, max_cells // (n_draws * d))
+    for lo in range(0, n, step):
+        a, Lc = A[lo:lo + step], L[lo:lo + step]
+        logp = np.zeros((len(a), n_draws))
+        z = np.zeros((len(a), n_draws, d - 1))
+        for j in range(d):
+            mu = z[:, :, :j] @ Lc[:, j, :j, None]
+            b = (a[:, j, None] - mu[:, :, 0]) / Lc[:, j, j, None]
+            logp += log_ndtr(b)
+            if j < d - 1:
+                z[:, :, j] = ndtri(np.clip(U[:, j] * ndtr(b), 1e-300, 1.0 - 1e-16))
+        out[lo:lo + step] = np.exp(logp).mean(axis=1)
+    return out
+
+
 def _compiled_orthant(A, corr_stack, resolution):
     try:
         from . import orthant
@@ -153,11 +200,11 @@ def _compiled_orthant(A, corr_stack, resolution):
     return np.asarray(prob, dtype=float)
 
 
-def lower_orthant(A, corr_stack, evaluator="quadrature", n_quad=24, resolution="high"):
+def lower_orthant(A, corr_stack, evaluator="quadrature", n_quad=24, resolution="high", n_draws=512):
     """:func:`mvn_orthant` with a choice of backend.
 
-    ``n_quad`` is used only by ``"quadrature"`` and ``resolution`` only by
-    ``"orthant"``. A backend that cannot run as asked raises; nothing falls
+    ``n_quad`` is used only by ``"quadrature"``, ``resolution`` only by
+    ``"orthant"`` and ``n_draws`` only by ``"ghk"``. A backend that cannot run as asked raises; nothing falls
     back to another backend. Results are clipped to [0, 1].
     """
     A = np.atleast_2d(np.asarray(A, dtype=float))
@@ -167,6 +214,8 @@ def lower_orthant(A, corr_stack, evaluator="quadrature", n_quad=24, resolution="
         prob = _scipy_orthant(A, corr_stack)
     elif evaluator == "orthant":
         prob = _compiled_orthant(A, corr_stack, resolution)
+    elif evaluator == "ghk":
+        prob = _ghk_orthant(A, corr_stack, n_draws=n_draws)
     else:
         raise ValueError(f"evaluator must be one of {EVALUATORS}; got {evaluator!r}")
     return np.clip(prob, 0.0, 1.0)
@@ -192,14 +241,14 @@ def signed_corr_stack(corr, signs):
     return stack
 
 
-def orthant_prob(upper, corr, n_quad=24, evaluator="quadrature", resolution="high"):
+def orthant_prob(upper, corr, n_quad=24, evaluator="quadrature", resolution="high", n_draws=512):
     """P(Z_j <= upper[i, j] for all j) for a single shared correlation matrix."""
     upper = np.atleast_2d(np.asarray(upper, dtype=float))
     stack = signed_corr_stack(corr, np.ones_like(upper))
-    return lower_orthant(upper, stack, evaluator, n_quad=n_quad, resolution=resolution)
+    return lower_orthant(upper, stack, evaluator, n_quad=n_quad, resolution=resolution, n_draws=n_draws)
 
 
-def pattern_prob(eta, Y, corr, n_quad=24, evaluator="quadrature", resolution="high"):
+def pattern_prob(eta, Y, corr, n_quad=24, evaluator="quadrature", resolution="high", n_draws=512):
     """``P(Y = y | x)`` for the multivariate probit, row by row.
 
     With ``s = 2y - 1`` the event ``{Y = y}`` is the orthant
@@ -215,5 +264,10 @@ def pattern_prob(eta, Y, corr, n_quad=24, evaluator="quadrature", resolution="hi
 
     signs = 2.0 * Y - 1.0
     return lower_orthant(
-        signs * eta, signed_corr_stack(corr, signs), evaluator, n_quad=n_quad, resolution=resolution
+        signs * eta,
+        signed_corr_stack(corr, signs),
+        evaluator,
+        n_quad=n_quad,
+        resolution=resolution,
+        n_draws=n_draws,
     )

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/src/multivariate_probit/ifm.py

@@ -114,14 +114,16 @@ def free_from_corr(corr):
 
 
 def joint_log_likelihood(
-    corr, eta, Y, weights=None, n_quad=24, evaluator="quadrature", resolution="high"
+    corr, eta, Y, weights=None, n_quad=24, evaluator="quadrature", resolution="high", n_draws=512
 ):
     """Full d-variate log-likelihood in ``corr``, with the margins held fixed.
 
-    ``evaluator``, ``n_quad`` and ``resolution`` select and tune the orthant
+    ``evaluator``, ``n_quad``, ``resolution`` and ``n_draws`` select and tune the orthant
     backend; see :func:`~multivariate_probit._mvn.lower_orthant`.
     """
-    prob = pattern_prob(eta, Y, corr, n_quad=n_quad, evaluator=evaluator, resolution=resolution)
+    prob = pattern_prob(
+        eta, Y, corr, n_quad=n_quad, evaluator=evaluator, resolution=resolution, n_draws=n_draws
+    )
     prob = np.clip(prob, _LL_EPS, None)
     ll = np.log(prob)
     if weights is None:
@@ -140,6 +142,7 @@ def joint_correlation(
     options=None,
     evaluator="quadrature",
     resolution="high",
+    n_draws=512,
 ):
     """Estimate the latent correlation matrix by full-information ML in ``R``.
 
@@ -181,7 +184,14 @@ def joint_correlation(
         if np.linalg.eigvalsh(corr).min() <= min_eigenvalue:
             return 1e10  # not positive definite -- push the optimizer away
         return -joint_log_likelihood(
-            corr, eta, Y, weights=weights, n_quad=n_quad, evaluator=evaluator, resolution=resolution
+            corr,
+            eta,
+            Y,
+            weights=weights,
+            n_quad=n_quad,
+            evaluator=evaluator,
+            resolution=resolution,
+            n_draws=n_draws,
         )
 
     result = minimize(neg_ll, free_from_corr(start), method=optimizer, options=options)

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/src/multivariate_probit/model.py

@@ -144,7 +144,7 @@ class MultivariateProbit:
         absorbed part of the noise, which attenuates the estimated
         correlations toward zero. ``None`` skips cross-fitting -- reasonable
         for the linear default, risky for anything that can overfit.
-    evaluator : {"quadrature", "scipy", "orthant"}, default="quadrature"
+    evaluator : {"quadrature", "scipy", "orthant", "ghk"}, default="quadrature"
         Backend for the orthant probabilities behind ``dependence="joint"``
         and every joint query. The speed/accuracy trade-off is the caller's:
 
@@ -158,6 +158,10 @@ class MultivariateProbit:
           Linux; ``pip install multivariate-probit[orthant]``). Without a key
           it accepts ``d <= 3`` and ``resolution="low"`` only; outside that,
           and on any platform it was not built for, it raises.
+        - ``"ghk"``: the GHK simulator with ``n_draws`` fixed scrambled Sobol
+          draws per row. Deterministic, vectorised and free (no key), any
+          ``d``; error falls with ``n_draws``. Not available in 0.3.2 and
+          earlier.
 
         Results are clipped to [0, 1]. No backend ever falls back to another.
         ``dependence="pairwise"`` needs only bivariate probabilities, which
@@ -197,7 +201,8 @@ class MultivariateProbit:
         ``sample_weight`` are uploaded; only parameters come back, and every
         prediction afterwards runs locally on ``evaluator``.
     n_draws : int, default=512
-        Sobol draws per row for ``fitter="modal"``; ignored otherwise.
+        Sobol draws per row for ``fitter="modal"`` and ``evaluator="ghk"``;
+        ignored otherwise. Powers of 2 keep the Sobol set balanced.
 
     Attributes
     ----------
@@ -320,6 +325,7 @@ class MultivariateProbit:
                 optimizer=self.optimizer,
                 evaluator=self.evaluator,
                 resolution=self.resolution,
+                n_draws=self.n_draws,
             )
             self.nll_ = None if self.optimize_result_ is None else float(self.optimize_result_.fun)
         elif self.dependence == "pairwise":
@@ -525,6 +531,7 @@ class MultivariateProbit:
             n_quad=self.n_quad,
             evaluator=self.evaluator,
             resolution=self.resolution,
+            n_draws=self.n_draws,
         )
 
     def predict_marginal_proba(self, X):
@@ -556,6 +563,7 @@ class MultivariateProbit:
             n_quad=self.n_quad,
             evaluator=self.evaluator,
             resolution=self.resolution,
+            n_draws=self.n_draws,
         )
 
     def joint_log_proba(self, X, Y):

{multivariate_probit-0.3.2 → multivariate_probit-0.3.3}/src/multivariate_probit/results.py

@@ -21,18 +21,24 @@ class MultivariateProbitProba:
     correlation matrix was estimated in the first place.
     """
 
-    def __init__(self, eta, corr, n_quad=24, evaluator="quadrature", resolution="high"):
+    def __init__(self, eta, corr, n_quad=24, evaluator="quadrature", resolution="high", n_draws=512):
         self.eta = np.atleast_2d(np.asarray(eta, dtype=float))
         self.marginal = norm.cdf(self.eta)
         self.corr = np.asarray(corr, dtype=float)
         self.n_quad = n_quad
         self.evaluator = evaluator
         self.resolution = resolution
+        self.n_draws = n_draws
 
     def _orthant(self, upper, corr):
         stack = signed_corr_stack(corr, np.ones_like(upper))
         return lower_orthant(
-            upper, stack, self.evaluator, n_quad=self.n_quad, resolution=self.resolution
+            upper,
+            stack,
+            self.evaluator,
+            n_quad=self.n_quad,
+            resolution=self.resolution,
+            n_draws=self.n_draws,
         )
 
     # ------------------------------------------------------ array behaviour
@@ -72,6 +78,7 @@ class MultivariateProbitProba:
             n_quad=self.n_quad,
             evaluator=self.evaluator,
             resolution=self.resolution,
+            n_draws=self.n_draws,
         )
 
     def all(self, outcomes=None):
@@ -102,6 +109,7 @@ class MultivariateProbitProba:
             n_quad=self.n_quad,
             evaluator=self.evaluator,
             resolution=self.resolution,
+            n_draws=self.n_draws,
         )
 
     def conditional(self, event, given):