NEW: add filter-ids action (#370)

<!-- PR guidance and examples:
https://github.com/rachis-org/governance/blob/main/pr_template_guidelines.md
-->
<!-- rachis Generative AI Policy:
https://github.com/rachis-org/governance/blob/main/ai_policy.md -->

# Description
<!-- REQUIRED: Briefly describe this PR, or link the issue it closes.
-->
- Adds filter-id action that can filter any feature table with metadata
by samples or features. The logic for metadata filtering is the same as
in the actions filter-samples and filter-features.
- There is an additional parameter where you can specify ids directly
without a metadata file.
- This action was added because the `Unconstrained` table needs actions
for id filtering but the data of the `Unconstrained` table is not suited
for the additional filters of filter-samples and filter-features that
only work with count tables.
- `Unconstrained` was added as a type to the split, transpose and
rename-ids actions.

# AI Disclosure
<!-- REQUIRED: Check exactly one option. -->

- [ ] NO AI USED.
- [x] AI USED.


# AI Usage Details
<!-- REQUIRED if 'AI USED' is checked. This section can be deleted if
'NO AI USED' is checked. -->
Codex

Author: VinzentRisch

q2_feature_table/__init__.py

@@ -13,7 +13,7 @@
                          tabulate_sample_frequencies,
                          tabulate_feature_frequencies, summarize)
 from ._merge import (merge, merge_seqs, merge_taxa, overlap_methods)
