Python Tutorial: Data Visualization with Dokdo API

This tutorial has gotten so big that apparently the text body exceeded the maximum number of characters one can enter in a post (99,000)! Therefore, I will leave a link to Dokdo API for those who are interested in seeing the most up-to-date tutorial. Please let me know if you have any questions.

Click here to see the original documentation

Hi everyone,

My name is Seung-been Lee, and I go by Steven. I’m currently a senior researcher at a next-generation sequencing company in South Korea. I started doing microbiome analysis only this September. If it wasn’t for QIIME 2, I would not have been able to pick up my projects so quickly and smoothly. Therefore, I am very grateful for the QIIME 2 team for their amazing work and user support, as well as the QIIME 2 community for their kind and helpful discussions.

That being said, one main task I have to constantly do for my microbiome project is creating publication-quality figures. QIIME 2 already provides Visualizations and QIIME 2 View, both of which are extremely useful for exploring the output data interactively. However, I noticed that these options are not robust enough for me when it comes to making figures for presentation (e.g. PowerPoint). For example, you cannot currently download alpha rarefaction curve from the alpha-rarefaction.qzv file. For other Visualizations, you can download the figure as a PNG/SVG file, but you cannot change its axis, legend, title, etc. Moreover, once created, those visualization files cannot be modified to, for example, make a subset of the samples (e.g. a taxonomic bar plot). Therefore, the user would have to go way back to perform sample filtration, redo the analysis, and create a new visualization file again, which can be burdensome and time-consuming.

At this point, let me be very clear: I’m not saying QIIME 2 Visualizations should be able to do all the things I metnioned above. I would say it’s actually better QIIME 2 doesn’t do those because then its code can stay simple and focused on the method’s core functionality. And the QIIME 2 user can employ other tools to make the plots however they want. For example, if you are coming from the world of R software, you already have the famous tools available such as Phyloseq and qiime2R.

The issue for me was, even though I can code in both Python and R, I’m way more proficient in Python, and I could not find any Python packages for plotting QIIME 2 objects/files efficiently. That is why I wrote the Dokdo package myself. Dokdo is a lightweight Python package for microbiome sequencing analysis, which can be used as a command line tool and as a Python module. Dokdo is designed to be used with QIIME 2.

For the purpose of this tutorial, I will only describe the Dokdo API and how it can be used to make pretty figures using QIIME 2 files/objects directly. For more details, please visit the Dokdo repository and its Wiki page. Note also that this tutorial was inspired by the famous qiime2R tutorial by Jordan Bisanz.

If you have any questions/suggestions/feature requests/etc., please let me know in the comment section.

Important note: This page assumes you are using the latest Dokdo version 1.5.0. If you are using an older version, please consider updating.

Table of Contents

Introduction

This page describes the Dokdo API, which is designed to be used with Jupyter Notebook in Python. Before using the Dokdo API, please make sure your notebook is open within an environment where QIIME 2 and Dokdo are already installed.

First, at the beginning of your notebook, enter the following to import the Dokdo API.

import dokdo

Next, add the following to make figures. You should have the matplotlib package already installed in your environment because it is included in QIIME 2 installation. With the magic function %matplotlib inline, the output of plotting methods will be displayed inline within Jupyter Notebook.

import matplotlib.pyplot as plt
%matplotlib inline

Finally, set the seed so that our results are reproducible.

import numpy as np
np.random.seed(1)

Tips

Setting Figure Properties

In this section, you’ll learn how to control various properties of a figure using the plotting method denoising_stats_plot as an example. This method creates a grouped box chart using denoising statistics from the DADA 2 algorithm. For more details about the method, see the denoising_stats_plot section.

Let’s start with a toy example. The figure below does not have a legend, which is bad, but let’s not worry about that now.

qza_file = 'data/atacama-soil-microbiome-tutorial/denoising-stats.qza'
metadata_file = 'data/atacama-soil-microbiome-tutorial/sample-metadata.tsv'
where = 'transect-name'

args = [qza_file, metadata_file, where]

dokdo.denoising_stats_plot(*args)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-1C.png')

Setting-Figure-Properties-1C

Aesthetics

The first thing we can do is changing the figure style. I personally like the seaborn package’s default style.

import seaborn as sns

with sns.axes_style('darkgrid'):
    dokdo.denoising_stats_plot(*args)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-2C.png')

Setting-Figure-Properties-2C

If you’re coming from the world of R software, you may find the ggplot style more soothing for your eyes.

import matplotlib.pyplot as plt

with plt.style.context('ggplot'):
    dokdo.denoising_stats_plot(*args)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-3C.png')

Setting-Figure-Properties-3C

Note that in both cases, the styling is set locally. If you plan to make many plots and want to set the style for all of them (i.e. globally), use the following.

import seaborn as sns
sns.set()
# import matplotlib.pyplot as plt
# plt.style.use('ggplot')

Finally, you can turn off the styling at any point after setting it globally with the following.

# import matplotlib
# matplotlib.rc_file_defaults()

Plot Size

There are various ways you can control the figure size. The easiest way is to use the figsize argument in a plotting method call, as shown below.

dokdo.denoising_stats_plot(*args, figsize=(9, 3))

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-4C.png')

Setting-Figure-Properties-4C

If you plan to draw more than one plot in the same figure (i.e. multiple “subplots”), you can specify size for the entire figure in the following way.

fig, [ax1, ax2] = plt.subplots(1, 2, figsize=(9, 3))

dokdo.denoising_stats_plot(*args, ax=ax1)
dokdo.denoising_stats_plot(*args, ax=ax2)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-5C.png')

Setting-Figure-Properties-5C

You can also set the width and/or height of individual subplots using width_ratios and height_ratios from gridspec_kw.

fig, [ax1, ax2] = plt.subplots(1, 2, figsize=(9, 3), gridspec_kw={'width_ratios': [8, 2]})

dokdo.denoising_stats_plot(*args, ax=ax1)
dokdo.denoising_stats_plot(*args, ax=ax2)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-6C.png')

Setting-Figure-Properties-6C

Alternatively, you can combine empty subplots to create a bigger subplot using gridspec.

import matplotlib.gridspec as gridspec

fig, axes  = plt.subplots(2, 2, figsize=(9, 5))

dokdo.denoising_stats_plot(*args, ax=axes[0][0])
dokdo.denoising_stats_plot(*args, ax=axes[1][0])

gs = axes[0, 1].get_gridspec()

for ax in axes[0:2, 1]:
    ax.remove()

axbig = fig.add_subplot(gs[0:2, 1])
dokdo.denoising_stats_plot(*args, ax=axbig)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-7C.png')

Setting-Figure-Properties-7C

Title, Axis, Legend, Font Size

Each main plotting method takes a dictionary argument called artist_kwargs as input that is passed down to the private method _artist as shown below. For example, the show_legend argument defined in _artist is set as False by default, which means if you want to include the figure legend, you should include artist_kwargs=dict(show_legend=True) in your method call.

Note that internally, different plotting methods use a different set of default keyword arguments for _artist. For example, by default, the denoising_stats_plot method passes ylabel='Read depth' to _artist whereas the taxa_abundance_bar_plot method passes ylabel='Relative abundance (%)'. Of course, you can always easily change the y-axis label with artist_kwargs=dict(ylabel='My new y-axis label')

Help on function _artist in module dokdo.api:

_artist(ax, title=None, title_fontsize=None, xlabel=None, xlabel_fontsize=None, ylabel=None, ylabel_fontsize=None, zlabel=None, zlabel_fontsize=None, xticks=None, yticks=None, xticklabels=None, xticklabels_fontsize=None, yticklabels=None, yticklabels_fontsize=None, xrot=None, xha=None, xmin=None, xmax=None, ymin=None, ymax=None, xlog=False, ylog=False, hide_xtexts=False, hide_ytexts=False, hide_ztexts=False, hide_xlabel=False, hide_ylabel=False, hide_zlabel=False, hide_xticks=False, hide_yticks=False, hide_zticks=False, hide_xticklabels=False, hide_yticklabels=False, hide_zticklabels=False, show_legend=False, legend_loc='best', legend_ncol=1, legend_labels=None, legend_short=False, remove_duplicates=False, legend_only=False, legend_fontsize=None, legend_markerscale=None, legend_lw=None, legend_title=None, plot_method=None)
    This method controls various properties of a figure.

    Parameters
    ----------
    ax : matplotlib.axes.Axes
        Axes object to draw the plot onto.
    title : str, optional
        Sets the figure title.
    title_fontsize : float or str, optional
        Sets the title font size.
    xlabel : str, optional
        Set the x-axis label.
    xlabel_fontsize : float or str, optional
        Sets the x-axis label font size.
    ylabel : str, optional
        Set the y-axis label.
    ylabel_fontsize : float or str, optional
        Sets the y-axis label font size.
    zlabel : str, optional
        Set the z-axis label.
    zlabel_fontsize : float or str, optional
        Sets the z-axis label font size.
    xticks : list, optional
        Positions of x-axis ticks.
    yticks : list, optional
        Positions of y-axis ticks.
    xticklabels : list, optional
        Tick labels for the x-axis.
    xticklabels_fontsize : float or str, optional
        Font size for the x-axis tick labels.
    yticklabels : list, optional
        Tick labels for the y-axis.
    yticklabels_fontsize : float or str, optional
        Font size for the y-axis tick labels.
    xrot : float, optional
        Rotation degree of tick labels for the x-axis.
    xha : str, optional
        Horizontal alignment of tick labels for the x-axis.
    xmin : float, optional
        Minimum value for the x-axis.
    xmax : float, optional
        Maximum value for the x-axis.
    ymin : float, optional
        Minimum value for the y-axis.
    ymax : float, optional
        Maximum value for the x-axis.
    xlog : bool, default: False
        Draw the x-axis in log scale.
    ylog : bool, default: False
        Draw the y-axis in log scale.
    hide_xtexts : bool, default: False
        Hides all the x-axis texts.
    hide_ytexts : bool, default: False
        Hides all the y-axis texts.
    hide_ztexts : bool, default: False
        Hides all the z-axis texts.
    hide_xlabel : bool, default: False
        Hides the x-axis label.
    hide_ylabel : bool, default: False
        Hides the y-axis label.
    hide_zlabel : bool, default: False
        Hides the z-axis label.
    hide_xticks : bool, default: False
        Hides ticks and tick labels for the x-axis.
    hide_yticks : bool, default: False
        Hides ticks and tick labels for the y-axis.
    hide_zticks : bool, default: False
        Hides ticks and tick labels for the z-axis.
    hide_xticklabels : bool, default: False
        Hides tick labels for the x-axis.
    hide_yticklabels : bool, default: False
        Hides tick labels for the y-axis.
    hide_zticklabels : bool, default: False
        Hides tick labels for the z-axis.
    show_legend : bool, default: False
        Show the figure legend.
    legend_loc : str, default: 'best'
        Legend location specified as in matplotlib.pyplot.legend.
    legend_ncol : int, default: 1
        Number of columns that the legend has.
    legend_only : bool, default: False
        Clear the figure and display the legend only.
    legend_fontsize : float or str, optional
        Sets the legend font size.
    legend_markerscale : float, optional
        Relative size of legend markers compared with the original.
    legend_lw : float, optional
        Width of the lines in the legend.
    legend_title: str, optional
        Legend title.
    plot_method : str, optional
        Name of the plotting method. This argument is internally used for
        the `alpha_rarefaction_plot` method. Not to be used by users.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    Notes
    -----
    Font size can be specified by provding a number or a string as defined in:
    {'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'}.

Below are some simple examples.

fig, [[ax1, ax2, ax3], [ax4, ax5, ax6]] = plt.subplots(2, 3, figsize=(15, 8))

artist_kwargs1 = dict(title='My title')
artist_kwargs2 = dict(title='ylog=True', ylog=True, ymin=0.5E1, ymax=1.5E5)
artist_kwargs3 = dict(title='legend_ncol=2', show_legend=True, legend_ncol=2)
artist_kwargs4 = dict(title='hide_yticks=True', hide_yticks=True)
artist_kwargs5 = dict(title='title_fontsize=20', title_fontsize=20)
artist_kwargs6 = dict(title='legend_fontsize=15', show_legend=True, legend_ncol=2, legend_fontsize=15)

dokdo.denoising_stats_plot(*args, ax=ax1, artist_kwargs=artist_kwargs1)
dokdo.denoising_stats_plot(*args, ax=ax2, artist_kwargs=artist_kwargs2)
dokdo.denoising_stats_plot(*args, ax=ax3, artist_kwargs=artist_kwargs3)
dokdo.denoising_stats_plot(*args, ax=ax4, artist_kwargs=artist_kwargs4)
dokdo.denoising_stats_plot(*args, ax=ax5, artist_kwargs=artist_kwargs5)
dokdo.denoising_stats_plot(*args, ax=ax6, artist_kwargs=artist_kwargs6)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Setting-Figure-Properties-8D.png')

Plotting Legend Separately

In some situations, we may wish to plot the graph and the legend separately. For example, the taxa_abundance_bar_plot method by default displays the whole taxa name, which can be quite long and disrupting as shown below.

qzv_file = 'data/moving-pictures-tutorial/taxa-bar-plots.qzv'

