v1.11 — Joint (correlation-preserving) sampling

v1.11 — Joint (correlation-preserving) sampling

gsua_dmatrix gains 'Method','Joint', which draws whole parameter vectors from an accepted-estimate ensemble instead of sampling each parameter independently inside its own interval.

For a model with parameter confounding, the marginal methods leave the identified manifold, so any uncertainty band built from them reports variation the inference does not actually contain. This is the condition gsua_covmetric already flags as cost_band far above cost_data — a diagnostic the toolbox shipped without a corresponding fix until now.

What's new

• gsua_dmatrix(Tia, N, 'Method','Joint') — the pool is recovered automatically from Tia.Est, which gsua_ia already stores: row-aligned with the table and already cost-filtered, dominant-cluster-restricted and outlier-cleaned. An explicit 'Pool' overrides it.
• 'JointType' selects Bootstrap (default), SmoothBootstrap (variance-corrected kernel, for new points near the manifold) or Gaussian (mean + covariance via eigendecomposition, so a rank-deficient covariance still works).
• Also fixes the CI-of-the-median problem. gsua_ia leaves T.Range as a distribution-free confidence interval of the median of the pool, which narrows as the pool grows and is not the spread of values consistent with the data — measured at 14× narrower than the pool on the analytic control. Joint draws inherit the pool's own spread instead. 'Clip' therefore defaults to none: clipping back to Tia.Range would reimpose exactly that narrowness.
• Small-pool guard. A pool below 'MinPoolN' (default 5) is refused with a warning and falls back to marginal sampling. Two points always correlate at exactly ±1, so such a band would be confidently wrong rather than approximately right.
• New 'Seed', 'Bandwidth' and 'MinPoolN' options; functionSignatures.json updated for tab completion.

Why Bootstrap is the default

On an analytic control whose identified manifold is the known hyperbola a*b = c, the Gaussian mode reproduces the pool's correlation coefficient almost exactly (−0.906 vs the pool's −0.913) and still leaks 3.4e-1 off the manifold, against bootstrap's 1.2e-7. Matching pairwise linear correlation is not sufficient on a curved ridge. gsuaDmatrixJointManifoldTest pins this, so the default's justification fails loudly if it ever stops holding.

Packaging fix

The .mltbx was bundling previous release artifacts inside itself — v1.10 shipped 15.5 MB containing releases 1.7/1.8/1.9, the entire Python port, __pycache__, the test suite and local editor config, because ToolboxOptions does not apply the exclude filters declared in the .prj. The file list and path metadata are now filtered explicitly to the six directories the project actually declares as toolbox content. This release is 2.8 MB, and installs with no warnings.

Python port

Mirrored as design_matrix(model, n, "joint", ...). IdentifiabilityResult gains estimates_used, since it was discarding the pool it summarized. Pool orientation there is (n_pool, Np), matching PEResult.x rather than importing MATLAB's Np x nPool layout.

Validation

python/paper_experiments/joint_vs_marginal_bands.py validates this on three rungs — an analytic control, Bertozzi_PNAS2020 (real COVID case counts, documented 2-of-3 non-identifiability) and Boehm_JProteomeRes2014 (two basins; its dominant basin is 2 vectors, and the guard correctly fires). Two negative results are reported rather than glossed: neither dataset reproduces the band mis-centering seen on the dengue–Wolbachia case that motivated the request, and a parameter-uncertainty band is not a prediction interval — observation noise is gsua_noisefloor's job, and the two features compose.

35 new tests (28 MATLAB, 7 Python). Full suites: 49 MATLAB, 192 Python, all passing.