Add algorithm selection options for feature grouping

Co-authored-by: timosachsenberg <5803621+timosachsenberg@users.noreply.github.com>

Author: Copilot

openms_python/py_consensusmap.py

@@ -164,6 +164,8 @@ def align_and_link(
         *,
         alignment_method: str = "pose_clustering",
         alignment_params: Optional[Dict[str, Union[int, float, str]]] = None,
+        grouping_method: str = "qt",
+        grouping_params: Optional[Dict[str, Union[int, float, str]]] = None,
     ) -> 'Py_ConsensusMap':
         """Align multiple feature maps and return their linked consensus map.
 
@@ -180,14 +182,21 @@ def align_and_link(
         alignment_params:
             Optional dictionary of parameters applied to the selected
             alignment algorithm.
+        grouping_method:
+            Name of the OpenMS feature grouping algorithm to use. Supported values
+            are ``"qt"`` (QT clustering, default), ``"kd"`` (KD-tree based),
+            ``"labeled"`` (for labeled data), and ``"unlabeled"`` (for unlabeled data).
+        grouping_params:
+            Optional dictionary of parameters applied to the selected
+            grouping algorithm.
         """
 
         if not feature_maps:
             return cls()
 
         native_maps = [cls._copy_feature_map(feature_map) for feature_map in feature_maps]
         cls._align_feature_maps(native_maps, alignment_method, alignment_params)
-        consensus_map = cls._link_feature_maps(native_maps)
+        consensus_map = cls._link_feature_maps(native_maps, grouping_method, grouping_params)
         return cls(consensus_map)
 
     # ==================== pandas integration ====================
@@ -388,11 +397,37 @@ def _create_alignment_algorithm(method: str):
             "Unsupported alignment_method. Use 'pose_clustering', 'identification', or 'identity'."
         )
 
+    @staticmethod
+    def _create_grouping_algorithm(method: str):
+        """Create the appropriate feature grouping algorithm."""
+        normalized = method.lower()
+        if normalized in {"qt", "qtcluster"}:
+            return oms.FeatureGroupingAlgorithmQT()
+        if normalized in {"kd", "tree"}:
+            return oms.FeatureGroupingAlgorithmKD()
+        if normalized == "labeled":
+            return oms.FeatureGroupingAlgorithmLabeled()
+        if normalized == "unlabeled":
+            return oms.FeatureGroupingAlgorithmUnlabeled()
+        raise ValueError(
+            "Unsupported grouping_method. Use 'qt', 'kd', 'labeled', or 'unlabeled'."
+        )
+
     @staticmethod
     def _link_feature_maps(
         feature_maps: Sequence[oms.FeatureMap],
+        grouping_method: str = "qt",
+        grouping_params: Optional[Dict[str, Union[int, float, str]]] = None,
     ) -> oms.ConsensusMap:
-        grouping = oms.FeatureGroupingAlgorithmQT()
+        grouping = Py_ConsensusMap._create_grouping_algorithm(grouping_method)
+        
+        # Apply parameters if provided
+        if grouping_params:
+            params = grouping.getDefaults()
+            for key, value in grouping_params.items():
+                params.setValue(str(key), value)
+            grouping.setParameters(params)
+        
         consensus_map = oms.ConsensusMap()
         grouping.group(feature_maps, consensus_map)
 

openms_python/workflows.py

