From 7fcc9e446cf8d913d4cff33ad484304f3e4aeb5c Mon Sep 17 00:00:00 2001 From: Phil Ewels Date: Wed, 31 May 2017 15:12:36 +0200 Subject: [PATCH] Wrote documentation. Improved bismark output organisation. Added --saveAlignedIntermediates and --saveTrimmed (don't save trimmed FastQ and undeduplicated BAM by default) Made output saved in subdirectories --- README.md | 167 ++++----------------------------- bismark.nf | 45 +++++++-- docs/images/NGI_logo.png | Bin 0 -> 25121 bytes docs/installation.md | 174 ++++++++++++++++++++++++++++++++++ docs/output.md | 150 +++++++++++++++++++++++++++++ docs/usage.md | 198 +++++++++++++++++++++++++++++++++++++++ 6 files changed, 574 insertions(+), 160 deletions(-) create mode 100644 docs/images/NGI_logo.png create mode 100644 docs/installation.md create mode 100644 docs/output.md create mode 100644 docs/usage.md diff --git a/README.md b/README.md index 49fa7fb..0afa267 100644 --- a/README.md +++ b/README.md @@ -1,164 +1,31 @@ # ![NGI-MethylSeq](docs/images/NGI-MethylSeq_logo.png) -> # UNDER DEVELOPMENT -> This pipeline is currently under active development and has very little in the way of testing. You may well have problems running it. Any help debugging is very welcome! Please fork, make changes and submit a pull request. +[![Build Status](https://travis-ci.org/SciLifeLab/NGI-MethylSeq.svg?branch=master)](https://travis-ci.org/SciLifeLab/NGI-MethylSeq) +[![Nextflow](https://img.shields.io/badge/nextflow-%E2%89%A50.22.2-brightgreen.svg)](https://www.nextflow.io/) -**NGI-MethylSeq** is a bioinformatics best-practice analysis pipeline used for Methylation (BS-Seq) data analysis at the [National Genomics Infastructure](https://ngisweden.scilifelab.se/) at [SciLifeLab Stockholm](https://www.scilifelab.se/platforms/ngi/), Sweden. +### Introduction + +NGI-MethylSeq is a bioinformatics best-practice analysis pipeline used for Methylation (BS-Seq) data analysis at the [National Genomics Infastructure](https://ngisweden.scilifelab.se/) at [SciLifeLab Stockholm](https://www.scilifelab.se/platforms/ngi/), Sweden. The pipeline uses [Nextflow](https://www.nextflow.io), a bioinformatics workflow tool. It pre-processes raw data from FastQ inputs, aligns the reads and performs extensive quality-control on the results. This pipeline is primarily used with a SLURM cluster on the Swedish [UPPMAX systems](https://www.uppmax.uu.se). However, the pipeline should be able to run on any system that Nextflow supports. We have done some limited testing using Docker and AWS, and the pipeline comes with some configuration for these systems. See the [installation docs](docs/installation.md) for more information. -## Pipeline Results -See the [pipeline documentation](docs/README.md) for explanations of -the results files. - -## Installation -### NextFlow installation -See https://github.com/SciLifeLab/NGI-NextflowDocs for instructions on how to install and configure -Nextflow. - -### Pipeline installation -This pipeline itself needs no installation - NextFlow will automatically fetch it from GitHub when run if -`SciLifeLab/NGI-MethylSeq` is specified as the pipeline name. - -If you prefer, you can download the files yourself from GitHub and run them directly: -``` -git clone https://github.com/SciLifeLab/NGI-MethylSeq.git -nextflow NGI-MethylSeq/main.nf -``` - -## Configuration -By default, the pipeline is configured to run on the Swedish UPPMAX cluster (milou / irma). - -You will need to specify your UPPMAX project ID when running a pipeline. To do this, use -the command line flag `--project `. - -To avoid having to specify this every time you run Nextflow, you can add it to your -personal Nextflow config file instead. Add this line to `~/.nextflow/config`: - -```groovy -params.project = 'project_ID' -``` - -The pipeline will exit with an error message if you try to run it pipeline with the default -UPPMAX config profile and don't set project. - - -### Running on other clusters -It is entirely possible to run this pipeline on other clusters, though you will need to set up -your own config file so that the script knows where to find your reference files and how your -cluster works. - -Copy the contents of [`conf/uppmax.config`](conf/uppmax.config) to your own config file somewhere -and then reference it with `-c` when running the pipeline. - -If you think that there are other people using the pipeline who would benefit from your configuration -(eg. other common cluster setups), please let us know. It should be easy to create a new config file -in `conf` and reference this as a named profile in [`nextflow.config`](nextflow.config). Then these -configuration options can be used by specifying `-profile ` when running the pipeline. - - -## Running the pipeline -The typical command for running the pipeline is as follows: -``` -nextflow SciLifeLab/NGI-MethylSeq --reads '*_R{1,2}.fastq.gz' --genome GRCh37 -``` - -Note that the pipeline will create files in your working directory: -```bash -work # Directory containing the nextflow working files -results # Finished results (configurable, see below) -.nextflow_log # Log file from Nextflow -# Other nextflow hidden files, eg. history of pipeline runs and old logs. -``` - -### `--reads` -Location of the input FastQ files: -``` - --reads 'path/to/data/sample_*_{1,2}.fastq' -``` - -**NB: Must be enclosed in quotes!** - -Note that the `{1,2}` parentheses are required to specify paired end data. Running `--reads '*.fastq'` will treat -all files as single end. Also, note that the file path should be in quotation marks to prevent shell glob expansion. - -If left unspecified, the pipeline will assume that the data is in a directory called `data` in the working directory. - -### `--genome` -The reference genome to use of the analysis, needs to be one of the genome specified in the config file. - -See [`conf/uppmax.config`](conf/uppmax.config) for a list of the supported reference genomes -and their keys. Common genomes that are supported are: - -* Human - * `--genome GRCh37` -* Mouse - * `--genome GRCm38` -* Drosophila - * `--genome BDGP6` -* _S. cerevisiae_ - * `--genome 'R64-1-1'` - -> There are numerous others - check the config file for more. - -If you usually want to work with a single species, you can set a default in your user config file. -For example, add this line to `~/.nextflow/config`: -``` -params.genome = 'GRCh37' -``` - -### Trimming Parameters -The pipeline accepts a number of parameters to change how the trimming is done, according to your data type. -The following settings are set for these command line flags: - -| Parameter | 5' R1 Trim | 5' R2 Trim | 3' R1 Trim | 3' R2 Trim | -|-----------------|------------|------------|------------|------------| -| `--pbat` | 6 | 9 | 6 | 9 | -| `--single_cell` | 6 | 6 | 6 | 6 | -| `--epignome` | 8 | 8 | 8 | 8 | -| `--accel` | 10 | 15 | 10 | 10 | -| `--zymo` | 10 | 15 | 10 | 10 | -| `--cegx` | 6 | 6 | 2 | 2 | - -You can specify custom trimming parameters as follows: - -* `--clip_r1 ` -* `--clip_r2 ` -* `--three_prime_clip_r1 ` -* `--three_prime_clip_r2 ` - -Finally, specifying `--rrbs` will pass on the `--rrbs` parameter to TrimGalore! - -### Bismark Parameters -Using the `--pbat` parameter will affect the trimming (see above) and also set the `--pbat` flag when -aligning with Bismark. - -Using the `--single_cell` or `--zymo` parameters will set the `--non_directional` flag when aligning with Bismark. -This can also be set with `--non_directional` (doesn't affect trimming). - -Use the `--unmapped` flag to set the `--unmapped` flag with Bismark align and save the unmapped reads. +### Documentation +The NGI-MethylSeq pipeline comes with documentation about the pipeline, found in the `docs/` directory: -### Deduplication -By default, the pipeline includes a deduplication step after alignment. This is skipped if `--rrbs` or `--nodedup` are specified on the command line. +1. [Installation and configuration](docs/installation.md) +2. [Running the pipeline](docs/usage.md) +3. [Output and how to interpret the results](docs/output.md) -### `--bismark_index` -If you prefer, you can specify the full path to your reference genome when you run the pipeline: -``` ---bismark_index [path to Bismark index] -``` +If you're interested in running the pipeline in the cloud, please read the docs about using our pipeline with Amazon Web Services on the [NGI-RNAseq pipeline](https://github.com/SciLifeLab/NGI-RNAseq/blob/master/docs/amazon_web_services.md) (the instructions should work with this pipeline as well). -### `--outdir` -The output directory where the results will be saved. +### Credits +These scripts were written for use at the [National Genomics Infrastructure](https://portal.scilifelab.se/genomics/) at [SciLifeLab](http://www.scilifelab.se/) in Stockholm, Sweden. Written by Phil Ewels (@ewels) and Rickard Hammarén (@Hammarn). -### `-c` -Specify the path to a specific config file (this is a core NextFlow command). Useful if using different UPPMAX -projects or different sets of reference genomes. +--- -## Credits -These scripts were written for use at the [National Genomics Infrastructure](https://portal.scilifelab.se/genomics/) -at [SciLifeLab](http://www.scilifelab.se/) in Stockholm, Sweden. -Written by Phil Ewels (@ewels) and Rickard Hammarén (@Hammarn). +[![SciLifeLab](https://raw.githubusercontent.com/SciLifeLab/NGI-MethylSeq/master/docs/images/SciLifeLab_logo.png)](http://www.scilifelab.se/) +[![National Genomics Infrastructure](https://raw.githubusercontent.com/SciLifeLab/NGI-MethylSeq/master/docs/images/NGI_logo.png)](https://ngisweden.scilifelab.se/) -

+--- diff --git a/bismark.nf b/bismark.nf index 460df4c..28154f3 100644 --- a/bismark.nf +++ b/bismark.nf @@ -27,6 +27,8 @@ params.email = false params.genome = false params.bismark_index = params.genome ? params.genomes[ params.genome ].bismark ?: false : false params.saveReference = false +params.saveTrimmed = false +params.saveAlignedIntermediates = false params.reads = "data/*_R{1,2}.fastq.gz" params.outdir = './results' params.multiqc_config = "$baseDir/conf/multiqc_config.yaml" @@ -39,7 +41,7 @@ params.relaxMismatches = false params.numMismatches = 0.6 // 0.6 will allow a penalty of bp * -0.6 // For 100bp reads, this is -60. Mismatches cost -6, gap opening -5 and gap extension -2 -// Sp -60 would allow 10 mismatches or ~ 8 x 1-2bp indels +// So -60 would allow 10 mismatches or ~ 8 x 1-2bp indels // Bismark default is 0.2 (L,0,-0.2), Bowtie2 default is 0.6 (L,0,-0.6) // Validate inputs @@ -114,7 +116,9 @@ summary['Working dir'] = workflow.workDir summary['Output dir'] = params.outdir summary['Script dir'] = workflow.projectDir summary['Deduplication'] = params.nodedup ? 'No' : 'Yes' +summary['Save Trimmed'] = params.saveTrimmed summary['Save Unmapped'] = params.unmapped ? 'Yes' : 'No' +summary['Save Intermeds'] = params.saveAlignedIntermediates summary['Directional Mode'] = params.non_directional ? 'No' : 'Yes' summary['All C Contexts'] = params.comprehensive ? 'Yes' : 'No' if(params.rrbs) summary['RRBS Mode'] = 'On' @@ -144,7 +148,8 @@ if( workflow.profile == 'standard' && !params.project ) exit 1, "No UPPMAX proje */ process fastqc { tag "$name" - publishDir "${params.outdir}/fastqc", mode: 'copy' + publishDir "${params.outdir}/fastqc", mode: 'copy', + saveAs: {filename -> filename.indexOf(".zip") > 0 ? "zips/$filename" : "$filename"} input: set val(name), file(reads) from read_files_fastqc @@ -167,14 +172,20 @@ if(params.notrim){ } else { process trim_galore { tag "$name" - publishDir "${params.outdir}/trim_galore", mode: 'copy' + publishDir "${params.outdir}/trim_galore", mode: 'copy', + saveAs: {filename -> + if (filename.indexOf("_fastqc") > 0) "FastQC/$filename" + else if (filename.indexOf("trimming_report.txt") > 0) "logs/$filename" + else params.saveTrimmed ? filename : null + } input: set val(name), file(reads) from read_files_trimming output: set val(name), file('*fq.gz') into trimmed_reads - file '*trimming_report.txt' into trimgalore_results + file "*trimming_report.txt" into trimgalore_results + file "*_fastqc.{zip,html}" into trimgalore_fastqc_reports script: c_r1 = params.clip_r1 > 0 ? "--clip_r1 ${params.clip_r1}" : '' @@ -182,13 +193,14 @@ if(params.notrim){ tpc_r1 = params.three_prime_clip_r1 > 0 ? "--three_prime_clip_r1 ${params.three_prime_clip_r1}" : '' tpc_r2 = params.three_prime_clip_r2 > 0 ? "--three_prime_clip_r2 ${params.three_prime_clip_r2}" : '' rrbs = params.rrbs ? "--rrbs" : '' + non_directional = params.rrbs && params.non_directional ? "--non_directional" : '' if (params.singleEnd) { """ - trim_galore --gzip $rrbs $c_r1 $tpc_r1 $reads + trim_galore --fastqc --gzip $rrbs $c_r1 $tpc_r1 $reads """ } else { """ - trim_galore --paired --gzip $rrbs $c_r1 $c_r2 $tpc_r1 $tpc_r2 $reads + trim_galore --paired --fastqc --gzip $rrbs $c_r1 $c_r2 $tpc_r1 $tpc_r2 $reads """ } } @@ -199,7 +211,12 @@ if(params.notrim){ */ process bismark_align { tag "$name" - publishDir "${params.outdir}/bismark_alignments", mode: 'copy' + publishDir "${params.outdir}/bismark_alignments", mode: 'copy', + saveAs: {filename -> + if (filename.indexOf(".fq.gz") > 0) "unmapped/$filename" + else if (filename.indexOf(".bam") == -1) "logs/$filename" + else params.saveAlignedIntermediates || params.nodedup || params.rrbs ? filename : null + } input: file index from bismark_index @@ -240,7 +257,8 @@ if (params.nodedup || params.rrbs) { } else { process bismark_deduplicate { tag "${bam.baseName}" - publishDir "${params.outdir}/bismark_deduplicated", mode: 'copy' + publishDir "${params.outdir}/bismark_deduplicated", mode: 'copy', + saveAs: {filename -> filename.indexOf(".bam") == -1 ? "logs/$filename" : "$filename"} input: file bam @@ -267,7 +285,14 @@ if (params.nodedup || params.rrbs) { */ process bismark_methXtract { tag "${bam.baseName}" - publishDir "${params.outdir}/bismark_methylation_calls", mode: 'copy' + publishDir "${params.outdir}/bismark_methylation_calls", mode: 'copy', + saveAs: {filename -> + if (filename.indexOf("splitting_report.txt") > 0) "logs/$filename" + else if (filename.indexOf("M-bias") > 0) "m-bias/$filename" + else if (filename.indexOf(".cov") > 0) "methylation_coverage/$filename" + else if (filename.indexOf("bedGraph") > 0) "bedGraph/$filename" + else "methylation_calls/$filename" + } input: file bam from bam_dedup @@ -366,7 +391,7 @@ process bismark_summary { */ process qualimap { tag "${bam.baseName}" - publishDir "${params.outdir}/Qualimap", mode: 'copy' + publishDir "${params.outdir}/qualimap", mode: 'copy' input: file bam from bam_dedup_qualimap diff --git a/docs/images/NGI_logo.png b/docs/images/NGI_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..6ef69f820bfc717c4821ca16e0dc8f6be00d74e9 GIT binary patch literal 25121 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. The pipeline will exit with an error message if you try to run it pipeline with the default UPPMAX config profile without a project. + +**Optional Extra:** To avoid having to specify your project every time you run Nextflow, you can add it to your personal Nextflow config file instead. Add this line to `~/.nextflow/config`: + +```groovy +params.project = 'project_ID' // eg. b2017123 +``` + +## 3.2) Configuration: Other clusters +It is entirely possible to run this pipeline on other clusters, though you will need to set up your own config file so that the script knows where to find your reference files and how your cluster works. + +> If you think that there are other people using the pipeline who would benefit from your configuration (eg. other common cluster setups), please let us know. We can add a new configuration and profile which can used by specifying `-profile ` when running the pipeline. + +If you are the only person to be running this pipeline, you can create your config file as `~/.nextflow/config` and it will be applied every time you run Nextflow. Alternatively, save the file anywhere and reference it when running the pipeline with `-c path/to/config`. + +An empty configuration comes with the pipeline, which should be applied by using the command line flag `-profile none`. This prevents the UPPMAX defaults (above) from being applied and means that you only need to configure the specifics for your system. + +### Cluster Environment +By default, Nextflow uses the `local` executor - in other words, all jobs are run in the login session. If you're using a simple server, this may be fine. If you're using a compute cluster, this is bad as all jobs will run on the head node. + +To specify your cluster environment, add the following line to your config file: + +```groovy +process { + executor = 'YOUR_SYSTEM_TYPE' +} +``` + +Many different cluster types are supported by Nextflow. For more information, please see the [Nextflow documentation](https://www.nextflow.io/docs/latest/executor.html). + +Note that you may need to specify cluster options, such as a project or queue. To do so, use the `clusterOptions` config option: + +```groovy +process { + executor = 'SLURM' + clusterOptions = '-A myproject' +} +``` + +### Reference Genomes +The NGI-MethylSeq pipeline needs a reference genome for alignment and annotation. If not already available, start by downloading the relevant reference, for example from [illumina iGenomes](https://support.illumina.com/sequencing/sequencing_software/igenome.html). + +> NB: The below paragraph is a lie. You currently need a Bismark reference. Integrated builds from Fasta files coming soon... + +The minimal requirements are a FASTA file. If a Bismark reference is specified, the pipeline won't have to generate it and will be finished quite a bit faster. Use the command line option `--saveReference` to keep the generated references so that they can be added to your config and used again in the future. + +A reference genome path can be specified on the command line each time you run with `--bismark_index` or `--fasta`. Alternatively, add the paths to the config under a relevant id and just specify this id with `--genome ID` when you run the pipeline _(this can also be set as a default in your config)_: + +```groovy +params { + genomes { + 'YOUR-ID' { + bismar = '/BismarkIndex' + fasta = '/genome.fa' + } + 'OTHER-GENOME' { + // [..] + } + } + // Optional - default genome. Ignored if --genome 'OTHER-GENOME' specified on command line + genome = 'YOUR-ID' +} +``` + + +### Software Requirements +To run the pipeline, several software packages are required. How you satisfy these requirements is essentially up to you and depends on your system. + +#### Environment Modules +If your cluster uses environment modules, the software may already be available. If so, just add lines to your custom config file as follows _(customise module names and versions as appropriate)_: + +```groovy +process { + // Main Bismark Pipeline + $fastqc.module = ['FastQC'] + $trim_galore.module = ['TrimGalore'] + $bismark_align.module = ['samtools/1.3', 'bismark'] + $bismark_deduplicate.module = ['samtools/1.3', 'bismark'] + $bismark_methXtract.module = ['samtools/1.3', 'bismark'] + $bismark_report.module = ['bismark'] + $bismark_summary.module = ['bismark'] + $qualimap.module = ['samtools/1.3', 'QualiMap'] + $multiqc.module = ['MultiQC'] + + // Extras for BWA-meth Pipeline + $makeBwaMemIndex.module = ['bwa', 'bwa-meth', 'samtools/1.3'] + $makeFastaIndex.module = ['samtools/1.3'] + $bwamem_align.module = ['bwa', 'bwa-meth', 'samtools/1.3'] + $samtools_flagstat.module = ['samtools/1.3'] + $samtools_sort.module = ['samtools/1.3'] + $samtools_index.module = ['samtools/1.3'] + $markDuplicates.module = ['picard/2.0.1'] + $methyldackel.module = ['MethylDackel'] +} +``` + +#### Manual Installation +If the software is not already available, you will need to install it. + +If you are able to use [Docker](https://www.docker.com/), you can use the [sclifelab/ngi-methylseq](https://hub.docker.com/r/scilifelab/ngi-methylseq/) image which comes with all requirements. This is pulled by Nextflow automatically if you use `-profile docker` (see below for [further instructions](#33-configuration-docker)). + +We recommend using [Bioconda](https://bioconda.github.io/) to install the required software as the process is quite easy in our experience. + +## 3.3) Configuration: Docker +Docker is a great way to run NGI-MethylSeq, as it manages all software installations and allows the pipeline to be run in an identical software environment across a range of systems. + +Nextflow has [excellent integration](https://www.nextflow.io/docs/latest/docker.html) with Docker, and beyond installing the two tools, not much else is required. + +First, install docker on your system : [Docker Installation Instructions](https://docs.docker.com/engine/installation/) + +Then, simply run the analysis pipeline: +```bash +nextflow run SciLifeLab/NGI-MethylSeq -profile docker # rest of normal launch command +``` + +Nextflow will recognise `SciLifeLab/NGI-MethylSeq` and download the pipeline from GitHub. The `-profile docker` configuration lists the [sclifelab/ngi-methylseq](https://hub.docker.com/r/scilifelab/ngi-methylseq/) image that we have created and is hosted at dockerhub, and this is downloaded. + +A reference genome is still required by the pipeline. Specifying a path to a FASTA file is the minimum requirement, a Bismark reference will automatically be generated. See the above [Reference Genomes](#reference-genomes) documentation for instructions on how to configure Nextflow with preset paths to make this easier. + +A test suite for docker comes with the pipeline, and can be run by moving to the [`tests` directory](https://github.com/ewels/NGI-MethylSeq/tree/master/tests) and running `./docker_test.sh`. This will download a small lambda genome and some data, and attempt to run the pipeline through docker on that small dataset. This is automatically run using [Travis](https://travis-ci.org/SciLifeLab/NGI-MethylSeq/) whenever changes are made to the pipeline. + +## 3.4) Configuration: Amazon EC2 +There are multiple ways of running this pipeline over Amazon's EC2 service. Please see the [NGI-RNAseq pipeline docs](https://github.com/SciLifeLab/NGI-RNAseq/blob/master/docs/amazon_web_services.md) for more information. + +--- + +[![SciLifeLab](images/SciLifeLab_logo.png)](http://www.scilifelab.se/) +[![National Genomics Infrastructure](images/NGI_logo.png)](https://ngisweden.scilifelab.se/) + +--- \ No newline at end of file diff --git a/docs/output.md b/docs/output.md new file mode 100644 index 0000000..51fe86f --- /dev/null +++ b/docs/output.md @@ -0,0 +1,150 @@ +# NGI-MethylSeq Output + +NGI-MethylSeq is the new RNA-seq Best Practice pipeline used by the [National Genomics Infrastructure](https://ngisweden.scilifelab.se/) at [SciLifeLab](https://www.scilifelab.se/platforms/ngi/) in Stockholm, Sweden. + +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. + +Note that NGI-MethylSeq contains two workflows - one for Bismark, one for bwa-meth. This document describes the output from the default Bismark workflow. + +## Pipeline overview +The pipeline is built using [Nextflow](https://www.nextflow.io/) +and processes data using the following steps: + +* [FastQC](#fastqc) - read quality control +* [TrimGalore](#trimgalore) - adapter trimming +* [Bismark](#bismark) + * [Alignment](#alignment) - aligning reads to reference genome + * [Deduplication](#deduplication) - deduplicating reads + * [Methylation Extraction](#methylation-extraction) - calling cytosine methylation steps + * [Report](#report) - single-sample analysis report + * [Summary](#summary) - multi-sample analysis summary report +* [Qualimap](#qualimap) - QC package for genome alignments +* [MultiQC](#multiqc) - aggregate report, describing results of the whole pipeline + +## FastQC +[FastQC](http://www.bioinformatics.babraham.ac.uk/projects/fastqc/) gives general quality metrics about your reads. It provides information about the quality score distribution across your reads, the per base sequence content (%T/A/G/C). You get information about adapter contamination and other overrepresented sequences. + +For further reading and documentation see the [FastQC help](http://www.bioinformatics.babraham.ac.uk/projects/fastqc/Help/). + +> **NB:** The FastQC plots displayed in the MultiQC report shows _untrimmed_ reads. They may contain adapter sequence and potentially regions with low quality. To see how your reads look after trimming, look at the FastQC reports in the `trim_galore` directory. + +**Output directory: `results/fastqc`** + +* `sample_fastqc.html` + * FastQC report, containing quality metrics for your untrimmed raw fastq files +* `sample_fastqc.zip` + * zip file containing the FastQC report, tab-delimited data file and plot images + +## TrimGalore +The NGI-MethylSeq BP 2.0 pipeline uses [TrimGalore](http://www.bioinformatics.babraham.ac.uk/projects/trim_galore/) for removal of adapter contamination and trimming of low quality regions. TrimGalore uses [Cutadapt](https://github.com/marcelm/cutadapt) for adapter trimming and runs FastQC after it finishes. + +MultiQC reports the percentage of bases removed by TrimGalore in the _General Statistics_ table, along with a line plot showing where reads were trimmed. + +**Output directory: `results/trim_galore`** + +Contains FastQ files with quality and adapter trimmed reads for each sample, along with a log file describing the trimming. + +* `sample_val_1.fq.gz`, `sample_val_2.fq.gz` + * Trimmed FastQ data, reads 1 and 2. + * NB: Only saved if `--saveTrimmed` has been specified. +* `logs/sample_val_1.fq.gz_trimming_report.txt` + * Trimming report (describes which parameters that were used) +* `FastQC/sample_val_1_fastqc.zip` + * FastQC report for trimmed reads + +Single-end data will have slightly different file names and only one FastQ file per sample. + +## Bismark +The default NGI-MethylSeq workflow uses [Bismark](http://www.bioinformatics.babraham.ac.uk/projects/bismark/) to process raw sequencing reads into cytosine methylation calls. + +### Alignment +Bismark converts all Cytosines to Thymine _in-silico_ and then aligns against a three-letter reference genome. It produces a BAM file of genomic alignments. + +**Output directory: `results/bismark_alignments/`** + +* `sample.bam` + * Aligned reads in BAM format. + * Only saved if `--saveAlignedIntermediates`, `--nodedup` or `--rrbs` is specified when running the pipeline. +* `logs/sample_PE_report.txt` + * Log file giving summary statistics about alignment. +* `unmapped/unmapped_reads_1.fq.gz`, `unmapped/unmapped_reads_2.fq.gz` + * Unmapped reads in FastQ format. + * Only saved if `--unmapped` specified when running the pipeline. + +### Deduplication +This step removes alignments with identical mapping position to avoid technical duplication in the results. Note that it is skipped if `--saveAlignedIntermediates`, `--nodedup` or `--rrbs` is specified when running the pipeline. + +**Output directory: `results/bismark_deduplicated/`** + +* `deduplicated.bam` + * BAM file with only unique alignments. +* `logs/deduplication_report.txt` + * Log file giving summary statistics about deduplication. + +### Methylation Extraction +The bismark methylation extractor tool takes a BAM file aligned with Bismark and generates files containing methylation information about cytosines. It produces a few different output formats, described below. + +Note that the output may vary a little depending on whether you specify `--comprehensive` or `--non_directional` when running the pipeline. + +Filename abbreviations stand for the following reference alignment strands: + +* `OT` - original top strand +* `OB` - original bottom strand +* `CTOT` - complementary to original top strand +* `CTOB` - complementary to original bottom strand + +(`CTOT` and `CTOB` are not aligned unless `--non_directional` specified). + +**Output directory: `results/bismark_methylation_calls/`** + +* `methylation_calls/XXX_context_sample.txt.gz` + * Individual methylation calls, sorted into files according to cytosine context. +* `methylation_coverage/sample.bismark.cov.gz` + * Coverage text file summarising cytosine methylation values. +* `bedGraph/sample.bedGraph.gz` + * Methylation statuses in [bedGraph](http://genome.ucsc.edu/goldenPath/help/bedgraph.html) format, with 0-based genomic start and 1- based end coordinates. +* `m-bias/sample.M-bias.txt` + * QC data showing methylation bias across read lengths. See the [bismark documentation](https://rawgit.com/FelixKrueger/Bismark/master/Docs/Bismark_User_Guide.html#m-bias-plot) for more information. +* `logs/sample_splitting_report.txt` + * Log file giving summary statistics about methylation extraction. + +### Report +Bismark generates a HTML report describing results for each sample. + +**Output directory: `results/bismark_reports`** + +### Summary +Bismark generates summary text and HTML reports giving an overview of results for all samples in a project. + +**Output directory: `results/bismark_summary`** + +## Qualimap + +[Qualimap BamQC](http://qualimap.bioinfo.cipf.es/doc_html/analysis.html#bam-qc) is a general-use quality-control tool that generates a number of statistics about aligned BAM files. It's not specific to bisulfite data, but it produces several useful stats - for example, insert size and coverage statistics. + +**Output directory: `results/qualimap`** + +* `sample/qualimapReport.html` + * Qualimap HTML report +* `sample/genome_results.txt`, `sample/raw_data_qualimapReport/*.txt` + * Text-based statistics that can be loaded into downstream programs + + +## MultiQC +[MultiQC](http://multiqc.info) is a visualisation 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 within the report data directory. + +**Output directory: `results/multiqc`** + +* `Project_multiqc_report.html` + * MultiQC report - a standalone HTML file that can be viewed in your web browser +* `Project_multiqc_data/` + * Directory containing parsed statistics from the different tools used in the pipeline + +For more information about how to use MultiQC reports, see http://multiqc.info + +--- + +[![SciLifeLab](images/SciLifeLab_logo.png)](http://www.scilifelab.se/) +[![National Genomics Infrastructure](images/NGI_logo.png)](https://ngisweden.scilifelab.se/) + +--- diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..b200f96 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,198 @@ +# NGI-MethylSeq Usage + +## Bismark and bwa-meth workflow + +The NGI-MethylSeq package is actually two pipelines in one. The default (and most polished) workflow uses [Bismark](http://www.bioinformatics.babraham.ac.uk/projects/bismark/) for processing and can be found in `bismark.nf`. Unless specified otherwise, NGI-MethylSeq will run this pipeline. + +The second included workflow uses [BWA-Meth](https://github.com/brentp/bwa-meth) and [MethylDackyl](https://github.com/dpryan79/methyldackel) instead of Bismark and can be found in `bwa-meth.nf`. To run this workflow, you must download the repository files and explicitly call `nextflow run /path/to/files/bwa-meth.nf`. Note that this workflow has not been tested to the same extent and may have bugs. + +All of the documentation refers to the Bismark workflow at this stage, though most of it also applies to the bwa-meth workflow. + +## Running the pipeline +The typical command for running the pipeline is as follows: + +```bash +nextflow run SciLifeLab/NGI-MethylSeq --genome GRCh37 --reads '*_R{1,2}.fastq.gz' +``` + +Note that the pipeline will create files in your working directory: + +```bash +work # Directory containing the nextflow working files +results # Finished results (configurable, see below) +.nextflow_log # Log file from Nextflow +# Other nextflow hidden files, eg. history of pipeline runs and old logs. +``` + +## Input Data + +### `--reads` +Location of the input FastQ files: + +```bash + --reads 'path/to/data/sample_*_{1,2}.fastq' +``` + +**NB: Must be enclosed in quotes!** + +Note that the `{1,2}` parentheses are required to specify paired end data. The file path should be in quotation marks to prevent shell glob expansion. + +If left unspecified, the pipeline will assume that the data is in a directory called `data` in the working directory (`data/*{1,2}.fastq.gz`). + +### `--singleEnd` +By default, the pipeline expects paired-end data. If you have single-end data, specify `--singleEnd` on the command line when you launch the pipeline. A normal glob pattern, enclosed in quotation marks, can then be used for `--reads`. For example: `--singleEnd --reads '*.fastq'` + +It is not possible to run a mixture of single-end and paired-end files in one run. + +## Reference Genomes + +### `--genome` +The reference genome to use for the analysis, needs to be one of the genome specified in the config file. This is `False` by default and needs to be specified (unless index files are supplied, see below). + +See [`conf/uppmax.config`](conf/uppmax.config) for a list of the supported reference genomes and their keys. Common genomes that are supported are: + +* Human + * `--genome GRCh37` +* Mouse + * `--genome GRCm38` +* _Drosophila_ + * `--genome BDGP6` +* _S. cerevisiae_ + * `--genome 'R64-1-1'` + +> There are numerous others - check the config file for more. + +If you're not running on UPPMAX (the default profile), you can create your own config file with paths to your reference genomes. See the [Nextflow documentation](https://www.nextflow.io/docs/latest/config.html) for instructions on where to add this. + +The syntax for this reference configuration is as follows: + +```groovy +params { + genomes { + 'GRCh37' { + bismark = '' + fasta = '' // Used if no bismark index given + } + // Any number of additional genomes, key is used with --genome + } +} +``` + +### `--bismark_index`, `--fasta` +If you prefer, you can specify the full path to your reference genome when you run the pipeline: + +```bash +--bismark_index '[path to Bismark index]' +--fasta '[path to Fasta reference]' +``` + +### `--saveReference` +Supply this parameter to save any generated reference genome files to your results folder. These can then be used for future pipeline runs, reducing processing times. + +## Adapter Trimming +The pipeline accepts a number of parameters to change how the trimming is done, according to your data type. +The following settings are set for these command line flags: + +| Parameter | 5' R1 Trim | 5' R2 Trim | 3' R1 Trim | 3' R2 Trim | +|-----------------|------------|------------|------------|------------| +| `--pbat` | 6 | 9 | 6 | 9 | +| `--single_cell` | 6 | 6 | 6 | 6 | +| `--epignome` | 8 | 8 | 8 | 8 | +| `--accel` | 10 | 15 | 10 | 10 | +| `--zymo` | 10 | 15 | 10 | 10 | +| `--cegx` | 6 | 6 | 2 | 2 | + +You can specify custom trimming parameters as follows: + +* `--clip_r1 ` + * Instructs Trim Galore to remove bp from the 5' end of read 1 (or single-end reads). +* `--clip_r2 ` + * Instructs Trim Galore to remove bp from the 5' end of read 2 (paired-end reads only). +* `--three_prime_clip_r1 ` + * Instructs Trim Galore to remove bp from the 3' end of read 1 _AFTER_ adapter/quality trimming has been +* `--three_prime_clip_r2 ` + * Instructs Trim Galore to re move bp from the 3' end of read 2 _AFTER_ adapter/quality trimming has been performed. + +### `--rrbs` +Specifying `--rrbs` will pass on the `--rrbs` parameter to TrimGalore! See the [TrimGalore! documentation](https://github.com/FelixKrueger/TrimGalore/blob/master/Docs/Trim_Galore_User_Guide.md#rrbs-specific-options-mspi-digested-material) to read more about the effects of this option. + +### `--notrim` +Specifying `--notrim` will skip the adapter trimming step. Use this if your input FastQ files have already been trimmed outside of the workflow. + +### `--saveTrimmed` +By default, trimmed FastQ files will not be saved to the results directory. Specify this flag (or set to true in your config file) to copy these files to the results directory when complete. + + +## Bismark Parameters + +### `--pbat` +Using the `--pbat` parameter will affect the trimming (see above) and also set the `--pbat` flag when aligning with Bismark. It tells Bismark to align complementary strands (the opposite of `--directional`). + +### `--non_directional` +By default, Bismark assumes that libraries are directional and does not align against complementary strands. If your library prep was not direcional, use `--non_directional` to align against all four possible strands. + +Note that the `--single_cell` and `--zymo` parameters both set the `--non_directional` workflow flag automatically. + +### `--comprehensive` +This flag instructs the Bismark methylation extractor to use the `--comprehensive` and `--merge_non_CpG` flags. This produces coverage files with information from about all strands and cytosine contexts merged into two files - one for CpG context and one for non-CpG context. Note that for large genomes (eg. Human), these can be massive files. This is only recommended for small genomes (especially those that don't exhibit strong CpG context methylation specificity). + +### `--relaxMismatches` and `--numMismatches` + +By default, Bismark is pretty strict about which alignments it accepts as valid. If you have good reason to believe that your reads will contain more mismatches than normal, these flags can be used to relax the stringency that Bismark uses when accepting alignments. This can greatly improve the number of aligned reads you get back, but may negatively impact the quality of your data. + +`--numMismatches` is `0.2` by default in Bismark, or `0.6` if `--relaxMismatches` is specified. `0.6` will allow a penalty of `bp * -0.6` - for 100bp reads, this is `-60`. Mismatches cost `-6`, gap opening `-5` and gap extension `-2`. So, `-60` would allow 10 mismatches or ~ 8 x 1-2bp indels. + +### `--unmapped` +Use the `--unmapped` flag to set the `--unmapped` flag with Bismark align and save the unmapped reads to FastQ files. + +### `--nodedup` +By default, the pipeline includes a deduplication step after alignment. Use `--nodedup` on the command line to skip this step. This is automatically set if using `--rrbs` for the workflow. + +### `--saveAlignedIntermediates` +By default intermediate BAM files will not be saved. The final BAM files created after the Bismark deduplication step are always saved. Set to true to also copy out BAM files from the initial Bismark alignment step. If `--nodedup` or `--rrbs` is specified then BAMs from the initial alignment will always be saved. + +## Job Resources +### Automatic resubmission +Each step in the pipeline has a default set of requirements for number of CPUs, memory and time. For most of the steps in the pipeline, if the job exits on UPPMAX with an error code of `143` (exceeded requested resources) it will automatically resubmit with higher requests (2 x original, then 3 x original). If it still fails after three times then the pipeline is stopped. + +### Custom resource requests +Wherever process-specific requirements are set in the pipeline, the default value can be changed by creating a custom config file. See the files in [`conf`](../conf) for examples. + +## Other command line parameters +### `--outdir` +The output directory where the results will be saved. + +### `--email` +Set this parameter to your e-mail address to get a summary e-mail with details of the run sent to you when the workflow exits. If set in your user config file (`~/.nextflow/config`) then you don't need to speicfy this on the command line for every run. + +### `--clusterOptions` +Submit arbitrary SLURM options (UPPMAX profile only). For instance, you could use `--clusterOptions '-p devcore'` +to run on the development node (though won't work with default process time requests). + +### `--multiqc_config` +If you would like to supply a custom config file to MultiQC, you can specify a path with `--multiqc_config`. This is used instead of the config file specific to the pipeline. + +### `-name` +Name for the pipeline run. If not specified, Nextflow will automatically generate a random mnemonic. + +**NB:** Single hyphen (core Nextflow option) + +### `-c` +Specify the path to a specific config file (this is a core NextFlow command). Useful if using different UPPMAX +projects or different sets of reference genomes. + +**NB:** Single hyphen (core Nextflow option) + +Note - you can use this to override defaults. For example, we run on UPPMAX but don't want to use the MultiQC +environment module as is the default. So we specify a config file using `-c` that contains the following: + +```groovy +process.$multiqc.module = [] +``` + +--- + +[![SciLifeLab](images/SciLifeLab_logo.png)](http://www.scilifelab.se/) +[![National Genomics Infrastructure](images/NGI_logo.png)](https://ngisweden.scilifelab.se/) + +---