From fcfd92229651bc904b1c62cef023045a7faf6a99 Mon Sep 17 00:00:00 2001 From: Kevin Dalton Date: Fri, 19 Sep 2025 11:02:58 -0600 Subject: [PATCH 1/3] improve documentation of parameters Fix #313 --- DESCRIPTION | 2 +- R/parameters.R | 22 ++++++++++++++++++---- man/dials-package.Rd | 2 +- man/finalize.Rd | 2 +- man/parameters.Rd | 18 ++++++++++++++++-- 5 files changed, 37 insertions(+), 9 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index a4364a6f..9c2fa2b6 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -50,4 +50,4 @@ Config/usethis/last-upkeep: 2025-04-23 Encoding: UTF-8 LazyData: true Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.2 +RoxygenNote: 7.3.3 diff --git a/R/parameters.R b/R/parameters.R index 50e11e20..5718a1f5 100644 --- a/R/parameters.R +++ b/R/parameters.R @@ -1,9 +1,22 @@ -#' Information on tuning parameters within an object +#' Return a parameter set from one or more dials `param` objects. #' #' @param x An object, such as a list of `param` objects or an actual `param` -#' object. +#' object. #' @param ... Only used for the `param` method so that multiple `param` objects -#' can be passed to the function. +#' can be passed to the function. +#' +#' @return +#' A tibble of class `parameters` where each row represents one tunable +#' parameter. +#' +#' @seealso [dials::update.parameters()], [dials::finalize()], +#' [hardhat::extract_parameter_set_dials()] +#' +#' @examples +#' params <- list(lambda = penalty(), alpha = mixture(), `rand forest` = mtry()) +#' pset <- parameters(params) +#' pset +#' #' @export parameters <- function(x, ...) { UseMethod("parameters") @@ -177,12 +190,13 @@ print.parameters <- function(x, ...) { print_x$object <- purrr::map_chr( print_x$object, - \(.x) + \(.x) { if (all(is.na(.x))) { "missing" } else { pillar::type_sum(.x) } + } ) cli::cli_par() diff --git a/man/dials-package.Rd b/man/dials-package.Rd index e55736d9..64667afe 100644 --- a/man/dials-package.Rd +++ b/man/dials-package.Rd @@ -53,7 +53,7 @@ Authors: Other contributors: \itemize{ - \item Posit Software, PBC (03wc8by49) [copyright holder, funder] + \item Posit Software, PBC (\href{https://ror.org/03wc8by49}{ROR}) [copyright holder, funder] } } diff --git a/man/finalize.Rd b/man/finalize.Rd index 3958c318..becf9a29 100644 --- a/man/finalize.Rd +++ b/man/finalize.Rd @@ -87,7 +87,7 @@ rows in the data or a fraction of the total number of rows. \code{\link[kernlab:sigest]{kernlab::sigest()}}. It requires that all columns in \code{x} be numeric. } \examples{ -\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} +\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf} library(dplyr) car_pred <- select(mtcars, -mpg) diff --git a/man/parameters.Rd b/man/parameters.Rd index 289307ea..f13e9778 100644 --- a/man/parameters.Rd +++ b/man/parameters.Rd @@ -5,7 +5,7 @@ \alias{parameters.default} \alias{parameters.param} \alias{parameters.list} -\title{Information on tuning parameters within an object} +\title{Return a parameter set from one or more dials \code{param} objects.} \usage{ parameters(x, ...) @@ -22,6 +22,20 @@ object.} \item{...}{Only used for the \code{param} method so that multiple \code{param} objects can be passed to the function.} } +\value{ +A tibble of class \code{parameters} where each row represents one tunable +parameter. +} \description{ -Information on tuning parameters within an object +Return a parameter set from one or more dials \code{param} objects. +} +\examples{ +params <- list(lambda = penalty(), alpha = mixture(), `rand forest` = mtry()) +pset <- parameters(params) +pset + +} +\seealso{ +\code{\link[=update.parameters]{update.parameters()}}, \code{\link[=finalize]{finalize()}}, +\code{\link[hardhat:hardhat-extract]{hardhat::extract_parameter_set_dials()}} } From 9462c6f73c05b1b396d1921bbcb0f9a5f80c591e Mon Sep 17 00:00:00 2001 From: Hannah Frick Date: Mon, 22 Sep 2025 11:21:45 +0100 Subject: [PATCH 2/3] update roxygen2 version separately --- DESCRIPTION | 2 +- man/dials-package.Rd | 2 +- man/finalize.Rd | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 9c2fa2b6..a4364a6f 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -50,4 +50,4 @@ Config/usethis/last-upkeep: 2025-04-23 Encoding: UTF-8 LazyData: true Roxygen: list(markdown = TRUE) -RoxygenNote: 7.3.3 +RoxygenNote: 7.3.2 diff --git a/man/dials-package.Rd b/man/dials-package.Rd index 64667afe..e55736d9 100644 --- a/man/dials-package.Rd +++ b/man/dials-package.Rd @@ -53,7 +53,7 @@ Authors: Other contributors: \itemize{ - \item Posit Software, PBC (\href{https://ror.org/03wc8by49}{ROR}) [copyright holder, funder] + \item Posit Software, PBC (03wc8by49) [copyright holder, funder] } } diff --git a/man/finalize.Rd b/man/finalize.Rd index becf9a29..3958c318 100644 --- a/man/finalize.Rd +++ b/man/finalize.Rd @@ -87,7 +87,7 @@ rows in the data or a fraction of the total number of rows. \code{\link[kernlab:sigest]{kernlab::sigest()}}. It requires that all columns in \code{x} be numeric. } \examples{ -\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) withAutoprint(\{ # examplesIf} +\dontshow{if (interactive() || identical(Sys.getenv("IN_PKGDOWN"), "true")) (if (getRversion() >= "3.4") withAutoprint else force)(\{ # examplesIf} library(dplyr) car_pred <- select(mtcars, -mpg) From 40e9590cb61de3cf536e4301d58e4e2178484a81 Mon Sep 17 00:00:00 2001 From: Hannah Frick Date: Mon, 22 Sep 2025 11:22:13 +0100 Subject: [PATCH 3/3] put emphasis on parameter set --- R/parameters.R | 6 +++--- man/parameters.Rd | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/R/parameters.R b/R/parameters.R index 5718a1f5..55ab7da9 100644 --- a/R/parameters.R +++ b/R/parameters.R @@ -1,4 +1,4 @@ -#' Return a parameter set from one or more dials `param` objects. +#' Create a parameter set #' #' @param x An object, such as a list of `param` objects or an actual `param` #' object. @@ -6,8 +6,8 @@ #' can be passed to the function. #' #' @return -#' A tibble of class `parameters` where each row represents one tunable -#' parameter. +#' A parameter set of class `parameters` in the form of a data frame where each +#' row represents one tunable parameter. #' #' @seealso [dials::update.parameters()], [dials::finalize()], #' [hardhat::extract_parameter_set_dials()] diff --git a/man/parameters.Rd b/man/parameters.Rd index f13e9778..81a80028 100644 --- a/man/parameters.Rd +++ b/man/parameters.Rd @@ -5,7 +5,7 @@ \alias{parameters.default} \alias{parameters.param} \alias{parameters.list} -\title{Return a parameter set from one or more dials \code{param} objects.} +\title{Create a parameter set} \usage{ parameters(x, ...) @@ -23,11 +23,11 @@ object.} can be passed to the function.} } \value{ -A tibble of class \code{parameters} where each row represents one tunable -parameter. +A parameter set of class \code{parameters} in the form of a data frame where each +row represents one tunable parameter. } \description{ -Return a parameter set from one or more dials \code{param} objects. +Create a parameter set } \examples{ params <- list(lambda = penalty(), alpha = mixture(), `rand forest` = mtry())