q2-boots

A plugin providing bootstrapped and rarefaction-based (i.e., resampled) diversity analyses, designed to mirror the interface of q2-diversity.

version: 0.0.1+65.g7560f82

website: https://library.qiime2.org/plugins/caporaso-lab/q2-boots

user support:

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

citations:

Raspet et al., 2025

Actions¶

boots alpha-average¶

Compute the per-sample average across a collection of alpha diversity vectors computed from the same samples.

Citations¶

Raspet et al., 2025

Inputs¶

data: Collection[SampleData[AlphaDiversity]]

Alpha diversity vectors to be averaged.[required]

Parameters¶

average_method: Str % Choices('mean', 'median')

Method to use for averaging.[required]

Outputs¶

average_alpha_diversity: SampleData[AlphaDiversity]

The average alpha diversity vector.[required]

boots beta-average¶

Compute the average distance matrix across a collection of distance matrices.

Citations¶

Raspet et al., 2025

Inputs¶

data: Collection[DistanceMatrix]

Distance matrices to be average.[required]

Parameters¶

average_method: Str % Choices('non-metric-mean', 'non-metric-median', 'medoid')

Method to use for averaging.[required]

Outputs¶

average_distance_matrix: DistanceMatrix

The average distance matrix.[required]

boots resample¶

Resample table to sampling_depth total observations with replacement (i.e., bootstrapping) or without replacement (i.e., rarefaction) n times, to generate n resampled feature tables.

Citations¶

Raspet et al., 2025

Inputs¶

table: FeatureTable[Frequency]

The input feature table.[required]

Parameters¶

sampling_depth: Int % Range(1, None)

The total number of observations that each sample in table should be resampled to. Samples where the total number of observations in table is less than sampling_depth will be not be included in the output tables.[required]

n: Int % Range(1, None)

The number of resampled tables that should be generated.[required]

replacement: Bool

Resample table with replacement (i.e., bootstrap) or without replacement (i.e., rarefaction).[required]

Outputs¶

resampled_tables: Collection[FeatureTable[Frequency]]

The n resampled tables.[required]

Examples¶

Generate 10 bootstrapped tables.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/resample/1/table.qza'

qiime boots resample \
  --i-table table.qza \
  --p-sampling-depth 20 \
  --p-n 10 \
  --p-replacement \
  --o-resampled-tables bootstrapped-tables/

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/resample/1/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

