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… 👴👵
shuffle-groups: Shuffle values in a categorical sample metadata column.¶
Docstring:
Usage: qiime metadata shuffle-groups [OPTIONS]
Create one or more categorical sample metadata columns by shuffling the
values in an input metadata column. To avoid confusion, the column name and
values will be derived from the provided prefixes. The number of different
values (or groups), and the counts of each value, will match the input
metadata column but the association of values with sample ids will be
random. These data will be written to an artifact that can be used as sample
metadata.
Parameters:
--m-metadata-file METADATA
--m-metadata-column COLUMN MetadataColumn[Categorical]
Categorical metadata column to shuffle. [required]
--p-n-columns INTEGER The number of shuffled metadata columns to create.
[default: 3]
--p-md-column-name-prefix TEXT
Prefix to use in naming the shuffled metadata
columns. [default: 'shuffled.grouping.']
--p-md-column-values-prefix TEXT
Prefix to use in naming the values in the shuffled
metadata columns. [default: 'fake.group.']
--p-encode-sample-size / --p-no-encode-sample-size
If true, the sample size of each metadata group will
be appended to the shuffled metadata column values.
[default: False]
Outputs:
--o-shuffled-groups ARTIFACT SampleData[ArtificialGrouping]
Randomized metadata columns [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.
Import:
from qiime2.plugins.metadata.methods import shuffle_groups
Docstring:
Shuffle values in a categorical sample metadata column.
Create one or more categorical sample metadata columns by shuffling the
values in an input metadata column. To avoid confusion, the column name and
values will be derived from the provided prefixes. The number of different
values (or groups), and the counts of each value, will match the input
metadata column but the association of values with sample ids will be
random. These data will be written to an artifact that can be used as
sample metadata.
Parameters
----------
metadata : MetadataColumn[Categorical]
Categorical metadata column to shuffle.
n_columns : Int, optional
The number of shuffled metadata columns to create.
md_column_name_prefix : Str, optional
Prefix to use in naming the shuffled metadata columns.
md_column_values_prefix : Str, optional
Prefix to use in naming the values in the shuffled metadata columns.
encode_sample_size : Bool, optional
If true, the sample size of each metadata group will be appended to the
shuffled metadata column values.
Returns
-------
shuffled_groups : SampleData[ArtificialGrouping]
Randomized metadata columns