-from ._filter import (filter_samples, filter_features, filter_seqs,
+from ._filter import (filter_samples, filter_features, filter_ids, filter_seqs,
                       filter_features_conditionally)
 from ._split import split
 from ._core_features import core_features
@@ -30,9 +30,9 @@
 
 __all__ = ['rarefy', 'presence_absence', 'relative_frequency', 'transpose',
            '_summarize', 'merge', 'merge_seqs', 'filter_samples',
-           'filter_features', 'merge_taxa', 'tabulate_seqs', 'overlap_methods',
-           'core_features', 'group', 'heatmap', 'heatmap_choices',
-           'filter_seqs', 'subsample_ids', 'rename_ids',
+           'filter_features', 'filter_ids', 'merge_taxa', 'tabulate_seqs',
+           'overlap_methods', 'core_features', 'group', 'heatmap',
+           'heatmap_choices', 'filter_seqs', 'subsample_ids', 'rename_ids',
            'filter_features_conditionally', 'split',
            'tabulate_feature_frequencies', 'tabulate_sample_frequencies',
            'summarize', 'normalize', 'multiply_tables', '_multiply_tables',

q2_feature_table/_examples.py

@@ -461,3 +461,41 @@ def feature_table_summarize(use):
     feature_freqs.assert_output_type('ImmutableMetadata')
     sample_freqs.assert_output_type('ImmutableMetadata')
     viz.assert_output_type('Visualization')
+
+
+def feature_table_filter_ids_samples_by_metadata_and_where(use):
+    feature_table = use.init_artifact_from_url(
+        "feature_table", moving_pics_ft_url
+    )
+    sample_metadata = use.init_metadata_from_url(
+        "sample_metadata", moving_pics_md_url
+    )
+
+    filtered_table, = use.action(
+        use.UsageAction(plugin_id="feature_table", action_id="filter_ids"),
+        use.UsageInputs(
+            table=feature_table,
+            axis="sample",
+            metadata=sample_metadata,
+            where="[subject]='subject-1'",
+        ),
+        use.UsageOutputNames(filtered_table="filtered_table"),
+    )
+
+    filtered_table.assert_output_type("FeatureTable[Frequency]")
+
+
+def feature_table_filter_ids_features_by_ids(use):
+    feature_table = use.init_artifact("feature_table", ft4_factory)
+
+    filtered_table, = use.action(
+        use.UsageAction(plugin_id="feature_table", action_id="filter_ids"),
+        use.UsageInputs(
+            table=feature_table,
+            axis="feature",
+            ids=["F1", "F3"],
+        ),
+        use.UsageOutputNames(filtered_table="filtered_table"),
+    )
+
+    filtered_table.assert_output_type("FeatureTable[Frequency]")

q2_feature_table/_filter.py

@@ -30,8 +30,12 @@ def check_relative_frequency(table: biom.Table) -> bool:
 def _get_biom_filter_function(ids_to_keep, min_frequency, max_frequency,
                               min_nonzero, max_nonzero):
     ids_to_keep = set(ids_to_keep)
+    if min_frequency is None:
+        min_frequency = -np.inf
     if max_frequency is None:
         max_frequency = np.inf
+    if min_nonzero is None:
+        min_nonzero = 0
     if max_nonzero is None:
         max_nonzero = np.inf
 
@@ -48,21 +52,28 @@ def f(data_vector, id_, metadata):
 def _filter_table(table, min_frequency, max_frequency, min_nonzero,
                   max_nonzero, metadata, where, axis, exclude_ids=False,
                   filter_opposite_axis=True,
-                  allow_empty_table=False):
-    if min_frequency == 0 and max_frequency is None and min_nonzero == 0 and\
-       max_nonzero is None and metadata is None and where is None and\
-       exclude_ids is False:
+                  allow_empty_table=False, ids=None):
+    if (min_frequency in (None, 0) and max_frequency is None and
+            min_nonzero in (None, 0) and max_nonzero is None and ids is None
+            and metadata is None and where is None and exclude_ids is False):
         raise ValueError("No filtering was requested.")
     if metadata is None and where is not None:
         raise ValueError("Metadata must be provided if 'where' is "
                          "specified.")
-    if metadata is None and exclude_ids is True:
-        raise ValueError("Metadata must be provided if 'exclude_ids' "
-                         "is True.")
-    if metadata is not None:
-        ids_to_keep = metadata.get_ids(where=where)
+    if ids is None and metadata is None and exclude_ids is True:
+        raise ValueError("Either 'ids' or metadata must be provided if "
+                         "'exclude_ids' is True.")
+    if ids is not None:
+        missing_ids = set(ids) - set(table.ids(axis=axis))
+        if missing_ids:
+            raise ValueError("The following IDs are not in the table: %s" %
+                             ", ".join(sorted(missing_ids)))
+    if ids is None and metadata is None:
+        ids_to_keep = set(table.ids(axis=axis))
     else:
-        ids_to_keep = table.ids(axis=axis)
+        ids_to_keep = set(ids or [])
+        if metadata is not None:
+            ids_to_keep.update(metadata.get_ids(where=where))
     if exclude_ids is True:
         ids_to_keep = set(table.ids(axis=axis)) - set(ids_to_keep)
 
@@ -82,7 +93,9 @@ def _filter_table(table, min_frequency, max_frequency, min_nonzero,
 def filter_samples(table: biom.Table, min_frequency: int = 0,
                    max_frequency: int = None, min_features: int = 0,
                    max_features: int = None,
-                   metadata: qiime2.Metadata = None, where: str = None,
+                   ids: list[str] = None,
+                   metadata: qiime2.Metadata = None,
+                   where: str = None,
                    exclude_ids: bool = False,
                    filter_empty_features: bool = True,
                    allow_empty_table: bool = False)\
@@ -92,15 +105,17 @@ def filter_samples(table: biom.Table, min_frequency: int = 0,
                   max_nonzero=max_features, metadata=metadata,
                   where=where, axis='sample', exclude_ids=exclude_ids,
                   filter_opposite_axis=filter_empty_features,
-                  allow_empty_table=allow_empty_table
+                  allow_empty_table=allow_empty_table, ids=ids
                   )
     return table
 
 
 def filter_features(table: biom.Table, min_frequency: int = 0,
                     max_frequency: int | str = 'None', min_samples: int = 0,
                     max_samples: int = None,
-                    metadata: qiime2.Metadata = None, where: str = None,
+                    ids: list[str] = None,
+                    metadata: qiime2.Metadata = None,
+                    where: str = None,
                     exclude_ids: bool = False,
                     filter_empty_samples: bool = True,
                     allow_empty_table: bool = False)\
@@ -115,7 +130,7 @@ def filter_features(table: biom.Table, min_frequency: int = 0,
                   max_nonzero=max_samples, metadata=metadata,
                   where=where, axis='observation', exclude_ids=exclude_ids,
                   filter_opposite_axis=filter_empty_samples,
-                  allow_empty_table=allow_empty_table)
+                  allow_empty_table=allow_empty_table, ids=ids)
 
     if is_relative_frequency and not table.is_empty():
         relative_frequency(table)
@@ -178,3 +193,34 @@ def _filter_f(values, id_, metadata):
         _validate_nonempty_table(new_table)
 
     return new_table
+
+
+def filter_ids(
+        table: biom.Table,
+        axis: str,
+        ids: list[str] = None,
+        metadata: qiime2.Metadata = None,
+        where: str = None,
+        exclude_ids: bool = False,
+        allow_empty_table: bool = False
+) -> biom.Table:
+    """
+    Filter sample or feature IDs from a table.
+
+    IDs may be supplied directly with ``ids`` and/or selected from
+    ``metadata`` using a SQLite ``where`` clause. When both are supplied,
+    their IDs are combined. Direct IDs must all occur on the requested axis.
+    ``where`` may be used only with ``metadata``; without a WHERE clause, all
+    metadata IDs are selected. IDs on the opposite axis are retained.
+    """
+    axis_map = {"sample": "sample", "feature": "observation"}
+    biom_axis = axis_map[axis]
+
+    _filter_table(
+        table=table, min_frequency=None, max_frequency=None,
+        min_nonzero=None, max_nonzero=None, metadata=metadata, where=where,
+        axis=biom_axis, exclude_ids=exclude_ids,
+        filter_opposite_axis=False,
+        allow_empty_table=allow_empty_table, ids=ids)
+
+    return table

q2_feature_table/plugin_setup.py

@@ -12,7 +12,8 @@
                            Visualization)
 
 from q2_types.feature_table import (
-    FeatureTable, Frequency, RelativeFrequency, PresenceAbsence, Composition)
+    FeatureTable, Frequency, RelativeFrequency, PresenceAbsence, Composition,
+    Unconstrained)
 from q2_types.feature_data import (
     FeatureData, Sequence, Taxonomy, AlignedSequence, SequenceCharacteristics,
     LinkedSequence
@@ -35,6 +36,26 @@
 T1 = TypeMatch([Frequency, RelativeFrequency, PresenceAbsence, Composition])
 T2 = TypeMatch([Sequence, AlignedSequence, LinkedSequence])
 T3 = TypeMatch([Sequence, LinkedSequence])
+T4 = TypeMatch([Frequency, RelativeFrequency, PresenceAbsence, Composition,
+                Unconstrained])
+
+_filter_parameter_descriptions = {
+    'ids': ('IDs to retain or, with `exclude_ids`, discard. When supplied '
+            'with `metadata`, IDs from both sources are selected.'),
+    'metadata': ('Metadata used with the `where` parameter when selecting '
+                 'IDs to retain, or with `exclude_ids` when selecting IDs '
+                 'to discard.'),
+    'where': ('SQLite WHERE clause specifying metadata criteria that must be '
+              'met for IDs to be included in the filtered feature table. If '
+              'not provided, all IDs in `metadata` that are also in the '
+              'feature table will be retained.'),
+    'exclude_ids': ('If true, the IDs selected by `ids`, `metadata`, or '
+                    '`where` will be excluded from the filtered table '
+                    'instead of being retained.'),
+    'allow_empty_table': ('If true, the filtered table may be empty. Default '
+                          'behavior is to raise an error if the filtered '
+                          'table is empty.')
+}
 
 plugin.methods.register_function(
     function=q2_feature_table.rarefy,
@@ -136,10 +157,10 @@
 
 plugin.methods.register_function(
     function=q2_feature_table.transpose,
-    inputs={'table': FeatureTable[T1]},
+    inputs={'table': FeatureTable[T4]},
     parameters={},
     outputs=[('transposed_feature_table',
-             FeatureTable[T1])],
+             FeatureTable[T4])],
     input_descriptions={
         'table': 'The feature table to be transposed.'
     },
@@ -283,15 +304,15 @@
 plugin.methods.register_function(
     function=q2_feature_table.rename_ids,
     inputs={
-        'table': FeatureTable[T1],
+        'table': FeatureTable[T4],
     },
     parameters={
         'metadata': MetadataColumn[Categorical],
         'strict': Bool,
         'axis': Str % Choices({'sample', 'feature'})
         },
     outputs=[
-        ('renamed_table', FeatureTable[T1])
+        ('renamed_table', FeatureTable[T4])
         ],
     input_descriptions={
         'table': 'The table to be renamed',
@@ -323,6 +344,7 @@
                 'max_frequency': Int,
                 'min_features': Int,
                 'max_features': Int,
+                'ids': List[Str],
                 'metadata': Metadata,
                 'where': Str,
                 'exclude_ids': Bool,
@@ -345,27 +367,15 @@
                          'have to be retained. If no value is provided '
                          'this will default to infinity (i.e., no maximum '
                          'feature filter will be applied).'),
-        'metadata': 'Sample metadata used with `where` parameter when '
-                    'selecting samples to retain, or with `exclude_ids` '
-                    'when selecting samples to discard.',
-        'where': 'SQLite WHERE clause specifying sample metadata criteria '
-                 'that must be met to be included in the filtered feature '
-                 'table. If not provided, all samples in `metadata` that are '
-                 'also in the feature table will be retained.',
-        'exclude_ids': 'If true, the samples selected by `metadata` or '
-                       '`where` parameters will be excluded from the filtered '
-                       'table instead of being retained.',
+        **_filter_parameter_descriptions,
         'filter_empty_features': 'If true, features which are not present in '
                                  'any retained samples are dropped.',
-        'allow_empty_table': 'If true, the filtered table may be empty. '
-                             'Default behavior is to raise an error if the '
-                             'filtered table is empty.'
     },
     output_descriptions={
         'filtered_table': 'The resulting feature table filtered by sample.'
     },
     name="Filter samples from table",
-    description="Filter samples from table based on frequency and/or "
+    description="Filter samples from table based on frequency, IDs, and/or "
                 "metadata. Any features with a frequency of zero after sample "
                 "filtering will also be removed.",
     examples={
@@ -440,6 +450,7 @@
                 'max_frequency': p_filter_features_max_frequency,
                 'min_samples': Int,
                 'max_samples': Int,
+                'ids': List[Str],
                 'metadata': Metadata,
                 'where': Str,
                 'exclude_ids': Bool,
@@ -465,27 +476,15 @@
                         'be observed in to be retained. If no value is '
                         'provided this will default to infinity (i.e., no '
                         'maximum sample filter will be applied).'),
-        'metadata': 'Feature metadata used with `where` parameter when '
-                    'selecting features to retain, or with `exclude_ids` '
-                    'when selecting features to discard.',
-        'where': 'SQLite WHERE clause specifying feature metadata criteria '
-                 'that must be met to be included in the filtered feature '
-                 'table. If not provided, all features in `metadata` that are '
-                 'also in the feature table will be retained.',
-        'exclude_ids': 'If true, the features selected by `metadata` or '
-                       '`where` parameters will be excluded from the filtered '
-                       'table instead of being retained.',
+        **_filter_parameter_descriptions,
         'filter_empty_samples': 'If true, drop any samples where none of the '
                                 'retained features are present.',
-        'allow_empty_table': 'If true, the filtered table may be empty. '
-                                'Default behavior is to raise an error if the '
-                                'filtered table is empty.'
     },
     output_descriptions={
         'filtered_table': 'The resulting feature table filtered by feature.'
     },
     name="Filter features from table",
