ACEcall: Categorize and plot subclonal, single, and double gains /...
In ACE: Absolute Copy Number Estimation from Low-coverage Whole Genome Sequencing

Description Usage Arguments Details Value Note Author(s) See Also Examples

ACEcall is the calling algorithm for ACE that utilizes the absolute copy number scaling to distinguish subclonal, single, and double losses and gains. For a segment to be "called", its segment mean needs to deviate from the general tumor ploidy both based on statistical significance and a large enough difference (both parameters can be set by the user).

ACEcall(template, QDNAseqobjectsample = FALSE, cellularity = 1, 
        ploidy = 2, standard, plot = TRUE, title, pcutoff, 
        qcutoff = -3, subcutoff = 0.2, trncname = FALSE, 
        cap = 12, bottom = 0, chrsubset, onlyautosomes = TRUE)

`template`	Object. Either a data frame as created by `objectsampletotemplate`, or a QDNAseq-object
`QDNAseqobjectsample`	Integer. Specifies which sample to analyze from the QDNAseq-object. Required when using a QDNAseq-object as template. Default = FALSE
`cellularity`	Numeric. Used for rescaling bin and segment values. Printed on graph. Default = 1
`ploidy`	Integer. Assume the median of segments has this absolute copy number. Default = 2
`standard`	Numeric. Forces the given ploidy to represent this raw value. When omitted, the standard will be calculated from the data. When using parameters obtained from `squaremodel`, specify standard = 1
`plot`	Logical. Specifies whether the plot is created. When FALSE, only the data frame will be returned. Default = TRUE
`title`	Character string. Overwrites the automatically generated title
`pcutoff`	Numeric. Specifies the cutoff for statistical significance, without multiple testing correction, required to call a segment. Provide the desired log10-transformed p-value cutoff. When omitted (default), the q-value cutoff will be used instead.
`qcutoff`	Numeric. Specifies the cutoff for statistical significance, with multiple testing correction, required to call a segment. Provide the desired log10-transformed q-value cutoff. Default = -3
`subcutoff`	Numeric. Specifies the difference from the general tumor ploidy required to call a segment. Also used as margin for the other calls. Default = 0.2
`trncname`	Logical. In case of a QDNAseq object, the name of the sample is retrieved from the object and used as title. If set to TRUE, `trncname` truncates the sample name from the first instance of "_" in the name. You can also specify the regular expression here, e.g. trncname = "-.*" truncates the name from the first dash. Default = FALSE
`cap`	Integer. Influences your output copy number graphs. The upper limit of the y-axis is set at this number. When set to "max", it sets the cap to the maximum absolute copynumber value, rounded up. Bins and segments that exceed the cap are represented by a special mark. Recommended use between 8 and 16. Default = 12
`bottom`	Integer. Similar to cap, but for the lower limit of the y-axis. When set to "min", it sets the bottom to the minimum absolute copynumber value, rounded down. Bins and segments that subceed the bottom are represented by a special mark. Default = 0
`chrsubset`	Integer vector. Specify the chromosomes you want to plot. It will always take the full range of chromosomes in your subset, so specifying chrsubset = c(4, 8) will give the same plot as chrsubset = 4:8. When using a subset, `ACEcall` will not plot the cellularity and error on the plot.
`onlyautosomes`	Logical or integer. You can fill in an integer to specify how many autosomes your species has. When TRUE, `ACEcall` defaults to 22 (human) autosomes. When FALSE, `ACEcall` will also plot whichever other chromosomes are specified in the template, e.g. "X", "Y", "MT"

The color code in the plot is as follows (in parentheses the call in the data frame):

black - not called (0)
gold - subclonal gain (0.5)
turquoise - subclonal loss (-0.5)
dark orange - single copy gain (1)
blue - single copy loss (-1)
red - double copy gain (2)
dark blue - double copy or full loss (-2)
purple - amplification (3)

ACEcall returns a data frame that is similar to the input template, but it is supplemented with adjusted copy numbers, adjusted segment values, the segment mean and associated standard error, and the log10 p-value and q-value, which signifies the probability that if the true segment mean equals the general tumor ploidy (rounded to an integer), the resulting or a more extreme segment mean would be found. The q-value is the result of a Benjamini-Hochberg correction of the p-value, taking into account all tested segments. If the argument plot = TRUE, ACEcall will also return an absolute copy number plot (a ggplot2-object) with the segments color-coded to specify the calls.

For biological reasons, a segment is called a double loss when it is highly likely that some cells do not harbor a single copy of the segment of interest. Therefore, a segment with exactly one copy in a triploid tumor will be called as a single loss, not a double loss. Note that ACEcall compares segments to integer copy numbers. It therefore needs to round the given ploidy to an integer as well. It uses the round function for this.

Jos B. Poell

singleplot

## simulated data assuming each chromosome comprises 100 bins
s <- jitter(c(1, 1, 0.8, 1.2, rep(1, 5), 1.4, rep(1, 13)), amount = 0)
n <- c(100, 100, 40, 60, rep(100, 5), 100, rep(100, 13))
bin <- 1:2200
chr <- rep(1:22, each = 100)
start <- rep(0:99*1000000+1, 22)
end <- rep(1:100*1000000, 22)
copynumbers <- jitter(rep(s,n), amount = 0.05)
segments <- rep(s, n)
template <- data.frame(bin = bin, chr = chr, start = start, end = end, 
  copynumbers = copynumbers, segments = segments)
ACEcall(template, cellularity = 0.4, title = "sim")
## using segmented data from a QDNAseq-object
data("copyNumbersSegmented")
## for derivations of the parameters for this fit, 
## see documentation on squaremodel
ACEcall(copyNumbersSegmented, QDNAseqobjectsample = 2, 
  cellularity = 0.41, ploidy = 2.08, standard = 1)