docs: fix ten docstring/code mismatches in multivariate/experiments

[kgdunn]

Summary

Docstring-only corrections to bring the documented behaviour into line with what the code actually does across the multivariate and experiments modules. No runtime behaviour changes - several of the drifts point at genuine bugs that the maintainer may want to fix in a follow-up PR, and those are called out below rather than being silently patched here.

Fixes in this PR

1. src/process_improve/experiments/designs_response_surface.py (~line 46) - dispatch_ccd. Docstring claimed a numeric alpha sets alpha directly, but the cube="full" branch (lines ~101-103) silently drops the numeric value and forces alpha_str = "orthogonal". Clarified that numeric alpha is honoured only under cube='fractional'.
2. src/process_improve/multivariate/_pca.py (~line 1076) - PCA.select_n_components. Added the missing return_consensus: bool = False entry to Parameters and described the extra Bunch keys (minka_n_components, parallel_analysis_n_components, consensus, consensus_counts).
3. src/process_improve/multivariate/_pca.py (~line 926) - PCA.parallel_analysis. Dropped the incorrect "(matches :meth:minka_mle)" claim and noted that minka_mle centres only, so the two do not share preprocessing when scale=True.
4. src/process_improve/multivariate/_pca.py (~line 224) - PCA.__init__. Changed n_components : int to n_components : int or None, default=None and described the None / clamp-with-warning behaviour that fit() implements.
5. src/process_improve/multivariate/_pls.py (~line 152) - PLS.__init__. Same fix as Check that all entries in the level list are accounted for. #4: n_components : int or None, default=None.
6. src/process_improve/multivariate/_tpls.py (~line 355) - TPLS.fit. Changed the X type from {dictionary of dataframes} to DataFrameDict, because fit raises TypeError for a plain dict; cross-referenced the class-level example.
7. src/process_improve/multivariate/_preprocessing.py (~line 161-190) - center() / scale(). Reworded the "Missing values" bullets: the default np.mean / np.std reducers do not skip NaN reliably (a NaN in a column propagates NaN into the returned centring / scaling vector). Recommended np.nanmean / np.nanstd for NaN-aware behaviour.
8. src/process_improve/multivariate/_limits.py (~line 79-93) - spe_calculation. Made the Returns block explicit: the returned value is on the sqrt-of-sum-of-squared-residuals scale (directly comparable to entries of model.spe_), not the squared scale.
9. src/process_improve/multivariate/_pca.py (~line 103-105) - _pca_ekf_press. Corrected "Per-cell PRESS" to "Total PRESS per component count (sum of squared cell-residuals across all folds, averaged over n_repeats)".
10. src/process_improve/multivariate/_limits.py (~line 183-185) - ellipse_coordinates. Made the scaling_factor_for_scores Parameters entry explicit: the parameter defaults to None but passing None raises AssertionError.

Bumped version in pyproject.toml to 1.54.1 (PATCH, docs-only), synced CITATION.cff (1.54.1, 2026-07-17), and added an entry to the ## [Unreleased] section of CHANGELOG.md.

Follow-up (not in this PR)

These are behavioural fixes, out of scope for a docs-only PR - opening as maintainer follow-ups:

• Finding Add input checks to "grocery" simulation #1 code fix. dispatch_ccd(cube='full', alpha=<numeric>) silently ignores the numeric value; the maintainer may want to forward it into the pyDOE3 call rather than only documenting the current drop.
• f_std/f_iqr/f_range/... don't filter to [f_names] like f_mean does in the sensory descriptive family - output columns leak the full covariate frame rather than the requested subset.
• ttest_paired Bunch key Standard deviation is actually the standard error of the mean (SEM), not the standard deviation. Either rename the key (breaking change) or return both.

Test plan

• ruff check . on the touched files (no lint impact - docstring changes only).
• uv run pytest - to be run in CI; no test changes made because no runtime behaviour changed.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!