@@ -193,11 +193,43 @@ def align_feature_maps(
 def link_features(
     feature_maps: Sequence[_FeatureMapLike],
     *,
+    grouping_method: str = "qt",
     params: Optional[Dict[str, Union[int, float, str]]] = None,
 ) -> Py_ConsensusMap:
-    """Group features across runs into a consensus map."""
-
-    grouping = oms.FeatureGroupingAlgorithmQT()
+    """Group features across runs into a consensus map.
+    
+    Parameters
+    ----------
+    feature_maps:
+        Sequence of feature maps to link.
+    grouping_method:
+        Name of the OpenMS feature grouping algorithm to use. Supported values
+        are ``"qt"`` (QT clustering, default), ``"kd"`` (KD-tree based),
+        ``"labeled"`` (for labeled data), and ``"unlabeled"`` (for unlabeled data).
+    params:
+        Optional dictionary of parameters applied to the selected grouping algorithm.
+        
+    Returns
+    -------
+    Py_ConsensusMap
+        The linked consensus map.
+    """
+
+    # Create grouping algorithm
+    normalized = grouping_method.lower()
+    if normalized in {"qt", "qtcluster"}:
+        grouping = oms.FeatureGroupingAlgorithmQT()
+    elif normalized in {"kd", "tree"}:
+        grouping = oms.FeatureGroupingAlgorithmKD()
+    elif normalized == "labeled":
+        grouping = oms.FeatureGroupingAlgorithmLabeled()
+    elif normalized == "unlabeled":
+        grouping = oms.FeatureGroupingAlgorithmUnlabeled()
+    else:
+        raise ValueError(
+            "Unsupported grouping_method. Use 'qt', 'kd', 'labeled', or 'unlabeled'."
+        )
+    
     param_obj = grouping.getDefaults()
     if params:
         for key, value in params.items():

tests/test_consensus_map.py

@@ -33,3 +33,45 @@ def test_align_and_link_invalid_method_raises():
     fmap = Py_FeatureMap(_simple_feature_map(10.0))
     with pytest.raises(ValueError):
         Py_ConsensusMap.align_and_link([fmap], alignment_method="unknown")
+
+
+def test_align_and_link_with_kd_grouping():
+    """Test that KD-tree grouping method is supported."""
+    fmap_a = Py_FeatureMap(_simple_feature_map(10.0))
+    fmap_b = Py_FeatureMap(_simple_feature_map(10.0))
+
+    consensus = Py_ConsensusMap.align_and_link(
+        [fmap_a, fmap_b],
+        alignment_method="identity",
+        grouping_method="kd",
+    )
+
+    assert isinstance(consensus, Py_ConsensusMap)
+    assert len(consensus) == 1
+
+
+def test_align_and_link_invalid_grouping_raises():
+    """Test that invalid grouping method raises error."""
+    fmap = Py_FeatureMap(_simple_feature_map(10.0))
+    with pytest.raises(ValueError, match="Unsupported grouping_method"):
+        Py_ConsensusMap.align_and_link(
+            [fmap], 
+            alignment_method="identity",
+            grouping_method="invalid"
+        )
+
+
+def test_align_and_link_with_grouping_params():
+    """Test that grouping parameters can be passed."""
+    fmap_a = Py_FeatureMap(_simple_feature_map(10.0))
+    fmap_b = Py_FeatureMap(_simple_feature_map(10.0))
+
+    consensus = Py_ConsensusMap.align_and_link(
+        [fmap_a, fmap_b],
+        alignment_method="identity",
+        grouping_method="qt",
+        grouping_params={"distance_RT:max_difference": 100.0},
+    )
+
+    assert isinstance(consensus, Py_ConsensusMap)
+    assert len(consensus) == 1

tests/test_workflows.py

@@ -156,3 +156,50 @@ def test_link_features_and_export_quant_table():
     assert df.shape[0] >= 1
     # Expect one column per input map
     assert {col for col in df.columns if col.startswith("map_")}
+
+
+def test_link_features_with_kd_grouping():
+    """Test that KD-tree grouping method works in link_features."""
+    fmap_a = oms.FeatureMap()
+    feat_a = oms.Feature()
+    feat_a.setRT(10.0)
+    feat_a.setMZ(500.0)
+    feat_a.setIntensity(100.0)
+    fmap_a.push_back(feat_a)
+
+    fmap_b = oms.FeatureMap()
+    feat_b = oms.Feature()
+    feat_b.setRT(10.0)
+    feat_b.setMZ(500.0)
+    feat_b.setIntensity(110.0)
+    fmap_b.push_back(feat_b)
+
+    consensus = link_features(
+        [Py_FeatureMap(fmap_a), Py_FeatureMap(fmap_b)],
+        grouping_method="kd"
+    )
+    assert len(consensus) == 1
+
+
+def test_link_features_with_unlabeled_grouping():
+    """Test that unlabeled grouping method works in link_features."""
+    fmap_a = oms.FeatureMap()
+    feat_a = oms.Feature()
+    feat_a.setRT(10.0)
+    feat_a.setMZ(500.0)
+    feat_a.setIntensity(100.0)
+    fmap_a.push_back(feat_a)
+
+    fmap_b = oms.FeatureMap()
+    feat_b = oms.Feature()
+    feat_b.setRT(10.0)
+    feat_b.setMZ(500.0)
+    feat_b.setIntensity(110.0)
+    fmap_b.push_back(feat_b)
+
+    consensus = link_features(
+        [Py_FeatureMap(fmap_a), Py_FeatureMap(fmap_b)],
+        grouping_method="unlabeled"
+    )
+    assert len(consensus) == 1
+