q2-diversity

This QIIME 2 plugin supports metrics for calculating and exploring community alpha and beta diversity through statistics and visualizations in the context of sample metadata.

version: 2025.7.0.dev0

website: https://github.com/qiime2/q2-diversity

user support:

Please post to the QIIME 2 forum for help with this plugin: https://forum.qiime2.org

Actions¶

diversity pcoa¶

Apply principal coordinate analysis.

Citations¶

Legendre & Legendre, 2012; Halko et al., 2011

Inputs¶

distance_matrix: DistanceMatrix

The distance matrix on which PCoA should be computed.[required]

Parameters¶

number_of_dimensions: Int % Range(1, None)

Dimensions to reduce the distance matrix to. This number determines how many eigenvectors and eigenvalues are returned,and influences the choice of algorithm used to compute them. By default, uses the default eigendecomposition method, SciPy's eigh, which computes all eigenvectors and eigenvalues in an exact manner. For very large matrices, this is expected to be slow. If a value is specified for this parameter, then the fast, heuristic eigendecomposition algorithm fsvd is used, which only computes and returns the number of dimensions specified, but suffers some degree of accuracy loss, the magnitude of which varies across different datasets.[optional]

Outputs¶

pcoa: PCoAResults

The resulting PCoA matrix.[required]

diversity pcoa-biplot¶

Project features into a principal coordinates matrix. The features used should be the features used to compute the distance matrix. It is recommended that these variables be normalized in cases of dimensionally heterogeneous physical variables.

Citations¶

Legendre & Legendre, 2012

Inputs¶

pcoa: PCoAResults

The PCoA where the features will be projected onto.[required]

features: FeatureTable[RelativeFrequency]

Variables to project onto the PCoA matrix[required]

Outputs¶

biplot: PCoAResults % Properties('biplot')

The resulting PCoA matrix.[required]

diversity tsne¶

Apply t-distributed stochastic neighbor embedding.

Inputs¶

distance_matrix: DistanceMatrix

The distance matrix on which t-SNE should be computed.[required]

Parameters¶

number_of_dimensions: Int % Range(2, None)

Dimensions to reduce the distance matrix to.[default: 2]

perplexity: Float % Range(1, None)

Provide the balance between local and global structure. Low values concentrate on local structure. Large values sacrifice local details for a broader global embedding. The default value is 25 to achieve better results for small microbiome datasets.[default: 25.0]

n_iter: Int % Range(1, None)

<no description>[default: 1000]

learning_rate: Float % Range(10.0, None)

Controls how much the weights are adjusted at each update.[default: 200.0]

early_exaggeration: Float % Range(0, None)

Affects the tightness of the shown clusters. Larger values increase the distance between natural clusters in the embedded space.[default: 12.0]

random_state: Int

Seed used by random number generator.[optional]

Outputs¶

tsne: PCoAResults

The resulting t-SNE matrix.[required]

diversity umap¶

Apply Uniform Manifold Approximation and Projection.

Inputs¶

distance_matrix: DistanceMatrix

The distance matrix on which UMAP should be computed.[required]

Parameters¶

number_of_dimensions: Int % Range(2, None)

Dimensions to reduce the distance matrix to.[default: 2]

n_neighbors: Int % Range(1, None)

Provide the balance between local and global structure. Low values prioritize the preservation of local structures. Large values sacrifice local details for a broader global embedding.[default: 15]

min_dist: Float % Range(0, None)

Controls the cluster size. Low values cause clumpier clusters. Higher values preserve a broad topological structure. To get less overlapping data points the default value is set to 0.4. For more details visit: https://umap-learn.readthedocs.io/en/latest/parameters.html[default: 0.4]

random_state: Int

Seed used by random number generator.[optional]

Outputs¶

umap: PCoAResults

The resulting UMAP matrix.[required]

diversity procrustes-analysis¶

Fit two ordination matrices with Procrustes analysis

