Signal-ladder API renames, and two real defects the naming proposal missed (2.0.0)

[kgdunn]

Summary

• Rename the permutation-null functions so their names state the question they answer: permutation_q2 -> check_predictive_signal, pipeline_null -> count_discoveries_under_null, discriminate_observational -> find_predictive_descriptors. The "discriminator" vocabulary goes with them (result.relate["discriminator"] -> ["predictive_descriptors"], discriminator_significant -> is_predictive, kwarg discriminator= -> find_predictive=, including on the sensory_analyze_descriptive tool schema). Removed names raise AttributeError naming their replacement, following the precedent in univariate/metrics.py.
• Fix two real naming defects that a review turned up and the original proposal walked past. find_predictive_descriptors claimed in its docstring to apply Benjamini-Hochberg correction; it does not, and never did, the code builds a Westfall-Young max-statistic null as its own inline comment says. And the field carrying that value was named q_value, FDR vocabulary for a family-wise-error-adjusted p-value, while q_value in the sibling associations list of the same result dict genuinely is a BH q-value. One key name, two quantities. It is now p_value_fwer.
• check_predictive_signal takes x and y first and makes fit_predict optional, defaulting to leave-one-out cross-validated PLS on the raw blocks, so each fold derives its own constants rather than inheriting constants computed from the row it is predicting.
• empirical_fdr -> null_to_observed_ratio, with the [0, 1] clip dropped. On pure noise the old field reported a tidy 1.0 for draws where shuffling actually out-found the real response, which is the single most informative reading the function can give. A test now pins that at least one such draw exceeds 1.

Two things the proposal asked for that this does not do

• Its section-5 "defect fix" is dropped. predictable = q2_cv > 0.0 is one of three conjunctive conditions at analysis.py:456, ANDed with a FWER-controlled max-statistic p-value and a jackknife flag, so a loose gate cannot manufacture findings. Its real role is to skip the 199-refit permutation loop. Routing it through a permutation null would have cost roughly 20-46x on the default analyze_descriptive path to fix a problem that is not there. The gate is now documented as the deliberate pre-screen it is.
• permutation_column_null is kept, not deleted. All three stated reasons fail: it answers a block-level question (one multi-response fit, one record per descriptor) that the per-attribute function does not; the vip note it cited condemns counting VIP > 1 exceedances under response permutation, which is not what it does; and a calibration experiment measured it conservative (VIP 1.9%, cv_beta 4.4% against a nominal 5%). It and find_predictive_descriptors now cross-reference each other so the choice between them is explicit.

The cross-attribute multiplicity gap is real (the max-statistic family is rebuilt per attribute, so nothing corrects across them) and is documented, not closed in this PR, since closing it changes results.

This is a breaking release with no deprecation cycle, departing from CONTRIBUTING.md. Deliberate and recorded in the CHANGELOG: the two multivariate names shipped in 1.76.0, one release and one day earlier, so shims would have carried dead weight to 2.0.0 for names nobody could have adopted.

Test plan

• uv run pytest green: 2978 passed, 3 skipped, coverage 94.45% against the 92% gate
• New coverage: the LOO default separates signal from noise, matches an explicit equivalent callable, and clamps an oversized n_components; pre-scaling the blocks does not change the answer; every removed name raises with its replacement on all import surfaces; null_to_observed_ratio equals the raw quotient and exceeds 1 on noise; permutation_column_null is still exported
• uv run ruff check . and uv run ruff format --check . both pass
• uv run mypy src/process_improve passes, 153 files
• uv run sphinx-build docs docs/_build/html -b html -W succeeds, which is where a stale :func: role would have failed CI

Checklist

• Version bumped in pyproject.toml to 2.0.0 (MAJOR: public names removed), with CITATION.cff set to the identical version and date in the same commit
• Tests added or updated where relevant
• ruff check . passes
• CHANGELOG.md updated

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!