Package PSCBS

Description

Segmentation of allele-specific DNA copy number data and detection of regions with abnormal copy number within each parental chromosome. Both tumor-normal paired and tumor-only analyses are supported..

This package should be considered to be in an alpha or beta phase. You should expect the API to be changing over time.

Installation and updates

To install this package, use install.packages("PSCBS").

To get started

To get started, see:

1. Vignettes 'Parent-specific copy-number segmentation using Paired PSCBS' and 'Total copy-number segmentation using CBS'.

2. segmentByCBS() - segments total copy-numbers, or any other unimodal genomic signals, using the CBS method [3,4].

3. segmentByPairedPSCBS() - segments allele-specific tumor signal from a tumor with a matched normal using the Paired PSCBS method [1,2].

4. segmentByNonPairedPSCBS() - segments allele-specific tumor signal from a tumor without a matched normal using the Non-Paired PSCBS method adopted from [1,2].

How to cite

Please use [1] and [2] to cite when using Paired PSCBS, and [3] and [4] when using CBS. When using Non-Paired PSCBS, please cite [1] and [2] as well.

License

GPL (>= 2).

Author(s)

Henrik Bengtsson

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
[3] A.B. Olshen, E.S. Venkatraman (aka Venkatraman E. Seshan), R. Lucito and M. Wigler, Circular binary segmentation for the analysis of array-based DNA copy number data, Biostatistics, 2004
[4] E.S. Venkatraman and A.B. Olshen, A faster circular binary segmentation algorithm for the analysis of array CGH data, Bioinformatics, 2007

The AbstractCBS class

Description

Package: PSCBS
Class AbstractCBS

list
~~|
~~+--AbstractCBS

Directly known subclasses:
CBS, NonPairedPSCBS, PSCBS, PairedPSCBS

public abstract class AbstractCBS
extends list

All CBS-style segmentation results extend this class, e.g. CBS and PairedPSCBS.

Usage

AbstractCBS(fit=list(), sampleName=fit$sampleName, ...)

Arguments

Fields and Methods

Methods:

Methods inherited from list:
Ops,nonStructure,vector-method, Ops,structure,vector-method, Ops,vector,nonStructure-method, Ops,vector,structure-method, all.equal, as.data.frame, attachLocally, averageQuantile, callHooks, coerce,ANY,list-method, normalizeAverage, normalizeDifferencesToAverage, normalizeQuantileRank, normalizeQuantileSpline, plotDensity, relist, reset, type.convert, within

Author(s)

Henrik Bengtsson

The CBS class

Description

A CBS object holds results from the Circular Binary Segmentation (CBS) method for one sample for one or more chromosomes.

Package: PSCBS
Class CBS

list
~~|
~~+--AbstractCBS
~~~~~~~|
~~~~~~~+--CBS

Directly known subclasses:

public abstract class CBS
extends AbstractCBS

Usage

CBS(...)

Arguments

Fields and Methods

Methods:

Methods inherited from AbstractCBS:
adjustPloidyScale, all.equal, as.data.frame, clearCalls, drawChangePoints, drawKnownSegments, dropChangePoint, dropChangePoints, dropRegion, dropRegions, extractCNs, extractChromosome, extractChromosomes, extractRegions, extractSegments, extractWIG, getChangePoints, getChromosomeOffsets, getChromosomeRanges, getChromosomes, getLocusData, getLocusSignalNames, getMeanEstimators, getSampleName, getSegmentSizes, getSegmentTrackPrefixes, getSegments, mergeThreeSegments, mergeTwoSegments, nbrOfChangePoints, nbrOfChromosomes, nbrOfLoci, nbrOfSegments, normalizeTotalCNs, ploidy, ploidy<-, plotTracks, print, pruneByDP, pruneByHClust, renameChromosomes, report, resegment, resetSegments, sampleCNs, sampleName, sampleName<-, seqOfSegmentsByDP, setLocusData, setMeanEstimators, setPloidy, setSampleName, setSegments, shiftTCN, tileChromosomes, updateMeans, writeWIG

Methods inherited from list:
Ops,nonStructure,vector-method, Ops,structure,vector-method, Ops,vector,nonStructure-method, Ops,vector,structure-method, all.equal, as.data.frame, attachLocally, averageQuantile, callHooks, coerce,ANY,list-method, normalizeAverage, normalizeDifferencesToAverage, normalizeQuantileRank, normalizeQuantileSpline, plotDensity, relist, reset, type.convert, within

Difference to DNAcopy object

A CBS object is similar to DNAcopy objects with the major difference that a CBS object holds only one sample, whereas a DNAcopy object can hold more than one sample.

See also

The segmentByCBS() method returns an object of this class.

Author(s)

Henrik Bengtsson

Non-documented objects

Description

This page contains aliases for all "non-documented" objects that R CMD check detects in this package.

Almost all of them are generic functions that have specific document for the corresponding method coupled to a specific class. Other functions are re-defined by setMethodS3() to default methods. Neither of these two classes are non-documented in reality. The rest are deprecated methods.

Author(s)

Henrik Bengtsson

The NonPairedPSCBS class

Description

Package: PSCBS
Class NonPairedPSCBS

list
~~|
~~+--AbstractCBS
~~~~~~~|
~~~~~~~+--PSCBS
~~~~~~~~~~~~|
~~~~~~~~~~~~+--NonPairedPSCBS

Directly known subclasses:

public abstract class NonPairedPSCBS
extends PSCBS

A NonPairedPSCBS is an object containing the results from the Non-paired PSCBS method.

Usage

NonPairedPSCBS(fit=list(), ...)

Arguments

Fields and Methods

Methods:
No methods defined.

Methods inherited from PSCBS:
as.data.frame, c, drawChangePoints, extractChromosomes, extractWIG, getLocusData, getLocusSignalNames, getSegmentTrackPrefixes, isLocallyPhased, isSegmentSplitter, normalizeTotalCNs, writeSegments

Methods inherited from AbstractCBS:
adjustPloidyScale, all.equal, as.data.frame, clearCalls, drawChangePoints, drawKnownSegments, dropChangePoint, dropChangePoints, dropRegion, dropRegions, extractCNs, extractChromosome, extractChromosomes, extractRegions, extractSegments, extractWIG, getChangePoints, getChromosomeOffsets, getChromosomeRanges, getChromosomes, getLocusData, getLocusSignalNames, getMeanEstimators, getSampleName, getSegmentSizes, getSegmentTrackPrefixes, getSegments, mergeThreeSegments, mergeTwoSegments, nbrOfChangePoints, nbrOfChromosomes, nbrOfLoci, nbrOfSegments, normalizeTotalCNs, ploidy, ploidy<-, plotTracks, print, pruneByDP, pruneByHClust, renameChromosomes, report, resegment, resetSegments, sampleCNs, sampleName, sampleName<-, seqOfSegmentsByDP, setLocusData, setMeanEstimators, setPloidy, setSampleName, setSegments, shiftTCN, tileChromosomes, updateMeans, writeWIG

Methods inherited from list:
Ops,nonStructure,vector-method, Ops,structure,vector-method, Ops,vector,nonStructure-method, Ops,vector,structure-method, all.equal, as.data.frame, attachLocally, averageQuantile, callHooks, coerce,ANY,list-method, normalizeAverage, normalizeDifferencesToAverage, normalizeQuantileRank, normalizeQuantileSpline, plotDensity, relist, reset, type.convert, within

Author(s)

Henrik Bengtsson

See Also

The segmentByNonPairedPSCBS() method returns an object of this class.

The PSCBS class

Description

Package: PSCBS
Class PSCBS

list
~~|
~~+--AbstractCBS
~~~~~~~|
~~~~~~~+--PSCBS

Directly known subclasses:
NonPairedPSCBS, PairedPSCBS

public abstract class PSCBS
extends AbstractCBS

A PSCBS is an object containing results from parent-specific copy-number (PSCN) segmentation.

Usage

PSCBS(fit=list(), ...)

Arguments