-    description="Filter features from table based on frequency and/or "
+    description="Filter features from table based on frequency, IDs, and/or "
                 "metadata. Any samples with a frequency of zero after feature "
                 "filtering will also be removed.",
     examples={
@@ -662,13 +661,13 @@
 
 plugin.methods.register_function(
     function=q2_feature_table.split,
-    inputs={'table': FeatureTable[T1]},
+    inputs={'table': FeatureTable[T4]},
     parameters={
         'metadata': MetadataColumn[Categorical],
         'filter_empty_features': Bool
     },
     outputs=[
-        ('tables', Collection[FeatureTable[T1]])
+        ('tables', Collection[FeatureTable[T4]])
     ],
     input_descriptions={
         'table': 'The table to split.'
@@ -961,3 +960,42 @@
     ),
     citations=[],
 )
+
+plugin.methods.register_function(
+    function=q2_feature_table.filter_ids,
+    inputs={"table": FeatureTable[T4]},
+    parameters={"axis": Str % Choices(["sample", "feature"]),
+                "ids": List[Str],
+                "metadata": Metadata,
+                "where": Str,
+                "exclude_ids": Bool,
+                "allow_empty_table": Bool},
+    outputs=[("filtered_table", FeatureTable[T4])],
+    input_descriptions={
+        "table": (
+            "The feature table from which IDs should be filtered."
+        )
+    },
+    parameter_descriptions={
+        "axis": (
+            "The axis to filter. Select 'sample' to filter sample IDs or "
+            "'feature' to filter feature IDs."
+        ),
+        **_filter_parameter_descriptions,
+    },
+    output_descriptions={
+        "filtered_table": (
+            "The feature table filtered by selected sample or feature IDs."
+        )
+    },
+    name="Filter IDs from table",
+    description=(
+        "Filter samples or features from a table using an ID list or "
+        "metadata selected with a SQLite WHERE clause."
+    ),
+    examples={
+        "filter_samples_by_metadata_and_where":
+        ex.feature_table_filter_ids_samples_by_metadata_and_where,
+        "filter_features_by_ids": ex.feature_table_filter_ids_features_by_ids,
+    },
+)