Merge pull request #107 from qiyunzhu/upgrade

Updated Qiita documentation

README.md

@@ -30,7 +30,7 @@ Woltka ships with a **QIIME 2 plugin**. [See here for instructions](woltka/q2).
   - [Working with WoL](doc/wol.md)
   - [OGU analysis](doc/ogu.md)
 - For users of
-  - [QIIME 2](woltka/q2), [Qiita](doc/app.md#qiita), [SHOGUN](doc/wol.md#sequence-alignment), [GTDB](doc/gtdb.md), [MetaCyc](doc/metacyc.md), [KEGG](doc/kegg.md)
+  - [QIIME 2](woltka/q2), [Qiita](doc/qiita.md), [SHOGUN](doc/wol.md#sequence-alignment), [GTDB](doc/gtdb.md), [MetaCyc](doc/metacyc.md), [KEGG](doc/kegg.md)
 - References
   - [Command-line interface](doc/cli.md)
   - [Computational efficiency](doc/perform.md)

doc/ogu.md

@@ -33,7 +33,7 @@ If necessary, you may convert a BIOM table into tab-delimited file:
 biom convert --to-tsv -i table.biom -o table.tsv
 ```
 
-Note: Both SHOGUN and WoL are available at the [**Qiita**](https://qiita.ucsd.edu/) server. If you are a Qiita user, the alignment file can be automatically generated and downloaded from the Qiita interface. See [details](app.md#qiita).
+Note: [**Qiita**](https://qiita.ucsd.edu/) implements the WoL database and a Woltka workflow, which performs sequence alignment using the same approach as SHOGUN does. If you are a Qiita user, the alignment file can be automatically generated and downloaded from the Qiita interface. See [details](qiita.md).
 
 ## OGU analysis using QIIME 2
 

doc/qiita.md

@@ -0,0 +1,52 @@
+# Working with Qiita
+
+[**Qiita**](https://qiita.ucsd.edu/) is a web platform for hosting and analyzing microbiome datasets. Woltka has been implemented in Qiita as part of the standard operating procedure for shotgun metagenomic data analysis. Please find below the instructions for using Woltka and retrieving Woltka results.
+
+## Existing results
+
+We have run Woltka using the [**WoL**](wol.md) and **Rep200** (NCBI RefSeq v200, representative & reference genomes) database on all shotgun metagenomic datasets hosted in Qiita. The output files (white triangles) are ready for download, as shown below:
+
+![Qiita1](img/qiita1.png)
+
+There are more than one Woltka runs. To determine which database was used in each analysis, click the "**Woltka v0.1.1**" green circle, check the "**Database**" parameter.
+
+The output files of each run are:
+
+  - "**Alignment Profile**". The alignment file generated by Bowtie2. This is also the input file for Woltka, with which one can run custom analyses.
+  - "**Per genome predictions**": Genome-level profile, i.e., an "OGU table".
+  - "**Per gene predictions**: Gene-level profile, generated using Woltka's ordinal matching function.
+  - "**Taxonomic predictions**: Taxonomic profiles at the levels of species, genus and phylum.
+
+
+## New analysis
+
+You may analyze you own shotgun metagenomic data
+
+1. Start from host-filtered, adapter-trimmed per sample FASTQ files. Click "**Process**".
+2. In "Choose command:", select "**Woltka v0.1.1**" (or the latest version).
+3. In "Parameter set:", select "**wol**" or "**rep200**", which are the two aforementioned databases.
+4. Click "Add Command" to kick-start the Woltka workflow.
+5. When the job is completed, you will see the aforementioned output files.
+
+![Qiita2](img/qiita2.png)
+
+
+## Downstream analysis
+
+While multiple downstream analyses can be performed on the Woltka output files, we hereby demonstrate an analysis of the **OGU table** using Qiita's built-in functions.
+
+1. Start from the "per-genome prediction" file, click "**Add to analysis**". In a few moments, it will display "Added".
+2. In the navigation bar, select "**Analysis**" -> "**Create From Selected Samples**". You will see the OGU table in the list.
+2. Click the green "Create Analysis" button. Enter analysis name and description.
+ - You may add multiple OGU tables (e.g., those from multiple sequencing runs), and check the "**Merge samples with the same name**" box.
+
+![Qiita3](img/qiita3.png)
+
+3. After a short while, you will see a single triangle "**dflt_name (BIOM)**" in the processing network interface. This is the OGU table. Select it. The summary of sample and feature information will be displayed in the interface below.
+4. Click "**Process**". There is a big list of available commands in the "Choose command:" dropdown menu.
+5. Select "**Core diversity metrics (phylogenetic and non-phylogenetic)**". This is an all-in-one QIIME 2 pipeline.
+6. In "Phylogenetic tree", select "**/projects/wol/release/databases/qiime2/phylogeny.qza**". This is the WoL tree. Also specify a reasonable **sampling depth** based on the summary of feature counts (e.g., 100,000).
+7. Click "Add command", then click "Run". You job will be queued.
+8. Once the job is completed, you will see a number of output files. Enjoy browsing and interpreting the results!
+
+![Qiita4](img/qiita4.png)

doc/wol.md

@@ -6,7 +6,7 @@ Phase I of the project was already completed ([Zhu et al., 2019](https://www.nat
 
 The project is detailed at our website: https://biocore.github.io/wol/, including data and [metadata](https://biocore.github.io/wol/data/genomes/metadata.tsv.bz2), code, protocols, a gallery and a visualizer. Large data files are hosted at our Globus endpoint: [WebOfLife](https://app.globus.org/file-manager/collections/31acbeb8-c62f-11ea-bef9-0e716405a293) (see [instruction](https://biocore.github.io/wol/download#download-via-globus)).
 
-This public resource provides everything one needs to start microbiome data analysis using WoL, including raw sequence data, metadata, tree and taxonomy, and pre-built databases that are ready to be plugged into your bioinformatics protocols. Currently, we provide databases for QIIME 2, SHOGUN, Bowtie2, Centrifuge, Kraken2 / Bracken, BLASTn and BLASTp, Minimap2, and DIAMOND. Even if your favorate tool is not on this list, we provide detailed tutorials on how to [build your own database](https://biocore.github.io/wol/protocols/genome_database) and many other related [protocols](https://biocore.github.io/wol/protocols/). Meanwhile, WoL is also hosted at our web-based microbiome study platform: **Qiita** (https://qiita.ucsd.edu/) (see [details](app.md#qiita)).
+This public resource provides everything one needs to start microbiome data analysis using WoL, including raw sequence data, metadata, tree and taxonomy, and pre-built databases that are ready to be plugged into your bioinformatics protocols. Currently, we provide databases for QIIME 2, SHOGUN, Bowtie2, Centrifuge, Kraken2 / Bracken, BLASTn and BLASTp, Minimap2, and DIAMOND. Even if your favorate tool is not on this list, we provide detailed tutorials on how to [build your own database](https://biocore.github.io/wol/protocols/genome_database) and many other related [protocols](https://biocore.github.io/wol/protocols/). Meanwhile, WoL is also hosted at our web-based microbiome study platform: **Qiita** (https://qiita.ucsd.edu/) (see [details](qiita.md)).
 
 The following tutorial assume that you have downloaded the entire WoL directory from our Globus server. The paths mentioned below are relative to this directory.
 

woltka/q2/README.md

@@ -116,15 +116,15 @@ q2-woltka defines five new semantic types:
 - `GeneCoordinates`: [Gene coordinate mapping format](../../doc/ordinal.md#gene-coordinates).
 
 
-## Output profile
+## Downstream analyses
 
 The resulting file (e.g., `table.qza`) is a **feature table**. Its semantic type is `FeatureTable[Frequency]`. This table can be directly analyzed using downstream QIIME plugins. For example:
 
 ```bash
 qiime diversity core-metrics-phylogenetic \
   --i-phylogeny tree.qza \
   --i-table table.qza \
-  --p-sampling-depth 1000 \
+  --p-sampling-depth 10000 \
   --m-metadata-file metadata.tsv \
   --output-dir .
 ```