Documentation improvements

7 files changed, 97 insertions, 20 deletions

diff --git a/R/gensvm.R b/R/gensvm.R
index 8e1242e..db023e2 100644
--- a/R/gensvm.R
+++ b/R/gensvm.R
@@ -13,6 +13,9 @@
 #' @param lambda regularization parameter for the loss function (lambda > 0)
 #' @param kappa parameter for the hinge function in the loss function (kappa >
 #' -1.0)
+#' @param epsilon Stopping parameter for the optimization algorithm. The 
+#' optimization will stop if the relative change in the loss function is below 
+#' this value.
 #' @param weights type or vector of instance weights to use. Options are 'unit'
 #' for unit weights and 'group' for group size correction weights (eq. 4 in the
 #' paper). Alternatively, a vector of weights can be provided.
@@ -92,7 +95,7 @@
 #' fit <- gensvm(x, y)
 #'
 #' # fit and show progress
-#' fit <- gensvm(x, y, verbose=T)
+#' fit <- gensvm(x, y, verbose=TRUE)
 #'
 #' # fit with some changed parameters
 #' fit <- gensvm(x, y, lambda=1e-8)
diff --git a/R/gensvm.accuracy.R b/R/gensvm.accuracy.R
index c762dd7..387c2db 100644
--- a/R/gensvm.accuracy.R
+++ b/R/gensvm.accuracy.R
@@ -1,8 +1,13 @@
 #' @title Compute the accuracy score
 #'
+#' @description Compute the accuracy score between the true labels and the 
+#' predicted labels.
+#'
 #' @param y.true vector of true labels
 #' @param y.pred vector of predicted labels
 #'
+#' @return The accuracy as a value in the range [0.0, 1.0]
+#'
 #' @author
 #' Gerrit J.J. van den Burg, Patrick J.F. Groenen \cr
 #' Maintainer: Gerrit J.J. van den Burg <gertjanvandenburg@gmail.com>
diff --git a/R/gensvm.grid.R b/R/gensvm.grid.R
index 7be065b..755d650 100644
--- a/R/gensvm.grid.R
+++ b/R/gensvm.grid.R
@@ -362,11 +362,29 @@ gensvm.load.small.grid <- function()
 }
 
 
-#' Generate a vector of cross-validation indices
+#' @title Generate a vector of cross-validation indices
 #'
+#' @description
 #' This function generates a vector of length \code{n} with values from 0 to 
 #' \code{folds-1} to mark train and test splits.
 #'
