ModelSegments

Models segmented copy ratios from denoised copy ratios and segmented minor-allele fractions from allelic counts

Category Copy Number Variant Discovery

Overview

Models segmented copy ratios from denoised copy ratios and segmented minor-allele fractions from allelic counts.

Possible data inputs are: 1) denoised copy ratios for the case sample, 2) allelic counts for the case sample, and 3) allelic counts for a matched-normal sample. All available inputs will be used to to perform segmentation and model inference.

Genotyping step

If allelic counts are available, the first step in the inference process is to genotype heterozygous sites, as the allelic counts at these sites will subsequently be modeled to infer segmented minor-allele fraction. We perform a relatively simple and naive genotyping based on the allele counts (i.e., pileups), which is controlled by a small number of parameters ({@code minimum-total-allele-count}, {@code genotyping-homozygous-log-ratio-threshold}, and {@code genotyping-homozygous-log-ratio-threshold}). If the matched normal is available, its allelic counts will be used to genotype the sites, and we will simply assume these genotypes are the same in the case sample. (This can be critical, for example, for determining sites with loss of heterozygosity in high purity case samples; such sites will be genotyped as homozygous if the matched-normal sample is not available.)

Segmentation step

Next, we segment, if available, the denoised copy ratios and the alternate-allele fractions at the genotyped heterozygous sites. This is done using kernel segmentation (see {@link KernelSegmenter}). Various segmentation parameters control the sensitivity of the segmentation and should be selected appropriately for each analysis. If a Picard interval-list file has been specified by the {@code segments} argument, the corresponding segmentation will be used instead and this step will be skipped.

If both copy ratios and allele fractions are available, we perform segmentation using a combined kernel that is sensitive to changes that occur not only in either of the two but also in both. However, in this case, we simply discard all allele fractions at sites that lie outside of the available copy-ratio intervals (rather than imputing the missing copy-ratio data); these sites are filtered out during the genotyping step discussed above. This can have implications for analyses involving the sex chromosomes; see comments in {@link CreateReadCountPanelOfNormals}.

Modeling step

After segmentation is complete, we run Markov-chain Monte Carlo (MCMC) to determine posteriors for segmented models for the log2 copy ratio and the minor-allele fraction; see {@link CopyRatioModeller} and {@link AlleleFractionModeller}, respectively. After the first run of MCMC is complete, smoothing of the segmented posteriors is performed by merging adjacent segments whose posterior credible intervals sufficiently overlap according to specified segmentation-smoothing parameters. Then, additional rounds of segmentation smoothing (with intermediate MCMC optionally performed in between rounds) are performed until convergence, at which point a final round of MCMC is performed.

Inputs

(Optional) Denoised-copy-ratios file from {@link DenoiseReadCounts}. If allelic counts are not provided, then this is required.
(Optional) Allelic-counts file from {@link CollectAllelicCounts}. If denoised copy ratios are not provided, then this is required.
(Optional) Matched-normal allelic-counts file from {@link CollectAllelicCounts}. This can only be provided if allelic counts for the case sample are also provided.
(Optional, Advanced) Picard interval-list file containing a multisample segmentation output by a previous run of {@link ModelSegments} in multisample mode. Segmentation step will not be performed. See description of multisample mode below.
Output prefix. This is used as the basename for output files.
Output directory. This will be created if it does not exist.

Outputs

