mvr: Function for Mean-Variance Regularization and Variance Stabilization

Description

End-user function for Mean-Variance Regularization (MVR) and Variance Stabilization by similarity statistic under sample group homoscedasticity or heteroscedasticity assumption. Return an object of class "mvr". Offers the option of parallel computation for improved efficiency. See vignette Cluster_Setup.pdf.

Usage

mvr(data, 
        block = rep(1,nrow(data)),
        tolog = FALSE, 
        nc.min = 1, 
        nc.max = 30, 
        probs = seq(0, 1, 0.01),
        B = 100, 
        parallel = FALSE,
        conf = NULL,
        verbose = TRUE)

Arguments

data

numeric matrix of untransformed (raw) data, where samples are by rows and variables (to be clustered) are by columns, or an object that can be coerced to such a matrix (such as a n

block

character or numeric vector or factor grouping/blocking variable of length the sample size. Defaults to single group situation (see details).

tolog

logical scalar. Is the data to be log2-transformed first? Optional, defaults to FALSE. Note that negative or null values will be changed to 1 before taking log2-transformation.

nc.min

Positive integer scalar of the minimum number of clusters, defaults to 1

nc.max

Positive integer scalar of the maximum number of clusters, defaults to 30

probs

numeric vector of probabilities for quantile diagnostic plots. Defaults to seq(0, 1, 0.01).

Positive integer scalar of the number of Monte Carlo replicates of the inner loop of the sim statistic function (see details).

parallel

logical scalar. Is parallel computing to be performed? Optional, defaults to FALSE.

conf

list of parameters for cluster configuration. Inputs for R package snow function makeCluster (R package snow) for cluster setup. Optional, defaults to NULL. See detai

verbose

logical scalar. Is the output to be verbose? Optional, defaults to TRUE.

Value

Xrawnumeric matrix of original data.
Xmvrnumeric matrix of MVR-transformed data.
centeringnumeric vector of centering values for standardization (cluster mean of pooled sample mean).
scalingnumeric vector of scaling values for standardization (cluster mean of pooled sample std dev).
MVRlist (of size the number of groups) containing MeanVarReg values.
blockValue of argument block.
tologValue of argument tolog.
nc.minValue of argument nc.min.
nc.maxValue of argument nc.max.
probsValue of argument probs.

Details

Argument block is a vector or a factor grouping/blocking variable. It must be of length sample size with as many different character or numeric values as the number of levels or sample groups. It defaults to single group situation, i.e. under the assumption of equal variance between sample groups. All group sample sizes must be greater than 1, otherwise the program will stop. Argument B is reset to conf$cpus*ceiling(B/conf$cpus) in case the Rocks cluster is used (i.e. conf is non NULL), where conf$cpus denotes the total number of CPUs to be used (see below). Argument nc.max currently defaults to 30. We found in our hands that this is enough for most datasets tested. This depends on (i) the dimensionality/sample size ratio $\frac{p}{n}$, (ii) the signal/noise ratio, and (iii) whether a pre-transformation has been applied (see Dazard, J-E. and J. S. Rao (2012) for more details). See the cluster diagnostic function cluster.diagnostic for more details, whether larger values of nc.max may be required. To run a parallel session (and parallel RNG) of the MVR procedures (parallel=TRUE), argument conf is to be specified (i.e. non NULL). It must list the specifications of the folowing parameters for cluster configuration: ("cpus", "type", "homo", "script", "outfile") matching the arguments and options described in function makeCluster of the R package snow:

"cpus":spec:integerscalar specifying the total number of CPU cores, counting the masternode.
"type":type:charactervector specifying the cluster type ("SOCK", "PVM", "MPI").
"homo":homogeneous:logicalscalar to be set toFALSEfor inhomogeneous clusters. (optional, defaults toTRUE).
"script":useRscript:logicalscalar to be set toFALSEif non-R script is used. (optional, defaults toTRUE).
"outfile":outfile:charactervector of the output log file name for the slavenodes. (optional, defaults to"").

Note that the actual creation of the cluster, its initialization, and closing are all done internally. In addition, when random number generation is needed, the creation of separate Stream of Parallel RNG (SPRNG) per node is done internally by distributing the stream states to the nodes (For more details see vignette Cluster_Setup.pdf and see function makeCluster (R package snow) and/or http://www.stat.uiowa.edu/~luke/R/cluster/cluster.html.

References

Dazard J-E., Hua Xu and J. S. Rao (2011). "R package MVR for Joint Adaptive Mean-Variance Regularization and Variance Stabilization." In JSM Proceedings, Section for Statistical Programmers and Analysts. Miami Beach, FL, USA: American Statistical Association IMS - JSM. (in press).
Dazard J-E. and J. S. Rao (2012). "Joint Adaptive Mean-Variance Regularization and Variance Stabilization of High Dimensional Data." Comput. Statist. Data Anal. (to appear).

Examples

Run this code

#===================================================
# Loading the library and its dependencies
#===================================================
library("MVR")
require("statmod", quietly = TRUE)
require("snow", quietly = TRUE)
require("RColorBrewer", quietly = TRUE)

#===================================================
# MVR package news
#===================================================
MVR.news()

#================================================
# MVR package citation
#================================================
citation("MVR")

#===================================================
# Loading of the Synthetic and Real datasets 
# (see description of datasets)
#===================================================
data("Synthetic", "Real", package="MVR")

#===================================================
# Mean-Variance Regularization (Synthetic dataset)
# Single-Group Assumption
# Assuming equal variance between groups
# Without Rocks cluster usage
#===================================================
nc.min <- 1
nc.max <- 20
probs <- seq(0, 1, 0.01)
n <- 10
mvr.obj <- mvr(data = Synthetic, 
               block = rep(1,n), 
               tolog = FALSE, 
               nc.min = nc.min, 
               nc.max = nc.max, 
               probs = probs, 
               B = 100, 
               parallel = FALSE, 
               conf = NULL, 
               verbose = TRUE)
 
#===================================================
if (.Platform$OS.type == "unix") {
    if (!is.loaded("rpvm")) {
            library("rpvm")
    }
}
masterhost <- Sys.getenv("HOSTNAME")
slavehosts <- unlist(strsplit(Sys.getenv("HOSTS"), split="\n"))
.PVM.start.pvmd(hosts = masterhost) 
.PVM.addhosts(hosts = slavehosts)
#===================================================

#===================================================
cpus <- as.numeric(Sys.getenv("NUMCPU"))
nodes <- length(slavehosts) + 1
conf <- list("cpus" = nodes * cpus, 
             "type" = getClusterOption("type"), 
             "homo" = getClusterOption("homogeneous"), 
             "script" = getClusterOption("useRscript"),
             "outfile" = "")
#===================================================

#===================================================
# Mean-Variance Regularization (Real dataset)
# Multi-Group Assumption
# Assuming unequal variance between groups
# With Rocks cluster usage
#===================================================
nc.min <- 1
nc.max <- 30
probs <- seq(0, 1, 0.01)
n <- 6
GF <- factor(gl(n = 2, k = n/2, len = n), 
             ordered = FALSE, 
             labels = c("M", "S"))
mvr.obj <- mvr(data = Real, 
               block = GF, 
               tolog = FALSE, 
               nc.min = nc.min, 
               nc.max = nc.max, 
               probs = probs,
               B = 100, 
               parallel = TRUE, 
               conf = conf,
               verbose = TRUE)

#===================================================
# Mean-Variance Regularization (Real dataset)
# Single-Group Assumption
# Assuming equal variance between groups
# With Rocks cluster usage
#===================================================
nc.min <- 1
nc.max <- 30
probs <- seq(0, 1, 0.01)
n <- 6
mvr.obj <- mvr(data = Real, 
               block = rep(1,n), 
               tolog = FALSE, 
               nc.min = nc.min, 
               nc.max = nc.max, 
               probs = probs, 
               B = 100, 
               parallel = TRUE, 
               conf = conf, 
               verbose = TRUE)

#===================================================
.PVM.delhosts(hosts = slavehosts)
.PVM.delhosts(hosts = masterhost)
.PVM.halt()
#===================================================

Run the code above in your browser using DataLab