Feature: pp.var_consistency() and pp.filter_by_var_consistency()

[idf-io]

Summary

Fractionation and other profile experiments need a way to drop peptides
whose profile is not reproducible across batches/replicates before COPF
correlates them. Without it, noise drives the proteoform calls. This
adds pr.pp.var_consistency() and pr.pp.filter_by_var_consistency(),
ported from the exp009 proteoform tutorial and generalised: they work
with any batch column and any combination of grouping columns. Before,
replicate, condition and fraction columns were hardcoded.

Related issues

None

General checklist

• Branch name and commit subjects follow the repo conventions
• HISTORY.md updated under [Unreleased]
• CI is green (flake8, pylint, pytest). Locally: flake8, pylint and
  the pre-commit/pre-push hooks pass; CI pending. No new tests.

---

✨ Feature

What it adds:

• pr.pp.var_consistency(adata, batch_key, group_by, min_groups=4, ...)
  • For each variable, builds one profile per batch across the
    group_by groups. A list such as ["condition", "fraction"] uses
    every combination of values as a group. Samples sharing a batch and
    a group are averaged.
  • Computes the Pearson correlation for every pair of batches. A
    correlation is NaN if fewer than min_groups groups are shared or
    either profile is constant.
  • Stores <key_added>_{median,min,mean,n_valid} in .var, and the
    per-pair correlations and shared-group counts in
    .varm["<key_added>_pairs"]. key_added defaults to
    <batch_key>_corr.
• pr.pp.filter_by_var_consistency(adata, threshold, key=None, ...)
  keeps the variables with score >= threshold. If key is None, it
  uses the single .var column ending in _corr_min, and raises if
  there are none or several. remove_na controls whether variables
  with an undefined score are dropped.

Example usage:

import proteopy as pr

pr.pp.var_consistency(
    adata,
    batch_key="replicate",
    group_by=["condition", "fraction"],
)
pr.pl.ann_hist(
    adata,
    x="replicate_corr_min",
    vline={"value": 0.25, "text": "Threshold = 0.25"},
)
pr.pp.filter_by_var_consistency(adata, threshold=0.25, verbose=True)

• Follows the AGENTS.md function and module conventions
  (check_proteodata on entry/exit, sparse input warned and densified,
  inplace, key_added, verbose, validation helpers)
• Tests added for the new behavior. Not included in this PR on
  purpose; to follow in a separate PR. The checks run instead are
  listed below.
• Numpydoc docstring with an example
• Added to the Sphinx API docs (docs/sphinx/source/api/pp.rst).
  The Sphinx build itself was not run.
• Relevant tutorial notebooks updated, or none affected. No tutorial
  under docs/tutorials/ uses these functions yet.

Notes for reviewers

• Vectorised implementation (_pairwise_profile_corr). The original
  looped over variables and batch pairs with pandas. This version
  computes one masked, column-wise Pearson correlation per batch pair in
  numpy. A profile counts as constant when the minimum and maximum of
  its shared values are equal. This exact test matches the original
  nunique() > 1 check and is not affected by rounding.
• Checked against the original on the exp009 dataset (PXD034969,
  60,698 peptides, 3 replicates × 2 conditions × 6 fractions):
  • all .var summaries and .varm pairs agree with the original
    within 8e-16
  • both remove_na settings keep the same 48,279 peptides
  • runtime fell from about 220 s to 0.1 s
  • sparse input warns and matches dense input
  • changing the order of the group_by columns, or passing one combined
    column, gives identical results
  • each validation error case raises
  • the exp009 notebook runs end to end with these functions
• Zeros count as values, not as missing, as in the original. Users
  whose zeros mean "not measured" should convert them to NaN first; the
  docstring says this.
• Missing values in batch_key / group_by raise an error. A
  plain groupby would drop those samples without saying so.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 proteopy | 🛠️ Build #35094604 | 📁 Comparing 899c990 against latest (08d8bbf)

  🔍 Preview build  

7 files changed · + 3 added · ± 4 modified

+ Added

• api/generated/proteopy.pp.filter_by_var_consistency.html
• api/generated/proteopy.pp.var_consistency.html
• _modules/proteopy/pp/var_consistency.html

± Modified

• changelog.html
• genindex.html
• _modules/index.html
• api/pp.html

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e9d20ec1e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".