Fields and Methods

Methods:

Methods inherited from AbstractCBS:
adjustPloidyScale, all.equal, as.data.frame, clearCalls, drawChangePoints, drawKnownSegments, dropChangePoint, dropChangePoints, dropRegion, dropRegions, extractCNs, extractChromosome, extractChromosomes, extractRegions, extractSegments, extractWIG, getChangePoints, getChromosomeOffsets, getChromosomeRanges, getChromosomes, getLocusData, getLocusSignalNames, getMeanEstimators, getSampleName, getSegmentSizes, getSegmentTrackPrefixes, getSegments, mergeThreeSegments, mergeTwoSegments, nbrOfChangePoints, nbrOfChromosomes, nbrOfLoci, nbrOfSegments, normalizeTotalCNs, ploidy, ploidy<-, plotTracks, print, pruneByDP, pruneByHClust, renameChromosomes, report, resegment, resetSegments, sampleCNs, sampleName, sampleName<-, seqOfSegmentsByDP, setLocusData, setMeanEstimators, setPloidy, setSampleName, setSegments, shiftTCN, tileChromosomes, updateMeans, writeWIG

Methods inherited from list:
Ops,nonStructure,vector-method, Ops,structure,vector-method, Ops,vector,nonStructure-method, Ops,vector,structure-method, all.equal, as.data.frame, attachLocally, averageQuantile, callHooks, coerce,ANY,list-method, normalizeAverage, normalizeDifferencesToAverage, normalizeQuantileRank, normalizeQuantileSpline, plotDensity, relist, reset, type.convert, within

Author(s)

Henrik Bengtsson

See Also

PairedPSCBS.

The PairedPSCBS class

Description

Package: PSCBS
Class PairedPSCBS

list
~~|
~~+--AbstractCBS
~~~~~~~|
~~~~~~~+--PSCBS
~~~~~~~~~~~~|
~~~~~~~~~~~~+--PairedPSCBS

Directly known subclasses:

public abstract class PairedPSCBS
extends PSCBS

A PairedPSCBS is an object containing the results from the Paired PSCBS method.

Usage

PairedPSCBS(fit=list(), ...)

Arguments

Fields and Methods

Methods:

Methods inherited from PSCBS:
as.data.frame, c, drawChangePoints, extractChromosomes, extractWIG, getLocusData, getLocusSignalNames, getSegmentTrackPrefixes, isLocallyPhased, isSegmentSplitter, normalizeTotalCNs, writeSegments

Methods inherited from AbstractCBS:
adjustPloidyScale, all.equal, as.data.frame, clearCalls, drawChangePoints, drawKnownSegments, dropChangePoint, dropChangePoints, dropRegion, dropRegions, extractCNs, extractChromosome, extractChromosomes, extractRegions, extractSegments, extractWIG, getChangePoints, getChromosomeOffsets, getChromosomeRanges, getChromosomes, getLocusData, getLocusSignalNames, getMeanEstimators, getSampleName, getSegmentSizes, getSegmentTrackPrefixes, getSegments, mergeThreeSegments, mergeTwoSegments, nbrOfChangePoints, nbrOfChromosomes, nbrOfLoci, nbrOfSegments, normalizeTotalCNs, ploidy, ploidy<-, plotTracks, print, pruneByDP, pruneByHClust, renameChromosomes, report, resegment, resetSegments, sampleCNs, sampleName, sampleName<-, seqOfSegmentsByDP, setLocusData, setMeanEstimators, setPloidy, setSampleName, setSegments, shiftTCN, tileChromosomes, updateMeans, writeWIG

Methods inherited from list:
Ops,nonStructure,vector-method, Ops,structure,vector-method, Ops,vector,nonStructure-method, Ops,vector,structure-method, all.equal, as.data.frame, attachLocally, averageQuantile, callHooks, coerce,ANY,list-method, normalizeAverage, normalizeDifferencesToAverage, normalizeQuantileRank, normalizeQuantileSpline, plotDensity, relist, reset, type.convert, within

Author(s)

Henrik Bengtsson

See Also

The segmentByPairedPSCBS() method returns an object of this class.

Restructuring AbstractCBS objects

Description

This page describes available methods for restructuring an AbstractCBS object.

• *extractChromosomes() / *extractChromosome() - Extracts an AbstractCBS with the specified chromosomes.

• *extractSegments() / *extractSegment() - Extracts an AbstractCBS with the specified segments.

• *extractRegions() / *extractRegion() - Extracts an AbstractCBS with the specified regions each of a certain size, where a region is defined as a connected set of segments.

• *dropRegions() / *dropRegion() - Drops specified regions and returns an AbstractCBS without them.

• *dropChangePoint() / *mergeTwoSegments() - Drops a change point by merging two neighboring segments and recalculates the statistics for the merged segment before returning an AbstractCBS.

• *dropChangePoints() - Drops zero or more change points and recalculates the segment statistics before returning an AbstractCBS.

• *mergeThreeSegments() - Merges a segment with its two flanking segments and recalculates the statistics for the merged segment before returning an AbstractCBS.

All of the above methods are implemented for CBS and PairedPSCBS objects.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Coerces a DNAcopy object to a CBS object

Description

Coerces a DNAcopy object to a CBS object.

Usage

## S3 method for class 'DNAcopy'
as.CBS(fit, sample=1L, ...)

Arguments

Value

Returns a CBS object.

Author(s)

Henrik Bengtsson

See Also

as.DNAcopy(). For more information see DNAcopy.

Coerces a CBS object to a DNAcopy object

Description

Coerces a CBS object to a DNAcopy object.

Usage

## S3 method for class 'CBS'
as.DNAcopy(fit, ...)

Arguments

Value

Returns a DNAcopy object (of the DNAcopy package).

Author(s)

Henrik Bengtsson

See Also

as.CBS(). For more information see CBS.

Examples

 
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Simulating copy-number data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
set.seed(0xBEEF)

# Number of loci
J <- 1000

mu <- double(J)
mu[200:300] <- mu[200:300] + 1
mu[350:400] <- NA # centromere
mu[650:800] <- mu[650:800] - 1
eps <- rnorm(J, sd=1/2)
y <- mu + eps
x <- sort(runif(length(y), max=length(y))) * 1e5
w <- runif(J)
w[650:800] <- 0.001


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Segmentation
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fit <- segmentByCBS(y, x=x)
print(fit)
plotTracks(fit)


 
# Coerce an CBS object to a DNAcopy object
fitD <- as.DNAcopy(fit)

# Coerce an DNAcopy object to a CBS object
fitC <- as.CBS(fitD)

# Sanity check
fitD2 <- as.DNAcopy(fit)
stopifnot(all.equal(fitD2, fitD))

fitC2 <- as.CBS(fitD2)
stopifnot(all.equal(fitC2, fitC))

Gets the table of segments

Description

Gets the table of segments.

Usage

## S3 method for class 'AbstractCBS'
as.data.frame(x, ...)

Arguments

Value

Returns a data.frame, where each row corresponds to a unique segment.

Author(s)

Henrik Bengtsson

See Also

Utilizes *getSegments(). For more information see AbstractCBS..

Gets the table of segments

Description

Gets the table of segments.

Usage

## S3 method for class 'CBS'
as.data.frame(x, ...)

Arguments

Value

Returns a data.frame, where each row corresponds to a unique segment.

Author(s)

Henrik Bengtsson

See Also

Utilizes *getSegments(). For more information see CBS..

Estimate confidence intervals of TCN and DH segment levels

Description

Estimate confidence intervals of TCN and DH segment levels using bootstrap.

Usage

## S3 method for class 'PairedPSCBS'
bootstrapTCNandDHByRegion(fit, B=1000L, boot=NULL, ..., probs=c(0.025, 0.05, 0.95,
  0.975), statsFcn=NULL, what=c("segment", "changepoint"), force=FALSE, verbose=FALSE,
  .debug=FALSE)

Arguments

Value

Returns a PairedPSCBS object.

