Publication Plots in R (Self-Study)¶

This page is a self-study reference. It expands on the short Day 2 demo on Getting Data Into R and provides a tutorial for you to work through to run longitudinal stats and generate publication quality figures.

Work through it at your own pace after the workshop.

Tutorial Location

This tutorial was designed to be run on your local computer, not on Alpine, although you can use R on Alpine. If you would like to use R on Alpine, some adjustments may need to be made for the tutorial to run smoothly.

Directory for the tutorial¶

You can download the zipped directory with all the files needed for the decomp R stats and publication quality figures tutorial here:

Download the R tutorial files

These are the same files that were extracted from QIIME2 outputs in the Getting Data Into R tutorial. They have been organized into a structured directory to make the tutorial easier to follow.

Directory Download

The r_decomp_tutorial directory is downloaded as a zip file. Before using it, you will need to unzip it and then move the unzipped folder to wherever you want to work through the tutorial on your local computer. On Macs, you can usually unzip the file by double-clicking it in your Downloads folder. On Windows, you can unzip it by right-clicking the file and selecting Extract All. You can also use the command line commands below.

Mac:

unzip r_decomp_tutorial.zip

Windows:

Expand-Archive -Path r_decomp_tutorial.zip -DestinationPath r_decomp_tutorial

Directory Set up¶

Inside this directory:

01_notes - This is where any project background/notes on can be stored.

02_data - Raw data such as sequencing, or other qiime2 outputs can go here.

03_metadata - Metadata for you project can be stored here, including any previous versions.

metadata.txt- This is the metadata for the decomp data set, it is the same as the one we used in qiime and has the sample id and any other data that can be used for analysis and figure generation.

04_code - Code for you project can go here. There can be subdirectories for each analysis.

04_code.Rproj- This is the R project file that opens the tutorial as a self-contained project.
decomp_stats_figures.Rmd- This is the R Markdown file that contains the tutorial you will work through. It is located in the 04_code directory.
Diversity metrics: evenness.tsv, faith_pd.tsv, observed_features.tsv, shannon.tsv, bray_curtis.txt, jaccard.txt, unweighted_unifrac.txt, weighted_unifrac.txt, tabulated_results.tsv - These are the exported diversity metric files. They are located in the 04_code directory under the corresponding metric folders (alpha_div, beta_div, and taxonomy). - The metrics are stored in 04_code to simplify file paths for the tutorial, but they could also be placed in 02_rawdata or another data directory.

05_figures - Figures from analysis or for publications can be stored here.

Figures generated by the R Markdown are saved into the 05_figures directory using ggsave().

README.txt - This is a text file that usually gives some background on the project, here it has what files are included in the directory and how to get started in R.

Setting up R and R Studio¶

If you don't already have R and R studio they can be donwloaded here:

R: https://www.r-project.org/

R studio: https://posit.co/downloads

What is R and R Studio?

From the BYU Department of Statistics: R is a free software programming language and a software environment for statistical computing and graphics. The R language is widely used among statisticians and data miners for developing statistical software and data analysis.

R the application is installed on your computer and uses your personal computer resources to process R programming language. RStudio integrates with R as an IDE (Integrated Development Environment) to provide further functionality. RStudio combines a source code editor, build automation tools and a debugger.

Getting Started in R¶

To start the analysis, first click the 04_code.Rproj file in the 04_code directory. This will open an R project.

An R project helps bundle your work into a portable, self-contained folder. Within the project, all relevant scripts, data files, figures, outputs, and history are stored in subfolders, and the working directory is the project root.

Once the R project is open, you should initially see three panels in RStudio. In the bottom-right panel, click the Files tab, and you should see decomp_stats_figures.Rmd. Click decomp_stats_figures.Rmd, and a fourth panel in the upper-left will open. This is the R Markdown file you will work through for the stats and figures tutorial.

This Markdown file contains non-code chunks where instructions, explanations, and notes are written. These chunks are white. There are also code chunks, which contain executable code. To run these chunks, press the green play button in the upper-right corner of the chunk. To run individual lines in a chunk, highlight the line or place your cursor on the line you want to run and press Ctrl + Enter on Windows/Linux or Cmd + Enter on Mac.

It is important to execute the code chunks in the order they are presented. Running them out of order can cause errors because data may not have been loaded or cleaned before the code runs.

Once you are done working make sure to save any changes you have made.

Important notes¶

The code in this tutorial is an example and was made specifically for the decomp dataset. For your own data, this is a good starting point, but the code will need to be modified to match your specific data.
Some common errors are file path errors. This can happen if a file is moved and the file path in the code is no longer correct. To fix this, double-check that the file location and file path match exactly.
When working in R, it is a good habit to use relative file paths whenever possible, since they are more portable than absolute paths. However if R can't find a file, an absolute file path usually solves that issue.
Make sure the packages used in the tutorial are installed and loaded before running the code.
Save your work often, especially after generating figures or creating new data objects.
If an error appears, read the message carefully. R error messages often point to the line or object that needs attention.
Comments in the code are there to help explain what each step is doing, so feel free to use them as a guide while working through the tutorial.

Other ways to export QIIME2 data¶

Using QIIME2 commands to export data

Export α-Diversity Vectors¶

