Skip to content

VBPCApy 0.4.6 release validation

This patch supplies encoding-aware categorical scores (#266, PR #271) and training-only preprocessing for raw variable-cell CV (#267, PR #272). Dense one-hot centering now stays fixed when transforming new observations. The trade-study installation recipe is portable (#269, PR #270).

The numerical fitting implementation and recommended options for a fixed encoded matrix are unchanged from 0.4.5. Raw-table CV changes which values fit each transform; that methodology can change fitted models and selected capacities. The Gaussian reconstruction still supplies approximate clipped, normalized category probabilities, rather than a categorical likelihood.

Local validation

From a clean checkout, with Eigen installed:

uv sync --extra dev --extra data --extra plot --extra docs
just ci
just release-check
uv run python scripts/check_release_metadata.py --tag v0.4.6
just docs
just example-raw-cv
just build-check

The just bench-study-full, just bench-study-summary, and just bench-study-paper recipes named in CONTRIBUTING.md are absent from the current justfile. Use the commands above and the fitting check below for this patch; just --list lists the available benchmark recipes.

Reproduce the fitting check

scripts/check_fitting_identity.py captures six seeded fits (tall, wide and square matrices, complete and 30% MCAR observations, ranks one and two) under the registered pp-eigentest policy. It also captures two legacy full-one-hot CV sweeps over capacities 0, 1 and 2. Each snapshot contains fitted posterior arrays, reconstruction, ARD state, noise/RMS, iteration/convergence state, CV decisions and score summaries. The paired check compares 94 arrays.

Obtain the same immutable policy module for both environments:

git -C ../pp-eigentest show \
  cfe25775b7485b98a092287f1d7743bc0401d3a7:analysis/eigentest_study/fitting_policy.py \
  > /tmp/vbpca-fit-policy.py

Build 0.4.5 and the candidate wheels with the same Python/compiler/Eigen configuration. Install each wheel in a separate environment with identical NumPy and SciPy versions. The snapshot commands must import the intended installed package; unset any source-checkout PYTHONPATH. For example, with those environments at /tmp/vbpca-045 and /tmp/vbpca-046:

export OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1
env -u PYTHONPATH /tmp/vbpca-045/bin/python scripts/check_fitting_identity.py \
  snapshot --policy-module /tmp/vbpca-fit-policy.py --output /tmp/baseline.npz
env -u PYTHONPATH /tmp/vbpca-046/bin/python scripts/check_fitting_identity.py \
  snapshot --policy-module /tmp/vbpca-fit-policy.py --output /tmp/candidate.npz
env -u PYTHONPATH /tmp/vbpca-046/bin/python scripts/check_fitting_identity.py \
  compare --baseline /tmp/baseline.npz --candidate /tmp/candidate.npz \
  --output /tmp/fitting-identity.json

Keep the NPZ/JSON pairs and compiler/environment records together. The snapshot records version/source, policy SHA-256, resolved options, seeds, numerical dependency versions and thread environment. The comparison rejects protocol drift, missing/empty field sets, dtype/shape changes and any byte difference, and exits nonzero on failure. Confirm the reported versions are 0.4.5 and 0.4.6 and the sources are the intended installed distributions. Byte identity depends on a controlled build/runtime; comparisons across compilers or numerical libraries need separate interpretation.

These are bounded fixed-input compatibility checks. They do not establish identity for every possible input or equivalence of different preprocessing methods. The encoding/raw-CV tests separately check decoded scores, held-out mask preservation, training-only statistics and reuse across capacities.

Run the mixed-data example against the installed candidate outside the checkout:

cp scripts/example_raw_cell_cv.py /tmp/example_raw_cell_cv.py
cd /tmp
env -u PYTHONPATH /tmp/vbpca-046/bin/python example_raw_cell_cv.py

Publication and study adoption

Package, citation, changelog and tag metadata must agree on 0.4.6. The existing publish workflow validates this, builds CPython 3.11–3.14 wheels for Linux x86_64, macOS arm64 and Windows amd64, checks the complete artifact matrix, and then publishes after a GitHub release event. Its manual dispatch builds and checks the artifacts without publishing them.

The pp-eigentest #195 adoption record must retain the paired fitting evidence and define the scoring/preprocessing contract for each #160 arm before updating that study's pin. Ongoing registered studies continue with their existing 0.4.5 source and policy. This release does not select the mixed-type tuning default or register the preprocessing study; those depend on the #176 results.