Author(s)

Henrik Bengtsson

Concatenates segmentation results

Description

Concatenates segmentation results.

Usage

## S3 method for class 'CBS'
c(..., addSplit=TRUE)

Arguments

Value

Returns an AbstractCBS object of the same class in ....

Author(s)

Henrik Bengtsson

See Also

For more information see CBS.

Calls segments that are in allelic balance

Description

Calls segments that are in allelic balance, i.e. that have equal minor and major copy numbers.

Usage

## S3 method for class 'PairedPSCBS'
callAB(fit, flavor=c("DeltaAB*"), ..., minSize=1, xorCalls=TRUE, force=FALSE)

Arguments

Value

Returns a PairedPSCBS object with allelic-balance calls.

AB and LOH consistency

Biologically, a segment can not be both in allelic balance (AB) and in loss-of-heterozygosity (LOH) at the same time. To avoid reporting such inconsistencies, the LOH caller will, if argument xorCalls=TRUE, never report a segment to be in LOH if it is already called to be in AB. However, regardless of of the AB call, a segment is still always tested for LOH, to check weather the LOH caller is consistent with the AB caller or not. Thus, in order to distinguish the case where the AB caller and LOH caller agree from when they disagree, we report either (AB,LOH)=(TRUE,FALSE) or (TRUE,NA). The former is reported when they are consistent, and the latter when they are not, or when the AB caller could not call it.

Author(s)

Henrik Bengtsson

See Also

Internally, one of the following methods are used: *callAllelicBalanceByDH().

Calls segments that are in allelic balance

Description

Calls segments that are in allelic balance by thresholding on DH using a predetermined threshold. The variability of the DH mean levels is taken into account via a bootstrap estimator.

Usage

## S3 method for class 'PairedPSCBS'
callAllelicBalanceByDH(fit, delta=estimateDeltaAB(fit, flavor = "qq(DH)"), alpha=0.05,
  ..., verbose=FALSE)

Arguments

Value

Returns a PairedPSCBS object with allelic-balance calls.

Algorithm

• Foo

• Bar

Author(s)

Henrik Bengtsson

See Also

Instead of calling this method explicitly, it is recommended to use the *callAllelicBalance() method.

Calls (focal) amplifications

Description

Calls (focal) amplifications.

Usage

## S3 method for class 'CBS'
callAmplifications(fit, adjust=1, maxLength=2e+07, method=c("ucsf-exp"), ...,
  verbose=FALSE)

Arguments

Value

Returns a CBS object where logical column 'amplificationCall' has been appended to the segmentation table.

The UCSF caller

If method == "ucsf-exp", then segments are called using [1], i.e. a segment is called an amplification if ...

Author(s)

Henrik Bengtsson

References

[1] Fridlyand et al. Breast tumor copy number aberration phenotypes and genomic instability, BMC Cancer, 2006.

See Also

*callGainsAndLosses(). *callOutliers(). For more information see CBS.

Calls segments that have a neutral total copy number

Description

Calls segments that have a neutral total copy number (NTCN), i.e. that have a TCN that corresponds to the ploidy of the genome.

Usage

## S3 method for class 'PairedPSCBS'
callCopyNeutral(fit, flavor=c("TCN|AB"), ..., minSize=1, force=FALSE)

Arguments

Value

Returns a PairedPSCBS object with copy-neutral calls.

Author(s)

Henrik Bengtsson

See Also

Internally, one of the following methods are used: *callCopyNeutralByTCNofAB().

Calls regions that are copy neutral

Description

Calls regions that are copy neutral from the total copy numbers (TCNs) of segments in allelic balance (AB).

Usage

## S3 method for class 'PairedPSCBS'
callCopyNeutralByTCNofAB(fit, delta=estimateDeltaCN(fit), alpha=0.05, ..., force=FALSE,
  verbose=FALSE)

Arguments

Details

...

Value

Returns a PairedPSCBS fit object where a column with the copy-neutral call.

Author(s)

Henrik Bengtsson

Calls segments that are gained, copy neutral, or lost

Description

Calls segments that are gained, copy neutral, or lost, where copy neutral means having a total copy number that corresponds to the ploidy of the genome.

Usage

## S3 method for class 'PairedPSCBS'
callGNL(fit, flavor=c("TCN|AB"), ..., minSize=1, force=FALSE)

Arguments

Value

Returns a PairedPSCBS object with added calls.

Author(s)

Henrik Bengtsson

See Also

Internally, one of the following methods are used: callGNLByTCNofAB().

Calls gains and losses

Description

Calls gains and losses.

Usage

## S3 method for class 'CBS'
callGainsAndLosses(fit, adjust=1, method=c("ucsf-mad", "ucsf-dmad"), ..., verbose=FALSE)

Arguments

Value

Returns a CBS object where logical columns 'lossCall' and 'gainCall' have been appended to the segmentation table.

The UCSF caller

If method == "ucsf-mad", then segments are called using [1], i.e. a segment is called gained or lost if its segment level is at least two standard deviations away from the median segment level on Chr1-22, where standard deviation is estimated using MAD. Then same is done for method == "ucsf-dmad" with the difference that the standard deviation is estimated using a robust first order variance estimator.

Author(s)

Henrik Bengtsson

References

[1] Fridlyand et al. Breast tumor copy number aberration phenotypes and genomic instability, BMC Cancer, 2006.

See Also

*callAmplifications(). *callOutliers(). For more information see CBS.

Examples

 
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Simulating copy-number data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
set.seed(0xBEEF)

# Number of loci
J <- 1000

mu <- double(J)
mu[200:300] <- mu[200:300] + 1
mu[350:400] <- NA # centromere
mu[650:800] <- mu[650:800] - 1
eps <- rnorm(J, sd=1/2)
y <- mu + eps
x <- sort(runif(length(y), max=length(y))) * 1e5
w <- runif(J)
w[650:800] <- 0.001


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Segmentation
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fit <- segmentByCBS(y, x=x)
print(fit)
plotTracks(fit)


 
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# CALLS
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Call gains and losses by segments
fitC <- callGainsAndLosses(fit)

# Call amplifications by segments
fitC <- callAmplifications(fitC)

# Call outliers by loci
fitC <- callOutliers(fitC)

Calls segments that are in LOH

Description

Calls segments that are in LOH, i.e. that have "zero" minor copy number.

Usage

## S3 method for class 'PairedPSCBS'
callLOH(fit, flavor=c("SmallC1", "LargeDH"), ..., minSize=1, xorCalls=TRUE, force=FALSE)

Arguments

Value

Returns a PairedPSCBS object with LOH calls.

AB and LOH consistency

Biologically, a segment can not be both in allelic balance (AB) and in loss-of-heterozygosity (LOH) at the same time. To avoid reporting such inconsistencies, the LOH caller will, if argument xorCalls=TRUE, never report a segment to be in LOH if it is already called to be in AB. However, regardless of of the AB call, a segment is still always tested for LOH, to check weather the LOH caller is consistent with the AB caller or not. Thus, in order to distinguish the case where the AB caller and LOH caller agree from when they disagree, we report either (AB,LOH)=(TRUE,FALSE) or (TRUE,NA). The former is reported when they are consistent, and the latter when they are not, or when the LOH caller could not call it.

Author(s)

Henrik Bengtsson

See Also

Internally, one of the following methods are used: *callLowC1ByC1(), *callExtremeAllelicImbalanceByDH().

Calls outliers

Description

Calls outliers.

Usage

## S3 method for class 'CBS'
callOutliers(fit, adjust=1, method=c("ucsf-mad"), ...)

Arguments

Value

Returns a CBS object where logical columns 'negOutlierCall' and 'posOutlierCall' have been appended to the segmentation table.

The UCSF caller

If method == "ucsf-mad", then loci are called using [1] "Finally, to identify single technical or biological outliers such as high level amplifications, the presence of the outliers within a segment was allowed by assigning the original observed log2ratio to the clones for which the observed values were more than four tumor-specific MAD away from the smoothed values." [1; Suppl. Mat.]