qiime tools export \
  --input-path core_metrics/evenness_vector.qza \
  --output-path output_for_R

mv output_for_R/alpha-diversity.tsv output_for_R/evenness_vector.tsv

qiime tools export \
  --input-path core_metrics/faith_pd_vector.qza \
  --output-path output_for_R

mv output_for_R/alpha-diversity.tsv output_for_R/faith_pd_vector.tsv

qiime tools export \
  --input-path core_metrics/observed_features_vector.qza \
  --output-path output_for_R

mv output_for_R/alpha-diversity.tsv output_for_R/observed_features_vector.tsv

qiime tools export \
  --input-path core_metrics/shannon_vector.qza \
  --output-path output_for_R

mv output_for_R/alpha-diversity.tsv output_for_R/shannon_vector.tsv

Why the renames?

Every alpha export writes to alpha-diversity.tsv by default, without the immediate mv, each subsequent export overwrites the previous one.

Export β-Diversity Distance Matrices¶

qiime tools export \
  --input-path core_metrics/bray_curtis_distance_matrix.qza \
  --output-path output_for_R

mv output_for_R/distance-matrix.tsv output_for_R/bray_curtis_distance_matrix.tsv

qiime tools export \
  --input-path core_metrics/jaccard_distance_matrix.qza \
  --output-path output_for_R

mv output_for_R/distance-matrix.tsv output_for_R/jaccard_distance_matrix.tsv

qiime tools export \
  --input-path core_metrics/unweighted_unifrac_distance_matrix.qza \
  --output-path output_for_R

mv output_for_R/distance-matrix.tsv output_for_R/unweighted_unifrac_distance_matrix.tsv

qiime tools export \
  --input-path core_metrics/weighted_unifrac_distance_matrix.qza \
  --output-path output_for_R

mv output_for_R/distance-matrix.tsv output_for_R/weighted_unifrac_distance_matrix.tsv

Export Taxonomy & Feature Table¶

Transpose the feature table and join with sequence and taxonomy data into a single tabulated visualization:

qiime feature-table transpose \
  --i-table table_nomitochloro.qza \
  --o-transposed-feature-table table_nomitochloro_transposed.qza

qiime metadata tabulate \
  --m-input-file table_nomitochloro_transposed.qza \
  --m-input-file seqs.qza \
  --m-input-file taxonomy_gg2.qza \
  --o-visualization tabulated_results.qzv

tabulated_results.qzv opens on view.qiime2.org and exports straight to TSV from the table view.

Export ANCOM-BC2 Results¶

ANCOMB-BC2 in R

There is also an ANCOM-BC2 package in R, it can be helpful if you have more complicated data/questions. The ANCOM-BC2 R package allows you to input a "linear mixed effects formula" so that you can account for variables that have a signial that are not related to your research question (ex. age). There are some really good ANCOM-BC2 R tutorials online.

qiime tools export \
  --input-path ancombc_sample_type.qza \
  --output-path output_for_R/ancombc/sample_type

qiime tools export \
  --input-path ancombc_facility.qza \
  --output-path output_for_R/ancombc/facility

Export Machine Learning Feature Importances¶

Sample type classifier:

qiime feature-table transpose \
  --i-table sample_classifier_results_sample_type/filtered_table_100_features.qza \
  --o-transposed-feature-table sample_classifier_results_sample_type/filtered_table_100_features_transposed.qza

qiime metadata tabulate \
  --m-input-file sample_classifier_results_sample_type/filtered_table_100_features_transposed.qza \
  --m-input-file sample_classifier_results_sample_type/feature_importance.qza \
  --o-visualization sample_classifier_results_sample_type/table_100_feature_importances.qzv

Facility classifier:

qiime feature-table transpose \
  --i-table sample_classifier_results_facility/filtered_table_100_features.qza \
  --o-transposed-feature-table sample_classifier_results_facility/filtered_table_100_features_transposed.qza

qiime metadata tabulate \
  --m-input-file sample_classifier_results_facility/filtered_table_100_features_transposed.qza \
  --m-input-file sample_classifier_results_facility/feature_importance.qza \
  --o-visualization sample_classifier_results_facility/table_100_feature_importances.qzv

Final Directory Layout¶

After completing the r_decomp_tutorial your working directory should look like this:

r_decomp_tutorial/ ├── 01_notes/ ├── 02_data/ ├── 03_metadata/ │ └── metadata.txt ★ ├── 04_code/ │ ├── alpha_div/ │ │ ├── evenness.tsv ★ │ │ ├── faith_pd.tsv ★ │ │ ├── observed_features.tsv ★ │ │ └── shannon.tsv ★ │ ├── beta_div/ │ │ ├── bray_curtis.txt ★ │ │ ├── jaccard.txt ★ │ │ ├── unweighted_unifrac.txt ★ │ │ └── weighted_unifrac.txt ★ │ ├── taxonomy/ │ │ └── tabulated_results.tsv ★ │ └── decomp_stats_figures.Rmd ★ └── 05_figures/ ├── add_split_faiths_facility.jpeg ├── add_split_shannon.jpeg ├── alpha_div_addOc.jpeg ├── beta_div_sample_type.jpeg ├── taxa_family_add.jpeg └── taxa_family_sample_type.jpeg