Inputs¶

reference: PCoAResults

The ordination matrix to which data is fitted to.[required]

other: PCoAResults

The ordination matrix that's fitted to the reference ordination.[required]

Parameters¶

dimensions: Int % Range(1, None)

The number of dimensions to use when fitting the two matrices[default: 5]

permutations: Int % Range(1, None) | Str % Choices('disable')

The number of permutations to be run when computing p-values. Supplying a value of disable will disable permutation testing and p-values will not be calculated (this results in much quicker execution time if p-values are not desired).[default: 999]

Outputs¶

transformed_reference: PCoAResults

A normalized version of the "reference" ordination matrix.[required]

transformed_other: PCoAResults

A normalized and fitted version of the "other" ordination matrix.[required]

disparity_results: ProcrustesStatistics

The sum of the squares of the pointwise differences between the two input datasets & its p value.[required]

diversity partial-procrustes¶

Transform one ordination into another, using paired samples to anchor the transformation. This method allows does not require all samples to be paired.

Inputs¶

reference: PCoAResults

The ordination matrix to which data is fitted to.[required]

other: PCoAResults

The ordination matrix that's fitted to the reference ordination.[required]

Parameters¶

pairing: MetadataColumn[Categorical]

The metadata column describing sample pairs which exist.[required]

dimensions: Int % Range(1, None)

The number of dimensions to use when fitting the two matrices[default: 5]

Outputs¶

transformed: PCoAResults

The 'other' ordination transformed into the space of the reference ordination.[required]

diversity filter-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.

Inputs¶

distance_matrix: DistanceMatrix

Distance matrix to filter by sample.[required]

Parameters¶

metadata: Metadata

Sample metadata used with where parameter when selecting samples to retain, or with exclude_ids when selecting samples to discard.[required]

where: Str

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]

exclude_ids: Bool

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¶

filtered_distance_matrix: DistanceMatrix

Distance matrix filtered to include samples matching search criteria[required]

diversity filter-alpha-diversity¶

Filter samples from an alpha diversity metric, retaining samples with corresponding metadata (or retaining samples without metadata, if exclude_ids is True). See the filtering tutorial on https://docs.qiime2.org for additional details.

Inputs¶

alpha_diversity: SampleData[AlphaDiversity]

Alpha diversity sample data to filter by sample.[required]

Parameters¶

metadata: Metadata

Sample metadata used to select samples to retain from the sample data (default) or select samples to exclude using the exclude_ids parameter.[required]

where: Str

SQLite WHERE clause specifying sample metadata criteria that must be met to be included in the filtered alpha diversity artifact. If not provided, all samples in metadata that are also in the input alpha diversity artifact will be retained.[optional]

exclude_ids: Bool

If True, the samples selected by metadata or the where parameters will be excluded from the filtered alpha diversity artifact instead of being retained.[default: False]

Outputs¶

filtered_alpha_diversity: SampleData[AlphaDiversity]

<no description>[required]

diversity alpha-group-significance¶

Visually and statistically compare groups of alpha diversity values.

Citations¶

Kruskal & Wallis, 1952

Inputs¶

alpha_diversity: SampleData[AlphaDiversity]

Vector of alpha diversity values by sample.[required]

Parameters¶

metadata: Metadata

The sample metadata.[required]

Outputs¶

visualization: Visualization

<no description>[required]

Examples¶

alpha_group_significance_faith_pd¶

wget -O 'alpha-div-faith-pd.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-group-significance/1/alpha-div-faith-pd.qza'

wget -O 'metadata.tsv' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-group-significance/1/metadata.tsv'

qiime diversity alpha-group-significance \
  --i-alpha-diversity alpha-div-faith-pd.qza \
  --m-metadata-file metadata.tsv \
  --o-visualization visualization.qzv

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.diversity.actions as diversity_actions

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-group-significance/1/alpha-div-faith-pd.qza'
fn = 'alpha-div-faith-pd.qza'
request.urlretrieve(url, fn)
alpha_div_faith_pd = Artifact.load(fn)

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-group-significance/1/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

