OpenMS
Public Types | Static Public Member Functions | List of all members
FeatureOverlapFilter Class Reference

#include <OpenMS/PROCESSING/FEATURE/FeatureOverlapFilter.h>

Public Types

using OverlapMode = FeatureOverlapMode
 Enum to specify the overlap detection mode (alias for backward compatibility) More...
 

Static Public Member Functions

static void filter (FeatureMap &fmap, std::function< bool(const Feature &, const Feature &)> FeatureComparator=[](const Feature &left, const Feature &right){ return left.getOverallQuality() > right.getOverallQuality();}, std::function< bool(Feature &, Feature &)> FeatureOverlapCallback=[](Feature &, Feature &){ return true;}, bool check_overlap_at_trace_level=true)
 
static void filter (FeatureMap &fmap, std::function< bool(const Feature &, const Feature &)> FeatureComparator, std::function< bool(Feature &, Feature &)> FeatureOverlapCallback, FeatureOverlapMode mode, const CentroidTolerances &tolerances=CentroidTolerances())
 
static std::function< bool(Feature &, Feature &)> createFAIMSMergeCallback (MergeIntensityMode intensity_mode=MergeIntensityMode::SUM, bool write_meta_values=true)
 Create a callback function for merging overlapping features. More...
 
static void mergeOverlappingFeatures (FeatureMap &feature_map, double max_rt_diff=5.0, double max_mz_diff=0.05, bool require_same_charge=true, bool require_same_im=false, MergeIntensityMode intensity_mode=MergeIntensityMode::SUM, bool write_meta_values=true)
 Merge overlapping features based on centroid distances. More...
 
static void mergeFAIMSFeatures (FeatureMap &feature_map, double max_rt_diff=5.0, double max_mz_diff=0.05)
 Merge FAIMS features that represent the same analyte detected at different CV values. More...
 

Member Typedef Documentation

◆ OverlapMode

using OverlapMode = FeatureOverlapMode

Enum to specify the overlap detection mode (alias for backward compatibility)

Member Function Documentation

◆ createFAIMSMergeCallback()

static std::function<bool(Feature&, Feature&)> createFAIMSMergeCallback ( MergeIntensityMode  intensity_mode = MergeIntensityMode::SUM,
bool  write_meta_values = true 
)
static

Create a callback function for merging overlapping features.

Creates a callback suitable for use with filter() that merges feature information when features overlap. The callback:

  • Combines intensities according to intensity_mode (SUM or MAX)
  • Optionally stores merge tracking information as meta values:
    • "merged_centroid_rts": vector of RT positions from all merged features
    • "merged_centroid_mzs": vector of m/z positions from all merged features
    • "merged_centroid_IMs": vector of FAIMS CV values (only if FAIMS_CV present on features)
    • "FAIMS_merge_count": count of merged FAIMS CV values

This callback is designed to work with features that may or may not have FAIMS CV annotations. Features without FAIMS_CV will simply not contribute to merged_centroid_IMs.

Parameters
intensity_modeHow to combine intensities: SUM adds all intensities, MAX keeps the highest intensity (default: SUM)
write_meta_valuesIf true, write merge tracking meta values to the surviving feature for debugging/analysis (default: true)
Returns
A callback function suitable for use with filter()

◆ filter() [1/2]

static void filter ( FeatureMap &  fmap,
std::function< bool(const Feature &, const Feature &)>  FeatureComparator,
std::function< bool(Feature &, Feature &)>  FeatureOverlapCallback,
FeatureOverlapMode  mode,
const CentroidTolerances &  tolerances = CentroidTolerances() 
)
static

◆ filter() [2/2]

static void filter ( FeatureMap &  fmap,
std::function< bool(const Feature &, const Feature &)>  FeatureComparator = [](const Feature &left, const Feature &right){ return left.getOverallQuality() > right.getOverallQuality();},
std::function< bool(Feature &, Feature &)>  FeatureOverlapCallback = [](Feature &, Feature &){ return true;},
bool  check_overlap_at_trace_level = true 
)
static

References Feature::getOverallQuality().

◆ mergeFAIMSFeatures()

static void mergeFAIMSFeatures ( FeatureMap &  feature_map,
double  max_rt_diff = 5.0,
double  max_mz_diff = 0.05 
)
static

Merge FAIMS features that represent the same analyte detected at different CV values.

This is a convenience function specifically designed for FAIMS data. It only merges features that have the FAIMS_CV meta value annotation AND have DIFFERENT CV values. Features without FAIMS_CV are left unchanged, and features with the same CV are never merged (they are considered different analytes).

This makes it safe to call on any data:

  • Non-FAIMS data: no merging occurs
  • Single-CV FAIMS data: no merging occurs (all features have same CV)
  • Multi-CV FAIMS data: only features at different CVs are merged

Features are considered the same analyte if they:

  • Have DIFFERENT FAIMS_CV values (same CV = different analytes)
  • Are within max_rt_diff seconds in RT
  • Are within max_mz_diff Da in m/z
  • Have the same charge state

The feature with highest intensity is kept, and intensities are summed.

Parameters
feature_mapThe feature map to process (modified in place)
max_rt_diffMaximum RT difference in seconds (default: 5.0)
max_mz_diffMaximum m/z difference in Da (default: 0.05)

◆ mergeOverlappingFeatures()

static void mergeOverlappingFeatures ( FeatureMap &  feature_map,
double  max_rt_diff = 5.0,
double  max_mz_diff = 0.05,
bool  require_same_charge = true,
bool  require_same_im = false,
MergeIntensityMode  intensity_mode = MergeIntensityMode::SUM,
bool  write_meta_values = true 
)
static

Merge overlapping features based on centroid distances.

Identifies features whose centroids are within the specified RT and m/z tolerances and merges them into a single representative feature. This is primarily designed for FAIMS data where the same analyte is detected at multiple compensation voltages.

The feature with the highest intensity is kept as the representative. Depending on intensity_mode, intensities are either summed or the maximum is kept.

When write_meta_values is true, the following meta values are stored on merged features:

  • "merged_centroid_rts": RT positions of all features that were merged
  • "merged_centroid_mzs": m/z positions of all features that were merged
  • "merged_centroid_IMs": FAIMS CV values (if present on the original features)
  • "FAIMS_merge_count": number of FAIMS CV values that were merged
Parameters
feature_mapThe feature map to process (modified in place)
max_rt_diffMaximum RT difference in seconds for considering features as overlapping (default: 5.0)
max_mz_diffMaximum m/z difference in Da for considering features as overlapping (default: 0.05)
require_same_chargeIf true, only merge features with identical charge states. If false, features with different charges can be merged (default: true)
require_same_imIf true, only merge features with identical FAIMS CV values. Features without FAIMS_CV are treated as a separate group and can only merge with other features lacking FAIMS_CV (default: false)
intensity_modeHow to combine intensities: SUM adds all intensities, MAX keeps the highest intensity (default: SUM)
write_meta_valuesIf true, write merge tracking meta values to merged features (default: true)