Author(s)

Henrik Bengtsson

References

[1] Fridlyand et al. Breast tumor copy number aberration phenotypes and genomic instability, BMC Cancer, 2006.

See Also

*callGainsAndLosses(). *callAmplifications(). For more information see CBS.

Calls segments that are in ROH

Description

Calls segments that are in ROH, i.e. that have no (true) heterozygous genotypes. Run of homozygosity (ROH) is a property of the normal (germline) sample.

Usage

## S3 method for class 'PairedPSCBS'
callROH(fit, ..., updateMeans=TRUE, force=FALSE, verbose=FALSE)

Arguments

Value

Returns a PairedPSCBS object with ROH calls.

Author(s)

Pierre Neuvial, Henrik Bengtsson

See Also

Internally, testROH() is used. To call allelic balance (AB) see *callAB(). To call loss of heterozygosity (LOH) see *callLOH().

Calls/drops single-locus outliers along the genome

Description

Calls/drops single-locus outliers along the genome that have a signal that differ significantly from the neighboring loci.

Usage

 ## Default S3 method:
callSegmentationOutliers(y, chromosome=0, x=NULL, method="DNAcopy::smooth.CNA", ...,
  verbose=FALSE)
 ## S3 method for class 'data.frame'
callSegmentationOutliers(y, ...)
 ## Default S3 method:
dropSegmentationOutliers(y, ...)
 ## S3 method for class 'data.frame'
dropSegmentationOutliers(y, ...)

Arguments

Value

callSegmentationOutliers() returns a logical vector of length J. dropSegmentationOutliers() returns an object of the same type as argument y, where the signals for which outliers were called have been set to NA.

Missing and non-finite values

Signals as well as genomic positions may contain missing values, i.e. NAs or NaNs. By definition, these cannot be outliers.

Author(s)

Henrik Bengtsson

See Also

Internally smooth.CNA is utilized to identify the outliers.

Drops zero or more change points

Description

Drops zero or more change points, which is done by dropping one change point at the time using *dropChangePoint() and recalculating the segment statistics at the end.

NOTE: This method only works if there is only one chromosome.

Usage

## S3 method for class 'AbstractCBS'
dropChangePoints(fit, idxs, update=TRUE, ...)

Arguments

Value

Returns an AbstractCBS of the same class with length(idxs) segments.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Drops chromosomal regions (a connected set of segments)

Description

Drops chromosomal regions (a connected set of segments) each of a certain size (number of segments). None of the statistics are recalculated.

Usage

## S3 method for class 'AbstractCBS'
dropRegions(this, regions, H=1, ..., asMissing=FALSE, verbose=FALSE)

Arguments

Value

Returns an AbstractCBS object of the same class with (at most) R*H segments dropped. If some regions overlap (share segments), then fewer than R*H segments are dropped.

Author(s)

Henrik Bengtsson

See Also

Internally *extractRegions() is used. See also *dropChangePoint() and *mergeTwoSegments(). For more information see AbstractCBS.

Estimate a threshold for calling allelic balance from DH

Description

Estimate a threshold for calling allelic balance from DH to be used by the *callAB() method.

Usage

## S3 method for class 'PairedPSCBS'
estimateDeltaAB(this, scale=NULL, flavor=c("qq(DH)", "q(DH)", "mad(hBAF)", "median(DH)"),
  ..., max=Inf, verbose=FALSE)

Arguments

Value

Returns the threshold estimate as a numeric scalar.

Author(s)

Henrik Bengtsson

See Also

Internally, one of the following methods are used: *estimateDeltaABBySmallDH(), *estimateStdDevForHeterozygousBAF(), *estimateMeanForDH(), and *estimateHighDHQuantileAtAB().

Estimate a threshold for calling allelic balance from DH

Description

Estimate a threshold for calling allelic balance from DH.

Usage

## S3 method for class 'PairedPSCBS'
estimateDeltaABBySmallDH(fit, q1=0.05, q2=0.9, ..., verbose=FALSE)

Arguments

Value

Returns the threshold estimate as a numeric scalar.

Algorithm

• Grabs the segment-level DH estimates.

• Calculate segment weights proportional to the number of heterozygous SNPs.

• Calculate \Delta as the 5% quantile of the weighted DH means.

• Choose the segments with means less than \Delta.

• Calculate threshold \Delta_{AB} as the 90% "symmetric" quantile of the observed locus-level DHs from the selected segments in Step 4. The q:th "symmetric" quantile is estimated by estimating the ((1-q), 50%) quantiles, calculating their distance as "50%-(1-q)" and add to the median (50%), i.e. "median + (median-(1-q))" = "2*median-1 + q", which should equal q if the distribution is symmetric.

Author(s)

Henrik Bengtsson

See Also

Instead of calling this method explicitly, it is recommended to use the *estimateDeltaAB() method.

Estimates the length of one total copy-number (TCN) unit

Description

Estimates the length of one total copy-number (TCN) unit

Usage

## S3 method for class 'PairedPSCBS'
estimateDeltaCN(fit, scale=1, flavor=c("1-kappa", "delta(mode)"),
  kappa=estimateKappa(fit), adjust=0.2, quantile=0.95, ...)

Arguments

Details

For parent-specific copy-number (PSCN) data, the TCN unit length is estimated as (1-kappa)/2, where kappa is estimated from data (by estimateKappa).

For total copy-number (TCN) data (only),

Value

Returns a positive scalar numeric.

Author(s)

Henrik Bengtsson

See Also

For more information see PairedPSCBS.

Estimate a threshold for calling LOH from DH

Description

Estimate a threshold for calling LOH from DH to be used by the *callLOH() method.

Usage

## S3 method for class 'PairedPSCBS'
estimateDeltaLOH(this, flavor=c("minC1|nonAB"), ..., max=Inf, verbose=FALSE)

Arguments

Value

Returns the threshold estimate as a numeric scalar or -Inf. In case it is not possible to estimate the LOH threshold, then -Inf is returned.

Author(s)

Henrik Bengtsson

See Also

Internally, one of the following methods are used: *estimateDeltaLOHByMinC1ForNonAB().

Estimate a threshold for calling LOH from DH

Description

Estimate a threshold for calling LOH from DH based on the location of guessed C1=0 and C1=1 peaks.

Usage

## S3 method for class 'PairedPSCBS'
estimateDeltaLOHByMinC1ForNonAB(this, midpoint=1/2, maxC=3 * (ploidy(this)/2), ...,
  verbose=FALSE)

Arguments

Details

This method requires that calls for allelic balances already have been me made, cf. *callAllelicBalance().

Value

Returns the estimated LOH threshold as a numeric scalar or -Inf. In case it is not possible to estimate the LOH threshold, then -Inf is returned.

Algorithm

• Grabs the segment-level C1 estimates.

• Calculate segment weights proportional to the number of heterozygous SNPs.

• Estimate the C1=1 location as the weighted median C1 for segments that have been called to be in allelic balance.

• Estimate the C1=0 location as the smallest C1 among segments that are not in allelic balance.

• Let the LOH threshold be the midpoint of the estimates C1=0 and C1=1 locations.

Author(s)

Henrik Bengtsson

See Also

Instead of calling this method explicitly, it is recommended to use the *estimateDeltaLOH() method.

Estimate global background in segmented copy numbers

Description

Estimate global background in segmented copy numbers. The global background, here called \kappa, may have multiple origins where normal contamination is one, but not necessarily the only one.

Usage

## S3 method for class 'PairedPSCBS'
estimateKappa(this, flavor=c("density(C1)"), ...)

Arguments

Value

Returns the background estimate as a numeric scalar.

Author(s)

Henrik Bengtsson

See Also

Internally, one of the following methods are used: *estimateKappaByC1Density().

Estimate global background in segmented copy numbers

Description

Estimate global background in segmented copy numbers based on the location of peaks in a weighted density estimator of the minor copy number mean levels.

