q2-boots 🥾

q2-boots 🥾#

q2-boots is a QIIME 2 plugin providing bootstrapped and rarefaction-based (collectively, resampled) alpha and beta diversity analyses, designed to mirror the interface of q2-diversity.

Development status

q2-boots is in beta release. It is sufficiently validated and ready for real-world data analysis, but interfaces are still subject to change. For example, default parameter settings, command names, and outputs generated by specific commands may evolve as we get usability feedback and feature requests from users.

Installing#

Step 1: Install prerequisites#

Miniconda provides the conda environment and package manager, and is currently the only supported way to install QIIME 2. Follow the instructions for downloading and installing Miniconda.

After installing Miniconda and opening a new terminal, make sure you’re running the latest version of conda.

conda update conda

Step 2: Install q2-boots#

Installing the release version of q2-boots allows you to access the most stable version of the functionality in a QIIME 2 2024.10 release environment. This is most convenient if you need to reference a specific version of q2-boots in a publication (you would refer to it as the 2024.10.beta release of q2-boots.) Since q2-boots is still under active development, there may be some new functionality that isn’t included in this release.

conda env create \
  -n q2-boots-2024.10.beta \
  -f https://raw.githubusercontent.com/qiime2/q2-boots/main/environment-files/q2-boots-qiime2-amplicon-2024.10.yml

conda activate q2-boots-2024.10.beta

Installing the most recent development version of q2-boots allows you to access the most recent functionality, including some that depends on features being introduced in the 2025.4 version of the QIIME 2 Framework. 🔧 Referencing specific versions of q2-boots is still possible — just be sure to hang on to your QIIME 2 Results and/or Visualizations, so you can review the specific revisions (including git commit hashes) in your data provenance.

conda env create \
  -n q2-boots-2025.4.dev \
  -f https://raw.githubusercontent.com/qiime2/q2-boots/main/environment-files/q2-boots-qiime2-amplicon-2025.4.yml

conda activate q2-boots-2025.4.dev

Using#

After completing the install steps above, you can review the top-level q2-boots help text by running:

qiime boots --help

To view the help text for a specific command, including executable usage examples, you can run:

qiime boots core-metrics --help

This will display the help text for the core-metrics command. Notice the usage examples at the bottom of the help text - these are a good starting point for your commands. Calling core-metrics with the --example-data parameter will write the corresponding example data to a directory you specify for you to test or experiment with as you figure out how you want to use the command. For example:

qiime boots core-metrics --example-data cm-example-data

will write example input data to a new cm-example-data directory. That directory will contain a sub-directory per usage example:

cm-example-data
├── Bootstrapped core metrics.
│   ├── metadata.tsv
│   └── table.qza
└── Rarefaction-based core metrics.
    ├── metadata.tsv
    └── table.qza

Notice that the subdirectory names align with names of the usage examples in the core-metrics --help text. Change into one of those directories and run the corresponding usage example to test out the command. You can then adapt the usage example commands to apply to your own data.

Once you’ve figured out how you want to use q2-boots on your data, you can run Pipelines in parallel by including the --parallel flag in your commands:

qiime boots core-metrics --parallel ...

Pipeline resumption will work in the background, unless you pass --no-recycle, allowing you to restart failed runs without needing to recompute results that had already completed.

Note

The default parallel configuration changed between versions 2024.5 and 2024.10 of the QIIME 2 Framework. Parallel configuration will require a little more setup in the 2024.5.beta release of q2-boots - reach out on the QIIME 2 Forum if you’re interested in doing this and we’ll help out. If you’re using the --parallel option with the 2024.10 development release of QIIME 2, you’re all set.

Have fun! 😎

Getting help#

If you need help with q2-boots, please get in touch on the QIIME 2 Forum.

About q2-boots#

q2-boots was developed for a Master’s degree in Computer Science project at Northern Arizona University (NAU), and will be maintained by the Caporaso Lab at NAU. If you use q2-boots in published work, please cite it as referenced here [1].

q2-boots was derived from content in the QIIME 2 plugin template (q2-boots existed before the plugin template, so didn’t use it directly). To learn how to use q2-boots, refer to the plugin documentation. To learn how to use QIIME 2, refer to the QIIME 2 User Documentation. To learn QIIME 2 plugin development, refer to Developing with QIIME 2.

q2-boots is a QIIME 2 community plugin. While this plugin is developed in the Caporaso Lab, community plugins in general are not necessarily developed and maintained by the developers of QIIME 2. Because community plugins are developed by the QIIME 2 developer community, and not necessarily the QIIME 2 developers themselves, some may not be actively maintained or compatible with current release versions of the QIIME 2 distributions. More information on development and support for community plugins can be found here.

References#

[1]

Isaiah Raspet, Elizabeth Gehret, Chloe Herman, Jeff Meilander, Andrew Manley, Anthony Simard, Evan Bolyen, and J Gregory Caporaso. Facilitating bootstrapped and rarefaction-based microbiome diversity analysis with q2-boots. arXiv [q-bio.QM], August 2024. doi:https://doi.org/10.48550/arXiv.2408.05420.