addPloidyData

Description

This function is used to append your ploidy data onto the sample component matrix. The function is called in runPipeline if you specify ploidy as a desired feature and give a vector of ploidy values.

Usage

addPloidyData(scm, ploidyData)

Arguments

Value

Returns scm including the ploidy data

Components derived from TCGA

Description

These generated components were derived from all of the copy number data available from TCGA. It is meant to be used to look for signatures in cancer data so that you do not have to model new data, and so that you can easily compare signatures

Usage

cancerComps

Format

A list with 6 flexmix objects:

segsize

Mixture of normal distributions

bp10MB

Mixture of normal distributions

osCN

Mixture of poisson distributions

changepoint

Mixture of normal distributions

copynumber

Mixture of normal distributions

bpchrarm

Mixture of poisson distributions

Signatures derived from TCGA

Description

These signatures were derived from all of the copy number data available from TCGA. It is meant to be used so that you can compare newly found signatures to these described signatures. There are a total of 25 signatures. The components used to derive these signatures can be found in the cancerComps variable.

Usage

cancerSigs

Format

An object of class matrix (inherits from array) with 28 rows and 25 columns.

checkCompOverlap

Description

This function is used to check for overlapping components and remove them if they overlap. The mixed modeling can sometimes run into an error in which it produces multiple essentially identical components. This function attempts to find and remove these duplicates.

Usage

checkCompOverlap(comps, pois = FALSE)

Arguments

Value

Returns a components with no overlaps

Signatures derived from TCGA and collapsed.

Description

These signatures were derived from all of the copy number data available from TCGA. These pan-cancer signatures were collapsed by similarity to a total of 13 signatures and were built using ploidy data. It is meant to be used so that you can compare newly found signatures to these described signatures.

Usage

collapsedSigs

Format

An object of class data.frame with 29 rows and 13 columns.

compareExposures

Description

This function is used to check two signature sets in order to compare how the samples exposures differ across the two runs.

Usage

compareExposures(reference, toCompare)

Arguments

Value

Prints out the difference in signature exposures

Examples

compareExposures(referenceExp, referenceExp)

Components fitted onto featsExp

Description

The generated components for the segDataExp dataset. Generated using the function fitModels(featsExp). Each data frame has a value and a ID column. The ID tells you which sample the observed value is from.

Usage

compsExp

Format

A list with 6 flexmix objects:

segsize

Mixture of normal distributions

bp10MB

Mixture of normal distributions

osCN

Mixture of poisson distributions

changepoint

Mixture of normal distributions

copynumber

Mixture of normal distributions

bpchrarm

Mixture of poisson distributions

createSigs

Description

This function is used to create the final signatures and generates the resulting NMF object, from which you can extract the feature contribution to each signature using NMF::basis(), and the signature contribution of each sample by using NMF::scoef()

Usage

createSigs(scm, nsig, cores = 1, runName = "", saveRes = FALSE, saveDir = NULL)

Arguments

Value

Returns the resulting NMF object

Examples

createSigs(scmExp,5) #Generates 5 signatures from the SCM

Default features to use for copy number signatures

Description

These are the default features that are used in the package. Use this to get a list of the feature names and you can remove values from this and pass it in to the package using the featsToUse parameter seen in multiple functions.

Usage

defaultFeats

Format

An object of class character of length 6.

detSigNumPipeline

Description

This function allows you to run the Copy number signature pipeline up until the determineSigNum call. This is useful if you want to repeteadly check the optimal number of signatures for different sample sets. May take a while, especially if not given multiple cores.

Usage

detSigNumPipeline(
  segData,
  cores = 1,
  components = NULL,
  saveRes = FALSE,
  runName = "Run",
  rmin = 3,
  rmax = 12,
  max_comps = NULL,
  min_comps = NULL,
  saveDir = NULL,
  smooth = FALSE,
  colMap = NULL,
  pR = FALSE,
  gbuild = "hg19",
  featsToUse = NULL,
  ploidyData = NULL
)

Arguments

Value

Returns a list with all of the results from the pipeline

Examples

#Runs the entire pipeline on the example data giving it 6 cores and specifying
#5 signatures with a name of "TCGA Test"

detSigNumPipeline(segDataExp, cores = 6, saveRes = FALSE, runName = "TCGA Test")

determineNumSigs

Description