The global background, here called \kappa, may have multiple origins where normal contamination is one, but not necessarily the only one.

Assumptions: This estimator assumes that there are segments with C1=0 and C1=1, i.e. some deletions and, typically, some normal segements.

Usage

## S3 method for class 'PairedPSCBS'
estimateKappaByC1Density(this, typeOfWeights=c("dhNbrOfLoci", "sqrt(dhNbrOfLoci)"),
  adjust=1, from=0, minDensity=0.2, ..., verbose=FALSE)

Arguments

Value

Returns the background estimate as a numeric scalar.

Algorithm

• Retrieve segment-level minor copy numbers and corresponding weights:

  1. Grabs the segment-level C1 estimates.

  2. Calculate segment weights. The default (typeOfWeights="dhNbrOfLoci") is to use weights proportional to the number of heterozygous SNPs. An alternative (typeOfWeights="sqrt(dhNbrOfLoci)") is to use the square root of those counts.

• Identify subset of regions with C1=0:

  1. Estimates the weighted empirical density function (truncated at zero below). Tuning parameter 'adjust'.

  2. Find the first two peaks (with a density greater than tuning parameter 'minDensity').

  3. Assumes that the two peaks corresponds to C1=0 and C1=1.

  4. Defines threshold Delta0.5 as the center location between these two peaks.

• Estimate the global background signal:

  1. For all segments with C1 < Delta0.5, calculate the weighted median of their C1:s.

  2. Let kappa be the above weighted median. This is the estimated background.

Author(s)

Henrik Bengtsson

See Also

Instead of calling this method explicitly, it is recommended to use the *estimateKappa() method.

Estimates the whole-genome standard deviation of the signals

Description

Estimates the whole-genome standard deviation of the signals.

Usage

## S3 method for class 'CBS'
estimateStandardDeviation(fit, chromosomes=NULL, method=c("diff", "res", "abs",
  "DNAcopy"), estimator=c("mad", "sd"), na.rm=TRUE, weights=NULL, ...)

Arguments

Value

Returns a non-negative numeric scale.

Author(s)

Henrik Bengtsson

See Also

For more information see CBS.

Gets an example data set

Description

Gets an example data set.

Usage

## Default S3 method:
exampleData(name=c("paired.chr01"), ...)

Arguments

Value

Returns data.frame.

Author(s)

Henrik Bengtsson

Extract minor and major copy-number mean levels per segment

Description

Extract minor and major copy-number mean levels per segment.

Usage

## S3 method for class 'PairedPSCBS'
extractMinorMajorCNs(fit, ...)

Arguments

Value

Returns a data.frame.

Author(s)

Henrik Bengtsson

See Also

*extractTCNAndDHs() For more information see PairedPSCBS.

Extracts segments means at each locus

Description

Extracts segments means at each locus.

Usage

## S3 method for class 'CBS'
extractSegmentMeansByLocus(fit, ...)

Arguments

Value

Returns a numeric vector of length nbrOfLoci().

Author(s)

Henrik Bengtsson

See Also

For more information see CBS.

Extract TCN and DH mean levels per segment

Description

Extract TCN and DH mean levels per segment.

Usage

## S3 method for class 'PairedPSCBS'
extractTCNAndDHs(fit, ...)

Arguments

Value

Returns a data.frame.

Author(s)

Henrik Bengtsson

See Also

*extractMinorMajorCNs(). For more information see PairedPSCBS.

Identifies gaps of a genome where there exist no observations

Description

Identifies gaps of a genome where there exist no observations.

Usage

## Default S3 method:
findLargeGaps(chromosome=NULL, x, minLength, resolution=1L, ...)

Arguments

Value

Returns data.frame zero or more rows and with columns chromosome (if given), start, stop, and length.

Author(s)

Henrik Bengtsson

See Also

Use gapsToSegments() to turn the set of identified gaps into the complementary set of segments such that they can be passed to segmentByCBS(), segmentByPairedPSCBS() and segmentByNonPairedPSCBS() via argument knownSegments.

Call segments to be copy neutral based on allelic imbalance calls and total copy number estimates

Description

Call segments to be copy neutral based on allelic imbalance calls and total copy number estimates.

Usage

## Default S3 method:
findNeutralCopyNumberState(C, isAI, weights=NULL, ..., minDensity=1e-10,
  flavor=c("firstPeak", "maxPeak"), verbose=FALSE)

Arguments

Value

A logical vector of "neutral copy number state" calls.

Author(s)

Pierre Neuvial, Henrik Bengtsson

Gets the genomic segments that are complementary to the gaps

Description

Gets the genomic segments that are complementary to the gaps, with default chromosome boundaries being -Inf and +Inf.

Usage

## S3 method for class 'data.frame'
gapsToSegments(gaps, resolution=1L, minLength=0L, dropGaps=FALSE, ...)

Arguments

Value

Returns data.frame of least one row with columns chromosome if that argument is given), start, stop and length. The segments are ordered along the genome.

Author(s)

Henrik Bengtsson

See Also

findLargeGaps().

Generates original and bootstrapped segment-specific index sets

Description

Generates original and bootstrapped segment-specific index sets, which can be used to calculate various bootstrap summaries, e.g. segment mean levels.

Usage

## S3 method for class 'PairedPSCBS'
getBootstrapLocusSets(fit, B=1000L, by=c("betaTN", "betaT"), seed=NULL, verbose=FALSE,
  .validate=FALSE, ...)

Arguments

Value

Returns a list.

Author(s)

Henrik Bengtsson

See Also

This is used internally by various bootstrap methods.

Calculates various call statistics per chromosome

Description

Calculates various call statistics per chromosome.

Usage

## S3 method for class 'CBS'
getCallStatistics(fit, regions=NULL, shrinkRegions=TRUE, ..., verbose=FALSE)

Arguments

Details

The estimators implemented here are based solely on the segmentation results, which is very fast. In the original proposal by Fridlyand et al. [1], the authors estimates the parameters by converting segment-level calls back to locus-level calls and there do the calculations. The difference between the two approaches should be minor, particularly for large density arrays.

Value

Returns a CxK data.frame, where C is the number of regions that meet the criteria setup by argument regions and (K-4)/2 is the number of call types. The first column is the chromosome index, the second and the third are the first and last position, and the fourth the length (=last-first+1) of the chromosome. The following columns contains call summaries per chromosome. For each chromosome and call type, the total length of such calls on that chromosome is reported together how large of a fraction of the chromosome such calls occupy.

Author(s)

Henrik Bengtsson

References

[1] Fridlyand et al. Breast tumor copy number aberration phenotypes and genomic instability, BMC Cancer, 2006.

See Also

For more information see CBS.

Gets the set of chromosomes

Description

Gets the set of chromosomes in the segmentation result.

Usage

## S3 method for class 'AbstractCBS'
getChromosomes(this, ...)

Arguments

Value

Returns a unique and sorted vector of chromosomes segmented.

Author(s)

Henrik Bengtsson

See Also

*nbrOfChromosomes(). For more information see AbstractCBS.

Calculates the fraction of the genome lost, gained, or aberrant either way

Description

Calculates the fraction of the genome lost, gained, or aberrant either way (in sense of total copy numbers), using definitions closely related to those presented in [1].

Usage

## S3 method for class 'CBS'
getFractionOfGenomeLost(fit, ...)

Arguments

Value

Returns a double in [0,1].

Author(s)

Henrik Bengtsson

References

[1] Fridlyand et al. Breast tumor copy number aberration phenotypes and genomic instability, BMC Cancer, 2006.

See Also

Internally, *getCallStatistics() is used. For more information see CBS.

Gets the locus-level data

Description

Gets the locus-level data.

Usage

## S3 method for class 'AbstractCBS'
getLocusData(...)

Arguments

Value

Returns a JxL data.frame, where J in the number of loci, and L is the number of locus-specific fields.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Gets the name of the sample segmented

Description

Gets the name of the sample segmented.

Usage

## S3 method for class 'AbstractCBS'
getSampleName(fit, ...)

