Various documentation fixes

11 files changed, 87 insertions, 64 deletions

diff --git a/R/coef.sparsestep.R b/R/coef.sparsestep.R
index 567b1f0..3ebbbc0 100644
--- a/R/coef.sparsestep.R
+++ b/R/coef.sparsestep.R
@@ -5,9 +5,10 @@
 #' @param object a \code{sparsestep} object
 #' @param \dots further argument are ignored
 #'
-#' @return The coefficients of the SparseStep model (i.e. the betas). If the
-#' model was fitted with an intercept this will be the first value in the
-#' resulting vector.
+#' @return The coefficients of the SparseStep model (i.e. the betas) as a 
+#' dgCMatrix. If the model was fitted with an intercept this will be the first
+#' row in the resulting matrix.
+#'
 #' @author
 #' Gerrit J.J. van den Burg, Patrick J.F. Groenen, Andreas Alfons\cr
 #' Maintainer: Gerrit J.J. van den Burg <gertjanvandenburg@gmail.com>
diff --git a/R/path.sparsestep.R b/R/path.sparsestep.R
index 429526f..01a9901 100644
--- a/R/path.sparsestep.R
+++ b/R/path.sparsestep.R
@@ -68,6 +68,7 @@
 #'  \emph{SparseStep: Approximating the Counting Norm for Sparse Regularization},
 #'  arXiv preprint arXiv:1701.06967 [stat.ME]. 
 #'  URL \url{https://arxiv.org/abs/1701.06967}.
+#'
 #' @seealso
 #' \code{\link{coef}}, \code{\link{print}}, \code{\link{predict}}, 
 #' \code{\link{plot}}, and \code{\link{sparsestep}}.
diff --git a/R/sparsestep-package.R b/R/sparsestep-package.R
index c1c5361..97fcd5b 100644
--- a/R/sparsestep-package.R
+++ b/R/sparsestep-package.R
@@ -38,6 +38,16 @@
 #'  arXiv preprint arXiv:1701.06967 [stat.ME]. 
 #'  URL \url{https://arxiv.org/abs/1701.06967}.
 #'
+#' @examples
+#' x <- matrix(rnorm(100*20), 100, 20)
+#' y <- rnorm(100)
+#' fit <- sparsestep(x, y)
+#' plot(fit)
+#' fits <- path.sparsestep(x, y)
+#' plot(fits)
+#' x2 <- matrix(rnorm(50*20), 50, 20)
+#' y2 <- predict(fits, x2)
+#'
 #' @name sparsestep-package
 #' @docType package
 #' @import Matrix
diff --git a/R/sparsestep.R b/R/sparsestep.R
index ef4ab22..f3c2901 100644
--- a/R/sparsestep.R
+++ b/R/sparsestep.R
@@ -1,6 +1,6 @@
-#' @title Fits the SparseStep model
+#' @title Fit the SparseStep model
 #'
-#' @description Fits the SparseStep model for a single value of the 
+#' @description Fits the SparseStep model for a chosen values of the 
 #' regularization parameter.
 #'
 #' @param x matrix of predictors
diff --git a/man/coef.sparsestep.Rd b/man/coef.sparsestep.Rd
index 4d713b5..0505cbc 100644
--- a/man/coef.sparsestep.Rd
+++ b/man/coef.sparsestep.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/coef.sparsestep.R
 \name{coef.sparsestep}
 \alias{coef}
