CancerEngine-class {Umpire}

The "CancerEngine" Class

Description

A CancerEngine combines a CancerModel (which defines the combinatorics of hits that produce cancer subtypes) with a pair of gene expression Engines that can be used to simulate microarray data depending on the presence or absence of different hits.

Usage

CancerEngine(cm, base, altered)
## S4 method for signature 'CancerEngine'
summary(object, ...)
## S4 method for signature 'CancerEngine'
nrow(x)
## S4 method for signature 'CancerEngine'
nComponents(object, ...)
## S4 method for signature 'CancerEngine'
rand(object, n, ...)
ClinicalEngine(nFeatures, nClusters, isWeighted,
               bHyp = NULL, survivalModel = NULL,
               SURV = function(n) rnorm(n, 0, 0.3),
               OUT = function(n) rnorm(n, 0, 0.3))

Arguments

cm

object of class CancerModel

base

character string giving the name of an Engine or EngineWithActivity, or an object of class Engine. Represents the expected gene expression in the absence of any hits.

altered

character string giving the name of an Engine or EngineWithActivity, or an object of class Engine. Represents the expected gene expression in the presence of hits.

object

object of class CancerEngine

x

object of class CancerEngine

n

numeric scalar representing number of samples to be simulated

...

extra arguments for generic routines

nFeatures

an integer; the number of simulated clinical features

nClusters

an integer; the number of simulated clusters or subtypes

isWeighted

a logical value; used to determine whether the prevalence of subtypes is equal (unweighted) or unequal (weighted).

bHyp

an object of the class BlockHyperParameters. If NULL, then it is constructed using the default clinical parameters. See the Values section below.

survivalModel

an object of the SurvivalModel class. If NULL, then it is constructed using the default parameters.

SURV

a function; the same as used in a CancerModel.

OUT

a function; the same as used in a CancerModel.

Objects from the Class

Although objects of the class can be created by a direct call to new, the preferred method is to use the CancerEngine or ClinicalEngine generator functions.

Slots

cm:

A CancerModel object.

base:

Object of class "character" giving the name of an Engine or EngineWithActivity. Represents the expected gene expression in the absence of any hits.

altered:

Object of class "character" giving the name of an Engine or EngineWithActivity. Represents the expected gene expression in the presence of hits.

localenv:

Object of class "environment"; used in the internal implementation.

Methods

rand

signature(object = "CancerEngine"): returns a list containing two named components, clinical and data, The clinical element is a data frame generated from the underlying CancerModel, and the data element is a matrix generated by the gene expression engines, altered by the appropriate "hits" present in each simulated individual.

summary

signature(object = "CancerEngine"): print summaries of the underlying cancer models and gene expression engines in the cancer engine.

Values

Both the CancerEngine and ClinicalEngine constructors return objects of the CancerEngine class. The only practical differences are the default parameters set by the constructors. The primary change is in the CancerModel slot. The CancerEngine expects you to construct your own CancerModel explicitly before producing a CancerEngine.

By contrast, the ClinicalEngine expects to use many fewer features, so gives a simpler interface and uses its parameters to construct the CancerModel for you. The "HIT" function will use 2 hits per subtype when there are fewer than 15 features, 3 hits between 15 and 45 features, and the older default of 5 hits when there are more than 45 features. The total number of possible hits is set equal to the number of features (N) when there are fewer than 12 features, approximately N/3 up to 50 features, approximately N/5 up to 100, and is then locked at 20. If isWeighted is TRUE, subtype prevalences are chosen from a Dirichlet distribution. Otherwise, each subtype is equally likely.

The nrow and nComponents methods both return non-negative integer values describing the number of rows (features) and the number of components of the underlying gene expression or clinical data Engines. The rand method returns a matrix with n columns of smiulated data.

Author(s)

Kevin R. Coombes [e-mail], Caitlin E. Coombes [e-mail]

References

Zhang J, Coombes KR.
Sources of variation in false discovery rate estimation include sample size, correlation, and inherent differences between groups.
BMC Bioinformatics. 2012; 13 Suppl 13:S1.

See Also

CancerModel

Examples

showClass("CancerEngine")
set.seed(391629)
## Set up survival outcome; baseline is exponential
sm <- SurvivalModel(baseHazard=1/5, accrual=5, followUp=1)
## Build a CancerModel with 6 subtypes
nBlocks <- 20    # number of possible hits
cm <- CancerModel(name="cansim",
                  nPossible=nBlocks,
                  nPattern=6,
                  OUT = function(n) rnorm(n, 0, 1), 
                  SURV= function(n) rnorm(n, 0, 1),
                  survivalModel=sm)
## Include 100 blocks/pathways that are not hit by cancer
nTotalBlocks <- nBlocks + 100
## Assign values to hyperparameters
## block size
blockSize <- round(rnorm(nTotalBlocks, 100, 30))
## log normal mean hypers
mu0    <- 6
sigma0 <- 1.5
## log normal sigma hypers
rate   <- 28.11
shape  <- 44.25
## block corr
p <- 0.6
w <- 5
## Set up the baseline Engine
rho <- rbeta(nTotalBlocks, p*w, (1-p)*w)
base <- lapply(1:nTotalBlocks,
               function(i) {
                 bs <- blockSize[i]
                 co <- matrix(rho[i], nrow=bs, ncol=bs)
                 diag(co) <- 1
                 mu <- rnorm(bs, mu0, sigma0)
                 sigma <- matrix(1/rgamma(bs, rate=rate, shape=shape), nrow=1)
                 covo <- co *(t(sigma) %*% sigma)
                 MVN(mu, covo)
               })
eng <- Engine(base)
## Alter the means if there is a hit
altered <- alterMean(eng, normalOffset, delta=0, sigma=1)
## Build the CancerEngine using character strings
object <- CancerEngine(cm, "eng", "altered")
## Or build it using the actual Engine components
ob <- CancerEngine(cm, eng, altered)
summary(object)
summary(ob)
## Simulate the data
dset <- rand(object, 20)
summary(dset$clinical)
summary(dset$data[, 1:3])