Arguments

Value

Returns a character string.

Author(s)

Henrik Bengtsson

See Also

*setSampleName(). For more information see AbstractCBS..

Gets the segments

Description

Gets the segments.

Usage

## S3 method for class 'AbstractCBS'
getSegments(...)

Arguments

Value

Returns a SxK data.frame, where S in the number of segments, and K is the number of segment-specific fields.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Gets the segments

Description

Gets the segments.

Usage

## S3 method for class 'PSCBS'
getSegments(fit, simplify=FALSE, splitters=TRUE, addGaps=FALSE, ...)

Arguments

#

Value

Returns a SxK data.frame, where S in the number of segments, and K is the number of segment-specific fields.

Author(s)

Henrik Bengtsson

See Also

For more information see PSCBS.

Gets smoothed locus-level data

Description

Gets smoothed locus-level data.

Usage

## S3 method for class 'CBS'
getSmoothLocusData(fit, by, ...)

Arguments

Value

Returns a data.frame where the first three columns are 'chromosome', 'x' (position), and 'count' (number of loci average over for the given bin), and the remaining ones are the smoothed locus-level data.

Author(s)

Henrik Bengtsson

See Also

For more information see CBS.

Performs a hierarchical clustering of the CN mean levels

Description

Performs a hierarchical clustering of the CN mean levels.

Usage

## S3 method for class 'AbstractCBS'
hclustCNs(fit, size=NULL, distMethod="euclidean", hclustMethod="ward.D", ...,
  verbose=FALSE)

Arguments

Value

Returns a hclust object as returned by hclust.

Author(s)

Henrik Bengtsson

See Also

This method is utilized by *pruneByHClust().

Install the DNAcopy package

Description

Install the DNAcopy package, if missing.

Usage

## Default S3 method:
installDNAcopy(..., force=FALSE)

Arguments

Details

This function is will download and call the biocLite() installation function from the Bioconductor Project website. This function will also make sure that DNAcopy is loaded so that it is reported by sessionInfo.

Value

Returns nothing.

Author(s)

Henrik Bengtsson

Joins neighboring segments such that there is no gap in between them

Description

Joins neighboring segments such that there is no gap in between them. For instance, consider two neighboring segments [x1,x2] and [x3,x4] with x1 < x2 < x3 < x4. After join the segments, they are [x1,x23] and [x23,x4] where x23 = (x2 + x3)/2.

Usage

## S3 method for class 'CBS'
joinSegments(fit, range=NULL, verbose=FALSE, ...)

Arguments

Details

This function assumes only chromosome exists. If more, an error will be thrown.

Value

Returns an updated CBS object.

Author(s)

Henrik Bengtsson

Merge neighboring segments that are not called

Description

Merge neighboring segments that are not called

Usage

## S3 method for class 'CBS'
mergeNonCalledSegments(fit, ..., verbose=FALSE)

Arguments

Value

Returns an object of the same class with the same of fewer number of segments.

Author(s)

Henrik Bengtsson

See Also

For more information see CBS.

Merge a segment and its two flanking segments

Description

Merge a segment and its two flanking segments into one segment, and recalculating the segment statistics.

Usage

## S3 method for class 'AbstractCBS'
mergeThreeSegments(fit, middle, ...)

Arguments

Value

Returns an AbstractCBS of the same class with two less segment.

Author(s)

Henrik Bengtsson

See Also

Internally *mergeTwoSegments() is used. For more information see AbstractCBS.

Merge two neighboring segments

Description

Merge two neighboring segments into one segment, which is done by dropping their common change point and recalculating the segment statistics.

Usage

## S3 method for class 'AbstractCBS'
mergeTwoSegments(...)

Arguments

Value

Returns an AbstractCBS of the same class with one less segment.

Author(s)

Henrik Bengtsson

See Also

To merge a segment and its two flanking segments, see *mergeThreeSegments(). To drop regions (a connected set of segments) see *dropRegions(). For more information see AbstractCBS.

Merge two neighboring segments

Description

Merge two neighboring segments by recalculating segment statistics.

Usage

## S3 method for class 'PairedPSCBS'
mergeTwoSegments(this, left, update=TRUE, verbose=FALSE, ...)

Arguments

Value

Returns a PairedPSCBS with one less segment.

Author(s)

Henrik Bengtsson

See Also

To drop regions (a connected set of segments) see dropRegions(). For more information see PairedPSCBS.

Gets the number of change points

Description

Gets the number of change points, which is defined as the number of segments minus the number of chromosomes.

Usage

## S3 method for class 'AbstractCBS'
nbrOfChangePoints(fit, ignoreGaps=FALSE, dropEmptySegments=TRUE, ...)

Arguments

Value

Returns an integer.

Author(s)

Henrik Bengtsson

See Also

*nbrOfSegments() *nbrOfChromosomes() For more information see AbstractCBS.

Gets the number of chromosomes

Description

Gets the number of chromosomes.

Usage

## S3 method for class 'AbstractCBS'
nbrOfChromosomes(this, ...)

Arguments

Value

Returns an integer.

Author(s)

Henrik Bengtsson

See Also

*getChromosomes(). For more information see AbstractCBS.

Gets the number of loci

Description

Gets the number of loci.

Usage

## S3 method for class 'AbstractCBS'
nbrOfLoci(fit, splitters=FALSE, ...)

Arguments

Value

Returns an integer.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Gets the number of segments

Description

Gets the number of segments.

Usage

## S3 method for class 'AbstractCBS'
nbrOfSegments(this, splitters=FALSE, ...)

Arguments

Value

Returns an integer.

Author(s)

Henrik Bengtsson

See Also

*nbrOfChangePoints() *nbrOfChromosomes() For more information see AbstractCBS.

Normalizes copy numbers such that the whole-genome average total copy number is two

Description

Normalizes copy numbers such that the whole-genome average total copy number is two.

Usage

## S3 method for class 'AbstractCBS'
normalizeTotalCNs(...)

Arguments

Value

Returns a normalized AbstractCBS object of the same class as fit.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS..

Gets and sets ploidy

Description

Gets and sets ploidy.

Usage

  ## S3 method for class 'AbstractCBS'
ploidy(fit, ...)
  ## S3 replacement method for class 'AbstractCBS'
ploidy(fit) <- value

Arguments

Value

Returns (invisibly) an updated object.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS..

Plots the segmentation result along the genome

Description

Plots the segmentation result along the genome.

Usage

## S3 method for class 'AbstractCBS'
plotTracks(...)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Plots copy numbers along the genome

Description

Plots copy numbers along the genome for one or more chromosomes. Each type of track is plotted in its own panel.

Usage

## S3 method for class 'CBS'
plotTracks(x, scatter=TRUE, pch=20, col="gray", meanCol="purple", cex=1, grid=FALSE,
  Clim="auto", xScale=1e-06, Clab="auto", ..., byIndex=FALSE, mar=NULL, add=FALSE)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

Plots parental specific copy numbers along the genome

Description

Plots parental specific copy numbers along the genome for one or more chromosomes. It is possible to specify what type of tracks to plot. Each type of track is plotted in its own panel.

Usage

## S3 method for class 'PairedPSCBS'
plotTracks1(x, tracks=c("tcn", "dh", "tcn,c1,c2", "tcn,c1", "tcn,c2", "c1,c2", "betaN",
  "betaT", "betaTN")[1:3], scatter="*", calls=".*", pch=".", col=NULL, cex=1,
  changepoints=FALSE, grid=FALSE, quantiles=c(0.05, 0.95), xlim=NULL,
  Clim=c(0, 3 * ploidy(x)), Blim=c(0, 1), xScale=1e-06, ..., add=FALSE,
  subplots=!add && (length(tracks) > 1), verbose=FALSE)

Arguments

Value

Returns nothing.

Author(s)

Henrik Bengtsson

Prunes the CN profile using dynamical programming

Description

Prunes the CN profile using dynamical programming by specifying the target number of segments or alternative how of many change points to drop.

