Getting started

Getting started#

The tutorials in Using QIIME 2 provide basic information on how to use the QIIME 2 framework, q2cli (i.e., the official QIIME 2 command line interface), and the QIIME 2 Python 3 API. The tutorials make use of the Tiny Distribution, and the QIIME 2 example plugin q2-dwq2. This deployment allows for in-depth learning of how QIIME 2 itself works, and the information you learn here will be relevant across all QIIME 2 distributions. When you’re ready to perform your own data analysis you’ll transition to domain-specific plugins or distributions and their documentation.

Before attempting to run the Using QIIME 2 tutorials, configure your learning environment following the steps here.

Warning

The installation instructions in this document are not finalized though they should work. Updated installation instructions will soon be added.

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

Install the QIIME 2 “Tiny Distribution”#

The QIIME 2 “Tiny Distribution” is a minimal set of QIIME 2 functionality for building and using plugins through the QIIME 2 command line or Python 3 API. Here’s we’ll install the most recent release version of QIIME 2, QIIME 2 2024.5.

macOS

conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-osx-conda.yml

Linux

conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-linux-conda.yml

macOS (Apple Silicon)

CONDA_SUBDIR=osx-64 conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-osx-conda.yml
conda activate using-qiime2
conda config --env --set subdir osx-64

Windows (via WSL)

conda env create -n using-qiime2 --file https://data.qiime2.org/distro/tiny/qiime2-tiny-2024.5-py39-linux-conda.yml

Activate the `conda` environment#

You can now activate the environment you just created as follows.

conda activate using-qiime2

To test your QIIME 2 environment, run:

qiime info

You should see something like the following, though the version numbers you’ll see may be different:

System versions
Python version: 3.9.19
QIIME 2 release: 2024.5
QIIME 2 version: 2024.5.1
q2cli version: 2024.5.0

Installed plugins
types: 2024.5.0

Application config directory
/Users/jgc/miniconda3/envs/using-qiime2/var/q2cli

Getting help
To get help with QIIME 2, visit https://qiime2.org

At this stage you have a working QIIME 2 environment, but it doesn’t do a whole lot. To add some bioinformatics functionality, we’ll next add the QIIME 2 example plugin q2-dwq2.

Install q2-dwq2#

All domain-specific functionality in QIIME 2 comes in the form of plugins. Sometimes you’ll install these directly, and sometimes you’ll install QIIME 2 distributions which are bundles of plugins intended to be used together. In this case, we’re going to install one specific plugin. Run the following command from your using-qiime2 conda environment (i.e., after having run conda activate using-qiime2).

pip install https://github.com/caporaso-lab/q2-dwq2/archive/refs/heads/main.zip

If you run qiime info again, you should now see a new plugin, dwq2, in the list of Installed Plugins.

System versions
Python version: 3.9.19
QIIME 2 release: 2024.5
QIIME 2 version: 2024.5.1
q2cli version: 2024.5.0

Installed plugins
dwq2: 0+unknown
types: 2024.5.0

Application config directory
/Users/jgc/miniconda3/envs/using-qiime2/var/q2cli

Getting help
To get help with QIIME 2, visit https://qiime2.org

Exploring the available functionality#

To see the list of available plugins, along with some additional information, run:

qiime --help

To see what functionality, or Actions a plugin defines, call help on that plugin:

qiime dwq2 --help

To learn how to use a specific action, call help on it:

qiime dwq2 nw-align --help

Take a few minutes now to explore q2-dwq2. What is this plugin intended to do? What is some of the functionality that it provides?