Value-fields and additional CRAN fine-tuning

DESCRIPTION

@@ -18,9 +18,9 @@ Description: Optimal Subset Cardinality Regression (OSCAR) models offer
     non-convex optimization task. These optimization modules include DBDC
     ('Double Bundle method for nonsmooth DC optimization' as described in
     Joki et al. (2018) <doi:10.1137/16M1115733>) and LMBM ('Limited
-    Memory Bundle Method for large-scale nonsmooth optimization' as 
-    in Haarala et al. (2004) <doi:10.1080/10556780410001689225>). 
-    Multiple regression model families are supported: Cox, logistic, 
+    Memory Bundle Method for large-scale nonsmooth optimization' as
+    in Haarala et al. (2004) <doi:10.1080/10556780410001689225>).
+    Multiple regression model families are supported: Cox, logistic,
     and Gaussian.
 License: GPL-3
 LazyData: true

R/fitS4.R

@@ -579,7 +579,7 @@ oscar <- function(
 #'
 #' @return A list of sanity checked parameter values for the OSCAR optimizers.
 #'
-#' @details This function sanity checks and provides reasonable DBDC and LMBM optimization tuning parameters. User may override custom values, though sanity checks will prevent unreasonable values and replace them. The returned list of parameters can be provided for the 'control' parameter when fitting oscar-objects.
+#' @details This function sanity checks and provides reasonable DBDC ('Double Bundle method for nonsmooth DC optimization' as described in Joki et al. (2018) <doi:10.1137/16M1115733>) and LMBM ('Limited Memory Bundle Method for large-scale nonsmooth optimization' as presented in Haarala et al. (2004) <doi:10.1080/10556780410001689225>) optimization tuning parameters. User may override custom values, though sanity checks will prevent unreasonable values and replace them. The returned list of parameters can be provided for the 'control' parameter when fitting oscar-objects.
 #'
 #' @examples 
 #' if(interactive()){

R/funcsS4.R

@@ -15,6 +15,8 @@
 #'
 #' @param object Fit oscar S4-object
 #'
+#' @return Outputs raw text describing key characteristics of the oscar-object
+#'
 #' @rdname generics
 #' @export
 setMethod("show", "oscar",
@@ -32,6 +34,8 @@ setMethod("show", "oscar",
 #' @param object Fit oscar S4-object
 #' @param k Cardinality 'k' to extract coefficients at
 #'
+#' @return Vector of model coefficient values at given cardinality 'k'
+#'
 #' @export
 #' @docType methods
 #' @rdname oscar-methods
@@ -55,6 +59,8 @@ setMethod("coef", "oscar",
 #' @param type Type of prediction; valid values are 'response', 'link', 'nonzero', 'coefficients', or 'label'
 #' @param newdata Data to predict on; if no alternate is supplied, the function uses the original 'x' data matrix used to fit object
 #'
+#' @return A vector of coefficient predictions at the specificied cardinality 'k' with a format depending on the supplied 'type' parameter
+#'
 #' @export
 #' @docType methods
 #' @rdname oscar-methods
@@ -112,6 +118,8 @@ setMethod("predict", "oscar",
 #' @param intercept Should model intercept be plotted, Default: FALSE
 #' @param ... Additional parameters passed on to the points-function drawing lines as a function of cardinality
 #'
+#' @return Override default plot function with no return but instead tailor suitable graphics plotting
+#'
 #' @export
 #' @docType methods
 #' @rdname oscar-methods
@@ -159,6 +167,8 @@ setMethod("plot", "oscar",
 #' @param object Fit oscar S4-object 
 #' @param k Cardinality 'k' to extract non-zero features at
 #'
+#' @return Vector of feature indices at cardinality 'k'
+#'
 #' @docType methods
 #' @export
 #' @aliases feat,oscar-methods
@@ -173,6 +183,8 @@ setGeneric("feat",
 #' @param object Fit oscar S4-object 
 #' @param k Cardinality 'k' to extract non-zero features at
 #'
+#' @return Vector of feature indices at cardinality 'k'
+#'
 #' @docType methods
 #' @export
 #' @aliases feat,oscar-methods
@@ -197,6 +209,8 @@ setMethod("feat", "oscar",
 #' @param object Fit oscar S4-object 
 #' @param k Cardinality 'k' to extract kit indices at
 #'
+#' @return Vector of kit indices at cardinality 'k'
+#'
 #' @docType methods
 #' @export
 #' @aliases kits,oscar-methods
@@ -211,6 +225,8 @@ setGeneric("kits",
 #' @param object Fit oscar S4-object 
 #' @param k Cardinality 'k' to extract kit indices at
 #'
+#' @return Vector of kit indices at cardinality 'k'
+#'
 #' @docType methods
 #' @export
 #' @aliases kits,oscar-methods
@@ -241,6 +257,8 @@ setMethod("kits", "oscar",
 #' @param object Fit oscar S4-object 
 #' @param k Cardinality 'k' to compute total feature cost at
 #'
+#' @return Numeric value of total feature/kit cost at cardinality 'k'
+#'
 #' @aliases cost,oscar-methods
 #' @export
 #' @docType methods
@@ -255,6 +273,8 @@ setGeneric("cost",
 #' @param object Fit oscar S4-object 
 #' @param k Cardinality 'k' to compute total feature cost at
 #'
+#' @return Numeric value of total feature/kit cost at cardinality 'k'
+#'
 #' @aliases cost,oscar-methods
 #' @export
 #' @docType methods
@@ -273,4 +293,3 @@ setMethod("cost", "oscar",
 		sum(object@w[kits])
 	}
 )
-

R/helpers.R

@@ -5,15 +5,20 @@
 ####
 
 #' @title Cross-validation for oscar-fitted model objects over k-range
+#'
 #' @description Create a cross-validation matrix with the chosen goodness metric with n-folds. Based on the goodness metric, one ought to pick optimal cardinality (parameter 'k').
+#'
 #' @param fit oscar-model object
 #' @param fold Number of cross-validation folds, Default: 10
 #' @param seed Random seed for reproducibility with NULL indicating that it is not set, Default: NULL
 #' @param strata Should stratified cross-validation be used; separate values indicate balanced strata. Default: Unit vector, which will treat all observations equally.
 #' @param verb Level of verbosity with higher integer giving more information, Default: 0
 #' @param ... Additional parameters passed to oscar-function
+#'
 #' @return A matrix with goodness of fit over folds and k-values
+#'
 #' @details A k-fold cross-validation is run by mimicking the parameters contained in the original oscar S4-object. This requires the original data at slots @x and @y.
+#*
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -183,14 +188,19 @@ oscar.cv <- function(
 }
 
 #' @title Bootstrapping for oscar-fitted model objects
+#'
 #' @description This model bootstraps the fitting of a given oscar object (re-fits the model for data that is equal in size but sampled with replacement). The output objects give insight into robustness of the oscar-coefficient path, as well as relative importance of model objects.
+#'
 #' @param fit oscar-model object
 #' @param bootstrap Number of bootstrapped datasets, Default: 100
 #' @param seed Random seed for reproducibility with NULL indicating that it is not set, Default: NULL
 #' @param verb Level of verbosity with higher integer giving more information, Default: 0
 #' @param ... Additional parameters passed to oscar-function
+#'
 #' @return 3-dimensional array with dimensions corresponding to k-steps, beta coefficients, and bootstrap runs
+#'
 #' @details The function provides a fail-safe try-catch in an event of non-convergence of the model fitting procedure. This may occur for example if a bootstrapped data matrix has a column consist of a single value only over all observations.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -242,8 +252,11 @@ oscar.bs <- function(
 }
 
 #' @title Reformatting bootstrap output for cardinality k rows
+#'
 #' @description The function reformats bootstrapped runs to a single long data.frame, where all bootstrapped runs are covered along with the choices for the variables at each cardinality 'k'.
+#'
 #' @param bs Bootstrapped list from oscar.bs
+#'
 #' @return Reformatted data.frame
 #'
 #' @examples 
@@ -292,11 +305,16 @@ oscar.bs.k <- function(
 }
 
 #' @title Create a sparse matrix representation of betas as a function of k
+#'
 #' @description Variable estimates (rows) as a function of cardinality (k, columns). Since a model can drop out variables in favor of two better ones as k increases, this sparse representation helps visualize which variables are included at what cardinality.
+#'
 #' @param fit oscar-model object
 #' @param kmax Create matrix until kmax-value; by default same as for fit object, but for high dimensional tasks one may wish to reduce this
+#'
 #' @return A sparse matrix of variables (rows) as a function of cardinality k (columns), where elements are the beta estimates.
+#'
 #' @details Uses sparseMatrix-class from Matrix-package
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -337,11 +355,16 @@ oscar.sparsify <- function(
 }
 
 #' @title Binary logical indicator matrix representation of an oscar object's coefficients (zero vs. non-zero, i.e. feature inclusion)
+#'
 #' @description Create a sparse matrix with binary indicator 1 indicating that a coefficient was non-zero, and value 0 (or . in sparse matrix) indicating that a coefficient was zero (i.e. feature not included)
+#'
 #' @param fit Fit oscar-model object
 #' @param kmax Create matrix until kmax-value; by default same as for fit object, but for high dimensional tasks one may wish to reduce this
+#'
 #' @return A binary logical indicator matrix of variables (rows) as a function of cardinality k (columns), where elements are binary indicators for 1 as non-zero and 0 as zero.
+#'
 #' @details The matrix consists of TRUE/FALSE values, and is very similar to the oscar.sparsify, where the function provides estimate values in a sparse matrix format.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -365,9 +388,9 @@ oscar.binarize <- function(
 	binmat[,1:kmax]
 }
 
-#' Retriever a set pareto-optimal points for an oscar-model based on model goodness-of-fit or cross-validation
+#' @title Retrieve a set of pareto-optimal points for an oscar-model based on model goodness-of-fit or cross-validation
 #'
-#' This function retrieves the set of pareto optimal points for an oscar model fit in n-proportional time as cardinality axis is readily sorted. It is advisable to optimize model generalization (via cross-validation) rather than mere goodness-of-fit.
+#' @description This function retrieves the set of pareto optimal points for an oscar model fit in n-proportional time as cardinality axis is readily sorted. It is advisable to optimize model generalization (via cross-validation) rather than mere goodness-of-fit.
 #'
 #' @param fit Fit oscar S4-object
 #' @param cv A cross-validation matrix as produced by oscar.cv; if CV is not provided, then goodness-of-fit from fit object itself is used rather than cross-validation generalization metric
@@ -376,6 +399,7 @@ oscar.binarize <- function(
 #' @param summarize Function that summarizes over cross-validation folds; by default, this is the mean over the k-folds.
 #' 
 #' @return A data.frame containing points and indices at which pareto optimal points exist
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -384,6 +408,7 @@ oscar.binarize <- function(
 #'   oscar.pareto(fit, cv=fit_cv)
 #' }
 #'
+#' @rdname oscar.pareto
 #' @export
 oscar.pareto <- function(
 	fit,
@@ -440,25 +465,28 @@ oscar.pareto <- function(
 		res <- do.call("rbind", by(res, INDICES=res[,1], FUN=function(x) { x[which(!x[,2]==max(x[,2])),3]<-FALSE; x }))
 		rownames(res) <- NULL
 	}
-		# Return to original point ordering
+	# Return to original point ordering
 	res <- res[order(res$ord),]
 	res
 }
 
-#' Return total cost of model fits if the cost is not included in the oscar object
+#' @title Return total cost of model fits if the cost is not included in the oscar object
 #'
-#' If at least one measurement from a kit is included in the model, the kit cost is added.
+#' @description If at least one measurement from a kit is included in the model, the kit cost is added.
 #'
 #' @param object Fit oscar S4-object 
+#'
+#' @return A vector for numeric values of total kit costs at different cardinalities.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
 #'   fit <- oscar(x=ex_X, y=ex_Y, k=ex_K, w=ex_c, family='cox')
 #'   oscar.cost.after(fit)
 #' }
 #'
+#' @rdname oscar.cost.after
 #' @export
-#cost.after <- function(object, kit.matrix, cost.vector){
 oscar.cost.after <- function(object){
 
 	# The values are readily stored in oscar S4-objects

R/visu.R

@@ -16,6 +16,8 @@
 #' @param add Should plot be added into an existing frame / plot
 #' @param main Main title
 #'
+#' @return This is a plotting function that does not return anything, but instead draws on an existing or a new graphics device.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -134,6 +136,8 @@ oscar.visu <- function(
 #' @param intercept Whether model intercept should be plotted also as a coefficient, Default: FALSE
 #' @param add Should plot be added on top of an existing plot device
 #'
+#' @return This is a plotting function that does not return anything, but instead draws on an existing or a new graphics device.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -185,6 +189,8 @@ oscar.bs.visu <- function(
 #' @param ylab Y-axis label
 #' @param ... Additional parameters passed on top the CV points
 #'
+#' @return This is a plotting function that does not return anything, but instead draws on an existing or a new graphics device.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -230,6 +236,8 @@ oscar.cv.visu <- function(
 #' @param bs Bootstrapped 3-dimensional array for an oscar object as produced by oscar.bs
 #' @param ... Additional parameters passed on to barplot
 #'
+#' @return This is a plotting function that does not return anything, but instead draws on a new graphics device.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -283,6 +291,8 @@ oscar.bs.boxplot <- function(
 #' @param heights Paneling proportions as a numeric vector of length 2
 #' @param ... Additional parameters passed on to hamlet::hmap
 #'
+#' @return This is a plotting function that does not return anything, but instead draws on a new graphics device.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)
@@ -356,6 +366,8 @@ oscar.binplot <- function(
 #' @param Rowv Row re-ordering indices or a readily built dendrogram
 #' @param ... Additional parameters passed on to the hamlet::hmap function
 #'
+#' @return This is a plotting function that does not return anything, but instead draws on a new graphics device.
+#'
 #' @details Further heatmap parameters available from ?hmap
 #'
 #' @examples 
@@ -421,6 +433,8 @@ oscar.bs.plot <- function(
 #' @param add If the fit should be added on top of an existing plot; in that case leaving out labels etc. By default new plot is called.
 #' @param ... Additional parameters provided for the plotting functions
 #'
+#' @return This is a plotting function that does not return anything, but instead draws on an existing or a new graphics device.
+#'
 #' @examples 
 #' if(interactive()){
 #'   data(ex)