Usage

## S3 method for class 'AbstractCBS'
pruneByDP(fit, nbrOfSegments, ..., verbose=FALSE)

Arguments

Value

Returns a pruned object of the same class.

Author(s)

Henrik Bengtsson, Pierre Neuvial

References

[1] ...

Examples

## Not run: 
 # Drop two segments
 fitP <- pruneByDP(fit, nbrOfSegments=-2)

## End(Not run)

Prunes the CN profile by pruning and merging through hierarchical clustering

Description

Prunes the CN profile by pruning and merging through hierarchical clustering.

Usage

## S3 method for class 'AbstractCBS'
pruneByHClust(fit, ..., size=NULL, distMethod="euclidean", hclustMethod="ward.D",
  merge=TRUE, update=TRUE, verbose=FALSE)

Arguments

Value

Returns a pruned object of the same class.

Author(s)

Henrik Bengtsson

Examples

## Not run: 
 fitP <- pruneByHClust(fit, h=0.25)

## End(Not run)

Prune the CBS profile by dropping change points that are too small

Description

Prune the CBS profile by dropping change points that are too small, where "too small" means that the amplitude of the change points is less than a multiple of the overall standard deviation of the copy-number signals.

Usage

## S3 method for class 'CBS'
pruneBySdUndo(fit, rho=3, sigma="DNAcopy", ..., verbose=FALSE)

Arguments

Details

This method corresponds to using the undo argument when calling segmentByCBS(), which in turn corresponds to using the undo.splits="sdundo" and undo.SD of the underlying segment method.

Value

Returns a CBS object (of the same class as fit).

Author(s)

Henrik Bengtsson, Pierre Neuvial

Examples

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Simulating copy-number data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
set.seed(0xBEEF)

# Number of loci
J <- 1000

mu <- double(J)
mu[1:100] <- mu[1:100] + 0.3
mu[200:300] <- mu[200:300] + 1
mu[350:400] <- NA # centromere
mu[650:800] <- mu[650:800] - 1
eps <- rnorm(J, sd=1/2)
y <- mu + eps
x <- sort(runif(length(y), max=length(y))) * 1e5
w <- runif(J)
w[650:800] <- 0.001


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Segmentation
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fit <- segmentByCBS(y, x=x)
print(fit)
plotTracks(fit)

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Post-segmentation pruning
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fitP <- pruneBySdUndo(fit, rho=1)
drawLevels(fitP, col="red")

Sets and resets the .Random.seed in the global environment

Description

Sets and resets the .Random.seed in the global environment.

Usage

 randomSeed(action=c("set", "advance", "reset", "get"), seed=NULL, kind=NULL, n=1L,
  backup=TRUE)

Arguments

Value

Returns a .Random.seed. If more than one is returned, the they are returned as a list.

Author(s)

Henrik Bengtsson

Generates a report of the segmentation results

Description

Generates a report of the segmentation results. Currently reports can be generated for segmentation results of class CBS and PairedPSCBS.

Usage

## S3 method for class 'AbstractCBS'
report(fit, sampleName=getSampleName(fit), studyName, ..., rspTags=NULL,
  rootPath="reports/", .filename="*", skip=TRUE, envir=new.env(), verbose=FALSE)

Arguments

Value

Returns the pathname of the generated PDF.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Reset the segments

Description

Reset the segments. More precisely, it removes columns in the segmentation result table that have been added by methods after the actual segmentation method, e.g. bootstrap estimated mean level quantiles and various calls. It leave the basic segmentation results untouched, i.e. the partitioning and the segment means.

Usage

## S3 method for class 'AbstractCBS'
resetSegments(fit, ...)

Arguments

Value

Returns an object if the same class as the input result.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS.

Segment genomic signals using the CBS method

Description

Segment genomic signals using the CBS method of the DNAcopy package. This is a convenient low-level wrapper for the DNAcopy::segment() method. It is intended to be applied to a sample at the time. For more details on the Circular Binary Segmentation (CBS) method see [1,2].

Usage

## Default S3 method:
segmentByCBS(y, chromosome=0L, x=NULL, index=seq_along(y), w=NULL, undo=0,
  avg=c("mean", "median"), ..., joinSegments=TRUE, knownSegments=NULL, seed=NULL,
  verbose=FALSE)

Arguments

Details

Internally segment of DNAcopy is used to segment the signals. This segmentation method support weighted segmentation.

Value

Returns a CBS 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.

Missing and non-finite values

Signals may contain missing values (NA or NaN), but not infinite values (+/-Inf). Loci with missing-value signals are preserved and keep in the result.

Likewise, genomic positions may contain missing values. However, if they do, such loci are silently excluded before performing the segmentation, and are not kept in the results. The mapping between the input locus-level data and ditto of the result can be inferred from the index column of the locus-level data of the result.

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

Author(s)

Henrik Bengtsson

References

[1] A.B. Olshen, E.S. Venkatraman (aka Venkatraman E. Seshan), R. Lucito and M. Wigler, Circular binary segmentation for the analysis of array-based DNA copy number data, Biostatistics, 2004
[2] E.S. Venkatraman and A.B. Olshen, A faster circular binary segmentation algorithm for the analysis of array CGH data, Bioinformatics, 2007

See Also

To segment allele-specific tumor copy-number signals from a tumor with a matched normal, see segmentByPairedPSCBS(). For the same without a matched normal, see segmentByNonPairedPSCBS().

It is also possible to prune change points after segmentation (with identical results) using pruneBySdUndo().

Examples

 
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Simulating copy-number data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
set.seed(0xBEEF)

# Number of loci
J <- 1000

mu <- double(J)
mu[200:300] <- mu[200:300] + 1
mu[350:400] <- NA # centromere
mu[650:800] <- mu[650:800] - 1
eps <- rnorm(J, sd=1/2)
y <- mu + eps
x <- sort(runif(length(y), max=length(y))) * 1e5
w <- runif(J)
w[650:800] <- 0.001


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Segmentation
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fit <- segmentByCBS(y, x=x)
print(fit)
plotTracks(fit)


     
xlab <- "Position (Mb)"
ylim <- c(-3,3)
xMb <- x/1e6
plot(xMb,y, pch=20, col="#aaaaaa", xlab=xlab, ylim=ylim)
drawLevels(fit, col="red", lwd=2, xScale=1e-6)

 
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# TESTS
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fit <- segmentByCBS(y, x=x, seed=0xBEEF)
print(fit)
##   id chromosome       start      end nbrOfLoci    mean
## 1  y          0    55167.82 20774251       201  0.0164
## 2  y          0 20774250.85 29320105        99  1.0474
## 3  y          0 29320104.86 65874675       349 -0.0227
## 4  y          0 65874675.06 81348129       151 -1.0813
## 5  y          0 81348129.20 99910827       200 -0.0612


# Test #1: Reverse the ordering and segment
fitR <- segmentByCBS(rev(y), x=rev(x), seed=0xBEEF)
# Sanity check
stopifnot(all.equal(getSegments(fitR), getSegments(fit)))
# Sanity check
stopifnot(all.equal(rev(getLocusData(fitR)$index), getLocusData(fit)$index))

# Test #2: Reverse, but preserve ordering of 'data' object
fitRP <- segmentByCBS(rev(y), x=rev(x), preserveOrder=TRUE)
stopifnot(all.equal(getSegments(fitRP), getSegments(fit)))


# (Test #3: Change points inbetween data points at the same locus)
x[650:654] <- x[649]
fitC <- segmentByCBS(rev(y), x=rev(x), preserveOrder=TRUE, seed=0xBEEF)

# Test #4: Allow for some missing values in signals
y[450] <- NA
fitD <- segmentByCBS(y, x=x, seed=0xBEEF)


# Test #5: Allow for some missing genomic annotations
x[495] <- NA
fitE <- segmentByCBS(y, x=x, seed=0xBEEF)


