Fixing founded issues with compile_ and fit_ args, and other general improvements

Author: davidrsch

R/create_keras_spec_helpers.R

@@ -12,7 +12,7 @@
 #'   (assumed to be the `model` object), to find tunable hyperparameters.
 #'
 #' For **functional models** (`functional = TRUE`):
-#' - It does **not** create `num_{block_name}` arguments.
+#' - It creates `num_{block_name}` arguments to control block repetition.
 #' - It inspects the arguments of each block function. Arguments whose names
 #'   match other block names are considered graph connections (inputs) and are
 #'   ignored. The remaining arguments are treated as tunable hyperparameters.
@@ -30,21 +30,11 @@
 #' @noRd
 collect_spec_args <- function(
   layer_blocks,
-  functional,
-  global_args = c(
-    "epochs",
-    "batch_size",
-    "learn_rate",
-    "validation_split",
-    "verbose",
-    "compile_loss",
-    "compile_optimizer",
-    "compile_metrics"
-  )
+  functional
 ) {
-  if (any(c("compile", "optimizer") %in% names(layer_blocks))) {
+  if (any(c("compile", "fit", "optimizer") %in% names(layer_blocks))) {
     stop(
-      "`compile` and `optimizer` are protected names and cannot be used as layer block names.",
+      "`compile`, `fit` and `optimizer` are protected names and cannot be used as layer block names.",
       call. = FALSE
     )
   }
@@ -90,8 +80,25 @@ collect_spec_args <- function(
     }
   }
 
-  # global training parameters
-  for (g in global_args) {
+  # Add global training and compile parameters dynamically
+  # These are discovered from keras3::fit and keras3::compile in zzz.R
+  fit_params <- if (length(keras_fit_arg_names) > 0) {
+    paste0("fit_", keras_fit_arg_names)
+  } else {
+    character()
+  }
+  compile_params <- if (length(keras_compile_arg_names) > 0) {
+    paste0("compile_", keras_compile_arg_names)
+  } else {
+    character()
+  }
+
+  # learn_rate is a special convenience argument for the default optimizer
+  special_params <- "learn_rate"
+
+  dynamic_global_args <- c(special_params, fit_params, compile_params)
+
+  for (g in dynamic_global_args) {
     all_args[[g]] <- rlang::zap()
     parsnip_names <- c(parsnip_names, g)
   }

R/generate_roxygen_docs.R

@@ -70,20 +70,22 @@ generate_roxygen_docs <- function(
 
   # Group args for structured documentation
   num_params <- arg_names[startsWith(arg_names, "num_")]
+  fit_params <- arg_names[startsWith(arg_names, "fit_")]
   compile_params <- arg_names[startsWith(arg_names, "compile_")]
-  global_params <- c(
-    "epochs",
-    "batch_size",
-    "learn_rate",
-    "validation_split",
-    "verbose"
-  )
+  # `learn_rate` is a special top-level convenience argument
+  special_params <- "learn_rate"
+
   block_params <- setdiff(
     arg_names,
-    c(num_params, compile_params, global_params)
+    c(num_params, fit_params, compile_params, special_params)
   )
 
   # Document block-specific params
+  if ("learn_rate" %in% block_params) {
+    # This can happen if a user names a block `learn` and it has a `rate` param.
+    # It's an edge case, but we should not document it twice.
+    block_params <- setdiff(block_params, "learn_rate")
+  }
   if (length(block_params) > 0) {
     param_docs <- c(
       param_docs,
@@ -135,40 +137,46 @@ generate_roxygen_docs <- function(
     )
   }
 
-  # Document global params
-  global_param_desc <- list(
-    epochs = "The total number of iterations to train the model.",
-    batch_size = "The number of samples per gradient update.",
-    learn_rate = "The learning rate for the default Adam optimizer. This is ignored if `compile_optimizer` is provided as a pre-built object.",
-    validation_split = "The proportion of the training data to be used as a validation set.",
-    verbose = "The level of verbosity for model fitting (0, 1, or 2)."
-  )
+  # Document special `learn_rate` param
   param_docs <- c(
     param_docs,
-    purrr::map_chr(global_params, function(p) {
-      paste0("@param ", p, " ", global_param_desc[[p]])
-    })
+    "@param learn_rate The learning rate for the default Adam optimizer. This is ignored if `compile_optimizer` is provided as a pre-built Keras optimizer object."
   )
 
   # Document compile params
-  compile_param_desc <- list(
-    compile_loss = "The loss function for compiling the model. Can be a string (e.g., 'mse') or a Keras loss object. Overrides the default.",
-    compile_optimizer = "The optimizer for compiling the model. Can be a string (e.g., 'sgd') or a Keras optimizer object. Overrides the default.",
-    compile_metrics = "A character vector of metrics to monitor during training (e.g., `c('mae', 'mse')`). Overrides the default."
-  )
-  param_docs <- c(
-    param_docs,
-    purrr::map_chr(compile_params, function(p) {
-      paste0("@param ", p, " ", compile_param_desc[[p]])
-    })
-  )
+  if (length(compile_params) > 0) {
+    param_docs <- c(
+      param_docs,
+      purrr::map_chr(compile_params, function(p) {
+        paste0(
+          "@param ",
+          p,
+          " Argument to `keras3::compile()`. See the 'Model Compilation' section."
+        )
+      })
+    )
+  }
+
+  # Document fit params
+  if (length(fit_params) > 0) {
+    param_docs <- c(
+      param_docs,
+      purrr::map_chr(fit_params, function(p) {
+        paste0(
+          "@param ",
+          p,
+          " Argument to `keras3::fit()`. See the 'Model Fitting' section."
+        )
+      })
+    )
+  }
 
   # Add ... param
   param_docs <- c(
     param_docs,
     paste0(
-      "@param ... Additional arguments passed to the Keras engine. This is commonly used for arguments to `keras3::fit()` (prefixed with `fit_`). ",
-      "See the 'Model Fitting' and 'Model Compilation' sections for details."
+      "@param ... Additional arguments passed to the Keras engine. Use this for arguments to `keras3::fit()` or `keras3::compile()` ",
+      "that are not exposed as top-level arguments."
     )
   )
 
@@ -178,7 +186,8 @@ generate_roxygen_docs <- function(
       "#' @section Model Architecture (Functional API):",
       "#' The Keras model is constructed using the Functional API. Each layer block function's arguments",
       "#' determine its inputs. For example, a block `function(input_a, input_b, ...)` will be connected",
-      "#' to the outputs of the `input_a` and `input_b` blocks.",
+      "#' to the outputs of the `input_a` and `input_b` blocks. You can also repeat a block by setting",
+      "#' the `num_{block_name}` argument, provided the block has a single input tensor.",
       "#' The first block in `layer_blocks` is assumed to be the input layer and should not have inputs from other layers."
     )
     see_also_fit <- "generic_functional_fit()"
@@ -213,7 +222,7 @@ generate_roxygen_docs <- function(
     "#' @section Model Fitting:",
     "#' The model is fit using `keras3::fit()`. You can pass any argument to this function by prefixing it with `fit_`.",
     "#' For example, to add Keras callbacks, you can pass `fit_callbacks = list(callback_early_stopping())`.",
-    "#' The `epochs` and `batch_size` arguments are also passed to `fit()`."
+    "#' Common arguments include `fit_epochs`, `fit_batch_size`, and `fit_validation_split`."
   )
 
   # Other tags

R/generic_fit_helpers.R

@@ -5,12 +5,15 @@
 #' list of arguments, resolves them, and combines them with defaults.
 #'
 #' @details
-#' It handles the special logic for the `optimizer`, where a string name is
-#' resolved to a Keras optimizer object, applying the `learn_rate` if necessary.
-#' It also resolves string names for `loss` and `metrics` using `get_keras_object()`.
+#' This function orchestrates the compilation setup. It gives precedence to
+#' user-provided arguments (e.g., `compile_optimizer`) over the mode-based
+#' defaults. It handles the special logic for the `optimizer`, where a string
+#' name (e.g., `"sgd"`) is resolved to a Keras optimizer object, applying the
+#' top-level `learn_rate` if necessary. It also resolves string names for `loss`
+#' and `metrics` using `get_keras_object()`.
 #'
 #' @param all_args The list of all arguments passed to the fitting function's `...`.
-#' @param learn_rate The main `learn_rate` parameter.
+#' @param learn_rate The top-level `learn_rate` parameter.
 #' @param default_loss The default loss function to use if not provided.
 #' @param default_metrics The default metric(s) to use if not provided.
 #' @return A named list of arguments ready to be passed to `keras3::compile()`.
@@ -69,6 +72,14 @@ collect_compile_args <- function(
     !names(user_compile_args) %in% c("optimizer", "loss", "metrics")
   ]
   final_compile_args <- c(final_compile_args, other_args)
+  # Filter out arguments that are NULL or rlang_zap before passing to keras3::compile
+  final_compile_args <- final_compile_args[
+    !vapply(
+      final_compile_args,
+      function(x) inherits(x, "rlang_zap"),
+      logical(1)
+    )
+  ]
   final_compile_args
 }
 
@@ -78,21 +89,22 @@ collect_compile_args <- function(
 #' This internal helper extracts all arguments prefixed with `fit_` from a list
 #' of arguments and combines them with the core arguments for `keras3::fit()`.
 #'
+#' @details
+#' It constructs the final list of arguments for `keras3::fit()`. It starts with
+#' the required data (`x`, `y`) and the `verbose` setting. It then merges any
+#' user-provided arguments from the model specification (e.g., `fit_epochs`,
+#' `fit_callbacks`), with the user-provided arguments taking precedence over
+#' any defaults.
+#'
 #' @param x_proc The processed predictor data.
 #' @param y_mat The processed outcome data.
-#' @param epochs The number of epochs.
-#' @param batch_size The batch size.
-#' @param validation_split The validation split proportion.
 #' @param verbose The verbosity level.
 #' @param all_args The list of all arguments passed to the fitting function's `...`.
 #' @return A named list of arguments ready to be passed to `keras3::fit()`.
 #' @noRd
 collect_fit_args <- function(
   x_proc,
   y_mat,
-  epochs,
-  batch_size,
-  validation_split,
   verbose,
   all_args
 ) {
@@ -101,15 +113,24 @@ collect_fit_args <- function(
   user_fit_args <- all_args[fit_arg_names]
   names(user_fit_args) <- sub("^fit_", "", names(user_fit_args))
 
-  final_fit_args <- c(
-    list(
-      x = x_proc,
-      y = y_mat,
-      epochs = epochs,
-      batch_size = batch_size,
-      validation_split = validation_split,
-      verbose = verbose
-    ),
-    user_fit_args
+  # Build the core argument set. `verbose` can be overridden by `fit_verbose`.
+  base_args <- list(
+    x = x_proc,
+    y = y_mat,
+    verbose = verbose
   )
+
+  merged_args <- utils::modifyList(base_args, user_fit_args)
+
+  # Filter out arguments that are NULL or rlang_zap before passing to keras3::fit
+  merged_args <- merged_args[
+    !vapply(
+      merged_args,
+      function(x) {
+        inherits(x, "rlang_zap")
+      },
+      logical(1)
+    )
+  ]
+  merged_args
 }

R/generic_sequential_fit.R

@@ -71,28 +71,13 @@ generic_sequential_fit <- function(
   x,
   y,
   layer_blocks,
-  epochs = 10,
-  batch_size = 32,
-  learn_rate = 0.01,
-  validation_split = 0.2,
-  verbose = 0,
   ...
 ) {
-  # --- 0. Resolve arguments ---
-  # Parsnip passes "zapped" arguments for user-unspecified args.
-  # This helper replaces them with the function's defaults.
-  resolve_default <- function(x, default) {
-    if (inherits(x, "rlang_zap")) default else x
-  }
-  fmls <- rlang::fn_fmls(sys.function())
-  epochs <- resolve_default(epochs, fmls$epochs)
-  batch_size <- resolve_default(batch_size, fmls$batch_size)
-  learn_rate <- resolve_default(learn_rate, fmls$learn_rate)
-  validation_split <- resolve_default(validation_split, fmls$validation_split)
-  verbose <- resolve_default(verbose, fmls$verbose)
-
-  # --- 1. Data & Input Shape Preparation ---
+  # --- 0. Argument & Data Preparation ---
   all_args <- list(...)
+  learn_rate <- all_args$learn_rate %||% 0.01
+  verbose <- all_args$verbose %||% 0
+
   # Handle both standard tabular data (matrix) and list-columns of arrays
   # (for images/sequences) that come from recipes.
   if (is.data.frame(x) && ncol(x) == 1 && is.list(x[[1]])) {
@@ -188,9 +173,6 @@ generic_sequential_fit <- function(
   fit_args <- collect_fit_args(
     x_proc,
     y_mat,
-    epochs,
-    batch_size,
-    validation_split,
     verbose,
     all_args
   )

R/globals.R

@@ -1,3 +1,11 @@
 utils::globalVariables(
-  c("object", "new_data", "engine", "fresh", "parameters")
+  c(
+    "object",
+    "new_data",
+    "engine",
+    "fresh",
+    "parameters",
+    "keras_fit_arg_names",
+    "keras_compile_arg_names"
+  )
 )

R/register_model_args.R

@@ -17,8 +17,10 @@
 #'   \item Other arguments are mapped based on their suffix (e.g., `dense_units`
 #'     is mapped based on `units`). The internal `keras_dials_map` object
 #'     contains common mappings like `units` -> `dials::hidden_units()`.
-#'   \item Arguments for `compile_loss` and `compile_optimizer` are mapped to
-#'     custom `dials` parameter functions within `kerasnip`.
+#'   \item Arguments for `compile_loss` and `compile_optimizer` are mapped to custom
+#'     `dials` parameter functions (`loss_function_keras()` and `optimizer_function()`)
+#'     that are part of the `kerasnip` package itself. The function correctly
+#'     sets the `pkg` for these to `kerasnip`.
 #' }
 #'
 #' @param model_name The name of the new model specification.
@@ -43,9 +45,9 @@ register_model_args <- function(model_name, parsnip_names) {
     "dropout",
     "learn_rate",
     "learn_rate",
+    "fit_epochs",
     "epochs",
-    "epochs",
-    "batch_size",
+    "fit_batch_size",
     "batch_size",
     "compile_loss", # parsnip arg
     "loss_function_keras", # dials function from kerasnip
@@ -54,7 +56,7 @@ register_model_args <- function(model_name, parsnip_names) {
   )
 
   # We now allow optimizer to be tuned. Metrics are for tracking, not training.
-  non_tunable <- c("verbose")
+  non_tunable <- c("fit_verbose")
 
   for (arg in parsnip_names) {
     if (arg %in% non_tunable) {