This function uses the extracted features and modelled components, and it performs NMF on these ranging from the minimum number of signatures to the max. It repeats this on randomized data and computes various measures to help inform the user on how many signatures to proceed with. This function may take a while to run since it repeats the NMF process many times. It is suggested to give it multiple cores to allow for parallel processing.

Usage

determineNumSigs(
  scm,
  rmin = 3,
  rmax = 12,
  cores = 1,
  nrun = 250,
  saveRes = FALSE,
  saveDir = NULL,
  runName = ""
)

Arguments

Value

Creates a series of plots to help user decide

Examples

determineNumSigs(generateSCM(featsExp,compsExp))

diffCompSigSim

Description

This function is used to determine the similarity between two signatures that have different underlying components. Uses ks-statistic based measure to estimate similarity for normal distribution based components and uses a correlation measure when comparing poisson distribution based components.

Usage

diffCompSigSim(refComps, refWeights, valComps, valWeights)

Arguments

Value

Returns a correlation value

extractCNFeats

Description

This function is used to extract the six copy number features that are eventually used in order to make the signatures. It does this using six sub functions to extract each feature. Before extracting the features, the segments are passed through a validation function to make sure the data is formatted correctly and there are no invalid segments. Can be done in parallel using the cores parameter.

Usage

extractCNFeats(
  segData,
  gbuild = "hg19",
  cores = 1,
  featsToExtract = CNSigs::defaultFeats
)

Arguments

Value

list of dataframes containing results of six copy number features

Examples

extractCNFeats(segDataExp)

featureFuncs

Description

This group of functions return vectors of the corresponding features for the samples passed in. Some of the functions use internal datasets to the CNSig package that specify the chromosome lengths and the centromere positions.

Usage

extractSegsize(segData)

extractBP10MB(segData, chrlen)

extractOscillations(segData, chrlen)

extractBPChrArm(segData, centromeres, chrlen)

extractChangepoints(segData, centromeres, chrlen)

extractCN(segData)

Arguments

extractSegsize

This function returns a vector of all the segment sizes for all for all of the samples.

extractBP10MB

This function returns a vector of the average number of breakpoints in a per 10MB for each chromosome.

extractOscillations

This function returns a vector of number of oscillation events found on each of the chromosomes.

getBPChrArm

This function returns a vector of number of total breakpoints per chromosome arm.

extractChangepoints

This function returns a vector of average size of changepoints per chromosome

extractCN

This function returns a vector of average copynumber per chromosome

Features from segDataExp

Description

The extracted features from the segDataExp dataset. Generated using the function extractCNFeats(segDataExp). Each data frame has a value and a ID column. The ID tells you which sample the observed value is from.

Usage

featsExp

Format

A list with 6 data frames:

segsize

Size of every segment

bp10MB

Average # of breakpoints per 10MB per chromosome

osCN

Number of oscillation events per chromosome

changepoint

Average changepoint per chromosome

copynumber

Average copy number per chromosome

bpchrarm

Number of breakpoints per chromosome arm

findExposures

Description

This function is used to find the signature exposures of a set of samples using fixed signatures found earlier. It does this using the least squares optimization method with constraints to keep the output as non-negative using the lsei function from the package limSolve.

Usage

findExposures(scm, fixedSigs, runName = "", saveRes = FALSE, saveDir = NULL)

Arguments

Value

Returns the resulting matrix of exposures

Examples

findExposures(t(scmExp), sigsExp)

fitComponent

Description

This function is used to fit a mixture model of either normal or poisson distributions to the inpput data. This function is mainly used by the fitModels function to create the components from the extracted features.

Usage

fitComponent(
  toFit,
  min_prior = 0.001,
  min_comp = 2,
  max_comp = 10,
  dist = "norm",
  pR = FALSE,
  seed = 77777,
  model_sel = "BIC",
  niter = 10000,
  nrep = 1
)

Arguments

Value

Returns the flexmix object for the fit model.

Examples

fitComponent(featsExp$bp10MB[,2]) #Fits 2-10 normal distributions

#Tries to fit exactly 4 poisson distributions
fitComponent(featsExp$osCN[,2],dist="pois",min_comp = 4, max_comp = 4)

fitModels

Description

This function takes all of the extracted copy number features and attempts to fit a mixture of poisson and normal distributions to the data, and returns a mixture of components that can be used to build the signatures. The order of features is "segsize","bp10MB","osCN","changepoint","copynumber","bpchrarm". Therefore if you only want to change the maximum number of components for osCN to 5 then you would use max_comps = c(10,10,5,10,10,10).

