-
Notifications
You must be signed in to change notification settings - Fork 154
Add more resource usage guidance docs #1055
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jfy133
wants to merge
9
commits into
dev
Choose a base branch
from
resource-guidance
base: dev
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+157
−6
Open
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
23f3ecb
Expand resource usage guidance in documentation
jfy133 a705b32
Add link to Resource guidance in usage.md
jfy133 daf5e5d
Add defaults table
jfy133 62ae4fc
update CHANGELOG
jfy133 5f8ec6c
Update nextflow.config
jfy133 11ae462
Apply suggestions from code review
jfy133 e60aa7d
Update docs/usage/resource_guidance.md
jfy133 d1a0e44
Merge branch 'dev' into resource-guidance
dialvarezs 66fa29b
chore: update resources
dialvarezs File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| # Resource usage guidance | ||
|
|
||
| **nf-core/mag** is a bioinformatics best-practice analysis pipeline for the assembly, binning, and annotation of metagenomes. | ||
| Due to the nature of metagenomic samples, nf-core/mag can in some cases require large amounts of computational resources to execute. | ||
| In this page we provide information and guidance on how nf-core/mag works by default, and in some cases how to optimise computational resource usage. | ||
|
jfy133 marked this conversation as resolved.
|
||
|
|
||
|
jfy133 marked this conversation as resolved.
|
||
| ## Multi-sample or bin executing modules | ||
|
|
||
| By default, nf-core/mag aims to make the runtime as efficiently as possible on HPC and similar infrastructure through generating more but shorter running jobs. | ||
|
|
||
| In most cases, all pre-assembly steps typically run one job per input FASTQ file. | ||
| After assembly, most steps run on a per assembly or contig. | ||
| After binning, each step runs on a per-bin basis, and so forth. | ||
|
|
||
| There are a few exceptions to this. | ||
| In the following cases, depending on the options you set in the pipeline, you may see some steps running as a single job with multiple samples. | ||
|
|
||
| - Multiple samples processed in one job: | ||
| - If `--coassemble_group`: all reads across all samples in a group will be pooled into one assembly job (e.g. MEGAHIT, metaSPAdes) | ||
| - If `--gtdbtk_single_job`: all bins across all samples will be pooled into a single GTDBTk classification job | ||
|
|
||
| ## Default resource requests | ||
|
|
||
| The following table lists the default resources that Nextflow will request from a machine on it's first execution attempt for a given module. | ||
| It summaries information recorded in the file `conf/base.conf` and the module files themselves `modules`. | ||
|
|
||
| To customise these resource requests, see the central [nf-core instructions](https://nf-co.re/docs/running/configuration/nextflow-for-your-system#customize-process-resources). | ||
|
|
||
| Please also note the following: | ||
|
|
||
| - Not all modules in this table will run in every pipeline run, nor will the tool necessarily _use_ the requested amount. | ||
| - On certain module execution failures (such as out of memory), Nextflow will try and resubmit with increased resources with the equation `<resource value> * task.attempt`, up to a certain number of retries. See `conf/base.conf` for more information. | ||
| - Some modules have a dedicate flag to fix the number of CPUs for reproducibility reasons (e.g. `--megahit_fix_cpu_1`). See the [parameters page](https://nf-co.re/mag/dev/parameters). | ||
| - `METASPADES`, `METASPADESHYBRID`, `FILTLONG`, `METAMDBG_ASM` and `FLYE` grow memory and time exponentially with each retry (`<value> * 2 ** (task.attempt - 1)`); the table shows the first-attempt request. | ||
| - `ALE` requests 18.GB by default, but 30.GB when `--coassemble_group` is set. | ||
|
|
||
| The table is ordered first by 'Source' of defaults by specificity of definition, then by 'memory', and then 'Module name' by alphabetical order. | ||
|
|
||
| | Module Name | CPU | Memory | Time | Source | | ||
| | ------------------------------------ | --- | ------ | ---- | --------------------- | | ||
| | GTDBTK_CLASSIFYWF | 10 | 140.GB | 12.h | Named customisation | | ||
| | CATPACK_BINS | 6 | 120.GB | 8.h | Named customisation | | ||
| | FLYE | 12 | 72.GB | 24.h | Named customisation | | ||
| | METAMDBG_ASM | 12 | 72.GB | 24.h | Named customisation | | ||
| | FILTLONG | 8 | 64.GB | 24.h | Named customisation | | ||
| | METASPADES | 10 | 64.GB | 24.h | Named customisation | | ||
| | METASPADESHYBRID | 10 | 64.GB | 24.h | Named customisation | | ||
| | PORECHOP_ABI | 4 | 64.GB | 8.h | Named customisation | | ||
| | CATPACK_CONTIGS | 6 | 60.GB | 8.h | Named customisation | | ||
| | CHECKM_LINEAGEWF | 6 | 42.GB | 8.h | Named customisation | | ||
| | MEGAHIT | 8 | 40.GB | 16.h | Named customisation | | ||
| | PORECHOP_PORECHOP | 4 | 30.GB | 4.h | Named customisation | | ||
| | BOWTIE2_HOST_REMOVAL_BUILD | 10 | 20.GB | 4.h | Named customisation | | ||
| | METABAT2_METABAT2 | 8 | 20.GB | 8.h | Named customisation | | ||
| | ALE | 1 | 18.GB | 4.h | Named customisation | | ||
| | MAG_DEPTHS | 1 | 16.GB | 4.h | Named customisation | | ||
| | BUSCO_BUSCO | 10 | 12.GB | 8.h | Named customisation | | ||
| | BOWTIE2_HOST_REMOVAL_ALIGN | 10 | 10.GB | 6.h | Named customisation | | ||
| | NANOLYSE | 2 | 10.GB | 3.h | Named customisation | | ||
| | BOWTIE2_ASSEMBLY_ALIGN | 2 | 8.GB | 8.h | Named customisation | | ||
| | BOWTIE2_PHIX_REMOVAL_ALIGN | 4 | 4.GB | 6.h | Named customisation | | ||
| | CONCAT_BUSCO_TSV | 1 | 1.GB | 4.h | Named customisation | | ||
| | CONCAT_CHECKM_TSV | 1 | 1.GB | 4.h | Named customisation | | ||
| | CONCAT_CHECKM2_TSV | 1 | 1.GB | 4.h | Named customisation | | ||
| | CONCAT_GUNC_CHECKM_TSV | 1 | 1.GB | 4.h | Named customisation | | ||
| | CONCAT_GUNC_TSV | 1 | 1.GB | 4.h | Named customisation | | ||
| | RENAME_POSTDASTOOL | 1 | 1.GB | 4.h | Named customisation | | ||
| | RENAME_PREDASTOOL | 1 | 1.GB | 4.h | Named customisation | | ||
| | SEQKIT_STATS | 1 | 1.GB | 4.h | Named customisation | | ||
| | COMEBIN_RUNCOMEBIN | 12 | 72.GB | 16.h | Label: process_high | | ||
| | CONCOCT_CONCOCT | 12 | 72.GB | 16.h | Label: process_high | | ||
| | GENOMAD_ENDTOEND | 12 | 72.GB | 16.h | Label: process_high | | ||
| | MINIMAP2_ALIGN | 12 | 72.GB | 16.h | Label: process_high | | ||
| | ADAPTERREMOVAL | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | BBMAP_BBNORM | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | BCFTOOLS_CONSENSUS | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | BCFTOOLS_VIEW | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | CATPACK_PREPARE | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | CHECKM2_PREDICT | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | CHOPPER | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | DASTOOL_DASTOOL | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | FASTP | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | GUNC_RUN | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | MAXBIN2 | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | METABAT2_JGISUMMARIZEBAMCONTIGDEPTHS | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | METABINNER_METABINNER | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | METAEUK_EASYPREDICT | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | MMSEQS_DATABASES | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | PYDAMAGE_ANALYZE | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | SEMIBIN_SINGLEEASYBIN | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | TIARA_TIARA | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | TRIMMOMATIC | 6 | 36.GB | 8.h | Label: process_medium | | ||
| | ADJUST_MAXBIN2_EXT | 2 | 12.GB | 4.h | Label: process_low | | ||
| | BCFTOOLS_INDEX | 2 | 12.GB | 4.h | Label: process_low | | ||
| | CHECKM_QA | 2 | 12.GB | 4.h | Label: process_low | | ||
| | FASTQC | 2 | 12.GB | 4.h | Label: process_low | | ||
| | FIND_CONCATENATE | 2 | 12.GB | 4.h | Label: process_low | | ||
| | METABINNER_BINS | 2 | 12.GB | 4.h | Label: process_low | | ||
| | METABINNER_KMER | 2 | 12.GB | 4.h | Label: process_low | | ||
| | METABINNER_TOOSHORT | 2 | 12.GB | 4.h | Label: process_low | | ||
| | MINIMAP2_INDEX | 2 | 12.GB | 4.h | Label: process_low | | ||
| | NANOPLOT | 2 | 12.GB | 4.h | Label: process_low | | ||
| | NANOQ | 2 | 12.GB | 4.h | Label: process_low | | ||
| | PROKKA | 2 | 12.GB | 4.h | Label: process_low | | ||
| | PYPOLCA_RUN | 2 | 12.GB | 4.h | Label: process_low | | ||
| | SAMTOOLS_INDEX | 2 | 12.GB | 4.h | Label: process_low | | ||
| | SAMTOOLS_UNMAPPED | 2 | 12.GB | 4.h | Label: process_low | | ||
| | SPLIT_FASTA | 2 | 12.GB | 4.h | Label: process_low | | ||
| | SUMMARISE_PYDAMAGEBINS | 2 | 12.GB | 4.h | Label: process_low | | ||
| | CAT_FASTQ | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CATPACK_ADDNAMES | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CATPACK_DOWNLOAD | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CATPACK_SUMMARISE | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CHECKM2_DATABASEDOWNLOAD | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CONCOCT_CONCOCTCOVERAGETABLE | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CONCOCT_CUTUPFASTA | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CONCOCT_EXTRACTFASTABINS | 1 | 6.GB | 4.h | Label: process_single | | ||
| | CONCOCT_MERGECUTUPCLUSTERING | 1 | 6.GB | 4.h | Label: process_single | | ||
| | DASTOOL_FASTATOCONTIG2BIN | 1 | 6.GB | 4.h | Label: process_single | | ||
| | FREEBAYES | 1 | 6.GB | 4.h | Label: process_single | | ||
| | GENOMAD_DOWNLOAD | 1 | 6.GB | 4.h | Label: process_single | | ||
| | GUNC_DOWNLOADDB | 1 | 6.GB | 4.h | Label: process_single | | ||
| | GUNC_MERGECHECKM | 1 | 6.GB | 4.h | Label: process_single | | ||
| | GUNZIP | 1 | 6.GB | 4.h | Label: process_single | | ||
| | MULTIQC | 1 | 6.GB | 4.h | Label: process_single | | ||
| | PRODIGAL | 1 | 6.GB | 4.h | Label: process_single | | ||
| | PYDAMAGE_FILTER | 1 | 6.GB | 4.h | Label: process_single | | ||
| | QSV_CAT | 1 | 6.GB | 4.h | Label: process_single | | ||
| | SAMTOOLS_FAIDX | 1 | 6.GB | 4.h | Label: process_single | | ||
| | SAMTOOLS_STATS | 1 | 6.GB | 4.h | Label: process_single | | ||
| | SEQTK_MERGEPE | 1 | 6.GB | 4.h | Label: process_single | | ||
| | TIARA_CLASSIFY | 1 | 6.GB | 4.h | Label: process_single | | ||
| | UNTAR | 1 | 6.GB | 4.h | Label: process_single | | ||
| | BIN_SUMMARY | 1 | 7.GB | 4.h | Default | | ||
| | BOWTIE2_ASSEMBLY_BUILD | 1 | 7.GB | 4.h | Default | | ||
| | BOWTIE2_PHIX_REMOVAL_BUILD | 1 | 7.GB | 4.h | Default | | ||
| | CONVERT_DEPTHS | 1 | 7.GB | 4.h | Default | | ||
| | GTDBTK_DB_PREPARATION | 1 | 7.GB | 4.h | Default | | ||
| | GTDBTK_SUMMARY | 1 | 7.GB | 4.h | Default | | ||
| | MAG_DEPTHS_SUMMARY | 1 | 7.GB | 4.h | Default | | ||
| | PREPARE_BIGMAG_SUMMARY | 1 | 7.GB | 4.h | Default | | ||
| | QUAST | 1 | 7.GB | 4.h | Default | | ||
| | QUAST_BINS | 1 | 7.GB | 4.h | Default | | ||
|
|
||
| _Table generated for nf-core/mag v5.5, using Claude Haiku 4.5, and corrected for accuracy by a human._ | ||
|
|
||
| <!-- TODO mag: update when new modules added/defaults changed, if using an LLM, careful to tell it to follow module import aliases --> | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The long table might become a maintenance headache, but it will be useful I believe. In a better world, this would be generated by nf-core/tools by inspection of module code perhaps?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, I've made an issue proposing this: nf-core/tools#4345, if you want to add support to it :)