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:
  1. Set “distance_matrix” to #: qiime2 diversity core-metrics-phylogenetic [...] : unweighted_unifrac_distance_matrix.qza

  2. 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:
  1. Set “distance_matrix” to #: qiime2 diversity core-metrics-phylogenetic [...] : weighted_unifrac_distance_matrix.qza

  2. 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

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:
  1. 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

  2. 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

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:
  1. Set “table” to #: filtered-table-4.qza

  2. 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

  3. 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

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:
  1. Set “pcoa” to #: uu-umap.qza

  2. 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

  3. Expand the additional options section

    • For “custom_axes”:

      1. Set “element” to week-relative-to-hct

      2. (Do not insert additional values.)

  4. 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:
  1. Set “pcoa” to #: wu-umap.qza

  2. 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

  3. Expand the additional options section

    • For “custom_axes”:

      1. Set “element” to week-relative-to-hct

      2. (Do not insert additional values.)

  4. 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:
  1. Set “pcoa” to #: qiime2 diversity core-metrics-phylogenetic [...] : unweighted_unifrac_pcoa_results.qza

  2. 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

  3. Expand the additional options section

    • For “custom_axes”:

      1. Set “element” to week-relative-to-hct

      2. (Do not insert additional values.)

  4. 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:
  1. Set “pcoa” to #: qiime2 diversity core-metrics-phylogenetic [...] : weighted_unifrac_pcoa_results.qza

  2. 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

  3. Expand the additional options section

    • For “custom_axes”:

      1. Set “element” to week-relative-to-hct

      2. (Do not insert additional values.)

  4. 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

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.