This pipeline takes BAMs and corresponding indices from pipeline-align-DNA and performs indel realignment and BQSR. It can be run with any combination of normal and tumor samples (normal only, tumor only, normal-tumor paired, multiple normal and tumor samples).
Requirements: Currently supported Nextflow versions: 23.04.2
The pipeline is currently configured to run on a SINGLE NODE mode with normal only, tumor only, normal-tumor paired, or multiple normal and tumor samples.
-
Update the params section of the .config file (Example config).
-
Update the YAML (Template YAMLs).
-
Download the submission script (submit_nextflow_pipeline.py) from here, and submit your pipeline below.
- YAML input
python submit_nextflow_pipeline.py \
--nextflow_script /path/to/main.nf \
--nextflow_config /path/to/call-recalibrate-bam.config \
--nextflow_yaml /path/to/sample.yaml \
--pipeline_run_name job_name \
--partition_type <type> \
--email email_address
Split the reference genome into intervals for parallel processing. If params.parallelize_by_chromosome
is set then the genome will be split by chromosome, otherwise it will be split into up to params.scatter_count
intervals.
Generate indel realignment targets and realign indels per interval.
Assess how sequencing errors correlate with four covariates (assigned quality score, read group, machine cycle producing this base, and current and immediately upstream base) and output base quality score recalibration table.
Apply the base quality score recalibration to each interval and reheader output as necessary.
Merge BAMs from each interval to generate a whole sample BAM.
If params.parallelize_by_chromosome
is not set, run a deduplication process to remove reads duplicated due to overlap on interval splitting sites.
Generate a BAI index file for fast random access of the whole sample BAM.
Tabulate pileup metrics for inferring contamination. Summarize counts of reads that support reference, alternate and other alleles for given sites.
Calculates the fraction of reads coming from cross-sample contamination, given results from Step 7. For paired samples, generates an additional output table containing segmentation of the tumor by minor allele fraction.
If params.is_DOC_run
is set, generate coverage summary information for the whole sample BAM from step 5, partitioned by sample, read group, and library.
Generate sha512 checksum for final BAM and BAI files.
Field | Type | Description |
---|---|---|
patient_id | string | Patient ID (will be standardized according to data storage structure in the near future) |
normal_BAM | path | Set to absolute path to normal BAM |
tumor_BAM | path | Set to absolute path to tumour BAM |
recalibration_table | path | (Optional) Absolute path to recalibration table |
Input without pre-existing recalibration table(s):
---
patient_id: "patient_id"
input:
BAM:
normal:
- "/absolute/path/to/BAM"
- "/absolute/path/to/BAM"
tumor:
- "/absolute/path/to/BAM"
- "/absolute/path/to/BAM"
Input with existing recalibration table(s):
---
patient_id: "patient_id"
input:
BAM:
normal:
- "/absolute/path/to/BAM"
- "/absolute/path/to/BAM"
tumor:
- "/absolute/path/to/BAM"
- "/absolute/path/to/BAM"
recalibration_table:
- "/absolute/path/to/recalibration/table1"
- "/absolute/path/to/recalibration/table2"
For normal-only or tumour-only samples, exclude the fields for the other state.
Input Parameter | Required | Type | Description |
---|---|---|---|
dataset_id |
Yes | string | Dataset ID |
blcds_registered_dataset |
Yes | boolean | Set to true when using BLCDS folder structure; use false for now |
output_dir |
Yes | string | Need to set if blcds_registered_dataset = false |
save_intermediate_files |
Yes | boolean | Set to false to disable publishing of intermediate files; true otherwise; disabling option will delete intermediate files to allow for processing of large BAMs |
aligner |
Yes | string | Original aligner used to align input BAMs; formatted as <aligner>-<aligner-version> |
cache_intermediate_pipeline_steps |
No | boolean | Set to true to enable process caching from Nextflow; defaults to false |
is_emit_original_quals |
Yes | boolean | Set to true to emit original quality scores; false to omit |
is_DOC_run |
Yes | boolean | Set to true to run GATK DepthOfCoverage (very time-consuming for large BAMs); false otherwise |
parallelize_by_chromosome |
Yes | boolean | Whether the parallelize by chromosome or by scattering intervals |
scatter_count |
Yes | integer | Number of intervals to divide into for parallelization |
intervals |
Yes | path | Use all .list in inputs for WGS; Set to absolute path to targeted exome interval file (with .interval_list, .list, .intervals, or .bed suffix) |
gatk_ir_compression |
No | integer | Compression level for BAMs output by IndelRealigner. Default: 0. Range: 0-9 |
reference_fasta |
Yes | path | Absolute path to reference genome fasta file, e.g., /hot/ref/reference/GRCh38-BI-20160721/Homo_sapiens_assembly38.fasta |
bundle_mills_and_1000g_gold_standard_indels_vcf_gz |
Yes | path | Absolute path to Mills & 1000G Gold Standard Indels file, e.g., /hot/ref/tool-specific-input/GATK/GRCh38/Mills_and_1000G_gold_standard.indels.hg38.vcf.gz |
bundle_known_indels_vcf_gz |
Yes | path | Absolute path to known indels file, e.g., /hot/ref/tool-specific-input/GATK/GRCh38/Homo_sapiens_assembly38.known_indels.vcf.gz |
bundle_v0_dbsnp138_vcf_gz |
Yes | path | Absolute path to dbsnp file, e.g., /hot/ref/tool-specific-input/GATK/GRCh38/resources_broad_hg38_v0_Homo_sapiens_assembly38.dbsnp138.vcf.gz |
bundle_contest_hapmap_3p3_vcf_gz |
Yes | path | Absolute path to HapMap 3.3 biallelic sites file, e.g., /hot/ref/tool-specific-input/GATK/GRCh38/Biallelic/hapmap_3.3.hg38.BIALLELIC.PASS.2021-09-01.vcf.gz |
work_dir |
optional | path | Path of working directory for Nextflow. When included in the sample config file, Nextflow intermediate files and logs will be saved to this directory. With ucla_cds, the default is /scratch and should only be changed for testing/development. Changing this directory to /hot or /tmp can lead to high server latency and potential disk space limitations, respectively. |
docker_container_registry |
optional | string | Registry containing tool Docker images. Default: ghcr.io/uclahs-cds |
metapipeline_delete_input_bams |
optional | boolean | Set to true to delete the input BAM files once the initial processing step is complete. WARNING: This option should NOT be used for individual runs of recalibate-BAM; it's intended for metapipeline-DNA to optimize disk space usage by removing files that are no longer needed from the workDir . |
metapipeline_final_output_dir |
optional | string | Absolute path for the final output directory of metapipeline-DNA that's expected to contain the output BAM from align-DNA. WARNING: This option should not be used for individual runs of recalibrate-BAM; it's intended for metapipeline-DNA to optimize disk space usage. |
metapipeline_states_to_delete |
optional | list | List of states for which to delete input BAMs. WARNING: This option should not be used for individual runs of recalibrate-BAM; it's intended for metapipeline-DNA to optimize disk space usage. |
base_resource_update |
optional | namespace | Namespace of parameters to update base resource allocations in the pipeline. Usage and structure are detailed in template.config and below. |
To update the base resource (cpus or memory) allocations for processes, use the following structure and add the necessary parts. The default allocations can be found in the node-specific config files
base_resource_update {
memory = [
[['process_name', 'process_name2'], <multiplier for resource>],
[['process_name3', 'process_name4'], <different multiplier for resource>]
]
cpus = [
[['process_name', 'process_name2'], <multiplier for resource>],
[['process_name3', 'process_name4'], <different multiplier for resource>]
]
}
Note Resource updates will be applied in the order they're provided so if a process is included twice in the memory list, it will be updated twice in the order it's given.
Examples:
- To double memory of all processes:
base_resource_update {
memory = [
[[], 2]
]
}
- To double memory for
run_ApplyBQSR_GATK
and triple memory forrun_validate_PipeVal
andrun_IndelRealigner_GATK
:
base_resource_update {
memory = [
['run_ApplyBQSR_GATK', 2],
[['run_validate_PipeVal', 'run_IndelRealigner_GATK'], 3]
]
}
- To double CPUs and memory for
run_ApplyBQSR_GATK
and double memory forrun_validate_PipeVal
:
base_resource_update {
cpus = [
['run_ApplyBQSR_GATK', 2]
]
memory = [
[['run_ApplyBQSR_GATK', 'run_validate_PipeVal'], 2]
]
}
Output | Description |
---|---|
<aligner>_<GATK>_<dataset_id>_<sample_id>.bam |
Post-processes BAM |
<aligner>_<GATK>_<dataset_id>_<sample_id>.bam.sha512 |
Post-processes BAM SHA512 checksum |
<aligner>_<GATK>_<dataset_id>_<sample_id>.bam.bai |
Post-processes BAM index |
<aligner>_<GATK>_<dataset_id>_<sample_id>.bam.bai.sha512 |
Post-processes BAM index SHA512 checksum |
report.html , timeline.html and trace.txt |
Nextflow report, timeline and trace files |
*.command.* |
Process specific logging files created by nextflow |
- Issue tracker to report errors and enhancement ideas.
- Discussions can take place in recalibrate-BAM Discussions
- recalibrate-BAM pull requests are also open for discussion
Update link to repo-specific URL for GitHub Insights Contributors page.
Please see list of Contributors at GitHub.
--
Authors: Yash Patel (YashPatel@mednet.ucla.edu), Shu Tao (shutao@mednet.ucla.edu), Stefan Eng (stefaneng@mednet.ucla.edu)
Recalibrate-BAM is licensed under the GNU General Public License version 2. See the file LICENSE for the terms of the GNU GPL license.
Recalibrate-BAM takes BAM files and utilizes GATK to perform indel realignment and BQSR.
Copyright (C) 2023-2024 University of California Los Angeles ("Boutros Lab") All rights reserved.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.