Genome Analysis Toolkit

Variant Discovery in High-Throughput Sequencing Data

GATK process banner

Need Help?

Search our documentation

Community Forum

Hi, How can we help?

Developed in the Data Sciences Platform at the Broad Institute, the toolkit offers a wide variety of tools with a primary focus on variant discovery and genotyping. Its powerful processing engine and high-performance computing features make it capable of taking on projects of any size. Learn more

Articles in this section

See more

PlotDenoisedCopyRatios Follow

Avatar
GATK Team
  • Updated

Creates plots of denoised copy ratios

Category Copy Number Variant Discovery

Overview

Creates plots of standardized and denoised copy ratios. The tool also generates various denoising metrics.

Inputs

  • Standardized-copy-ratios from {@link DenoiseReadCounts}.
  • Denoised-copy-ratios from {@link DenoiseReadCounts}.
  • Sequence-dictionary file. This determines the order and representation of contigs in the plot.
  • Output prefix. This is used as the basename for output files.
  • Output directory. This will be created if it does not exist.

Outputs

  • Denoised-plot file. A plot showing both the standardized and denoised copy ratios is output. Copy ratios are only plotted up to the maximum value specified by the argument {@code maximum-copy-ratio}. Point size can be specified by the argument {@code point-size-copy-ratio}.
  • Median-absolute-deviation files. These files contain the median absolute deviation (MAD) for both the standardized (.standardizedMAD.txt) and denoised (.denoisedMAD.txt) copy ratios, the change between the two (.deltaMAD.txt), and the change between the two scaled by the standardized MAD (.deltaScaledMAD.txt).

Usage examples

     gatk PlotDenoisedCopyRatios \
          --standardized-copy-ratios tumor.standardizedCR.tsv \
          --denoised-copy-ratios tumor.denoisedCR.tsv \
          --sequence-dictionary contigs_to_plot.dict \
          --output-prefix tumor \
          -O output_dir
@author Samuel Lee <slee@broadinstitute.org>

PlotDenoisedCopyRatios specific arguments

This table summarizes the command-line arguments that are specific to this tool. For more details on each argument, see the list further down below the table or click on an argument name to jump directly to that entry in the list.

Argument name(s) Default value Summary
Required Arguments
--denoised-copy-ratios
 Input file containing denoised copy ratios (output of DenoiseReadCounts).
--output
 -O 		Output directory. This will be created if it does not exist.
--output-prefix
 Prefix for output filenames.
--sequence-dictionary
 File containing a sequence dictionary, which specifies the contigs to be plotted and their relative lengths. The sequence dictionary must be a subset of those contained in other input files. Contigs will be plotted in the order given. Contig names should not include the string "CONTIG_DELIMITER". The tool only considers contigs in the given dictionary for plotting, and data for contigs absent in the dictionary generate only a warning. In other words, you may modify a reference dictionary for use with this tool to include only contigs for which plotting is desired, and sort the contigs to the order in which the plots should display the contigs.
--standardized-copy-ratios
 Input file containing standardized copy ratios (output of DenoiseReadCounts).
Optional Tool Arguments
--arguments_file
 read one or more arguments files and add them to the command line
--gcs-max-retries
 -gcs-retries 		20 If the GCS bucket channel errors out, how many times it will attempt to re-initiate the connection
--gcs-project-for-requester-pays
 Project to bill when accessing "requester pays" buckets. If unset, these buckets cannot be accessed. User must have storage.buckets.get permission on the bucket being accessed.
--help
 -h 		false display the help message
--maximum-copy-ratio
 4.0 Maximum copy ratio to be plotted. If Infinity, the maximum copy ratio will be automatically determined.
--minimum-contig-length
 1000000 Threshold length (in bp) for contigs to be plotted. Contigs with lengths less than this threshold will not be plotted. This can be used to filter out mitochondrial contigs, unlocalized contigs, etc.
--point-size-copy-ratio
 0.2 Point size to use for plotting copy-ratio points.
--version
 false display the version number for this tool
Optional Common Arguments
--gatk-config-file
 A configuration file to use with the GATK.
--QUIET
 false Whether to suppress job-summary info on System.err.
--tmp-dir
 Temp directory to use.
--use-jdk-deflater
 -jdk-deflater 		false Whether to use the JdkDeflater (as opposed to IntelDeflater)