Usage

fitModels(
  CN_features,
  max_comps = NULL,
  min_comps = NULL,
  cores = 1,
  pR = FALSE,
  min_prior = NULL,
  featsToModel = CNSigs::defaultFeats
)

Arguments

Value

Returns a list of the different components that contain flexmix objects for each feature

Examples

fitModels(featsExp)

#Models an exact number of components, useful when comparing two different
#datasets
min_comps = c(7, 3, 3, 2, 2, 3)
max_comps = c(7, 3, 3, 2, 10, 3)
fitModels(featsExp, max_comps, min_comps)

generateSCM

Description

This function takes in an extracted set of features and a defined set of components, and calculates the sum of the posterior probabilities for each feature. This sum represents how much each component contributes to a sample and corresponds to one column in the matrix.

Usage

generateSCM(feats, comps, runName = "", saveRes = FALSE, saveDir = NULL)

Arguments

Value

Creates a sample by component matrix

Examples

generateSCM(featsExp,compsExp)

matchSigs

Description

This function is used to check to find a mapping between two similar sets of signatures. It compares the signature values to see how similar the proposed signatures are and shows you the best matches. It uses the measure of cosine similarity to compare signatures. The two signature sets must have the same underlying components to be matched.

Usage

matchSigs(referenceSigs, toCompareSigs)

Arguments

Value

Prints out the signature mapping and returns the avg similarity

Examples

matchSigs(referenceExp$sigs, referenceExp$sigs)

plotComp

Description

This function plots the specified mixed model so that it can be visualized. It utilizes the gamma function to allow approximations of the poisson distributions, allowing for a smooth plot.

Usage

plotComp(comps, compName, saveRes = FALSE, saveDir = NULL, runName = "")

Arguments

Value

Plots the components to allow visualization

Examples

plotComp(compsExp, compName = "segsize")

plotComps

Description

This function plots all of the mixed models so that it can be visualized. It utilizes the gamma function to allow approximations of the poisson distributions, allowing for a smooth plot.

Usage

plotComps(comps, saveRes = FALSE, saveDir = NULL, runName = "")

Arguments

Value

Plots all the components to allow visualization

Examples

plotComps(compsExp)

plotScm

Description

This function is used to generate the sample by component matrix plot.

Usage

plotScm(
  scm,
  runName = "",
  saveRes = FALSE,
  saveDir = NULL,
  rowOrder = FALSE,
  colOrder = TRUE
)

Arguments

Value

pheatmap figure of component result by sample

Examples

plotScm(scmExp)

plotScm(scmExp, rowOrder = FALSE, colOrder = FALSE)

newOrder = sample(1:ncol(scmExp), ncol(scmExp))
plotScm(scmExp, colOrder = newOrder)

plotSegs

Description

This function is used to create a plot of a samples segs. The input samples can either be a single data.frame of the segs of one patient or a list of data.frames for multiple samples.

Usage

plotSegs(
  samples,
  name = "",
  chrom = -1,
  gbuild = "hg19",
  sep = FALSE,
  alpha = 1
)

Arguments

Value

displays a plot of the segments

Examples

plotSegs(segDataExp[[1]]) #Plots all of the first sample's segments
plotSegs(segDataExp[[1]],1) #Only plots the first chromosome segments
plotSegs(segDataExp[1:2]) #Plots first two samples on same axis
plotSegs(segDataExp[1:2], sep = TRUE) #Plots first two samples seperately

plotSig

Description

This function is used to create a plot for the specified signature to look at the contribution of each of the components to the signatures

Usage

plotSig(sigs, sigNum)

Arguments

Value

displays a plot of the signature

Examples

plotSig(referenceExp$sigs, 1) #Plots first signature

plotSigExposure

Description

This function plots the signature exposure for all of the samples as a stacked bar plot. There are a number of different options for how to sort the resulting plot.

Usage

plotSigExposure(
  sigExposure,
  saveRes = FALSE,
  saveDir = NULL,
  runName = "",
  trackData = NULL,
  sort = FALSE,
  sortOrder = "m",
  method = NULL,
  colors = NULL
)

Arguments

Details

Adding data tracks to the plot: One of the major features of this function is that it allows the user to add in some additional data for the samples to be plotted as a track alongside the main signature exposure stacked bar plot. These additional data points can be passed in as a vector of corresponding values in the same order. If you want to plot multiple tracks you can pass in a list of vectors using the trackData parameter.