@@ -13,9 +13,9 @@
 \item{\dots}{further argument are ignored}
 }
 \value{
-The coefficients of the SparseStep model (i.e. the betas). If the
-model was fitted with an intercept this will be the first value in the
-resulting vector.
+The coefficients of the SparseStep model (i.e. the betas) as a 
+dgCMatrix. If the model was fitted with an intercept this will be the first
+row in the resulting matrix.
 }
 \description{
 Returns the coefficients of the SparseStep model.
diff --git a/man/path.sparsestep.Rd b/man/path.sparsestep.Rd
index 935d17b..70faa7d 100644
--- a/man/path.sparsestep.Rd
+++ b/man/path.sparsestep.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/path.sparsestep.R
 \name{path.sparsestep}
 \alias{path.sparsestep}
@@ -20,22 +20,22 @@ path.sparsestep(x, y, max.depth = 10, gamma0 = 1000, gammastop = 1e-04,
 
 \item{gammastop}{stopping value of the gamma parameter}
 
-\item{IMsteps}{number of steps of the majorization algorithm to perform for
+\item{IMsteps}{number of steps of the majorization algorithm to perform for 
 each value of gamma}
 
 \item{gammastep}{factor to decrease gamma with at each step}
 
-\item{normalize}{if TRUE, each variable is standardized to have unit L2
+\item{normalize}{if TRUE, each variable is standardized to have unit L2 
 norm, otherwise it is left alone.}
 
-\item{intercept}{if TRUE, an intercept is included in the model (and not
+\item{intercept}{if TRUE, an intercept is included in the model (and not 
 penalized), otherwise no intercept is included}
 
-\item{force.zero}{if TRUE, absolute coefficients smaller than the provided
-threshold value are set to absolute zero as a post-processing step,
+\item{force.zero}{if TRUE, absolute coefficients smaller than the provided 
+threshold value are set to absolute zero as a post-processing step, 
 otherwise no thresholding is performed}
 
-\item{threshold}{threshold value to use for setting coefficients to
+\item{threshold}{threshold value to use for setting coefficients to 
 absolute zero}
 
 \item{XX}{The X'X matrix; useful for repeated runs where X'X stays the same}
@@ -47,7 +47,7 @@ absolute zero}
 \item{use.Xy}{whether or not to compute X'y and return it}
 }
 \value{
-A "sparsestep" S3 object is returned, for which print, predict,
+A "sparsestep" S3 object is returned, for which print, predict, 
 coef, and plot methods exist. It has the following items:
 \item{call}{The call that was used to construct the model.}
 \item{lambda}{The value(s) of lambda used to construct the model.}
@@ -55,12 +55,12 @@ coef, and plot methods exist. It has the following items:
 \item{gammastop}{The gammastop value of the model}
 \item{IMsteps}{The IMsteps value of the model}
 \item{gammastep}{The gammastep value of the model}
-\item{intercept}{Boolean indicating if an intercept was fitted in the
+\item{intercept}{Boolean indicating if an intercept was fitted in the 
 model}
-\item{force.zero}{Boolean indicating if a force zero-setting was
+\item{force.zero}{Boolean indicating if a force zero-setting was 
 performed.}
 \item{threshold}{The threshold used for a forced zero-setting}
-\item{beta}{The resulting coefficients stored in a sparse matrix format
+\item{beta}{The resulting coefficients stored in a sparse matrix format 
 (dgCMatrix). This matrix has dimensions nvar x nlambda}
 \item{a0}{The intercept vector for each value of gamma of length nlambda}
 \item{normx}{Vector used to normalize the columns of x}
@@ -69,18 +69,18 @@ performed.}
 \item{Xy}{The matrix X'y if use.Xy was set to TRUE}
 }
 \description{
-Fits the entire regularization path for SparseStep using a
-Golden Section search. Note that this algorithm is approximate, there is no
-guarantee that the solutions _between_ induced values of lambdas do not
-differ from those calculated. For instance, if solutions are calculated at
-\eqn{\lambda_{i}}{\lambda[i]} and \eqn{\lambda_{i+1}}{\lambda[i+1]}, this
-algorithm ensures that \eqn{\lambda_{i+1}}{\lambda[i+1]} has one more zero
-than the solution at \eqn{\lambda_{i}}{\lambda[i]} (provided the recursion
-depth is large enough). There is however no guarantee that there are no
-different solutions between \eqn{\lambda_{i}}{\lambda[i]} and
+Fits the entire regularization path for SparseStep using a 
+Golden Section search. Note that this algorithm is approximate, there is no 
+guarantee that the solutions _between_ induced values of lambdas do not 
+differ from those calculated. For instance, if solutions are calculated at 
+\eqn{\lambda_{i}}{\lambda[i]} and \eqn{\lambda_{i+1}}{\lambda[i+1]}, this 
+algorithm ensures that \eqn{\lambda_{i+1}}{\lambda[i+1]} has one more zero 
+than the solution at \eqn{\lambda_{i}}{\lambda[i]} (provided the recursion 
+depth is large enough). There is however no guarantee that there are no 
+different solutions between \eqn{\lambda_{i}}{\lambda[i]} and 
 \eqn{\lambda_{i+1}}{\lambda[i+1]}.  This is an ongoing research topic.
 
-Note that this path algorithm is not faster than running the
+Note that this path algorithm is not faster than running the 
 \code{sparsestep} function with the same \eqn{\lambda} sequence.
 }
 \examples{
@@ -100,7 +100,7 @@ Van den Burg, G.J.J., Groenen, P.J.F. and Alfons, A. (2017).
  URL \url{https://arxiv.org/abs/1701.06967}.
 }
 \seealso{
-\code{\link{coef}}, \code{\link{print}}, \code{\link{predict}},
+\code{\link{coef}}, \code{\link{print}}, \code{\link{predict}}, 
 \code{\link{plot}}, and \code{\link{sparsestep}}.
 }
 
diff --git a/man/plot.sparsestep.Rd b/man/plot.sparsestep.Rd
index 88c8d67..0fd0171 100644
--- a/man/plot.sparsestep.Rd
+++ b/man/plot.sparsestep.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/plot.sparsestep.R
 \name{plot.sparsestep}
 \alias{plot}
diff --git a/man/predict.sparsestep.Rd b/man/predict.sparsestep.Rd
index 8318c34..d738e78 100644
--- a/man/predict.sparsestep.Rd
+++ b/man/predict.sparsestep.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/predict.sparsestep.R
 \name{predict.sparsestep}
 \alias{predict}
@@ -10,7 +10,7 @@
 \arguments{
 \item{object}{Fitted \code{sparsestep} object}
 
-\item{newx}{Matrix of new values for \code{x} at which predictions are to
+\item{newx}{Matrix of new values for \code{x} at which predictions are to 
 be made.}
 
 \item{\dots}{further argument are ignored}
@@ -19,7 +19,7 @@ be made.}
 a matrix of numerical predictions of size nobs x nlambda
 }
 \description{
-Predicts the outcome variable for the SparseStep model for
+Predicts the outcome variable for the SparseStep model for 
 each value of lambda supplied to the model.
 }
 \examples{
diff --git a/man/print.sparsestep.Rd b/man/print.sparsestep.Rd
index 2baa6bc..3a9e200 100644
--- a/man/print.sparsestep.Rd
+++ b/man/print.sparsestep.Rd
@@ -1,4 +1,4 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/print.sparsestep.R
 \name{print.sparsestep}
 \alias{print}
diff --git a/man/sparsestep-package.Rd b/man/sparsestep-package.Rd
index 67ca27d..9bf2144 100644
--- a/man/sparsestep-package.Rd
+++ b/man/sparsestep-package.Rd
@@ -1,39 +1,50 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/sparsestep-package.R
 \docType{package}
 \name{sparsestep-package}
 \alias{sparsestep-package}
 \title{SparseStep: Approximating the Counting Norm for Sparse Regularization}
 \description{
-In the SparseStep regression model the ordinary least-squares problem is
-augmented with an approximation of the exact \eqn{\ell_0}{l[0]} pseudonorm.
-This approximation is made increasingly more accurate in the SparseStep
-algorithm, resulting in a sparse solution to the regression problem. See
+In the SparseStep regression model the ordinary least-squares problem is 
+augmented with an approximation of the exact \eqn{\ell_0}{l[0]} pseudonorm.  
+This approximation is made increasingly more accurate in the SparseStep 
+algorithm, resulting in a sparse solution to the regression problem. See 
 the references for more information.
 }
 \section{SparseStep functions}{
 
 The main SparseStep functions are:
 \describe{
-\item{\code{\link{sparsestep}}}{Fit a SparseStep model for a given range of
+\item{\code{\link{sparsestep}}}{Fit a SparseStep model for a given range of 
 \eqn{\lambda} values}
-\item{\code{\link{path.sparsestep}}}{Fit the SparseStep model along a path
-of \eqn{\lambda} values which are generated such that a model is created at
-each possible level of sparsity, or until a given recursion depth is
+\item{\code{\link{path.sparsestep}}}{Fit the SparseStep model along a path 
+of \eqn{\lambda} values which are generated such that a model is created at 
+each possible level of sparsity, or until a given recursion depth is 
 reached.}
 }
 
 Other available functions are:
 \describe{
-\item{\code{\link{plot}}}{Plot the coefficient path of the SparseStep
+\item{\code{\link{plot}}}{Plot the coefficient path of the SparseStep 
 model.}
-\item{\code{\link{predict}}}{Predict the outcome of the linear model using
+\item{\code{\link{predict}}}{Predict the outcome of the linear model using 
 SparseStep}
 \item{\code{\link{coef}}}{Get the coefficients from the SparseStep model}
-\item{\code{\link{print}}}{Print a short description of the SparseStep
+\item{\code{\link{print}}}{Print a short description of the SparseStep 
 model}
 }
 }
+\examples{
+x <- matrix(rnorm(100*20), 100, 20)
+y <- rnorm(100)
+fit <- sparsestep(x, y)
+plot(fit)
+fits <- path.sparsestep(x, y)
+plot(fits)
+x2 <- matrix(rnorm(50*20), 50, 20)
+y2 <- predict(fits, x2)
+
+}
 \author{
 Gerrit J.J. van den Burg, Patrick J.F. Groenen, Andreas Alfons\cr
 Maintainer: Gerrit J.J. van den Burg <gertjanvandenburg@gmail.com>
diff --git a/man/sparsestep.Rd b/man/sparsestep.Rd
index 7e8fa44..d00b47c 100644
--- a/man/sparsestep.Rd
+++ b/man/sparsestep.Rd
@@ -1,8 +1,8 @@
-% Generated by roxygen2 (4.1.1): do not edit by hand
+% Generated by roxygen2: do not edit by hand
 % Please edit documentation in R/sparsestep.R
 \name{sparsestep}
 \alias{sparsestep}
-\title{Fits the SparseStep model}
+\title{Fit the SparseStep model}
 \usage{
 sparsestep(x, y, lambda = c(0.1, 0.5, 1, 5, 10), gamma0 = 1000,
   gammastop = 1e-04, IMsteps = 2, gammastep = 2, normalize = TRUE,
@@ -20,34 +20,34 @@ sparsestep(x, y, lambda = c(0.1, 0.5, 1, 5, 10), gamma0 = 1000,
 
 \item{gammastop}{stopping value of the gamma parameter}
 
-\item{IMsteps}{number of steps of the majorization algorithm to perform for
+\item{IMsteps}{number of steps of the majorization algorithm to perform for 
 each value of gamma}
 
 \item{gammastep}{factor to decrease gamma with at each step}
 
-\item{normalize}{if TRUE, each variable is standardized to have unit L2
+\item{normalize}{if TRUE, each variable is standardized to have unit L2 
 norm, otherwise it is left alone.}
 
-\item{intercept}{if TRUE, an intercept is included in the model (and not
+\item{intercept}{if TRUE, an intercept is included in the model (and not 
 penalized), otherwise no intercept is included}
 
-\item{force.zero}{if TRUE, absolute coefficients smaller than the provided
-threshold value are set to absolute zero as a post-processing step,
+\item{force.zero}{if TRUE, absolute coefficients smaller than the provided 
+threshold value are set to absolute zero as a post-processing step, 
 otherwise no thresholding is performed}
 
-\item{threshold}{threshold value to use for setting coefficients to
+\item{threshold}{threshold value to use for setting coefficients to 
 absolute zero}
 
 \item{XX}{The X'X matrix; useful for repeated runs where X'X stays the same}
 
 \item{Xy}{The X'y matrix; useful for repeated runs where X'y stays the same}
 
-\item{use.XX}{whether or not to compute X'X and return it}
+\item{use.XX}{whether or not to compute X'X and return it (boolean)}
 
-\item{use.Xy}{whether or not to compute X'y and return it}
+\item{use.Xy}{whether or not to compute X'y and return it (boolean)}
 }
 \value{
-A "sparsestep" S3 object is returned, for which print, predict,
+A "sparsestep" S3 object is returned, for which print, predict, 
 coef, and plot methods exist. It has the following items:
 \item{call}{The call that was used to construct the model.}
 \item{lambda}{The value(s) of lambda used to construct the model.}
@@ -55,12 +55,12 @@ coef, and plot methods exist. It has the following items:
 \item{gammastop}{The gammastop value of the model}
 \item{IMsteps}{The IMsteps value of the model}
 \item{gammastep}{The gammastep value of the model}
-\item{intercept}{Boolean indicating if an intercept was fitted in the
+\item{intercept}{Boolean indicating if an intercept was fitted in the 
 model}
-\item{force.zero}{Boolean indicating if a force zero-setting was
+\item{force.zero}{Boolean indicating if a force zero-setting was 
 performed.}
 \item{threshold}{The threshold used for a forced zero-setting}
-\item{beta}{The resulting coefficients stored in a sparse matrix format
+\item{beta}{The resulting coefficients stored in a sparse matrix format 
 (dgCMatrix). This matrix has dimensions nvar x nlambda}
 \item{a0}{The intercept vector for each value of gamma of length nlambda}
 \item{normx}{Vector used to normalize the columns of x}
@@ -69,7 +69,7 @@ performed.}
 \item{Xy}{The matrix X'y if use.Xy was set to TRUE}
 }
 \description{
-Fits the SparseStep model for a single value of the
+Fits the SparseStep model for a chosen values of the 
 regularization parameter.
 }
 \examples{
@@ -89,7 +89,7 @@ Van den Burg, G.J.J., Groenen, P.J.F. and Alfons, A. (2017).
  URL \url{https://arxiv.org/abs/1701.06967}.
 }
 \seealso{
-\code{\link{coef}}, \code{\link{print}}, \code{\link{predict}},
+\code{\link{coef}}, \code{\link{print}}, \code{\link{predict}}, 
 \code{\link{plot}}, and \code{\link{path.sparsestep}}.
 }