--use-jdk-inflater
 -jdk-inflater 		false Whether to use the JdkInflater (as opposed to IntelInflater)
--verbosity
 INFO Control verbosity of logging.
Advanced Arguments
--showHidden
 false display hidden arguments

Argument details

Arguments in this list are specific to this tool. Keep in mind that other arguments are available that are shared with other tools (e.g. command-line GATK arguments); see Inherited arguments above.

--arguments_file

read one or more arguments files and add them to the command line

List[File]  []

--denoised-copy-ratios

Input file containing denoised copy ratios (output of DenoiseReadCounts).

R File  null

--gatk-config-file

A configuration file to use with the GATK.

String  null

--gcs-max-retries / -gcs-retries

If the GCS bucket channel errors out, how many times it will attempt to re-initiate the connection

int  20  [ [ -∞  ∞ ] ]

--gcs-project-for-requester-pays

Project to bill when accessing "requester pays" buckets. If unset, these buckets cannot be accessed. User must have storage.buckets.get permission on the bucket being accessed.

String  ""

--help / -h

display the help message

boolean  false

--maximum-copy-ratio

Maximum copy ratio to be plotted. If Infinity, the maximum copy ratio will be automatically determined.

double  4.0  [ [ 0  ∞ ] ]

--minimum-contig-length

Threshold length (in bp) for contigs to be plotted. Contigs with lengths less than this threshold will not be plotted. This can be used to filter out mitochondrial contigs, unlocalized contigs, etc.

int  1000000  [ [ 0  ∞ ] ]

--output / -O

Output directory. This will be created if it does not exist.

R File  null

--output-prefix

Prefix for output filenames.

R String  null

--point-size-copy-ratio

Point size to use for plotting copy-ratio points.

double  0.2  [ [ 0  ∞ ] ]

--QUIET

Whether to suppress job-summary info on System.err.

Boolean  false

--sequence-dictionary / -sequence-dictionary

File containing a sequence dictionary, which specifies the contigs to be plotted and their relative lengths. The sequence dictionary must be a subset of those contained in other input files. Contigs will be plotted in the order given. Contig names should not include the string "CONTIG_DELIMITER". The tool only considers contigs in the given dictionary for plotting, and data for contigs absent in the dictionary generate only a warning. In other words, you may modify a reference dictionary for use with this tool to include only contigs for which plotting is desired, and sort the contigs to the order in which the plots should display the contigs.

R File  null

--showHidden / -showHidden

display hidden arguments

boolean  false

--standardized-copy-ratios

Input file containing standardized copy ratios (output of DenoiseReadCounts).

R File  null

--tmp-dir

Temp directory to use.

GATKPath  null

--use-jdk-deflater / -jdk-deflater

Whether to use the JdkDeflater (as opposed to IntelDeflater)

boolean  false

--use-jdk-inflater / -jdk-inflater

Whether to use the JdkInflater (as opposed to IntelInflater)

boolean  false

--verbosity / -verbosity

Control verbosity of logging.

The --verbosity argument is an enumerated type (LogLevel), which can have one of the following values:

ERROR
WARNING
INFO
DEBUG

LogLevel  INFO

--version

display the version number for this tool

boolean  false

Return to top

GATK version 4.4.0.0 built at Thu, 16 Mar 2023 15:00:37 -0400.

Related articles

1 comment