Specifying how to sort the plot: When you give the function a set of trackData, it allows you to begin to specify the sortOrder. This allows your to sort the main plot in a different order. "m" represents the main plot, and "t" followed by the number of the track (ie: "t1","t2" ...) represents the tracks. By chaining the values together you can specify a variety of ways to sort the final plot. As an example, the sortOrder of "mt1t2" specifies the the plot should be sorted by the signature exposures first followed by the first track and finally the second track. In another example, the sortOrder of "t2mt1" specifies the plot to be sorted by track number 2 first followed by the signature exposures and lastly by track number 1.

Sorting method: The two methods of sorting the signature exposure are either "hclust" or "group". The hclust uses the ward.D method to cluster the exposures and then cuts the tree to split the data. The group method splits the samples into groups based on which signatures they had the highest exposure to.

Value

Plots the signature exposure to allow visualization

Examples

plotSigExposure(sigExposExp)

plotSigExposureMat

Description

This function is used to generate the signature exposure matrix heatmap plot.

Usage

plotSigExposureMat(
  sigExposure,
  runName = "",
  saveRes = FALSE,
  saveDir = NULL,
  rowOrder = FALSE,
  colOrder = TRUE
)

Arguments

Value

pheatmap figure of signature exposure by patient

Examples

plotSigExposureMat(sigExposExp)

plotSigExposureMat(sigExposExp, rowOrder = FALSE, colOrder = FALSE)

newOrder = sample(1:ncol(sigExposExp), ncol(sigExposExp))
plotSigExposureMat(sigExposExp, colOrder = newOrder)

plotSigMat

Description

This function is used to generate the signature by component matrix plot.

Usage

plotSigMat(sigs, runName = "", saveRes = FALSE, saveDir = NULL)

Arguments

Value

pheatmap figure of component weights by sample

Examples

plotSigMat(sigsExp)

plotSigs

Description

This function plots all of the signatures so that they can be visualized. It does this by looping through the signatures and calling the plotSig function

Usage

plotSigs(sigs, saveRes = FALSE, saveDir = NULL, runName = "")

Arguments

Value

Plots all the signatures to allow visualization

Examples

plotSigs(referenceExp$sigs)

postProb

Description

This function calculates the probabilities that each of the new data point falls into the distributions defined by the parameters. Used when calculating the sample by component matrix.

Usage

postProb(params, newData)

Arguments

Value

Returns the probability that the newData is in the distributions

readSegs

Description

This function is used to read in the segments. It can either take a file path to a csv to read in the data, or it can take in a long data frame and convert it to the format needed for the pipeline. The variable colMap is used in order to map your column names to what the pipeline expects. For instance, if your column that has the chromosome numbers in it is titled "chrom" instead of the expected "chromosome" then you would specify the colMap as c("ID","chrom","start","end","segVal"). If your data is seperated into major and minor allele copy numbers then for the segVal part of the colMap should be formatted as "nMajor+nMinor" to let the function know to add them together.

Usage

readSegs(path, colMap = NULL, readPloidy = FALSE)

Arguments

Value

Returns a segments in a list formatted to be run through the pipeline

reducePeaks

Description

This function is used to reduce the peaks within a feature distribution so that the models can be fitted properly. The flexmix package can struggle to converge on a solution if there are large spikes in the distribution.

Usage

reducePeaks(toReduce)

Arguments

Value

Returns the input feature with the peaks reduced

The result object from Pipeline using segDataExp.

Description

The generated result object from the entire pipelin using the segDataExp. Function used to create: referenceExp = runPipeline(segDataExp,nsigs = 5)

Usage

referenceExp

Format

A list with 7 elements:

func

The function call used in the pipeline run

Input_data

The data the features were extracted from

CN_features

The extracted features

CN_components

The fitted component models

scm

The sample by component matrix

nmf_Results

The results of the NMF run

sigs

The signature by component matrix.

remapResults

Description

This function is used to remap the results from a runPipeline run with a different order of the signatures or different names. You can either give the function a new mapping of the signatures which is just a new order in which you want the signatures in. For instance, if you want to just swap the first and second signatures and you have a total of 4 signatures, you would pass in c(2,1,3,4) for the sigMap parameters. The other use case is if you want to rename the signatures. To do this you just have to pass a vector of names that is of the same length as the number of signatures.

Usage

remapResults(path, sigMap = NULL, sigNames = NULL, saveRes = FALSE)

