Documentation improvements

17 files changed, 146 insertions, 39 deletions

diff --git a/man/coef.gensvm.Rd b/man/coef.gensvm.Rd
index 9f08ecc..aba3efe 100644
--- a/man/coef.gensvm.Rd
+++ b/man/coef.gensvm.Rd
@@ -4,10 +4,10 @@
 \alias{coef.gensvm}
 \title{Get the coefficients of the fitted GenSVM model}
 \usage{
-\method{coef}{gensvm}(fit, ...)
+\method{coef}{gensvm}(object, ...)
 }
 \arguments{
-\item{fit}{a \code{gensvm} object}
+\item{object}{a \code{gensvm} object}
 
 \item{\dots}{further arguments are ignored}
 }
diff --git a/man/fitted.gensvm.Rd b/man/fitted.gensvm.Rd
index b242eb8..c65123e 100644
--- a/man/fitted.gensvm.Rd
+++ b/man/fitted.gensvm.Rd
@@ -2,13 +2,12 @@
 % Please edit documentation in R/fitted.gensvm.R
 \name{fitted.gensvm}
 \alias{fitted.gensvm}
-\alias{fitted}
 \title{Show fitted labels for the GenSVM model}
 \usage{
-\method{fitted}{gensvm}(fit, ...)
+\method{fitted}{gensvm}(object, ...)
 }
 \arguments{
-\item{fit}{Fitted \code{gensvm} object}
+\item{object}{Fitted \code{gensvm} object}
 
 \item{\dots}{further arguments are passed to predict}
 }
diff --git a/man/fitted.gensvm.grid.Rd b/man/fitted.gensvm.grid.Rd
index 1e2f697..455df7e 100644
--- a/man/fitted.gensvm.grid.Rd
+++ b/man/fitted.gensvm.grid.Rd
@@ -2,13 +2,12 @@
 % Please edit documentation in R/fitted.gensvm.grid.R
 \name{fitted.gensvm.grid}
 \alias{fitted.gensvm.grid}
-\alias{fitted}
 \title{Fitted labels for the GenSVMGrid class}
 \usage{
-\method{fitted}{gensvm.grid}(grid, ...)
+\method{fitted}{gensvm.grid}(object, ...)
 }
 \arguments{
-\item{grid}{A \code{gensvm.grid} object}
+\item{object}{A \code{gensvm.grid} object}
 
 \item{\dots}{further arguments are passed to fitted}
 }
diff --git a/man/gensvm.Rd b/man/gensvm.Rd
index b6c9bf0..4f5d614 100644
--- a/man/gensvm.Rd
+++ b/man/gensvm.Rd
@@ -24,6 +24,10 @@ function (i.e. \code{model.matrix( ~ var - 1)}).}
 \item{kappa}{parameter for the hinge function in the loss function (kappa >
 -1.0)}
 
+\item{epsilon}{Stopping parameter for the optimization algorithm. The 
+optimization will stop if the relative change in the loss function is below 
+this value.}
+
 \item{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.}
@@ -99,7 +103,7 @@ y <- iris[, 5]
 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/man/gensvm.accuracy.Rd b/man/gensvm.accuracy.Rd
index 9463fa5..25b8fb7 100644
--- a/man/gensvm.accuracy.Rd
+++ b/man/gensvm.accuracy.Rd
@@ -11,6 +11,13 @@ gensvm.accuracy(y.true, y.pred)
 
 \item{y.pred}{vector of predicted labels}
 }
+\value{
+The accuracy as a value in the range [0.0, 1.0]
+}
+\description{
+Compute the accuracy score between the true labels and the 
+predicted labels.
+}
 \examples{
 x <- iris[, -5]
 y <- iris[, 5]
diff --git a/man/gensvm.generate.cv.idx.Rd b/man/gensvm.generate.cv.idx.Rd
index 38d8829..dbba19e 100644
--- a/man/gensvm.generate.cv.idx.Rd
+++ b/man/gensvm.generate.cv.idx.Rd
@@ -6,7 +6,28 @@
 \usage{
 gensvm.generate.cv.idx(n, folds)
 }
+\arguments{
+\item{n}{the number of instances}
+
+\item{folds}{the number of cross validation folds}
+}
+\value{
+an array of length \code{n} with values in the range [0, folds-1] 
+indicating the test fold of each instance.
+}
 \description{
 This function generates a vector of length \code{n} with values from 0 to 
 \code{folds-1} to mark train and test splits.
 }
+\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}}
+}
+\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/man/gensvm.rank.score.Rd b/man/gensvm.rank.score.Rd
index a92d4be..627e60b 100644
--- a/man/gensvm.rank.score.Rd
+++ b/man/gensvm.rank.score.Rd
@@ -9,8 +9,11 @@ gensvm.rank.score(x)
 \arguments{
 \item{x}{array of numeric values}
 }
