Rename updateProteinReferences to removeDanglingProteinReferences (OpenMS#8500)

The function removes PeptideEvidence entries that reference proteins
that no longer exist in the protein hits. The new name more clearly
describes this removal behavior, aligning with other IDFilter methods
like removeUnreferencedProteins and removeUngroupedProteins.

Changes:
- Renamed all three overloads of the function
- Improved documentation with detailed @param[in]/[out] annotations
- Updated all usages in TOPP tools and library code
- Updated Python bindings with expanded docstring
- Updated unit tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <noreply@anthropic.com>

Author: timosachsenberg

src/openms/include/OpenMS/PROCESSING/ID/IDFilter.h

@@ -782,31 +782,53 @@ namespace OpenMS
     static void removeUnreferencedProteins(ProteinIdentification& proteins, const PeptideIdentificationList& peptides);
 
     /**
-       @brief Removes references to missing proteins
+       @brief Removes dangling protein references from peptide hits
 
-       Only PeptideEvidence entries that reference protein hits in @p proteins are kept in the peptide hits.
+       Cleans up PeptideEvidence entries by removing references to proteins that no longer exist
+       in the provided protein identifications. This is typically called after filtering protein hits
+       to maintain consistency between peptide-to-protein mappings.
 
-       If @p remove_peptides_without_reference is set, peptide hits without any remaining protein reference are removed.
+       @param[in,out] peptides The peptide identifications to process
+       @param[in] proteins The protein identifications containing valid protein hits
+       @param[in] remove_peptides_without_reference If true, peptide hits that have no remaining
+              protein references after cleanup are also removed (default: false)
+
+       @note Only PeptideEvidence entries referencing protein hits in @p proteins are kept.
+             The matching is done per identification run using the run identifier.
     */
-    static void updateProteinReferences(PeptideIdentificationList& peptides, const std::vector<ProteinIdentification>& proteins, bool remove_peptides_without_reference = false);
+    static void removeDanglingProteinReferences(PeptideIdentificationList& peptides, const std::vector<ProteinIdentification>& proteins, bool remove_peptides_without_reference = false);
 
     /**
-       @brief Removes references to missing proteins
+       @brief Removes dangling protein references from peptide hits in a ConsensusMap
+
+       Cleans up PeptideEvidence entries by removing references to proteins that no longer exist
+       in the ConsensusMap's protein identifications. This is typically called after filtering
+       protein hits to maintain consistency between peptide-to-protein mappings.
 
-       Only PeptideEvidence entries that reference protein hits in their corresponding protein run of @p cmap are kept in the peptide hits.
+       @param[in,out] cmap The ConsensusMap containing peptide and protein identifications
+       @param[in] remove_peptides_without_reference If true, peptide hits that have no remaining
+              protein references after cleanup are also removed (default: false)
 
-       If @p remove_peptides_without_reference is set, peptide hits without any remaining protein reference are removed.
+       @note Only PeptideEvidence entries referencing protein hits in the corresponding
+             protein run of @p cmap are kept. The matching is done per identification run.
     */
-    static void updateProteinReferences(ConsensusMap& cmap, bool remove_peptides_without_reference = false);
+    static void removeDanglingProteinReferences(ConsensusMap& cmap, bool remove_peptides_without_reference = false);
 
     /**
-       @brief Removes references to missing proteins
+       @brief Removes dangling protein references from peptide hits using a reference protein run
+
+       Cleans up PeptideEvidence entries by removing references to proteins that do not exist
+       in the specified reference protein run. This is typically called after filtering protein
+       hits to maintain consistency between peptide-to-protein mappings.
 
-       Only PeptideEvidence entries that reference protein hits in @p ref_run are kept in the peptide hits.
+       @param[in,out] cmap The ConsensusMap containing peptide identifications to process
+       @param[in] ref_run The reference ProteinIdentification containing valid protein hits
+       @param[in] remove_peptides_without_reference If true, peptide hits that have no remaining
+              protein references after cleanup are also removed (default: false)
 
-       If @p remove_peptides_without_reference is set, peptide hits without any remaining protein reference are removed.
+       @note Only PeptideEvidence entries referencing protein hits in @p ref_run are kept.
     */
-    static void updateProteinReferences(ConsensusMap& cmap, const ProteinIdentification& ref_run, bool remove_peptides_without_reference = false);
+    static void removeDanglingProteinReferences(ConsensusMap& cmap, const ProteinIdentification& ref_run, bool remove_peptides_without_reference = false);
 
     /**
        @brief Update protein groups after protein hits were filtered
@@ -1195,7 +1217,7 @@ namespace OpenMS
       {
         filterHitsByScore(peptide_id, peptide_threshold_score);
       }
-      updateProteinReferences(annotated_data.getPeptideIdentifications(), annotated_data.getProteinIdentifications());
+      removeDanglingProteinReferences(annotated_data.getPeptideIdentifications(), annotated_data.getProteinIdentifications());
     }
 
     /// Filters AnnotatedMSRun by keeping the N best peptide hits for every spectrum
@@ -1223,7 +1245,7 @@ namespace OpenMS
         // Since we're working with individual PeptideIdentifications, we don't need to remove empty ones
         // but we still need to update protein references
         temp_vec = {peptide_id};
-        updateProteinReferences(temp_vec, annotated_data.getProteinIdentifications());
+        removeDanglingProteinReferences(temp_vec, annotated_data.getProteinIdentifications());
         all_peptides.push_back(peptide_id);
       }
       // update protein hits:

src/openms/source/ANALYSIS/ID/BasicProteinInferenceAlgorithm.cpp

@@ -86,7 +86,7 @@ namespace OpenMS
     {
       std::vector<ProteinIdentification> tmp(1);
       std::swap(tmp[0], prot_id);
-      IDFilter::updateProteinReferences(pep_ids, tmp, true); //TODO allow keeping PSMs without evidence?
+      IDFilter::removeDanglingProteinReferences(pep_ids, tmp, true); //TODO allow keeping PSMs without evidence?
       std::swap(tmp[0], prot_id);
     }
 
@@ -186,7 +186,7 @@ namespace OpenMS
       IDFilter::removeMatchingItems<std::vector<ProteinHit>>(prot_run.getHits(),
           IDFilter::HasMaxMetaValue<ProteinHit>("nr_found_peptides", static_cast<int>(min_peptides_per_protein) - 1));
 
-      IDFilter::updateProteinReferences(cmap, prot_run, true);
+      IDFilter::removeDanglingProteinReferences(cmap, prot_run, true);
     }
 
     if (group)
@@ -259,7 +259,7 @@ namespace OpenMS
 
     if (min_peptides_per_protein > 0) //potentially sth was filtered
     {
-      IDFilter::updateProteinReferences(pep_ids, prot_ids, true); //TODO allow keeping PSMs without evidence?
+      IDFilter::removeDanglingProteinReferences(pep_ids, prot_ids, true); //TODO allow keeping PSMs without evidence?
     }
 
     IDScoreSwitcherAlgorithm::switchBackScoreType(pep_ids, isr); // NOP if no switch was performed

src/openms/source/PROCESSING/ID/IDFilter.cpp

@@ -299,7 +299,7 @@ namespace OpenMS
   }
 
   // TODO write version where you look up in a specific run (e.g. first inference run)
-  void IDFilter::updateProteinReferences(ConsensusMap& cmap, bool remove_peptides_without_reference)
+  void IDFilter::removeDanglingProteinReferences(ConsensusMap& cmap, bool remove_peptides_without_reference)
   {
     vector<ProteinIdentification>& proteins = cmap.getProteinIdentifications();
     // collect valid protein accessions for each ID run:
@@ -336,7 +336,7 @@ namespace OpenMS
     cmap.applyFunctionOnPeptideIDs(check_prots_avail);
   }
 
-  void IDFilter::updateProteinReferences(ConsensusMap& cmap, const ProteinIdentification& ref_run, bool remove_peptides_without_reference)
+  void IDFilter::removeDanglingProteinReferences(ConsensusMap& cmap, const ProteinIdentification& ref_run, bool remove_peptides_without_reference)
   {
     // collect valid protein accessions for each ID run:
     unordered_set<String> accessions_avail;
@@ -369,7 +369,7 @@ namespace OpenMS
     cmap.applyFunctionOnPeptideIDs(check_prots_avail);
   }
 
-  void IDFilter::updateProteinReferences(PeptideIdentificationList& peptides, const vector<ProteinIdentification>& proteins, bool remove_peptides_without_reference)
+  void IDFilter::removeDanglingProteinReferences(PeptideIdentificationList& peptides, const vector<ProteinIdentification>& proteins, bool remove_peptides_without_reference)
   {
     // collect valid protein accessions for each ID run:
     map<String, unordered_set<String>> run_to_accessions;

src/pyOpenMS/pxds/IDFilter.pxd

@@ -81,7 +81,18 @@ cdef extern from "<OpenMS/PROCESSING/ID/IDFilter.h>" namespace "OpenMS":
 
         void removeUnreferencedProteins(libcpp_vector[ProteinIdentification]& proteins, PeptideIdentificationList& peptides) except + nogil  # wrap-doc:Removes protein hits from the protein IDs in a 'cmap' that are not referenced by a peptide in the features or if requested in the unassigned peptide list
 
-        void updateProteinReferences(PeptideIdentificationList& peptides, libcpp_vector[ProteinIdentification]& proteins, bool remove_peptides_without_reference) except + nogil  # wrap-doc:Removes references to missing proteins. Only PeptideEvidence entries that reference protein hits in 'proteins' are kept in the peptide hits
+        void removeDanglingProteinReferences(PeptideIdentificationList& peptides, libcpp_vector[ProteinIdentification]& proteins, bool remove_peptides_without_reference) except + nogil
+            # wrap-doc:
+                #  Removes dangling protein references from peptide hits
+                #
+                #  Cleans up PeptideEvidence entries by removing references to proteins that no longer exist
+                #  in the provided protein identifications. This is typically called after filtering protein hits
+                #  to maintain consistency between peptide-to-protein mappings.
+                #
+                #  :param peptides: The peptide identifications to process (in/out)
+                #  :param proteins: The protein identifications containing valid protein hits (in)
+                #  :param remove_peptides_without_reference: If true, peptide hits that have no remaining
+                #         protein references after cleanup are also removed (default: false) (in)
 
         bool updateProteinGroups(libcpp_vector[ProteinGroup]& groups, libcpp_vector[ProteinHit]& hits) except + nogil 
             # wrap-doc:

src/tests/class_tests/openms/source/IDFilter_test.cpp

@@ -239,7 +239,7 @@ START_SECTION((static void removeUnreferencedProteins(vector<ProteinIdentificati
 }
 END_SECTION
 
-START_SECTION((static void updateProteinReferences(PeptideIdentificationList& peptides, const vector<ProteinIdentification>& proteins, bool remove_peptides_without_reference = false)))
+START_SECTION((static void removeDanglingProteinReferences(PeptideIdentificationList& peptides, const vector<ProteinIdentification>& proteins, bool remove_peptides_without_reference = false)))
 {
   vector<ProteinIdentification> proteins = global_proteins;
   PeptideIdentificationList peptides = global_peptides;
@@ -250,7 +250,7 @@ START_SECTION((static void updateProteinReferences(PeptideIdentificationList& pe
   TEST_EQUAL(peptide_hits[4].getPeptideEvidences().size(), 1);
   proteins[0].getHits().resize(2);
 
-  IDFilter::updateProteinReferences(peptides, proteins);
+  IDFilter::removeDanglingProteinReferences(peptides, proteins);
   TEST_EQUAL(peptide_hits.size(), 11);
   for (Size i = 0; i < peptide_hits.size(); ++i)
   {
@@ -267,7 +267,7 @@ START_SECTION((static void updateProteinReferences(PeptideIdentificationList& pe
   }
 
   // remove peptide hits without any reference to an existing proteins:
-  IDFilter::updateProteinReferences(peptides, proteins, true);
+  IDFilter::removeDanglingProteinReferences(peptides, proteins, true);
   TEST_EQUAL(peptide_hits.size(), 2);
 }
 END_SECTION

src/topp/FalseDiscoveryRate.cpp

@@ -265,7 +265,7 @@ class TOPPFalseDiscoveryRate :
         IDFilter::removeUnreferencedProteins(prot_ids, pep_ids);
       }
       //remove_psms_without_proteins
-      IDFilter::updateProteinReferences(pep_ids,
+      IDFilter::removeDanglingProteinReferences(pep_ids,
                                         prot_ids,
                                         getStringOption_("FDR:cleanup:remove_psms_without_proteins") == "true");
       //remove_spectra_without_psms

src/topp/IDFilter.cpp

@@ -807,7 +807,7 @@ class TOPPIDFilter :
     {
       OPENMS_LOG_INFO << "Removing peptide hits without protein references..." << endl;
     }
-    IDFilter::updateProteinReferences(peptides, proteins, rm_pep);
+    IDFilter::removeDanglingProteinReferences(peptides, proteins, rm_pep);
 
     IDFilter::removeEmptyIdentifications(peptides);
     // we want to keep "empty" protein IDs because they contain search meta data

src/topp/IsobaricWorkflow.cpp

@@ -769,7 +769,7 @@ class TOPPIsobaricWorkflow :
       OPENMS_LOG_INFO << "Removing peptide hits without protein references..." << endl;
     }
 
-    IDFilter::updateProteinReferences(cmap, rm_pep);
+    IDFilter::removeDanglingProteinReferences(cmap, rm_pep);
     IDFilter::removeUnreferencedProteins(cmap, true);
     IDFilter::updateProteinGroups(proteins.getIndistinguishableProteins(), proteins.getHits());
     IDFilter::updateProteinGroups(proteins.getProteinGroups(), proteins.getHits());
@@ -790,7 +790,7 @@ class TOPPIsobaricWorkflow :
     if (max_pro_fdr < 1.0)
     {
       IDFilter::filterHitsByScore(proteins, max_pro_fdr);
-      IDFilter::updateProteinReferences(cmap, rm_pep);
+      IDFilter::removeDanglingProteinReferences(cmap, rm_pep);
     }
 
     if (max_psm_fdr < 1.0) 

src/topp/ProteomicsLFQ.cpp

@@ -1313,7 +1313,7 @@ class ProteomicsLFQ :
 
     if (!getFlag_("PeptideQuantification:quantify_decoys"))
     { // FDR filtering removed all decoy proteins -> update references and remove all unreferenced (decoy) PSMs
-      IDFilter::updateProteinReferences(consensus, true);
+      IDFilter::removeDanglingProteinReferences(consensus, true);
       IDFilter::removeUnreferencedProteins(consensus, true); // if we don't filter peptides for now, we don't need this
       IDFilter::updateProteinGroups(overall_proteins.getIndistinguishableProteins(),
                                     overall_proteins.getHits());
@@ -1338,7 +1338,7 @@ class ProteomicsLFQ :
 
     if (max_fdr < 1. || !getFlag_("PeptideQuantification:quantify_decoys"))
     {
-      IDFilter::updateProteinReferences(consensus, true);
+      IDFilter::removeDanglingProteinReferences(consensus, true);
     }
 
     if (max_psm_fdr < 1.)