multivariate-probit 0.2.3__tar.gz → 0.3.1__tar.gz

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/CITATION.cff

@@ -6,8 +6,8 @@ authors:
   - family-names: Shipman
     given-names: Mark
     orcid: "https://orcid.org/0009-0008-7193-1263"
-version: 0.2.3
-# TODO(Mark): add date-released (YYYY-MM-DD) when 0.2.3 is published.
+version: 0.3.0
+date-released: 2026-10-06
 license: MIT
 repository-code: "https://github.com/sign-of-fourier/multivariate-probit"
 url: "https://quantecarlo.com/multivariate-probit"

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: multivariate-probit
-Version: 0.2.3
+Version: 0.3.1
 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
@@ -101,7 +101,7 @@ Using this on a real problem?
 - Your **multilabel** or **multi-output** model treats labels as independent,
   and you need the **joint probability** of a label combination.
 - You've used R `mvProbit` or Stata `mvprobit` and want **multivariate probit in
-  Python** for prediction at scale (no standard errors yet; see below).
+  Python**, with standard errors from a full-likelihood fit or prediction at scale.
 - You want to **combine several fraud or risk model scores** into one
   probability that "any of these happened."
 - You need **co-occurrence** or **label dependence** expressed as one
@@ -129,6 +129,9 @@ features it is the tetrachoric correlation conditional on x. Fitting is
 two-stage **Inference Functions for Margins** (IFM): each margin is fitted
 alone and cross-fitted, then Σ is estimated by maximum likelihood with the
 margins held fixed ([docs/ifm.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/ifm.md)).
+For linear margins, `fitter="modal"` is the alternative: full maximum
+likelihood, all margins and Σ at once, on a hosted GPU, with standard errors
+([docs/fiml.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/fiml.md)).
 
 ## Why not write it yourself
 
@@ -166,8 +169,11 @@ wrong; each is handled here and documented.
   explicit and readable in `correlation_`, but each margin is as much a black
   box as the classifier inside it. SHAP is the tool for explaining a single
   black-box model; this package does not make one explainable.
-- **No standard errors yet.** Coefficients and Σ are point estimates
-  ([limitations](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/limitations.md)).
+- **Standard errors with `fitter="modal"` only.** The IFM fit gives point
+  estimates
+  ([limitations](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/limitations.md));
+  the full-likelihood fit returns `stderr_` and `cov_params_` for the
+  coefficients and Σ.
 
 ## Bring your own model, or use ours
 
@@ -207,15 +213,21 @@ The backend is chosen with `evaluator=`:
 of magnitude faster than SciPy, at roughly the accuracy of 100-draw GHK
 simulation ([studies/ghk.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/studies/ghk.md)). It ships for CPython 3.11
 and 3.12 on x86-64 Linux (`pip install multivariate-probit[orthant]`); without