Modeled-segments .modelBegin.seg and .modelFinal.seg files. These are tab-separated values (TSV) files with a SAM-style header containing a read group sample name, a sequence dictionary, a row specifying the column headers contained in {@link ModeledSegmentCollection.ModeledSegmentTableColumn}, and the corresponding entry rows. The initial result before segmentation smoothing is output to the .modelBegin.seg file and the final result after segmentation smoothing is output to the .modelFinal.seg file.
Allele-fraction-model global-parameter files (.modelBegin.af.param and .modelFinal.af.param). These are tab-separated values (TSV) files with a SAM-style header containing a read group sample name, a row specifying the column headers contained in {@link ParameterDecileCollection.ParameterTableColumn}, and the corresponding entry rows. The initial result before segmentation smoothing is output to the .modelBegin.af.param file and the final result after segmentation smoothing is output to the .modelFinal.af.param file.
Copy-ratio-model global-parameter files (.modelBegin.cr.param and .modelFinal.cr.param). These are tab-separated values (TSV) files with a SAM-style header containing a read group sample name, a row specifying the column headers contained in {@link ParameterDecileCollection.ParameterTableColumn}, and the corresponding entry rows. The initial result before segmentation smoothing is output to the .modelBegin.cr.param file and the final result after segmentation smoothing is output to the .modelFinal.cr.param file.
Copy-ratio segments file (.cr.seg). This is a tab-separated values (TSV) file with a SAM-style header containing a read group sample name, a sequence dictionary, a row specifying the column headers contained in {@link CopyRatioSegmentCollection.CopyRatioSegmentTableColumn}, and the corresponding entry rows. It contains the segments from the .modelFinal.seg file converted to a format suitable for input to {@link CallCopyRatioSegments}.
CBS-formatted .cr.igv.seg and .af.igv.seg files (compatible with IGV). These are tab-separated values (TSV) files with CBS-format column headers (see http://software.broadinstitute.org/cancer/software/genepattern/file-formats-guide#CBS) and the corresponding entry rows that can be plotted using IGV (see https://software.broadinstitute.org/software/igv/SEG). The posterior medians of the log2 copy ratio and minor-allele fraction are given in the SEGMENT_MEAN columns in the .cr.igv.seg and .af.igv.seg files, respectively.
(Optional) Allelic-counts file containing the counts at sites genotyped as heterozygous in the case sample (.hets.tsv). This is a tab-separated values (TSV) file with a SAM-style header containing a read group sample name, a sequence dictionary, a row specifying the column headers contained in {@link AllelicCountCollection.AllelicCountTableColumn}, and the corresponding entry rows. This is only output if allelic counts are provided as input.
(Optional) Allelic-counts file containing the counts at sites genotyped as heterozygous in the matched-normal sample (.hets.normal.tsv). This is a tab-separated values (TSV) file with a SAM-style header containing a read group sample name, a sequence dictionary, a row specifying the column headers contained in {@link AllelicCountCollection.AllelicCountTableColumn}, and the corresponding entry rows. This is only output if matched-normal allelic counts are provided as input.

Usage examples

     gatk ModelSegments \
          --denoised-copy-ratios tumor.denoisedCR.tsv \
          --allelic-counts tumor.allelicCounts.tsv \
          --normal-allelic-counts normal.allelicCounts.tsv \
          --output-prefix tumor \
          -O output_dir

     gatk ModelSegments \
          --denoised-copy-ratios normal.denoisedCR.tsv \
          --allelic-counts normal.allelicCounts.tsv \
          --output-prefix normal \
          -O output_dir

     gatk ModelSegments \
          --allelic-counts tumor.allelicCounts.tsv \
          --normal-allelic-counts normal.allelicCounts.tsv \
          --output-prefix tumor \
          -O output_dir

     gatk ModelSegments \
          --denoised-copy-ratios normal.denoisedCR.tsv \
          --output-prefix normal \
          -O output_dir

     gatk ModelSegments \
          --allelic-counts tumor.allelicCounts.tsv \
          --output-prefix tumor \
          -O output_dir

Multisample Mode (ADVANCED / EXPERIMENTAL)

Multisample mode is activated when inputs for more than one case sample are specified via the {@code denoised-copy-ratios} and/or {@code allelic-counts} arguments. In this mode, {@link ModelSegments} finds common segments across multiple case samples using denoised copy ratios and allelic counts. This segmentation can be used as input to subsequent, individual runs of {@link ModelSegments} on each of the case samples.

Possible data inputs are: 1) denoised copy ratios for the case samples, 2) allelic counts for the case samples, and 3) allelic counts for a matched-normal sample. All available inputs will be used to to perform segmentation.

