feat(pp): add summarize_peptides_by_neighbourhood_union

HISTORY.md

@@ -7,6 +7,33 @@ and this project adheres to
 
 ## [Unreleased]
 
+### Added
+
+- **Preprocessing** (`pr.pp`): `summarize_peptides_by_neighbourhood_union()`
+  collapses peptides that overlap in the protein sequence, keeping the
+  most abundant member of each group. Peptide positions are resolved
+  from a FASTA in the same call. A reimplementation of CCprofiler's
+  `summarizeAlternativePeptideSequences(topN = 1)`.
+  - groups by positional overlap rather than substring containment, so
+    it sees peptide pairs that overlap without either containing the
+    other, and needs no separate modification-summarisation step
+  - selects the most abundant member instead of aggregating; `top_n`
+    sums the leading members instead, with `keep_less` controlling
+    undersized groups
+  - missing values are deprioritised rather than removed: an
+    incomplete peptide sorts last and loses to any complete
+    competitor, but survives if its group has no complete member
+  - equal totals are resolved by `tie_break_key`, so the result does
+    not depend on input row order; the default sorts non-letters after
+    letters, favouring the unmodified form of an identifier
+  - `on_unknown_protein` and `on_unlocated_peptide` decide whether an
+    unresolvable position raises, skips the peptide, or leaves the
+    position undefined
+  - `.var` is reduced to the peptide-level proteodata columns plus the
+    function's own output, since the surviving row's annotations
+    describe one member rather than the group; `keep_var_cols` carries
+    chosen columns through, aggregated across the group
+
 ### Fixed
 
 - **Datasets** (`pr.datasets`) and **Download** (`pr.download`):

docs/sphinx/source/api/pp.rst

@@ -47,6 +47,7 @@ filtering, normalization, and imputation of proteomics data.
    proteopy.pp.extract_peptide_groups
    proteopy.pp.summarize_modifications
    proteopy.pp.summarize_overlapping_peptides
+   proteopy.pp.summarize_peptides_by_neighbourhood_union
    proteopy.pp.quantify_proteins
    proteopy.pp.quantify_proteoforms
 

proteopy/pp/__init__.py

@@ -7,15 +7,15 @@
     filter_samples_by_category_count,
     remove_zero_variance_vars,
     remove_contaminants,
-    )
+)
 
 from .imputation import (
     impute_downshift,
-    )
+)
 
 from .normalization import (
     normalize_median,
-    )
+)
 
 from .quantification import (
     extract_peptide_groups,
@@ -24,6 +24,10 @@
     quantify_by_category,
     quantify_proteins,
     quantify_proteoforms,
-    )
+)
+
+from .summarize_peptides_by_neighbourhood_union import (
+    summarize_peptides_by_neighbourhood_union,
+)
 
 from .stats import calculate_cv