Beta diversity visualizations

Beta diversity visualizations#

Generating and exploring ordination plots#

umap is an ordination method that can be used in place of PCoA and has been shown to better resolve differences between microbiome samples in ordination plots [AMR+21]. Like PCoA, umap operates on distance matrices. We’ll compute this on our weighted and unweighted UniFrac distance matrices. For the moment, there won’t be anything to visualize as a result of these steps: we’ll come back to visualization of these results shortly.

uu_umap, = diversity_actions.umap(
    distance_matrix=unweighted_unifrac_distance_matrix,
)
wu_umap, = diversity_actions.umap(
    distance_matrix=weighted_unifrac_distance_matrix,
)

action_results <- diversity_actions$umap(
    distance_matrix=unweighted_unifrac_distance_matrix,
)
uu_umap <- action_results$umap
action_results <- diversity_actions$umap(
    distance_matrix=weighted_unifrac_distance_matrix,
)
wu_umap <- action_results$umap

qiime diversity umap \
  --i-distance-matrix diversity-core-metrics-phylogenetic/unweighted_unifrac_distance_matrix.qza \
  --o-umap uu-umap.qza
qiime diversity umap \
  --i-distance-matrix diversity-core-metrics-phylogenetic/weighted_unifrac_distance_matrix.qza \
  --o-umap wu-umap.qza

uu_umap, = use.action(
    use.UsageAction(plugin_id='diversity', action_id='umap'),
    use.UsageInputs(distance_matrix=core_metrics_results.unweighted_unifrac_distance_matrix),
    use.UsageOutputNames(umap='uu_umap')
)

wu_umap, = use.action(
    use.UsageAction(plugin_id='diversity', action_id='umap'),
    use.UsageInputs(distance_matrix=core_metrics_results.weighted_unifrac_distance_matrix),
    use.UsageOutputNames(umap='wu_umap')
)

Using the qiime2 diversity umap tool:

Set “distance_matrix” to #: qiime2 diversity core-metrics-phylogenetic [...] : unweighted_unifrac_distance_matrix.qza
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 diversity umap [...] : umap.qza`	`uu-umap.qza`

Using the qiime2 diversity umap tool:

Set “distance_matrix” to #: qiime2 diversity core-metrics-phylogenetic [...] : weighted_unifrac_distance_matrix.qza
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 diversity umap [...] : umap.qza`	`wu-umap.qza`

uu-umap.qza | view | download
wu-umap.qza | view | download

A useful feature of QIIME 2 is that you can integrate data that is per-sample as “metadata” in other visualizations. For example, alpha diversity values such as Faith’s Phylogenetic Diversity, are computed on a per-sample basis and thus can be viewed or used as QIIME 2 sample metadata. Since beta diversity metrics such as UniFrac are computed on pairs of samples, they’re not as useful to view or use as metadata. However ordination values computed from distance matrices, for example a sample’s PCoA or umap axis 1 and axis 2 values, are computed per sample and so can be viewed or used as metadata.

In the next few steps, we’ll integrate our unweighted UniFrac umap axis 1 values, and our Faith PD, evenness, and Shannon diversity values, as metadata in visualizations. This will provide a few different ways of interpreting these values.

uu_umap_as_metadata_md = uu_umap.view(Metadata)
faith_pd_as_metadata_md = faith_pd_vector.view(Metadata)
evenness_as_metadata_md = evenness_vector.view(Metadata)
shannon_as_metadata_md = shannon_vector.view(Metadata)
expanded_sample_metadata_md = sample_metadata_md.merge(uu_umap_as_metadata_md, faith_pd_as_metadata_md, evenness_as_metadata_md, shannon_as_metadata_md)

uu_umap_as_metadata_md <- uu_umap$view(Metadata)
faith_pd_as_metadata_md <- faith_pd_vector$view(Metadata)
evenness_as_metadata_md <- evenness_vector$view(Metadata)
shannon_as_metadata_md <- shannon_vector$view(Metadata)
expanded_sample_metadata_md <- sample_metadata_md$merge(uu_umap_as_metadata_md, faith_pd_as_metadata_md, evenness_as_metadata_md, shannon_as_metadata_md)

uu_umap_as_metadata = use.view_as_metadata('uu_umap_as_metadata', uu_umap)
faith_pd_as_metadata = use.view_as_metadata('faith_pd_as_metadata', core_metrics_results.faith_pd_vector)
evenness_as_metadata = use.view_as_metadata('evenness_as_metadata', core_metrics_results.evenness_vector)
shannon_as_metadata = use.view_as_metadata('shannon_as_metadata', core_metrics_results.shannon_vector)