As in single-sample mode, the first step is to genotype heterozygous sites. If allelic counts from a matched normal are available, heterozygous sites in all samples are defined using the normal, as usual; otherwise, each case sample is genotyped individually. The intersection of heterozygous sites across case samples after filtering on total count and overlap with available copy-ratio intervals is then used for segmentation. (When the matched normal is available, this intersection is inconsequential if {@code minimum-total-allele-count-case} is appropriately set to zero. As in single-sample mode, determining sites with loss of heterozygosity in high purity case samples will be difficult if the matched normal is not available.)

Next, we jointly segment, if available, the denoised copy ratios and the alternate-allele fractions at the genotyped heterozygous sites across all case samples (which can include the matched normal, if desired). The same caveats discussed above also apply to segmentation in multisample mode; as in single-sample mode, segmentation parameters should be tuned appropriately for each analysis. Moreover, parameters may also need to be tuned as a function of the number of samples used.

The final output of multisample mode is a Picard interval-list file specifying the joint segmentation. This can be provided to subsequent, individual runs of {@link ModelSegments} via the {@code segments} argument to perform modeling for each of the case samples; the segmentation step will be skipped in these runs.

Note that the genotyping step will be repeated in these runs, so filters identical to those used in the multisample-mode run should be used. If allelic counts from a matched normal are available, the resulting set of heterozygous sites used for modeling in these runs should then be identical to that used for segmentation in the multisample-mode run if {@code minimum-total-allele-count-case} is appropriately set to zero for all runs. (However, if this is set to a non-zero value or if no matched normal is available, because the intersection of heterozygous sites across samples performed in the multisample-mode run cannot be replicated in the single-sample mode runs, this may ultimately yield sets of sites for modeling that differ across samples.)

See below for usage examples illustrating a run in multisample mode followed by multiple runs in single-sample mode.

Inputs

(Optional) List of more than one denoised-copy-ratios files from {@link DenoiseReadCounts}. If a list of allelic counts is not provided, then this is required. If a list of allelic counts is also provided, then sample order must match across both lists.
(Optional) List of more than one allelic-counts files from {@link CollectAllelicCounts}. If a list of denoised copy ratios is not provided, then this is required. If a list of denoised copy ratios is also provided, then sample order must match across both lists.
(Optional) Matched-normal allelic-counts file from {@link CollectAllelicCounts}. This can only be provided if a list of allelic counts for the case samples are also provided.

Outputs

Multisample-segments .interval_list Picard interval-list file. This segmentation can be used as input to subsequent, individual runs of {@link ModelSegments} on each of the case samples.

Usage examples

Multisample-mode run (outputs {@code multisample-segmentation.interval_list} containing the multisample segmentation)

     gatk ModelSegments \
          --denoised-copy-ratios normal.denoisedCR.tsv \
          --denoised-copy-ratios tumor-1.denoisedCR.tsv \
          ...
          --denoised-copy-ratios tumor-N.denoisedCR.tsv \
          --allelic-counts normal.allelicCounts.tsv \
          --allelic-counts tumor-1.allelicCounts.tsv \
          ...
          --allelic-counts tumor-N.allelicCounts.tsv \
          --normal-allelic-counts normal.allelicCounts.tsv \
          --output-prefix multisample-segmentation
          -O output_dir

