Feature: tl.infer_proteoform_groups()

[idf-io]

Summary

Adds pr.tl.infer_proteoform_groups(), a single entry point for proteoform group inference. Users currently have to chain four pr.tl COPF calls with the right arguments; this wrapper runs the currently recommended approach in one call. It is deliberately dynamic: the default method tracks whatever approach is recommended and may change in future releases, so the docstring tells users to pass method explicitly for reproducible results.

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) — pending; pre-commit and pre-push hooks passed locally

---

✨ Feature

What it adds:

pr.tl.infer_proteoform_groups(adata, method="copf", *, batch_key=None, min_score=0.1, min_adj_pval=0.1, inplace=True, verbose=False)

method="copf" (the current default) is equivalent to:

pr.tl.pairwise_peptide_correlations(adata, batch_key=batch_key)
pr.tl.peptide_dendograms_by_correlation(
    adata, method="agglomerative-hierarchical-clustering"
)
pr.tl.peptide_clusters_from_dendograms(
    adata, n_clusters=2, min_peptides_per_cluster=2
)
pr.tl.proteoform_scores(adata, min_score=min_score, min_pval_adj=min_adj_pval)

Methods are registered in a METHODS dict in proteopy/tl/proteoform_group_inference.py, so a future approach is one new function plus one entry, and changing the recommendation means editing DEFAULT_METHOD. Before running, the function rejects protein-level data, an unknown method, a batch_key missing from .obs, non-numeric thresholds, and a min_adj_pval outside (0, 1].

Example usage:

import proteopy as pr

pr.tl.infer_proteoform_groups(
    adata,
    method="copf",
    batch_key="multiplex_batch",
    min_score=0.1,
    min_adj_pval=0.1,
)
adata.var.loc[adata.var["is_proteoform"] == 1, "protein_id"]

• Follows the AGENTS.md function and module conventions (check_proteodata on entry and exit, inplace, verbose)
• Tests added for the new behavior (tests/tl/test_proteoform_group_inference.py, 16 tests)
• Numpydoc docstring with an example
• Added to the Sphinx API docs (docs/sphinx/source/api/tl.rst)
• Relevant tutorial notebooks updated, or none affected — none changed; tutorials still call the individual COPF steps
• Algorithm reimplemented from published work: Bludau et al. 2021 cited in a References section. The wrapper adds no new algorithm; tests assert its .var and .uns output equals running the four COPF steps by hand, with and without batch_key

---

Notes for reviewers

• Docstring wording on the dynamic default is the main thing to check: does the warning make clear enough that relying on the default is not reproducible across releases?
• method is positional (infer_proteoform_groups(adata, "copf") works); the other parameters are keyword-only.
• The min_adj_pval docstring does not mention the (0, 1] range that _validate_args enforces.
• Pre-existing bug found, not fixed here: pairwise_peptide_correlations_ in proteopy/tl/copf.py joins peptide pairs as "pepA_pepB" and splits on _, so any peptide_id containing an underscore raises ValueError: Columns must be same length as key. The test fixture uses sequence-like IDs to avoid it; it should get its own fix.
• Sphinx docs were not built locally, so the rendering of the warning block and reference is unchecked.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 proteopy | 🛠️ Build #35090436 | 📁 Comparing 5be726d against latest (3ab0460)

  🔍 Preview build  

6 files changed · + 2 added · ± 4 modified

+ Added

• api/generated/proteopy.tl.infer_proteoform_groups.html
• _modules/proteopy/tl/proteoform_group_inference.html

± Modified

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