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

{multivariate_probit-0.2.3 → multivariate_probit-0.3.0}/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-04
 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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: multivariate-probit
-Version: 0.2.3
+Version: 0.3.0
 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
 
@@ -214,8 +220,12 @@ Benchmarks against other tools: [docs/benchmarks.md](https://github.com/sign-of-
 
 ## 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 +262,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.0}/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
 
@@ -150,8 +156,12 @@ Benchmarks against other tools: [docs/benchmarks.md](https://github.com/sign-of-
 
 ## 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 +198,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.0}/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,
 )
 ```
 
@@ -34,6 +37,8 @@ MultivariateProbit(
 | `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. |
+| `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
@@ -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"`. |
+| `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.0/docs/fiml.md

@@ -0,0 +1,75 @@
+# 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
+```
+
+## 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.0}/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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "multivariate-probit"
-version = "0.2.3"
+version = "0.3.0"
 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.0}/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.0"
 
 __all__ = [
     "MultivariateProbit",

multivariate_probit-0.3.0/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)

{multivariate_probit-0.2.3 → multivariate_probit-0.3.0}/src/multivariate_probit/model.py

@@ -1,4 +1,4 @@
-"""The estimator: a multivariate probit fitted by IFM."""
+"""The estimator: a multivariate probit fitted by IFM, or by full ML on a GPU service."""
 
 from __future__ import annotations
 
@@ -8,6 +8,7 @@ import warnings
 import numpy as np
 from scipy.stats import norm
 
+from . import _remote
 from ._corr import is_positive_definite
 from ._mvn import EVALUATORS, pattern_prob
 from .ifm import joint_correlation, pair_log_likelihood, pairwise_correlation
@@ -19,6 +20,8 @@ __all__ = ["MultivariateProbit"]
 
 _LL_EPS = 1e-12
 
+FITTERS = ("ifm", "modal")
+
 # Slopes outside this band warn. Deliberately loose: the clinical literature
 # often flags below 0.8, which is noisier than is useful for a warning that
 # cannot be turned off per-outcome.
@@ -114,6 +117,11 @@ class MultivariateProbit:
 
     See ``docs/ifm.md`` for the derivation and the trade-offs.
 
+    ``fitter="modal"`` is the alternative: full-information maximum likelihood,
+    every margin and ``R`` estimated jointly, on a hosted GPU service. It is
+    limited to linear margins, sends X, Y and the weights to the service, and
+    returns standard errors. See ``docs/fiml.md``.
+
     Parameters
     ----------
     inner : str, estimator, callable or list, default="linear"
@@ -167,7 +175,20 @@ class MultivariateProbit:
         Project a pairwise estimate onto the nearest positive-definite
         correlation matrix (pairwise fits need not be jointly coherent).
     random_state : int or Generator, optional
-        Controls the cross-fitting split and :meth:`sample`.
+        Controls the cross-fitting split and :meth:`sample`. With
+        ``fitter="modal"``, an int also seeds the Sobol draws (otherwise 0, so
+        remote fits are reproducible by default).
+    fitter : {"ifm", "modal"}, default="ifm"
+        ``"ifm"`` is the two-stage fit described above, run locally.
+        ``"modal"`` is full maximum likelihood on the hosted GPU service:
+        linear margins only (``inner="linear"``; ``inner_params`` may set
+        ``alpha``), ``R`` and every margin fitted jointly by a GHK simulated
+        likelihood with fixed scrambled Sobol draws. ``dependence``, ``cv``,
+        ``optimizer`` and ``project_correlation`` do not apply to it. X, Y and
+        ``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.
 
     Attributes
     ----------
@@ -191,7 +212,17 @@ class MultivariateProbit:
         the slope is not identified. Computed unweighted, ignoring
         ``sample_weight``.
     nll_ : float
-        Negative log-likelihood at the end of the dependence fit.
+        Negative log-likelihood at the end of the dependence fit (for
+        ``fitter="modal"``, the simulated joint negative log-likelihood).
+    stderr_, stderr_robust_ : dict, ``fitter="modal"`` only
+        Standard errors keyed ``"coef"`` (d, n_features), ``"intercept"`` (d,)
+        and ``"correlation"`` (d, d), from the inverse Hessian and from the
+        sandwich (robust; the one to use with ``sample_weight``).
+    cov_params_, cov_params_robust_ : ndarray, ``fitter="modal"`` only
+        The matching covariance matrices, in the order of ``param_names_``.
+    param_names_ : list of str, ``fitter="modal"`` only
+    fit_result_ : dict, ``fitter="modal"`` only
+        ``n_iter``, ``converged``, ``grad_max``, ``n_draws``, ``seed``.
     n_outcomes_ : int
     n_features_in_ : int
     """
@@ -208,6 +239,8 @@ class MultivariateProbit:
         random_state=None,
         evaluator="quadrature",
         resolution="high",
+        fitter="ifm",
+        n_draws=512,
     ):
         self.inner = inner
         self.inner_params = inner_params
@@ -219,6 +252,8 @@ class MultivariateProbit:
         self.optimizer = optimizer
         self.project_correlation = project_correlation
         self.random_state = random_state
+        self.fitter = fitter
+        self.n_draws = n_draws
 
     # ------------------------------------------------------------------ fit
 
@@ -235,11 +270,15 @@ class MultivariateProbit:
             raise ValueError("Y must contain only 0/1 values")
         if self.evaluator not in EVALUATORS:
             raise ValueError(f"evaluator must be one of {EVALUATORS}; got {self.evaluator!r}")
+        if self.fitter not in FITTERS:
+            raise ValueError(f"fitter must be one of {FITTERS}; got {self.fitter!r}")
         Y = Y.astype(float)
 
         n, d = Y.shape
         self.n_features_in_ = X.shape[1]
         self.n_outcomes_ = d
+        if self.fitter == "modal":
+            return self._fit_modal(X, Y, sample_weight)
         rng = np.random.default_rng(self.random_state)
         params = dict(self.inner_params or {})
 
@@ -296,6 +335,87 @@ class MultivariateProbit:
         _require_positive_definite(self.correlation_)
         return self
 
+    def _fit_modal(self, X, Y, sample_weight):
+        if not (isinstance(self.inner, str) and self.inner == "linear"):
+            raise ValueError(
+                'fitter="modal" fits linear margins only; use inner="linear" '
+                '(or fitter="ifm" for other inner models)'
+            )
+        params = dict(self.inner_params or {})
+        alpha = float(params.pop("alpha", 1e-6))
+        if params.pop("fit_intercept", True) is not True or params:
+            raise ValueError(
+                'fitter="modal" accepts only inner_params={"alpha": ...}; '
+                "the intercept is always fitted"
+            )
+        if isinstance(self.random_state, (int, np.integer)):
+            seed = int(self.random_state)
+        else:
+            seed = 0
+        out = _remote.fit_remote(
+            X, Y, sample_weight, n_draws=int(self.n_draws), seed=seed, alpha=alpha, se=True
+        )
+
+        n, d = Y.shape
+        p = X.shape[1]
+        coef = np.asarray(out["coef"], dtype=float).reshape(d, p)
+        intercept = np.asarray(out["intercept"], dtype=float).reshape(d)
+        self.inner_models_ = []
+        for j in range(d):
+            model = ProbitRegressor(alpha=alpha)
+            model.coef_ = coef[j].copy()
+            model.intercept_ = float(intercept[j])
+            model.classes_ = np.array([0, 1])
+            model.n_iter_ = int(out["n_iter"])
+            self.inner_models_.append(model)
+        corr = np.asarray(out["corr"], dtype=float).reshape(d, d)
+        self.correlation_ = (corr + corr.T) / 2.0
+        np.fill_diagonal(self.correlation_, 1.0)
+        self.nll_ = float(out["nll"])
+        self.optimize_result_ = None
+        self.fit_result_ = {
+            "n_iter": int(out["n_iter"]),
+            "converged": bool(out["converged"]),
+            "grad_max": float(out["grad_max"]),
+            "n_draws": int(out["n_draws"]),
+            "seed": int(out["seed"]),
+        }
+
+        iu = np.triu_indices(d, 1)
+        self.param_names_ = (
+            [f"coef[{j},{k}]" for j in range(d) for k in range(p)]
+            + [f"intercept[{j}]" for j in range(d)]
+            + [f"rho[{j},{k}]" for j, k in zip(*iu)]
+        )
+
+        def unpack(se):
+            se = np.asarray(se, dtype=float)
+            rho = np.zeros((d, d))
+            rho[iu] = se[d * p + d :]
+            return {
+                "coef": se[: d * p].reshape(d, p),
+                "intercept": se[d * p : d * p + d],
+                "correlation": rho + rho.T,
+            }
+
+        self.stderr_ = unpack(out["se_hessian"])
+        self.stderr_robust_ = unpack(out["se_sandwich"])
+        self.cov_params_ = np.asarray(out["cov_hessian"], dtype=float)
+        self.cov_params_robust_ = np.asarray(out["cov_sandwich"], dtype=float)
+
+        if not self.fit_result_["converged"]:
+            warnings.warn(
+                f"the remote fit stopped at its iteration limit "
+                f"(max |gradient| {self.fit_result_['grad_max']:.2e}); the estimates "
+                "may not be at the optimum",
+                UserWarning,
+                stacklevel=3,
+            )
+        self.eta_ = self.decision_function(X)
+        self.calibration_ = self._calibrate(self.eta_, Y)
+        _require_positive_definite(self.correlation_)
+        return self
+
     def _calibrate(self, eta, Y):
         calibration = np.array(
             [_calibration_slope(eta[:, j], Y[:, j]) for j in range(Y.shape[1])],
@@ -468,6 +588,8 @@ class MultivariateProbit:
             "optimizer": self.optimizer,
             "project_correlation": self.project_correlation,
             "random_state": self.random_state,
+            "fitter": self.fitter,
+            "n_draws": self.n_draws,
         }
 
     def set_params(self, **params):
@@ -481,5 +603,5 @@ class MultivariateProbit:
     def __repr__(self):
         return (
             f"MultivariateProbit(inner={self.inner!r}, dependence={self.dependence!r}, "
-            f"cv={self.cv!r})"
+            f"cv={self.cv!r}, fitter={self.fitter!r})"
         )

multivariate_probit-0.3.0/tests/test_modal_fit.py

@@ -0,0 +1,192 @@
+"""``fitter="modal"``: the hosted full-likelihood fit.
+
+Offline: the HTTP client is faked, so these check the request, the polling
+protocol and how a result becomes a fitted model. The live round trip runs
+only with ``MVP_LIVE_MODAL=1``.
+"""
+
+import io
+import json
+import os
+import urllib.error
+
+import numpy as np
+import pytest
+
+from multivariate_probit import MultivariateProbit, ProbitRegressor
+from multivariate_probit import _remote
+
+D, P = 3, 2
+COEF = np.array([[0.5, -1.0], [1.0, 0.2], [-0.5, 0.3]])
+INTERCEPT = np.array([0.2, -0.3, 0.1])
+CORR = np.array([[1.0, 0.5, -0.3], [0.5, 1.0, 0.4], [-0.3, 0.4, 1.0]])
+K = D * P + D + D * (D - 1) // 2
+
+
+def _data(n=400, seed=0):
+    rng = np.random.default_rng(seed)
+    X = rng.normal(size=(n, P))
+    E = rng.multivariate_normal(np.zeros(D), CORR, size=n)
+    return X, (X @ COEF.T + INTERCEPT + E > 0).astype(int)
+
+
+def _result(converged=True):
+    se = np.arange(1, K + 1) / 100.0
+    return {
+        "coef": COEF, "intercept": INTERCEPT, "corr": CORR, "nll": np.array(123.4),
+        "n_iter": np.array(17), "converged": np.array(converged), "grad_max": np.array(3e-6),
+        "n_draws": np.array(512), "seed": np.array(0),
+        "se_hessian": se, "se_sandwich": 2 * se,
+        "cov_hessian": np.diag(se**2), "cov_sandwich": np.diag(4 * se**2),
+    }
+
+
+@pytest.fixture
+def fake_fit(monkeypatch):
+    calls = []
+
+    def fit_remote(X, Y, sample_weight=None, **params):
+        calls.append({"X": X, "Y": Y, "sample_weight": sample_weight, **params})
+        return _result()
+
+    monkeypatch.setattr(_remote, "fit_remote", fit_remote)
+    return calls
+
+
+def test_result_becomes_a_fitted_linear_model(fake_fit):
+    X, Y = _data()
+    model = MultivariateProbit(fitter="modal", random_state=7).fit(X, Y)
+    assert all(isinstance(m, ProbitRegressor) for m in model.inner_models_)
+    assert np.allclose(model.decision_function(X), X @ COEF.T + INTERCEPT)
+    assert np.allclose(model.correlation_, CORR)
+    assert model.nll_ == pytest.approx(123.4)
+    assert model.fit_result_["converged"] and model.fit_result_["n_iter"] == 17
+    assert model.eta_.shape == (len(X), D) and model.calibration_.shape == (D, 2)
+    proba = model.predict_proba(X[:5])
+    assert proba.shape == (5, D) and proba.all().shape == (5,)
+    assert fake_fit[0]["seed"] == 7 and fake_fit[0]["n_draws"] == 512
+
+
+def test_standard_errors_are_unpacked_in_parameter_order(fake_fit):
+    X, Y = _data()
+    model = MultivariateProbit(fitter="modal").fit(X, Y)
+    se = np.arange(1, K + 1) / 100.0
+    assert np.allclose(model.stderr_["coef"], se[: D * P].reshape(D, P))
+    assert np.allclose(model.stderr_["intercept"], se[D * P : D * P + D])
+    rho = model.stderr_["correlation"]
+    assert rho[0, 1] == rho[1, 0] == se[-3] and rho[1, 2] == se[-1] and rho[0, 0] == 0
+    assert np.allclose(model.stderr_robust_["intercept"], 2 * se[D * P : D * P + D])
+    assert model.param_names_[0] == "coef[0,0]" and model.param_names_[-1] == "rho[1,2]"
+    assert model.cov_params_.shape == (K, K) == model.cov_params_robust_.shape
+
+
+def test_alpha_weights_and_seed_default_reach_the_service(fake_fit):
+    X, Y = _data()
+    w = np.linspace(0.5, 2.0, len(X))
+    MultivariateProbit(fitter="modal", inner_params={"alpha": 0.1}, n_draws=128).fit(
+        X, Y, sample_weight=w
+    )
+    call = fake_fit[0]
+    assert call["alpha"] == 0.1 and call["n_draws"] == 128 and call["seed"] == 0
+    assert np.array_equal(call["sample_weight"], w)
+
+
+def test_non_linear_inner_is_rejected():
+    X, Y = _data(50)
+    with pytest.raises(ValueError, match="linear margins only"):
+        MultivariateProbit(inner="rf", fitter="modal").fit(X, Y)
+    with pytest.raises(ValueError, match="inner_params"):
+        MultivariateProbit(fitter="modal", inner_params={"max_iter": 5}).fit(X, Y)
+
+
+def test_unknown_fitter_is_rejected():
+    X, Y = _data(50)
+    with pytest.raises(ValueError, match="fitter must be one of"):
+        MultivariateProbit(fitter="gpu").fit(X, Y)
+
+
+def test_unconverged_fit_warns(monkeypatch):
+    monkeypatch.setattr(_remote, "fit_remote", lambda *a, **k: _result(converged=False))
+    X, Y = _data()
+    with pytest.warns(UserWarning, match="iteration limit"):
+        MultivariateProbit(fitter="modal").fit(X, Y)
+
+
+def test_params_round_trip():
+    model = MultivariateProbit(fitter="modal", n_draws=256)
+    params = model.get_params()
+    assert params["fitter"] == "modal" and params["n_draws"] == 256
+    assert MultivariateProbit(**params).get_params() == params
+
+
+# ------------------------------------------------------------ HTTP protocol
+
+
+class _Resp:
+    def __init__(self, status, body):
+        self.status, self._body = status, body
+
+    def read(self):
+        return self._body
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+
+def _npz(arrays):
+    buf = io.BytesIO()
+    np.savez(buf, **arrays)
+    return buf.getvalue()
+
+
+def test_client_submits_npz_then_polls_until_done(monkeypatch):
+    seen = []
+    pending = [_Resp(202, b'{"status": "pending"}')] * 2
+
+    def urlopen(request, timeout=None):
+        if not isinstance(request, str):  # the POST
+            with np.load(io.BytesIO(request.data)) as npz:
+                seen.append((npz["X"].shape, json.loads(str(npz["params"]))))
+            return _Resp(200, b'{"call_id": "fc-123"}')
+        assert "call_id=fc-123" in request and "format=npz" in request
+        return pending.pop() if pending else _Resp(200, _npz({"coef": np.ones((2, 1))}))
+
+    monkeypatch.setattr(_remote.urllib.request, "urlopen", urlopen)
+    out = _remote.fit_remote(np.zeros((4, 1)), np.zeros((4, 2)), poll_interval=0, n_draws=64)
+    assert out["coef"].shape == (2, 1)
+    assert seen == [((4, 1), {"n_draws": 64})]
+
+
+@pytest.mark.parametrize("code, exc", [(400, ValueError), (500, RuntimeError)])
+def test_client_maps_submit_errors(monkeypatch, code, exc):
+    def urlopen(request, timeout=None):
+        raise urllib.error.HTTPError(
+            _remote.FIT_URL, code, "x", {}, io.BytesIO(b'{"error": "bad Y"}')
+        )
+
+    monkeypatch.setattr(_remote.urllib.request, "urlopen", urlopen)
+    with pytest.raises(exc, match="bad Y"):
+        _remote.fit_remote(np.zeros((4, 1)), np.zeros((4, 2)))
+
+
+def test_client_reports_a_failed_fit(monkeypatch):
+    def urlopen(request, timeout=None):
+        if not isinstance(request, str):
+            return _Resp(200, b'{"call_id": "fc-9"}')
+        raise urllib.error.HTTPError(request, 422, "x", {}, io.BytesIO(b'{"error": "boom"}'))
+
+    monkeypatch.setattr(_remote.urllib.request, "urlopen", urlopen)
+    with pytest.raises(RuntimeError, match="fc-9.*boom"):
+        _remote.fit_remote(np.zeros((4, 1)), np.zeros((4, 2)))
+
+
+@pytest.mark.skipif(os.environ.get("MVP_LIVE_MODAL") != "1", reason="set MVP_LIVE_MODAL=1")
+def test_live_round_trip():
+    X, Y = _data(3000)
+    model = MultivariateProbit(fitter="modal").fit(X, Y)
+    assert np.abs(np.vstack([m.coef_ for m in model.inner_models_]) - COEF).max() < 0.15
+    assert np.abs(model.correlation_ - CORR).max() < 0.15
+    assert np.all(model.stderr_["coef"] > 0)