Skip to content
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- [[PR #542](https://github.com/nf-core/chipseq/pull/542)] - Updated pipeline template to [nf-core/tools 4.1.0](https://github.com/nf-core/tools/releases/tag/4.1.0),
increased nf-test selfhosted runners volume to 60gb
- [[PR #547](https://github.com/nf-core/chipseq/pull/547)] - Updated pipeline template to [nf-core/tools 4.2.2](https://github.com/nf-core/tools/releases/tag/4.2.2)
- [[PR #548](https://github.com/nf-core/chipseq/pull/548)] - Allow `--macs_gsize` in scientific notation (e.g. `2.7e9`), clarify the MACS3 genome size warning/error messages and document `--macs_gsize` and `--read_length` in the usage docs.

### Parameters

Expand Down
27 changes: 27 additions & 0 deletions docs/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,33 @@ The minimum reference genome requirements are a FASTA and a GTF file, all other

> **NB:** Compressed reference files are also supported by the pipeline i.e. standard files with the `.gz` extension and indices folders with the `tar.gz` extension.

## MACS3 effective genome size

MACS3 requires an [effective genome size](https://macs3-project.github.io/MACS/docs/callpeak.html#options-controling-peak-calling-behaviors) for peak calling. This value depends on the read length, since longer reads can be mapped uniquely to a larger fraction of the genome. The pipeline determines it as follows:

1. If `--genome` and `--read_length` are provided and pre-computed `macs_gsize` for
[`igenomes.config`](https://github.com/nf-core/chipseq/blob/master/conf/igenomes.config) exist it will be used.
Some commonly used genomes contain pre-computed `macs_gsize` with different read length (`50`, `75`, `100`, `150` and
`200` ).
2. If `--fasta` and `--read_length` are provided e.g. for custom genomes, then `macs_gsize` is calculated
from the genome FASTA with `khmer unique-kmers.py`.
3. `--macs_gsize` can also be explicitly provided and will then be used, this is a fall back, **options 1 and 2** are
preferred. It can be given as an integer, e.g. `--macs_gsize 2805665311`.

If neither `--macs_gsize` nor `--read_length` is provided, the pipeline stops with an error. This also applies when
using `--genome` only, because the pre-computed value is selected by read length. Valid combinations are:

```bash
# 1. Use the pre-computed value for GRCh38 and 150 bp reads
nextflow run nf-core/chipseq --input samplesheet.csv --outdir results --genome GRCh38 --read_length 150 -profile docker

# 2. Or providing a custom fasta and the read length explicitly
nextflow run nf-core/chipseq --input samplesheet.csv --outdir results --fasta path/to/GRCh38.fasta[.gz] --read_length 150 -profile docker

# 3. Or provide the effective genome size explicitly
nextflow run nf-core/chipseq --input samplesheet.csv --outdir results --genome GRCh38 --macs_gsize 2805665311 -profile docker
```

## Blacklist bed files

The blacklist bed files where obtained using the commands below:
Expand Down
5 changes: 3 additions & 2 deletions nextflow_schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -154,10 +154,11 @@
},
"macs_gsize": {
"type": "integer",
"minimum": 1,
"description": "Effective genome size parameter required by MACS3.",
Comment thread
Kevin-Brockers marked this conversation as resolved.
Resolved
"help_text": "[Effective genome size](https://github.com/taoliu/MACS#-g--gsize) parameter required by MACS3. If using an iGenomes reference these have been provided for any of the genomes available in the igenomes.config, and for the following read lengths (50,75,100,150,200) that should be set using the `--read_length` parameter. For other genomes, if this parameter is not specified it will be inferred using the provided `--read_length` or otherwise the pipeline execution will stop with an error.",
"help_text": "[Effective genome size](https://macs3-project.github.io/MACS/docs/callpeak.html#options-controling-peak-calling-behaviors) parameter required by MACS3, given as a positive integer (e.g. `2701262066`). If this parameter is set it always takes precedence. Otherwise, when using `--genome`, a pre-computed value is taken from `igenomes.config` for the read length given with `--read_length` (50, 75, 100, 150 or 200). For other genomes it is calculated with `khmer` from the genome FASTA and `--read_length`. If neither `--macs_gsize` nor `--read_length` are provided the pipeline will stop with an error. See the usage documentation for details.",
"fa_icon": "fas fa-arrows-alt-h",
"errorMessage": "MACS3 effective genome size must be a positive number."
"errorMessage": "MACS3 effective genome size must be a positive integer (e.g. 2701262066)."
},
"blacklist": {
"type": "string",
Expand Down
57 changes: 50 additions & 7 deletions subworkflows/local/utils_nfcore_chipseq_pipeline/main.nf
Original file line number Diff line number Diff line change
Expand Up @@ -183,12 +183,46 @@ def validateInputParameters() {
}

if (!params.macs_gsize) {
if (!params.read_length) {
macsGsizeError()
}
macsGsizeWarn(log)
}
}

//
// Read lengths for which a pre-computed MACS3 genome size is available for the selected '--genome'
//
def igenomesMacsGsizeReadLengths() {
if (params.genomes && params.genome && params.genomes.containsKey(params.genome)) {
def gsize = params.genomes[params.genome].get('macs_gsize')
if (gsize instanceof Map) {
return gsize.keySet().collect { read_length -> read_length.toString() }
}
}
return []
}

if (!params.read_length && !params.macs_gsize) {
error ("Both '--read_length' and '--macs_gsize' not specified! Please specify either to infer MACS3 genome size for peak calling.")
//
// Exit pipeline if the MACS3 genome size can neither be looked up nor calculated
//
def macsGsizeError() {
def read_lengths = igenomesMacsGsizeReadLengths()
def error_string = "~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n" +
" The MACS3 effective genome size could not be determined.\n" +
" Please provide one of the following:\n"
if (read_lengths) {
error_string +=
" - '--read_length' (one of: ${read_lengths.join(', ')}) to use the value\n" +
" pre-computed for '--genome ${params.genome}' in 'igenomes.config'.\n"
} else {
error_string +=
" - '--read_length' to calculate it from the genome FASTA with 'khmer'.\n"
}
error_string +=
" - '--macs_gsize' to set it explicitly, e.g. '--macs_gsize 2805665311'.\n" +
"~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"
error(error_string)
}

//
Expand Down Expand Up @@ -279,12 +313,21 @@ def gtfGffWarn(log) {
}

//
// Print a warning if macs_gsize parameter has not been provided
// Print a warning if the MACS3 genome size will be calculated with khmer
//
def macsGsizeWarn(log) {
log.warn "=============================================================================\n" +
" --macs_gsize parameter has not been provided.\n" +
" It will be auto-calculated by 'khmer unique-kmers.py' using the '--read_length' parameter.\n" +
" Explicitly provide '--macs_gsize macs3_genome_size' to change this behaviour.\n" +
def read_lengths = igenomesMacsGsizeReadLengths()
def warn_string = "=============================================================================\n" +
" '--macs_gsize' has not been provided"
if (read_lengths) {
warn_string += " and no pre-computed value exists for\n" +
" '--genome ${params.genome}' with '--read_length ${params.read_length}' (available: ${read_lengths.join(', ')}).\n"
} else {
warn_string += ".\n"
}
warn_string +=
" It will be calculated by 'khmer unique-kmers.py' using '--read_length ${params.read_length}'.\n" +
" Explicitly provide '--macs_gsize' (e.g. '--macs_gsize 2805665311') to change this behaviour.\n" +
"==================================================================================="
log.warn warn_string
}
Loading