Arguments

Details

Overall, this function will create a duplicate results folder in the same directory and regenerate all of the plots and result files into the new order or with the new names. This means that you don't have to regenerate all of the plots manually.

Value

no return

runPipeline

Description

This function allows you to run the entire Copy number signature pipeline in one go. May take a while, especially if not given multiple cores. For more information on what actually happens in the pipeline, refer to the CNSigs vignette.

Usage

runPipeline(
  segData,
  cores = 1,
  nsigs = 0,
  saveRes = FALSE,
  runName = "Run",
  rmin = 3,
  rmax = 12,
  components = NULL,
  max_comps = NULL,
  min_comps = NULL,
  fixedSigs = NULL,
  saveDir = NULL,
  smooth = FALSE,
  colMap = NULL,
  pR = FALSE,
  gbuild = "hg19",
  featsToUse = NULL,
  ploidyData = NULL,
  plot = TRUE
)

Arguments

Value

Returns a list with all of the results from the pipeline

Examples

#Runs the entire pipeline on the example data giving it 6 cores and specifying
#5 signatures with a name of "TCGA Test"

runPipeline(segDataExp, cores = 6, nsigs = 5, saveRes = FALSE, "TCGA Test")

Sample by component matrix for segDataExp

Description

The generated scm for the segDataExp dataset. Generated using the function generateSCM(featsExp,compsExp). It is a matrix showing how much each extracted component contributes to each sample. Is what is put into NMF and used to create the signatures.

Usage

scmExp

Format

An object of class matrix (inherits from array) with 20 rows and 20 columns.

Segmentation Data from TCGA BRCA samples

Description

A small example subset of BRCA samples from TCGA in list format. Each item contains the segmentation data for that sample.

Usage

segDataExp

Format

A list with 20 elements and 5 variables:

ID

ID number for the sample

chromosome

chromosome the segment is found on

start

starting position of the segment

end

end position of the segment

segVal

copynumber value for the segment

Source

https://portal.gdc.cancer.gov/

segStats

Description

This function allows you to get an overview of some of the features of your samples. It outputs a summary of stats for the segments, including size, number per sample, along with various other measures.

Usage

segStats(segTabs)

Arguments

Value

Outputs a summary of the statistics

Examples

segStats(segDataExp)

The generated sigExposure from the segDataExp run

Description

The generated signature exposure matrix for the segDataExp dataset. Extracted from the referenceExp data object using referenceExp$sigExposure. This matrix shows how much each signature contributes to the patient samples.

Usage

sigExposExp

Format

An object of class data.frame with 5 rows and 20 columns.

sigSim

Description

This function is used to compare two sets of signatures by finding the similarity matrix across both signature sets. If the signatures have the same underlying components similarity is calculated using the cosine similarity. If the signatures have different underlying components the similarity is estimated using a ks-statistic based measure. See package vignette for more information.

Usage

sigSim(reference, toCompare, plot = TRUE, text = TRUE)

Arguments

Value

Plots signature similarity and returns the avg similarity

Examples

sigSim(referenceExp, referenceExp)

The generated Signatures from the segDataExp run

Description

The generated signature by component matrix for the segDataExp dataset. Extracted from the referenceExp data object using referenceExp$sigs. This matrix shows how much each component contributes to the signatures.

Usage

sigsExp

Format

An object of class matrix (inherits from array) with 20 rows and 5 columns.

smoothSegs

Description

This function is used to attempt to smooth the input copy number segments in order to reduce the biasing affect of the technology and copy number caller used to make the segments. It does this by trying to join together close segs and removing small abbarent segments.

Usage

smoothSegs(segData, cores = 1)

Arguments

Value

Returns the smoothed segments

Examples

smoothSegs(segDataExp)

sumOfPosteriors

Description

This function is used to calculate the sum of posteriors for a given feature. It returns a vector of posterior probabilities which describe how much each component contributes to the distribution of features passed in.

Usage

sumOfPosteriors(feat, comps, name)

Arguments

Value

Returns the sum of the posteriors for the specified feature.

validateSegData

Description

This function is used to validate and clean up all of the input data. It converts all the columns to numeric that need to be, and filters out any invalid segments, like ones with 0 or negative length. It also converts the chromosome tags to the proper format for feature extraction.

Usage

validateSegData(segData, cores = 1)

Arguments

Value

list of dataframes containing converted seg data

Examples

validateSegData(segDataExp)