# Test #6: Undo all change points found
fitF <- segmentByCBS(y, x=x, undo=Inf, seed=0xBEEF)
print(fitF)
stopifnot(nbrOfSegments(fitF) == 1L)


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# MISC.
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Emulate a centromere
x[650:699] <- NA
fit <- segmentByCBS(y, x=x, seed=0xBEEF)
xMb <- x/1e6
plot(xMb,y, pch=20, col="#aaaaaa", xlab=xlab, ylim=ylim)
drawLevels(fit, col="red", lwd=2, xScale=1e-6)

fitC <- segmentByCBS(y, x=x, joinSegments=FALSE, seed=0xBEEF)
drawLevels(fitC, col="blue", lwd=2, xScale=1e-6)



# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Multiple chromosomes
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Appending CBS results
fit1 <- segmentByCBS(y, chromosome=1, x=x)
fit2 <- segmentByCBS(y, chromosome=2, x=x)
fit <- c(fit1, fit2)
print(fit)
plotTracks(fit, subset=NULL, lwd=2, Clim=c(-3,3))


# Segmenting multiple chromosomes at once
chromosomeWG <- rep(1:2, each=J)
xWG <- rep(x, times=2)
yWG <- rep(y, times=2)
fitWG <- segmentByCBS(yWG, chromosome=chromosomeWG, x=xWG)
print(fitWG)
plotTracks(fitWG, subset=NULL, lwd=2, Clim=c(-3,3))

# Assert same results
fit$data[,"index"] <- getLocusData(fitWG)[,"index"] # Ignore 'index'
stopifnot(all.equal(getLocusData(fitWG), getLocusData(fit)))
stopifnot(all.equal(getSegments(fitWG), getSegments(fit)))

Segment total copy numbers and allele B fractions using the Non-paired PSCBS method

Description

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

Usage

## Default S3 method:
segmentByNonPairedPSCBS(CT, betaT, ..., flavor=c("tcn", "tcn&dh", "tcn,dh",
  "sqrt(tcn),dh", "sqrt(tcn)&dh"), tauA=NA, tauB=1 - tauA, verbose=FALSE)

Arguments

Details

Internally segmentByPairedPSCBS() is used for segmentation. This segmentation method does not support weights.

Value

Returns the segmentation results as a NonPairedPSCBS 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 chromosome 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.

Non-Paired PSCBS with known genotypes

If allele B fractions for the matched normal (betaN) are not available, but genotypes (muN) are, then it is possible to run Paired PSCBS. See segmentByPairedPSCBS() for details.

Author(s)

Henrik Bengtsson

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

To segment paired tumor-normal total copy numbers and allele B fractions, see segmentByPairedPSCBS().

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

Examples

verbose <- R.utils::Arguments$getVerbose(-10*interactive(), timestamp=TRUE)

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Load SNP microarray data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
data <- PSCBS::exampleData("paired.chr01")
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=20),]

str(dataS)

R.oo::attachLocally(dataS)

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


# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Bootstrap segment level estimates
# (used by the AB caller, which, if skipped here,
#  will do it automatically)
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
fit <- bootstrapTCNandDHByRegion(fit, B=100, verbose=verbose)
print(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=verbose)
print(deltaAB)

fit <- callAB(fit, delta=deltaAB, verbose=verbose)
print(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=verbose)
print(deltaLOH)

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

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

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

## Default S3 method:
segmentByPairedPSCBS(CT, thetaT=NULL, thetaN=NULL, betaT=NULL, betaN=NULL, muN=NULL,
  rho=NULL, chromosome=0, x=NULL, alphaTCN=0.009, alphaDH=0.001, undoTCN=0, undoDH=0,
  ..., avgTCN=c("mean", "median"), avgDH=c("mean", "median"),
  flavor=c("tcn&dh", "tcn,dh", "sqrt(tcn),dh", "sqrt(tcn)&dh", "tcn"), tbn=is.null(rho),
  joinSegments=TRUE, knownSegments=NULL, dropMissingCT=TRUE, seed=NULL, verbose=FALSE,
  preserveScale=FALSE)

Arguments

Details

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

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

Author(s)

Henrik Bengtsson

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 tumor total copy numbers and allele B fractions without a matched normal, see segmentByNonPairedPSCBS().

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

Examples

verbose <- R.utils::Arguments$getVerbose(-10*interactive(), timestamp=TRUE)

# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Load SNP microarray data
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
data <- PSCBS::exampleData("paired.chr01")
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=10),]

str(dataS)

R.oo::attachLocally(dataS)

# Paired PSCBS segmentation
fit <- segmentByPairedPSCBS(CT, betaT=betaT, betaN=betaN,
                            chromosome=chromosome, x=x,
                            seed=0xBEEF, verbose=verbose)
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, B=100, verbose=verbose)
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=verbose)
print(deltaAB)
## [1] 0.1657131

fit <- callAB(fit, delta=deltaAB, verbose=verbose)
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=verbose)
print(deltaLOH)
## [1] 0.625175

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

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

Sets the name of the sample segmented

Description

Sets the name of the sample segmented.

Usage

## S3 method for class 'AbstractCBS'
setSampleName(fit, name, ...)

Arguments

Value

Returns (invisibly) an updated object.

Author(s)

Henrik Bengtsson

See Also

For more information see AbstractCBS..

Tests if a segment is in Run-of-Homozygosity (ROH)

Description

Tests if a segment is in Run-of-Homozygosity (ROH).

Usage

## S3 method for class 'numeric'
testROH(muN, csN=NULL, betaN=NULL, minNbrOfSnps=1, delta=1/12, ..., verbose=FALSE)

Arguments

Value

Returns a logical.

Author(s)

Pierre Neuvial, Henrik Bengtsson

Updates the CN mean levels for each segment independently

Description

Updates the CN mean levels for each segment independently as if they were one large segment. The locus-level data is not updated/modified.

Usage

## S3 method for class 'AbstractCBS'
updateMeans(...)

Arguments

Value

Returns an object of the same class.

Author(s)

Henrik Bengtsson

Updates the CN mean levels jointly in sets of segments

Description

Updates the CN mean levels jointly in sets of segments as if they were one large segment. The locus-level data is not updated/modified.

Usage

## S3 method for class 'AbstractCBS'
updateMeansTogether(...)

Arguments

Value

Returns an object of the same class.

Author(s)

Henrik Bengtsson

See Also

This method is utilized by *pruneByHClust().

Weighted Quantile Value

Description

Computes a weighted quantile of a numeric vector.

Usage

## Default S3 method:
weightedQuantile(x, w, probs=c(0, 0.25, 0.5, 0.75, 1), na.rm=TRUE,
  method=c("wtd.quantile"), ...)

Arguments

Value

Returns the weighted quantile.

Author(s)

Henrik Bengtsson

See Also

Internally the following functions may be used: quantile (if no weights are specified), or an internal copy of Hmisc::wtd.quantile(). For a weighted median estimator, weightedMedian of the matrixStats package.

Writes the table of segments to file

Description

Writes the table of segments to file.

Usage

## S3 method for class 'CBS'
writeSegments(fit, name=getSampleName(fit), tags=NULL, ext="tsv", path=NULL,
  addHeader=TRUE, createdBy=NULL, sep="\t", nbrOfDecimals=4L, splitters=FALSE,
  overwrite=FALSE, skip=FALSE, ...)

Arguments

.

Value

Returns the pathname of the the file written.

Author(s)

Henrik Bengtsson

See Also

Utilizes *getSegments(). For more information see CBS..

Writes the table of segments to file

Description

Writes the table of segments to file.

Usage

## S3 method for class 'PSCBS'
writeSegments(fit, name=getSampleName(fit), tags=NULL, ext="tsv", path=NULL,
  addHeader=TRUE, createdBy=NULL, sep="\t", nbrOfDecimals=4L, splitters=FALSE,
  overwrite=FALSE, skip=FALSE, ...)

Arguments

.

Value

Returns the pathname of the the file written.

Author(s)

Henrik Bengtsson

See Also

Utilizes *getSegments(). For more information see PSCBS..