docs: correct usage of default / initial value

R/learner_LiblineaR_regr_liblinear.R

@@ -15,10 +15,10 @@
 #' * `type = 12` – L2-regularized L2-loss support vector regression (dual)
 #' * `type = 13` – L2-regularized L1-loss support vector regression (dual)
 #'
-#' @section Custom mlr3 defaults:
+#' @section Initial parameter values:
 #' - `svr_eps`:
 #'   - Actual default: `NULL`
-#'   - Adjusted default: 0.001
+#'   - Initial value: 0.001
 #'   - Reason for change: `svr_eps` is type dependent and the "type" is handled
 #'   by the mlr3learner. The default value is set to th default of the respective
 #'   "type".

R/learner_dbarts_regr_bart.R

@@ -9,19 +9,16 @@
 #' @template learner
 #' @templateVar id regr.bart
 #'
-#' @section Initial parameter values:
+#' @section Custom mlr3 parameters:
 #' * Parameter: offset
 #'   * The parameter is removed, because only `dbarts::bart2` allows an offset during training,
 #'     and therefore the offset parameter in `dbarts:::predict.bart` is irrelevant for
 #'     `dbarts::dbart`.
 #' * Parameter: nchain, combineChains, combinechains
 #'   * The parameters are removed as parallelization of multiple models is handled by future.
 #'
-#' @section Custom mlr3 defaults:
-#' * Parameter: keeptrees
-#'   * Original: FALSE
-#'   * New: TRUE
-#'   * Reason: Required for prediction
+#' @section Initial parameter values:
+#' * `keeptrees` is initialized to `TRUE` because it is required for prediction.
 #'
 #' @references
 #' `r format_bib("sparapani2021nonparametric", "chipman2010bart")`

R/learner_flexsurv_surv_flexible.R

@@ -21,10 +21,10 @@
 #' and covariates \eqn{X^T = (X_0,...,X_P)^T}{X^T = (X0,...,XP)^T}, where \eqn{X_0}{X0} is a column
 #' of \eqn{1}s: \eqn{lp = \beta X}{lp = \betaX}.
 #'
-#' @section Custom mlr3 defaults:
+#' @section Initial parameter values:
 #' - `k`:
 #'   - Actual default: `0`
-#'   - Adjusted default: `1`
+#'   - Initial value: `1`
 #'   - Reason for change: The default value of `0` is equivalent to, and a much less efficient
 #'   implementation of, [LearnerSurvParametric].
 #'

R/learner_gbm_classif_gbm.R

@@ -9,16 +9,9 @@
 #' @template learner
 #' @templateVar id classif.gbm
 #'
-#' @section Custom mlr3 defaults:
-#' - `keep.data`:
-#'   - Actual default: TRUE
-#'   - Adjusted default: FALSE
-#'   - Reason for change: `keep.data = FALSE` saves memory during model fitting.
-#' - `n.cores`:
-#'   - Actual default: NULL
-#'   - Adjusted default: 1
-#'   - Reason for change: Suppressing the automatic internal parallelization if
-#'     `cv.folds` > 0.
+#' @section Initial parameter values:
+#' - `keep.data` is initialized to `FALSE` to save memory.
+#' - `n.cores` is initialized to 1 to avoid conflicts with parallelization through future.
 #'
 #' @references
 #' `r format_bib("friedman2002stochastic")`

R/learner_glmnet_surv_cv_glmnet.R

@@ -6,8 +6,8 @@
 #' Generalized linear models with elastic net regularization.
 #' Calls [glmnet::cv.glmnet()] from package \CRANpkg{glmnet}.
 #'
-#' @section Custom mlr3 defaults:
-#' - `family` The default is set to `"cox"`.
+#' @section Custom mlr3 parameters:
+#' - `family` is set to `"cox"` and cannot be changed.
 #'
 #' @templateVar id surv.cv_glmnet
 #' @template learner

R/learner_glmnet_surv_glmnet.R

@@ -6,8 +6,8 @@
 #' Generalized linear models with elastic net regularization.
 #' Calls [glmnet::glmnet()] from package \CRANpkg{glmnet}.
 #'
-#' @section Custom mlr3 defaults:
-#' - `family` The default is set to `"cox"`.
+# @section Custom mlr3 parameters:
+#' - `family` is set to `"cox"` and cannot be changed.
 #'
 #' @details
 #' Caution: This learner is different to learners calling [glmnet::cv.glmnet()]

R/learner_lightgbm_classif_lightgbm.R

@@ -14,27 +14,27 @@
 #' @templateVar id classif.lightgbm
 #'
 #' @section Initial parameter values:
-#' * `convert_categorical`:
-#'   Additional parameter. If this parameter is set to `TRUE` (default), all factor and logical
-#'   columns are converted to integers and the parameter categorical_feature of lightgbm is set to
-#'   those columns.
-#' * `num_class`:
-#'  This parameter is automatically inferred for multiclass tasks and does not have to be set.
-#' @section Custom mlr3 defaults:
 #' * `num_threads`:
 #'   * Actual default: 0L
-#'   * Adjusted default: 1L
+#'   * Initial value: 1L
 #'   * Reason for change: Prevents accidental conflicts with `future`.
 #' * `verbose`:
 #'   * Actual default: 1L
-#'   * Adjusted default: -1L
+#'   * Initial value: -1L
 #'   * Reason for change: Prevents accidental conflicts with mlr messaging system.
+#' @section Custom mlr3 defaults:
 #' * `objective`:
-#'   Depending if the task is binary / multiclass, the default is set to `"binary"` or
+#'   Depending if the task is binary / multiclass, the default is `"binary"` or
 #'   `"multiclasss"`.
 #' @section Custom mlr3 parameters:
 #' * `early_stopping`
 #'   Whether to use the test set for early stopping. Default is `FALSE`.
+#' * `convert_categorical`:
+#'   Additional parameter. If this parameter is set to `TRUE` (default), all factor and logical
+#'   columns are converted to integers and the parameter categorical_feature of lightgbm is set to
+#'   those columns.
+#' * `num_class`:
+#'  This parameter is automatically inferred for multiclass tasks and does not have to be set.
 #'
 #' @references
 #' `r format_bib("ke2017lightgbm")`

R/learner_lightgbm_regr_lightgbm.R

@@ -14,23 +14,22 @@
 #' @templateVar id regr.lightgbm
 #'
 #' @section Initial parameter values:
-#' * `convert_categorical`:
-#'   Additional parameter. If this parameter is set to `TRUE` (default), all factor and logical
-#'   columns are converted to integers and the parameter categorical_feature of lightgbm is set to
-#'   those columns.
-#' @section Custom mlr3 defaults:
 #' * `num_threads`:
 #'   * Actual default: 0L
-#'   * Adjusted default: 1L
+#'   * Iniital value: 1L
 #'   * Reason for change: Prevents accidental conflicts with `future`.
 #' * `verbose`:
 #'   * Actual default: 1L
-#'   * Adjusted default: -1L
+#'   * Initial value: -1L
 #'   * Reason for change: Prevents accidental conflicts with mlr messaging system.
 #'
 #' @section Custom mlr3 parameters:
 #' * `early_stopping`
 #'   Whether to use the test set for early stopping. Default is `FALSE`.
+#' * `convert_categorical`:
+#'   Additional parameter. If this parameter is set to `TRUE` (default), all factor and logical
+#'   columns are converted to integers and the parameter categorical_feature of lightgbm is set to
+#'   those columns.
 #'
 #' @references
 #' `r format_bib("ke2017lightgbm")`

R/learner_obliqueRSF_surv_obliqueRSF.R

@@ -10,17 +10,14 @@
 #' @template learner
 #' @templateVar id surv.obliqueRSF
 #'
-#' @section Initial parameter values:
+#' @section Custom mlr3 parameters:
 #' - `mtry`:
 #'   - This hyperparameter can alternatively be set via the added hyperparameter `mtry_ratio`
 #'     as `mtry = max(ceiling(mtry_ratio * n_features), 1)`.
 #'     Note that `mtry` and `mtry_ratio` are mutually exclusive.
 #'
-#' @section Custom mlr3 defaults:
-#' - `verbose`:
-#'   - Actual default: `TRUE`
-#'   - Adjusted default: `FALSE`
-#'   - Reason for change: mlr3 already has it's own verbose set to `TRUE` by default
+#' @section Initial parameter values:
+#' - `verbose` is initialized to `FALSE`
 #'
 #' @references
 #' `r format_bib("jaeger_2019")`

R/learner_randomForestSRC_classif_imbalanced_rfsrc.R

@@ -16,11 +16,8 @@
 #'     as `sampsize = max(ceiling(sampsize.ratio * n_obs), 1)`.
 #'     Note that `sampsize` and `sampsize.ratio` are mutually exclusive.
 #'
