multivariate-probit 0.1.0__tar.gz → 0.2.0__tar.gz

multivariate_probit-0.2.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+venv/
+.env
+.idea/
+.vscode/
+.DS_Store
+
+# Local data, not redistributed
+UCI/
+
+# Compiled extensions, except the bundled orthant package
+*.so
+!src/multivariate_probit/orthant/*.so
+
+# Local agent notes, never part of the repo
+CLAUDE.md
+CLAUDE.local.md
+PLAN.md

{multivariate_probit-0.1.0 → multivariate_probit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: multivariate-probit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Multivariate probit models fitted by Inference Functions for Margins (IFM), with pluggable inner models.
 Project-URL: Homepage, https://github.com/sign-of-fourier/multivariate-probit
 Project-URL: Documentation, https://github.com/sign-of-fourier/multivariate-probit/blob/main/docs/ifm.md
@@ -38,12 +38,16 @@ Requires-Python: >=3.9
 Requires-Dist: numpy>=1.22
 Requires-Dist: scipy>=1.8
 Provides-Extra: all
+Requires-Dist: cryptography>=42; extra == 'all'
 Requires-Dist: scikit-learn>=1.1; extra == 'all'
 Requires-Dist: xgboost>=1.7; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: cryptography>=42; extra == 'dev'
 Requires-Dist: pytest>=7; extra == 'dev'
 Requires-Dist: scikit-learn>=1.1; extra == 'dev'
 Requires-Dist: xgboost>=1.7; extra == 'dev'
+Provides-Extra: orthant
+Requires-Dist: cryptography>=42; extra == 'orthant'
 Provides-Extra: sklearn
 Requires-Dist: scikit-learn>=1.1; extra == 'sklearn'
 Provides-Extra: xgboost
@@ -110,10 +114,12 @@ all; everything joint does.
 
 ## Everything here is a squashing function over a latent index
 
-The inner model never sees a probability, and never sees another outcome's
-labels. It produces an unbounded score η_j(x) on (-∞, ∞); Φ is the only
-squashing function applied to it. Any estimator that emits a real-valued score,
-or a probability that can be pushed back through Φ⁻¹, is a legal margin.
+The inner model never sees another outcome's labels. What stage two consumes is
+an unbounded index η_j(x) on (-∞, ∞); Φ is the only squashing function applied
+to it. A legal margin either produces that index directly, or emits a
+probability that is pushed back through Φ⁻¹ — a classifier with `predict_proba`.
+An uncalibrated `decision_function` score is not enough, since its scale is
+arbitrary.
 
 That is the whole abstraction, and it is why the inner model is swappable
 without touching the estimation code.
@@ -162,6 +168,8 @@ point estimate. Known gaps are listed in
 - **[docs/api.md](docs/api.md)** — parameters, attributes, methods, extension
   points
 - **[docs/limitations.md](docs/limitations.md)** — known gaps and roadmap
+- **[docs/studies/](docs/studies/)** — the research archive: what was measured,
+  what it settled, and what it left open
 
 ## Development
 

{multivariate_probit-0.1.0 → multivariate_probit-0.2.0}/README.md

@@ -57,10 +57,12 @@ all; everything joint does.
 
 ## Everything here is a squashing function over a latent index
 
-The inner model never sees a probability, and never sees another outcome's
-labels. It produces an unbounded score η_j(x) on (-∞, ∞); Φ is the only
-squashing function applied to it. Any estimator that emits a real-valued score,
-or a probability that can be pushed back through Φ⁻¹, is a legal margin.
+The inner model never sees another outcome's labels. What stage two consumes is
+an unbounded index η_j(x) on (-∞, ∞); Φ is the only squashing function applied
+to it. A legal margin either produces that index directly, or emits a
+probability that is pushed back through Φ⁻¹ — a classifier with `predict_proba`.
+An uncalibrated `decision_function` score is not enough, since its scale is
+arbitrary.
 
 That is the whole abstraction, and it is why the inner model is swappable
 without touching the estimation code.
@@ -109,6 +111,8 @@ point estimate. Known gaps are listed in
 - **[docs/api.md](docs/api.md)** — parameters, attributes, methods, extension
   points
 - **[docs/limitations.md](docs/limitations.md)** — known gaps and roadmap
+- **[docs/studies/](docs/studies/)** — the research archive: what was measured,
+  what it settled, and what it left open
 
 ## Development
 

{multivariate_probit-0.1.0 → multivariate_probit-0.2.0}/docs/api.md

@@ -15,6 +15,8 @@ MultivariateProbit(
     optimizer="Nelder-Mead",
     project_correlation=True,
     random_state=None,
+    evaluator="quadrature",
+    resolution="high",
 )
 ```
 
@@ -26,16 +28,52 @@ MultivariateProbit(
 | `inner_params` | `None` | Keyword arguments forwarded to the preset factory. Ignored when `inner` is already an instance. |
 | `dependence` | `"joint"` | `"joint"` maximises the full d-variate likelihood for Σ; `"pairwise"` maximises each pair's bivariate likelihood (composite likelihood, far cheaper). |
 | `cv` | `5` | Folds used to cross-fit the latent indices that stage two consumes. `None` skips cross-fitting — see the warning below. |
-| `n_quad` | `24` | Gauss-Legendre order for the orthant evaluator. Lower it if fitting with many outcomes gets slow. |
+| `n_quad` | `24` | Gauss-Legendre order for `evaluator="quadrature"`. Lower it if fitting with many outcomes gets slow. |
 | `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). |
+| `resolution` | `"high"` | Passed to `evaluator="orthant"`; 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
+> near 1 is expected. It is *not* a calibration assessment — a slope of 1 rules
+> out a first-order scale error and nothing more, and a departure from 1 has
+> several possible causes: miscalibrated probabilities from the classifier, a
+> correctly calibrated but noisy index, or an index scored on the rows it was
+> fitted on. For a real assessment of a classifier's probabilities use a
+> reliability curve; calibrating the margins is the caller's job, not the
+> estimator's, and `CalibratedClassifierCV` is the usual way to do it.
+>
+> Slopes outside roughly [0.5, 2.0] emit a `UserWarning` and never raise. The
+> band is a loose convenience, not a test with a calibrated error rate — a
+> slope inside it is not a clean bill of health, and one outside it is a
+> suggestion to look, not a verdict on the fit. A slope that is not identified
+> — a constant or non-finite index, or a single-class outcome — is `nan` and
+> stays silent. A slope near 1 is not evidence that Σ is trustworthy: the check
+> is blind to omitted signal by construction. See
+> [ifm.md](ifm.md#the-calibration-slope-sees-exactly-one-of-them) and
+> [limitations.md](limitations.md).
 
 > **`cv=None` is not a neutral speed-up.** In-sample margins drive every fitted
 > correlation toward +1. It is defensible for the linear default and reckless
 > for anything that can overfit. See
 > [ifm.md](ifm.md#why-cross-fitting-is-required).
 
+### Evaluators
+
+The speed/accuracy trade-off is the caller's. None of the backends falls back to
+another: one that cannot run as asked raises. All results are clipped to
+[0, 1]. `dependence="pairwise"` needs only bivariate probabilities, which are
+always computed in closed form, so it is unaffected during fitting; joint
+queries on a pairwise fit still use the chosen backend.
+
+| `evaluator` | What it is | Trade-off |
+| --- | --- | --- |
+| `"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. |
+
 ### Attributes
 
 | Name | Shape | Meaning |
@@ -43,6 +81,7 @@ MultivariateProbit(
 | `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. |
+| `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"`. |
 | `n_outcomes_`, `n_features_in_` | int | |
@@ -51,7 +90,7 @@ MultivariateProbit(
 
 | Method | Returns | Notes |
 | --- | --- | --- |
-| `fit(X, Y, sample_weight=None)` | self | `Y` is (n, d) and strictly 0/1. Weights are forwarded to margins that accept them. |
+| `fit(X, Y, sample_weight=None)` | self | `Y` is (n, d) and strictly 0/1. Weights are forwarded to every margin, including the wrapped estimator inside `ProbitCalibrated`; a margin whose `fit` takes no `sample_weight` is fitted unweighted with a warning. |
 | `decision_function(X)` / `transform(X)` | (n, d) | Latent indices η on (-∞, ∞). |
 | `fit_transform(X, Y)` | (n, d) | |
 | `predict_proba(X)` | `MultivariateProbitProba` | See below. |
@@ -89,14 +128,26 @@ one-liner.
 An inner model is anything with `fit(X, y)` and `latent(X) -> (n,)`, where
 `latent` returns a real-valued index on the probit scale.
 
-Estimators that do not expose `latent` are wrapped automatically by
-`ProbitCalibrated`, which supplies it:
-
-- if the estimator has `predict_proba`, `latent(X)` is `Φ⁻¹(p̂)`, clipped away
-  from 0 and 1;
-- otherwise, if it has `decision_function`, that score is used as the index
-  as-is — which assumes it is already probit-scaled. Check that assumption
-  before relying on it.
+Estimators that do not expose `latent` must expose `predict_proba`, and are
+wrapped automatically by `ProbitCalibrated`, whose `latent(X)` is `Φ⁻¹(p̂)`
+clipped away from 0 and 1. Anything else is a `TypeError` at coercion, before
+any margin is fitted: an uncalibrated `decision_function` score is on an
+arbitrary scale, so `Φ` applied to it is not a probability and no diagnostic
+can detect the mismatch. Wrap such an estimator in a calibrator first
+(`CalibratedClassifierCV`, or `SVC(probability=True)`).
+
+The probability itself need not be any good. Inverting the link is exact for a
+calibrated `p̂`, and a miscalibrated one is reported by `calibration_` rather
+than repaired.
+
+`predict_proba` is an interface requirement, not a quality bar, and the gap
+between the two can be large. A fully grown `DecisionTreeClassifier` satisfies
+the contract and emits only exact 0s and 1s, so every index is pinned at the
+clip and Σ is fitted from thresholds that carry no information — on a synthetic
+bivariate probit with true ρ = 0.5 it returned 0.914, with calibration slopes
+of 0.11. The same tree at `min_samples_leaf=50` returned 0.362. Neither is
+right, and the contract cannot tell them apart; `calibration_` flagged the
+first and not the second.
 
 ### Presets
 

{multivariate_probit-0.1.0 → multivariate_probit-0.2.0}/docs/ifm.md

@@ -15,6 +15,8 @@ score (attribute `eta_`). Σ is the latent correlation matrix — a *correlation
 matrix, with unit diagonal, not a covariance matrix (attribute
 `correlation_`). Φ and φ are the standard normal CDF and density; Φ_d is the
 d-variate normal CDF. `d` counts outcomes, `n` counts observations.
+[What Sigma is conditional on](#what-sigma-is-conditional-on) splits η_j into a
+fitted and an ideal version, and says so locally; nowhere else does.
 
 ## What IFM is
 
@@ -175,9 +177,14 @@ Pairwise estimates carry no such constraint — each ρ_jk is fitted in isolatio
 so the assembled matrix can fail to be positive definite when d ≥ 3. It is
 projected onto the nearest correlation matrix by Higham's (2002) alternating
 projections, with a small eigenvalue floor so the result is strictly positive
-definite and safe to Cholesky-factor for sampling. In practice the projection
-is a no-op unless the pairwise estimates are genuinely contradictory or the
-sample is small.
+definite and safe to Cholesky-factor for sampling.
+
+How often this engages depends entirely on the data. On the UCI credit study it
+never did — Σ stayed well conditioned throughout. On multi-label benchmark data
+the smallest eigenvalue hit the floor in 11 of 12 fits, so the projection was
+doing real work almost every time
+([studies/mulan-multilabel.md](studies/mulan-multilabel.md)). Treat it as an
+active part of the estimator at larger d, not a formality.
 
 ## Why cross-fitting is required
 
@@ -220,7 +227,8 @@ them distinct:
 - **Cross-fitted margins leave a residual downward bias.** An out-of-fold index
   still carries genuine prediction error, and noise in a regressor attenuates
   the correlation measured through it — classical errors-in-variables. In the
-  table, cross-fit estimates land at 0.376 and 0.340 against a true 0.6.
+  table, cross-fit estimates land at 0.376 and 0.340 against a true 0.6. The
+  algebra is in the next section, as Gap B.
 
 So cross-fitting trades a large upward bias for a smaller downward one. Treat a
 fitted correlation as a **floor** on the true dependence when the margins are
@@ -228,6 +236,127 @@ only moderately predictive; the gap closes as the margins get sharper. Nothing
 in the estimator corrects for the second effect, and correcting it would
 require knowing the margins' prediction error on the latent scale.
 
+## What Sigma is conditional on
+
+Step 4 takes the fitted index as given and evaluates
+`P(Y_j = 1, Y_k = 1 | x) = Φ_2(η_j, η_k; ρ_jk)`. That is valid only if the
+index it is handed satisfies
+
+```
+P(Y_j = 1 | x) = Φ( η_j(x) )    for all x
+```
+
+Two distinct things separate the fitted index from the truth, and **they are
+not the same kind of defect**. Write η*_j for the index a fully specified model
+would use, η_j for the ideal index given only the features this model sees,
+
+```
+η_j(x) = Φ⁻¹( P(Y_j = 1 | x) )
+```
+
+and η̂_j for the one that was actually fitted. Elsewhere in this file η_j is
+the index the estimator works with — `eta_`, the fitted one. This section is
+the one place the three are separated, because the difference between them is
+the subject.
+
+### Gap A — the estimand moves
+
+The features and the functional form may omit determinants of the outcome.
+Projecting the full-information index onto the fitted one,
+
+```
+η*_j = c_j η_j + b_j + w_j,    w_j independent of η_j,   Var(w_j) = v_j
+```
+
+The omitted part w_j joins the latent error, so `w_j + e_j` has variance
+`1 + v_j`. Dividing through to restore the unit diagonal the model requires,
+the correlation stage two can recover is
+
+```
+ρ_recovered = [ ρ_jk + Cov(w_j, w_k) ] / sqrt( (1 + v_j) (1 + v_k) )
+```
+
+**This is not an estimation error.** A margin calibrated with respect to x
+satisfies the display above by construction, and Σ then measures dependence
+*conditional on x*, with the omitted shared variation correctly counted as part
+of it. That is a well-posed quantity, and often the one a caller wants. It is
+simply not the structural correlation of a fully specified model.
+
+The two terms pull opposite ways. `Cov(w_j, w_k) > 0` — margins missing the
+*same* thing — raises ρ_recovered, with no bound and no fixed sign in general;
+`v_j > 0` shrinks whatever the numerator is. The denominator has been checked
+against known v on synthetic draws; the numerator has not
+([studies/margin-gaps.md](studies/margin-gaps.md)).
+
+Nothing can correct this, and no diagnostic can detect it. The marginal law of
+(Y_j, η̂_j) depends on c_j and v_j only through `c_j / sqrt(1 + v_j)`: a margin
+that is correctly scaled but incomplete and one that is over-dispersed but
+complete produce identical marginal data while implying different Σ. The
+information is not in the data being fitted, at any level of flexibility.
+
+### Gap B — a real bias
+
+The fitted index also differs from the ideal one by finite-sample estimation
+error and by miscalibration of the classifier. This is **different algebra, not
+the same mechanism at a different stage**. Write
+
+```
+η̂_j = η_j + u_j,    Var(u_j) = τ_j²,   Var(η_j) = σ_j²
+```
+
+Here u_j is *part of* η̂_j — the estimator conditions on the noisy index rather
+than on a clean one perturbed afterwards — so this is classical measurement
+error, not the Berkson form of Gap A. The reliability ratio is
+
+```
+λ_j = σ_j² / (σ_j² + τ_j²)   < 1
+```
+
+with `E[η_j | η̂_j] = λ_j η̂_j + (1 - λ_j) m_j` and residual variance
+`λ_j τ_j²`. Substituting as before, and for estimation errors independent
+across margins,
+
+```
+ρ_recovered = ρ_jk / sqrt( (1 + λ_j τ_j²) (1 + λ_k τ_k²) )
+```
+
+This is a genuine downward bias — u_j is no part of the conditional estimand —
+and it is the residual attenuation the previous section describes. It is
+derivable rather than empirical.
+
+### The calibration slope sees exactly one of them
+
+After step 3 the cross-fitted η̂ and the labels are both in hand, so a
+probit of Y_j on η̂_j costs one one-dimensional fit per outcome and no extra
+inner-model fits. Its slope is the **calibration slope** of prognostic-model
+validation (Cox), reported as `calibration_`, and what it estimates is
+`λ / sqrt(1 + λ τ²)`. That is the reliability of the fitted index, which is
+precisely the quantity separating the two gaps:
+
+| | calibration slope | Σ |
+| --- | --- | --- |
+| Gap A (omitted signal) | exactly 1 | moves, legitimately |
+| Gap B (estimation error) | strictly below 1 | biased down |
+
+Two consequences follow, and both matter more than the number itself:
+
+- A quiet diagnostic is **not** evidence that Σ is trustworthy. It rules out
+  one of the two mechanisms, and not the one that moves Σ furthest. On
+  synthetic Gap A draws the slope holds at 1.00 while ρ falls by a factor of
+  three ([studies/margin-gaps.md](studies/margin-gaps.md)).
+- A slope far *above* 1 is a third thing again: the index has absorbed the
+  noise of the rows it is being scored on, so the labels look more predictable
+  than the index admits. That is the memorisation signature cross-fitting
+  exists to remove.
+
+Neither gap is corrected. Gap A cannot be, for the identifiability reason
+above. Gap B could be, since the slope estimates the very reliability that
+attenuates Σ — but the slope is itself estimated, dividing by it amplifies its
+error into Σ, and the result would be a point estimate with no standard error
+to say how far to trust it. Correcting one gap while the other stays silent
+would make `correlation_` harder to interpret, not easier. Report both, correct
+neither. See [limitations.md](limitations.md).
+
 ## Why not full joint MLE (FIML)
 
 The other classical estimator for the same model is FIML: optimize the marginal
@@ -276,6 +405,16 @@ and rejected, each variant for a specific, empirically confirmed reason:
   raw-Y and the correct value, since removing a genuinely positive
   shared-predictor contribution pulls the number down further.
 
+- **Rank-transforming the predicted probabilities first** — empirical CDF per
+  margin, then Φ⁻¹, then Pearson. This is a monotone reparameterisation of the
+  first bullet and inherits its verdict: measured against arm (b) on the same
+  cross-fitted indices, the rank step moves the answer by 0.003 on average and
+  never more than 0.011. What the number tracks is the overlap between the
+  margins' predictors, not ρ. On synthetic draws with a true ρ of 0 and 60%
+  shared index variance it returns 0.58; with a true ρ of 0.5 and disjoint
+  predictors it returns 0.02
+  ([studies/index-correlation-shortcut.md](studies/index-correlation-shortcut.md)).
+
 All three are linear correlation measures applied to a relationship that is
 nonlinear by construction (a threshold on a latent Gaussian). Only the
 maximum-likelihood approach above, working through Φ, correctly inverts that
@@ -288,65 +427,18 @@ support, and nothing constrains the result to be consistent with the marginals.
 
 ## Validation on real data
 
-Everything above was developed against synthetic draws, where the true Σ is
-known. The claim that matters most in practice — that the composite pairwise
-objective is a legitimate substitute for the full likelihood — was checked on
-the UCI *Default of Credit Card Clients* data (Yeh & Lien, 2009): 30,000
-clients, three binary outcomes (any repayment delay in September, July and
-April 2005, i.e. `PAY_0`, `PAY_3`, `PAY_6` > 0), five demographic predictors
-(`LIMIT_BAL`, `SEX`, `EDUCATION`, `MARRIAGE`, `AGE`), an 80/20 split and
-`cv=5`. Outcome prevalence was 22.8 / 14.0 / 10.2 percent. The dataset is not
-redistributed with this library.
-
-Both modes were run on identical margins — same inner model, same seed, same
-folds — so the only thing varying is stage two.
-
-Fitted correlations (ρ_12, ρ_13, ρ_23):
-
-| inner | joint | pairwise | max entrywise difference |
-| --- | --- | --- | --- |
-| linear | 0.669, 0.523, 0.682 | 0.673, 0.535, 0.690 | 0.012 |
-| xgboost | 0.655, 0.510, 0.667 | 0.661, 0.524, 0.676 | 0.014 |
-
-Pairwise came out slightly higher in every entry — a small systematic offset,
-not noise.
-
-Cost of stage two alone, on the same cross-fitted η (30,000 rows, d = 3):
-
-| inner | pairwise | joint | ratio |
-| --- | --- | --- | --- |
-| linear | 0.53 s | 60.3 s | 114x |
-| xgboost | 0.52 s | 45.6 s | 88x |
-
-Held-out mean joint log-likelihood:
-
-| inner | joint | pairwise | difference |
-| --- | --- | --- | --- |
-| linear | -1.09124 | -1.09131 | 0.00007 nats/row |
-| xgboost | -1.08451 | -1.08461 | 0.00010 nats/row |
-
-Per-row `P(all three late)` differed between modes by 0.001 on average, 0.0026
-at worst. Marginal AUC, log-loss and Brier are identical across modes by
-construction, since the margins are stage one.
-
-An independent earlier tetrachoric/Gaussian-copula fit on the same data found
-correlations in the 0.51-0.66 range, with AUC 0.72, log-loss 0.173 and Brier
-0.043 for the joint event "late in all three months". Both modes reproduce it:
-correlations 0.510-0.655, and for that same joint event AUC 0.7224, log-loss
-0.1827, Brier 0.0458.
-
-**Conclusion.** At d = 3 with moderate positive correlations, `"pairwise"`
-gives up about 1e-4 nats/row of held-out likelihood and saves two orders of
-magnitude of fitting time. That is a strong result for the composite objective,
-but it is evidence from one regime only: Σ was well conditioned throughout
-(smallest eigenvalue 0.27 or above), so the projection step never engaged, and
-nothing here speaks to large d, near-singular Σ, or strongly mixed-sign
-correlations — the settings where a composite likelihood is most likely to
-diverge from the full one.
-
-Note also what this study does *not* establish. Cross-fitting was used
-throughout, so these runs assume the case made above rather than retesting it;
-the in-sample bias measurement remains synthetic.
+The composite pairwise objective was checked against the full likelihood on the
+UCI *Default of Credit Card Clients* data: 30,000 clients, three binary
+repayment-delay outcomes, five demographic predictors. At d = 3 with moderate
+positive correlations, `"pairwise"` gives up about 1e-4 nats/row of held-out
+likelihood and saves two orders of magnitude of fitting time, and both modes
+reproduce an independent tetrachoric fit on the same data.
+
+That is evidence from one regime only — Σ well conditioned throughout, so the
+projection step never engaged — and it validates the *objective*, not Σ itself,
+since the true Σ is unknown there. Numbers, configuration, the sampling noise
+floor and the full list of what it does not establish are in
+[studies/uci-credit.md](studies/uci-credit.md).
 
 ## Computational cost
 

{multivariate_probit-0.1.0 → multivariate_probit-0.2.0}/docs/implementation.md

@@ -46,7 +46,8 @@ Drezner-Wesolowsky form of Plackett's identity, and Φ_d for d ≥ 3 by Genz's
 recursive conditioning down onto it. Both are vectorised over observations and
 accept a `(d, d, n)` stack so the correlation matrix may vary by row.
 
-`scipy.stats.multivariate_normal.cdf` was deliberately not used:
+`scipy.stats.multivariate_normal.cdf` is not the default, though it can be
+selected with `evaluator="scipy"` (see [api.md](api.md#evaluators)):
 
 - It is quasi-Monte-Carlo, so it is **stochastic**. Noise inside an optimizer
   objective is corrosive — Nelder-Mead cannot distinguish a genuine likelihood
@@ -56,8 +57,9 @@ accept a `(d, d, n)` stack so the correlation matrix may vary by row.
 - It is about **1e-5** accurate where the closed-form bivariate case reaches
   about 1e-12.
 
-SciPy's version does appear in the test suite, as an independent cross-check of
-the hand-rolled evaluator.
+Selecting it is the caller's speed/accuracy decision; it is the only route to
+joint probabilities once d is too large for quadrature. It also appears in the
+test suite, as an independent cross-check of the hand-rolled evaluator.
 
 ### Cross-fitting
 
@@ -78,6 +80,7 @@ Optimizers and primitives only:
 
 - `scipy.optimize.minimize` (Nelder-Mead) — the joint Σ fit
 - `scipy.optimize.minimize_scalar` (bounded Brent) — each pairwise ρ
+- `scipy.stats.multivariate_normal.cdf` — Φ_d, only with `evaluator="scipy"`
 - `scipy.stats.norm` — Φ, φ, Φ⁻¹
 - `numpy.polynomial.legendre.leggauss` — quadrature nodes and weights
 - `numpy.linalg` — `solve`, `eigh`, `cholesky`