Home

Welcome to the q2-amr wiki!

Components

This Figure contains all functionalities currently included in q2-amr.
(Blue: artifacts with semantic types, green: actions, red: visualizers, yellow: visualizations, grey: CARD website)

q2amr

Installation

Follow the installation instructions in the README to install q2-amr.

Usage Tutorial

This tutorial will show you how to annotate reads and MAGs with antimicrobial resistance genes (ARGs) from CARD using the q2-amr plugin. So far the functionalities of the plugin include:

Download the CARD database files with the fetch-card-db action.
Annotate reads with ARGs using the annotate-reads-card action.
Annotate MAGs with ARGs using the annotate-mags-card action.
Visualize the annotations from MAGs in a heatmap using the heatmap function.

Download CARD database

To download the CARD database we can use the fetch-card-db action. It automatically downloads the newest version of the CARD, WildCARD and Kmer databases and does all necessary preprocessing. The CARD and WildCARD databases are combined into a single artifact, while the K-mer database is stored in a separate artifact. The CARD and WildCARD databases are used to annotate reads and MAGs with ARGs. The K-mer database is used to predict the taxonomic origin of ARGs, but this functionality is still in development.

qiime amr fetch-card-database \
  --output-dir card_database

Annotate reads

To annotate reads with ARGs from CARD we can use the annotate-reads-card action. We can choose from three different alignment tools that should be used. The default and recommended aligner is KMA. Per default the action maps reads to the ARG sequences on CARD but they can be additionally mapped to the WildCARD database and/or to three further detection models in CARD. Please refer to the RGI documentation for more information on WildCARD and the detection models.

For this tutorial we will map reads to CARD and additionally to WildCARD with the three further detection models included. You can download reads to test here.

qiime amr annotate-reads-card \
  --i-reads reads.qza \
  --i-card-db card_database/card_db.qza \
  --p-aligner kma \
  --p-threads 2 \
  --p-include-other-models \
  --p-include-wildcard \
  --output-dir amr_annotation_reads

Normalization of annotations

Coming soon.

Annotate MAGs

To annotate reads with ARGs from CARD we can use the annotate-mags-card action. We can choose from two different alignment tools. While DIAMOND is faster, BLAST is more sensitive. By default, annotations include perfect matches (100% sequence identity) and strict matches (>95% sequence identity). loose matches (>95% sequence identity) are optional and can be added if preferred. Please refer to the RGI documentation for more information.
You can download MAGs to test here.

qiime amr annotate-mags-card \
  --i-mag mags.qza \
  --i-card-db card_database/card_db.qza \
  --p-alignment-tool BLAST \
  --output-dir amr_annotation_mags

Heatmap

A heatmap can be created from the MAG annotations with the heatmap action. As an option, you can choose to cluster samples, genes, or both based on similarity. Alternatively, genes can be organized according to drug class, resistance mechanism, or gene family.

For this tutorial we will organize the genes by drug class.

qiime amr heatmap \
  --i-amr-annotation amr_annotation_mags/amr_annotations.qza \
  --p-cat drug_class \
  --o-visualization amr_annotation_mags/heatmap.qzv

Tabulate ARG annotations

With the tabulate visualizer of the q2-metadata plugin it is possible to generate a tabular view of ARG annotations, from MAGs or reads. The output visualization supports interactive filtering, sorting, and exporting to common file formats. All samples get combined into one table.
First you have to install q2-metadata into your environment.

mamba install \
  -c conda-forge -c bioconda -c qiime2 -c defaults \
  -c https://packages.qiime2.org/qiime2/2023.9/shotgun/released/ \
  q2-metadata

Run visualizer with annotations from MAGs:

qiime metadata tabulate \
  --m-input-file amr_annotations.qza \
  --o-visualization amr_annotations_tabulated.qzv

Run visualizer with annotations from reads allele mapping output:

qiime metadata tabulate \
  --m-input-file amr_annotation_reads/amr_allele_annotation.qza \
  --o-visualization amr_annotation_reads/amr_allele_annotations_tabulated.qzv

Run visualizer with annotations from reads gene mapping output:

qiime metadata tabulate \
  --m-input-file amr_annotation_reads/amr_gene_annotation.qza \
  --o-visualization amr_annotation_reads/amr_gene_annotations_tabulated.qzv

Taxonomic predictions