From cd9fc1063e993437518c9c8b4bc612b51fa74956 Mon Sep 17 00:00:00 2001
From: prise6 <vieille.francois@gmail.com>
Date: Mon, 27 Jul 2015 01:40:52 +0200
Subject: [PATCH] update manual because of new wrappers

---
 R/aVirtualTwins.R    |  9 +++--
 R/forest.wrapper.R   | 90 ++++++++++++++++++++++++++++++--------------
 R/object.wrapper.R   | 23 +++++++----
 R/tools.R            | 36 ++++++++++++++----
 R/tree.wrapper.R     | 51 +++++++++++++++++++------
 man/aVirtualTwins.Rd |  7 +++-
 man/vt.data.Rd       |  9 ++++-
 man/vt.forest.Rd     | 54 +++++++++++++++++++++++---
 man/vt.subgroups.Rd  | 30 ++++++++++++---
 man/vt.tree.Rd       | 44 ++++++++++++++++++----
 10 files changed, 272 insertions(+), 81 deletions(-)

diff --git a/R/aVirtualTwins.R b/R/aVirtualTwins.R
index a972ab6..5f491b8 100644
--- a/R/aVirtualTwins.R
+++ b/R/aVirtualTwins.R
@@ -5,17 +5,20 @@
 #' \itemize{
 #'  \item \code{\link{VT.object}} class to represent RCT dataset used by aVirtualTwins. To format correctly RCT dataset, use \code{\link{formatRCTDataset}}.
 #'  \item \code{\link{VT.difft}} class to compute difference between twins. Family \code{\link{VT.forest}} extends it to compute twins by random forest.
-#'  \item \code{\link{VT.tree}} class to find subgroups from \code{difft} by CART trees. \code{\link{VT.tree.class}} and \code{\link{VT.tree.reg}} extend it.
+#'   \code{\link{vt.forest()}} is users function.
+#'  \item \code{\link{VT.tree}} class to find subgroups from \code{difft} by CART trees. \code{\link{VT.tree.class}} and \code{\link{VT.tree.reg}} extend it. 
+#'  \code{\link{vt.tree()}} is users function.
 #' }
 #'  
 #' @section TODO LIST:
-#' \emph{last update : 24.07.2015}
+#' \emph{last update : 27.07.2015}
 #' \itemize{
 #'  \item More detailed documentation and vignettes 
-#'  \item Write wrappers for classes
 #'  \item Write examples
 #'  \item ...
 #' }
+#' 
+#' See github.com/prise6/aVirtualTwins for last updates.
 #'
 #' @docType package
 #' @name aVirtualTwins
diff --git a/R/forest.wrapper.R b/R/forest.wrapper.R
index fae5174..439505c 100644
--- a/R/forest.wrapper.R
+++ b/R/forest.wrapper.R
@@ -2,58 +2,92 @@
 #' 
 #' Create forest to compute difft
 #' 
-#' \code{vt.forest} is a wrapper of \code{\link{VT.forest.one}},
-#' \code{\link{VT.forest.double}} and \code{\link{VT.forest.fold}}.
+#' \code{vt.forest} is a wrapper of \code{\link{VT.forest.one}}, 
+#' \code{\link{VT.forest.double}} and \code{\link{VT.forest.fold}}. With 
+#' parameter forest.type, any of these class can be used with its own parameter.
 #' 
-#' @param forest.type character one / double / fold
-#' @param vt.data \code{\link{VT.data}} or return of \code{vt.data()} function
+#' @param forest.type must be a character. "one" to use VT.forest.one class. 
+#'   "double" to use VT.forest.double. "fold" to use VT.forest.fold.
+#' @param vt.data \code{\link{VT.object}}. Can be return of \code{vt.data()} 
+#'   function
 #' @param interactions logical. If running VirtualTwins with treatment's 
 #'   interactions, set to TRUE (default value)