Single-sample mode runs (segmentation is taken from {@code multisample-segmentation.interval_list}, so the segmentation step is skipped in each run)

     gatk ModelSegments \
          --segments multisample-segmentation.interval_list
          --denoised-copy-ratios normal.denoisedCR.tsv \
          --allelic-counts normal.allelicCounts.tsv \
          --normal-allelic-counts normal.allelicCounts.tsv \
          --output-prefix normal
          -O output_dir

     gatk ModelSegments \
          --segments multisample-segmentation.interval_list
          --denoised-copy-ratios tumor-1.denoisedCR.tsv \
          --allelic-counts tumor-1.allelicCounts.tsv \
          --normal-allelic-counts normal.allelicCounts.tsv \
          --output-prefix tumor-1
          -O output_dir

...

     gatk ModelSegments \
          --segments multisample-segmentation.interval_list
          --denoised-copy-ratios tumor-N.denoisedCR.tsv \
          --allelic-counts tumor-N.allelicCounts.tsv \
          --normal-allelic-counts normal.allelicCounts.tsv \
          --output-prefix tumor-N
          -O output_dir

@author Samuel Lee <slee@broadinstitute.org>

ModelSegments 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
--output -O		Output directory. This will be created if it does not exist.
--output-prefix		Prefix for output filenames.
Optional Tool Arguments
--allelic-counts		Input files containing allelic counts (output of CollectAllelicCounts). If multiple samples are specified, multisample kernel segmentation will be performed but modeling will be skipped; sample order must match that of input denoised-copy-ratios files.
--arguments_file		read one or more arguments files and add them to the command line
--denoised-copy-ratios		Input files containing denoised copy ratios (output of DenoiseReadCounts). If multiple samples are specified, multisample kernel segmentation will be performed but modeling will be skipped; sample order must match that of input allelic-counts files.
--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.
--genotyping-base-error-rate	0.05	Maximum base-error rate for genotyping and filtering homozygous allelic counts, if available. The likelihood for an allelic count to be generated from a homozygous site will be integrated from zero base-error rate up to this value. Decreasing this value will increase the number of sites assumed to be heterozygous for modeling.
--genotyping-homozygous-log-ratio-threshold	-10.0	Log-ratio threshold for genotyping and filtering homozygous allelic counts, if available. Increasing this value will increase the number of sites assumed to be heterozygous for modeling.
--help -h	false	display the help message
--kernel-approximation-dimension	100	Dimension of the kernel approximation. A subsample containing this number of data points will be used to construct the approximation for each chromosome. If the total number of data points in a chromosome is greater than this number, then all data points in the chromosome will be used. Time complexity scales quadratically and space complexity scales linearly with this parameter.
--kernel-scaling-allele-fraction	1.0	Relative scaling S of the kernel K_AF for allele-fraction segmentation to the kernel K_CR for copy-ratio segmentation. If multidimensional segmentation is performed, the total kernel used will be K_CR + S * K_AF.
--kernel-variance-allele-fraction	0.025	Variance of Gaussian kernel for allele-fraction segmentation, if performed. If zero, a linear kernel will be used.
--kernel-variance-copy-ratio	0.0	Variance of Gaussian kernel for copy-ratio segmentation, if performed. If zero, a linear kernel will be used.
--maximum-number-of-segments-per-chromosome	1000	Maximum number of segments allowed per chromosome.
--maximum-number-of-smoothing-iterations	25	Maximum number of iterations allowed for segmentation smoothing.
--minimum-total-allele-count-case	0	Minimum total count for filtering allelic counts in the case sample, if available. The default value of zero is appropriate for matched-normal mode; increase to an appropriate value for case-only mode.
--minimum-total-allele-count-normal	30	Minimum total count for filtering allelic counts in the matched-normal sample, if available.
--minor-allele-fraction-prior-alpha	25.0	Alpha hyperparameter for the 4-parameter beta-distribution prior on segment minor-allele fraction. The prior for the minor-allele fraction f in each segment is assumed to be Beta(alpha, 1, 0, 1/2). Increasing this hyperparameter will reduce the effect of reference bias at the expense of sensitivity.
--normal-allelic-counts		Input file containing allelic counts for a matched normal (output of CollectAllelicCounts). If specified, these allelic counts will be used to perform genotyping but will not be used for multisample kernel segmentation; if the latter is desired, additionally specify this file as one of the arguments to --allelic-counts.
--number-of-burn-in-samples-allele-fraction	50	Number of burn-in samples to discard for allele-fraction model.
--number-of-burn-in-samples-copy-ratio	50	Number of burn-in samples to discard for copy-ratio model.
--number-of-changepoints-penalty-factor	1.0	Factor A for the penalty on the number of changepoints per chromosome for segmentation. Adds a penalty of the form A * C * [1 + log (N / C)], where C is the number of changepoints in the chromosome and N is the number of data points in the chromosome, to the cost function for each chromosome. Must be non-negative.
--number-of-samples-allele-fraction	100	Total number of MCMC samples for allele-fraction model.
--number-of-samples-copy-ratio	100	Total number of MCMC samples for copy-ratio model.
--number-of-smoothing-iterations-per-fit	0	Number of segmentation-smoothing iterations per MCMC model refit. (Increasing this will decrease runtime, but the final number of segments may be higher. Setting this to 0 will completely disable model refitting between iterations.)
--smoothing-credible-interval-threshold-allele-fraction	2.0	Number of 10% equal-tailed credible-interval widths to use for allele-fraction segmentation smoothing.
--smoothing-credible-interval-threshold-copy-ratio	2.0	Number of 10% equal-tailed credible-interval widths to use for copy-ratio segmentation smoothing.
--version	false	display the version number for this tool
--window-size	[8, 16, 32, 64, 128, 256]	Window sizes to use for calculating local changepoint costs. For each window size, the cost for each data point to be a changepoint will be calculated assuming that the point demarcates two adjacent segments of that size. Including small (large) window sizes will increase sensitivity to small (large) events. Duplicate values will be ignored.
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
--segments		Input Picard interval-list file specifying segments. If provided, kernel segmentation will be skipped.
--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.

