diff --git a/NEWS.md b/NEWS.md index f723e537..7f8c5916 100644 --- a/NEWS.md +++ b/NEWS.md @@ -2,9 +2,11 @@ ## Improvements -* The space-filling design functionality was expanded to include several new types of designs: Audze-Eglais, max/min L1, max/min L2, and uniform. These are all pre-computed designs accessed from the sfd package. +* The space-filling design functionality was expanded to include several new types of designs: Audze-Eglais, max/min L1, max/min L2, and uniform. These are all pre-computed designs accessed from the sfd package (#329). -* A new function is used to access all of the space-filling designs called `grid_space_filling()`. +* A new function is used to access all of the space-filling designs called `grid_space_filling()` (#329). + +* `grid_max_entropy()` and `grid_latin_hypercube()` are deprecated in favor of `grid_space_filling()` (#332). # dials 1.2.1 diff --git a/R/dials-package.R b/R/dials-package.R index 01386646..f9815606 100644 --- a/R/dials-package.R +++ b/R/dials-package.R @@ -24,7 +24,7 @@ #' random_set #' #' # A small space-filling design based on experimental design methods: -#' design_set <- grid_max_entropy(penalty(), mixture(), deg_free(), size = 5) +#' design_set <- grid_space_filling(penalty(), mixture(), deg_free(), size = 5) #' design_set #' @keywords internal "_PACKAGE" diff --git a/R/space_filling.R b/R/space_filling.R index e3513586..57b5bc0d 100644 --- a/R/space_filling.R +++ b/R/space_filling.R @@ -48,9 +48,6 @@ #' size = 10, #' original = FALSE #' ) -#' -#' grid_latin_hypercube(penalty(), mixture(), original = TRUE) -#' #' # ------------------------------------------------------------------------------ #' # comparing methods #' @@ -205,8 +202,8 @@ make_sfd <- function(..., names(grid) <- names(params) } else { grid <- - grid_max_entropy( - params, + make_max_entropy_grid( + !!!params, size = size, original = original, variogram_range = variogram_range, @@ -215,15 +212,15 @@ make_sfd <- function(..., } } else if (type == "latin_hypercube") { grid <- - grid_latin_hypercube( - params, + make_latin_hypercube_grid( + !!!params, size = size, original = original ) } else { grid <- - grid_max_entropy( - params, + make_max_entropy_grid( + !!!params, size = size, original = original, variogram_range = variogram_range, @@ -241,7 +238,28 @@ base_recycle <- function(x, size) { # ------------------------------------------------------------------------------ -#' @rdname grid_space_filling +#' Max-entropy and latin hypercube grids +#' +#' @description +#' `r lifecycle::badge("deprecated")` +#' +#' These functions are deprecated because they have been replaced by +#' [grid_space_filling()]. +#' +#' @inheritParams grid_random +#' @param size A single integer for the maximum number of parameter value +#' combinations returned. If duplicate combinations are +#' generated from this size, the smaller, unique set is returned. +#' @param variogram_range A numeric value greater than zero. Larger values +#' reduce the likelihood of empty regions in the parameter space. Only used +#' for `type = "max_entropy"`. +#' @param iter An integer for the maximum number of iterations used to find +#' a good design. Only used for `type = "max_entropy"`. +#' +#' @examples +#' grid_latin_hypercube(penalty(), mixture(), original = TRUE) +#' +#' @keywords internal #' @export grid_max_entropy <- function(x, ..., @@ -249,6 +267,11 @@ grid_max_entropy <- function(x, original = TRUE, variogram_range = 0.5, iter = 1000) { + lifecycle::deprecate_soft( + "1.2.1.9000", + "grid_max_entropy()", + "grid_space_filling()" + ) dots <- list(...) if (any(names(dots) == "levels")) { @@ -258,7 +281,7 @@ grid_max_entropy <- function(x, } #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_max_entropy.parameters <- function(x, ..., size = 3, @@ -282,7 +305,7 @@ grid_max_entropy.parameters <- function(x, } #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_max_entropy.list <- function(x, ..., size = 3, @@ -306,7 +329,7 @@ grid_max_entropy.list <- function(x, #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_max_entropy.param <- function(x, ..., size = 3, @@ -329,7 +352,7 @@ grid_max_entropy.param <- function(x, } #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_max_entropy.workflow <- function(x, ..., size = 3, @@ -387,8 +410,14 @@ make_max_entropy_grid <- function(..., } #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_latin_hypercube <- function(x, ..., size = 3, original = TRUE) { + lifecycle::deprecate_soft( + "1.2.1.9000", + "grid_latin_hypercube()", + "grid_space_filling()" + ) + dots <- list(...) if (any(names(dots) == "levels")) { rlang::warn("`levels` is not an argument to `grid_latin_hypercube()`. Did you mean `size`?") @@ -397,7 +426,7 @@ grid_latin_hypercube <- function(x, ..., size = 3, original = TRUE) { } #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_latin_hypercube.parameters <- function(x, ..., size = 3, original = TRUE) { params <- x$object names(params) <- x$id @@ -408,7 +437,7 @@ grid_latin_hypercube.parameters <- function(x, ..., size = 3, original = TRUE) { } #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_latin_hypercube.list <- function(x, ..., size = 3, original = TRUE) { y <- parameters(x) params <- y$object @@ -420,7 +449,7 @@ grid_latin_hypercube.list <- function(x, ..., size = 3, original = TRUE) { #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_latin_hypercube.param <- function(x, ..., size = 3, original = TRUE) { y <- parameters(list(x, ...)) params <- y$object @@ -432,7 +461,7 @@ grid_latin_hypercube.param <- function(x, ..., size = 3, original = TRUE) { #' @export -#' @rdname grid_space_filling +#' @rdname grid_max_entropy grid_latin_hypercube.workflow <- function(x, ..., size = 3, original = TRUE) { lifecycle::deprecate_stop( when = "1.2.0", diff --git a/man/dials-package.Rd b/man/dials-package.Rd index 9bb2dc9c..eca5ac2c 100644 --- a/man/dials-package.Rd +++ b/man/dials-package.Rd @@ -31,7 +31,7 @@ random_set <- grid_random(penalty(), mixture(), deg_free(), size = 5) random_set # A small space-filling design based on experimental design methods: -design_set <- grid_max_entropy(penalty(), mixture(), deg_free(), size = 5) +design_set <- grid_space_filling(penalty(), mixture(), deg_free(), size = 5) design_set } \seealso{ diff --git a/man/grid_max_entropy.Rd b/man/grid_max_entropy.Rd new file mode 100644 index 00000000..3ad892c8 --- /dev/null +++ b/man/grid_max_entropy.Rd @@ -0,0 +1,102 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/space_filling.R +\name{grid_max_entropy} +\alias{grid_max_entropy} +\alias{grid_max_entropy.parameters} +\alias{grid_max_entropy.list} +\alias{grid_max_entropy.param} +\alias{grid_max_entropy.workflow} +\alias{grid_latin_hypercube} +\alias{grid_latin_hypercube.parameters} +\alias{grid_latin_hypercube.list} +\alias{grid_latin_hypercube.param} +\alias{grid_latin_hypercube.workflow} +\title{Max-entropy and latin hypercube grids} +\usage{ +grid_max_entropy( + x, + ..., + size = 3, + original = TRUE, + variogram_range = 0.5, + iter = 1000 +) + +\method{grid_max_entropy}{parameters}( + x, + ..., + size = 3, + original = TRUE, + variogram_range = 0.5, + iter = 1000 +) + +\method{grid_max_entropy}{list}( + x, + ..., + size = 3, + original = TRUE, + variogram_range = 0.5, + iter = 1000 +) + +\method{grid_max_entropy}{param}( + x, + ..., + size = 3, + original = TRUE, + variogram_range = 0.5, + iter = 1000 +) + +\method{grid_max_entropy}{workflow}( + x, + ..., + size = 3, + original = TRUE, + variogram_range = 0.5, + iter = 1000 +) + +grid_latin_hypercube(x, ..., size = 3, original = TRUE) + +\method{grid_latin_hypercube}{parameters}(x, ..., size = 3, original = TRUE) + +\method{grid_latin_hypercube}{list}(x, ..., size = 3, original = TRUE) + +\method{grid_latin_hypercube}{param}(x, ..., size = 3, original = TRUE) + +\method{grid_latin_hypercube}{workflow}(x, ..., size = 3, original = TRUE) +} +\arguments{ +\item{x}{A \code{param} object, list, or \code{parameters}.} + +\item{...}{One or more \code{param} objects (such as \code{\link[=mtry]{mtry()}} or +\code{\link[=penalty]{penalty()}}). None of the objects can have \code{unknown()} values in +the parameter ranges or values.} + +\item{size}{A single integer for the maximum number of parameter value +combinations returned. If duplicate combinations are +generated from this size, the smaller, unique set is returned.} + +\item{original}{A logical: should the parameters be in the original units or +in the transformed space (if any)?} + +\item{variogram_range}{A numeric value greater than zero. Larger values +reduce the likelihood of empty regions in the parameter space. Only used +for \code{type = "max_entropy"}.} + +\item{iter}{An integer for the maximum number of iterations used to find +a good design. Only used for \code{type = "max_entropy"}.} +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} + +These functions are deprecated because they have been replaced by +\code{\link[=grid_space_filling]{grid_space_filling()}}. +} +\examples{ +grid_latin_hypercube(penalty(), mixture(), original = TRUE) + +} +\keyword{internal} diff --git a/man/grid_space_filling.Rd b/man/grid_space_filling.Rd index b2da6504..31f3b0bb 100644 --- a/man/grid_space_filling.Rd +++ b/man/grid_space_filling.Rd @@ -5,16 +5,6 @@ \alias{grid_space_filling.parameters} \alias{grid_space_filling.list} \alias{grid_space_filling.param} -\alias{grid_max_entropy} -\alias{grid_max_entropy.parameters} -\alias{grid_max_entropy.list} -\alias{grid_max_entropy.param} -\alias{grid_max_entropy.workflow} -\alias{grid_latin_hypercube} -\alias{grid_latin_hypercube.parameters} -\alias{grid_latin_hypercube.list} -\alias{grid_latin_hypercube.param} -\alias{grid_latin_hypercube.workflow} \title{Space-filling parameter grids} \usage{ grid_space_filling(x, ..., size = 5, type = "any", original = TRUE) @@ -48,61 +38,6 @@ grid_space_filling(x, ..., size = 5, type = "any", original = TRUE) type = "any", original = TRUE ) - -grid_max_entropy( - x, - ..., - size = 3, - original = TRUE, - variogram_range = 0.5, - iter = 1000 -) - -\method{grid_max_entropy}{parameters}( - x, - ..., - size = 3, - original = TRUE, - variogram_range = 0.5, - iter = 1000 -) - -\method{grid_max_entropy}{list}( - x, - ..., - size = 3, - original = TRUE, - variogram_range = 0.5, - iter = 1000 -) - -\method{grid_max_entropy}{param}( - x, - ..., - size = 3, - original = TRUE, - variogram_range = 0.5, - iter = 1000 -) - -\method{grid_max_entropy}{workflow}( - x, - ..., - size = 3, - original = TRUE, - variogram_range = 0.5, - iter = 1000 -) - -grid_latin_hypercube(x, ..., size = 3, original = TRUE) - -\method{grid_latin_hypercube}{parameters}(x, ..., size = 3, original = TRUE) - -\method{grid_latin_hypercube}{list}(x, ..., size = 3, original = TRUE) - -\method{grid_latin_hypercube}{param}(x, ..., size = 3, original = TRUE) - -\method{grid_latin_hypercube}{workflow}(x, ..., size = 3, original = TRUE) } \arguments{ \item{x}{A \code{param} object, list, or \code{parameters}.} @@ -213,9 +148,6 @@ grid_space_filling( size = 10, original = FALSE ) - -grid_latin_hypercube(penalty(), mixture(), original = TRUE) - # ------------------------------------------------------------------------------ # comparing methods diff --git a/tests/testthat/_snaps/aaa_unknown.md b/tests/testthat/_snaps/aaa_unknown.md index 61c3bb64..b5062524 100644 --- a/tests/testthat/_snaps/aaa_unknown.md +++ b/tests/testthat/_snaps/aaa_unknown.md @@ -46,36 +46,36 @@ --- Code - grid_latin_hypercube(p1) + grid_space_filling(p1, type = "latin_hypercube") Condition - Error in `grid_latin_hypercube()`: + Error in `grid_space_filling()`: x This argument contains unknowns: `q`. i See the `dials::finalize()` function. --- Code - grid_latin_hypercube(p2) + grid_space_filling(p2, type = "latin_hypercube") Condition - Error in `grid_latin_hypercube()`: + Error in `grid_space_filling()`: x This argument contains unknowns: `mtry`. i See the `dials::finalize()` function. --- Code - grid_max_entropy(p1) + grid_space_filling(p1, type = "max_entropy") Condition - Error in `grid_max_entropy()`: + Error in `grid_space_filling()`: x This argument contains unknowns: `q`. i See the `dials::finalize()` function. --- Code - grid_max_entropy(p2) + grid_space_filling(p2, type = "max_entropy") Condition - Error in `grid_max_entropy()`: + Error in `grid_space_filling()`: x This argument contains unknowns: `mtry`. i See the `dials::finalize()` function. @@ -127,27 +127,27 @@ --- Code - grid_latin_hypercube(mtry()) + grid_space_filling(mtry(), type = "latin_hypercube") Condition - Error in `grid_latin_hypercube()`: + Error in `grid_space_filling()`: x This argument contains unknowns: `mtry`. i See the `dials::finalize()` function. --- Code - grid_max_entropy(min_n(), q = mtry()) + grid_space_filling(min_n(), q = mtry(), type = "max_entropy") Condition - Error in `grid_max_entropy()`: + Error in `grid_space_filling()`: x This argument contains unknowns: `q`. i See the `dials::finalize()` function. --- Code - grid_max_entropy(mtry()) + grid_space_filling(mtry(), type = "max_entropy") Condition - Error in `grid_max_entropy()`: + Error in `grid_space_filling()`: x This argument contains unknowns: `mtry`. i See the `dials::finalize()` function. diff --git a/tests/testthat/_snaps/grids.md b/tests/testthat/_snaps/grids.md index aeda4869..fc9d5ab3 100644 --- a/tests/testthat/_snaps/grids.md +++ b/tests/testthat/_snaps/grids.md @@ -19,32 +19,36 @@ # wrong argument name Code - grid_latin_hypercube(p, levels = 5) + grid_space_filling(p, levels = 5, type = "latin_hypercube") Condition Warning: - `levels` is not an argument to `grid_latin_hypercube()`. Did you mean `size`? + `levels` is not an argument to `grid_space_filling()`. Did you mean `size`? Output - # A tibble: 3 x 2 - penalty mixture - - 1 0.000000438 0.191 - 2 0.0000000918 0.688 - 3 0.00102 0.395 + # A tibble: 5 x 2 + penalty mixture + + 1 0.00563 0.367 + 2 0.0689 0.754 + 3 0.0000374 0.841 + 4 0.00000000349 0.440 + 5 0.0000000402 0.198 --- Code - grid_max_entropy(p, levels = 5) + grid_space_filling(p, levels = 5, type = "max_entropy") Condition Warning: - `levels` is not an argument to `grid_max_entropy()`. Did you mean `size`? + `levels` is not an argument to `grid_space_filling()`. Did you mean `size`? Output - # A tibble: 3 x 2 - penalty mixture - - 1 0.281 0.251 - 2 0.108 0.943 - 3 0.000000124 0.0366 + # A tibble: 5 x 2 + penalty mixture + + 1 1.37e- 1 0.925 + 2 5.80e- 1 0.237 + 3 1.31e- 5 0.526 + 4 3.77e-10 0.946 + 5 2.56e- 8 0.108 --- @@ -55,13 +59,13 @@ `levels` is not an argument to `grid_random()`. Did you mean `size`? Output # A tibble: 5 x 2 - penalty mixture - - 1 1.27e-10 0.642 - 2 1.43e- 2 0.942 - 3 5.29e- 4 0.284 - 4 7.45e- 2 0.523 - 5 4.91e-10 0.00216 + penalty mixture + + 1 0.00148 0.499 + 2 0.982 0.858 + 3 0.00000201 0.850 + 4 0.00000000125 0.493 + 5 0.0000864 0.968 --- diff --git a/tests/testthat/_snaps/space_filling.md b/tests/testthat/_snaps/space_filling.md index e45a5b7f..63f976c3 100644 --- a/tests/testthat/_snaps/space_filling.md +++ b/tests/testthat/_snaps/space_filling.md @@ -1,3 +1,18 @@ +# `grid_max_entropy()` is deprecated + + Code + grid_max_entropy(mixture(), trees(), size = 2) + Condition + Warning: + `grid_max_entropy()` was deprecated in dials 1.2.1.9000. + i Please use `grid_space_filling()` instead. + Output + # A tibble: 2 x 2 + mixture trees + + 1 0.00549 1964 + 2 0.549 1880 + # max entropy designs Code @@ -7,6 +22,21 @@ x This argument contains unknowns: `mtry`. i See the `dials::finalize()` function. +# `grid_latin_hypercube()` is deprecated + + Code + grid_latin_hypercube(mixture(), trees(), size = 2) + Condition + Warning: + `grid_latin_hypercube()` was deprecated in dials 1.2.1.9000. + i Please use `grid_space_filling()` instead. + Output + # A tibble: 2 x 2 + mixture trees + + 1 0.438 1787 + 2 0.709 772 + # latin square designs Code diff --git a/tests/testthat/test-aaa_unknown.R b/tests/testthat/test-aaa_unknown.R index ab4c42ea..6f73cbd5 100644 --- a/tests/testthat/test-aaa_unknown.R +++ b/tests/testthat/test-aaa_unknown.R @@ -35,17 +35,17 @@ test_that("unknowns in grid functions", { expect_snapshot(error = TRUE, grid_regular(p3)) expect_snapshot(error = TRUE, grid_random(p1)) expect_snapshot(error = TRUE, grid_random(p2)) - expect_snapshot(error = TRUE, grid_latin_hypercube(p1)) - expect_snapshot(error = TRUE, grid_latin_hypercube(p2)) - expect_snapshot(error = TRUE, grid_max_entropy(p1)) - expect_snapshot(error = TRUE, grid_max_entropy(p2)) + expect_snapshot(error = TRUE, grid_space_filling(p1, type = "latin_hypercube")) + expect_snapshot(error = TRUE, grid_space_filling(p2, type = "latin_hypercube")) + expect_snapshot(error = TRUE, grid_space_filling(p1, type = "max_entropy")) + expect_snapshot(error = TRUE, grid_space_filling(p2, type = "max_entropy")) expect_snapshot(error = TRUE, grid_regular(min_n(), q = mtry())) expect_snapshot(error = TRUE, grid_regular(mtry())) expect_snapshot(error = TRUE, grid_random(min_n(), q = mtry())) expect_snapshot(error = TRUE, grid_random(mtry())) expect_snapshot(error = TRUE, grid_regular(min_n(), q = mtry())) - expect_snapshot(error = TRUE, grid_latin_hypercube(mtry())) - expect_snapshot(error = TRUE, grid_max_entropy(min_n(), q = mtry())) - expect_snapshot(error = TRUE, grid_max_entropy(mtry())) + expect_snapshot(error = TRUE, grid_space_filling(mtry(), type = "latin_hypercube")) + expect_snapshot(error = TRUE, grid_space_filling(min_n(), q = mtry(), type = "max_entropy")) + expect_snapshot(error = TRUE, grid_space_filling(mtry(), type = "max_entropy")) }) diff --git a/tests/testthat/test-grids.R b/tests/testthat/test-grids.R index 49395796..31b232bd 100644 --- a/tests/testthat/test-grids.R +++ b/tests/testthat/test-grids.R @@ -69,8 +69,10 @@ test_that("random grid", { test_that("wrong argument name", { skip_if_below_r_version("3.6") p <- parameters(penalty(), mixture()) - expect_snapshot(grid_latin_hypercube(p, levels = 5)) - expect_snapshot(grid_max_entropy(p, levels = 5)) + set.seed(1) + + expect_snapshot(grid_space_filling(p, levels = 5, type = "latin_hypercube")) + expect_snapshot(grid_space_filling(p, levels = 5, type = "max_entropy")) expect_snapshot(grid_random(p, levels = 5)) expect_snapshot(grid_regular(p, size = 5)) }) diff --git a/tests/testthat/test-space_filling.R b/tests/testthat/test-space_filling.R index 31639ccf..b578547b 100644 --- a/tests/testthat/test-space_filling.R +++ b/tests/testthat/test-space_filling.R @@ -1,5 +1,13 @@ +test_that("`grid_max_entropy()` is deprecated", { + set.seed(1) + expect_snapshot( + grid_max_entropy(mixture(), trees(), size = 2) + ) +}) test_that("max entropy designs", { + withr::local_options(lifecycle_verbosity = "quiet") + grid_1 <- grid_max_entropy( cost(), mixture(), size = 11, @@ -46,7 +54,16 @@ test_that("max entropy designs", { ) }) +test_that("`grid_latin_hypercube()` is deprecated", { + set.seed(1) + expect_snapshot( + grid_latin_hypercube(mixture(), trees(), size = 2) + ) +}) + test_that("latin square designs", { + withr::local_options(lifecycle_verbosity = "quiet") + grid_1 <- grid_latin_hypercube( cost(), mixture(), size = 11, @@ -187,6 +204,7 @@ test_that("sfd package designs - uniform", { }) test_that("DiceDesign package designs - max entropy", { + withr::local_options(lifecycle_verbosity = "quiet") size <- 11 prm <- parameters(mom = momentum(), mixture()) @@ -224,6 +242,7 @@ test_that("DiceDesign package designs - max entropy", { }) test_that("DiceDesign package designs - latin hypercube", { + withr::local_options(lifecycle_verbosity = "quiet") size <- 11 prm <- parameters(mom = momentum(), mixture())