DSA {DSA} | R Documentation |
Performs data-adaptive estimation through estimator selection based on cross-validation and the L2 loss function. Candidate estimators are defined with polynomial generalized linear models generated with the Deletion/Substitution/Addition (D/S/A) algorithm under user-specified constraints.
DSA(formula, data, id = 1:nrow(data), family = gaussian, weights = NULL,maxsize, maxorderint, maxsumofpow, vsplits = NULL,userseed = NULL, nfolds = 5, model.matrices = FALSE, silent = TRUE, ...)
formula |
a symbolic description of the base model which specifies the
independent/response variable(s) and all terms forced in
the final model. Typically, formula is set to
Y ~ 1 when no terms are forced in the final model. Currently supported outcomes are
continuous or binomial (binary with 0s and 1s or a two-column
matrix of successes in the first column and failures in the
second). Dependent/Explanatory candidate variables can be continuous
or categorical (factors). Only polynomial main terms and
polynomial interaction terms specified within the I()
subroutine can be forced in the final model, i.e. interactions
between a factor and other variables are currently not suported.
|
data |
a non-optional data frame containing both the response variable(s) as well as the candidate covariates to be considered in the data-adaptive estimation procedure. |
id |
a vector identifying each independent experimental unit
in the data with a unique value, i.e. repeated measurements are
allowed in data . The length of id must correspond to the number of
observations (nrow(data) ). The default value for id is 1:nrow(data) which
indicates that all observations are independent.
|
family |
currently either binomial or gaussian . Used to determine whether
logistic (logit link only) or general linear models should be considered.
|
weights |
a matrix of real numbers whose number of rows
is nfolds+1 and whose number of columns is
the number of observations. The first nfolds rows contain the weights to be applied to
each observation (whether in the training or validation set) at each
split of the data. The last row contains
the weights to be applied to each observation in the learning
set. The argument weights is ignored if the value of
weights is NULL (default).
|
maxsize |
an integer strictly positive which limits the data-adaptive
estimation procedure to candidate linear models with a maximum
number of terms (excluding the intercept) lower or equal to
maxsize . The argument maxsize must be larger or equal to the
number of terms forced into the model through formula .
|
maxorderint |
an integer strictly positive which limits the data-adaptive
estimation procedure to candidate linear models with a maximum
order of interactions lower or equal to maxorderint . The argument
maxordeint must be 1 if the number of terms forced in the model is
equal to maxsize .
|
maxsumofpow |
an integer larger or equal to maxorderint which limits the data-adaptive
estimation procedure to candidate generalized linear models with terms involving
variables whose powers sum up to a value lower or equal to
maxsumofpow . The argument
maxsumofpow must be 1 if the number of terms forced in the model is
equal to maxsize .
|
nfolds |
an integer strictly larger than 1 indicating the number of data splits for the
cross-validation procedure. The default value for nfolds is 5 .
|
vsplits |
a matrix of 0s or 1s whose number of rows is
nfolds and whose number of columns is the number of
observations. Each row indicates how the learning set
is split in a training (0s) and validation (1s) set. The default
value for vsplits is NULL which indicates that the data should be
randomely split based on the v-fold splitting scheme, the values
for userseed , nfolds and id .
|
userseed |
a single value interpreted as an integer and used to
set the seed of the random number
generator which determines the v-fold data splits. If userseed=NULL (default) then
the current seed from the current R session is used. The argument
userseed is ignored if vsplits is not NULL . |
model.matrices |
a logical variable indicating that only the design and response matrices should be returned. |
silent |
if FALSE then
intermediate messages will be printed to standard output showing the progress of the
computations (message level set to 0). if TRUE then no
intermediate messages will be printed to standard output (message
level set to -1). One can further control the messaging level to be
printed to standard output with a call to the setDSAMessageLevel
subroutine preceding a call to the DSA routine where the argument
silent is not referenced.
|
... |
Currently used internally to recursively call the DSA to cross-validate the final model. |
The DSA routine implements a general data-adaptive estimation
procedure based on cross-validation and the L2 loss function. The final estimator is selected from a set
of candidate estimators defined with polynomial generalized linear models generated by the
Deletion/Substitution/Addition (D/S/A) algorithm. The space of
candidate estimators is parameterized with three variables:
maxsize
, maxorderint
and maxsumofpow
. The final
model returned minimizes the empirical risk on the
learning set among all estimators considered and characterized by the
'optimum' size and order of interactions selected by cross-validation.
The D/S/A algorithm is an aggressive model search algorithm which
iteratively generates polynomial generalized linear models based on
the existing terms in the current 'best' model and the following three steps: 1) a deletion step which removes a term from the model,
2) a substitution step which replaces one term with another, and 3) an
addition step which adds a term to the model. The search for the 'best'
estimator starts with the base model specified with formula
:
typically the intercept model except
when the user requires a number of terms to be forced in the final model.
The search for the 'best' estimator is limited by three user-specified
arguments: maxsize
, maxorderint
and maxsumofpow
. The first argument
limits the maximum number of terms in the models considered (excluding
the intercept). The second
argument limits the maximum order of interactions for the models
considered. All terms in the models considered are composed of interactions of
variables raised to a given power. The third argument limits the
maximum sum of powers in each term.
This data-adaptive estimation procedure allows comparison of models
based on different number of observations and can account for
informative censoring through the use of weights in each
regression. These weights are provided to the DSA routine with the
argument weights
.
The DSA routine currently supports data-adaptive estimation
for continuous or binomial outcomes. When the outcome is binomial, the estimators considered are
based on polynomial generalized linear models where the link function is the
logit function. Factors can be candidate variables with the caveat
that there are currently limitations
to the use of factors in terms forced in the final model (see formula
above).
The default cross-validation splitting scheme is v-fold
where the value for v is specified with the argument nfolds
. The DSA
routine performs the data splits based on the value for
nfolds
, id
and the userseed
arguments. The
argument id
identifies the independent experimental units in the data and ensures
that the training and validation sets are independent.
The argument userseed
is
used to set the seed of the R random number generators with the routine
set.seed()
. This allows for reproducible results. The user can specify
an alternative cross-validation splitting scheme with the argument vsplits
.
If model.matrices=TRUE
then a list of two objects is returned, X
and Y
, corresponding respectively with the
matrices of all candidate variables and outcome(s) which would be
considered by the data-adaptive estimation procedure if
model.matrices
were set to FALSE
(default).
Otherwise, an object of class 'DSA' is returned. The traditional print
,
summary
, predict
, and plot
methods are then available on the returned
object. Objects of class 'DSA' have the following attributes:
average.CVrisks |
a matrix containing the average cross-validated risks
defined by the L2 loss function over the splits of the data for each selected
'best' models of size 0 to maxsize (intercept excluded) and maximum order of
interactions 1 to maxorderint . The average cross-validated risk in
row i and column j corresponds to the average cross-validated risk
for the 'best' model of size j (intercept excluded) and maximum order of interactions
i. Note that the average cross-validated risk for a given size and
order of interactions is the average across data splits of the
average risks computed on the validation sets. The average
risks on a given validation set corresponds to the residuals sum of
squares (missing residuals excluded) divided by the
number of (complete) observations in the validation set. |
min.risk |
a vector with two values respectively identifying the row and column
numbers for the minimum average cross-validated risk in
average.CVrisks . Note that the corresponding average cross-validated
risk does not correspond to the average cross-validated risk for the final
model selected by the DSA routine. |
model.selected |
a formula representing the final model selected
by the DSA routine. The variables in model.selected
correspond to variables
in data . |
family |
a description of the link function for the final
generalized linear model selected: gaussian indicates
the indentity function while binomial indicates the logit function. |
coefficients |
the coefficients of the final model fitted on the learning set. |
userseed |
NULL if the argument vsplits was provided by the user or
if the user did not provide userseed , otherwise equal to userseed . |
vsplits |
the vsplits matrix if provided by the user or
the corresponding default matrix randomely generated by the DSA routine. |
computing.time |
an object of class difftime which contains the
information about the computing time associated with this DSA object. |
data |
the original data frame passed in to the DSA routine. |
formula |
the original base formula passed in to the DSA routine. |
call |
the DSA call which generated this DSA object. |
average.CVrisk.model.selected |
the average cross-validated risk
for model.selected .
|
weights |
The weights used in the original call. |
id |
the value of id used in the call. |
The computing time for a DSA call can be very large depending on the number of
candidate variables, number of observations, the value for maxorderint
, maxsize
and maxsumofpow
. DSA calls are more computing intensive with binomial outcomes. It is often
recommended to run this routine in BATCH mode.
Romain Neugebauer and James Bullard based on the original C code from Sandra Sinisi.
1. Mark J. van der Laan and Sandrine Dudoit, "Unified Cross-Validation Methodology For Selection Among Estimators and a General Cross-Validated Adaptive Epsilon-Net Estimator: Finite Sample Oracle Inequalities and Examples" (November 2003). U.C. Berkeley Division of Biostatistics Working Paper Series. Working Paper 130. http://www.bepress.com/ucbbiostat/paper130
2. Mark J. van der Laan, Sandrine Dudoit, and Aad W. van der Vaart, "The Cross-Validated Adaptive Epsilon-Net Estimator" (February 2004). U.C. Berkeley Division of Biostatistics Working Paper Series. Working Paper 142. http://www.bepress.com/ucbbiostat/paper142
3. Sandra E. Sinisi and Mark J. van der Laan, "Loss-Based Cross-Validated Deletion/Substitution/Addition Algorithms in Estimation" (March 2004). U.C. Berkeley Division of Biostatistics Working Paper Series. Working Paper 143. http://www.bepress.com/ucbbiostat/paper143
I
, set.seed
,
difftime
, print.DSA
,
summary.DSA
, predict.DSA
,
plot.DSA
, setDSAMessageLevel
, getDSAMessageLevel
.
library(DSA) ## an example using the state census data. (gaussian) data(state) state.data <- as.data.frame(state.x77) colnames(state.data) <- unlist(lapply(strsplit(colnames(state.data), " "), function(x) paste(x, collapse = ""))) res <- DSA(Murder ~ 1, data = state.data, maxsize = 5, maxsumofpow = 2, maxorderint = 2) residuals(res) coefficients(res) summary(res) ## an example using weights (gaussian). ddir <- paste(system.file(package = "DSA"), "/", "data", "/", sep = "") x <- read.table(paste(ddir, "smalllymphRoX.txt", sep = ""), nrow=240) y <- read.table(paste(ddir, "logT1lymph.txt", sep = "")) weights <- as.matrix(read.table(paste(ddir, "lymphWeights_111505", sep = ""))) colnames(y) <- "loglymph" data <- cbind(x, y) res <- DSA(loglymph ~ 1, data = data, maxsize = 5, maxorderint = 2, maxsumofpow = 2, weights = weights) plot(res) summary(res) ## an example using simulated data (binomial, logistic link). n <- 1000 W <- cbind(rnorm(n), rnorm(n) < 1, rnorm(n) < 2, rnorm(n, 2, 4), runif(n), rcauchy(n), rlogis(n) < .1, rnorm(n) < .1, rnorm(n, 120, 10), rnorm(n, 66, 2)) Y <- 22 + .5*W[,1] + .02*W[,1]^2 + .01*W[,1]*W[,2] + 2*W[,3] + .7*W[,4]^2 Y <- as.matrix(as.integer(Y - mean(Y))/sd(Y)) Y <- as.matrix(as.integer(Y < rlogis(n))) colnames(W) <- paste("V", 1:ncol(W), sep = "") colnames(Y) <- "Y" data <- as.data.frame(cbind(W, Y)) res <- DSA(Y ~ 1, data = data, family = binomial, maxsize = 8, maxorderint = 2, maxsumofpow = 3) plot(res) summary(res) ## an example with factors. n <- 1000 inc <- round(runif(n,1,4)) edu <- round(runif(n,1,4)) W <- data.frame(income = as.factor(c("10000", "10000.35000", "35000.100000", "100000")[inc]), age = round(runif(n, 20, 60)), weight = rnorm(n, 140, 30), degree = as.factor(c("highschool", "highschool.grad", "college", "post.graduate")[edu]), male = rbinom(10, size = 1, prob = .5)) Vertical.Leap <- 8 + ifelse(inc == 1, 2, 0) + (60 - W$age) * .1 + W$male * 4 + rnorm(n, 0, 4) data <- cbind(W, Vertical.Leap) res <- DSA(Vertical.Leap ~ 1, data = data, maxsize = 8, maxorderint = 2, maxsumofpow = 2) plot(res, plot.compare = TRUE) summary(res) ## now add some forced terms. res <- DSA(Vertical.Leap ~ degree, data = data, maxsize = 8, maxorderint = 2, maxsumofpow = 2) plot(res, plot.compare = TRUE) summary(res) ## ## an example using binomial - two column outcome and forced terms ## n <- 1000 W <- cbind(rnorm(n), rnorm(n) < 1, rnorm(n) < 2, rnorm(n, 2, 4), runif(n), rcauchy(n), rlogis(n) < .1, rnorm(n) < .1, rnorm(n, 120, 10), rnorm(n, 66, 2)) Y <- 10 + .5*W[,1] + .02*W[,1]^2 + .01*W[,1]*W[,2] + 2*W[,3] + .7*W[,4]^2 Y <- as.matrix(as.integer(Y - mean(Y))/sd(Y)) trials <- rpois(n, lambda = 20) successes <- sapply(1:n, function(i) { rbinom(1, size = trials[i], prob = pnorm(Y[i])) }) failures <- trials - successes colnames(W) <- paste("V", 1:ncol(W), sep = "") data <- as.data.frame(cbind(W, "successes" = successes, "failures" = failures)) res <- DSA(cbind(successes, failures) ~ 1, data = data, family = binomial, maxsize = 8, maxorderint = 2, maxsumofpow = 3) summary(res) plot(res) ## now add some forced terms res <- DSA(cbind(successes, failures) ~ V1 + I(V4^2), data = data, family = binomial, maxsize = 8, maxorderint = 2, maxsumofpow = 3) summary(res) plot(res)