--allelic-counts

Input files containing allelic counts (output of CollectAllelicCounts). If multiple samples are specified, multisample kernel segmentation will be performed but modeling will be skipped; sample order must match that of input denoised-copy-ratios files.

List[File] []

--arguments_file

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

List[File] []

--denoised-copy-ratios

Input files containing denoised copy ratios (output of DenoiseReadCounts). If multiple samples are specified, multisample kernel segmentation will be performed but modeling will be skipped; sample order must match that of input allelic-counts files.

List[File] []

--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 ""

--genotyping-base-error-rate

Maximum base-error rate for genotyping and filtering homozygous allelic counts, if available. The likelihood for an allelic count to be generated from a homozygous site will be integrated from zero base-error rate up to this value. Decreasing this value will increase the number of sites assumed to be heterozygous for modeling.

double 0.05 [ [ 0 1 ] ]

--genotyping-homozygous-log-ratio-threshold

Log-ratio threshold for genotyping and filtering homozygous allelic counts, if available. Increasing this value will increase the number of sites assumed to be heterozygous for modeling.

double -10.0 [ [ -∞ ∞ ] ]

--help / -h

display the help message

boolean false

--kernel-approximation-dimension

Dimension of the kernel approximation. A subsample containing this number of data points will be used to construct the approximation for each chromosome. If the total number of data points in a chromosome is greater than this number, then all data points in the chromosome will be used. Time complexity scales quadratically and space complexity scales linearly with this parameter.

int 100 [ [ 1 ∞ ] ]

--kernel-scaling-allele-fraction

Relative scaling S of the kernel K_AF for allele-fraction segmentation to the kernel K_CR for copy-ratio segmentation. If multidimensional segmentation is performed, the total kernel used will be K_CR + S * K_AF.

double 1.0 [ [ 0 ∞ ] ]

--kernel-variance-allele-fraction

Variance of Gaussian kernel for allele-fraction segmentation, if performed. If zero, a linear kernel will be used.

double 0.025 [ [ 0 ∞ ] ]