dokdo.taxa_abundance_bar_plot(qzv_file,
                              level=2,
                              count=8,
                              figsize=(9, 5),
                              artist_kwargs=dict(show_legend=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/Plotting-Legend-Separately-1C.png')

Plotting-Legend-Separately-1C

We can ameliorate the issue by plotting the legend separately with legend_only=True.

fig, [ax1, ax2] = plt.subplots(1, 2, figsize=(11, 5), gridspec_kw={'width_ratios': [9, 1]})

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax1,
                              level=2,
                              count=8)

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax2,
                              level=2,
                              count=8,
                              artist_kwargs=dict(legend_loc='upper left',
                                                 legend_only=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/Plotting-Legend-Separately-2C.png')

Plotting QIIME 2 Files vs. Objects

Thus far, for plotting purposes, we have only used files created by the QIIME 2 CLI (i.e. .qza and .qzv files). However, we can also plot Python objects created by the QIIME 2 API.

For example, we can directly plot the Artifact object from the diversity.visualizers.alpha_rarefaction method (i.e. QIIME 2 API).

from qiime2 import Artifact
from qiime2 import Metadata
from qiime2.plugins import diversity

table = Artifact.load('data/moving-pictures-tutorial/table.qza')
phylogeny = Artifact.load('data/moving-pictures-tutorial/rooted-tree.qza')
metadata = Metadata.load('data/moving-pictures-tutorial/sample-metadata.tsv')

rarefaction_result = diversity.visualizers.alpha_rarefaction(table=table,
                                                             metadata=metadata,
                                                             phylogeny=phylogeny,
                                                             max_depth=4000)
rarefaction = rarefaction_result.visualization

dokdo.alpha_rarefaction_plot(rarefaction)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Plotting-QIIME-2-Objects-1C.png')

Plotting-QIIME-2-Objects-1C

As expected, above gives the same result as using the Visualization file created by the qiime diversity alpha-rarefaction command (i.e. QIIME 2 CLI).

qzv_file = 'data/moving-pictures-tutorial/alpha-rarefaction.qzv'

dokdo.alpha_rarefaction_plot(qzv_file)

plt.tight_layout()
plt.savefig('images/Dokdo-API/Plotting-QIIME-2-Objects-2C.png')

Plotting-QIIME-2-Objects-2C

General Methods

get_mf

Help on function get_mf in module dokdo.api:

get_mf(metadata)
    This method automatically detects the type of input metadata and converts
    it to DataFrame object.

    Parameters
    ----------
    metadata : str or qiime2.Metadata
        Metadata file or object.

    Returns
    -------
    pandas.DataFrame
        DataFrame object containing metadata.

This is a simple example.

mf = dokdo.get_mf('data/moving-pictures-tutorial/sample-metadata.tsv')
mf.head()
barcode-sequence body-site year month day subject reported-antibiotic-usage days-since-experiment-start
sample-id
L1S8 AGCTGACTAGTC gut 2008.0 10.0 28.0 subject-1 Yes 0.0
L1S57 ACACACTATGGC gut 2009.0 1.0 20.0 subject-1 No 84.0
L1S76 ACTACGTGTGGT gut 2009.0 2.0 17.0 subject-1 No 112.0
L1S105 AGTGCGATGCGT gut 2009.0 3.0 17.0 subject-1 No 140.0
L2S155 ACGATGCGACCA left palm 2009.0 1.0 20.0 subject-1 No 84.0

ordinate

Help on function ordinate in module dokdo.api:

ordinate(table, metadata=None, where=None, metric='jaccard', sampling_depth=-1, phylogeny=None, number_of_dimensions=None, biplot=False)
    This method wraps multiple QIIME 2 methods to perform ordination and
    returns Artifact object containing PCoA results.

    Under the hood, this method filters the samples (if requested), performs
    rarefying of the feature table (if requested), computes distance matrix,
    and then runs PCoA.

    By default, the method returns PCoAResults. For creating a biplot, make
    sure to use `biplot=True` which returns PCoAResults % Properties('biplot').

    Parameters
    ----------
    table : str or qiime2.Artifact
        Artifact file or object corresponding to FeatureTable[Frequency].
    metadata : str or qiime2.Metadata, optional
        Metadata file or object.
    where : str, optional
        SQLite WHERE clause specifying sample metadata criteria.
    metric : str, default: 'jaccard'
        Metric used for distance matrix computation ('jaccard',
        'bray_curtis', 'unweighted_unifrac', or 'weighted_unifrac').
    sampling_depth : int, default: -1
        If negative, skip rarefying. If 0, rarefy to the sample with minimum
        depth. Otherwise, rarefy to the provided sampling depth.
    phylogeny : str, optional
        Rooted tree file. Required if using 'unweighted_unifrac', or
        'weighted_unifrac' as metric.
    number_of_dimensions : int, optional
        Dimensions to reduce the distance matrix to.
    biplot : bool, default: False
        If true, return PCoAResults % Properties('biplot').

    Returns
    -------
    qiime2.Artifact
        Artifact object corresponding to PCoAResults or
        PCoAResults % Properties('biplot').

    See Also
    --------
    beta_2d_plot
    beta_3d_plot
    beta_scree_plot
    beta_parallel_plot

    Notes
    -----
    The resulting Artifact object can be directly used for plotting.

Below is a simple example. Note that the default distance metric used is jaccard. The resulting object pcoa can be directly used for plotting by the beta_2d_plot method as shown below.

table_file = 'data/moving-pictures-tutorial/table.qza'
metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

pcoa_results = dokdo.ordinate(table_file)
dokdo.beta_2d_plot(pcoa_results, metadata=metadata_file, hue='body-site', artist_kwargs=dict(show_legend=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/ordinate-1-20201223.png')

ordinate-1-20201223

You can choose a subset of samples.

pcoa_results = dokdo.ordinate(table_file, metadata=metadata_file, where="[body-site] IN ('gut', 'left palm')")
dokdo.beta_2d_plot(pcoa_results, metadata=metadata_file, hue='body-site', artist_kwargs=dict(show_legend=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/ordinate-2-20201223.png')

ordinate-2-20201223

You can also generate a biplot.

pcoa_results = dokdo.ordinate(table_file, biplot=True, number_of_dimensions=10)

fig, ax = plt.subplots(1, 1, figsize=(8, 8))

dokdo.beta_2d_plot(pcoa_results, ax=ax, metadata=metadata_file, hue='body-site', artist_kwargs=dict(show_legend=True))
dokdo.addbiplot(pcoa_results, ax=ax, count=7)

plt.tight_layout()
plt.savefig('images/Dokdo-API/ordinate-3-20201223.png')

Main Plotting Methods

read_quality_plot

Help on function read_quality_plot in module dokdo.api:

read_quality_plot(demux, strand='forward', ax=None, figsize=None, artist_kwargs=None)
    This method creates a read quality plot.

    Parameters
    ----------
    demux : str or qiime2.Visualization
        Visualization file or object from the q2-demux plugin.
    strand : str, default: 'forward'
        Read strand to be displayed (either 'forward' or 'reverse').
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    Notes
    -----
    Example usage of the q2-demux plugin:
        CLI -> $ qiime demux summarize [OPTIONS]
        API -> from qiime2.plugins.demux.visualizers import summarize

Below is a simple example.

qzv_file = 'data/atacama-soil-microbiome-tutorial/demux-subsample.qzv'

fig, [ax1, ax2] = plt.subplots(1, 2)

artist_kwargs1 = dict(title='Forward read')
artist_kwargs2 = dict(title='Reverse read', hide_ylabel=True, hide_yticklabels=True)

dokdo.read_quality_plot(qzv_file, strand='forward', ax=ax1, artist_kwargs=artist_kwargs1)
dokdo.read_quality_plot(qzv_file, strand='reverse', ax=ax2, artist_kwargs=artist_kwargs2)

plt.tight_layout()
plt.savefig('images/Dokdo-API/read_quality_plot-1C.png')

read_quality_plot-1C

denoising_stats_plot

Help on function denoising_stats_plot in module dokdo.api:

denoising_stats_plot(stats, metadata, where, ax=None, figsize=None, pseudocount=False, order=None, hide_nsizes=False, artist_kwargs=None)
    This method creates a grouped box chart using denoising statistics from
    the DADA 2 algorithm.

    Parameters
    ----------
    stats : str or qiime2.Artifact
        Artifact file or object from the q2-dada2 plugin.
    metadata : str or qiime2.Metadata
        Metadata file or object.
    where : str
        Column name of the sample metadata.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    pseudocount : bool, default: False
        Add pseudocount to remove zeros.
    order : list, optional
        Order to plot the categorical levels in.
    hide_nsizes : bool, default: False
        Hide sample size from x-axis labels.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    Notes
    -----
    Example usage of the q2-dada2 plugin:
        CLI -> qiime dada2 denoise-paired [OPTIONS]
        API -> from qiime2.plugins.dada2.methods import denoise_paired

Below is a simple example.

qza_file = 'data/atacama-soil-microbiome-tutorial/denoising-stats.qza'
metadata_file = 'data/atacama-soil-microbiome-tutorial/sample-metadata.tsv'

dokdo.denoising_stats_plot(qza_file, metadata_file, 'transect-name', artist_kwargs=dict(show_legend=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/denoising_stats_plot-1C.png')

denoising_stats_plot-1C

alpha_rarefaction_plot

Help on function alpha_rarefaction_plot in module dokdo.api:

alpha_rarefaction_plot(rarefaction, hue='sample-id', metric='shannon', ax=None, figsize=None, hue_order=None, units=None, estimator='mean', seed=1, artist_kwargs=None)
    This method creates an alpha rarefaction plot.

    Parameters
    ----------
    rarefaction : str or qiime2.Visualization
        Visualization file or object from the q2-diversity plugin.
    hue : str, default: 'sample-id'
        Grouping variable that will produce lines with different colors. If not
        provided, sample IDs will be used.
    metric : str, default: 'shannon'
        Diversity metric ('shannon', 'observed_features', or 'faith_pd').
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    hue_order : list, optional
        Specify the order of categorical levels of the 'hue' semantic.
    units : str, optional
        Grouping variable identifying sampling units. When used, a separate
        line will be drawn for each unit with appropriate semantics, but no
        legend entry will be added.
    estimator : str, default: 'mean', optional
        Method for aggregating across multiple observations of the y variable
        at the same x level. If None, all observations will be drawn.
    seed : int, default: 1
        Seed for reproducible bootstrapping.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    Notes
    -----
    Example usage of the q2-diversity plugin:
        CLI -> qiime diversity alpha-rarefaction [OPTIONS]
        API -> from qiime2.plugins.diversity.visualizers import alpha_rarefaction

Below is a simple example.

qzv_file = 'data/moving-pictures-tutorial/alpha-rarefaction.qzv'
artist_kwargs = dict(show_legend=True, legend_ncol=5)

dokdo.alpha_rarefaction_plot(qzv_file,
                             figsize=(8, 5),
                             artist_kwargs=artist_kwargs)

plt.tight_layout()
plt.savefig('images/Dokdo-API/alpha_rarefaction_plot-1-20210109.png')

alpha_rarefaction_plot-1-20210109

We can group the samples by body-site.

artist_kwargs = dict(show_legend=True)

dokdo.alpha_rarefaction_plot(qzv_file,
                             hue='body-site',
                             metric='observed_features',
                             figsize=(8, 5),
                             units='sample-id',
                             estimator=None,
                             artist_kwargs=artist_kwargs)

plt.tight_layout()
plt.savefig('images/Dokdo-API/alpha_rarefaction_plot-2-20210109.png')

alpha_rarefaction_plot-2-20210109

Alternatively, we can aggregate the samples by body-site.

artist_kwargs = dict(show_legend=True)

dokdo.alpha_rarefaction_plot(qzv_file,
                             hue='body-site',
                             metric='observed_features',
                             figsize=(8, 5),
                             artist_kwargs=artist_kwargs)

plt.tight_layout()
plt.savefig('images/Dokdo-API/alpha_rarefaction_plot-3-20210109.png')

alpha_rarefaction_plot-3-20210109

alpha_diversity_plot

Help on function alpha_diversity_plot in module dokdo.api:

alpha_diversity_plot(alpha_diversity, metadata, where, ax=None, figsize=None, add_swarmplot=False, order=None, artist_kwargs=None)
    Create an alpha diversity plot.

    Parameters
    ----------
    alpha_diversity : str or qiime2.Artifact
        Artifact file or object with the semantic type
        `SampleData[AlphaDiversity]`.
    metadata : str or qiime2.Metadata
        Metadata file or object.
    where : str
        Column name to be used for the x-axis.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    add_swarmplot : bool, default: False
        Add a swarm plot on top of the box plot.
    order : list, optional
        Order to plot the categorical levels in.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

Below is a simple example.

qzv_file = 'data/moving-pictures-tutorial/faith_pd_vector.qza'
metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

dokdo.alpha_diversity_plot(qzv_file, metadata_file, 'body-site')

plt.tight_layout()
plt.savefig('images/Dokdo-API/alpha_diversity_plot-1-20210203.png')

alpha_diversity_plot-1-20210203

beta_2d_plot

Help on function beta_2d_plot in module dokdo.api:

beta_2d_plot(pcoa_results, metadata=None, hue=None, size=None, style=None, s=80, alpha=None, ax=None, figsize=None, hue_order=None, style_order=None, legend_type='brief', artist_kwargs=None)
    This method creates a 2D scatter plot from PCoA results.

    Parameters
    ----------
    pcoa_results : str or qiime2.Artifact
        Artifact file or object corresponding to PCoAResults or
        PCoAResults % Properties('biplot').
    metadata : str or qiime2.Metadata, optional
        Metadata file or object.
    hue : str, optional
        Grouping variable that will produce points with different colors.
    size : str, optional
        Grouping variable that will produce points with different sizes.
    style : str, optional
        Grouping variable that will produce points with different markers.
    s : float, default: 80.0
        Marker size.
    alpha : float, optional
        Proportional opacity of the points.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    hue_order : list, optional
        Specify the order of categorical levels of the 'hue' semantic.
    style_order : list, optional
        Specify the order of categorical levels of the 'style' semantic.
    legend_type : str, default: 'brief'
        Legend type as in seaborn.scatterplot ('brief' or 'full').
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    ordinate
    beta_3d_plot
    beta_scree_plot
    beta_parallel_plot
    addbiplot

    Notes
    -----
    Example usage of the q2-diversity plugin:
        CLI -> qiime diversity pcoa [OPTIONS]
        API -> from qiime2.plugins.diversity.methods import pcoa

Below is a simple example.

qza_file = 'data/moving-pictures-tutorial/unweighted_unifrac_pcoa_results.qza'

dokdo.beta_2d_plot(qza_file)

plt.tight_layout()
plt.savefig('images/Dokdo-API/beta_2d_plot-1C.png')

beta_2d_plot-1C

We can color the datapoints with hue. We can also change the style of datapoints with style. If the variable of interest is numeric, we can use size to control the size of datapoints. Finally, we can combine all those groupings.

metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

fig, [[ax1, ax2], [ax3, ax4]] = plt.subplots(2, 2, figsize=(8, 8))

artist_kwargs1 = dict(show_legend=True, title="hue='body-site'")
artist_kwargs2 = dict(show_legend=True, title="style='subject'")
artist_kwargs3 = dict(show_legend=True, title="size='days-since-experiment-start'")
artist_kwargs4 = dict(title="Combined groupings")

dokdo.beta_2d_plot(qza_file, metadata_file, ax=ax1, hue='body-site', artist_kwargs=artist_kwargs1)
dokdo.beta_2d_plot(qza_file, metadata_file, ax=ax2, style='subject', artist_kwargs=artist_kwargs2)
dokdo.beta_2d_plot(qza_file, metadata_file, ax=ax3, size='days-since-experiment-start', artist_kwargs=artist_kwargs3)
dokdo.beta_2d_plot(qza_file, metadata_file, ax=ax4, hue='body-site', style='subject', size='days-since-experiment-start', artist_kwargs=artist_kwargs4)

plt.tight_layout()
plt.savefig('images/Dokdo-API/beta_2d_plot-2C.png')

beta_3d_plot

Help on function beta_3d_plot in module dokdo.api:

beta_3d_plot(pcoa_results, metadata=None, hue=None, azim=-60, elev=30, s=80, ax=None, figsize=None, hue_order=None, artist_kwargs=None)
    This method creates a 3D scatter plot from PCoA results.

    Parameters
    ----------
    pcoa_results : str or qiime2.Artifact
        Artifact file or object corresponding to PCoAResults or
        PCoAResults % Properties('biplot').
    metadata : str or qiime2.Metadata, optional
        Metadata file or object.
    hue : str, optional
        Grouping variable that will produce points with different colors.
    azim : int, default: -60
        Elevation viewing angle.
    elev : int, default: 30
        Azimuthal viewing angle.
    s : float, default: 80.0
        Marker size.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    hue_order : list, optional
        Specify the order of categorical levels of the 'hue' semantic.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    ordinate
    beta_2d_plot
    beta_scree_plot
    beta_parallel_plot
    addbiplot

    Notes
    -----
    Example usage of the q2-diversity plugin:
        CLI -> qiime diversity pcoa [OPTIONS]
        API -> from qiime2.plugins.diversity.methods import pcoa

Below is a simple example.

qza_file = 'data/moving-pictures-tutorial/unweighted_unifrac_pcoa_results.qza'
metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

dokdo.beta_3d_plot(qza_file,
                   metadata_file,
                   'body-site',
                   figsize=(6, 6),
                   artist_kwargs=dict(show_legend=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/beta_3d_plot-1-20210203.png')

beta_3d_plot-1-20210203

We can control the camera angle with elev and azim.

fig = plt.figure(figsize=(12, 6))

ax1 = fig.add_subplot(1, 2, 1, projection='3d')
ax2 = fig.add_subplot(1, 2, 2, projection='3d')

dokdo.beta_3d_plot(qza_file, metadata_file, ax=ax1, hue='body-site', elev=15)
dokdo.beta_3d_plot(qza_file, metadata_file, ax=ax2, hue='body-site', azim=70)

plt.tight_layout()
plt.savefig('images/Dokdo-API/beta_3d_plot-2-20210203.png')

beta_scree_plot

Help on function beta_scree_plot in module dokdo.api:

beta_scree_plot(pcoa_results, count=5, ax=None, figsize=None, color='blue', artist_kwargs=None)
    This method creates a scree plot from PCoA results.

    Parameters
    ----------
    pcoa_results : str or qiime2.Artifact
        Artifact file or object corresponding to PCoAResults.
    count : int, default: 5
        Number of principal components to be displayed.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    color : str, default: 'blue'
        Bar color.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    ordinate
    beta_2d_plot
    beta_3d_plot
    beta_parallel_plot

    Notes
    -----
    Example usage of the q2-diversity plugin:
        CLI -> qiime diversity pcoa [OPTIONS]
        API -> from qiime2.plugins.diversity.methods import pcoa

Below is a simple example.

qza_file = 'data/moving-pictures-tutorial/unweighted_unifrac_pcoa_results.qza'

dokdo.beta_scree_plot(qza_file)

plt.tight_layout()
plt.savefig('images/Dokdo-API/beta_scree_plot-1-20201217.png')

beta_scree_plot-1-20201217

beta_parallel_plot

Help on function beta_parallel_plot in module dokdo.api:

beta_parallel_plot(pcoa_results, hue=None, hue_order=None, metadata=None, count=5, ax=None, figsize=None, artist_kwargs=None)
    This method creates a parallel plot from PCoA results.

    Parameters
    ----------
    pcoa_results : str or qiime2.Artifact
        Artifact file or object corresponding to PCoAResults.
    hue : str, optional
        Grouping variable that will produce lines with different colors.
    hue_order : list, optional
        Specify the order of categorical levels of the 'hue' semantic.
    metadata : str or qiime2.Metadata, optional
        Metadata file or object. Required if 'hue' is used.
    count : int, default: 5
        Number of principal components to be displayed.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    ordinate
    beta_2d_plot
    beta_3d_plot
    beta_scree_plot

    Notes
    -----
    Example usage of the q2-diversity plugin:
        CLI -> qiime diversity pcoa [OPTIONS]
        API -> from qiime2.plugins.diversity.methods import pcoa

Below is a simple example.

qza_file = 'data/moving-pictures-tutorial/unweighted_unifrac_pcoa_results.qza'

dokdo.beta_parallel_plot(qza_file)

plt.tight_layout()
plt.savefig('images/Dokdo-API/beta_parallel_plot-1-20210202.png')

beta_parallel_plot-1-20210202

We can group the lines by body-site.

metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

dokdo.beta_parallel_plot(qza_file, metadata=metadata_file, hue='body-site', artist_kwargs=dict(show_legend=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/beta_parallel_plot-2-20210202.png')

beta_parallel_plot-2-20210202

distance_matrix_plot

Help on function distance_matrix_plot in module dokdo.api:

distance_matrix_plot(distance_matrix, bins=100, pairs=None, ax=None, figsize=None, artist_kwargs=None)
    This method creates a histogram from a distance matrix.

    Parameters
    ----------
    distance_matrix : str or qiime2.Artifact
        Artifact file or object from the q2-diversity-lib plugin.
    bins : int, optional
        Number of bins to be displayed.
    pairs : list, optional
        List of sample pairs to be shown in red vertical lines.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    Notes
    -----
    Example usage of the q2-diversity-lib plugin:
        CLI -> qiime diversity-lib jaccard [OPTIONS]
        API -> from qiime2.plugins.diversity_lib.methods import jaccard

Below is a simple example.

qza_file = 'data/moving-pictures-tutorial/unweighted_unifrac_distance_matrix.qza'

dokdo.distance_matrix_plot(qza_file)

plt.tight_layout()
plt.savefig('images/Dokdo-API/distance_matrix_plot-1C.png')

distance_matrix_plot-1

We can indicate the distance between any two samples on top of the histogram using pairs.

dokdo.distance_matrix_plot(qza_file, pairs=[['L1S8', 'L1S57'], ['L2S175', 'L2S204']])

plt.tight_layout()
plt.savefig('images/Dokdo-API/distance_matrix_plot-2C.png')

distance_matrix_plot-2

taxa_abundance_bar_plot

Help on function taxa_abundance_bar_plot in module dokdo.api:

taxa_abundance_bar_plot(taxa, metadata=None, level=1, by=None, ax=None, figsize=None, width=0.8, count=0, exclude_samples=None, include_samples=None, exclude_taxa=None, sort_by_names=False, colors=None, label_columns=None, orders=None, sample_names=None, csv_file=None, taxa_names=None, sort_by_mean1=True, sort_by_mean2=True, sort_by_mean3=True, show_others=True, cmap_name='Accent', artist_kwargs=None)
    This method creates a taxa abundance plot.

    Although the input visualization file should contain medatadata already,
    you can replace it with new metadata by using the 'metadata' option.

    Parameters
    ----------
    taxa : str or qiime2.Visualization
        Visualization file or object from the q2-taxa plugin.
    metadata : str or qiime2.Metadata, optional
        Metadata file or object.
    level : int, default: 1
        Taxonomic level at which the features should be collapsed.
    by : list, optional
        Column name(s) to be used for sorting the samples. Using 'sample-id'
        will sort the samples by their name, in addition to other column
        name(s) that may have been provided. If multiple items are provided,
        sorting will occur by the order of the items.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    width : float, default: 0.8
        The width of the bars.
    count : int, default: 0
        The number of taxa to display. When 0, display all.
    exclude_samples : dict, optional
        Filtering logic used for sample exclusion.
        Format: {'col': ['item', ...], ...}.
    include_samples : dict, optional
        Filtering logic used for sample inclusion.
        Format: {'col': ['item', ...], ...}.
    exclude_taxa : list, optional
        The taxa names to be excluded when matched. Case insenstivie.
    sort_by_names : bool, default: False
        If true, sort the columns (i.e. species) to be displayed by name.
    colors : list, optional
        The bar colors.
    label_columns : list, optional
        The column names to be used as the x-axis labels.
    orders : dict, optional
        Dictionary of {column1: [element1, element2, ...], column2:
        [element1, element2...], ...} to indicate the order of items. Used to
        sort the sampels by the user-specified order instead of ordering
        numerically or alphabetically.
    sample_names : list, optional
        List of sample IDs to be included.
    csv_file : str, optional
        Path of the .csv file to output the dataframe to.
    taxa_names : list, optional
        List of taxa names to be displayed.
    sort_by_mean1 : bool, default: True
        Sort taxa by their mean relative abundance before sample filtration.
    sort_by_mean2 : bool, default: True
        Sort taxa by their mean relative abundance after sample filtration by
        'include_samples' or 'exclude_samples'.
    sort_by_mean3 : bool, default: True
        Sort taxa by their mean relative abundance after sample filtration by
        'sample_names'.
    show_others : bool, default: True
        Include the 'Others' category.
    cmap_name : str, default: 'Accent'
        Name of the colormap passed to `matplotlib.cm.get_cmap()`.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    taxa_abundance_box_plot

    Notes
    -----
    Example usage of the q2-taxa plugin:
        CLI -> qiime taxa barplot [OPTIONS]
        API -> from qiime2.plugins.taxa.visualizers import barplot

Below is a simple example showing taxonomic abundance at the kingdom level (i.e. level=1), which is the default taxonomic rank.

qzv_file = 'data/moving-pictures-tutorial/taxa-bar-plots.qzv'

dokdo.taxa_abundance_bar_plot(qzv_file,
                              figsize=(10, 7),
                              artist_kwargs=dict(show_legend=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-1-20210109.png')

We can change the taxonomic rank from kingdom to genus by setting level=6. Note that I removed show_legend=True because otherwise there will be too many taxa to display on the legend. Note also that the colors are recycled in each bar.

dokdo.taxa_abundance_bar_plot(qzv_file,
                              figsize=(10, 7),
                              level=6)

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-2-20210109.png')

We can only show the top seven most abundant genera plus ‘Others’ with count=8.

dokdo.taxa_abundance_bar_plot(qzv_file,
                              figsize=(10, 7),
                              level=6,
                              count=8,
                              artist_kwargs=dict(show_legend=True,
                                                 legend_loc='upper left',
                                                 legend_short=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-3-20210109.png')

We can plot the figure and the legend separately.

fig, [ax1, ax2] = plt.subplots(1, 2, figsize=(12, 7), gridspec_kw={'width_ratios': [9, 1]})

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax1,
                              level=6,
                              count=8)

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax2,
                              level=6,
                              count=8,
                              artist_kwargs=dict(legend_only=True,
                                                 legend_loc='upper left',
                                                 legend_short=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-4-20210109.png')

We can use a different color map to display more unique genera (e.g. 20).

fig, [ax1, ax2] = plt.subplots(1, 2, figsize=(12, 7), gridspec_kw={'width_ratios': [9, 1]})

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax1,
                              level=6,
                              count=20,
                              cmap_name='tab20')

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax2,
                              level=6,
                              count=20,
                              cmap_name='tab20',
                              artist_kwargs=dict(legend_only=True,
                                                 legend_loc='upper left',
                                                 legend_short=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-5-20210109.png')

We can sort the samples by the body-site column in metadata with by=['body-site']. To check whether the sorting worked properly, we can change the x-axis tick labels to include each sample’s body-site with label_columns.

dokdo.taxa_abundance_bar_plot(qzv_file,
                              by=['body-site'],
                              label_columns=['body-site', 'sample-id'],
                              figsize=(10, 7),
                              level=6,
                              count=8,
                              artist_kwargs=dict(show_legend=True,
                                                 legend_loc='upper left',
                                                 legend_short=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-6-20210109.png')

If you want to sort the samples in a certain order instead of ordering numerically or alphabetically, use the orders option.

dokdo.taxa_abundance_bar_plot(qzv_file,
                              by=['body-site'],
                              label_columns=['body-site', 'sample-id'],
                              figsize=(10, 7),
                              level=6,
                              count=8,
                              orders={'body-site': ['left palm', 'tongue', 'gut', 'right palm']},
                              artist_kwargs=dict(show_legend=True,
                                                 legend_loc='upper left',
                                                 legend_short=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-7-20210109.png')

We can only display the ‘gut’ and ‘tongue’ samples with include_samples.

fig, [ax1, ax2] = plt.subplots(1, 2, figsize=(9, 7), gridspec_kw={'width_ratios': [9, 1]})

kwargs = dict(include_samples={'body-site': ['gut', 'tongue']},
                by=['body-site'],
                label_columns=['body-site', 'sample-id'],
                level=6,
                count=8)

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax1,
                              **kwargs)

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax2,
                              **kwargs,
                              artist_kwargs=dict(legend_only=True,
                                                 legend_loc='upper left',
                                                 legend_short=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-8-20210109.png')

We can make multiple bar charts grouped by body-site. When making a grouped bar chart, it’s important to include sort_by_mean2=False in order to have the same bar colors for the same taxa across different groups.

fig, [ax1, ax2, ax3, ax4, ax5] = plt.subplots(1, 5, figsize=(16, 7), gridspec_kw={'width_ratios': [2, 2, 2, 2, 1]})

kwargs = dict(level=6, count=8, sort_by_mean2=False)

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax1,
                              include_samples={'body-site': ['gut']},
                              **kwargs,
                              artist_kwargs=dict(title='gut'))

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax2,
                              include_samples={'body-site': ['left palm']},
                              **kwargs,
                              artist_kwargs=dict(title='left palm',
                                                 hide_ylabel=True,
                                                 hide_yticks=True))

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax3,
                              include_samples={'body-site': ['right palm']},
                              **kwargs,
                              artist_kwargs=dict(title='right palm',
                                                 hide_ylabel=True,
                                                 hide_yticks=True))

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax4,
                              include_samples={'body-site': ['tongue']},
                              **kwargs,
                              artist_kwargs=dict(title='tongue',
                                                 hide_ylabel=True,
                                                 hide_yticks=True))

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax5,
                              **kwargs,
                              artist_kwargs=dict(legend_only=True,
                                                 legend_loc='upper left',
                                                 legend_short=True))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-9-20210109.png')

We can select specific samples with sample_names. We can also manually set the x-axis tick labels with xticklabels. Finally, you can pick specific colors for the bars.

fig, [ax1, ax2, ax3] = plt.subplots(1, 3, figsize=(10, 5))

kwargs = dict(level=6, count=3, sample_names=['L2S382', 'L4S112'])

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax1,
                              **kwargs,
                              artist_kwargs=dict(show_legend=True,
                                                 legend_short=True,
                                                 legend_loc='upper right',
                                                 title="sample_names=['L2S382', 'L4S112']"))

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax2,
                              **kwargs,
                              artist_kwargs=dict(show_legend=True,
                                                 legend_short=True,
                                                 legend_loc='upper right',
                                                 title="xticklabels=['A', 'B']",
                                                 xticklabels=['A', 'B']))

dokdo.taxa_abundance_bar_plot(qzv_file,
                              ax=ax3,
                              colors=['tab:blue', 'tab:orange', 'tab:gray'],
                              **kwargs,
                              artist_kwargs=dict(show_legend=True,
                                                 legend_short=True,
                                                 legend_loc='upper right',
                                                 title="colors=['tab:blue', 'tab:orange', 'tab:gray']"))

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_bar_plot-10-20210109.png')

taxa_abundance_box_plot

taxa_abundance_box_plot(taxa, metadata=None, hue=None, hue_order=None, add_datapoints=False, level=1, by=None, ax=None, figsize=None, count=0, exclude_samples=None, include_samples=None, exclude_taxa=None, sort_by_names=False, sample_names=None, csv_file=None, size=5, pseudocount=False, taxa_names=None, brief_xlabels=False, show_means=False, meanprops=None, show_others=True, sort_by_mean=True, jitter=1, alpha=None, artist_kwargs=None)
    This method creates a taxa abundance box plot.

    Parameters
    ----------
    taxa : str or qiime2.Visualization
        Visualization file or object from the q2-taxa plugin.
    metadata : str or qiime2.Metadata, optional
        Metadata file or object.
    hue : str, optional
        Grouping variable that will produce boxes with different colors.
    hue_order : list, optional
        Specify the order of categorical levels of the 'hue' semantic.
    add_datapoints : bool, default: False
        Show datapoints on top of the boxes.
    level : int, default: 1
        Taxonomic level at which the features should be collapsed.
    by : list, optional
        Column name(s) to be used for sorting the samples. Using 'sample-id'
        will sort the samples by their name, in addition to other column
        name(s) that may have been provided. If multiple items are provided,
        sorting will occur by the order of the items.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    count : int, default: 0
        The number of taxa to display. When 0, display all.
    exclude_samples : dict, optional
        Filtering logic used for sample exclusion.
        Format: {'col': ['item', ...], ...}.
    include_samples : dict, optional
        Filtering logic used for sample inclusion.
        Format: {'col': ['item', ...], ...}.
    exclude_taxa : list, optional
        The taxa names to be excluded when matched. Case insenstivie.
    sort_by_names : bool, default: False
        If true, sort the columns (i.e. species) to be displayed by name.
    sample_names : list, optional
        List of sample IDs to be included.
    csv_file : str, optional
        Path of the .csv file to output the dataframe to.
    size : float, default: 5.0
        Radius of the markers, in points.
    pseudocount : bool, default: False
        Add pseudocount to remove zeros.
    taxa_names : list, optional
        List of taxa names to be displayed.
    brief_xlabels : bool, default: False
        If true, only display the smallest taxa rank in the x-axis labels.
    show_means : bool, default: False
        Add means to the boxes.
    meanprops : dict, optional
        The meanprops argument as in matplotlib.pyplot.boxplot.
    show_others : bool, default: True
        Include the 'Others' category.
    sort_by_mean : bool, default: True
        Sort taxa by their mean relative abundance after sample filtration.
    jitter : float, default: 1
        Amount of jitter (only along the categorical axis) to apply.
    alpha : float, optional
        Proportional opacity of the points.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    taxa_abundance_bar_plot
    addpairs

    Notes
    -----
    Example usage of the q2-taxa plugin:
        CLI -> qiime taxa barplot [OPTIONS]
        API -> from qiime2.plugins.taxa.visualizers import barplot

Below is a simple example showing taxonomic abundance at the phylum level (i.e. level=2).

qzv_file = 'data/moving-pictures-tutorial/taxa-bar-plots.qzv'

dokdo.taxa_abundance_box_plot(qzv_file, level=2)

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_box_plot-1-20210202.png')

taxa_abundance_box_plot-1-20210202

We can control how many taxa to display with count. Also, we can make the x-axis tick labels pretty with brief_xlabels. We can manually set the x-axis tick labels with xticklabels. Lastly, we can select specific taxa to display with taxa_names.

fig, [[ax1, ax2], [ax3, ax4]] = plt.subplots(2, 2, figsize=(10, 10))

kwargs = {'level' : 2}

artist_kwargs1 = dict(title='count=4')
artist_kwargs2 = dict(title='brief_xlabels=True')
artist_kwargs3 = dict(xticklabels=['A', 'B', 'C', 'D'], title="xticklabels=['A', 'B', 'C', 'D']")
artist_kwargs4 = dict(title="taxa_names=[...]")

dokdo.taxa_abundance_box_plot(qzv_file, ax=ax1, count=4, artist_kwargs=artist_kwargs1, **kwargs)
dokdo.taxa_abundance_box_plot(qzv_file, ax=ax2, count=4, brief_xlabels=True, artist_kwargs=artist_kwargs2, **kwargs)
dokdo.taxa_abundance_box_plot(qzv_file, ax=ax3, count=4, artist_kwargs=artist_kwargs3, **kwargs)
dokdo.taxa_abundance_box_plot(qzv_file, ax=ax4, taxa_names=['k__Bacteria;p__Firmicutes', 'k__Bacteria;p__Proteobacteria'], artist_kwargs=artist_kwargs4, **kwargs)

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_box_plot-2-20210202.png')

We can group the boxes by a metadata column with hue. For this plot, we will draw the y-axis in log scale with ylog. To do this, we actually need to adjust the y-axis limits with ymin and ymax, and also add a pseudocount of 1 to remove 0s with pseudocount (because 0s cannot be shown in log scale). We will also add data points with add_datapoints=True.

artist_kwargs = dict(ylog=True, ymin=0.05, ymax=200, show_legend=True)

dokdo.taxa_abundance_box_plot(qzv_file,
                              level=2,
                              figsize=(10, 7),
                              hue='body-site',
                              size=3,
                              count=4,
                              pseudocount=True,
                              add_datapoints=True,
                              artist_kwargs=artist_kwargs)

plt.tight_layout()
plt.savefig('images/Dokdo-API/taxa_abundance_box_plot-3-20210202.png')

ancom_volcano_plot

Help on function ancom_volcano_plot in module dokdo.api:

ancom_volcano_plot(ancom, ax=None, figsize=None, s=80, artist_kwargs=None)
    This method creates an ANCOM volcano plot.

    Parameters
    ----------
    ancom : str
        Visualization file or object from the q2-composition plugin.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    s : float, default: 80.0
        Marker size.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    Notes
    -----
    Example usage of the q2-composition plugin:
        CLI -> qiime composition ancom [OPTIONS]
        API -> from qiime2.plugins.composition.visualizers import ancom

Below is a simple example.

dokdo.ancom_volcano_plot('data/moving-pictures-tutorial/ancom-subject.qzv', figsize=(8, 5))

plt.tight_layout()
plt.savefig('images/Dokdo-API/ancom_volcano_plot-1C.png')

ancom_volcano_plot-1C

Other Plotting Methods

addsig

Help on function addsig in module dokdo.api:

addsig(x1, x2, y, t='', h=1.0, lw=1.0, lc='black', tc='black', ax=None, figsize=None, fontsize=None)
    This method adds signifiance annotation between two groups in a box plot.

    Parameters
    ----------
    x1 : float
        Position of the first box.
    x2 : float
        Position of the second box.
    y : float
        Bottom position of the drawing.
    t : str, default: ''
        Text.
    h : float, default: 1.0
        Height of the drawing.
    lw : float, default: 1.0
        Line width.
    lc : str, default: 'black'
        Line color.
    tc : str, default: 'black'
        Text color.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    fontsize : float, optional
        Sets the fontsize.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

Below is a simple example.

vector_file = 'data/moving-pictures-tutorial/faith_pd_vector.qza'
metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

ax = dokdo.alpha_diversity_plot(vector_file,
                                metadata_file,
                                'body-site',
                                figsize=(8, 5),
                                artist_kwargs=dict(ymin=0, ymax=30))

dokdo.addsig(0, 1, 20, t='***', ax=ax)
dokdo.addsig(1, 2, 26, t='ns', ax=ax)

plt.tight_layout()
plt.savefig('images/Dokdo-API/addsig-1-20210203.png')

addsig-1-20210203

addpairs

Help on function addpairs in module dokdo.api:

addpairs(taxon, csv_file, subject, category, group1, group2, p1=-0.2, p2=0.2, ax=None, figsize=None)
    This method adds lines between two groups in a plot generated by the
    taxa_abundance_box_plot() method.

    This method also prints the p-value for Wilcoxon signed-rank test.

    Parameters
    ----------
    taxon : str
        Target taxon name.
    csv_file : str
        Path to the .csv file from the `taxa_abundance_box_plot` method.
    subject : str
        Column name to indicate pair information.
    category : str
        Column name to be studied.
    group1 : str
        First group in the category column.
    group2 : str
        Second group in the category column.
    p1 : float, default: -0.2
        Start position of the lines.
    p2 : float, default: 0.2
        End position of the lines.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    taxa_abundance_box_plot

Below is a simple example where we pretend we only have the samples shown below. We are interested in comparing the relative abundance of Preteobacteria between the left palm and the right palm. We also want to perofrm the comparison in the context of days-since-experiment-start (i.e. paired comparison).

from qiime2 import Metadata

metadata = Metadata.load('data/moving-pictures-tutorial/sample-metadata.tsv')
sample_names = ['L2S240', 'L3S242', 'L2S155', 'L4S63', 'L2S175', 'L3S313', 'L2S204', 'L4S112', 'L2S222', 'L4S137']
metadata = metadata.filter_ids(sample_names)
mf = dokdo.get_mf(metadata)
mf
barcode-sequence body-site year month day subject reported-antibiotic-usage days-since-experiment-start
sample-id
L2S155 ACGATGCGACCA left palm 2009.0 1.0 20.0 subject-1 No 84.0
L2S175 AGCTATCCACGA left palm 2009.0 2.0 17.0 subject-1 No 112.0
L2S204 ATGCAGCTCAGT left palm 2009.0 3.0 17.0 subject-1 No 140.0
L2S222 CACGTGACATGT left palm 2009.0 4.0 14.0 subject-1 No 168.0
L3S242 ACAGTTGCGCGA right palm 2008.0 10.0 28.0 subject-1 Yes 0.0
L3S313 AGTGTCACGGTG right palm 2009.0 2.0 17.0 subject-1 No 112.0
L2S240 CATATCGCAGTT left palm 2008.0 10.0 28.0 subject-2 Yes 0.0
L4S63 CTCGTGGAGTAG right palm 2009.0 1.0 20.0 subject-2 No 84.0
L4S112 GCGTTACACACA right palm 2009.0 3.0 17.0 subject-2 No 140.0
L4S137 GAACTGTATCTC right palm 2009.0 4.0 14.0 subject-2 No 168.0
qzv_file = 'data/moving-pictures-tutorial/taxa-bar-plots.qzv'


ax = dokdo.taxa_abundance_box_plot(qzv_file,
                                   level=2,
                                   hue='body-site',
                                   taxa_names=['k__Bacteria;p__Proteobacteria'],
                                   show_others=False,
                                   figsize=(6, 6),
                                   sample_names=sample_names,
                                   add_datapoints=True,
                                   include_samples={'body-site': ['left palm', 'right palm']},
                                   csv_file='output/Dokdo-API/addpairs.csv',
                                   artist_kwargs=dict(show_legend=True, ymax=70))

plt.tight_layout()
dokdo.addpairs('k__Bacteria;p__Proteobacteria', 'output/Dokdo-API/addpairs.csv', 'days-since-experiment-start', 'body-site', 'left palm', 'right palm', ax=ax)
dokdo.addsig(-0.2, 0.2, 65, t='p-value = 0.0625', ax=ax)
plt.savefig('images/Dokdo-API/addpairs-1-20210203.png')

addpairs-1-20210203

addbiplot

Help on function addbiplot in module dokdo.api:

addbiplot(pcoa_results, taxonomy=None, dim=2, scale=1.0, count=5, fontsize=None, name_type='feature', level=None, ax=None, figsize=None)
    This methods adds arrows (i.e. features) to a PCoA scatter plot (both 2D
    and 3D).

    Parameters
    ----------
    pcoa_results : str or qiime2.Artifact
        Artifact file or object corresponding to
        PCoAResults % Properties('biplot').
    taxonomy : str or qiime2.Artifact
        Artifact file or object corresponding to FeatureData[Taxonomy].
        Required if `name_type='taxon'` or `name_type='confidence'.
    dim : [2, 3], default: 2
        Dimension of the input scatter plot.
    scale : float, default: 1.0
        Scale for arrow length.
    count : int, default: 5
        Number of important features to be displayed.
    fontsize : float or str, optional
        Sets font size.
    name_type : ['feature', 'taxon', 'confidence'], default: 'feature'
        Determines the type of names displayed. Using 'taxon' and 'confidence'
        requires taxonomy.
    level : int, optional
        Taxonomic rank to be displayed. Only use with `name_type='taxon'`.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    ordinate
    beta_2d_plot
    beta_3d_plot

Below is a simple example.

table_file = 'data/moving-pictures-tutorial/table.qza'
metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

pcoa_results = dokdo.ordinate(table_file, sampling_depth=0, biplot=True, number_of_dimensions=10)

ax = dokdo.beta_2d_plot(pcoa_results, hue='body-site', metadata=metadata_file, figsize=(8, 8), artist_kwargs=dict(show_legend=True))

dokdo.addbiplot(pcoa_results, ax=ax, count=3)

plt.tight_layout()
plt.savefig('images/Dokdo-API/addbiplot-1-20210203.png')

We can also draw a 3D biplot.

ax = dokdo.beta_3d_plot(pcoa_results, hue='body-site', metadata=metadata_file, figsize=(8, 8), artist_kwargs=dict(show_legend=True))

dokdo.addbiplot(pcoa_results, ax=ax, count=3, dim=3)

plt.tight_layout()
plt.savefig('images/Dokdo-API/addbiplot-2-20210203.png')

Finally, we can display taxonomic classification instead of feature ID.

taxonomy_file = 'data/moving-pictures-tutorial/taxonomy.qza'

ax = dokdo.beta_3d_plot(pcoa_results, hue='body-site', metadata=metadata_file, figsize=(8, 8), artist_kwargs=dict(show_legend=True))

dokdo.addbiplot(pcoa_results, ax=ax, count=3, dim=3, taxonomy=taxonomy_file, name_type='taxon', level=6)

plt.tight_layout()
plt.savefig('images/Dokdo-API/addbiplot-3-20210203.png')

barplot

Help on function barplot in module dokdo.api:

barplot(barplot_file, group, axis=0, figsize=(10, 10), level=1, count=0, items=None, by=None, label_columns=None, metadata=None, artist_kwargs=None, ylabel_fontsize=None, xaxis_repeated=False, cmap_name='Accent')
    This method creates a grouped abundance bar plot.

    Under the hood, this method essentially wraps the
    `taxa_abundance_bar_plot` method.

    Parameters
    ----------
    barplot_file : str or qiime2.Visualization
        Visualization file or object from the q2-taxa plugin.
    group : str
        Metadata column.
    axis : int, default : 0
        By default, charts will be stacked vertically. Use 1 for horizontal
        stacking.
    figsize : tuple, default: (10, 10)
        Width, height in inches. Format: (float, float).
    level : int, default: 1
        Taxonomic level at which the features should be collapsed.
    count : int, default: 0
        The number of taxa to display. When 0, display all.
    items : list, optional
        Specify the order of charts.
    by : list, optional
        Column name(s) to be used for sorting the samples. Using 'index' will
        sort the samples by their name, in addition to other column name(s)
        that may have been provided. If multiple items are provided, sorting
        will occur by the order of the items.
    label_columns : list, optional
        The column names to be used as the x-axis labels.
    metadata : str or qiime2.Metadata, optional
        Metadata file or object.
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.
    ylabel_fontsize : float or str, optional
        Sets the y-axis label font size.
    xaxis_repeated : bool, default: False
        If true, remove all x-axis tick labels except for the bottom subplot.
        Ignored if `axis=1`.
    cmap_name : str, default: 'Accent'
        Name of the colormap passed to `matplotlib.cm.get_cmap()`.

    See Also
    --------
    taxa_abundance_bar_plot

Below is a simple example.

barplot_file = 'data/moving-pictures-tutorial/taxa-bar-plots.qzv'

dokdo.barplot(barplot_file, 'body-site', axis=1, figsize=(10, 6), level=6, count=8)

plt.savefig('images/Dokdo-API/barplot-1-20201217.png')

We can draw the subplots vertically, which is particularly useful when the samples are matched.

dokdo.barplot(barplot_file, 'body-site', axis=0, figsize=(8, 10), level=6, count=8, xaxis_repeated=True)

plt.savefig('images/Dokdo-API/barplot-2-20201217.png')

heatmap

Help on function heatmap in module dokdo.api:

heatmap(table, metadata=None, hue=None, hue_order=None, normalize=True, method='average', metric='euclidean', figsize=(10, 10), row_cluster=True, col_cluster=True, cmap_name='tab10')
    This method creates a heatmap representation of a feature table.

    Parameters
    ----------
    table : str or qiime2.Artifact
        Artifact file or object corresponding to FeatureTable[Frequency].
    metadata : str or qiime2.Metadata, optional
        Metadata file or object.
    hue : str, optional
        Grouping variable that will produce labels with different colors.
    hue_order : list, optional
        Specify the order of categorical levels of the 'hue' semantic.
    normalize : bool, default: True
        Normalize the feature table by adding a psuedocount of 1 and then
        taking the log10 of the table.
    method : str, default: 'average'
        Linkage method to use for calculating clusters. See
        `scipy.cluster.hierarchy.linkage()` documentation for more information.
    metric : str, default: 'euclidean'
        Distance metric to use for the data. See
        `scipy.spatial.distance.pdist()` documentation for more options.
    figsize : tuple, default: (10, 10)
        Width, height in inches. Format: (float, float).
    row_cluster : bool, default: True
        If True, cluster the rows.
    col_cluster : bool, default: True
        If True, cluster the columns.
    cmap_name : str, default: 'tab10'
        Name of the colormap passed to `matplotlib.cm.get_cmap()`.

    Returns
    -------
    seaborn.matrix.ClusterGrid
        A ClusterGrid instance.

Below is a simple example.

table_file = 'data/moving-pictures-tutorial/table.qza'

dokdo.heatmap(table_file)

plt.savefig('images/Dokdo-API/heatmap-1-20210202.png')

We can color the samples by body-site.

metadata_file = 'data/moving-pictures-tutorial/sample-metadata.tsv'

dokdo.heatmap(table_file, metadata=metadata_file, hue='body-site')

plt.savefig('images/Dokdo-API/heatmap-2-20210202.png')

regplot

Help on function regplot in module dokdo.api:

regplot(taxon, csv_file, subject, category, group1, group2, label=None, ax=None, figsize=None, artist_kwargs=None)
    Plot relative abundance data and a linear regression model fit from
    paired samples for the given taxon.

    Parameters
    ----------
    taxon : str
        Target taxon name.
    csv_file : str
        Path to the .csv file from the `taxa_abundance_box_plot` method.
    subject : str
        Column name to indicate pair information.
    category : str
        Column name to be studied.
    group1 : str
        First group in the category column.
    group2 : str
        Second group in the category column.
    label : str
        Label to use in a legend.
    ax : matplotlib.axes.Axes, optional
        Axes object to draw the plot onto, otherwise uses the current Axes.
    figsize : tuple, optional
        Width, height in inches. Format: (float, float).
    artist_kwargs : dict, optional
        Keyword arguments passed down to the _artist() method.

    Returns
    -------
    matplotlib.axes.Axes
        Axes object with the plot drawn onto it.

    See Also
    --------
    taxa_abundance_box_plot

Below is a simple example where we pretend we only have the samples shown below. We are interested in comparing the relative abundance of Preteobacteria between the left palm and the right palm. We also want to perofrm the comparison in the context of days-since-experiment-start (i.e. paired comparison).

from qiime2 import Metadata

metadata = Metadata.load('data/moving-pictures-tutorial/sample-metadata.tsv')
sample_names = ['L2S240', 'L3S242', 'L2S155', 'L4S63', 'L2S175', 'L3S313', 'L2S204', 'L4S112', 'L2S222', 'L4S137']
metadata = metadata.filter_ids(sample_names)
mf = dokdo.get_mf(metadata)
mf
barcode-sequence body-site year month day subject reported-antibiotic-usage days-since-experiment-start
sample-id
L2S155 ACGATGCGACCA left palm 2009.0 1.0 20.0 subject-1 No 84.0
L2S175 AGCTATCCACGA left palm 2009.0 2.0 17.0 subject-1 No 112.0
L2S204 ATGCAGCTCAGT left palm 2009.0 3.0 17.0 subject-1 No 140.0
L2S222 CACGTGACATGT left palm 2009.0 4.0 14.0 subject-1 No 168.0
L3S242 ACAGTTGCGCGA right palm 2008.0 10.0 28.0 subject-1 Yes 0.0
L3S313 AGTGTCACGGTG right palm 2009.0 2.0 17.0 subject-1 No 112.0
L2S240 CATATCGCAGTT left palm 2008.0 10.0 28.0 subject-2 Yes 0.0
L4S63 CTCGTGGAGTAG right palm 2009.0 1.0 20.0 subject-2 No 84.0
L4S112 GCGTTACACACA right palm 2009.0 3.0 17.0 subject-2 No 140.0
L4S137 GAACTGTATCTC right palm 2009.0 4.0 14.0 subject-2 No 168.0

Next, we will run the taxa_abundance_box_plot() method to create the input file for the regplot() method.

qzv_file = 'data/moving-pictures-tutorial/taxa-bar-plots.qzv'

dokdo.taxa_abundance_box_plot(qzv_file,
                              level=2,
                              hue='body-site',
                              taxa_names=['k__Bacteria;p__Proteobacteria'],
                              show_others=False,
                              figsize=(6, 6),
                              sample_names=sample_names,
                              add_datapoints=True,
                              include_samples={'body-site': ['left palm', 'right palm']},
                              csv_file='output/Dokdo-API/addpairs.csv',
                              artist_kwargs=dict(show_legend=True, ymax=70))

Finally, run the regplot() method.

dokdo.regplot('k__Bacteria;p__Proteobacteria',
              'output/Dokdo-API/addpairs.csv',
              'days-since-experiment-start',
              'body-site',
              'left palm',
              'right palm')

plt.tight_layout()
plt.savefig('images/Dokdo-API/regplot-1-20210203.png')

regplot-1-20210203

15 Likes

Hi! Thank you for an excellent tutorial!
It would be nice to have it earlier when I was redrawing a lot of figures from Qiime2 in Python and Jupyter lab :laughing:
Will save it for the future

4 Likes

Hi @sbslee, this is really neat! :desktop_computer:

Thank you so much for sharing this with the :qiime2: community!

3 Likes

Hello! This is just to announce that a new version of Dokdo is available (1.1.0). The tutorial has been updated to reflect the changes as well. If you have any questions, please let me know.

4 Likes

A new version of Dokdo (1.2.0) is available now! The tutorial has been updated accordingly. The biggest API change is that you can now control the font size for titles, labels, tick labels, legend, etc. See the Title, Axis, Legend, Font Size section for details.

5 Likes

Dokdo 1.3.0 is available now and the tutorial has been updated accordingly. From the CHANGELOG.md file in Dokdo:

1.3.0

  • Updated the ordinate() method so that the user can now choose to:
    • skip rarefying,
    • provide custom sampling depth for rarefying,
    • provide qiime2.Artifact as input instead of file path, and
    • output PCoAResults % Properties('biplot') as well as PCoAResults .
  • Added new plotting methods:
    • beta_scree_plot()
    • beta_parallel_plot()
    • addbiplot()
    • barplot()
  • See #2 for more details.
3 Likes

Dokdo 1.4.0 is available now and the tutorial has been updated accordingly. From the CHANGELOG.md file in Dokdo:

1.4.0

  • Added a new command called summarize.
  • Added a new plotting method called heatmap().
  • Updated the following commands:
    • make_manifest
    • add_metadata
    • collapse
  • Updated the following methods:
    • _artist()
    • alpha_rarefaction_plot()
    • taxa_abundance_bar_plot()
    • taxa_abundance_box_plot()
  • See #4 for more details.
3 Likes

Dokdo 1.5.0 is available now and the tutorial has been updated accordingly. From the CHANGELOG.md file in Dokdo:

1.5.0

  • Starting this version, Dokdo is packaged with setuptools.
  • There have been major changes to the Dokdo CLI.
  • Added a new plotting method called regplot().
  • Added a new command called prepare-lefse.
  • The merge_metadata command has been deprecated.
  • Updated the following methods:
    • _artist()
    • alpha_diversity_plot()
    • beta_3d_plot()
    • beta_parallel_plot()
    • barplot()
    • ordinate()
    • taxa_abundance_bar_plot()
    • taxa_abundance_box_plot()
    • heatmap()
  • Updated the make_manifest command.
  • See #6 for more details.
4 Likes

Dokdo 1.6.0 is available now, but the tutorial will not be updated anymore for the reasons stated in the edited post above.

5 Likes

Dokdo 1.7.0 is available now, but the tutorial will not be updated anymore for the reasons stated in the edited post above.

1 Like

Dokdo 1.8.0 is available now, but the tutorial will not be updated anymore for the reasons stated in the edited post above.

3 Likes

Dokdo 1.9.0 is available now, but the tutorial will not be updated anymore for the reasons stated in the edited post above.

2 Likes