-a key it runs d ≤ 3 at `resolution="low"`. Key:
-[quantecarlo.com/orthant_key](https://quantecarlo.com/orthant_key).
+a key it runs d ≤ 3 at `resolution="low"`. The key is read from `$ORTHANT_KEY` or
+`~/.orthant/key` at import, or passed in code with
+`from multivariate_probit import orthant; orthant.activate(key)` (on Spark, call it inside
+the function the workers run). Key: [quantecarlo.com/orthant_key](https://quantecarlo.com/orthant_key).
 
 Benchmarks against other tools: [docs/benchmarks.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/benchmarks.md).
 
 ## Where your data goes
 
-Nowhere. Fitting and every `evaluator` run on your machine; the package makes
-no network calls, and the `"orthant"` key is checked offline.
+Nowhere, by default. Fitting and every `evaluator` run on your machine; the
+package makes no network calls, and the `"orthant"` key is checked offline.
+
+The exception is opt-in: `fitter="modal"` uploads X, Y and `sample_weight` to
+a GPU service for the full-likelihood fit and gets parameters back. Everything
+after `fit` runs locally.
 
 The one hosted path is a separate package you call yourself:
 [`quantecarlo.orthant_cdf`](https://github.com/sign-of-fourier/quantecarlo#orthant-probabilities-orthant_cdf),
@@ -252,6 +264,7 @@ runnable example on synthetic data:
 ## Documentation
 
 - [docs/ifm.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/ifm.md): the estimation algorithm, and why IFM
+- [docs/fiml.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/fiml.md): the full-likelihood GPU fit (`fitter="modal"`), with standard errors
 - [docs/api.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/api.md): parameters, evaluators, the inner-model contract
 - [docs/implementation.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/implementation.md): what is hand-rolled, numerical accuracy
 - [docs/limitations.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/limitations.md): known gaps

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/README.md

@@ -37,7 +37,7 @@ Using this on a real problem?
 - Your **multilabel** or **multi-output** model treats labels as independent,
   and you need the **joint probability** of a label combination.
 - You've used R `mvProbit` or Stata `mvprobit` and want **multivariate probit in
-  Python** for prediction at scale (no standard errors yet; see below).
+  Python**, with standard errors from a full-likelihood fit or prediction at scale.
 - You want to **combine several fraud or risk model scores** into one
   probability that "any of these happened."
 - You need **co-occurrence** or **label dependence** expressed as one
@@ -65,6 +65,9 @@ features it is the tetrachoric correlation conditional on x. Fitting is
 two-stage **Inference Functions for Margins** (IFM): each margin is fitted
 alone and cross-fitted, then Σ is estimated by maximum likelihood with the
 margins held fixed ([docs/ifm.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/ifm.md)).
+For linear margins, `fitter="modal"` is the alternative: full maximum
+likelihood, all margins and Σ at once, on a hosted GPU, with standard errors
+([docs/fiml.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/fiml.md)).
 
 ## Why not write it yourself
 
@@ -102,8 +105,11 @@ wrong; each is handled here and documented.
   explicit and readable in `correlation_`, but each margin is as much a black
   box as the classifier inside it. SHAP is the tool for explaining a single
   black-box model; this package does not make one explainable.
-- **No standard errors yet.** Coefficients and Σ are point estimates
-  ([limitations](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/limitations.md)).
+- **Standard errors with `fitter="modal"` only.** The IFM fit gives point
+  estimates
+  ([limitations](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/limitations.md));
+  the full-likelihood fit returns `stderr_` and `cov_params_` for the
+  coefficients and Σ.
 
 ## Bring your own model, or use ours
 
@@ -143,15 +149,21 @@ The backend is chosen with `evaluator=`:
 of magnitude faster than SciPy, at roughly the accuracy of 100-draw GHK
 simulation ([studies/ghk.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/studies/ghk.md)). It ships for CPython 3.11
 and 3.12 on x86-64 Linux (`pip install multivariate-probit[orthant]`); without
-a key it runs d ≤ 3 at `resolution="low"`. Key:
-[quantecarlo.com/orthant_key](https://quantecarlo.com/orthant_key).
+a key it runs d ≤ 3 at `resolution="low"`. The key is read from `$ORTHANT_KEY` or
+`~/.orthant/key` at import, or passed in code with
+`from multivariate_probit import orthant; orthant.activate(key)` (on Spark, call it inside
+the function the workers run). Key: [quantecarlo.com/orthant_key](https://quantecarlo.com/orthant_key).
 
 Benchmarks against other tools: [docs/benchmarks.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/benchmarks.md).
 
 ## Where your data goes
 
-Nowhere. Fitting and every `evaluator` run on your machine; the package makes
-no network calls, and the `"orthant"` key is checked offline.
+Nowhere, by default. Fitting and every `evaluator` run on your machine; the
+package makes no network calls, and the `"orthant"` key is checked offline.
+
+The exception is opt-in: `fitter="modal"` uploads X, Y and `sample_weight` to
+a GPU service for the full-likelihood fit and gets parameters back. Everything
+after `fit` runs locally.
 
 The one hosted path is a separate package you call yourself:
 [`quantecarlo.orthant_cdf`](https://github.com/sign-of-fourier/quantecarlo#orthant-probabilities-orthant_cdf),
@@ -188,6 +200,7 @@ runnable example on synthetic data:
 ## Documentation
 
 - [docs/ifm.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/ifm.md): the estimation algorithm, and why IFM
+- [docs/fiml.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/fiml.md): the full-likelihood GPU fit (`fitter="modal"`), with standard errors
 - [docs/api.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/api.md): parameters, evaluators, the inner-model contract
 - [docs/implementation.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/implementation.md): what is hand-rolled, numerical accuracy
 - [docs/limitations.md](https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/limitations.md): known gaps

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/benchmarks/bench.py

@@ -104,8 +104,8 @@ def run_cell(d, n_train=3000, n_test=100, rho=0.4, seed=0, sigma="equi"):
     if d <= 6:
         res["mvp quadrature"] = timed(lambda: model.set_params(evaluator="quadrature").joint_proba(Xte, Yte))
     if orthant is not None and (ORTHANT_KEYED or d <= 3):
-        r = "high" if ORTHANT_KEYED else "low"
-        res[f"mvp orthant ({r})"] = timed(lambda: model.set_params(evaluator="orthant", resolution=r).joint_proba(Xte, Yte))
+        for r in (("high", "highest") if ORTHANT_KEYED else ("low",)):
+            res[f"mvp orthant ({r})"] = timed(lambda: model.set_params(evaluator="orthant", resolution=r).joint_proba(Xte, Yte))
     res["SciPy default"] = timed(lambda: model.set_params(evaluator="scipy").joint_proba(Xte, Yte))
     if mvncd_batch is not None:
         st = np.moveaxis(stack, 2, 0)

multivariate_probit-0.3.1/benchmarks/results.csv

@@ -0,0 +1,65 @@
+sigma,d,N,method,median_err,max_err,s_per_row
+equi,3,100,mvp quadrature,1.3373382605444406e-05,5.564767189014663e-05,7.751391967758536e-05
+equi,3,100,mvp orthant (high),5.190348623980261e-05,0.00019774969627306405,1.484813867136836e-05
+equi,3,100,mvp orthant (highest),1.999845194528005e-06,7.989768001565034e-06,4.311794182285666e-05
+equi,3,100,SciPy default,2.039637077871914e-06,1.1415786741186817e-05,0.005793280370999128
+equi,3,100,pybhatlib ovus,0.00011229346488104974,0.0008524556947959311,8.469653083011508e-05
+equi,3,100,statsmodels,0.028443441360488153,0.09919722660040897,6.613903678953648e-07
+equi,3,100,reference,0.0,0.0,0.2536748156798421
+equi,5,100,mvp quadrature,2.0314513939401896e-05,0.00011324180994054522,0.04333823672030121
+equi,5,100,mvp orthant (high),8.080162918654848e-05,0.00030384074452138865,2.3601381108164788e-05
+equi,5,100,mvp orthant (highest),3.4247200694226265e-06,2.3859122737224236e-05,7.270404836162925e-05
+equi,5,100,SciPy default,1.3427915335623153e-06,7.990427117937626e-06,0.010302326420787721
+equi,5,100,pybhatlib ovus,0.00039917378471633624,0.0019016346577496457,0.00011997280875220894
+equi,5,100,statsmodels,0.024622620503874038,0.12870241315304662,5.677388980984688e-07
+equi,5,100,reference,0.0,0.0,0.5339089114402304
+equi,8,100,mvp orthant (high),7.013787736394328e-05,0.00045342350585386715,4.317081067711115e-05
+equi,8,100,mvp orthant (highest),4.605751738051556e-06,2.9230892634346528e-05,9.955347049981356e-05
+equi,8,100,SciPy default,1.0030036643121978e-06,8.134689687355756e-06,0.01642337770899758
+equi,8,100,pybhatlib ovus,0.0003370945286850363,0.0023083975100191556,0.0001771104708313942
+equi,8,100,statsmodels,0.014453125416131472,0.11538392212916126,9.872694499790668e-07
+equi,8,100,reference,0.0,0.0,1.4400106923800196
+equi,12,100,mvp orthant (high),6.245144142705012e-05,0.0007179989696481925,6.305043119937181e-05
+equi,12,100,mvp orthant (highest),5.63448417025339e-06,4.668168500868153e-05,0.00014906150056049228
+equi,12,100,SciPy default,3.440844550360589e-07,7.96331593577726e-06,0.02377823827089742
+equi,12,100,pybhatlib ovus,0.0002047092197251764,0.0035788660943063266,0.0002432926092296839
+equi,12,100,statsmodels,0.006303004648829415,0.07762653255283464,1.5006307512521743e-06
+equi,12,100,reference,0.0,0.0,1.6423227695701643
+equi,16,100,mvp orthant (high),1.630594965073808e-05,0.0006243813016577615,9.883297141641379e-05
+equi,16,100,mvp orthant (highest),1.1074220600440065e-06,2.9310608489277468e-05,0.00022130653960630297
+equi,16,100,SciPy default,6.853848620851782e-08,4.3920697129634645e-06,0.03263484545052051
+equi,16,100,pybhatlib ovus,1.6800734753088424e-05,0.0011253768512156778,0.00031500173965469
+equi,16,100,statsmodels,0.0014514737962008938,0.05355898580397629,1.4994502998888493e-06
+equi,16,100,reference,0.0,0.0,1.1454083026899025
+pairwise,3,100,mvp quadrature,4.975128970532983e-06,8.276622284841828e-05,7.341289892792702e-05
+pairwise,3,100,mvp orthant (high),0.0006363036604397354,0.002893273763736187,2.0136469975113868e-05
+pairwise,3,100,mvp orthant (highest),0.00011323696696274865,0.0007099285566469216,4.4253640808165074e-05
+pairwise,3,100,SciPy default,1.3494787358958593e-06,2.586364471635072e-05,0.0073384556197561325
+pairwise,3,100,pybhatlib ovus,0.00037654161082817383,0.004713394298326956,8.070134790614248e-05
+pairwise,3,100,statsmodels,0.037060543222106224,0.15997644750429899,4.6383123844861987e-07
+pairwise,3,100,reference,0.0,0.0,0.24052267621998907
+pairwise,5,100,mvp quadrature,5.607947987679163e-06,6.266772635254991e-05,0.04593952419003472
+pairwise,5,100,mvp orthant (high),0.0060661393002539865,0.03370856471106998,2.4112039245665073e-05
+pairwise,5,100,mvp orthant (highest),0.003141591472459862,0.0325453719435822,6.538510089740157e-05
+pairwise,5,100,SciPy default,1.2512113251161167e-06,2.1201235567813725e-05,0.14286554857157172
+pairwise,5,100,pybhatlib ovus,0.0014663128072703105,0.02764332982515838,0.00012095558922737837
+pairwise,5,100,statsmodels,0.052292238612919734,0.2549403651447862,5.610100924968719e-07
+pairwise,5,100,reference,0.0,0.0,1.2560263323498657
+pairwise,8,100,mvp orthant (high),0.0047540425543466,0.03786870554320598,3.998839994892478e-05
+pairwise,8,100,mvp orthant (highest),0.0021531855423506108,0.013414597153998009,9.109209990128875e-05
+pairwise,8,100,SciPy default,2.2860621589921443e-06,3.321167501391109e-05,1.132777205838356
+pairwise,8,100,pybhatlib ovus,0.0015355099588129813,0.010313908094296734,0.00017519862158223986
+pairwise,8,100,statsmodels,0.024908203618945243,0.1426044668035415,8.142902515828609e-07
+pairwise,8,100,reference,0.0,0.0,4.434727118879964
+pairwise,12,100,mvp orthant (high),0.003428055959417961,0.04309079684926198,6.395480129867793e-05
+pairwise,12,100,mvp orthant (highest),0.002445889327158528,0.02153141541464762,0.00015708803897723555
+pairwise,12,100,SciPy default,1.9157011284364617e-06,5.195613406111521e-05,1.5738827282516286
+pairwise,12,100,pybhatlib ovus,0.0007431598443556342,0.01388904489935694,0.0002463792893104255
+pairwise,12,100,statsmodels,0.014263734107914516,0.1854686635860365,1.2842798605561255e-06
+pairwise,12,100,reference,0.0,0.0,9.518902401560045
+pairwise,16,100,mvp orthant (high),0.0037733872849075424,0.04512852480876324,8.360587060451507e-05
+pairwise,16,100,mvp orthant (highest),0.00293222915103126,0.045234964595115376,0.00021089559188112618
+pairwise,16,100,SciPy default,1.7024296601283496e-06,1.0376357636343592e-05,1.7738397101382726
+pairwise,16,100,pybhatlib ovus,0.0009786447220386783,0.015062755675490355,0.0003229634207673371
+pairwise,16,100,statsmodels,0.010651175036494289,0.18479811475521019,1.8178089521825314e-06
+pairwise,16,100,reference,0.0,0.0,19.51646036452992

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/docs/api.md

@@ -1,7 +1,8 @@
 # API reference
 
 For the model and a quickstart see [../README.md](../README.md); for the
-estimation algorithm see [ifm.md](ifm.md).
+estimation algorithm see [ifm.md](ifm.md), and for the full-likelihood GPU fit
+see [fiml.md](fiml.md).
 
 ## MultivariateProbit
 
@@ -17,6 +18,8 @@ MultivariateProbit(
     random_state=None,
     evaluator="quadrature",
     resolution="high",
+    fitter="ifm",
+    n_draws=512,
 )
 ```
 
@@ -33,7 +36,9 @@ MultivariateProbit(
 | `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). |
-| `resolution` | `"high"` | Passed to `evaluator="orthant"`; ignored otherwise. |
+| `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. |
 
 > **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
@@ -72,7 +77,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`; see https://quantecarlo.com/orthant_key. Accuracy and speed against GHK and SciPy: [studies/ghk.md](studies/ghk.md). |
+| `"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). |
 
 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
@@ -87,10 +92,14 @@ the
 | --- | --- | --- |
 | `inner_models_` | list, length d | The fitted margins, one per outcome. |
 | `correlation_` | (d, d) | The fitted Σ. |
-| `eta_` | (n, d) | The (cross-fitted) latent indices stage two was fitted on. |
+| `eta_` | (n, d) | The (cross-fitted) latent indices stage two was fitted on; for `fitter="modal"`, the in-sample indices of the fitted model. |
 | `calibration_` | (d, 2) | Intercept and slope of a probit of each outcome on its own fitted index — the calibration slope. See the note below. |
-| `nll_` | float | Negative log-likelihood at the end of the dependence fit. Joint and pairwise fits optimise different objectives, so the values are not comparable across settings. |
-| `optimize_result_` | OptimizeResult or None | The SciPy result for `dependence="joint"`. |
+| `nll_` | float | Negative log-likelihood at the end of the dependence fit. Joint and pairwise fits optimise different objectives, so the values are not comparable across settings. For `fitter="modal"`, the simulated joint negative log-likelihood of all margins and Σ. |
+| `optimize_result_` | OptimizeResult or None | The SciPy result for `dependence="joint"`. `None` for `fitter="modal"`. |
+| `stderr_`, `stderr_robust_` | dict | `fitter="modal"` only. Standard errors keyed `"coef"` (d, n_features), `"intercept"` (d,), `"correlation"` (d, d); inverse-Hessian and sandwich. |
+| `cov_params_`, `cov_params_robust_` | (k, k) | `fitter="modal"` only. The matching covariance matrices, ordered as `param_names_`. |
+| `param_names_` | list of str | `fitter="modal"` only. `coef[j,k]`, then `intercept[j]`, then `rho[j,k]` for j < k. |
+| `fit_result_` | dict | `fitter="modal"` only. `n_iter`, `converged`, `grad_max`, `n_draws`, `seed`. |
 | `n_outcomes_`, `n_features_in_` | int | |
 
 ### Methods

multivariate_probit-0.3.1/docs/benchmarks.md

@@ -0,0 +1,95 @@
+# Benchmarks against other tools
+
+**Task.** Score `P(Y = y | x)`, the probability of the pattern each held-out
+row actually has, from one fitted model. Synthetic data: 6 features, linear
+margins, 3,000 training rows, 100 scored rows per d. The model is
+`MultivariateProbit(inner="linear", dependence="pairwise", random_state=0)`.
+Every column scores that same fitted model (η̂, Σ̂), except statsmodels.
+
+There are two shapes of true Σ:
+
+- **Equicorrelated**, ρ = 0.4: the easy case.
+- **Pairwise-shaped**: a rank-2 factor plus noise, projected to the nearest
+  correlation matrix (smallest eigenvalue about 1e-8), the same construction
+  as [studies/ghk.md](studies/ghk.md). A fitted pairwise Σ̂ lands on that PSD
+  boundary, which is hard for every approximation.
+
+**Reference.** SciPy `multivariate_normal.cdf` with `abseps=1e-7`,
+`releps=1e-6`, one row at a time. Error is the absolute difference from it in
+probability: median over rows, maximum in parentheses. Time is wall-clock per
+row after one warm-up call, on a two-core x86-64 Linux machine.
+
+Reproduce with [benchmarks/benchmarks.ipynb](../benchmarks/benchmarks.ipynb)
+(logic in `benchmarks/bench.py`; raw numbers in `benchmarks/results.csv`).
+The reference values are cached in `benchmarks/ref_*.npz` together with the
+problem they were computed for, so a rerun skips the slow part and a changed
+problem recomputes. The `orthant` column needs a key in `$ORTHANT_KEY` or
+`~/.orthant/key`.
+
+### Equicorrelated Σ (ρ = 0.4)
+
+| d | median p | multivariate-probit `orthant` (`resolution="high"`) | multivariate-probit `orthant` (`resolution="highest"`) | multivariate-probit `quadrature` | SciPy, default tolerances | pybhatlib (Bhat OVUS) | statsmodels |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 3 | 0.348 | 1.5e-05 s / 0.0001 (0.0002) | 4.3e-05 s / 0.0000 (0.0000) | 7.8e-05 s / 0.0000 (0.0001) | 5.8e-03 s / 0.0000 (0.0000) | 8.5e-05 s / 0.0001 (0.0009) | 6.6e-07 s / 0.0284 (0.0992) |
+| 5 | 0.154 | 2.4e-05 s / 0.0001 (0.0003) | 7.3e-05 s / 0.0000 (0.0000) | 4.3e-02 s / 0.0000 (0.0001) | 1.0e-02 s / 0.0000 (0.0000) | 1.2e-04 s / 0.0004 (0.0019) | 5.7e-07 s / 0.0246 (0.1287) |
+| 8 | 0.101 | 4.3e-05 s / 0.0001 (0.0005) | 1.0e-04 s / 0.0000 (0.0000) | impractical past d = 7 | 1.6e-02 s / 0.0000 (0.0000) | 1.8e-04 s / 0.0003 (0.0023) | 9.9e-07 s / 0.0145 (0.1154) |
+| 12 | 0.022 | 6.3e-05 s / 0.0001 (0.0007) | 1.5e-04 s / 0.0000 (0.0000) | impractical past d = 7 | 2.4e-02 s / 0.0000 (0.0000) | 2.4e-04 s / 0.0002 (0.0036) | 1.5e-06 s / 0.0063 (0.0776) |
+| 16 | 0.0024 | 9.9e-05 s / 0.0000 (0.0006) | 2.2e-04 s / 0.0000 (0.0000) | impractical past d = 7 | 3.3e-02 s / 0.0000 (0.0000) | 3.2e-04 s / 0.0000 (0.0011) | 1.5e-06 s / 0.0015 (0.0536) |
+
+### Pairwise-shaped Σ (near-singular)
+
+| d | median p | multivariate-probit `orthant` (`resolution="high"`) | multivariate-probit `orthant` (`resolution="highest"`) | multivariate-probit `quadrature` | SciPy, default tolerances | pybhatlib (Bhat OVUS) | statsmodels |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| 3 | 0.431 | 2.0e-05 s / 0.0006 (0.0029) | 4.4e-05 s / 0.0001 (0.0007) | 7.3e-05 s / 0.0000 (0.0001) | 7.3e-03 s / 0.0000 (0.0000) | 8.1e-05 s / 0.0004 (0.0047) | 4.6e-07 s / 0.0371 (0.1600) |
+| 5 | 0.171 | 2.4e-05 s / 0.0061 (0.0337) | 6.5e-05 s / 0.0031 (0.0325) | 4.6e-02 s / 0.0000 (0.0001) | 1.4e-01 s / 0.0000 (0.0000) | 1.2e-04 s / 0.0015 (0.0276) | 5.6e-07 s / 0.0523 (0.2549) |
+| 8 | 0.097 | 4.0e-05 s / 0.0048 (0.0379) | 9.1e-05 s / 0.0022 (0.0134) | impractical past d = 7 | 1.1e+00 s / 0.0000 (0.0000) | 1.8e-04 s / 0.0015 (0.0103) | 8.1e-07 s / 0.0249 (0.1426) |
+| 12 | 0.025 | 6.4e-05 s / 0.0034 (0.0431) | 1.6e-04 s / 0.0024 (0.0215) | impractical past d = 7 | 1.6e+00 s / 0.0000 (0.0001) | 2.5e-04 s / 0.0007 (0.0139) | 1.3e-06 s / 0.0143 (0.1855) |
+| 16 | 0.013 | 8.4e-05 s / 0.0038 (0.0451) | 2.1e-04 s / 0.0029 (0.0452) | impractical past d = 7 | 1.8e+00 s / 0.0000 (0.0000) | 3.2e-04 s / 0.0010 (0.0151) | 1.8e-06 s / 0.0107 (0.1848) |
+
+R `mvProbit` was not run (see below).
+
+The reference itself took 0.24 to 1.6 s per row on the equicorrelated Σ and
+0.24 to 20 s per row on the pairwise-shaped one. At d = 16 on the
+equicorrelated Σ most pattern probabilities are small (median 0.0024), so the
+maximum error says more than the median there.
+
+## Reading the tables
+
+- **statsmodels** fits one `Probit` per outcome and has no correlation matrix,
+  so its pattern probability is a product of marginals. Its error is the cost
+  of ignoring Σ, not of numerical integration, and it does not shrink with
+  more data. Its time covers prediction only.
+- **`orthant`** scores all rows in one compiled call.
+  - **`resolution="high"`** was the fastest of the integrating methods at every
+    d on both Σ shapes: 3 to 6 times faster than pybhatlib, and 330 to 440 times
+    faster than SciPy on the equicorrelated Σ. Median error 0.0001 or less on the
+    equicorrelated Σ (maximum up to 0.0007, against pybhatlib's 0.0009 to
+    0.0036). On the pairwise-shaped Σ, median error 0.0006 to 0.0061, maximum up
+    to 0.045, the largest of the integrating methods.
+  - **`resolution="highest"`** costs 2.2 to 3.1 times `"high"`'s time and is
+    still 1.4 to 2 times faster than pybhatlib. On the equicorrelated Σ its
+    median and maximum error are below 0.00005 at every d. On the
+    pairwise-shaped Σ its median error is 0.0001 to 0.0031 (`"high"`: 0.0006 to
+    0.0061) and its maximum up to 0.045; pybhatlib's median there is 0.0004 to
+    0.0015.
+- **pybhatlib** scores with Bhat's analytic approximation (`mvncd_batch`,
+  `method="ovus"`), one row at a time in Python. It is 70 to 105 times faster
+  than SciPy on the equicorrelated Σ. On the pairwise-shaped Σ its median error
+  is 0.0004 to 0.0015 and its maximum 0.0047 to 0.028. pybhatlib also has a PyTorch backend that runs on
+  your own GPU, but in pybhatlib 0.4.0 `mvncd` converts its inputs to NumPy
+  and `mvncd_batch` loops over rows in Python, so the GPU does not speed up
+  this scoring.
+- **SciPy** stays accurate on the pairwise-shaped Σ but slows sharply, to
+  1.1 to 1.8 s per row from d = 8. That is 54 to 69 times its time on the
+  equicorrelated Σ at the same d.
+- **`quadrature`** matched the reference on both shapes up to d = 5.
+- **R `mvProbit`** was not run: R is not installed on the benchmark machine,
+  and the notebook has no R column yet.
+
+## What this does not establish
+
+- Two Σ shapes, one seed, and 100 rows per d. The pairwise-shaped Σ is one
+  construction of a near-singular matrix; see [studies/ghk.md](studies/ghk.md)
+  and [studies/comparators.md](studies/comparators.md) for more.
+- Scoring only. Fitting time against full-likelihood estimation is in
+  [studies/comparators.md](studies/comparators.md).

multivariate_probit-0.3.1/docs/fiml.md

@@ -0,0 +1,96 @@
+# Full maximum likelihood on a GPU (`fitter="modal"`)
+
+An alternative to [IFM](ifm.md), not a stage of it. Every margin's
+coefficients and the correlation matrix Σ are estimated together, by
+maximising the joint likelihood
+
+```
+L(B, Σ) = Σ_i w_i log P(Y = y_i | x_i),    η_ij = b_j0 + x_i' b_j
+```
+
+on a hosted GPU service. Only linear margins: the joint likelihood has to be
+differentiated through every margin, which rules out boosted trees and forests.
+
+```python
+model = MultivariateProbit(fitter="modal").fit(X, Y)
+model.correlation_            # Σ
+model.stderr_["coef"]         # (d, n_features) standard errors
+model.stderr_robust_          # sandwich standard errors
+model.predict_proba(X_new)    # runs locally, on any evaluator
+```
+
+## What changes, and what doesn't
+
+Only `fitter="modal"` changes. After `fit`, the model is used exactly as an
+IFM fit is: `transform`, `predict_proba` and its joint queries, `joint_proba`,
+`score`, `sample`, `correlation_`, `inner_models_[j].coef_`, `get_params` /
+`set_params`. Prediction runs locally on the chosen `evaluator`.
+
+The differences:
+
+- `inner` must be `"linear"`; `inner_params` may set only `alpha`. Anything
+  else raises.
+- `dependence`, `cv`, `optimizer` and `project_correlation` do not apply.
+- `fit` uploads X, Y and `sample_weight` and waits for the service (see
+  [Cost](#cost)).
+- Extra attributes: `stderr_`, `stderr_robust_`, `cov_params_`,
+  `cov_params_robust_`, `param_names_`, `fit_result_`.
+- `eta_` holds in-sample indices (there is no cross-fitting); `nll_` is the
+  simulated joint negative log-likelihood; `optimize_result_` is `None`.
+- An int `random_state` seeds the Sobol draws; otherwise the seed is 0, so
+  repeated fits agree.
+
+## When to use it instead of IFM
+
+- You need **standard errors** for the coefficients and for Σ. IFM does not
+  report them ([limitations.md](limitations.md)); this path does.
+- You want the **efficient estimator**. IFM is consistent but discards the
+  information that the other outcomes carry about each margin; full ML does not.
+- The margins are linear anyway. With flexible margins, IFM is the only option.
+
+IFM stays the default: it runs locally, takes any inner model, and its cost
+does not grow with the number of margin parameters.
+
+## How it works
+
+- The probability of each observed pattern is a d-dimensional orthant integral,
+  simulated by GHK with randomised quasi-Monte Carlo: one scrambled Sobol set
+  of `n_draws` points, shifted per row. The draws are **fixed for the whole
+  fit**, so the simulated log-likelihood is a smooth deterministic function of
+  the parameters and a quasi-Newton optimiser (L-BFGS) with exact gradients
+  applies.
+- Σ is parameterised so that every parameter value is a valid correlation
+  matrix: no projection or penalty is ever needed.
+- The fit starts from the margins fitted with Σ = I (exact, no simulation),
+  then optimises everything jointly.
+- X is standardised on the service; coefficients come back on the original
+  scale. `inner_params={"alpha": ...}` sets the same small ridge on the slopes
+  as `ProbitRegressor` (default 1e-6).
+
+## Standard errors
+
+At the optimum the service computes the exact Hessian of the simulated
+log-likelihood. Two covariance matrices come back, mapped to the reported
+parameters (coefficients on the original X scale, intercepts, and the
+correlations ρ_jk):
+
+- `cov_params_` / `stderr_`: inverse Hessian, the classical ML standard errors.
+- `cov_params_robust_` / `stderr_robust_`: the sandwich `H⁻¹ (Σ_i w_i² g_i g_i') H⁻¹`.
+  Use it with `sample_weight`, or when the model may be misspecified.
+
+`param_names_` gives the order of both matrices. The standard errors treat the
+Sobol draws as fixed: they do not include simulation error, which is small
+next to sampling error at the default `n_draws=512`.
+
+## Where the data goes
+
+X, Y and `sample_weight` are uploaded to the service. The response holds
+parameters only; the service keeps the result for collection, and nothing
+after `fit` makes a network call — prediction and scoring run locally with the
+chosen `evaluator`.
+
+## Cost
+
+A fit is submitted, then polled until done. On a T4: about 50 s end to end for
+n = 50,000, 10 features and d = 6, standard errors included; small fits take
+15 to 20 s, plus up to a minute when the service is starting cold.

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/docs/limitations.md

@@ -4,7 +4,8 @@ The gaps below are known and stated rather than discovered later.
 
 ## Statistical
 
-**No standard errors.** `correlation_` is a point estimate. Because stage two
+**No standard errors from IFM.** (`fitter="modal"` reports them, for linear
+margins; see [fiml.md](fiml.md).) Under IFM, `correlation_` is a point estimate. Because stage two
 conditions on estimated margins, inverse-Hessian standard errors would be
 wrong; correct inference needs a Godambe (sandwich) information matrix or a
 bootstrap that resamples and refits both stages. Neither is implemented, and

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/docs/studies/ghk.md

@@ -6,6 +6,11 @@ without measuring it. For *scoring* a fitted model, where that objection does
 not apply, how does GHK compare with the compiled `orthant` backend in
 accuracy and speed?
 
+> **Version note (2026-10).** This study measured the backend shipped in 0.2.1. Later builds integrate
+> `resolution="high"` on a finer rule and add `resolution="highest"`, which is more accurate at a few times the
+> cost. The tables below were not rerun; current numbers for both settings are in
+> [benchmarks.md](../benchmarks.md).
+
 ## Summary
 
 | | accuracy | speed (s per row) |

{multivariate_probit-0.2.3 → multivariate_probit-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "multivariate-probit"
-version = "0.2.3"
+version = "0.3.1"
 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.2.3 → multivariate_probit-0.3.1}/src/multivariate_probit/__init__.py

@@ -4,7 +4,8 @@ A multivariate probit is a Gaussian squashing function wrapped around an
 arbitrary inner model. This package fits one by Inference Functions for Margins
 (IFM): margins first, dependence second. The inner model is pluggable -- linear
 by default, gradient boosting or random forests via named presets, anything
-scikit-learn-shaped via the adapter.
+scikit-learn-shaped via the adapter. For linear margins, ``fitter="modal"``
+fits by full maximum likelihood on a hosted GPU instead, with standard errors.
 
     >>> from multivariate_probit import MultivariateProbit
     >>> model = MultivariateProbit(inner="linear").fit(X, Y)
@@ -33,7 +34,7 @@ from .linear import ProbitRegressor
 from .model import MultivariateProbit
 from .results import MultivariateProbitProba
 
-__version__ = "0.2.3"
+__version__ = "0.3.1"
 
 __all__ = [
     "MultivariateProbit",

multivariate_probit-0.3.1/src/multivariate_probit/_remote.py

@@ -0,0 +1,81 @@
+"""Client for the hosted full-likelihood fit (``fitter="modal"``).
+
+The fit runs on a GPU service: the request carries X, Y and the weights; the
+response carries parameters only -- coefficients, intercepts, the correlation
+matrix and their covariance. Everything after that runs locally. The service
+answers a submission with a call id and is then polled, because a fit can
+outlast a single HTTP request.
+
+Standard library only (``urllib``), so the package gains no dependency.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+import numpy as np
+
+__all__ = ["fit_remote", "FIT_URL", "RESULT_URL"]
+
+FIT_URL = "https://info-29741--bo-gp-service-mvp-fit.modal.run"
+RESULT_URL = "https://info-29741--bo-gp-service-mvp-fit-result.modal.run"
+
+_REQUEST_TIMEOUT = 300  # seconds per HTTP request (the upload can be large)
+
+
+def _error_text(exc):
+    try:
+        body = json.loads(exc.read())
+        return body.get("error", str(body))
+    except Exception:
+        return str(exc)
+
+
+def fit_remote(X, Y, sample_weight=None, poll_interval=2.0, timeout=3600, **params):
+    """Submit a fit, wait for it, and return the result as a dict of arrays.
+
+    ``params`` are the service's fields: ``n_draws``, ``seed``, ``max_iter``,
+    ``tol``, ``alpha``, ``se``, ``dtype``. Raises ``ValueError`` if the service
+    rejects the input, ``RuntimeError`` if the fit fails or cannot be
+    collected, and ``TimeoutError`` after ``timeout`` seconds.
+    """
+    arrays = {"X": np.asarray(X, dtype=np.float64), "Y": np.asarray(Y, dtype=np.float64)}
+    if sample_weight is not None:
+        arrays["sample_weight"] = np.asarray(sample_weight, dtype=np.float64)
+    buf = io.BytesIO()
+    np.savez(buf, params=np.array(json.dumps(params)), **arrays)
+    request = urllib.request.Request(
+        FIT_URL,
+        data=buf.getvalue(),
+        headers={"Content-Type": "application/octet-stream"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=_REQUEST_TIMEOUT) as resp:
+            call_id = json.loads(resp.read())["call_id"]
+    except urllib.error.HTTPError as exc:
+        if exc.code == 400:
+            raise ValueError(f"the fitting service rejected the input: {_error_text(exc)}") from None
+        raise RuntimeError(f"the fitting service failed ({exc.code}): {_error_text(exc)}") from None
+
+    url = RESULT_URL + "?" + urllib.parse.urlencode({"call_id": call_id, "format": "npz"})
+    deadline = time.monotonic() + timeout
+    while True:
+        try:
+            with urllib.request.urlopen(url, timeout=_REQUEST_TIMEOUT) as resp:
+                status, body = resp.status, resp.read()
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(
+                f"remote fit {call_id} failed ({exc.code}): {_error_text(exc)}"
+            ) from None
+        if status == 200:
+            with np.load(io.BytesIO(body), allow_pickle=False) as npz:
+                return {key: npz[key] for key in npz.files}
+        if time.monotonic() > deadline:
+            raise TimeoutError(f"remote fit {call_id} still running after {timeout} s")
+        time.sleep(poll_interval)