--kernel-variance-copy-ratio

Variance of Gaussian kernel for copy-ratio segmentation, if performed. If zero, a linear kernel will be used.

double 0.0 [ [ 0 ∞ ] ]

--maximum-number-of-segments-per-chromosome

Maximum number of segments allowed per chromosome.

int 1000 [ [ 1 ∞ ] ]

--maximum-number-of-smoothing-iterations

Maximum number of iterations allowed for segmentation smoothing.

int 25 [ [ 0 ∞ ] ]

--minimum-total-allele-count-case

Minimum total count for filtering allelic counts in the case sample, if available. The default value of zero is appropriate for matched-normal mode; increase to an appropriate value for case-only mode.

int 0 [ [ 0 ∞ ] ]

--minimum-total-allele-count-normal

Minimum total count for filtering allelic counts in the matched-normal sample, if available.

int 30 [ [ 0 ∞ ] ]

--minor-allele-fraction-prior-alpha

Alpha hyperparameter for the 4-parameter beta-distribution prior on segment minor-allele fraction. The prior for the minor-allele fraction f in each segment is assumed to be Beta(alpha, 1, 0, 1/2). Increasing this hyperparameter will reduce the effect of reference bias at the expense of sensitivity.

double 25.0 [ [ 1 ∞ ] ]

--normal-allelic-counts

Input file containing allelic counts for a matched normal (output of CollectAllelicCounts). If specified, these allelic counts will be used to perform genotyping but will not be used for multisample kernel segmentation; if the latter is desired, additionally specify this file as one of the arguments to --allelic-counts.

File null

--number-of-burn-in-samples-allele-fraction

Number of burn-in samples to discard for allele-fraction model.

int 50 [ [ 0 ∞ ] ]

--number-of-burn-in-samples-copy-ratio

Number of burn-in samples to discard for copy-ratio model.

int 50 [ [ 0 ∞ ] ]

--number-of-changepoints-penalty-factor

Factor A for the penalty on the number of changepoints per chromosome for segmentation. Adds a penalty of the form A * C * [1 + log (N / C)], where C is the number of changepoints in the chromosome and N is the number of data points in the chromosome, to the cost function for each chromosome. Must be non-negative.

double 1.0 [ [ 0 ∞ ] ]

--number-of-samples-allele-fraction

Total number of MCMC samples for allele-fraction model.

int 100 [ [ 1 ∞ ] ]

--number-of-samples-copy-ratio

Total number of MCMC samples for copy-ratio model.

int 100 [ [ 1 ∞ ] ]

--number-of-smoothing-iterations-per-fit

Number of segmentation-smoothing iterations per MCMC model refit. (Increasing this will decrease runtime, but the final number of segments may be higher. Setting this to 0 will completely disable model refitting between iterations.)

int 0 [ [ 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

--QUIET

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

Boolean false

--segments

Input Picard interval-list file specifying segments. If provided, kernel segmentation will be skipped.

File null

--showHidden / -showHidden

display hidden arguments

boolean false

--smoothing-credible-interval-threshold-allele-fraction

Number of 10% equal-tailed credible-interval widths to use for allele-fraction segmentation smoothing.

double 2.0 [ [ 0 ∞ ] ]

--smoothing-credible-interval-threshold-copy-ratio

Number of 10% equal-tailed credible-interval widths to use for copy-ratio segmentation smoothing.

double 2.0 [ [ 0 ∞ ] ]

--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

--window-size

Window sizes to use for calculating local changepoint costs. For each window size, the cost for each data point to be a changepoint will be calculated assuming that the point demarcates two adjacent segments of that size. Including small (large) window sizes will increase sensitivity to small (large) events. Duplicate values will be ignored.

List[Integer] [8, 16, 32, 64, 128, 256]

Return to top

GATK version 4.6.2.0 built at Sun, 13 Apr 2025 13:21:43 -0400.