-#' @param method character absolute / relative / logit
-#' @param ... parameters of \code{\link{VT.difft}} or \code{\link{VT.forest}}  
+#' @param method character c("absolute", "relative", "logit"). See 
+#'   \code{\link{VT.difft}}.
+#' @param model allows to give a model you build outside this function. Can be 
+#'   randomForest, train or cforest. Is only used with forest.type = "one". If 
+#'   NULL, a randomForest model is grown inside the function. NULL is default.
+#' @param model_trt0 works the same as model parameter. Is only used with 
+#'   forest.type = "double". If NULL, a randomForest model is grown inside the 
+#'   function. NULL is default. See \code{\link{VT.forest.double}} for details.
+#' @param model_trt1 see model_trt0 explanation and 
+#'   \code{\link{VT.double.forest}} details.
+#' @param fold number of fold you want to construct forest with k-fold method. 
+#'   Is only used with forest.type = "fold". Default to 5. See 
+#'   \code{\link{VT.forest.fold}}
+#' @param ratio numeric value that allow sampsize to be a bit controlled.
+#'   Default to 1. See \code{\link{VT.forest.fold}}.
+#' @param ... randomForest() function parameters. Can be used for any forest.type.
 #'   
 #' @return \code{VT.difft}
-#'
+#'  
+#' @examples
+#' \dontrun{
+#'  # data(sepsis)
+#'  vt.o <- vt.data(sepsis, "survival", "THERAPY", T)
+#'  # inside model : 
+#'  vt.f <- vt.forest("one", vt.o)
+#'  # ... 
+#'  # your model : 
+#'  rf <- randomForest(y = vt.o$getY(),
+#'                      x = vt.o$getX(int = T),
+#'                      mtry = 3,
+#'                      nodesize = 15)
+#'  vt.f <- vt.forest("one", vt.o, model = rf)
+#'  # ...
+#'  # Can also use ... parameters
+#'  vt.f <- vt.forest("one", vt.o, mtry = 3, nodesize = 15)
+#'  # ...
+#' }   
+#' 
 #' @include forest.R difft.R
-#' 
+#'   
 #' @name vt.forest
-#' 
+#'   
 #' @export vt.forest
 
