Repository: kkholst/targeted
Pull request #54: develop: inherit roxygen documentation for `predictor_` functions
Author: login: benesom
Created: 2025-05-09T06:21:15Z | Merged: 2025-05-16T07:45:54Z

We are currently missing roxygen documentation for the arguments of all `predictor_` functions. This is a suggestion to inherit the documentation from the estimators that we're instantiating as `ml_model` objects. Inherinting the roxygen documentation requires that the package that implements the estimator is listed in the `DESCRIPTION` file, either as a suggested or imported package.  


Diff:
diff --git a/NAMESPACE b/NAMESPACE
index e1030989..533dab92 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -132,6 +132,7 @@ importFrom(stats,model.frame)
 importFrom(stats,model.matrix)
 importFrom(stats,model.offset)
 importFrom(stats,model.response)
+importFrom(stats,na.omit)
 importFrom(stats,na.pass)
 importFrom(stats,nlminb)
 importFrom(stats,pchisq)
@@ -139,6 +140,7 @@ importFrom(stats,predict)
 importFrom(stats,quantile)
 importFrom(stats,reformulate)
 importFrom(stats,runif)
+importFrom(stats,sd)
 importFrom(stats,terms)
 importFrom(stats,uniroot)
 importFrom(stats,update)
diff --git a/R/ml_model.R b/R/ml_model.R
index 9ed7c215..4453bad3 100644
--- a/R/ml_model.R
+++ b/R/ml_model.R
@@ -1,18 +1,12 @@
 #' @title R6 class for prediction models
-#' @description Provides standardized estimation and prediction methods
+#' @description Interface for standardized estimation and prediction The
+#' following built-in learners are provided: [predictor_glm], [predictor_gam]
 #' @param data data.frame
 #' @author Klaus Kähler Holst
-#' @aliases ml_model predictor
-#' predictor_glm predictor_gam predictor_glmnet
-#' predictor_grf predictor_grf_binary
-#' predictor_xgboost predictor_xgboost_multiclass
-#' predictor_xgboost_count predictor_xgboost_cox
-#' predictor_xgboost_binary
-#' predictor_hal predictor_isoreg
-#' predictor_svm
-#' predictor_mars
-#' predictor_nb
-#' @seealso predictor_sl
+#' @aliases predictor_gam predictor_grf predictor_grf_binary predictor_isoreg
+#' predictor_mars predictor_nb predictor_svm predictor_xgboost_binary
+#' predictor_xgboost predictor_xgboost_count predictor_xgboost_cox
+#' predictor_xgboost_multiclass
 #' @examples
 #' data(iris)
 #' rf <- function(formula, ...) {
diff --git a/R/predictor.R b/R/predictor.R
index 0836d253..01f10147 100644
--- a/R/predictor.R
+++ b/R/predictor.R
@@ -1,4 +1,22 @@
+#' @title Instantiate a learner
+#' @param info (character) Optional information to describe the instantiated
+#' [ml_model] object.
+#' @param formula (formula or character) Formula specifying response and design
+#' matrix.
+#' @param learner.args (list) Additional arguments to
+#' [ml_model$new()][ml_model].
+#' @return [ml_model] object.
+#' @name predictor
+NULL
+
+
+#' @description [ml_model] generator function for generalized linear models with
+#' [stats::glm] and [MASS::glm.nb]. Negative binomial regression is supported
+#' with `family = "nb"` (or alternatively `family = "negbin"`).
+#' @param ... Additional arguments to [stats::glm] or [MASS::glm.nb].
 #' @export