expanded_sample_metadata = use.merge_metadata('expanded_sample_metadata',
                                              sample_metadata,
                                              uu_umap_as_metadata,
                                              faith_pd_as_metadata,
                                              evenness_as_metadata,
                                              shannon_as_metadata)

expanded_metadata_summ_viz, = metadata_actions.tabulate(
    input=expanded_sample_metadata_md,
)

action_results <- metadata_actions$tabulate(
    input=expanded_sample_metadata_md,
)
expanded_metadata_summ_viz <- action_results$visualization

qiime metadata tabulate \
  --m-input-file sample-metadata.tsv uu-umap.qza diversity-core-metrics-phylogenetic/faith_pd_vector.qza diversity-core-metrics-phylogenetic/evenness_vector.qza diversity-core-metrics-phylogenetic/shannon_vector.qza \
  --o-visualization expanded-metadata-summ.qzv

use.action(
    use.UsageAction(plugin_id='metadata', action_id='tabulate'),
    use.UsageInputs(input=expanded_sample_metadata),
    use.UsageOutputNames(visualization='expanded_metadata_summ')
)

Using the qiime2 metadata tabulate tool:

For “input”:
1. Perform the following steps.
  1. Leave as Metadata from TSV
  2. Set “Metadata Source” to sample-metadata.tsv
2. Press the + Insert input button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to uu-umap.qza
3. Press the + Insert input button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : faith_pd_vector.qza
4. Press the + Insert input button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : evenness_vector.qza
5. Press the + Insert input button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : shannon_vector.qza
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 metadata tabulate [...] : visualization.qzv`	`expanded-metadata-summ.qzv`

expanded-metadata-summ.qzv | view | download

To see how this information can be used, let’s generate another version of our taxonomy barplots that includes these new metadata values.

taxa_bar_plots_2_viz, = taxa_actions.barplot(
    table=filtered_table_4,
    taxonomy=taxonomy,
    metadata=expanded_sample_metadata_md,
)

action_results <- taxa_actions$barplot(
    table=filtered_table_4,
    taxonomy=taxonomy,
    metadata=expanded_sample_metadata_md,
)
taxa_bar_plots_2_viz <- action_results$visualization

qiime taxa barplot \
  --i-table filtered-table-4.qza \
  --i-taxonomy taxonomy.qza \
  --m-metadata-file sample-metadata.tsv uu-umap.qza diversity-core-metrics-phylogenetic/faith_pd_vector.qza diversity-core-metrics-phylogenetic/evenness_vector.qza diversity-core-metrics-phylogenetic/shannon_vector.qza \
  --o-visualization taxa-bar-plots-2.qzv

use.action(
    use.UsageAction(plugin_id='taxa', action_id='barplot'),
    use.UsageInputs(table=filtered_table_4, taxonomy=taxonomy,
                    metadata=expanded_sample_metadata),
    use.UsageOutputNames(visualization='taxa_bar_plots_2'),
)

Using the qiime2 taxa barplot tool:

Set “table” to #: filtered-table-4.qza
Expand the additional options section
1. Set “taxonomy” to #: taxonomy.qza
2. For “metadata”:
  1. Press the + Insert metadata button to set up the next steps.
    1. Leave as Metadata from TSV
    2. Set “Metadata Source” to sample-metadata.tsv
  2. Press the + Insert metadata button to set up the next steps.
    1. Change to Metadata from Artifact
    2. Set “Metadata Source” to uu-umap.qza
  3. Press the + Insert metadata button to set up the next steps.
    1. Change to Metadata from Artifact
    2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : faith_pd_vector.qza
  4. Press the + Insert metadata button to set up the next steps.
    1. Change to Metadata from Artifact
    2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : evenness_vector.qza
  5. Press the + Insert metadata button to set up the next steps.
    1. Change to Metadata from Artifact
    2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : shannon_vector.qza
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 taxa barplot [...] : visualization.qzv`	`taxa-bar-plots-2.qzv`

taxa-bar-plots-2.qzv | view | download

Tip

QIIME 2’s q2-diversity plugin provides visualizations for assessing whether microbiome composition differs across groups of independent samples (for example, individuals with a certain disease state and healthy controls) and for assessing whether differences in microbiome composition are correlated with differences in a continuous variable (for example, subjects’ body mass index). These tools assume that all samples are independent of one another, and therefore aren’t applicable to the data used in this tutorial where multiple samples are obtained from the same individual. We therefore don’t illustrate the use of these visualizations on this data, but you can learn about these approaches and view examples in the Moving Pictures tutorial. The Moving Pictures tutorial contains example data and commands, like this tutorial does, so you can experiment with generating these visualizations on your own.