-\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.
+\value{
+array with the ranks of the values in the input array.
+}
+\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.
 }
diff --git a/man/gensvm.refit.Rd b/man/gensvm.refit.Rd
index 8a711bc..cae0646 100644
--- a/man/gensvm.refit.Rd
+++ b/man/gensvm.refit.Rd
@@ -4,7 +4,7 @@
 \alias{gensvm.refit}
 \title{Train an already fitted model on new data}
 \usage{
-gensvm.refit(fit, X, y, p = NULL, lambda = NULL, kappa = NULL,
+gensvm.refit(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)
@@ -12,16 +12,59 @@ gensvm.refit(fit, X, y, p = NULL, lambda = NULL, kappa = NULL,
 \arguments{
 \item{fit}{Fitted \code{gensvm} object}
 
-\item{X}{Data matrix of the new data}
+\item{x}{Data matrix of the new data}
 
 \item{y}{Label vector of the new data}
 
-\item{verbose}{Turn on verbose output and fit progress. If NULL (the 
-default) the value from the fitted model is chosen.}
+\item{p}{if NULL use the value from \code{fit} in the new model, otherwise 
+override with this value.}
+
+\item{lambda}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{kappa}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{epsilon}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{weights}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{kernel}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{gamma}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{coef}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{degree}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{kernel.eigen.cutoff}{if NULL use the value from \code{fit} in the new 
+model, otherwise override with this value.}
+
+\item{max.iter}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{verbose}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
+
+\item{random.seed}{if NULL use the value from \code{fit} in the new model, 
+otherwise override with this value.}
 }
 \value{
 a new fitted \code{gensvm} model
 }
+\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.
+}
 \examples{
 x <- iris[, -5]
 y <- iris[, 5]
diff --git a/man/gensvm.train.test.split.Rd b/man/gensvm.train.test.split.Rd
index fe2b1fb..261f7d1 100644
--- a/man/gensvm.train.test.split.Rd
+++ b/man/gensvm.train.test.split.Rd
@@ -27,6 +27,14 @@ of 0.25 will be used.}
 \item{shuffle}{shuffle the rows or not}
 
 \item{random.state}{seed for the random number generator (int)}
+
+\item{return.idx}{whether or not to return the indices in the output}
+}
+\value{
+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}.
 }
 \description{
 Often it is desirable to split a dataset into a training and 
diff --git a/man/gensvm.validate.param.grid.Rd b/man/gensvm.validate.param.grid.Rd
index 69882fe..7deacfd 100644
--- a/man/gensvm.validate.param.grid.Rd
+++ b/man/gensvm.validate.param.grid.Rd
@@ -6,4 +6,12 @@
 \usage{
 gensvm.validate.param.grid(df)
 }
+\value{
+TRUE if all values pass their respective conditions, FALSE 
+otherwise.
+}
+\description{
+Internal function to validate all parameters in a parameter 
+grid.
+}
 \keyword{internal}
diff --git a/man/gensvm.validate.params.Rd b/man/gensvm.validate.params.Rd
index 8e50137..ca6ddab 100644
--- a/man/gensvm.validate.params.Rd
+++ b/man/gensvm.validate.params.Rd
@@ -7,4 +7,12 @@
 gensvm.validate.params(p = NULL, kappa = NULL, lambda = NULL,
   epsilon = NULL, gamma = NULL, weights = NULL, kernel = NULL, ...)
 }
+\value{
+TRUE if all values pass their respective conditions, FALSE 
+otherwise.
+}
+\description{
+Internal function used to validate the parameters passed to the 
+gensvm() function.
+}
 \keyword{internal}