+#' @inherit predictor
+#' @inheritParams stats::glm
 predictor_glm <- function(formula,
                           info = "glm",
                           family = gaussian(),
@@ -33,7 +51,12 @@ predictor_glm <- function(formula,
   return(mod)
 }
 
+#' @description [ml_model] generator function for [glmnet::cv.glmnet]. Defaults
+#' to [glmnet::glmnet] for `nfolds = 1`.
 #' @export
+#' @inherit predictor
+#' @inheritParams glmnet::glmnet
+#' @inheritParams glmnet::cv.glmnet
 predictor_glmnet <- function(formula,
                              info = "glmnet",
                              family = gaussian(),
@@ -74,7 +97,11 @@ predictor_glmnet <- function(formula,
   return(mod)
 }
 
+#' @description [ml_model] generator function for [hal9001::fit_hal].
 #' @export
+#' @param ... Additional arguments to [hal9001::fit_hal].
+#' @inherit predictor
+#' @inheritParams hal9001::fit_hal
 predictor_hal <- function(formula,
                           info = "hal9001::fit_hal",
                           smoothness_orders = 0,
@@ -209,6 +236,7 @@ predictor_svm <- function(formula,
 }
 
 #' @export
+#' @inherit predictor
 #' @title Superlearner (stacked/ensemble learner)
 #' @description This function creates a predictor object (class [ml_model])
 #'   from a list of existing [ml_model] objects. When estimating this model a
@@ -216,10 +244,7 @@ predictor_svm <- function(formula,
 #'   of each of the initial models. The weights are learned using
 #'   cross-validation.
 #' @param model.list (list) List of [ml_model] objects (i.e. [predictor_glm])
-#' @param info Optional model description to store in model object
 #' @param nfolds Number of folds to use in cross validation
-#' @param learner.args (list) Additional arguments to
-#' [ml_model$new()][ml_model].
 #' @param meta.learner meta.learner function (default non-negative least
 #'   squares). Must be a function of the response (nx1 vector), `y`, and the
 #'   predictions (nxp matrix), `pred`.
diff --git a/R/targeted-package.R b/R/targeted-package.R
index 83403a02..4d341187 100644
--- a/R/targeted-package.R
+++ b/R/targeted-package.R
@@ -15,7 +15,7 @@
 #'   lm.wfit lm.fit glm lm coef vcov model.frame model.matrix na.pass nlminb
 #'   predict dnorm quantile terms weighted.mean runif .getXlevels
 #'   delete.response model.response gaussian formula model.offset reformulate
-#'   drop.terms weights model.extract cov2cor pchisq uniroot
+#'   drop.terms weights model.extract cov2cor pchisq uniroot sd na.omit
 #' @importFrom rlang hash call_match
 #' @importFrom optimx optimx
 #' @importFrom data.table data.table is.data.table dcast :=
diff --git a/man/ml_model.Rd b/man/ml_model.Rd
index 8c7b8eb1..e13a70de 100644
--- a/man/ml_model.Rd
+++ b/man/ml_model.Rd
@@ -2,25 +2,22 @@
 % Please edit documentation in R/ml_model.R
 \name{ml_model}
 \alias{ml_model}
-\alias{predictor}
-\alias{predictor_glm}
 \alias{predictor_gam}
-\alias{predictor_glmnet}
 \alias{predictor_grf}
 \alias{predictor_grf_binary}
-\alias{predictor_xgboost}
-\alias{predictor_xgboost_multiclass}
-\alias{predictor_xgboost_count}
-\alias{predictor_xgboost_cox}
-\alias{predictor_xgboost_binary}
-\alias{predictor_hal}
 \alias{predictor_isoreg}
-\alias{predictor_svm}
 \alias{predictor_mars}
 \alias{predictor_nb}
+\alias{predictor_svm}
+\alias{predictor_xgboost_binary}
+\alias{predictor_xgboost}
+\alias{predictor_xgboost_count}
+\alias{predictor_xgboost_cox}
+\alias{predictor_xgboost_multiclass}
 \title{R6 class for prediction models}
 \description{
-Provides standardized estimation and prediction methods
+Interface for standardized estimation and prediction The
+following built-in learners are provided: \link{predictor_glm}, \link{predictor_gam}
 }
 \examples{
 data(iris)
@@ -60,9 +57,6 @@ ff <- ml_model$new(
 ## tmp <- ff$estimate(y, x=x)
 ## ff$predict(x)
 }
-\seealso{
-predictor_sl
-}
 \author{
 Klaus Kähler Holst
 }
diff --git a/man/predictor.Rd b/man/predictor.Rd
new file mode 100644
index 00000000..f548f4fd
--- /dev/null
+++ b/man/predictor.Rd
@@ -0,0 +1,21 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/predictor.R
+\name{predictor}
+\alias{predictor}
+\title{Instantiate a learner}
+\arguments{
+\item{info}{(character) Optional information to describe the instantiated
+\link{ml_model} object.}
+
+\item{formula}{(formula or character) Formula specifying response and design
+matrix.}
+
+\item{learner.args}{(list) Additional arguments to
+\link[=ml_model]{ml_model$new()}.}
+}
+\value{
+\link{ml_model} object.
+}
+\description{
+Instantiate a learner
+}
diff --git a/man/predictor_glm.Rd b/man/predictor_glm.Rd
new file mode 100644
index 00000000..95a53a06
--- /dev/null
+++ b/man/predictor_glm.Rd
@@ -0,0 +1,41 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/predictor.R
+\name{predictor_glm}
+\alias{predictor_glm}
+\title{Instantiate a learner}
+\usage{
+predictor_glm(
+  formula,
+  info = "glm",
+  family = gaussian(),
+  learner.args = NULL,
+  ...
+)
+}
+\arguments{
+\item{formula}{(formula or character) Formula specifying response and design
+matrix.}
+
+\item{info}{(character) Optional information to describe the instantiated
+\link{ml_model} object.}
+
+\item{family}{a description of the error distribution and link
+    function to be used in the model.  For \code{glm} this can be a
+    character string naming a family function, a family function or the
+    result of a call to a family function.  For \code{glm.fit} only the
+    third option is supported.  (See \code{\link[stats]{family}} for details of
+    family functions.)}
+
+\item{learner.args}{(list) Additional arguments to
+\link[=ml_model]{ml_model$new()}.}
+
+\item{...}{Additional arguments to \link[stats:glm]{stats::glm} or \link[MASS:glm.nb]{MASS::glm.nb}.}
+}
+\value{
+\link{ml_model} object.
+}
+\description{
+\link{ml_model} generator function for generalized linear models with
+\link[stats:glm]{stats::glm} and \link[MASS:glm.nb]{MASS::glm.nb}. Negative binomial regression is supported
+with \code{family = "nb"} (or alternatively \code{family = "negbin"}).
+}
diff --git a/man/predictor_glmnet.Rd b/man/predictor_glmnet.Rd
new file mode 100644
index 00000000..5f2c3f9d
--- /dev/null
+++ b/man/predictor_glmnet.Rd
@@ -0,0 +1,56 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/predictor.R
+\name{predictor_glmnet}
+\alias{predictor_glmnet}
+\title{Instantiate a learner}
+\usage{
+predictor_glmnet(
+  formula,
+  info = "glmnet",
+  family = gaussian(),
+  alpha = 1,
+  lambda = NULL,
+  nfolds = 10,
+  ...
+)
+}
+\arguments{
+\item{formula}{(formula or character) Formula specifying response and design
+matrix.}
+
+\item{info}{(character) Optional information to describe the instantiated
+\link{ml_model} object.}
+
+\item{family}{Either a character string representing
+one of the built-in families, or else a \code{glm()} family object. For more
+information, see Details section below or the documentation for response
+type (above).}
+
+\item{alpha}{The elasticnet mixing parameter, with \eqn{0\le\alpha\le 1}.
+The penalty is defined as
+\deqn{(1-\alpha)/2||\beta||_2^2+\alpha||\beta||_1.} \code{alpha=1} is the
+lasso penalty, and \code{alpha=0} the ridge penalty.}
+
+\item{lambda}{A user supplied \code{lambda} sequence. Typical usage is to
+have the program compute its own \code{lambda} sequence based on
+\code{nlambda} and \code{lambda.min.ratio}. Supplying a value of
+\code{lambda} overrides this. WARNING: use with care. Avoid supplying a
+single value for \code{lambda} (for predictions after CV use
+\code{predict()} instead).  Supply instead a decreasing sequence of
+\code{lambda} values. \code{glmnet} relies on its warms starts for speed,
+and its often faster to fit a whole path than compute a single fit.}
+
+\item{nfolds}{number of folds - default is 10. Although \code{nfolds} can be
+as large as the sample size (leave-one-out CV), it is not recommended for
+large datasets. Smallest value allowable is \code{nfolds=3}}
+
+\item{...}{Additional argument used in \code{relax.glmnet}. These include
+some of the original arguments to 'glmnet', and each must be named if used.}
+}
+\value{
+\link{ml_model} object.
+}
+\description{
+\link{ml_model} generator function for \link[glmnet:cv.glmnet]{glmnet::cv.glmnet}. Defaults
+to \link[glmnet:glmnet]{glmnet::glmnet} for \code{nfolds = 1}.
+}
diff --git a/man/predictor_hal.Rd b/man/predictor_hal.Rd
new file mode 100644
index 00000000..a86d0711
--- /dev/null
+++ b/man/predictor_hal.Rd
@@ -0,0 +1,54 @@
+% Generated by roxygen2: do not edit by hand
+% Please edit documentation in R/predictor.R
+\name{predictor_hal}
+\alias{predictor_hal}
+\title{Instantiate a learner}
+\usage{
+predictor_hal(
+  formula,
+  info = "hal9001::fit_hal",
+  smoothness_orders = 0,
+  reduce_basis = NULL,
+  family = "gaussian",
+  ...
+)
+}
+\arguments{
+\item{formula}{(formula or character) Formula specifying response and design
+matrix.}
+
+\item{info}{(character) Optional information to describe the instantiated
+\link{ml_model} object.}
+
+\item{smoothness_orders}{An \code{integer}, specifying the smoothness of the
+basis functions. See details for \code{smoothness_orders} for more
+information.}
+
+\item{reduce_basis}{Am optional \code{numeric} value bounded in the open
+unit interval indicating the minimum proportion of 1's in a basis function
+column needed for the basis function to be included in the procedure to fit
+the lasso. Any basis functions with a lower proportion of 1's than the
+cutoff will be removed. Defaults to 1 over the square root of the number of
+observations. Only applicable for models fit with zero-order splines, i.e.
+\code{smoothness_orders = 0}.}
+
+\item{family}{A \code{character} or a \code{\link[stats]{family}} object
+(supported by \code{\link[glmnet]{glmnet}}) specifying the error/link
+family for a generalized linear model. \code{character} options are limited
+to "gaussian" for fitting a standard penalized linear model, "binomial" for
+penalized logistic regression, "poisson" for penalized Poisson regression,
+"cox" for a penalized proportional hazards model, and "mgaussian" for
+multivariate penalized linear model. Note that passing in
+family objects leads to slower performance relative to passing in a
+character family (if supported). For example, one should set
+\code{family = "binomial"} instead of \code{family = binomial()} when
+calling \code{fit_hal}.}
+
+\item{...}{Additional arguments to \link[hal9001:fit_hal]{hal9001::fit_hal}.}
+}
+\value{
+\link{ml_model} object.
+}
+\description{
+\link{ml_model} generator function for \link[hal9001:fit_hal]{hal9001::fit_hal}.
+}
diff --git a/man/predictor_sl.Rd b/man/predictor_sl.Rd
index bc550c60..9b6d304e 100644
--- a/man/predictor_sl.Rd
+++ b/man/predictor_sl.Rd
@@ -18,7 +18,8 @@ predictor_sl(
 \arguments{
 \item{model.list}{(list) List of \link{ml_model} objects (i.e. \link{predictor_glm})}
 
-\item{info}{Optional model description to store in model object}
+\item{info}{(character) Optional information to describe the instantiated
+\link{ml_model} object.}
 
 \item{nfolds}{Number of folds to use in cross validation}
 
@@ -33,6 +34,9 @@ predictions (nxp matrix), \code{pred}.}
 
 \item{...}{additional argument to \code{superlearner}}
 }
+\value{
+\link{ml_model} object.
+}
 \description{
 This function creates a predictor object (class \link{ml_model})
 from a list of existing \link{ml_model} objects. When estimating this model a


Reviews:
user: login: benesom
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-09T06:38:28Z
user: login: benesom
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-05-15T07:27:34Z
user: login: kkholst
state: APPROVED
author_association: OWNER
submitted_at: 2025-05-16T07:45:36Z

Review comments:
diff_hunk: @@ -1,5 +1,11 @@
-#' @export
-predictor <- function(...) return(ml_model$new(...))
path: R/predictor.R
user: login: benesom
body: @kkholst what was the reason to export this function? 
created_at: 2025-05-09T06:38:28Z
author_association: COLLABORATOR
diff_hunk: @@ -1,5 +1,11 @@
-#' @export
-predictor <- function(...) return(ml_model$new(...))
path: R/predictor.R
user: login: benesom
body: removed as agreed.
created_at: 2025-05-15T07:27:34Z
author_association: COLLABORATOR

PR comments:
user: login: benesom
created_at: 2025-05-09T06:31:06Z
body: Looks like this on my machine 
<img width="1459" alt="image" src="https://github.com/user-attachments/assets/a6527e18-ef0e-4766-95c0-736a7c21e3d2" />

author_association: COLLABORATOR
user: login: benesom
created_at: 2025-05-09T06:40:06Z
body: I will add or modify
```
if (!requireNamespace("xgboost", quietly = TRUE)) {
      stop("xgboost library required")
    }
```
for all `predictor_` functions in this PR once we agreed that handling the roxygen documentation in the proposed way makes sense.  
author_association: COLLABORATOR
user: login: kkholst
created_at: 2025-05-15T07:32:25Z
body: > Looks like this on my machine <img alt="image" width="1459" src="https://private-user-images.githubusercontent.com/55534750/442005776-a6527e18-ef0e-4766-95c0-736a7c21e3d2.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3NDcyOTQ0OTYsIm5iZiI6MTc0NzI5NDE5NiwicGF0aCI6Ii81NTUzNDc1MC80NDIwMDU3NzYtYTY1MjdlMTgtZWYwZS00NzY2LTk1YzAtNzM2YTdjMjFlM2QyLnBuZz9YLUFtei1BbGdvcml0aG09QVdTNC1ITUFDLVNIQTI1NiZYLUFtei1DcmVkZW50aWFsPUFLSUFWQ09EWUxTQTUzUFFLNFpBJTJGMjAyNTA1MTUlMkZ1cy1lYXN0LTElMkZzMyUyRmF3czRfcmVxdWVzdCZYLUFtei1EYXRlPTIwMjUwNTE1VDA3Mjk1NlomWC1BbXotRXhwaXJlcz0zMDAmWC1BbXotU2lnbmF0dXJlPTEzMGZmZTQ3NmVhZTM0ZDNhNDdmYTFlMWFmN2RiNTQxMGFjZDgxYjZkYmFhYTVkOTVmMDI3NDBiMTE3Y2NlNDUmWC1BbXotU2lnbmVkSGVhZGVycz1ob3N0In0.xTKfDNhZiPA5ZO_uS0J2BlMW56uceeR_pPQO1hFJk-U">

Nice. Regarding the ellipsis arguments then they also cover potential additional arguments to the particular learner (her the hal9001). Perhaps it would be nice to reference the [hal9001] here as well? 
author_association: OWNER