docs: fix a batch of docstring/code inconsistencies (no behaviour change) by kgdunn · Pull Request #472 · kgdunn/process-improve

kgdunn · 2026-07-24T07:26:41Z

Summary

Docstring-only pass across multivariate, batch, experiments, visualization, and config modules. No runtime behaviour is changed.
Each edit makes the docstring describe the code that is actually there today; the underlying code is left untouched.
Where a finding is a real code bug rather than a docstring drift, the docstring is tightened to describe the current behaviour and the bug is flagged below for maintainer follow-up.
PATCH version bump to 1.59.1 with matching CITATION.cff and CHANGELOG.md updates.

Fixes

#	File:line	Function / attribute	Change
1	`src/process_improve/multivariate/plots.py:575`	`t2_plot` (`with_a` param)	Was described as showing "the SPE after this number of model components"; corrected to say Hotelling's T2.
2	`src/process_improve/multivariate/_preprocessing.py:161`	`center`	Docstring said "skipping any missing data", but the default `func=np.mean` propagates NaN. Reworded to describe the actual NaN-propagating behaviour and to point at `np.nanmean` when NaN-skipping is desired.
3	`src/process_improve/multivariate/_preprocessing.py:187`	`scale`	Same fix as `center`: `np.std` propagates NaN. Reworded and pointed at `np.nanstd`.
4	`src/process_improve/multivariate/_resampling.py:49`	`Resampler.__init__`	Docstring said `use_jackknife`, `bootstrap_rounds`, `fraction_excluded` are mutually exclusive, but the guard only fires when all three are set. Reworded to describe the actual guard and to note the `resample()` precedence (jackknife > bootstrap > fractional). See "Bugs flagged for maintainer" below.
5	`src/process_improve/config.py:138`	`Settings` class docstring	Said to "call `override()` to set a single knob"; no such method exists. Now points at the per-knob property setters and describes `reload()` / `as_dict()`.
6	`src/process_improve/visualization/themes.py:68`	`DEFAULT_THEME` attribute	Attribute doc claimed the theme is applied on import, but the module docstring explicitly says import does not change the Plotly default. Reworded to match: `DEFAULT_THEME` is the theme this library's own plots request explicitly; use `set_theme()` to opt a whole session in.
7	`src/process_improve/batch/data_input.py:173`	`melted_to_wide`	Unimplemented; validates the batch id column and returns `{}`. Added a `.. warning::` admonition marking it as a stub. See "Bugs flagged for maintainer".
8	`src/process_improve/batch/features.py:625`	`f_crossing`	Docstring promised per-phase crossings via `phase_col`, but the implementation hard-wires `phase_col=None` when calling `_prepare_data`. Added a note that `phase_col` is currently ignored. See "Bugs flagged for maintainer".
9	`src/process_improve/experiments/designs_response_surface.py:30`	`dispatch_ccd`	Docstring said any numeric `alpha` sets the axial distance directly, but under `cube="full"` numeric values are coerced to the pyDOE3 `"orthogonal"` alpha. Split the wording: numeric alpha honoured under `cube="fractional"`, silently discarded under `cube="full"`. See "Bugs flagged for maintainer".
10	`src/process_improve/multivariate/_pca.py:1010`	`PCA.select_n_components`	`return_consensus: bool = False` was missing from Parameters; the extra Bunch keys (`minka_n_components`, `parallel_analysis_n_components`, `consensus`, `consensus_counts`) were missing from Returns. Both added.
11	`src/process_improve/multivariate/_pca.py:892`	`PCA.parallel_analysis`	Docstring said `scale=True` "matches `minka_mle`", but `minka_mle` only mean-centres while `parallel_analysis(scale=True)` also unit-variance-scales via `MCUVScaler`. Corrected.
12	`src/process_improve/multivariate/_tpls.py:557`	`TPLS.diagnose`	Example built `new_data` as a plain `dict`, but the method raises `TypeError` unless the argument is a `DataFrameDict`. Wrapped the example.

Bugs flagged for maintainer

These are real code bugs rather than docstring drift. This PR leaves the code alone and only makes the docstrings describe the current (buggy) behaviour honestly. Filing them for follow-up:

Resampler.__init__ mutual-exclusion guard is too weak (src/process_improve/multivariate/_resampling.py:84). The guard raises only when use_jackknife and bootstrap_rounds > 0 and fraction_excluded > 0.0 are all set simultaneously. Pairwise conflicts (e.g. use_jackknife=True, bootstrap_rounds=100) slip through and are silently resolved by resample()'s ordering (jackknife > bootstrap > fractional). Suggested fix: count how many of the three modes are active and raise when the count is greater than one.
melted_to_wide is a silent stub (src/process_improve/batch/data_input.py:173). Callers get back an empty dict with no warning. The intended pivot implementation is present but commented out. Suggested fix: either finish the implementation (there is a sketch just below the return) or raise NotImplementedError so callers cannot use it accidentally.
f_crossing ignores phase_col (src/process_improve/batch/features.py:663-669). The function accepts phase_col as a parameter but hard-wires phase_col=None on the call to _prepare_data, so the per-phase behaviour promised by the docstring never actually runs. Suggested fix: forward phase_col=phase_col and add tests that cover phased data.
dispatch_ccd silently discards numeric alpha under cube="full" (src/process_improve/experiments/designs_response_surface.py:101-104). The isinstance(alpha, (int, float)) branch sets alpha_str = "orthogonal" and face = "circumscribed", effectively throwing the numeric value away. Callers who pass e.g. alpha=1.68 under cube="full" get an orthogonal design and no warning. Suggested fix: either honour the numeric value (pyDOE3's ccdesign accepts numeric alpha under an appropriate alpha= setting) or raise a ValueError telling the caller that numeric alpha is only supported for cube="fractional".

Test plan

uv run ruff check src/process_improve passes.
uv run ruff format --check on the touched files: no new formatting drift introduced by this PR (the pre-existing repo-wide format drift is unrelated and outside the scope of a docstring-only patch).
No source code was modified; only docstrings, pyproject.toml (version bump), CITATION.cff (version + date), and CHANGELOG.md (entry).
uv.lock was not committed (per repo policy for Claude Code sessions).

Checklist

Version bumped in pyproject.toml (PATCH: 1.59.0 → 1.59.1, docs-only).
CITATION.cff version + date-released synced to 1.59.1 / 2026-07-24.
CHANGELOG.md updated with a 1.59.1 section and its compare-link footer.
No tests added: docstring-only changes with no behaviour change.
ruff check . passes on the touched files.

Generated with Claude Code

https://claude.ai/code/session_019ocQ71UFry6rkJnBNLeQKg

Generated by Claude Code

The parameter description said 'shows the SPE after this number of model components' but t2_plot plots Hotelling's T^2. Reword to match the actual statistic shown.

Both docstrings claimed the defaults (np.mean / np.std) skip missing data, but those functions propagate NaN. Reword to describe the actual behaviour and point callers at np.nanmean / np.nanstd when NaN-skipping is desired.

The docstring said the three mode flags are mutually exclusive, but the __init__ guard only raises when all three are set at once. Document the actual behaviour (all-three-set trigger; resample() prefers jackknife over bootstrap over fractional) so users are not misled by the guarantee. The guard itself is left unchanged; the underlying bug is flagged in the PR body for the maintainer.

Settings has no override() method. Point users at the per-knob property setters (each property has a paired setter) and describe reload() / as_dict() in terms of what they actually do.

The module docstring is explicit that importing themes does NOT set the Plotly default template, but the DEFAULT_THEME attribute docstring contradicted that. Reword to match: DEFAULT_THEME is the theme this library's own plots request explicitly, and set_theme() is the way to change the process-wide default.

The function validates the batch id column and then unconditionally returns an empty dict; the real pivot is commented out beneath. Add a warning admonition so callers do not silently receive an empty result believing they got a reshaped view. Flagged for maintainer follow-up in the PR body.

f_crossing's docstring promised per-phase evaluation via phase_col but the implementation hard-wires phase_col=None when calling _prepare_data, so crossings are computed across the whole batch instead. Add a note to make the current behaviour explicit; the underlying bug is flagged in the PR body for the maintainer.

The docstring implied any numeric alpha sets the axial distance directly, but under cube='full' the code discards numeric values and forces the pyDOE3 'orthogonal' alpha instead. Only cube='fractional' actually honours a numeric alpha. Document the split so callers do not silently get an 'orthogonal' design when they passed a specific number. The behavioural gap is flagged in the PR body for the maintainer.

…note Two docstring drifts in PCA: - select_n_components was missing the return_consensus parameter and the four extra Bunch keys it enables (minka_n_components, parallel_analysis_n_components, consensus, consensus_counts). Document both. - parallel_analysis said scale=True 'matches minka_mle', but minka_mle only mean-centres while parallel_analysis(scale=True) additionally unit-variance-scales via MCUVScaler. Describe the actual behaviour.

The example built new_data as a plain dict, but diagnose() raises TypeError unless the argument is a DataFrameDict. Update the example so the code actually runs.

Docs-only PATCH bump for the docstring-drift fixes across the codebase. CITATION.cff and CHANGELOG.md updated in the same commit per repo policy.

codecov · 2026-07-24T07:29:42Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

claude added 11 commits July 24, 2026 07:20

docs: fix t2_plot with_a docstring (was describing SPE, not T^2)

5139875

The parameter description said 'shows the SPE after this number of model components' but t2_plot plots Hotelling's T^2. Reword to match the actual statistic shown.

docs: fix center/scale NaN behaviour claims in _preprocessing

e068832

Both docstrings claimed the defaults (np.mean / np.std) skip missing data, but those functions propagate NaN. Reword to describe the actual behaviour and point callers at np.nanmean / np.nanstd when NaN-skipping is desired.

docs: replace bogus Settings.override reference with real API

6c5a220

Settings has no override() method. Point users at the per-knob property setters (each property has a paired setter) and describe reload() / as_dict() in terms of what they actually do.

docs: wrap TPLS.diagnose example input in DataFrameDict

ed39924

The example built new_data as a plain dict, but diagnose() raises TypeError unless the argument is a DataFrameDict. Update the example so the code actually runs.

chore: bump to 1.59.1 (docs-only fixes)

c52950c

Docs-only PATCH bump for the docstring-drift fixes across the codebase. CITATION.cff and CHANGELOG.md updated in the same commit per repo policy.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: fix a batch of docstring/code inconsistencies (no behaviour change) - #472

docs: fix a batch of docstring/code inconsistencies (no behaviour change)#472
kgdunn wants to merge 11 commits into
mainfrom
claude/determined-fermat-lt0hp6

kgdunn commented Jul 24, 2026

Uh oh!

codecov Bot commented Jul 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

kgdunn commented Jul 24, 2026

Summary

Fixes

Bugs flagged for maintainer

Test plan

Checklist

Uh oh!

codecov Bot commented Jul 24, 2026

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants