segmentByPairedPSCBS: Segment total copy numbers and allele B fractions using the Paired PSCBS method

Description

Segment total copy numbers and allele B fractions using the Paired PSCBS method [1]. This method requires matched normals. This is a low-level segmentation method. It is intended to be applied to one tumor-normal sample at the time.

Usage

## S3 method for class 'default':
segmentByPairedPSCBS(CT, betaT, betaN=NULL, muN=NULL, chromosome=0, x=NULL, alphaTCN=0.009, alphaDH=0.001, undoTCN=Inf, undoDH=Inf, ..., flavor=c("tcn&dh", "tcn,dh", "sqrt(tcn),dh", "sqrt(tcn)&dh"), tbn=TRUE, joinSegments=TRUE, knownSegments=NULL, seed=NULL, verbose=FALSE)

Arguments

A numeric vector of J tumor total copy number (TCN) ratios in [0,+Inf) (due to noi

betaT

A numeric vector of J tumor allele B fractions (BAFs) in [0,1] (due to noise, values may be slightly outside as well) or

betaN

A numeric vector of J matched normal BAFs in [0,1] (due to noise, values may be slightly outside as well) or

muN

An optional numeric vector of J genotype calls in {0,1/2,1} for AA, AB, and BB, respectively, and

chromosome

(Optional) An integer scalar (or a vector of length J), which can be used to specify which chromosome each locus belongs to in case

Optional numeric vector of J genomic locations. If NULL, index locations 1:J

alphaTCN, alphaDH

The significance levels for segmenting total copy numbers (TCNs) and decrease-in-heterozygosity signals (DHs), respectively.

undoTCN, undoDH

Non-negative numerics. If less than +Inf, then a cleanup of segmentions post segmentation is done. See argument undo

...

Additional arguments passed to segmentByCBS().

flavor

A character specifying what type of segmentation and
     calling algorithm to be used.

tbn

If TRUE, betaT is normalized before segmentation
     using the TumorBoost method [2], otherwise not.

joinSegments

If TRUE, there are no gaps between neighboring
     segments.
     If FALSE, the boundaries of a segment are defined by the support

knownSegments

Optional data.frame specifying
     non-overlapping known segments.  These segments must
     not share loci.  See findLargeGaps() an

seed

An (optional) integer specifying the random seed to be
     set before calling the segmentation method.  The random seed is
     set to its original state when exiting.  If

verbose

See Verbose.

`Value`

Returns the segmentation results as a PairedPSCBS object.

`Reproducibility`

The "DNAcopy::segment" implementation of CBS uses approximation
   through random sampling for some estimates.  Because of this,
   repeated calls using the same signals may result in slightly
   different results, unless the random seed is set/fixed.

`Whole-genome segmentation is preferred`

Although it is possible to segment each chromosome independently
   using Paired PSCBS, we strongly recommend to segment whole-genome
   (TCN,BAF) data at once.  The reason for this is that downstream
   CN-state calling methods, such as the AB and the LOH callers,
   performs much better on whole-genome data.  In fact, they may
   fail to provide valid calls if done chromsome by chromosome.

`Missing and non-finite values`

The total copy number signals as well as any optional positions
   must not contain missing values, i.e. NAs or NaNs.
   If there are any, an informative error is thrown.
   Allele B fractions may contain missing values, because such are
   interpreted as representing non-polymorphic loci.

   None of the input signals may have infinite values, i.e. -Inf or +Inf.
   If so, an informative error is thrown.

`Paired PSCBS with only genotypes`

If allele B fractions for the matched normal (betaN) are
   not available, but genotypes (muN) are, then it is possible
   to run a version of Paired PSCBS where TumorBoost normalization
   of the tumor allele B fractions is skipped.  In order for this
   to work, argument tbn must be set to FALSE.

`Details`

Internally segmentByCBS() is used for segmentation.
   The Paired PSCBS segmentation method does not support weights.

`References`

[1] A.B. Olshen, H. Bengtsson, P. Neuvial, P.T. Spellman, R.A. Olshen, V.E. Seshan, Parent-specific copy number in paired tumor-normal studies using circular binary segmentation, Bioinformatics, 2011
 
[2] H. Bengtsson, P. Neuvial and T.P. Speed, TumorBoost: Normalization of allele-specific tumor copy numbers from a single pair of tumor-normal genotyping microarrays, BMC Bioinformatics, 2010

`See Also`

Internally, callNaiveGenotypes is used to
   call naive genotypes, normalizeTumorBoost is
   used for TumorBoost normalization, and segmentByCBS() is used
   to segment TCN and DH separately.

   To segment total copy-numbers, or any other unimodal signals,
   see segmentByCBS().

`Examples`

Run this code# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Load SNP microarray data
# (note to package developers: this example data set may
#  be replaced in a future release of the package)
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
pathname <- system.file("data-ex/PairedPSCBS,exData,chr01.Rbin", package="PSCBS")
data <- R.utils::loadObject(pathname)
str(data)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Paired PSCBS segmentation
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Drop single-locus outliers
dataS <- dropSegmentationOutliers(data)

# Speed up example by segmenting fewer loci
dataS <- dataS[seq(from=1, to=nrow(data), by=5),]

str(dataS)

R.oo::attachLocally(dataS)

# Paired PSCBS segmentation
fit <- segmentByPairedPSCBS(CT, betaT=betaT, betaN=betaN,
                            chromosome=chromosome, x=x,
                            seed=0xBEEF, verbose=-10)
print(fit)

# Plot results
plotTracks(fit)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Bootstrap segment level estimates
# (used by the AB caller, which, if skipped here,
#  will do it automatically)
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fit <- bootstrapTCNandDHByRegion(fit, verbose=-10)
print(fit)
plotTracks(fit)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Calling segments in allelic balance (AB)
# NOTE: Ideally, this should be done on whole-genome data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Explicitly estimate the threshold in DH for calling AB
# (which be done by default by the caller, if skipped here)
deltaAB <- estimateDeltaAB(fit, flavor="qq(DH)", verbose=-10)
print(deltaAB)
## [1] 0.1657131

fit <- callAB(fit, delta=deltaAB, verbose=-10)
print(fit)
plotTracks(fit)

# Even if not explicitly specified, the estimated
# threshold parameter is returned by the caller
stopifnot(fit$params$deltaAB == deltaAB)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Calling segments in loss-of-heterozygosity (LOH)
# NOTE: Ideally, this should be done on whole-genome data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Explicitly estimate the threshold in C1 for calling LOH
# (which be done by default by the caller, if skipped here)
deltaLOH <- estimateDeltaLOH(fit, flavor="minC1|nonAB", verbose=-10)
print(deltaLOH)
## [1] 0.625175

fit <- callLOH(fit, delta=deltaLOH, verbose=-10)
print(fit)
plotTracks(fit)

# Even if not explicitly specified, the estimated
# threshold parameter is returned by the caller
stopifnot(fit$params$deltaLOH == deltaLOH)
Run the code above in your browser using DataLab