Sort by Date Votes
  • Avatar
    PML Research
    • Edited

    Dear Team,

    Thank you for the tutorial.

    I am trying to use PlotDenoisedCopyRatios however i am unable to plot the CNVs and gives the following error. I have tried updating my dict file and also updated my R packages as well but still I am getting this error. of course i cannot update my paths if --args is too long for it.

    ##############################################################################

    14:36:57.877 INFO  NativeLibraryLoader - Loading libgkl_compression.so from jar:file:/media/pmlab/PML-Drive/Tools_DB/gatk-4.5.0.0/gatk-package-4.5.0.0.jar!/com/intel/gkl/native/libgkl_compression.so
    14:36:58.202 INFO  PlotDenoisedCopyRatios - ------------------------------------------------------------
    14:36:58.205 INFO  PlotDenoisedCopyRatios - The Genome Analysis Toolkit (GATK) v4.5.0.0
    14:36:58.205 INFO  PlotDenoisedCopyRatios - For support and documentation go to https://software.broadinstitute.org/gatk/
    14:36:58.206 INFO  PlotDenoisedCopyRatios - Executing as pmlab@pmlab-HP-Z8-G4-Workstation on Linux v6.5.0-15-generic amd64
    14:36:58.206 INFO  PlotDenoisedCopyRatios - Java runtime: OpenJDK 64-Bit Server VM v19.0.2+7-Ubuntu-0ubuntu322.04
    14:36:58.206 INFO  PlotDenoisedCopyRatios - Start Date/Time: February 1, 2024 at 2:36:57 PM PKT
    14:36:58.206 INFO  PlotDenoisedCopyRatios - ------------------------------------------------------------
    14:36:58.206 INFO  PlotDenoisedCopyRatios - ------------------------------------------------------------
    14:36:58.207 INFO  PlotDenoisedCopyRatios - HTSJDK Version: 4.1.0
    14:36:58.207 INFO  PlotDenoisedCopyRatios - Picard Version: 3.1.1
    14:36:58.207 INFO  PlotDenoisedCopyRatios - Built for Spark Version: 3.5.0
    14:36:58.207 INFO  PlotDenoisedCopyRatios - HTSJDK Defaults.COMPRESSION_LEVEL : 2
    14:36:58.207 INFO  PlotDenoisedCopyRatios - HTSJDK Defaults.USE_ASYNC_IO_READ_FOR_SAMTOOLS : false
    14:36:58.207 INFO  PlotDenoisedCopyRatios - HTSJDK Defaults.USE_ASYNC_IO_WRITE_FOR_SAMTOOLS : true
    14:36:58.207 INFO  PlotDenoisedCopyRatios - HTSJDK Defaults.USE_ASYNC_IO_WRITE_FOR_TRIBBLE : false
    14:36:58.207 INFO  PlotDenoisedCopyRatios - Deflater: IntelDeflater
    14:36:58.208 INFO  PlotDenoisedCopyRatios - Inflater: IntelInflater
    14:36:58.208 INFO  PlotDenoisedCopyRatios - GCS max retries/reopens: 20
    14:36:58.208 INFO  PlotDenoisedCopyRatios - Requester pays: disabled
    14:36:58.208 INFO  PlotDenoisedCopyRatios - Initializing engine
    14:36:58.208 INFO  PlotDenoisedCopyRatios - Done initializing engine
    14:36:58.209 INFO  PlotDenoisedCopyRatios - Reading and validating input files...
    14:36:59.233 INFO  PlotDenoisedCopyRatios - Contigs above length threshold: {chr1=248956422, chr2=242193529, chr3=198295559, chr4=190214555, chr5=181538259, chr6=170805979, chr7=159345973, chr8=145138636, chr9=138394717, chr10=133797422, chr11=135086622, chr12=133275309, chr13=114364328, chr14=107043718, chr15=101991189, chr16=90338345, chr17=83257441, chr18=80373285, chr19=58617616, chr20=64444167, chr21=46709983, chr22=50818468, chrX=156040895, chrY=57227415}
    14:36:59.325 INFO  PlotDenoisedCopyRatios - Writing plots to /media/pmlab/PML-Drive/OSCC/mock/Whole_exomes/HNSCC1/analysis_ready_bams/somatic_cnv/A2-61/tumor_cnv/DenoisedCopyRatioPlots...
    14:36:59.605 INFO  PlotDenoisedCopyRatios - Shutting down engine
    [February 1, 2024 at 2:36:59 PM PKT] org.broadinstitute.hellbender.tools.copynumber.plotting.PlotDenoisedCopyRatios done. Elapsed time: 0.03 minutes.
    Runtime.totalMemory()=629145600
    org.broadinstitute.hellbender.utils.R.RScriptExecutorException: 
    Rscript exited with 1
    Command Line: Rscript -e tempLibDir = '/tmp/Rlib.2631689807040578510';source('/tmp/CNVPlottingLibrary.7944090931043981279.R');source('/tmp/PlotDenoisedCopyRatios.207901167559333423.R'); --args --sample_name=A2-61-T --standardized_copy_ratios_file=/media/pmlab/PML-Drive/OSCC/mock/Whole_exomes/HNSCC1/analysis_ready_bams/somatic_cnv/A2-61/tumor_cnv/DenoiseReadCounts/A2-61-T.standardizedCR.tsv --denoised_copy_ratios_file=/media/pmlab/PML-Drive/OSCC/mock/Whole_exomes/HNSCC1/analysis_ready_bams/somatic_cnv/A2-61/tumor_cnv/DenoiseReadCounts/A2-61-T.denoisedCR.tsv --contig_names=chr1CONTIG_DELIMITERchr2CONTIG_DELIMITERchr3CONTIG_DELIMITERchr4CONTIG_DELIMITERchr5CONTIG_DELIMITERchr6CONTIG_DELIMITERchr7CONTIG_DELIMITERchr8CONTIG_DELIMITERchr9CONTIG_DELIMITERchr10CONTIG_DELIMITERchr11CONTIG_DELIMITERchr12CONTIG_DELIMITERchr13CONTIG_DELIMITERchr14CONTIG_DELIMITERchr15CONTIG_DELIMITERchr16CONTIG_DELIMITERchr17CONTIG_DELIMITERchr18CONTIG_DELIMITERchr19CONTIG_DELIMITERchr20CONTIG_DELIMITERchr21CONTIG_DELIMITERchr22CONTIG_DELIMITERchrXCONTIG_DELIMITERchrY --contig_lengths=248956422CONTIG_DELIMITER242193529CONTIG_DELIMITER198295559CONTIG_DELIMITER190214555CONTIG_DELIMITER181538259CONTIG_DELIMITER170805979CONTIG_DELIMITER159345973CONTIG_DELIMITER145138636CONTIG_DELIMITER138394717CONTIG_DELIMITER133797422CONTIG_DELIMITER135086622CONTIG_DELIMITER133275309CONTIG_DELIMITER114364328CONTIG_DELIMITER107043718CONTIG_DELIMITER101991189CONTIG_DELIMITER90338345CONTIG_DELIMITER83257441CONTIG_DELIMITER80373285CONTIG_DELIMITER58617616CONTIG_DELIMITER64444167CONTIG_DELIMITER46709983CONTIG_DELIMITER50818468CONTIG_DELIMITER156040895CONTIG_DELIMITER57227415 --maximum_copy_ratio=4.0 --point_size_copy_ratio=0.2 --output_dir=/media/pmlab/PML-Drive/OSCC/mock/Whole_exomes/HNSCC1/analysis_ready_bams/somatic_cnv/A2-61/tumor_cnv/DenoisedCopyRatioPlots/ --output_prefix=A2-61-T
    Stdout: 
    Stderr: Usage: %prog [options]


    NA: error: Error in getopt(spec = spec, opt = args) : long flag "args" is invalid

     


     at org.broadinstitute.hellbender.utils.R.RScriptExecutor.getScriptException(RScriptExecutor.java:79)
     at org.broadinstitute.hellbender.utils.R.RScriptExecutor.getScriptException(RScriptExecutor.java:18)
     at org.broadinstitute.hellbender.utils.runtime.ScriptExecutor.executeCuratedArgs(ScriptExecutor.java:112)
     at org.broadinstitute.hellbender.utils.R.RScriptExecutor.exec(RScriptExecutor.java:125)
     at org.broadinstitute.hellbender.tools.copynumber.plotting.PlotDenoisedCopyRatios.writeDenoisingPlots(PlotDenoisedCopyRatios.java:218)
     at org.broadinstitute.hellbender.tools.copynumber.plotting.PlotDenoisedCopyRatios.doWork(PlotDenoisedCopyRatios.java:174)
     at org.broadinstitute.hellbender.cmdline.CommandLineProgram.runTool(CommandLineProgram.java:149)
     at org.broadinstitute.hellbender.cmdline.CommandLineProgram.instanceMainPostParseArgs(CommandLineProgram.java:198)
     at org.broadinstitute.hellbender.cmdline.CommandLineProgram.instanceMain(CommandLineProgram.java:217)
     at org.broadinstitute.hellbender.Main.runCommandLineProgram(Main.java:166)
     at org.broadinstitute.hellbender.Main.mainEntry(Main.java:209)
     at org.broadinstitute.hellbender.Main.main(Main.java:306)

    ##############################################################

    Can I submit a custom R script to PlotDenoisedCopyRatios?

    0
    Comment actions Permalink

Please sign in to leave a comment.

Powered by Zendesk