bootstrapped_tables_artifact_collection, = boots_actions.resample(
    table=table,
    sampling_depth=20,
    n=10,
    replacement=True,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/resample/1/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

action_results <- boots_actions$resample(
    table=table,
    sampling_depth=20L,
    n=10L,
    replacement=TRUE,
)
bootstrapped_tables_artifact_collection <- action_results$resampled_tables

from q2_boots._examples import _resample_bootstrap_example

_resample_bootstrap_example(use)

Generate 10 rarefied tables.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/resample/2/table.qza'

qiime boots resample \
  --i-table table.qza \
  --p-sampling-depth 20 \
  --p-n 10 \
  --p-no-replacement \
  --o-resampled-tables rarefaction-tables/

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/resample/2/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

rarefaction_tables_artifact_collection, = boots_actions.resample(
    table=table,
    sampling_depth=20,
    n=10,
    replacement=False,
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/resample/2/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

action_results <- boots_actions$resample(
    table=table,
    sampling_depth=20L,
    n=10L,
    replacement=FALSE,
)
rarefaction_tables_artifact_collection <- action_results$resampled_tables

from q2_boots._examples import _resample_rarefaction_example

_resample_rarefaction_example(use)

boots alpha-collection¶

Given a single feature table as input, this action resamples the feature table n times to a total frequency of sampling depth per sample, and then computes the specified alpha diversity metric on each resulting table. The resulting artifacts can be used, for example, to explore the variance across n iterations of resampling.

Citations¶

Raspet et al., 2025

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The input feature table.[required]

phylogeny: Phylogeny[Rooted]

The phylogenetic tree to use in phylogenetic diversity calculations. All feature ids in table must be present in this tree, but this tree can contain feature ids that are not present in table.[optional]

Parameters¶

sampling_depth: Int % Range(1, None)

The total number of observations that each sample in table should be resampled to. Samples where the total number of observations in table is less than sampling_depth will be not be included in the output tables.[required]

metric: Str % Choices('ace', 'berger_parker_d', 'brillouin_d', 'chao1', 'chao1_ci', 'dominance', 'doubles', 'enspie', 'esty_ci', 'faith_pd', '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.[required]

n: Int % Range(1, None)

The number of resampled tables that should be generated.[required]

replacement: Bool

Resample table with replacement (i.e., bootstrap) or without replacement (i.e., rarefaction).[required]

Outputs¶

alpha_diversities: Collection[SampleData[AlphaDiversity]]

n alpha diversity vectors, each containing per-sample alpha diversity scores for the same samples.[required]

boots alpha¶

Given a single feature table as input, this action resamples the feature table n times to a total frequency of sampling depth per sample, and then computes the specified alpha diversity metric on each resulting table. The resulting artifacts are then averaged using the method specified by average_method, and the resulting average per-sample alpha diversities are returned.

Citations¶

Raspet et al., 2025

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The input feature table.[required]

phylogeny: Phylogeny[Rooted]

The phylogenetic tree to use in phylogenetic diversity calculations. All feature ids in table must be present in this tree, but this tree can contain feature ids that are not present in table.[optional]

Parameters¶

sampling_depth: Int % Range(1, None)

The total number of observations that each sample in table should be resampled to. Samples where the total number of observations in table is less than sampling_depth will be not be included in the output tables.[required]

metric: Str % Choices('ace', 'berger_parker_d', 'brillouin_d', 'chao1', 'chao1_ci', 'dominance', 'doubles', 'enspie', 'esty_ci', 'faith_pd', '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.[required]

n: Int % Range(1, None)

The number of resampled tables that should be generated.[required]

replacement: Bool

Resample table with replacement (i.e., bootstrap) or without replacement (i.e., rarefaction).[required]

average_method: Str % Choices('mean', 'median')

Method to use for averaging.[default: 'median']

Outputs¶

average_alpha_diversity: SampleData[AlphaDiversity]

The average alpha diversity vector.[required]

Examples¶

Bootstrapped observed features.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/alpha/1/table.qza'

qiime boots alpha \
  --i-table table.qza \
  --p-sampling-depth 20 \
  --p-metric observed_features \
  --p-n 10 \
  --p-replacement \
  --p-average-method median \
  --o-average-alpha-diversity observed-features-bootstrapped.qza

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/alpha/1/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

observed_features_bootstrapped, = boots_actions.alpha(
    table=table,
    sampling_depth=20,
    metric='observed_features',
    n=10,
    replacement=True,
    average_method='median',
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/alpha/1/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

action_results <- boots_actions$alpha(
    table=table,
    sampling_depth=20L,
    metric='observed_features',
    n=10L,
    replacement=TRUE,
    average_method='median',
)
observed_features_bootstrapped <- action_results$average_alpha_diversity

from q2_boots._examples import _alpha_bootstrap_example

_alpha_bootstrap_example(use)

Rarefaction-based observed features.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/alpha/2/table.qza'

qiime boots alpha \
  --i-table table.qza \
  --p-sampling-depth 20 \
  --p-metric observed_features \
  --p-n 10 \
  --p-no-replacement \
  --p-average-method median \
  --o-average-alpha-diversity observed-features-rarefaction.qza

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/alpha/2/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

observed_features_rarefaction, = boots_actions.alpha(
    table=table,
    sampling_depth=20,
    metric='observed_features',
    n=10,
    replacement=False,
    average_method='median',
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/alpha/2/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

action_results <- boots_actions$alpha(
    table=table,
    sampling_depth=20L,
    metric='observed_features',
    n=10L,
    replacement=FALSE,
    average_method='median',
)
observed_features_rarefaction <- action_results$average_alpha_diversity

from q2_boots._examples import _alpha_rarefaction_example

_alpha_rarefaction_example(use)

boots beta-collection¶

Given a single feature table as input, this action resamples the feature table n times to a total frequency of sampling depth per sample, and then computes the specified beta diversity metric on each resulting table. The resulting artifacts can be used, for example, to explore the variance across n iterations of resampling.

Citations¶

Raspet et al., 2025

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The input feature table.[required]

phylogeny: Phylogeny[Rooted]

The phylogenetic tree to use in phylogenetic diversity calculations. All feature ids in table must be present in this tree, but this tree can contain feature ids that are not present in table.[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]

sampling_depth: Int % Range(1, None)

The total number of observations that each sample in table should be resampled to. Samples where the total number of observations in table is less than sampling_depth will be not be included in the output tables.[required]

n: Int % Range(1, None)

The number of resampled tables that should be generated.[required]

replacement: Bool

Resample table with replacement (i.e., bootstrap) or without replacement (i.e., rarefaction).[required]

bypass_tips: Bool

Ignore tips of tree in phylogenetic diversity calculations, trading specificity 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]

pseudocount: Int % Range(1, None)

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

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

The alpha value used with the generalized UniFrac metric.[optional]

variance_adjusted: Bool

Perform variance adjustment based on Chang et al. BMC Bioinformatics (2011) for phylogenetic diversity metrics.[default: False]

Outputs¶

distance_matrices: Collection[DistanceMatrix]

n beta diversity distance matrices, each containing distances between all pairs of samples and computed from resampled feature tables.[required]

Examples¶

Bootstrapped Bray-Curtis.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/beta-collection/1/table.qza'

qiime boots beta \
  --i-table table.qza \
  --p-metric braycurtis \
  --p-sampling-depth 20 \
  --p-n 10 \
  --p-replacement \
  --p-average-method medoid \
  --o-average-distance-matrix braycurtis-bootstrapped.qza

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/beta-collection/1/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

braycurtis_bootstrapped, = boots_actions.beta(
    table=table,
    metric='braycurtis',
    sampling_depth=20,
    n=10,
    replacement=True,
    average_method='medoid',
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/beta-collection/1/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

action_results <- boots_actions$beta(
    table=table,
    metric='braycurtis',
    sampling_depth=20L,
    n=10L,
    replacement=TRUE,
    average_method='medoid',
)
braycurtis_bootstrapped <- action_results$average_distance_matrix

from q2_boots._examples import _beta_bootstrap_example

_beta_bootstrap_example(use)

Rarefaction-based Bray-Curtis.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/beta-collection/2/table.qza'

qiime boots beta \
  --i-table table.qza \
  --p-sampling-depth 20 \
  --p-metric braycurtis \
  --p-n 10 \
  --p-no-replacement \
  --p-average-method medoid \
  --o-average-distance-matrix braycurtis-rarefaction.qza

from qiime2 import Artifact
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/beta-collection/2/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

braycurtis_rarefaction, = boots_actions.beta(
    table=table,
    sampling_depth=20,
    metric='braycurtis',
    n=10,
    replacement=False,
    average_method='medoid',
)

library(reticulate)

Artifact <- import("qiime2")$Artifact
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/beta-collection/2/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

action_results <- boots_actions$beta(
    table=table,
    sampling_depth=20L,
    metric='braycurtis',
    n=10L,
    replacement=FALSE,
    average_method='medoid',
)
braycurtis_rarefaction <- action_results$average_distance_matrix

from q2_boots._examples import _beta_rarefaction_example

_beta_rarefaction_example(use)

boots beta¶

Given a single feature table as input, this action resamples the feature table n times to a total frequency of sampling depth per sample, and then computes the specified beta diversity metric on each resulting table. The resulting artifacts are then averaged using the method specified by average_method, and the resulting average beta diversity distance matrix is returned.

Citations¶

Raspet et al., 2025

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The input feature table.[required]

phylogeny: Phylogeny[Rooted]

The phylogenetic tree to use in phylogenetic diversity calculations. All feature ids in table must be present in this tree, but this tree can contain feature ids that are not present in table.[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]

sampling_depth: Int % Range(1, None)

The total number of observations that each sample in table should be resampled to. Samples where the total number of observations in table is less than sampling_depth will be not be included in the output tables.[required]

n: Int % Range(1, None)

The number of resampled tables that should be generated.[required]

replacement: Bool

Resample table with replacement (i.e., bootstrap) or without replacement (i.e., rarefaction).[required]

average_method: Str % Choices('non-metric-mean', 'non-metric-median', 'medoid')

Method to use for averaging.[default: 'non-metric-median']

bypass_tips: Bool

Ignore tips of tree in phylogenetic diversity calculations, trading specificity 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]

pseudocount: Int % Range(1, None)

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

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

The alpha value used with the generalized UniFrac metric.[optional]

variance_adjusted: Bool

Perform variance adjustment based on Chang et al. BMC Bioinformatics (2011) for phylogenetic diversity metrics.[default: False]

Outputs¶

average_distance_matrix: DistanceMatrix

The average distance matrix.[required]

boots core-metrics¶

Given a single feature table as input, this action resamples the feature table n times to a total frequency of sampling depth per sample, and then computes common alpha and beta diversity on each resulting table. The resulting artifacts are then averaged using the method specified by alpha_average_method and beta_average_method parameters. The resulting average alpha and beta diversity artifacts are returned, along with PCoA matrices, Emperor plots, and a 2D scatter plot including alpha diversity values and PCoA of all beta diversity metrics.

Citations¶

Raspet et al., 2025

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The input feature table.[required]

phylogeny: Phylogeny[Rooted]

The phylogenetic tree to use in phylogenetic diversity calculations. All feature ids in table must be present in this tree, but this tree can contain feature ids that are not present in table.[optional]

Parameters¶

sampling_depth: Int % Range(1, None)

The total number of observations that each sample in table should be resampled to. Samples where the total number of observations in table is less than sampling_depth will be not be included in the output tables.[required]

metadata: Metadata

The sample metadata used in generating Emperor plots.[required]

n: Int % Range(1, None)

The number of resampled tables that should be generated.[required]

replacement: Bool

Resample table with replacement (i.e., bootstrap) or without replacement (i.e., rarefaction).[required]

alpha_average_method: Str % Choices('mean', 'median')

Method to use for averaging alpha diversity.[default: 'median']

beta_average_method: Str % Choices('non-metric-mean', 'non-metric-median', 'medoid')

Method to use for averaging beta diversity.[default: 'non-metric-median']

pc_dimensions: Int

Number of principal coordinate dimensions to present in the 2D scatterplot.[default: 3]

color_by: Str

Categorical measure from the input Metadata that should be used for color-coding the 2D scatterplot.[optional]

Outputs¶

resampled_tables: Collection[FeatureTable[Frequency]]

The n resampled tables.[required]

alpha_diversities: Collection[SampleData[AlphaDiversity]]

Average alpha diversity vector for each metric.[required]

distance_matrices: Collection[DistanceMatrix]

Average beta diversity distance matrix for each metric.[required]

pcoas: Collection[PCoAResults]

PCoA matrix for each beta diversity metric.[required]

emperor_plots: Collection[Visualization]

Emperor plot for each beta diversity metric.[required]

scatter_plot: Visualization

2D scatter plot including alpha diversity and pcoa results for all selected metrics.[required]

Examples¶

Bootstrapped core metrics.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/1/table.qza'

wget -O 'metadata.tsv' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/1/metadata.tsv'

qiime boots core-metrics \
  --i-table table.qza \
  --m-metadata-file metadata.tsv \
  --p-sampling-depth 20 \
  --p-n 10 \
  --p-replacement \
  --p-alpha-average-method median \
  --p-beta-average-method medoid \
  --output-dir boots-core-metrics

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/1/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/1/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

action_results = boots_actions.core_metrics(
    table=table,
    metadata=metadata_md,
    sampling_depth=20,
    n=10,
    replacement=True,
    alpha_average_method='median',
    beta_average_method='medoid',
)
bootstrap_tables_artifact_collection = action_results.resampled_tables
bootstrap_alpha_diversities_artifact_collection = action_results.alpha_diversities
bootstrap_distance_matrices_artifact_collection = action_results.distance_matrices
bootstrap_pcoas_artifact_collection = action_results.pcoas
bootstrap_emperor_plots_viz_collection = action_results.emperor_plots
scatter_plot_viz = action_results.scatter_plot

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/1/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/1/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- boots_actions$core_metrics(
    table=table,
    metadata=metadata_md,
    sampling_depth=20L,
    n=10L,
    replacement=TRUE,
    alpha_average_method='median',
    beta_average_method='medoid',
)
bootstrap_tables_artifact_collection <- action_results$resampled_tables
bootstrap_alpha_diversities_artifact_collection <- action_results$alpha_diversities
bootstrap_distance_matrices_artifact_collection <- action_results$distance_matrices
bootstrap_pcoas_artifact_collection <- action_results$pcoas
bootstrap_emperor_plots_viz_collection <- action_results$emperor_plots
scatter_plot_viz <- action_results$scatter_plot

from q2_boots._examples import _core_metrics_bootstrap_example

_core_metrics_bootstrap_example(use)

Rarefaction-based core metrics.¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/2/table.qza'

wget -O 'metadata.tsv' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/2/metadata.tsv'

qiime boots core-metrics \
  --i-table table.qza \
  --m-metadata-file metadata.tsv \
  --p-sampling-depth 20 \
  --p-n 10 \
  --p-no-replacement \
  --p-alpha-average-method median \
  --p-beta-average-method medoid \
  --output-dir boots-core-metrics

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/2/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/2/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

action_results = boots_actions.core_metrics(
    table=table,
    metadata=metadata_md,
    sampling_depth=20,
    n=10,
    replacement=False,
    alpha_average_method='median',
    beta_average_method='medoid',
)
rarefaction_tables_artifact_collection = action_results.resampled_tables
rarefaction_alpha_diversities_artifact_collection = action_results.alpha_diversities
rarefaction_distance_matrices_artifact_collection = action_results.distance_matrices
rarefaction_pcoas_artifact_collection = action_results.pcoas
rarefaction_emperor_plots_viz_collection = action_results.emperor_plots
scatter_plot_viz = action_results.scatter_plot

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/2/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/core-metrics/2/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- boots_actions$core_metrics(
    table=table,
    metadata=metadata_md,
    sampling_depth=20L,
    n=10L,
    replacement=FALSE,
    alpha_average_method='median',
    beta_average_method='medoid',
)
rarefaction_tables_artifact_collection <- action_results$resampled_tables
rarefaction_alpha_diversities_artifact_collection <- action_results$alpha_diversities
rarefaction_distance_matrices_artifact_collection <- action_results$distance_matrices
rarefaction_pcoas_artifact_collection <- action_results$pcoas
rarefaction_emperor_plots_viz_collection <- action_results$emperor_plots
scatter_plot_viz <- action_results$scatter_plot

from q2_boots._examples import _core_metrics_rarefaction_example

_core_metrics_rarefaction_example(use)

boots kmer-diversity¶

Given a single feature table as input, this action resamples the feature table n times to a total frequency of sampling depth per sample. It then splits all input sequences into kmers, and computes common alpha and beta diversity on each resulting kmer table. The resulting artifacts are then averaged using the method specified by alpha_average_method and beta_average_method parameters. The resulting average alpha and beta diversity artifacts are returned, along with a scatter plot integrated all alpha diversity metrics and the PCoA axes for all beta diversity metrics.

Citations¶

Raspet et al., 2025; Bokulich, 2025

Inputs¶

table: FeatureTable[Frequency | RelativeFrequency | PresenceAbsence]

The input feature table.[required]

sequences: FeatureData[Sequence | RNASequence | ProteinSequence]

Input sequences for kmerization.[required]

Parameters¶

sampling_depth: Int % Range(1, None)

The total number of observations that each sample in table should be resampled to. Samples where the total number of observations in table is less than sampling_depth will be not be included in the output tables.[required]

metadata: Metadata

The sample metadata used in generating Emperor plots.[required]

n: Int % Range(1, None)

The number of resampled tables that should be generated.[required]

replacement: Bool

Resample table with replacement (i.e., bootstrap) or without replacement (i.e., rarefaction).[required]

kmer_size: Int

Length of kmers to generate.[default: 16]

tfidf: Bool

If True, kmers will be scored using TF-IDF and output frequencies will be weighted by scores. If False, kmers are counted without TF-IDF scores.[default: False]

max_df: Float % Range(0, 1, inclusive_end=True) | Int

Ignore kmers that have a frequency strictly higher than the given threshold. If float, the parameter represents a proportion of sequences, if an integer it represents an absolute count.[default: 1.0]

min_df: Float % Range(0, 1) | Int

Ignore kmers that have a frequency strictly lower than the given threshold. If float, the parameter represents a proportion of sequences, if an integer it represents an absolute count.[default: 1]

max_features: Int

If not None, build a vocabulary that only considers the top max_features ordered by frequency (or TF-IDF score).[optional]

alpha_average_method: Str % Choices('mean', 'median')

Method to use for averaging alpha diversity.[default: 'median']

beta_average_method: Str % Choices('non-metric-mean', 'non-metric-median', 'medoid')

Method to use for averaging beta diversity.[default: 'non-metric-median']

pc_dimensions: Int

Number of principal coordinate dimensions to present in the 2D scatterplot.[default: 3]

color_by: Str

Categorical measure from the input Metadata that should be used for color-coding the 2D scatterplot.[optional]

norm: Str % Choices('None', 'l1', 'l2')

Normalization procedure applied to TF-IDF scores. Ignored if tfidf=False. l2: Sum of squares of vector elements is 1. l1: Sum of absolute values of vector elements is 1.[default: 'None']

alpha_metrics: List[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')]

<no description>[default: ['pielou_e', 'observed_features', 'shannon']]

beta_metrics: List[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')]

<no description>[default: ['braycurtis', 'jaccard']]

Outputs¶

resampled_tables: Collection[FeatureTable[Frequency]]

The n resampled tables.[required]

kmer_tables: Collection[FeatureTable[Frequency]]

The n kmer tables.[required]

alpha_diversities: Collection[SampleData[AlphaDiversity]]

Average alpha diversity vector for each metric.[required]

distance_matrices: Collection[DistanceMatrix]

Average beta diversity distance matrix for each metric.[required]

pcoas: Collection[PCoAResults]

PCoA matrix for each beta diversity metric.[required]

scatter_plot: Visualization

2D scatter plot including alpha diversity and pcoa results for all selected metrics.[required]

Examples¶

Bootstrapped kmer diversity¶

wget -O 'table.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/table.qza'

wget -O 'sequences.qza' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/sequences.qza'

wget -O 'metadata.tsv' \
  'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/metadata.tsv'

qiime boots kmer-diversity \
  --i-table table.qza \
  --i-sequences sequences.qza \
  --m-metadata-file metadata.tsv \
  --p-sampling-depth 20 \
  --p-n 10 \
  --p-kmer-size 5 \
  --p-replacement \
  --p-alpha-average-method median \
  --p-beta-average-method medoid \
  --output-dir boots-kmer-diversity

from qiime2 import Artifact
from qiime2 import Metadata
from urllib import request
import qiime2.plugins.boots.actions as boots_actions

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/table.qza'
fn = 'table.qza'
request.urlretrieve(url, fn)
table = Artifact.load(fn)

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/sequences.qza'
fn = 'sequences.qza'
request.urlretrieve(url, fn)
sequences = Artifact.load(fn)

url = 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/metadata.tsv'
fn = 'metadata.tsv'
request.urlretrieve(url, fn)
metadata_md = Metadata.load(fn)

action_results = boots_actions.kmer_diversity(
    table=table,
    sequences=sequences,
    metadata=metadata_md,
    sampling_depth=20,
    n=10,
    kmer_size=5,
    replacement=True,
    alpha_average_method='median',
    beta_average_method='medoid',
)
bootstrap_tables_artifact_collection = action_results.resampled_tables
kmer_tables_artifact_collection = action_results.kmer_tables
bootstrap_alpha_diversities_artifact_collection = action_results.alpha_diversities
bootstrap_distance_matrices_artifact_collection = action_results.distance_matrices
bootstrap_pcoas_artifact_collection = action_results.pcoas
scatter_plot_viz = action_results.scatter_plot

library(reticulate)

Artifact <- import("qiime2")$Artifact
Metadata <- import("qiime2")$Metadata
boots_actions <- import("qiime2.plugins.boots.actions")
request <- import("urllib")$request

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/table.qza'
fn <- 'table.qza'
request$urlretrieve(url, fn)
table <- Artifact$load(fn)

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/sequences.qza'
fn <- 'sequences.qza'
request$urlretrieve(url, fn)
sequences <- Artifact$load(fn)

url <- 'https://q2-boots.readthedocs.io/en/latest/data/examples/boots/kmer-diversity/1/metadata.tsv'
fn <- 'metadata.tsv'
request$urlretrieve(url, fn)
metadata_md <- Metadata$load(fn)

action_results <- boots_actions$kmer_diversity(
    table=table,
    sequences=sequences,
    metadata=metadata_md,
    sampling_depth=20L,
    n=10L,
    kmer_size=5L,
    replacement=TRUE,
    alpha_average_method='median',
    beta_average_method='medoid',
)
bootstrap_tables_artifact_collection <- action_results$resampled_tables
kmer_tables_artifact_collection <- action_results$kmer_tables
bootstrap_alpha_diversities_artifact_collection <- action_results$alpha_diversities
bootstrap_distance_matrices_artifact_collection <- action_results$distance_matrices
bootstrap_pcoas_artifact_collection <- action_results$pcoas
scatter_plot_viz <- action_results$scatter_plot

from q2_boots._examples import _kmer_diversity_bootstrap_example

_kmer_diversity_bootstrap_example(use)