Include metagenomics mini-course

docs/nf4_science/metagenomics/00_orientation.md

@@ -0,0 +1,100 @@
+# Orientation
+
+The training environment contains all the software, code and data necessary to work through this training course, so you don't need to install anything yourself.
+However, you do need a (free) account to log in, and you should take a few minutes to familiarize yourself with the interface.
+
+If you have not yet done so, please the [Environment Setup](../../envsetup/) mini-course before going any further.
+
+## Materials provided
+
+For the purpose of the course, we'll be working in the `nf4-science/metagenomics/` directory, where you will find all the code files, test data and accessory files you will need.
+To move into it, run the following command:
+
+```bash
+cd nf4-science/metagenomics/
+```
+
+Before we go any further, we are going to download some files that are too large to be permanently stored within the GitHub repository.
+Specifically, this is a set of files that constitute the database required by Kraken2 and Bracken.
+
+Run the following commands in that exact order and wait until all of them are finished:
+
+```bash
+mkdir -p data/viral_db && cd "$_"
+wget --no-check-certificate --no-proxy 'https://genome-idx.s3.amazonaws.com/kraken/k2_viral_20241228.tar.gz'
+tar -xvzf k2_viral_20241228.tar.gz
+rm -r k2_viral_20241228.tar.gz
+cd -
+```
+
+Briefly, this creates a directory called `viral_db` under `data/` and moves into it.
+Then, it downloads an archive file with `wget`, unpacks its contents with `tar`, and deletes the original archive file.
+Finally, it moves you back up to the original `nf4-science/metagenomics/` directory.
+
+Now, let's take a look of the files contained in this directory with the `tree` command:
+
+```bash
+tree . -L 3
+```
+
+Here you should see the following directory structure:
+
+```console title="Directory contents"
+.
+├── bin
+│   └── report.Rmd
+├── data
+│   ├── samples
+│   │   ├── ERR2143768
+│   │   │   ├── ERR2143768_1.fastq
+│   │   │   └── ERR2143768_2.fastq
+│   │   ├── ERR2143769
+│   │   │   ├── ERR2143769_1.fastq
+│   │   │   └── ERR2143769_2.fastq
+│   │   ├── ERR2143770
+│   │   │   ├── ERR2143770_1.fastq
+│   │   │   └── ERR2143770_2.fastq
+│   │   └── ERR2143774
+│   │       ├── ERR2143774_1.fastq
+│   │       └── ERR2143774_2.fastq
+│   ├── samplesheet.csv
+│   └── yeast
+│       ├── yeast.1.bt2
+│       ├── yeast.2.bt2
+│       ├── yeast.3.bt2
+│       ├── yeast.4.bt2
+│       ├── yeast.rev.1.bt2
+│       └── yeast.rev.2.bt2
+├── main.nf
+├── modules
+│   ├── bowtie2.nf
+│   ├── bracken.nf
+│   ├── kReport2Krona.nf
+│   ├── knit_phyloseq.nf
+│   ├── kraken2.nf
+│   ├── kraken_biom.nf
+│   └── ktImportText.nf
+├── nextflow.config
+└── workflow.nf
+```
+
+**This a summarized description of the files and directories found:**
+
+- **`main.nf`** is the file we are going to invoke with the world-famous `nextflow run` command.
+- **`workflow.nf`** is where all the magic happens, it stores the order of execution of tasks and how data should be handled.
+- **`nextflow.config`**: you should know what this file does right? JK, with it we can manage different directives for workflow execution.
+- **`modules`** is a really important folder since here we find dedicated files per each process of the pipeline.
+- **`bin`** is the directory where we store customized scripts that can be run within a given process.
+- **`data`** contains input data and related resources:
+  - An indexed genome within the `yeast` folder representing the host genome to which we want to map the reads for contamination removal.
+  - _viral_db_ is a directory that contains Kraken2 database necessary for both taxonomic annotation and species abundance re-estimation.
+  - _samplesheet.csv_ lists the IDs and paths of the example data files, for processing in batches.
+  - _samples_ directory is where the raw sequences are stored.
+    The names correspond to accession numbers that you can search on the [Sequence Read Archive](https://www.ncbi.nlm.nih.gov/sra)
+
+!!!note
+
+    Don't panic if this feels like a lot.
+    This is just a glimpse of the material, and we are going to dig into each necessary file for the analysis in due time.
+
+Now, to begin the course, click on the arrow in the bottom right corner of this page.

docs/nf4_science/metagenomics/01_pipeline.md

@@ -0,0 +1,63 @@
+# Part 1: Method overview
+
+In the field of metagenomics data analysis, there is an endless universe of pipelines or methodologies you can follow to explore and characterize your samples.
+We recommend this comprehensive [review](https://www.sciencedirect.com/science/article/pii/S2001037021004931) for you to explore the different existing approaches.
+For this course, we propose to wrap with Nextflow the protocol published by [Jennifer Lu et al. (2022)](https://www.nature.com/articles/s41596-022-00738-y).
+
+The example dataset we will use to demonstrate the analysis consists of only paired-end reads recovered from an oligotrophic, phosphorus-deficient pond in Cuatro Ciénegas, Mexico ([Okie et al.,2020](https://elifesciences.org/articles/49816)) in FASTQ format.
+The BioProject accession number is [PRJEB22811](https://www.ncbi.nlm.nih.gov/bioproject/PRJEB22811).
+
+---
+
+## 1. Workflow design
+
+Our goal is to develop a workflow that takes **FASTQ** files from one or multiple samples as input and applies the following processing steps: host removal, taxonomic classification, Bayesian re-estimation of species abundance, and generation of plots and metrics.
+
+<div markdown class="metagenomics">
+
+![Metagenomics](../../assets/img/workflow_kraken.png)
+
+</div>
+
+To perform these steps, we will use the following tools:
+
+1. **Host removal** with [**Bowtie2**](https://bowtie-bio.sourceforge.net/bowtie2/manual.shtml) by aligning the reads against an indexed reference genome.
+   Here, we are using the indexed genome of yeast, but you can use any organism you are interested in by building [your own index](https://www.metagenomics.wiki/tools/bowtie2/index) or downloading a [precomputed one](https://benlangmead.github.io/aws-indexes/bowtie).
+2. **Taxonomic classification** with [**Kraken2**](https://ccb.jhu.edu/software/kraken2/).
+   This tools relies on a indexed database that can be [downloaded](https://benlangmead.github.io/aws-indexes/k2).
+   Alternatively, you can build your customized version following [these instructions](https://avilpage.com/2024/07/mastering-kraken2-build-custom-db.html).
+   Here, we will use the Viral database, therefore this methodology is labeled as "viral metagenomics".
+   However, you can annotate bacteria, archaea and more simply by switching to another database.
+3. **Bayesian re-estimation of species abundance** with [**Bracken**](https://ccb.jhu.edu/software/bracken/index.shtml?t=manual).
+   This software is designed to compute species abundance using Kraken classification results as described in the reference paper.
+   It also uses some files contained in the dabatase folders such as the kmer distribution files.
+   This is a fairly complex analysis, but you don't need to know the details in order to follow this tutorial; you can learn about how the method works afterwards.
+4. **Plot generation** with [**Krona**](https://bmcbioinformatics.biomedcentral.com/articles/10.1186/1471-2105-12-385) from the Bracken output.
+   This will allow us to visualize interactively the relative abundance of each annotated species.
+5. (Multi-sample) **Concatenation with kraken-biom.**
+   If multiple samples are provided, the Bracken reports will be concatenated and converted into a [Biological Observation Matrix (BIOM)](https://biom-format.org/) file.
+6. (Multi-sample) **Generation of final report with Phyloseq**
+   The BIOM file will be converted to a [Phyloseq](https://joey711.github.io/phyloseq/index.html) object, and this object will be further processed to generate absolute plots, estimate both α and β-diversity and perform a network analysis.
+   This information will be presented in a final `report.html`.
+   To learn more about the code used to generate the plots and metrics, check out this Phyloseq [tutorial](https://vaulot.github.io/tutorials/Phyloseq_tutorial.html).
+
+!!!tip
+
+    If you feel a bit overwhelmed by the theoretical background of the methodology, we strongly encourage you to check this [Carpentries](https://carpentries-lab.github.io/metagenomics-analysis/) lesson first, where the concepts are explained step by step using interesting examples.
+
+---
+
+## 2. [TODO: add optional manual testing of the various tools via containers]
+
+---
+
+### Takeaway
+
+You understand the underlying method and the overall design of the workflow.
+
+**[TODO: You have tested all the individual commands interactively in the relevant containers.]
+**
+
+### What's next?
+
+Learn how to wrap those same commands into a multi-step workflow that uses containers to execute the work.