# nf-core/scrnaseq: Output

## Introduction

This document describes the output produced by the pipeline. Most of the plots are taken from the MultiQC report, which summarises results at the end of the pipeline.

## Pipeline overview

The pipeline is built using [Nextflow](https://www.nextflow.io/) and processes data using the following steps:

- [Pipeline information](#pipeline-information) - Report metrics generated during the workflow execution
- [nf-core/scrnaseq: Output](#nf-corescrnaseq-output)
- [Introduction](#introduction)
- [Pipeline overview](#pipeline-overview)
- [FastQC](#fastqc)
- [Kallisto \& Bustools Results](#kallisto--bustools-results)
- [STARsolo](#starsolo)
- [Simpleaf \& AlevinQC](#simpleaf--alevinqc)
- [Cellranger](#cellranger)
- [Cellranger ARC](#cellranger-arc)
- [Cellranger multi](#cellranger-multi)
- [Cellbender remove background filter](#cellbender-remove-background-filter)
- [Other output data](#other-output-data)
- [MultiQC](#multiqc)

## FastQC

See [FastQC](https://www.bioinformatics.babraham.ac.uk/projects/fastqc) for details about FastQC.

The pipeline analyzes the raw data and generates for each file a FastQC report. All report are collected in MultiQC.

**Output directory: `results/fastqc`**

- `.html`
  - Contains the FastQC report.
- `.zip`
  - Contains additional information, such as individual plots, and FastQC raw data.

:::note
The FastQC plots displayed in the MultiQC report shows the unprocessed reads. Depending on the protocol,
they may contain barcodes, UMIs and adapter sequences.
:::

## Kallisto & Bustools Results

See [Kallisto](https://pachterlab.github.io/kallisto/about) for details about Kallisto and [Bustools](https://bustools.github.io/) for more information on BusTools.

The pipeline can analyze data from single cell rnaseq experiments and generates a set of folders with respective outputs from various steps of the analysis. For a detailed summary what the pipeline does specifically, please follow the [excellent tutorial](https://www.kallistobus.tools/getting_started.html) that also describes specific steps for downstream analysis of the generated matrices.

**Output directory: `results/kallisto`**

- `raw_bus`
  - Contains the unconverted BUS formatted pseudo aligned data
- `sort_bus`
  - Contains the same BUS formatted data, sorted and corrected with the supplied barcode whitelist
- `kallisto_gene_map`
  - Contains the converted GTF gene map that is used by BUSTools for downstream analysis
- `bustools_counts`
  - Contains two subdirectories
    - `eqcount`: Containing the Transcript Compatibility Count (TCC) Matrix (`tcc.mtx`)
    - `genecount`: Containing the Gene Count Matrix (`gene.mtx`)
- `bustools_metrics` \* Contains the JSON metrics generated by BUStools

For details on how to load these into R and perform further downstream analysis, please refer to the [BusTools HowTo](https://github.com/BUStools/getting_started/blob/master/getting_started.ipynb).

**Output directory: `results/reference_genome`**

- `kallisto_index`
  - Contains the index of the supplied (genome/transcriptome) fasta file

## STARsolo

**Output directory: `results/star`**

- Files will be organized in one directory per sample
- Contains the mapped BAM files and output metrics created by STARsolo

**Output directory: `results/reference_genome`**

- `star_index`
  - Contains the index of the supplied genome fasta file

## Simpleaf & AlevinQC

This pipeline uses the simplified and flexible modules in [Simpleaf](https://simpleaf.readthedocs.io/en/latest/) for processing single-cell data with [Salmon](https://salmon.readthedocs.io/en/latest/) or [Piscem](https://github.com/COMBINE-lab/piscem) as the underlying mapper and [Alevin-fry](https://alevin-fry.readthedocs.io/en/latest/) as the quantification tool. For detailed examples of using the quantification results generated by Alevin-fry in downstream analyses, such as RNA-velocity, please refer to [Alevin-fry/simpleaf tutorials](https://combine-lab.github.io/alevin-fry-tutorials/#blog).

**Output directory: `results/simpleaf`**

- `${meta.id}/simpleaf_quant/af_quant/alevin`
  - Contains the quantification results -- the count matrix -- generated by simpleaf for each sample with.
- `${meta.id}/simpleaf_quant/af_quant`
  - Contains the logs and other intermediate results generated during the quantification stage.
- `${meta.id}/simpleaf_quant/af_map`
  - Contains the logs and other intermediate results generated during the mapping stage.
- `${meta.id}/simpleaf_qc_report_${meta.id}.html`
  - The QC report generated by AlevinQC for each sample.
- `simpleaf_index`
  - Contains the indexed reference transcriptome generated by Simpleaf. This folder will be generated if the index was generated by the pipeline and the `save_reference` parameter is set to `true`. Notice that, because the simpleaf index generated from a specific reference is fixed, this folder can be passed to the pipeline via the `simpleaf_index` parameter, or save it in `igenome.config` under `genomes[ params.genome ][ "simpleaf" ]`, to avoid re-indexing the reference.

## Cellranger

Cell Ranger is a set of analysis scripts that processes 10x Chromium single cell data to align reads, generate feature-barcode matrices, perform clustering and other secondary analysis. See [Cellranger](https://support.10xgenomics.com/single-cell-gene-expression/software/pipelines/latest/what-is-cell-ranger) for more information on Cellranger.

**Output directory: `results/cellranger`**

- Contains the mapped BAM files, filtered and unfiltered HDF5 matrices and output metrics created by Cellranger

## Cellranger ARC

Cell Ranger ARC is a set of analysis pipelines that process Chromium Single Cell Multiome ATAC + Gene Expression sequencing data to generate a variety of analyses pertaining to gene expression (GEX), chromatin accessibility, and their linkage. Furthermore, since the ATAC and GEX measurements are on the very same cell, we are able to perform analyses that link chromatin accessibility and GEX. See [Cellranger ARC](https://support.10xgenomics.com/single-cell-multiome-atac-gex/software/pipelines/latest/what-is-cell-ranger-arc) for more information on Cellranger.

**Output directory: `results/cellrangerarc`**

- Contains the mapped BAM files, filtered and unfiltered HDF5 matrices and output metrics created by Cellranger ARC

## Cellranger multi

Cell Ranger Multi is the 10x analysis pipeline for *multi*omics and *multi*plexed experiments. See [Cell Ranger Multi]()
for the corresponding documentation.

**Output directory: `results/cellrangermulti`**

- Overall same output structure as cellranger. In case of multiplexed samples there will be one ouput folder for
  each demultiplexed sample, and one containing all (non-demultiplexed) cells.

## Cellbender remove background filter

The pipeline also possess a subworkflow imported from scdownstream to perform filter empty drops using [cellbender](https://github.com/broadinstitute/CellBender) remove background function. The process is simple, it takes a raw/unfiltered matrix file, and performs the filltering on it, generating another matrix file.

> Users can turn it of with `--skip_cellbender`.

**Output directory: `results/${params.aligner}/${meta.id}/cellbender_removebackground`**

- Contains the cellbender filtered matrices results generated by the remove background functionality.

## Other output data

**Output directory: `results/reference_genome`**

- `barcodes`
  - Contains the utilized cell barcode whitelists (if applicable)
- `extract_transcriptome`
  - When supplied with a `--fasta` genome fasta, this contains the extracted transcriptome
  - The GTF file supplied with `--gtf` is used to extract the transcriptome positions appropriately

**Output directory: `results/${params.aligner}/mtx_conversions`**

- `*_matrix.h5ad`
  - `.mtx` files converted to [AnnData](https://anndata.readthedocs.io/en/latest/) in `.h5ad` format, using [scanpy package](https://scanpy.readthedocs.io/en/stable/).
  - One per sample and a single one with all samples concatenated together `combined_matrix.h5ad`
- `*_matrix.rds`
  - `.mtx` files converted to R native data format, rds, using the [Seurat package](https://github.com/satijalab/seurat)
  - One per sample

Because the pipeline has both the data directly from the aligners, and from the cellbender empty-drops filtering module, the conversion modules were
modified to understand the difference between raw/filtered from the aligners itself and filtered from the empty-drops module.
So, to try to avoid confusion by the user, we added "suffixes" to the generated converted files so that we have provenance from what input it came from.

So, the conversion modules generate data with the following syntax: **`*_{raw,filtered,cellbender_filter}_matrix.{h5ad,rds}`**. With the following meanings:

| suffix            | meaning                                                                                                                                    |
| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
| raw               | Conversion of the raw/unprocessed matrix generated by the tool. It is also used for tools that generate only one matrix, such as simpleaf. |
| filtered          | Conversion of the filtered/processed matrix generated by the tool                                                                          |
| cellbender_filter | Conversion of the matrix that was generated by the cellbender remove background filtering module                                           |

> Some aligners, like `simpleaf` do not produce both raw&filtered matrices. When aligners give only one output, they are treated with the `raw` or `filtered` suffix accordingly. For `simpleaf`, by default only `raw` results are generated, followed by cellbender for filtering empty-drops to generate `cellbender_filter` results.
> Some aligners may have an option to give both raw&filtered and only one, like `kallisto`. Be aware when using the tools.

## MultiQC

<details markdown="1">
<summary>Output files</summary>

- `multiqc/`
  - `multiqc_report.html`: a standalone HTML file that can be viewed in your web browser.
  - `multiqc_data/`: directory containing parsed statistics from the different tools used in the pipeline.
  - `multiqc_plots/`: directory containing static images from the report in various formats.

</details>

[MultiQC](http://multiqc.info) is a visualization tool that generates a single HTML report summarising all samples in your project. Most of the pipeline QC results are visualised in the report and further statistics are available in the report data directory.

Results generated by MultiQC collate pipeline QC from supported tools e.g. FastQC. The pipeline has special steps which also allow the software versions to be reported in the MultiQC output for future traceability. For more information about how to use MultiQC reports, see <http://multiqc.info>.

### Pipeline information

<details markdown="1">
<summary>Output files</summary>

- `pipeline_info/`
  - Reports generated by Nextflow: `execution_report.html`, `execution_timeline.html`, `execution_trace.txt` and `pipeline_dag.dot`/`pipeline_dag.svg`.
  - Reports generated by the pipeline: `pipeline_report.html`, `pipeline_report.txt` and `software_versions.yml`. The `pipeline_report*` files will only be present if the `--email` / `--email_on_fail` parameter's are used when running the pipeline.
  - Reformatted samplesheet files used as input to the pipeline: `samplesheet.valid.csv`.
  - Parameters used by the pipeline run: `params.json`.

</details>

[Nextflow](https://www.nextflow.io/docs/latest/tracing.html) provides excellent functionality for generating various reports relevant to the running and execution of the pipeline. This will allow you to troubleshoot errors with the running of the pipeline, and also provide you with other information such as launch commands, run times and resource usage.
