ACEcall: Categorize and plot subclonal, single, and double gains /...

View source: R/accessory_functions.R

ACEcallR Documentation

Categorize and plot subclonal, single, and double gains / losses

Description

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

Usage

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,
        sgc = c())

Arguments

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"

sgc

Integer or character vector. Specify which chromosomes occur with only a single copy in the germline

Details

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)

Value

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. Output is restricted to the specified chromosomal subset. 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.

Note

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.

Author(s)

Jos B. Poell

See Also

singleplot

Examples

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

tgac-vumc/ACE documentation built on Nov. 29, 2022, 12:15 a.m.