-vt.forest <- function(forest.type = "one", vt.data, interactions = T, method = "absolute", ...){
+vt.forest <- function(forest.type = "one", vt.data, interactions = T, method = "absolute", 
+                      model = NULL, model_trt1 = NULL, model_trt0 = NULL, ratio = 1, fold = 10, ...){
   if(!inherits(vt.data, "VT.object"))
     stop("vt.data must be VT.object class")
   
   params <- list(...)
   if (forest.type == "one"){
-    if(! "model" %in% names(params) ){
-      rf <- randomForest(x = vt.data$getX(interactions = interactions, trt = NULL),
+    if(is.null(model)){
+      model <- randomForest(x = vt.data$getX(interactions = interactions, trt = NULL),
                          y = vt.data$getY(), 
                          ...)       
-    } else{
-      rf <- params[["model"]]
     }
+    rf <- model
     
     vt.difft <- VT.forest.one(vt.object = vt.data, model = rf, interactions = interactions, method = method)
   } else if (forest.type == "double"){
-    if(! "model_trt1" %in% names(params) ){
-      rf_trt1 <- randomForest(x = vt.data$getX(trt = 1, interactions = interactions),
-                              y = vt.data$getY(1),
-                              ...)
-    } else
-      rf_trt1 <- params[["model_trt1"]]
+    if(is.null(model_trt1)){
+      model_trt1 <- randomForest(x = vt.data$getX(trt = 1),
+                                  y = vt.data$getY(1),
+                                 ...)
+    }
+    rf_trt1 <- model_trt1
     
-    if(! "model_trt0" %in% names(params) ){
-      rf_trt0 <- randomForest(x = vt.data$getX(trt = 1, interactions = interactions),
-                              y = vt.data$getY(1),
-                              ...)
-    } else
-      rf_trt0 <- params[["model_trt0"]]
+    if(is.null(model_trt0)){
+      model_trt0 <- randomForest(x = vt.data$getX(trt = 0),
+                                  y = vt.data$getY(0),
+                                  ...)
+    }
+    rf_trt0 <- model_trt0
     
     vt.difft  <- VT.forest.double(vt.object = vt.data, model_trt1 = rf_trt1, model_trt0 = rf_trt0, method = method)
   } else if (forest.type == "fold"){
-    fold <- ifelse(! "fold" %in% names(params) , 5, as.numeric(params["fold"]))
-    ratio <- ifelse(! "ratio" %in% names(params) , 1, as.numeric(params["ratio"]))
     vt.difft <- aVirtualTwins:::VT.forest.fold(vt.object = vt.data, fold = fold, ratio = ratio, 
                                                interactions = interactions, method = method)
     
diff --git a/R/object.wrapper.R b/R/object.wrapper.R
index 07987c5..c09d1c0 100644
--- a/R/object.wrapper.R
+++ b/R/object.wrapper.R
@@ -1,22 +1,29 @@
 #' 
 #' Initialize virtual twins data
 #' 
-#' \code{vt.data} is a wrapper of \code{\link{formatRCTDataset}} and
-#' \code{\link{VT.object}}.
+#' \code{vt.data} is a wrapper of \code{\link{formatRCTDataset}} and 
+#' \code{\link{VT.object}}. Allows to format your data.frame in order to create
+#' a VT.object object.
 #' 
 #' @param dataset data.frame representing RCT's
 #' @param outcome.field name of the outcome's field in \code{dataset}
 #' @param treatment.field name of the treatment's field in \code{dataset}
-#' @param interactions logical. If running VirtualTwins with treatment's
+#' @param interactions logical. If running VirtualTwins with treatment's 
 #'   interactions, set to TRUE (default value)
 #' @param ... parameters of \code{\link{VT.object}}
-#' 
+#'   
+#' @examples
+#' \dontrun{
+#'  data(sepsis)
+#'  formatRCTdataset(sepsis, "survival", "THERAPY", T)
+#' }
+#'   
 #' @return \code{VT.object}
-#' 
-#' @include object.R 
-#' 
+#'   
+#' @include object.R
+#'   
 #' @name vt.data
-#' 
+#'   
 #' @export vt.data
 
 vt.data <- function(dataset, outcome.field, treatment.field, interactions = TRUE, ...){
diff --git a/R/tools.R b/R/tools.R
index e6c88c1..e2d3835 100644
--- a/R/tools.R
+++ b/R/tools.R
@@ -1,18 +1,38 @@
 
 #' Visualize subgroups
 #' 
-#' @param vt.trees \code{\link{VT.tree}} object (can be a list)
-#' @param only.leaf logical select only leaf of trees
-#' @param only.fav logical select only favorable subgroup (meaning with favorable label of the tree)
-#' @param tables logical show tables of incidence
-#' @param verbose print tables during computation
+#' Function which uses \code{\link{VT.tree}} intern functions. Package
+#' rpart.plot must be loaded. See \code{\link{VT.tree}} for details.
 #' 
+#' @param vt.trees \code{\link{VT.tree}} object. Or return of 
+#'   \code{\link{vt.tree}} function. Can be a list.
+#' @param only.leaf logical to select only leaf of trees. TRUE is default.
+#' @param only.fav logical select only favorable subgroups (meaning with 
+#'   favorable label of the tree). TRUE is default.
+#' @param tables set to TRUE if tables of incidence must be shown. FALSE is 
+#'   default.
+#' @param verbose print infos during computation. FALSE is default.
+#'   
 #' @return data.frame of rules
+#'   
+#' @examples 
+#' \dontrun{ 
+#'  # data(sepsis) 
+#'  vt.o <- vt.data(sepsis, "survival", "THERAPY", T) 
+#'  # inside model : 
+#'  vt.f <- vt.forest("one", vt.o) 
+#'  # use classification tree 
+#'  vt.tr <- vt.tree("class", vt.f, threshold = c(0.01, 0.05)) 
+#'  # show subgroups 
+#'  vt.subgroups(vt.tr) 
+#'  # change options you'll be surprised !
+#'  vt.subgroups(vt.tr, verbose = T, tables = T) 
+#' }
 #' 
 #' @export vt.subgroups
-#'
-#' @name vt.subgroups  
-#'  
+#'   
+#' @name vt.subgroups
+#'   
 
 vt.subgroups <- function(vt.trees, only.leaf = T, only.fav = T, tables = F, verbose = F){
   
diff --git a/R/tree.wrapper.R b/R/tree.wrapper.R
index 0d9a673..c6a22ba 100644
--- a/R/tree.wrapper.R
+++ b/R/tree.wrapper.R
@@ -1,22 +1,49 @@
 
 #' Trees to find Subgroups
 #' 
-#' A wrapper of class VT.tree.xxx
-#'
+#' \code{vt.tree} is a wrapper of \code{\link{VT.tree.class}} and 
+#' \code{\link{VT.tree.reg}}. With parameter tree.type, any of these two class 
+#' can be used with its own parameter.
 #' 
-#' See \code{\link{VT.tree}}
-#' 
-#' @param tree.type character "class" for classification tree, "reg" for regression tree
-#' @param vt.difft \code{\link{VT.difft}} object
-#' @param sens character c(">","<"). See details.
-#' @param threshold numeric It can be a unique value or a vector
-#' 
-#' @return \code{VT.tree} or a list of \code{VT.tree} depending on threshold dimension
+#' See \code{\link{VT.tree}}, \code{\link{VT.tree.class}} and 
+#' \code{\link{VT.tree.reg}} classes.
 #' 
+#' @param tree.type must be a character. "class" for classification tree, "reg" 
+#'   for regression tree.
+#' @param vt.difft \code{\link{VT.difft}} object. Or return of 
+#'   \code{\link{vt.forest}} function.
+#' @param sens must be a character c(">","<"). See \code{\link{VT.tree}} for 
+#'   details.
+#' @param threshold must be numeric. It can be a unique value or a vector. If 
+#'   numeric vector, a list is returned. See \code{\link{VT.tree}} for details.
+#' @param screening must be logical. If TRUE, only varimp variables of VT.object
+#'   is used to create the tree.
+#' @param ... rpart() function parameters. Can be used for any tree.type.
+#'   
+#' @return \code{VT.tree} or a list of \code{VT.tree} depending on threshold 
+#'   dimension. See examples.
+#'   
+#' @examples
+#' \dontrun{
+#'  # data(sepsis)
+#'  vt.o <- vt.data(sepsis, "survival", "THERAPY", T)
+#'  # inside model : 
+#'  vt.f <- vt.forest("one", vt.o)
+#'  # use classification tree
+#'  vt.tr <- vt.tree("class", vt.f, threshold = c(0.01, 0.05))
+#'  # return a list
+#'  class(vt.tr)
+#'  # access one of the tree
+#'  vt.tr$tree1
+#'  # return infos
+#'  vt.tr$tree1$getInfos()
+#'  # ...
+#' }
+#'   
 #' @include tree.R
-#' 
+#'   
 #' @name vt.tree
-#' 
+#'   
 #' @export vt.tree
 
 vt.tree <- function(tree.type = "class", vt.difft, sens = ">", threshold = seq(.5, .8, .1), screening = NULL, ...){
diff --git a/man/aVirtualTwins.Rd b/man/aVirtualTwins.Rd
index dff4c00..bf69dac 100644
--- a/man/aVirtualTwins.Rd
+++ b/man/aVirtualTwins.Rd
@@ -10,17 +10,20 @@ aVirtualTwins is written mainly with reference classes. Briefly, there is three
 \itemize{
  \item \code{\link{VT.object}} class to represent RCT dataset used by aVirtualTwins. To format correctly RCT dataset, use \code{\link{formatRCTDataset}}.
  \item \code{\link{VT.difft}} class to compute difference between twins. Family \code{\link{VT.forest}} extends it to compute twins by random forest.
+  \code{\link{vt.forest()}} is users function.
  \item \code{\link{VT.tree}} class to find subgroups from \code{difft} by CART trees. \code{\link{VT.tree.class}} and \code{\link{VT.tree.reg}} extend it.
+ \code{\link{vt.tree()}} is users function.
 }
 }
 \section{TODO LIST}{
 
-\emph{last update : 24.07.2015}
+\emph{last update : 27.07.2015}
 \itemize{
  \item More detailed documentation and vignettes
- \item Write wrappers for classes
  \item Write examples
  \item ...
 }
+
+See github.com/prise6/aVirtualTwins for last updates.
 }
 
diff --git a/man/vt.data.Rd b/man/vt.data.Rd
index 43ddf47..05a6783 100644
--- a/man/vt.data.Rd
+++ b/man/vt.data.Rd
@@ -23,6 +23,13 @@ interactions, set to TRUE (default value)}
 }
 \description{
 \code{vt.data} is a wrapper of \code{\link{formatRCTDataset}} and
-\code{\link{VT.object}}.
+\code{\link{VT.object}}. Allows to format your data.frame in order to create
+a VT.object object.
+}
+\examples{
+\dontrun{
+ data(sepsis)
+ formatRCTdataset(sepsis, "survival", "THERAPY", T)
+}
 }
 
diff --git a/man/vt.forest.Rd b/man/vt.forest.Rd
index b9df0ba..d2ef5c2 100644
--- a/man/vt.forest.Rd
+++ b/man/vt.forest.Rd
@@ -5,25 +5,67 @@
 \title{Create forest to compute difft}
 \usage{
 vt.forest(forest.type = "one", vt.data, interactions = T,
-  method = "absolute", ...)
+  method = "absolute", model = NULL, model_trt1 = NULL,
+  model_trt0 = NULL, ratio = 1, fold = 10, ...)
 }
 \arguments{
-\item{forest.type}{character one / double / fold}
+\item{forest.type}{must be a character. "one" to use VT.forest.one class.
+"double" to use VT.forest.double. "fold" to use VT.forest.fold.}
 
-\item{vt.data}{\code{\link{VT.data}} or return of \code{vt.data()} function}
+\item{vt.data}{\code{\link{VT.object}}. Can be return of \code{vt.data()}
+function}
 
 \item{interactions}{logical. If running VirtualTwins with treatment's
 interactions, set to TRUE (default value)}
 
-\item{method}{character absolute / relative / logit}
+\item{method}{character c("absolute", "relative", "logit"). See
+\code{\link{VT.difft}}.}
 
-\item{...}{parameters of \code{\link{VT.difft}} or \code{\link{VT.forest}}}
+\item{model}{allows to give a model you build outside this function. Can be
+randomForest, train or cforest. Is only used with forest.type = "one". If
+NULL, a randomForest model is grown inside the function. NULL is default.}
+
+\item{model_trt1}{see model_trt0 explanation and
+\code{\link{VT.double.forest}} details.}
+
+\item{model_trt0}{works the same as model parameter. Is only used with
+forest.type = "double". If NULL, a randomForest model is grown inside the
+function. NULL is default. See \code{\link{VT.forest.double}} for details.}
+
+\item{ratio}{numeric value that allow sampsize to be a bit controlled.
+Default to 1. See \code{\link{VT.forest.fold}}.}
+
+\item{fold}{number of fold you want to construct forest with k-fold method.
+Is only used with forest.type = "fold". Default to 5. See
+\code{\link{VT.forest.fold}}}
+
+\item{...}{randomForest() function parameters. Can be used for any forest.type.}
 }
 \value{
 \code{VT.difft}
 }
 \description{
 \code{vt.forest} is a wrapper of \code{\link{VT.forest.one}},
-\code{\link{VT.forest.double}} and \code{\link{VT.forest.fold}}.
+\code{\link{VT.forest.double}} and \code{\link{VT.forest.fold}}. With
+parameter forest.type, any of these class can be used with its own parameter.
+}
+\examples{
+\dontrun{
+ # data(sepsis)
+ vt.o <- vt.data(sepsis, "survival", "THERAPY", T)
+ # inside model :
+ vt.f <- vt.forest("one", vt.o)
+ # ...
+ # your model :
+ rf <- randomForest(y = vt.o$getY(),
+                     x = vt.o$getX(int = T),
+                     mtry = 3,
+                     nodesize = 15)
+ vt.f <- vt.forest("one", vt.o, model = rf)
+ # ...
+ # Can also use ... parameters
+ vt.f <- vt.forest("one", vt.o, mtry = 3, nodesize = 15)
+ # ...
+}
 }
 
diff --git a/man/vt.subgroups.Rd b/man/vt.subgroups.Rd
index 3bc73ab..1ba1525 100644
--- a/man/vt.subgroups.Rd
+++ b/man/vt.subgroups.Rd
@@ -8,20 +8,38 @@ vt.subgroups(vt.trees, only.leaf = T, only.fav = T, tables = F,
   verbose = F)
 }
 \arguments{
-\item{vt.trees}{\code{\link{VT.tree}} object (can be a list)}
+\item{vt.trees}{\code{\link{VT.tree}} object. Or return of
+\code{\link{vt.tree}} function. Can be a list.}
 
-\item{only.leaf}{logical select only leaf of trees}
+\item{only.leaf}{logical to select only leaf of trees. TRUE is default.}
 
-\item{only.fav}{logical select only favorable subgroup (meaning with favorable label of the tree)}
+\item{only.fav}{logical select only favorable subgroups (meaning with
+favorable label of the tree). TRUE is default.}
 
-\item{tables}{logical show tables of incidence}
+\item{tables}{set to TRUE if tables of incidence must be shown. FALSE is
+default.}
 
-\item{verbose}{print tables during computation}
+\item{verbose}{print infos during computation. FALSE is default.}
 }
 \value{
 data.frame of rules
 }
 \description{
-Visualize subgroups
+Function which uses \code{\link{VT.tree}} intern functions. Package
+rpart.plot must be loaded. See \code{\link{VT.tree}} for details.
+}
+\examples{
+\dontrun{
+ # data(sepsis)
+ vt.o <- vt.data(sepsis, "survival", "THERAPY", T)
+ # inside model :
+ vt.f <- vt.forest("one", vt.o)
+ # use classification tree
+ vt.tr <- vt.tree("class", vt.f, threshold = c(0.01, 0.05))
+ # show subgroups
+ vt.subgroups(vt.tr)
+ # change options you'll be surprised !
+ vt.subgroups(vt.tr, verbose = T, tables = T)
+}
 }
 
diff --git a/man/vt.tree.Rd b/man/vt.tree.Rd
index 4f38fe4..427bcc2 100644
--- a/man/vt.tree.Rd
+++ b/man/vt.tree.Rd
@@ -8,21 +8,51 @@ vt.tree(tree.type = "class", vt.difft, sens = ">", threshold = seq(0.5,
   0.8, 0.1), screening = NULL, ...)
 }
 \arguments{
-\item{tree.type}{character "class" for classification tree, "reg" for regression tree}
+\item{tree.type}{must be a character. "class" for classification tree, "reg"
+for regression tree.}
 
-\item{vt.difft}{\code{\link{VT.difft}} object}
+\item{vt.difft}{\code{\link{VT.difft}} object. Or return of
+\code{\link{vt.forest}} function.}
 
-\item{sens}{character c(">","<"). See details.}
+\item{sens}{must be a character c(">","<"). See \code{\link{VT.tree}} for
+details.}
 
-\item{threshold}{numeric It can be a unique value or a vector}
+\item{threshold}{must be numeric. It can be a unique value or a vector. If
+numeric vector, a list is returned. See \code{\link{VT.tree}} for details.}
+
+\item{screening}{must be logical. If TRUE, only varimp variables of VT.object
+is used to create the tree.}
+
+\item{...}{rpart() function parameters. Can be used for any tree.type.}
 }
 \value{
-\code{VT.tree} or a list of \code{VT.tree} depending on threshold dimension
+\code{VT.tree} or a list of \code{VT.tree} depending on threshold
+  dimension. See examples.
 }
 \description{
-A wrapper of class VT.tree.xxx
+\code{vt.tree} is a wrapper of \code{\link{VT.tree.class}} and
+\code{\link{VT.tree.reg}}. With parameter tree.type, any of these two class
+can be used with its own parameter.
 }
 \details{
-See \code{\link{VT.tree}}
+See \code{\link{VT.tree}}, \code{\link{VT.tree.class}} and
+\code{\link{VT.tree.reg}} classes.
+}
+\examples{
+\dontrun{
+ # data(sepsis)
+ vt.o <- vt.data(sepsis, "survival", "THERAPY", T)
+ # inside model :
+ vt.f <- vt.forest("one", vt.o)
+ # use classification tree
+ vt.tr <- vt.tree("class", vt.f, threshold = c(0.01, 0.05))
+ # return a list
+ class(vt.tr)
+ # access one of the tree
+ vt.tr$tree1
+ # return infos
+ vt.tr$tree1$getInfos()
+ # ...
+}
 }