+#' @param n the number of instances
+#' @param folds the number of cross validation folds
+#'
+#' @return an array of length \code{n} with values in the range [0, folds-1] 
+#' indicating the test fold of each instance.
+#'
+#' @author
+#' Gerrit J.J. van den Burg, Patrick J.F. Groenen \cr
+#' Maintainer: Gerrit J.J. van den Burg <gertjanvandenburg@gmail.com>
+#'
+#' @references
+#' Van den Burg, G.J.J. and Groenen, P.J.F. (2016). \emph{GenSVM: A Generalized 
+#' Multiclass Support Vector Machine}, Journal of Machine Learning Research, 
+#' 17(225):1--42. URL \url{http://jmlr.org/papers/v17/14-526.html}.
+#'
+#' @seealso
+#' \code{\link{gensvm.grid}}
 gensvm.generate.cv.idx <- function(n, folds)
 {
     cv.idx <- matrix(0, n, 1)
@@ -572,13 +590,14 @@ gensvm.expand.param.grid <- function(pg, n.features)
 
 #' @title Compute the ranks for the numbers in a given vector
 #'
-#' @details
-#' This function computes the ranks for the values in an array. The highest 
-#' value gets the smallest rank. Ties are broken by assigning the smallest 
-#' value.
+#' @description This function computes the ranks for the values in an array. 
+#' The highest value gets the smallest rank. Ties are broken by assigning the 
+#' smallest value. The smallest rank is 1.
 #'
 #' @param x array of numeric values
 #'
+#' @return array with the ranks of the values in the input array.
+#'
 gensvm.rank.score <- function(x)
 {
     x <- as.array(x)
diff --git a/R/gensvm.refit.R b/R/gensvm.refit.R
index b7a1a15..f3b818b 100644
--- a/R/gensvm.refit.R
+++ b/R/gensvm.refit.R
@@ -1,16 +1,40 @@
 #' @title Train an already fitted model on new data
 #'
-#' @title This function can be used to train an existing model on new data or 
-#' fit an existing model with slightly different parameters. It is useful for 
-#' retraining without having to copy all the parameters over. One common 
-#' application for this is to refit the best model found by a grid search, as 
-#' illustrated in the examples.
+#' @description This function can be used to train an existing model on new 
+#' data or fit an existing model with slightly different parameters. It is 
+#' useful for retraining without having to copy all the parameters over. One 
+#' common application for this is to refit the best model found by a grid 
+#' search, as illustrated in the examples.
 #'
 #' @param fit Fitted \code{gensvm} object
-#' @param X Data matrix of the new data
+#' @param x Data matrix of the new data
 #' @param y Label vector of the new data
-#' @param verbose Turn on verbose output and fit progress. If NULL (the 
-#' default) the value from the fitted model is chosen.
+#' @param p if NULL use the value from \code{fit} in the new model, otherwise 
+#' override with this value.
+#' @param lambda if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param kappa if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param epsilon if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param weights if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param kernel if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param gamma if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param coef if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param degree if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param kernel.eigen.cutoff if NULL use the value from \code{fit} in the new 
+#' model, otherwise override with this value.
+#' @param max.iter if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param verbose if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
+#' @param random.seed if NULL use the value from \code{fit} in the new model, 
+#' otherwise override with this value.
 #'
 #' @return a new fitted \code{gensvm} model
 #'
@@ -50,7 +74,7 @@
 #' fit1 <- gensvm(x1, y1)
 #' fit2 <- gensvm.refit(fit1, x2, y2)
 #'
-gensvm.refit <- function(fit, X, y, p=NULL, lambda=NULL, kappa=NULL, 
+gensvm.refit <- function(fit, x, y, p=NULL, lambda=NULL, kappa=NULL, 
                          epsilon=NULL, weights=NULL, kernel=NULL, gamma=NULL, 
                          coef=NULL, degree=NULL, kernel.eigen.cutoff=NULL, 
                          max.iter=NULL, verbose=NULL, random.seed=NULL)
@@ -76,7 +100,7 @@ gensvm.refit <- function(fit, X, y, p=NULL, lambda=NULL, kappa=NULL,
     # after the call to gensvm().
     errfunc <- getOption('error')
     options(error=function() {})
-    newfit <- gensvm(X, y, p=p, lambda=lambda, kappa=kappa, epsilon=epsilon, 
+    newfit <- gensvm(x, y, p=p, lambda=lambda, kappa=kappa, epsilon=epsilon, 
                      weights=weights, kernel=kernel, gamma=gamma, coef=coef,
                      degree=degree, kernel.eigen.cutoff=kernel.eigen.cutoff,
                      verbose=verbose, max.iter=max.iter, seed.V=coef(fit))
diff --git a/R/gensvm.train.test.split.R b/R/gensvm.train.test.split.R
index eca4b06..cd40ecc 100644
--- a/R/gensvm.train.test.split.R
+++ b/R/gensvm.train.test.split.R
@@ -18,6 +18,12 @@
 #' of 0.25 will be used.
 #' @param shuffle shuffle the rows or not
 #' @param random.state seed for the random number generator (int)
+#' @param return.idx whether or not to return the indices in the output
+#'
+#' @return a list with \code{x.train} and \code{x.test} splits of the \code{x} 
+#' array provided. If \code{y} is provided, also \code{y.train} and 
+#' \code{y.test}. If \code{return.idx} is TRUE, also \code{idx.train} and 
+#' \code{idx.test}.
 #'
 #' @author
 #' Gerrit J.J. van den Burg, Patrick J.F. Groenen \cr
diff --git a/R/plot.gensvm.R b/R/plot.gensvm.R
index 129d90a..3f6f5d2 100644
--- a/R/plot.gensvm.R
+++ b/R/plot.gensvm.R
@@ -1,8 +1,8 @@
 #' @title Plot the simplex space of the fitted GenSVM model
 #' 
 #' @description This function creates a plot of the simplex space for a fitted 
-#' GenSVM model and the given data set, as long as the dataset consists of only 
-#' 3 classes.  For more than 3 classes, the simplex space is too high 
+#' GenSVM model and the given data set. This function works for dataset with 
+#' two or three classes. For more than 3 classes, the simplex space is too high 
 #' dimensional to easily visualize.
 #'
 #' @param x A fitted \code{gensvm} object
@@ -60,8 +60,14 @@
 #' # plot only misclassified samples
 #' x.mis <- x[predict(fit) != y, ]
 #' y.mis.true <- y[predict(fit) != y]
-#' plot(fit, x.test=x.mis)
-#' plot(fit, y.mis.true, x.test=x.mis)
+#' plot(fit, newdata=x.mis)
+#' plot(fit, y.mis.true, newdata=x.mis)
+#'
+#' # plot a 2-d model
+#' xx <- x[y %in% c('versicolor', 'virginica'), ]
+#' yy <- y[y %in% c('versicolor', 'virginica')]
+#' fit <- gensvm(xx, yy, kernel='rbf', max.iter=5000)
+#' plot(fit)
 #'
 plot.gensvm <- function(x, labels, newdata=NULL, with.margins=TRUE, 
                         with.shading=TRUE, with.legend=TRUE, center.plot=TRUE, 
diff --git a/R/validate.R b/R/validate.R
index 5960a38..c708158 100644
--- a/R/validate.R
+++ b/R/validate.R
@@ -1,7 +1,14 @@
 #' @title [internal] Validate parameters
 #'
+#' @description Internal function used to validate the parameters passed to the 
+#' gensvm() function.
+#'
+#' @return TRUE if all values pass their respective conditions, FALSE 
+#' otherwise.
+#'
 #' @export
 #' @keywords internal
+#'
 gensvm.validate.params <- function(p=NULL, kappa=NULL, lambda=NULL, 
                                    epsilon=NULL, gamma=NULL, weights=NULL, 
                                    kernel=NULL, ...)
@@ -26,8 +33,15 @@ gensvm.validate.params <- function(p=NULL, kappa=NULL, lambda=NULL,
 
 #' @title [internal] Validate parameter grid
 #'
+#' @description Internal function to validate all parameters in a parameter 
+#' grid.
+#'
+#' @return TRUE if all values pass their respective conditions, FALSE 
+#' otherwise.
+#'
 #' @export
 #' @keywords internal
+#'
 gensvm.validate.param.grid <- function(df)
 {
     expected.colnames <- c("kernel", "coef", "degree", "gamma", "weights",