R wrapper overview

docs/wrappers/r.rst

@@ -0,0 +1,46 @@
+R
+=======
+
+.. include:: /global.rst
+.. highlight:: r
+
+In this page we briefly discuss the R wrapper, which provides most of Optunity's functionality. 
+For a general overview, we recommend reading the :doc:`/user/index`.
+
+For installation instructions, please refer to |installation|. To use the package has to be loaded like all R packages by::
+
+    library(optunity)
+
+
+Manual
+--------
+
+All functions in R wrapper have documentation available in R's help system,
+e.g., `?cv.particle_swarm` gives help for cross-validation (CV) using **particle swarms**.
+To see the list of available functions type `optunity::<TAB><TAB>` in R's command line.
+
+For R following main functions are available:
+
+-   `cv.setup` for **setting up CV**, specifying data and the number of folds
+
+-   `cv.particle_swarm`, `cv.nelder_mead`, `cv.grid_search`, `cv.random_search` for **optimizing hyperparameters** in CV setting.
+
+-   `auc_roc` and `auc_pr` for calculating **AUC** of ROC and precision-recall curve.
+
+-   `early_rie` and `early_bedroc` for **early discovery** metrics.
+
+-   `mean_se` and `mean_ae` for regression **loss functions**, mean squared error and mean absolute error.
+
+-   `particle_swarm`, `nelder_mead`, `grid_search`, `random_search` for minimizing (or maximizing) regular functionals.
+
+-   `cv.run` performs a **cross-validation** evaluation for the given values of the hyperparameters (no optimization).
+
+General workflow is to first create a CV object using **cv.setup** and then use
+it to run CV, by using functions like **cv.particle_swarms**, **cv.random_search** etc.
+
+Examples
+----------
+Please see the example pages,
+:doc:`/examples/r/ridgereg` and :doc:`/examples/r/svm`. The R help pages for each function
+contain examples showing how to use them.
+

wrappers/R/R/crossvalidation.R

@@ -103,8 +103,8 @@ cv.setup <- function(x, y=NULL, score, num_folds=5, num_iter=1,
 #' @details 
 #' There are two modes for f, depending on cv.setup's score parameter, if:
 #' \itemize{
-#'   \item{score=a_score_function}{f should perform train-predict: train model on xtrain and ytrain, then return predictions on xtest}
-#'   \item{score='user.score'}{f should perform train-predict-score: train model on xtrain and ytrain, then make predictions on xtest, finally return score based on ytest.}
+#'   \item{score=a_score_function}{ f should perform train-predict: train model on xtrain and ytrain, then return predictions on xtest}
+#'   \item{score='user.score'}{ f should perform train-predict-score: train model on xtrain and ytrain, then make predictions on xtest, finally return score based on ytest.}
 #' }
 #' @export
 #' @examples

wrappers/R/man/cv.grid_search.Rd

@@ -1,4 +1,5 @@
-% Generated by roxygen2 (4.0.2): do not edit by hand
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/crossvalidation.R
 \name{cv.grid_search}
 \alias{cv.grid_search}
 \title{Grid search to find parameters giving best cross-validated score}
@@ -25,7 +26,7 @@ y <- x[,1] + 0.5*x[,2] + 0.1*runif(50)
 
 ## linear regression
 regr <- function(x, y, xtest, ytest, logreg=0) {
-  C =  diag(x=exp(logreg), ncol(x))
+  C =  diag(x = 10^logreg, ncol(x))
   beta = solve(t(x) \%*\% x + C, t(x) \%*\% y)
   xtest \%*\% beta
 }

wrappers/R/man/cv.nelder_mead.Rd

@@ -1,4 +1,5 @@
-% Generated by roxygen2 (4.0.2): do not edit by hand
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/crossvalidation.R
 \name{cv.nelder_mead}
 \alias{cv.nelder_mead}
 \title{Nelder-Mead optimization to find parameters giving best cross-validated score}
@@ -28,7 +29,7 @@ y <- x[,1] + 0.5*x[,2] + 0.1*runif(50)
 
 ## linear regression
 regr <- function(x, y, xtest, ytest, logreg=0) {
-  C =  diag(x=exp(logreg), ncol(x))
+  C =  diag(x = 10^logreg, ncol(x))
   beta = solve(t(x) \%*\% x + C, t(x) \%*\% y)
   xtest \%*\% beta
 }

wrappers/R/man/cv.particle_swarm.Rd

@@ -1,4 +1,5 @@
-% Generated by roxygen2 (4.0.2): do not edit by hand
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/crossvalidation.R
 \name{cv.particle_swarm}
 \alias{cv.particle_swarm}
 \title{Particle swarm optimization to find parameters giving best cross-validated score}
@@ -30,7 +31,7 @@ y <- x[,1] + 0.5*x[,2] + 0.1*runif(50)
 
 ## linear regression
 regr <- function(x, y, xtest, ytest, logreg=0) {
-  C =  diag(x=exp(logreg), ncol(x))
+  C =  diag(x = 10^logreg, ncol(x))
   beta = solve(t(x) \%*\% x + C, t(x) \%*\% y)
   xtest \%*\% beta
 }

wrappers/R/man/cv.random_search.Rd

@@ -1,4 +1,5 @@
-% Generated by roxygen2 (4.0.2): do not edit by hand
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/crossvalidation.R
 \name{cv.random_search}
 \alias{cv.random_search}
 \title{Random search to find parameters giving best cross-validated score}
@@ -28,7 +29,7 @@ y <- x[,1] + 0.5*x[,2] + 0.1*runif(50)
 
 ## linear regression
 regr <- function(x, y, xtest, ytest, logreg=0) {
-  C =  diag(x=exp(logreg), ncol(x))
+  C =  diag(x = 10^logreg, ncol(x))
   beta = solve(t(x) \%*\% x + C, t(x) \%*\% y)
   xtest \%*\% beta
 }

wrappers/R/man/cv.run.Rd

@@ -1,4 +1,5 @@
-% Generated by roxygen2 (4.0.2): do not edit by hand
+% Generated by roxygen2 (4.1.1): do not edit by hand
+% Please edit documentation in R/crossvalidation.R
 \name{cv.run}
 \alias{cv.run}
 \title{Runs cross-validation on predict-train function}
@@ -21,8 +22,8 @@ Runs cross-validation on predict-train function
 \details{
 There are two modes for f, depending on cv.setup's score parameter, if:
 \itemize{
-  \item{score=a_score_function}{f should perform train-predict: train model on xtrain and ytrain, then return predictions on xtest}
-  \item{score='user.score'}{f should perform train-predict-score: train model on xtrain and ytrain, then make predictions on xtest, finally return score based on ytest.}
+  \item{score=a_score_function}{ f should perform train-predict: train model on xtrain and ytrain, then return predictions on xtest}
+  \item{score='user.score'}{ f should perform train-predict-score: train model on xtrain and ytrain, then make predictions on xtest, finally return score based on ytest.}
 }
 }
 \examples{