Warning
This site has been replaced by the new QIIME 2 “amplicon distribution” documentation, as of the 2025.4 release of QIIME 2. You can still access the content from the “old docs” here for the QIIME 2 2024.10 and earlier releases, but we recommend that you transition to the new documentation at https://amplicon-docs.qiime2.org. Content on this site is no longer updated and may be out of date.
Are you looking for:
the QIIME 2 homepage? That’s https://qiime2.org.
learning resources for microbiome marker gene (i.e., amplicon) analysis? See the QIIME 2 amplicon distribution documentation.
learning resources for microbiome metagenome analysis? See the MOSHPIT documentation.
installation instructions, plugins, books, videos, workshops, or resources? See the QIIME 2 Library.
general help? See the QIIME 2 Forum.
Old content beyond this point… 👴👵
group: Group samples or features by a metadata column¶
Docstring:
Usage: qiime feature-table group [OPTIONS]
Group samples or features in a feature table using metadata to define the
mapping of IDs to a group.
Inputs:
--i-table ARTIFACT FeatureTable[Frequency]
The table to group samples or features on. [required]
Parameters:
--p-axis TEXT Choices('feature', 'sample')
Along which axis to group. Each ID in the given axis
must exist in `metadata`. [required]
--m-metadata-file METADATA
--m-metadata-column COLUMN MetadataColumn[Categorical]
A column defining the groups. Each unique value will
become a new ID for the table on the given `axis`.
[required]
--p-mode TEXT Choices('mean-ceiling', 'median-ceiling', 'sum')
How to combine samples or features within a group.
`sum` will sum the frequencies across all samples or
features within a group; `mean-ceiling` will take the
ceiling of the mean of these frequencies;
`median-ceiling` will take the ceiling of the median
of these frequencies. [required]
Outputs:
--o-grouped-table ARTIFACT FeatureTable[Frequency]
A table that has been grouped along the given
`axis`. IDs on that axis are replaced by values in
the `metadata` column. [required]
Miscellaneous:
--output-dir PATH Output unspecified results to a directory
--verbose / --quiet Display verbose output to stdout and/or stderr
during execution of this action. Or silence output if
execution is successful (silence is golden).
--example-data PATH Write example data and exit.
--citations Show citations and exit.
--use-cache DIRECTORY Specify the cache to be used for the intermediate
work of this action. If not provided, the default
cache under $TMP/qiime2/ will be used.
IMPORTANT FOR HPC USERS: If you are on an HPC system
and are using parallel execution it is important to
set this to a location that is globally accessible to
all nodes in the cluster.
--help Show this message and exit.
Examples:
# ### example: group samples
# Combine samples from the same body-site into single sample. Feature
# frequencies will be the median across the samples being combined, rounded
# up to the nearest whole number.
qiime feature-table group \
--i-table feature-table.qza \
--m-metadata-file sample-metadata.tsv \
--m-metadata-column body-site \
--p-mode median-ceiling \
--p-axis sample \
--o-grouped-table body-site-table.qza
Import:
from qiime2.plugins.feature_table.methods import group
Docstring:
Group samples or features by a metadata column
Group samples or features in a feature table using metadata to define the
mapping of IDs to a group.
Parameters
----------
table : FeatureTable[Frequency]
The table to group samples or features on.
axis : Str % Choices('feature', 'sample')
Along which axis to group. Each ID in the given axis must exist in
`metadata`.
metadata : MetadataColumn[Categorical]
A column defining the groups. Each unique value will become a new ID
for the table on the given `axis`.
mode : Str % Choices('mean-ceiling', 'median-ceiling', 'sum')
How to combine samples or features within a group. `sum` will sum the
frequencies across all samples or features within a group; `mean-
ceiling` will take the ceiling of the mean of these frequencies;
`median-ceiling` will take the ceiling of the median of these
frequencies.
Returns
-------
grouped_table : FeatureTable[Frequency]
A table that has been grouped along the given `axis`. IDs on that axis
are replaced by values in the `metadata` column.