Fork me on GitHub

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:

Old content beyond this point… 👴👵

filter-distance-matrix: Filter samples from a distance matrix.

Docstring:

Usage: qiime diversity filter-distance-matrix [OPTIONS]

  Filter samples from a distance matrix, retaining only the samples matching
  search criteria specified by `metadata` and `where` parameters (or retaining
  only the samples not matching that criteria, if `exclude_ids` is True). See
  the filtering tutorial on https://docs.qiime2.org for additional details.

Inputs:
  --i-distance-matrix ARTIFACT
    DistanceMatrix       Distance matrix to filter by sample.       [required]
Parameters:
  --m-metadata-file METADATA...
    (multiple            Sample metadata used with `where` parameter when
     arguments will be   selecting samples to retain, or with `exclude-ids`
     merged)             when selecting samples to discard.         [required]
  --p-where TEXT         SQLite WHERE clause specifying sample metadata
                         criteria that must be met to be included in the
                         filtered distance matrix. If not provided, all
                         samples in `metadata` that are also in the input
                         distance matrix will be retained.          [optional]
  --p-exclude-ids / --p-no-exclude-ids
                         If `True`, the samples selected by `metadata` or
                         `where` parameters will be excluded from the filtered
                         distance matrix instead of being retained.
                                                              [default: False]
Outputs:
  --o-filtered-distance-matrix ARTIFACT
    DistanceMatrix       Distance matrix filtered to include samples matching
                         search criteria                            [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.diversity.methods import filter_distance_matrix

Docstring:

Filter samples from a distance matrix.

Filter samples from a distance matrix, retaining only the samples matching
search criteria specified by `metadata` and `where` parameters (or
retaining only the samples not matching that criteria, if `exclude_ids` is
True). See the filtering tutorial on https://docs.qiime2.org for additional
details.

Parameters
----------
distance_matrix : DistanceMatrix
    Distance matrix to filter by sample.
metadata : Metadata
    Sample metadata used with `where` parameter when selecting samples to
    retain, or with `exclude_ids` when selecting samples to discard.
where : Str, optional
    SQLite WHERE clause specifying sample metadata criteria that must be
    met to be included in the filtered distance matrix. If not provided,
    all samples in `metadata` that are also in the input distance matrix
    will be retained.
exclude_ids : Bool, optional
    If `True`, the samples selected by `metadata` or `where` parameters
    will be excluded from the filtered distance matrix instead of being
    retained.

Returns
-------
filtered_distance_matrix : DistanceMatrix
    Distance matrix filtered to include samples matching search criteria