Umpire (version 2.0.11)

MVN-class: The "MVN" Class

Description

The MVN class is a tool used to generate gene expressions that follow multivariate normal distribution.

Usage

MVN(mu, Sigma, tol = 1e-06)
covar(object)
correl(object)
# S4 method for MVN
alterMean(object, TRANSFORM, ...)
# S4 method for MVN
alterSD(object, TRANSFORM, ...)
# S4 method for MVN
nrow(x)
# S4 method for MVN
rand(object, n, ...)
# S4 method for MVN
summary(object, ...)

Arguments

mu

numeric vector representing k-dimensional means

Sigma

numeric k-by-k covariance matrix containing the measurement of the linear coupling between every pair of random vectors

tol

numeric scalar roundoff error that will be tolerated when assessing the singularity of the covariance matrix

object, x

object of class MVN

TRANSFORM

function that takes a vector of mean expression or standard deviation and returns a transformed vector that can be used to alter the appropriate slot of the object.

n

numeric scalar representing number of samples to be simulated

...

extra arguments for generic or plotting routines

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 MVN generator function.

Slots

mu:

numeric vector containing the k-dimensional means

lambda:

numeric vector containing the square roots of the eigenvalues of the covariance matrix

half:

numeric matrix with \(k*k\) dimensions whose columns contain the eigenvectors of the covariance matrix

Methods

alterMean(object, TRANSFORM, ...)

Takes an object of class MVN, loops over the mu slot, alters the mean as defined by TRANSFORM function, and returns an object of class MVN with altered mu.

alterSD(object, TRANSFORM, ...)

Takes an object of class MVN, works on the diagonal matrix of the covariance matrix, alters the standard deviation as defined by TRANSFORM function, and reconstructs an object of class MVN with the old mu and reconstructed covariance matrix.

nrow(x)

Returns the number of genes (i.e, the length of the mu vector).

rand(object, n, ...)

Generates \(nrow(MVN)*n\) matrix representing gene expressions of n samples following the multivariate normal distribution captured in the object of MVN.

summary(object, ...)

Prints out the number of multivariate normal random variables in the object of MVN.

covar(object)

Returns the covariance matrix of the object of class MVN.

correl(object)

Returns the correlation matrix of the object of class MVN.

Author

Kevin R. Coombes , Jiexin Zhang ,

Details

The implementation of MVN class is designed for efficiency when generating new samples, since we expect to do this several times. Basically, this class separates the mvrnorm function from the MASS package into several steps. The computationally expensive step (when the dimension is large) is the eigenvector decomposition of the covariance matrix. This step is performed at construction and the pieces are stored in the object. The rand method for MVN objects contains the second half of the mvrnorm function.

Note that we typically work on expression values after taking the logarithm to some appropriate base. That is, the multivariate normal should be used on the logarithmic scale in order to contruct an engine.

The alterMean method for an MVN simply replaces the appropriate slot by the transformed vector. The alterSD method for an MVN is trickier, because of the way the data is stored. In order to have some hope of getting this correct, we work in the space of the covariance matrix, Sigma. If we let R denote the correlation matrix and let Delta be the diagonal matrix whose entries are the individual standard deviations, then \(Sigma = Delta \%*\% R \%*\% Delta\). So, we can change the standard deviations by replacing Delta in this product. We then construct a new MVN object with the old mean vector and the new covariance matrix.

The covar and correl functions, respectively, calculate the covariance matrix and correlation matrix that underly the covariance matrix for the objects of class MVN. We have four assertions as shown below, which are tested in the examples section:

1. covar should return the same matrix that was used in the function call to construct the MVN object.

2. After applying an alterMean method, the covariance matrix is unchanged.

3. The diagonal of the correlation matrix consists of all ones.

4. After applying an alterMean or an alterSD method, the correlation matrix is unchanged.

See Also

Engine, IndependentNormal

Examples

showClass("MVN")
  if (FALSE) {
tolerance <- 1e-10
## Create a random orthogonal 2x2 matrix
a <- runif(1)
b <- sqrt(1-a^2)
X <- matrix(c(a, b, -b, a), 2, 2)
## Now choose random positive squared-eigenvalues
Lambda2 <- diag(rev(sort(rexp(2))), 2)
## Construct a covariance matrix
Y <- t(X) 
## Use the MVN constructor
marvin <- MVN(c(0,0), Y)
## Check the four assertions
print(paste('Tolerance for assertion checking:', tolerance))
print(paste('Covar  assertion 1:',
            all(abs(covar(marvin) - Y) < tolerance)))
mar2 <- alterMean(marvin, normalOffset, delta=3)
print(paste('Covar  assertion 2:',
            all(abs(covar(marvin) - covar(mar2)) < tolerance)))
print(paste('Correl assertion 1:',
            all(abs(diag(correl(marvin)) - 1) < tolerance)))
mar3 <- alterSD(marvin, function(x) 2*x)
print(paste('Correl assertion 1:',
            all(abs(correl(marvin) - correl(mar2)) < tolerance)))
rm(a, b, X, Lambda2, Y, marvin, mar2, mar3)
  }