visualization_viz, = diversity_actions.alpha_group_significance(
    alpha_diversity=alpha_div_faith_pd,
    metadata=metadata_md,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
diversity_actions <- import("qiime2.plugins.diversity.actions")
request <- import("urllib")$request

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-group-significance/1/alpha-div-faith-pd.qza'
fn <- 'alpha-div-faith-pd.qza'
request$urlretrieve(url, fn)
alpha_div_faith_pd <- Artifact$load(fn)

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-group-significance/1/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- diversity_actions$alpha_group_significance(
    alpha_diversity=alpha_div_faith_pd,
    metadata=metadata_md,
)
visualization_viz <- action_results$visualization

from q2_diversity._examples import alpha_group_significance_faith_pd

alpha_group_significance_faith_pd(use)

diversity bioenv¶

Find the subsets of variables in metadata whose Euclidean distances are maximally rank-correlated with distance matrix. All numeric variables in metadata will be considered, and samples which are missing data will be dropped. The output visualization will indicate how many samples were dropped due to missing data, if any were dropped.

Citations¶

Clarke & Ainsworth, 1993

Inputs¶

distance_matrix: DistanceMatrix

Matrix of distances between pairs of samples.[required]

Parameters¶

metadata: Metadata

The sample metadata.[required]

Outputs¶

visualization: Visualization

<no description>[required]

diversity beta-group-significance¶

Determine whether groups of samples are significantly different from one another using a permutation-based statistical test.

Citations¶

Anderson, 2001

Inputs¶

distance_matrix: DistanceMatrix

Matrix of distances between pairs of samples.[required]

Parameters¶

metadata: MetadataColumn[Categorical]

Categorical sample metadata column.[required]

method: Str % Choices('permanova', 'anosim', 'permdisp')

The group significance test to be applied.[default: 'permanova']

pairwise: Bool

Perform pairwise tests between all pairs of groups in addition to the test across all groups. This can be very slow if there are a lot of groups in the metadata column.[default: False]

permutations: Int

The number of permutations to be run when computing p-values.[default: 999]

Outputs¶

visualization: Visualization

<no description>[required]

diversity mantel¶

Apply a two-sided Mantel test to identify correlation between two distance matrices. Note: the directionality of the comparison has no bearing on the results. Thus, comparing distance matrix X to distance matrix Y is equivalent to comparing Y to X. Note: the order of samples within the two distance matrices does not need to be the same; the distance matrices will be reordered before applying the Mantel test. See the scikit-bio docs for more details about the Mantel test: http://scikit-bio.org/docs/latest/generated/skbio.stats.distance.mantel

Citations¶

Mantel, 1967; Pearson, 1895; Spearman, 1904

Inputs¶

dm1: DistanceMatrix

Matrix of distances between pairs of samples.[required]

dm2: DistanceMatrix

Matrix of distances between pairs of samples.[required]

Parameters¶

method: Str % Choices('spearman', 'pearson')

The correlation test to be applied in the Mantel test.[default: 'spearman']

permutations: Int % Range(0, None)

The number of permutations to be run when computing p-values. Supplying a value of zero will disable permutation testing and p-values will not be calculated (this results in much quicker execution time if p-values are not desired).[default: 999]

intersect_ids: Bool

If supplied, IDs that are not found in both distance matrices will be discarded before applying the Mantel test. Default behavior is to error on any mismatched IDs.[default: False]

label1: Str

Label for dm1 in the output visualization.[default: 'Distance Matrix 1']

label2: Str

Label for dm2 in the output visualization.[default: 'Distance Matrix 2']

Outputs¶

visualization: Visualization

<no description>[required]

diversity alpha-correlation¶

Determine whether numeric sample metadata columns are correlated with alpha diversity.

Citations¶

Pearson, 1895; Spearman, 1904

Inputs¶

alpha_diversity: SampleData[AlphaDiversity]

Vector of alpha diversity values by sample.[required]

Parameters¶

metadata: Metadata

The sample metadata.[required]

method: Str % Choices('spearman', 'pearson')

The correlation test to be applied.[default: 'spearman']

intersect_ids: Bool

If supplied, IDs that are not found in both the alpha diversity vector and metadata will be discarded before calculating the correlation. Default behavior is to error on any mismatched IDs.[default: False]

Outputs¶

visualization: Visualization

<no description>[required]

Examples¶

alpha_correlation_faith_pd¶

wget -O 'alpha-div-faith-pd.qza' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-correlation/1/alpha-div-faith-pd.qza'

wget -O 'metadata.tsv' \
  'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-correlation/1/metadata.tsv'

qiime diversity alpha-correlation \
  --i-alpha-diversity alpha-div-faith-pd.qza \
  --m-metadata-file metadata.tsv \
  --o-visualization visualization.qzv

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.diversity.actions as diversity_actions

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-correlation/1/alpha-div-faith-pd.qza'
fn = 'alpha-div-faith-pd.qza'
request.urlretrieve(url, fn)
alpha_div_faith_pd = Artifact.load(fn)

url = 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-correlation/1/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

visualization_viz, = diversity_actions.alpha_correlation(
    alpha_diversity=alpha_div_faith_pd,
    metadata=metadata_md,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
diversity_actions <- import("qiime2.plugins.diversity.actions")
request <- import("urllib")$request

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-correlation/1/alpha-div-faith-pd.qza'
fn <- 'alpha-div-faith-pd.qza'
request$urlretrieve(url, fn)
alpha_div_faith_pd <- Artifact$load(fn)

url <- 'https://amplicon-docs.qiime2.org/en/latest/data/examples/diversity/alpha-correlation/1/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- diversity_actions$alpha_correlation(
    alpha_diversity=alpha_div_faith_pd,
    metadata=metadata_md,
)
visualization_viz <- action_results$visualization

from q2_diversity._examples import alpha_correlation_faith_pd

alpha_correlation_faith_pd(use)

diversity alpha-rarefaction¶

Generate interactive alpha rarefaction curves by computing rarefactions between min_depth and max_depth. The number of intermediate depths to compute is controlled by the steps parameter, with n iterations being computed at each rarefaction depth. If sample metadata is provided, samples may be grouped based on distinct values within a metadata column.

Inputs¶

table: FeatureTable[Frequency]

Feature table to compute rarefaction curves from.[required]

phylogeny: Phylogeny[Rooted]

Optional phylogeny for phylogenetic metrics.[optional]

Parameters¶

max_depth: Int % Range(1, None)

The maximum rarefaction depth. Must be greater than min_depth.[required]

metrics: Set[Str % Choices('ace', 'berger_parker_d', 'brillouin_d', 'chao1', 'dominance', 'doubles', 'enspie', 'faith_pd', 'fisher_alpha', 'gini_index', 'goods_coverage', 'heip_e', 'lladser_pe', 'margalef', 'mcintosh_d', 'mcintosh_e', 'menhinick', 'michaelis_menten_fit', 'observed_features', 'pielou_e', 'robbins', 'shannon', 'simpson', 'simpson_e', 'singles')]

The metrics to be measured. By default computes observed_features, shannon, and if phylogeny is provided, faith_pd.[optional]

metadata: Metadata

The sample metadata.[optional]

min_depth: Int % Range(1, None)

The minimum rarefaction depth.[default: 1]

steps: Int % Range(2, None)

The number of rarefaction depths to include between min_depth and max_depth.[default: 10]

iterations: Int % Range(1, None)

The number of rarefied feature tables to compute at each step.[default: 10]

Outputs¶

visualization: Visualization

<no description>[required]

diversity beta-rarefaction¶

Repeatedly rarefy a feature table to compare beta diversity results within a given rarefaction depth. For a given beta diversity metric, this visualizer will provide: an Emperor jackknifed PCoA plot, samples clustered by UPGMA or neighbor joining with support calculation, and a heatmap showing the correlation between rarefaction trials of that beta diversity metric.

Citations¶

Mantel, 1967; Pearson, 1895; Spearman, 1904

Inputs¶

table: FeatureTable[Frequency]

Feature table upon which to perform beta diversity rarefaction analyses.[required]

phylogeny: Phylogeny[Rooted]

Phylogenetic tree containing tip identifiers that correspond to the feature identifiers in the table. This tree can contain tip ids that are not present in the table, but all feature ids in the table must be present in this tree. [required for phylogenetic metrics][optional]

Parameters¶

metric: Str % Choices('aitchison', 'braycurtis', 'canberra', 'canberra_adkins', 'chebyshev', 'cityblock', 'correlation', 'cosine', 'dice', 'euclidean', 'generalized_unifrac', 'hamming', 'jaccard', 'jensenshannon', 'matching', 'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean', 'sokalmichener', 'sokalsneath', 'sqeuclidean', 'unweighted_unifrac', 'weighted_normalized_unifrac', 'weighted_unifrac', 'yule')

The beta diversity metric to be computed.[required]

clustering_method: Str % Choices('nj', 'upgma')

Samples can be clustered with neighbor joining or UPGMA. An arbitrary rarefaction trial will be used for the tree, and the remaining trials are used to calculate the support of the internal nodes of that tree.[required]

metadata: Metadata

The sample metadata used for the Emperor jackknifed PCoA plot.[required]

sampling_depth: Int % Range(1, None)

The total frequency that each sample should be rarefied to prior to computing the diversity metric.[required]

iterations: Int % Range(2, None)

Number of times to rarefy the feature table at a given sampling depth.[default: 10]

correlation_method: Str % Choices('pearson', 'spearman')

The Mantel correlation test to be applied when computing correlation between beta diversity distance matrices.[default: 'spearman']

color_scheme: Str % Choices('BrBG', 'BrBG_r', 'PRGn', 'PRGn_r', 'PiYG', 'PiYG_r', 'PuOr', 'PuOr_r', 'RdBu', 'RdBu_r', 'RdGy', 'RdGy_r', 'RdYlBu', 'RdYlBu_r', 'RdYlGn', 'RdYlGn_r')

The matplotlib color scheme to generate the heatmap with.[default: 'BrBG']

Outputs¶

visualization: Visualization

<no description>[required]

diversity adonis¶

Determine whether groups of samples are significantly different from one another using the ADONIS permutation-based statistical test in vegan-R. The function partitions sums of squares of a multivariate data set, and is directly analogous to MANOVA (multivariate analysis of variance). This action differs from beta_group_significance in that it accepts R formulae to perform multi-way ADONIS tests; beta_group_signficance only performs one-way tests. For more details, consult the reference manual available on the CRAN vegan page: https://CRAN.R-project.org/package=vegan

Citations¶

Anderson, 2001; Oksanen et al., 2018

Inputs¶

distance_matrix: DistanceMatrix

Matrix of distances between pairs of samples.[required]

Parameters¶

metadata: Metadata

Sample metadata containing formula terms.[required]

formula: Str

Model formula containing only independent terms contained in the sample metadata. These can be continuous variables or factors, and they can have interactions as in a typical R formula. E.g., the formula "treatment+block" would test whether the input distance matrix partitions based on "treatment" and "block" sample metadata. The formula "treatment*block" would test both of those effects as well as their interaction. Enclose formulae in quotes to avoid unpleasant surprises.[required]

permutations: Int % Range(1, None)

The number of permutations to be run when computing p-values.[default: 999]

n_jobs: Threads

Number of parallel processes to run.[default: 1]

Outputs¶

visualization: Visualization

<no description>[required]

diversity beta-phylogenetic¶

Computes a user-specified phylogenetic beta diversity metric for all pairs of samples in a feature table.

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The feature table containing the samples over which beta diversity should be computed.[required]

phylogeny: Phylogeny[Rooted]

Phylogenetic tree containing tip identifiers that correspond to the feature identifiers in the table. This tree can contain tip ids that are not present in the table, but all feature ids in the table must be present in this tree.[required]

Parameters¶

metric: Str % Choices('generalized_unifrac', 'unweighted_unifrac', 'weighted_normalized_unifrac', 'weighted_unifrac')

The beta diversity metric to be computed.[required]

threads: Threads

The number of CPU threads to use in performing this calculation. May not exceed the number of available physical cores. If threads = 'auto', one thread will be created for each identified CPU core on the host.[default: 1]

variance_adjusted: Bool

Perform variance adjustment based on Chang et al. BMC Bioinformatics 2011. Weights distances based on the proportion of the relative abundance represented between the samples at a given node under evaluation.[default: False]

alpha: Float % Range(0, 1, inclusive_end=True)

This parameter is only used when the choice of metric is generalized_unifrac. The value of alpha controls importance of sample proportions. 1.0 is weighted normalized UniFrac. 0.0 is close to unweighted UniFrac, but only if the sample proportions are dichotomized.[optional]

bypass_tips: Bool

In a bifurcating tree, the tips make up about 50% of the nodes in a tree. By ignoring them, specificity can be traded for reduced compute time. This has the effect of collapsing the phylogeny, and is analogous (in concept) to moving from 99% to 97% OTUs[default: False]

Outputs¶

distance_matrix: DistanceMatrix

The resulting distance matrix.[required]

diversity beta¶

Computes a user-specified beta diversity metric for all pairs of samples in a feature table.

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The feature table containing the samples over which beta diversity should be computed.[required]

Parameters¶

metric: Str % Choices('aitchison', 'braycurtis', 'canberra', 'canberra_adkins', 'chebyshev', 'cityblock', 'correlation', 'cosine', 'dice', 'euclidean', 'hamming', 'jaccard', 'jensenshannon', 'matching', 'minkowski', 'rogerstanimoto', 'russellrao', 'seuclidean', 'sokalmichener', 'sokalsneath', 'sqeuclidean', 'yule')

The beta diversity metric to be computed.[required]

pseudocount: Int % Range(1, None)

A pseudocount to handle zeros for compositional metrics. This is ignored for other metrics.[default: 1]

n_jobs: Threads

The number of concurrent jobs to use in performing this calculation. May not exceed the number of available physical cores. If n_jobs = 'auto', one job will be launched for each identified CPU core on the host.[default: 1]

Outputs¶

distance_matrix: DistanceMatrix

The resulting distance matrix.[required]

diversity alpha-phylogenetic¶

Computes a user-specified phylogenetic alpha diversity metric for all samples in a feature table.

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The feature table containing the samples for which alpha diversity should be computed.[required]

phylogeny: Phylogeny[Rooted]

Phylogenetic tree containing tip identifiers that correspond to the feature identifiers in the table. This tree can contain tip ids that are not present in the table, but all feature ids in the table must be present in this tree.[required]

Parameters¶

metric: Str % Choices('faith_pd')

The alpha diversity metric to be computed.[required]

Outputs¶

alpha_diversity: SampleData[AlphaDiversity]

Vector containing per-sample alpha diversities.[required]

diversity alpha¶

Computes a user-specified alpha diversity metric for all samples in a feature table.

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The feature table containing the samples for which alpha diversity should be computed.[required]

Parameters¶

metric: Str % Choices('ace', 'berger_parker_d', 'brillouin_d', 'chao1', 'chao1_ci', 'dominance', 'doubles', 'enspie', 'esty_ci', 'fisher_alpha', 'gini_index', 'goods_coverage', 'heip_e', 'kempton_taylor_q', 'lladser_pe', 'margalef', 'mcintosh_d', 'mcintosh_e', 'menhinick', 'michaelis_menten_fit', 'observed_features', 'osd', 'pielou_e', 'robbins', 'shannon', 'simpson', 'simpson_e', 'singles', 'strong')

The alpha diversity metric to be computed. Information about specific metrics is available at https://scikit.bio/docs/latest/generated/skbio.diversity.alpha.html.[required]

Outputs¶

alpha_diversity: SampleData[AlphaDiversity]

Vector containing per-sample alpha diversities.[required]

diversity core-metrics-phylogenetic¶

Applies a collection of diversity metrics (both phylogenetic and non-phylogenetic) to a feature table.

Inputs¶

table: FeatureTable[Frequency]

The feature table containing the samples over which diversity metrics should be computed.[required]

phylogeny: Phylogeny[Rooted]

Phylogenetic tree containing tip identifiers that correspond to the feature identifiers in the table. This tree can contain tip ids that are not present in the table, but all feature ids in the table must be present in this tree.[required]

Parameters¶

sampling_depth: Int % Range(1, None)

The total frequency that each sample should be rarefied to prior to computing diversity metrics.[required]

metadata: Metadata

The sample metadata to use in the emperor plots.[required]

with_replacement: Bool

Rarefy with replacement by sampling from the multinomial distribution instead of rarefying without replacement.[default: False]

n_jobs_or_threads: Threads

[beta/beta-phylogenetic methods only] - The number of concurrent jobs or CPU threads to use in performing this calculation. Individual methods will create jobs/threads as implemented in q2-diversity-lib dependencies. May not exceed the number of available physical cores. If n_jobs_or_threads = 'auto', one thread/job will be created for each identified CPU core on the host.[default: 1]

ignore_missing_samples: Bool

If set to True samples and features without metadata are included by setting all metadata values to: "This element has no metadata". By default an exception will be raised if missing elements are encountered. Note, this flag only takes effect if there is at least one overlapping element.[default: False]

Outputs¶

rarefied_table: FeatureTable[Frequency]

The resulting rarefied feature table.[required]

faith_pd_vector: SampleData[AlphaDiversity]

Vector of Faith PD values by sample.[required]

observed_features_vector: SampleData[AlphaDiversity]

Vector of Observed Features values by sample.[required]

shannon_vector: SampleData[AlphaDiversity]

Vector of Shannon diversity values by sample.[required]

evenness_vector: SampleData[AlphaDiversity]

Vector of Pielou's evenness values by sample.[required]

unweighted_unifrac_distance_matrix: DistanceMatrix

Matrix of unweighted UniFrac distances between pairs of samples.[required]

weighted_unifrac_distance_matrix: DistanceMatrix

Matrix of weighted UniFrac distances between pairs of samples.[required]

jaccard_distance_matrix: DistanceMatrix

Matrix of Jaccard distances between pairs of samples.[required]

bray_curtis_distance_matrix: DistanceMatrix

Matrix of Bray-Curtis distances between pairs of samples.[required]

unweighted_unifrac_pcoa_results: PCoAResults

PCoA matrix computed from unweighted UniFrac distances between samples.[required]

weighted_unifrac_pcoa_results: PCoAResults

PCoA matrix computed from weighted UniFrac distances between samples.[required]

jaccard_pcoa_results: PCoAResults

PCoA matrix computed from Jaccard distances between samples.[required]

bray_curtis_pcoa_results: PCoAResults

PCoA matrix computed from Bray-Curtis distances between samples.[required]

unweighted_unifrac_emperor: Visualization

Emperor plot of the PCoA matrix computed from unweighted UniFrac.[required]

weighted_unifrac_emperor: Visualization

Emperor plot of the PCoA matrix computed from weighted UniFrac.[required]

jaccard_emperor: Visualization

Emperor plot of the PCoA matrix computed from Jaccard.[required]

bray_curtis_emperor: Visualization

Emperor plot of the PCoA matrix computed from Bray-Curtis.[required]

diversity core-metrics¶

Applies a collection of diversity metrics (non-phylogenetic) to a feature table.

Inputs¶

table: FeatureTable[Frequency]

The feature table containing the samples over which diversity metrics should be computed.[required]

Parameters¶

sampling_depth: Int % Range(1, None)

The total frequency that each sample should be rarefied to prior to computing diversity metrics.[required]

metadata: Metadata

The sample metadata to use in the emperor plots.[required]

with_replacement: Bool

Rarefy with replacement by sampling from the multinomial distribution instead of rarefying without replacement.[default: False]

n_jobs: Threads

[beta methods only] - The number of concurrent jobs to use in performing this calculation. May not exceed the number of available physical cores. If n_jobs = 'auto', one job will be launched for each identified CPU core on the host.[default: 1]

ignore_missing_samples: Bool

If set to True samples and features without metadata are included by setting all metadata values to: "This element has no metadata". By default an exception will be raised if missing elements are encountered. Note, this flag only takes effect if there is at least one overlapping element.[default: False]

Outputs¶

rarefied_table: FeatureTable[Frequency]

The resulting rarefied feature table.[required]

observed_features_vector: SampleData[AlphaDiversity]

Vector of Observed Features values by sample.[required]

shannon_vector: SampleData[AlphaDiversity]

Vector of Shannon diversity values by sample.[required]

evenness_vector: SampleData[AlphaDiversity]

Vector of Pielou's evenness values by sample.[required]

jaccard_distance_matrix: DistanceMatrix

Matrix of Jaccard distances between pairs of samples.[required]

bray_curtis_distance_matrix: DistanceMatrix

Matrix of Bray-Curtis distances between pairs of samples.[required]

jaccard_pcoa_results: PCoAResults

PCoA matrix computed from Jaccard distances between samples.[required]

bray_curtis_pcoa_results: PCoAResults

PCoA matrix computed from Bray-Curtis distances between samples.[required]

jaccard_emperor: Visualization

Emperor plot of the PCoA matrix computed from Jaccard.[required]

bray_curtis_emperor: Visualization

Emperor plot of the PCoA matrix computed from Bray-Curtis.[required]

diversity beta-correlation¶

Create a distance matrix from a numeric metadata column and apply a two-sided Mantel test to identify correlation between two distance matrices. Actions used internally: distance-matrix from q2-metadata and mantel from q2-diversity.

Inputs¶

distance_matrix: DistanceMatrix

Matrix of distances between pairs of samples.[required]

Parameters¶

metadata: MetadataColumn[Numeric]

Numeric metadata column from which to compute pairwise Euclidean distances[required]

method: Str % Choices('spearman', 'pearson')

The correlation test to be applied in the Mantel test.[default: 'spearman']

permutations: Int % Range(0, None)

The number of permutations to be run when computing p-values. Supplying a value of zero will disable permutation testing and p-values will not be calculated (this results in much quicker execution time if p-values are not desired).[default: 999]

intersect_ids: Bool

If supplied, IDs that are not found in both distance matrices will be discarded before applying the Mantel test. Default behavior is to error on any mismatched IDs.[default: False]

label1: Str

Label for distance_matrix in the output visualization.[default: 'Distance Matrix']

label2: Str

Label for metadata_distance_matrix in the output visualization.[default: 'Metadata']

Outputs¶

metadata_distance_matrix: DistanceMatrix

The Distance Matrix produced from the metadata column and used in the mantel test[required]

mantel_scatter_visualization: Visualization

Scatter plot rendering of the manteltest results[required]