We’ll start by integrating these values as metadata in our ordination plots. We’ll also customize these plots in another way: in addition to plotting the ordination axes, we’ll add an explicit time axis to these plots. This is often useful for visualization patterns in ordination plots in time series studies. We’ll add an axis for week-relative-to-hct.

import qiime2.plugins.emperor.actions as emperor_actions

uu_umap_emperor_w_time_viz, = emperor_actions.plot(
    pcoa=uu_umap,
    metadata=expanded_sample_metadata_md,
    custom_axes=['week-relative-to-hct'],
)
wu_umap_emperor_w_time_viz, = emperor_actions.plot(
    pcoa=wu_umap,
    metadata=expanded_sample_metadata_md,
    custom_axes=['week-relative-to-hct'],
)
uu_pcoa_emperor_w_time_viz, = emperor_actions.plot(
    pcoa=unweighted_unifrac_pcoa_results,
    metadata=expanded_sample_metadata_md,
    custom_axes=['week-relative-to-hct'],
)
wu_pcoa_emperor_w_time_viz, = emperor_actions.plot(
    pcoa=weighted_unifrac_pcoa_results,
    metadata=expanded_sample_metadata_md,
    custom_axes=['week-relative-to-hct'],
)

emperor_actions <- import("qiime2.plugins.emperor.actions")

action_results <- emperor_actions$plot(
    pcoa=uu_umap,
    metadata=expanded_sample_metadata_md,
    custom_axes=list('week-relative-to-hct'),
)
uu_umap_emperor_w_time_viz <- action_results$visualization
action_results <- emperor_actions$plot(
    pcoa=wu_umap,
    metadata=expanded_sample_metadata_md,
    custom_axes=list('week-relative-to-hct'),
)
wu_umap_emperor_w_time_viz <- action_results$visualization
action_results <- emperor_actions$plot(
    pcoa=unweighted_unifrac_pcoa_results,
    metadata=expanded_sample_metadata_md,
    custom_axes=list('week-relative-to-hct'),
)
uu_pcoa_emperor_w_time_viz <- action_results$visualization
action_results <- emperor_actions$plot(
    pcoa=weighted_unifrac_pcoa_results,
    metadata=expanded_sample_metadata_md,
    custom_axes=list('week-relative-to-hct'),
)
wu_pcoa_emperor_w_time_viz <- action_results$visualization

qiime emperor plot \
  --i-pcoa uu-umap.qza \
  --m-metadata-file sample-metadata.tsv uu-umap.qza diversity-core-metrics-phylogenetic/faith_pd_vector.qza diversity-core-metrics-phylogenetic/evenness_vector.qza diversity-core-metrics-phylogenetic/shannon_vector.qza \
  --p-custom-axes week-relative-to-hct \
  --o-visualization uu-umap-emperor-w-time.qzv
qiime emperor plot \
  --i-pcoa wu-umap.qza \
  --m-metadata-file sample-metadata.tsv uu-umap.qza diversity-core-metrics-phylogenetic/faith_pd_vector.qza diversity-core-metrics-phylogenetic/evenness_vector.qza diversity-core-metrics-phylogenetic/shannon_vector.qza \
  --p-custom-axes week-relative-to-hct \
  --o-visualization wu-umap-emperor-w-time.qzv
qiime emperor plot \
  --i-pcoa diversity-core-metrics-phylogenetic/unweighted_unifrac_pcoa_results.qza \
  --m-metadata-file sample-metadata.tsv uu-umap.qza diversity-core-metrics-phylogenetic/faith_pd_vector.qza diversity-core-metrics-phylogenetic/evenness_vector.qza diversity-core-metrics-phylogenetic/shannon_vector.qza \
  --p-custom-axes week-relative-to-hct \
  --o-visualization uu-pcoa-emperor-w-time.qzv
qiime emperor plot \
  --i-pcoa diversity-core-metrics-phylogenetic/weighted_unifrac_pcoa_results.qza \
  --m-metadata-file sample-metadata.tsv uu-umap.qza diversity-core-metrics-phylogenetic/faith_pd_vector.qza diversity-core-metrics-phylogenetic/evenness_vector.qza diversity-core-metrics-phylogenetic/shannon_vector.qza \
  --p-custom-axes week-relative-to-hct \
  --o-visualization wu-pcoa-emperor-w-time.qzv

use.action(
    use.UsageAction(plugin_id='emperor', action_id='plot'),
    use.UsageInputs(pcoa=uu_umap, metadata=expanded_sample_metadata,
                    custom_axes=['week-relative-to-hct']),
    use.UsageOutputNames(visualization='uu_umap_emperor_w_time')
)