diff --git a/man/plot.gensvm.Rd b/man/plot.gensvm.Rd
index d99c2a0..6e19228 100644
--- a/man/plot.gensvm.Rd
+++ b/man/plot.gensvm.Rd
@@ -4,15 +4,18 @@
 \alias{plot.gensvm}
 \title{Plot the simplex space of the fitted GenSVM model}
 \usage{
-\method{plot}{gensvm}(fit, y, x.test = NULL, with.margins = TRUE,
+\method{plot}{gensvm}(x, labels, newdata = NULL, with.margins = TRUE,
   with.shading = TRUE, with.legend = TRUE, center.plot = TRUE,
   xlim = NULL, ylim = NULL, ...)
 }
 \arguments{
-\item{fit}{A fitted \code{gensvm} object}
+\item{x}{A fitted \code{gensvm} object}
 
-\item{y}{the labels to color points with (if NULL the predicted labels are 
-used)}
+\item{labels}{the labels to color points with. If this is omitted the 
+predicted labels are used.}
+
+\item{newdata}{the dataset to plot. If this is NULL the training data is 
+used.}
 
 \item{with.margins}{plot the margins}
 
@@ -31,16 +34,14 @@ bounds will be used for the vertical axis and the value of center.plot will
 be ignored}
 
 \item{...}{further arguments are passed to the builtin plot() function}
-
-\item{x}{the dataset to plot (if NULL the training data is used)}
 }
 \value{
 returns the object passed as input
 }
 \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.
 }
 \examples{
@@ -59,8 +60,14 @@ plot(fit, y)
 # 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)
 
 }
 \references{
diff --git a/man/plot.gensvm.grid.Rd b/man/plot.gensvm.grid.Rd
index 44c599e..f23abda 100644
--- a/man/plot.gensvm.grid.Rd
+++ b/man/plot.gensvm.grid.Rd
@@ -4,10 +4,10 @@
 \alias{plot.gensvm.grid}
 \title{Plot the simplex space of the best fitted model in the GenSVMGrid}
 \usage{
-\method{plot}{gensvm.grid}(grid, ...)
+\method{plot}{gensvm.grid}(x, ...)
 }
 \arguments{
-\item{grid}{A \code{gensvm.grid} object trained with refit=TRUE}
+\item{x}{A \code{gensvm.grid} object trained with refit=TRUE}
 
 \item{...}{further arguments are passed to the plot function}
 }
diff --git a/man/predict.gensvm.Rd b/man/predict.gensvm.Rd
index 015623f..b521872 100644
--- a/man/predict.gensvm.Rd
+++ b/man/predict.gensvm.Rd
@@ -4,10 +4,10 @@
 \alias{predict.gensvm}
 \title{Predict class labels with the GenSVM model}
 \usage{
-\method{predict}{gensvm}(fit, newdata, add.rownames = FALSE, ...)
+\method{predict}{gensvm}(object, newdata, add.rownames = FALSE, ...)
 }
 \arguments{
-\item{fit}{Fitted \code{gensvm} object}
+\item{object}{Fitted \code{gensvm} object}
 
 \item{newdata}{Matrix of new data for which predictions need to be made.}
 
diff --git a/man/predict.gensvm.grid.Rd b/man/predict.gensvm.grid.Rd
index 01bf610..0c3cf2f 100644
--- a/man/predict.gensvm.grid.Rd
+++ b/man/predict.gensvm.grid.Rd
@@ -4,13 +4,13 @@
 \alias{predict.gensvm.grid}
 \title{Predict class labels from the GenSVMGrid class}
 \usage{
-\method{predict}{gensvm.grid}(grid, newx, ...)
+\method{predict}{gensvm.grid}(object, newdata, ...)
 }
 \arguments{
-\item{grid}{A \code{gensvm.grid} object trained with \code{refit=TRUE}}
+\item{object}{A \code{gensvm.grid} object trained with \code{refit=TRUE}}
 
-\item{newx}{Matrix of new values for \code{x} for which predictions need to 
-be computed.}
+\item{newdata}{Matrix of new values for \code{x} for which predictions need 
+to be computed.}
 
 \item{\dots}{further arguments are passed to predict.gensvm()}
 }
diff --git a/man/print.gensvm.Rd b/man/print.gensvm.Rd
index e3367fa..d8a7046 100644
--- a/man/print.gensvm.Rd
+++ b/man/print.gensvm.Rd
@@ -4,10 +4,10 @@
 \alias{print.gensvm}
 \title{Print the fitted GenSVM model}
 \usage{
-\method{print}{gensvm}(fit, ...)
+\method{print}{gensvm}(x, ...)
 }
 \arguments{
-\item{fit}{A \code{gensvm} object to print}
+\item{x}{A \code{gensvm} object to print}
 
 \item{\dots}{further arguments are ignored}
 }
diff --git a/man/print.gensvm.grid.Rd b/man/print.gensvm.grid.Rd
index 3b603c1..0a5377d 100644
--- a/man/print.gensvm.grid.Rd
+++ b/man/print.gensvm.grid.Rd
@@ -4,10 +4,10 @@
 \alias{print.gensvm.grid}
 \title{Print the fitted GenSVMGrid model}
 \usage{
-\method{print}{gensvm.grid}(grid, ...)
+\method{print}{gensvm.grid}(x, ...)
 }
 \arguments{
-\item{grid}{a \code{gensvm.grid} object to print}
+\item{x}{a \code{gensvm.grid} object to print}
 
 \item{\dots}{further arguments are ignored}
 }