-#' @section Custom mlr3 defaults:
-#' - `cores`:
-#'   - Actual default: Auto-detecting the number of cores
-#'   - Adjusted default: 1
-#'   - Reason for change: Threading conflicts with explicit parallelization via \CRANpkg{future}.
+#' @section Initial parameter values:
+#' - `cores` is initialized to 1 to avoid threading conflicts with explicit parallelization via \CRANpkg{future}.
 #'
 #' @templateVar id classif.imbalanced_rfsrc
 #' @template learner
@@ -109,6 +106,7 @@ LearnerClassifImbalancedRandomForestSRC = R6Class("LearnerClassifImbalancedRando
           save.memory = p_lgl(default = FALSE, tags = "train"),
         perf.type = p_fct(levels = c("gmean", "misclass", "brier", "none"), tags = "train") # nolint
       )
+      ps$values = list(cores = 1L)
 
       super$initialize(
         id = "classif.imbalanced_rfsrc",
@@ -154,7 +152,6 @@ LearnerClassifImbalancedRandomForestSRC = R6Class("LearnerClassifImbalancedRando
       pv = self$param_set$get_values(tags = "train")
       pv = convert_ratio(pv, "mtry", "mtry.ratio", length(task$feature_names))
       pv = convert_ratio(pv, "sampsize", "sampsize.ratio", task$nrow)
-      cores = pv$cores %??% 1L
 
       if ("weights" %in% task$properties) {
         pv$case.wt = as.numeric(task$weights$weight) # nolint

R/learner_randomForestSRC_classif_rfsrc.R

@@ -9,7 +9,7 @@
 #' @template learner
 #' @templateVar id classif.rfsrc
 #'
-#' @section Initial parameter values:
+#' @section Custom mlr3 parameters:
 #' - `mtry`:
 #'   - This hyperparameter can alternatively be set via the added hyperparameter `mtry.ratio`
 #'     as `mtry = max(ceiling(mtry.ratio * n_features), 1)`.
@@ -18,12 +18,8 @@
 #'   - This hyperparameter can alternatively be set via the added hyperparameter `sampsize.ratio`
 #'     as `sampsize = max(ceiling(sampsize.ratio * n_obs), 1)`.
 #'     Note that `sampsize` and `sampsize.ratio` are mutually exclusive.
-#'
-#' @section Custom mlr3 defaults:
-#' - `cores`:
-#'   - Actual default: Auto-detecting the number of cores
-#'   - Adjusted default: 1
-#'   - Reason for change: Threading conflicts with explicit parallelization via \CRANpkg{future}.
+#' @section Initial parameter values:
+#' - `cores` is initialized to 1 to avoid threading conflicts with explicit parallelization via \CRANpkg{future}.
 #'
 #' @references
 #' `r format_bib("breiman_2001")`
@@ -103,6 +99,8 @@ LearnerClassifRandomForestSRC = R6Class("LearnerClassifRandomForestSRC",
         perf.type = p_fct(levels = c("gmean", "misclass", "brier", "none"), tags = "train") # nolint
       )
 
+      ps$values = list(cores = 1)
+
       super$initialize(
         id = "classif.rfsrc",
         packages = c("mlr3extralearners", "randomForestSRC"),
@@ -156,7 +154,6 @@ LearnerClassifRandomForestSRC = R6Class("LearnerClassifRandomForestSRC",
       pv = self$param_set$get_values(tags = "train")
       pv = convert_ratio(pv, "mtry", "mtry.ratio", length(task$feature_names))
       pv = convert_ratio(pv, "sampsize", "sampsize.ratio", task$nrow)
-      cores = pv$cores %??% 1L
 
       if ("weights" %in% task$properties) {
         pv$case.wt = as.numeric(task$weights$weight) # nolint

R/learner_randomForestSRC_regr_rfsrc.R

@@ -89,6 +89,8 @@ LearnerRegrRandomForestSRC = R6Class("LearnerRegrRandomForestSRC",
         perf.type = p_fct(levels = "none", tags = "train")
       )
 
+      ps$values = list(cores = 1)
+
       super$initialize(
         id = "regr.rfsrc",
         packages = c("mlr3extralearners", "randomForestSRC"),
@@ -139,7 +141,6 @@ LearnerRegrRandomForestSRC = R6Class("LearnerRegrRandomForestSRC",
       pv = self$param_set$get_values(tags = "train")
       pv = convert_ratio(pv, "mtry", "mtry.ratio", length(task$feature_names))
       pv = convert_ratio(pv, "sampsize", "sampsize.ratio", task$nrow)
-      cores = pv$cores %??% 1L
 
       if ("weights" %in% task$properties) {
         pv$case.wt = as.numeric(task$weights$weight) # nolint

R/learner_randomForestSRC_surv_rfsrc.R

@@ -100,6 +100,8 @@ delayedAssign(
           perf.type = p_fct(levels = "none", tags = "train")
         )
 
+        ps$values = list(cores = 1)
+
         super$initialize(
           id = "surv.rfsrc",
           packages = c("mlr3extralearners", "randomForestSRC", "pracma"),
@@ -149,7 +151,6 @@ delayedAssign(
         pv = self$param_set$get_values(tags = "train")
         pv = convert_ratio(pv, "mtry", "mtry.ratio", length(task$feature_names))
         pv = convert_ratio(pv, "sampsize", "sampsize.ratio", task$nrow)
-        cores = pv$cores %??% 1L
 
         if ("weights" %in% task$properties) {
           pv$case.wt = as.numeric(task$weights$weight) # nolint

R/learner_ranger_surv_ranger.R

@@ -12,11 +12,8 @@
 #'     as `mtry = max(ceiling(mtry.ratio * n_features), 1)`.
 #'     Note that `mtry` and `mtry.ratio` are mutually exclusive.
 #'
-#' @section Custom mlr3 defaults:
-#' - `num.threads`:
-#'   - Actual default: `NULL`, triggering auto-detection of the number of CPUs.
-#'   - Adjusted value: 1.
-#'   - Reason for change: Conflicting with parallelization via \CRANpkg{future}.
+#' @section Initial parameter values:
+#' - `num.threads` is initialized to 1 to avoid conflicts with parallelization via \CRANpkg{future}.
 #'
 #' @templateVar id surv.ranger
 #' @template learner

R/learner_survivalmodels_surv_dnnsurv.R

@@ -17,11 +17,8 @@
 #'  The number of output channels should be of length `1` and number of input channels is
 #'  the number of features plus number of cuts.
 #'
-#' @section Custom mlr3 defaults:
-#' - `verbose`:
-#'   - Actual default: `1L`
-#'   - Adjusted default: `0L`
-#'   - Reason for change: Prevents plotting.
+#' @section Initial parameter values:
+#' - `verbose` is initialized to 0.
 #'
 #' @references
 #' `r format_bib("zhao2019dnnsurv")`

R/learner_xgboost_surv_xgboost.R

@@ -8,25 +8,11 @@
 #'
 #' @template note_xgboost
 #'
-#' @section Custom mlr3 defaults:
-#' - `nrounds`:
-#'   - Actual default: no default.
-#'   - Adjusted default: 1.
-#'   - Reason for change: Without a default construction of the learner
-#'     would error. Just setting a nonsense default to workaround this.
-#'     `nrounds` needs to be tuned by the user.
-#' - `nthread`:
-#'   - Actual value: Undefined, triggering auto-detection of the number of CPUs.
-#'   - Adjusted value: 1.
-#'   - Reason for change: Conflicting with parallelization via \CRANpkg{future}.
-#' - `verbose`:
-#'   - Actual default: 1.
-#'   - Adjusted default: 0.
-#'   - Reason for change: Reduce verbosity.
-#' - `objective`:
-#'   - Actual default: `reg:squarederror`.
-#'   - Adjusted default: `survival:cox`.
-#'   - Reason for change: Changed to a survival objective.
+#' @section Initial parameter values:
+#' - `nrounds` is initialized to 1.
+#' - `nthread` is initialized to 1 to avoid conflicts with parallelization via \CRANpkg{future}.
+#' - `verbose` is initialized to 0.
+#' - `objective` is initialized to `survival:cox` for survival analysis.
 #' @section Early stopping:
 #' Early stopping can be used to find the optimal number of boosting rounds.
 #' The `early_stopping_set` parameter controls which set is used to monitor the performance.

inst/templates/learner_template.R

@@ -9,11 +9,11 @@
 #' @section Initial parameter values:
 #' FIXME: DEVIATIONS FROM UPSTREAM PARAMETERS. DELETE IF NOT APPLICABLE.
 #'
-#' @section Custom mlr3 defaults:
+#' @section Custom mlr3 parameters:
 #' FIXME: DEVIATIONS FROM UPSTREAM DEFAULTS. DELETE IF NOT APPLICABLE.
 #'
-#' @section Installation:
-#' FIXME: CUSTOM INSTALLATION INSTRUCTIONS. DELETE IF NOT APPLICABLE.
+#' @section Custom mlr3 parameters:
+#' FIXME: INITIAL VALUES FOR PARAMETERS. DELETE IF NOT APPLICABLE.
 #'
 #' @templateVar id <type>.<key>
 #' @template learner