use.action(
    use.UsageAction(plugin_id='emperor', action_id='plot'),
    use.UsageInputs(pcoa=wu_umap, metadata=expanded_sample_metadata,
                    custom_axes=['week-relative-to-hct']),
    use.UsageOutputNames(visualization='wu_umap_emperor_w_time')
)

use.action(
    use.UsageAction(plugin_id='emperor', action_id='plot'),
    use.UsageInputs(pcoa=core_metrics_results.unweighted_unifrac_pcoa_results,
                    metadata=expanded_sample_metadata,
                    custom_axes=['week-relative-to-hct']),
    use.UsageOutputNames(visualization='uu_pcoa_emperor_w_time')
)

use.action(
    use.UsageAction(plugin_id='emperor', action_id='plot'),
    use.UsageInputs(pcoa=core_metrics_results.weighted_unifrac_pcoa_results,
                    metadata=expanded_sample_metadata,
                    custom_axes=['week-relative-to-hct']),
    use.UsageOutputNames(visualization='wu_pcoa_emperor_w_time')
)

Using the qiime2 emperor plot tool:

Set “pcoa” to #: uu-umap.qza
For “metadata”:
1. Perform the following steps.
  1. Leave as Metadata from TSV
  2. Set “Metadata Source” to sample-metadata.tsv
2. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to uu-umap.qza
3. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : faith_pd_vector.qza
4. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : evenness_vector.qza
5. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : shannon_vector.qza
Expand the additional options section
- For “custom_axes”:
  1. Set “element” to week-relative-to-hct
  2. (Do not insert additional values.)
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 emperor plot [...] : visualization.qzv`	`uu-umap-emperor-w-time.qzv`

Using the qiime2 emperor plot tool:

Set “pcoa” to #: wu-umap.qza
For “metadata”:
1. Perform the following steps.
  1. Leave as Metadata from TSV
  2. Set “Metadata Source” to sample-metadata.tsv
2. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to uu-umap.qza
3. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : faith_pd_vector.qza
4. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : evenness_vector.qza
5. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : shannon_vector.qza
Expand the additional options section
- For “custom_axes”:
  1. Set “element” to week-relative-to-hct
  2. (Do not insert additional values.)
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 emperor plot [...] : visualization.qzv`	`wu-umap-emperor-w-time.qzv`

Using the qiime2 emperor plot tool:

Set “pcoa” to #: qiime2 diversity core-metrics-phylogenetic [...] : unweighted_unifrac_pcoa_results.qza
For “metadata”:
1. Perform the following steps.
  1. Leave as Metadata from TSV
  2. Set “Metadata Source” to sample-metadata.tsv
2. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to uu-umap.qza
3. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : faith_pd_vector.qza
4. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : evenness_vector.qza
5. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : shannon_vector.qza
Expand the additional options section
- For “custom_axes”:
  1. Set “element” to week-relative-to-hct
  2. (Do not insert additional values.)
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 emperor plot [...] : visualization.qzv`	`uu-pcoa-emperor-w-time.qzv`

Using the qiime2 emperor plot tool:

Set “pcoa” to #: qiime2 diversity core-metrics-phylogenetic [...] : weighted_unifrac_pcoa_results.qza
For “metadata”:
1. Perform the following steps.
  1. Leave as Metadata from TSV
  2. Set “Metadata Source” to sample-metadata.tsv
2. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to uu-umap.qza
3. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : faith_pd_vector.qza
4. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : evenness_vector.qza
5. Press the + Insert metadata button to set up the next steps.
  1. Change to Metadata from Artifact
  2. Set “Metadata Source” to qiime2 diversity core-metrics-phylogenetic [...] : shannon_vector.qza
Expand the additional options section
- For “custom_axes”:
  1. Set “element” to week-relative-to-hct
  2. (Do not insert additional values.)
Press the Execute button.

Once completed, for the new entry in your history, use the Edit button to set the name as follows:

(Renaming is optional, but it will make any subsequent steps easier to complete.)

History Name	“Name” to set (be sure to press `Save`)
`#: qiime2 emperor plot [...] : visualization.qzv`	`wu-pcoa-emperor-w-time.qzv`

uu-umap-emperor-w-time.qzv | view | download
wu-umap-emperor-w-time.qzv | view | download
uu-pcoa-emperor-w-time.qzv | view | download
wu-pcoa-emperor-w-time.qzv | view | download

You have now generated ordination plots all combinations of two different diversity metrics (weighted and unweighted UniFrac) and two different ordination techniques (PCoA and umap). View these plots and consider what is similar and different about each.

Beta diversity visualizations

Contents

Beta diversity visualizations#

Generating and exploring ordination plots#