diff --git a/DESCRIPTION b/DESCRIPTION index 4d81a3a..11d67f1 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -19,7 +19,7 @@ URL: https://github.com/tidymodels/finetune, BugReports: https://github.com/tidymodels/finetune/issues Depends: R (>= 3.5), - tune (>= 1.1.2.9011) + tune (>= 1.1.2.9020) Imports: cli, dials (>= 0.1.0), diff --git a/NEWS.md b/NEWS.md index 55f5ce5..6fe8a90 100644 --- a/NEWS.md +++ b/NEWS.md @@ -10,12 +10,11 @@ * Enabling the `verbose_elim` control option for `tune_race_anova()` will now additionally introduce a message confirming that the function is evaluating against the burn-in resamples. -* Updates based on the new version of tune, primarily for survival analysis models. +* Updates based on the new version of tune, primarily for survival analysis models (#104). ## Breaking Change -* `show_best.tune_race()` gains an `eval_time` argument for censored regression models. This breaks passing `n` by position (#104). - +* Ellipses (...) are now used consistently in the package to require optional arguments to be named. `collect_predictions()`, `collect_metrics()` and `show_best()` methods previously had ellipses at the end of the function signature that have been moved to follow the last argument without a default value. Optional arguments previously passed by position will now error informatively prompting them to be named (#105). # finetune 1.1.0 diff --git a/R/racing_helpers.R b/R/racing_helpers.R index 07f92c2..5f47a9b 100644 --- a/R/racing_helpers.R +++ b/R/racing_helpers.R @@ -665,12 +665,13 @@ randomize_resamples <- function(x) { #' @name collect_predictions collect_predictions.tune_race <- function(x, + ..., summarize = FALSE, parameters = NULL, - all_configs = FALSE, - ...) { + all_configs = FALSE) { + rlang::check_dots_empty() x <- dplyr::select(x, -.order) - res <- NextMethod(summarize = summarize, parameters = parameters) + res <- collect_predictions(x, summarize = summarize, parameters = parameters) if (!all_configs) { final_configs <- subset_finished_race(x) res <- dplyr::inner_join(res, final_configs, by = ".config") @@ -681,10 +682,11 @@ collect_predictions.tune_race <- #' @inheritParams tune::collect_metrics #' @export #' @rdname collect_predictions -collect_metrics.tune_race <- function(x, summarize = TRUE, all_configs = FALSE, ...) { +collect_metrics.tune_race <- function(x, ..., summarize = TRUE, type = c("long", "wide"), all_configs = FALSE) { + rlang::check_dots_empty() x <- dplyr::select(x, -.order) final_configs <- subset_finished_race(x) - res <- NextMethod(summarize = summarize, ...) + res <- collect_metrics(x, summarize = summarize, type = type) if (!all_configs) { final_configs <- subset_finished_race(x) res <- dplyr::inner_join(res, final_configs, by = ".config") @@ -704,7 +706,13 @@ collect_metrics.tune_race <- function(x, summarize = TRUE, all_configs = FALSE, #' resampled). Comparing performance metrics for configurations averaged with #' different resamples is likely to lead to inappropriate results. #' @export -show_best.tune_race <- function(x, metric = NULL, eval_time = NULL, n = 5, ...) { +show_best.tune_race <- function(x, + ..., + metric = NULL, + eval_time = NULL, + n = 5, + call = rlang::current_env()) { + rlang::check_dots_empty() if (!is.null(metric)) { # What was used to judge the race and how are they being sorted now? metrics <- tune::.get_tune_metrics(x) @@ -722,7 +730,7 @@ show_best.tune_race <- function(x, metric = NULL, eval_time = NULL, n = 5, ...) x <- dplyr::select(x, -.order) final_configs <- subset_finished_race(x) - res <- NextMethod(metric = metric, eval_time = eval_time, n = Inf, ...) + res <- NextMethod(metric = metric, eval_time = eval_time, n = Inf, call = call) res$.ranked <- 1:nrow(res) res <- dplyr::inner_join(res, final_configs, by = ".config") res$.ranked <- NULL diff --git a/R/tune_race_anova.R b/R/tune_race_anova.R index 86480b2..a979930 100644 --- a/R/tune_race_anova.R +++ b/R/tune_race_anova.R @@ -303,8 +303,8 @@ tune_race_anova_workflow <- opt_metric_time <- tune::first_eval_time( metrics, - opt_metric_name, - eval_time, + metric = opt_metric_name, + eval_time = eval_time, call = call ) diff --git a/R/tune_race_win_loss.R b/R/tune_race_win_loss.R index 1c67d9d..8f4c0e8 100644 --- a/R/tune_race_win_loss.R +++ b/R/tune_race_win_loss.R @@ -283,8 +283,8 @@ tune_race_win_loss_workflow <- opt_metric_time <- tune::first_eval_time( metrics, - opt_metric_name, - eval_time, + metric = opt_metric_name, + eval_time = eval_time, call = call ) diff --git a/R/tune_sim_anneal.R b/R/tune_sim_anneal.R index 4cb6e0b..6e4f190 100644 --- a/R/tune_sim_anneal.R +++ b/R/tune_sim_anneal.R @@ -344,8 +344,8 @@ tune_sim_anneal_workflow <- eval_time <- tune::check_eval_time_arg(eval_time, metrics, call = call) opt_metric_time <- tune::first_eval_time( metrics, - opt_metric_name, - eval_time, + metric = opt_metric_name, + eval_time = eval_time, call = call ) diff --git a/man/collect_predictions.Rd b/man/collect_predictions.Rd index 9e4c59d..9d35d4b 100644 --- a/man/collect_predictions.Rd +++ b/man/collect_predictions.Rd @@ -8,18 +8,26 @@ \usage{ \method{collect_predictions}{tune_race}( x, + ..., summarize = FALSE, parameters = NULL, - all_configs = FALSE, - ... + all_configs = FALSE ) -\method{collect_metrics}{tune_race}(x, summarize = TRUE, all_configs = FALSE, ...) +\method{collect_metrics}{tune_race}( + x, + ..., + summarize = TRUE, + type = c("long", "wide"), + all_configs = FALSE +) } \arguments{ \item{x}{The results of \code{\link[tune:tune_grid]{tune_grid()}}, \code{\link[tune:tune_bayes]{tune_bayes()}}, \code{\link[tune:fit_resamples]{fit_resamples()}}, or \code{\link[tune:last_fit]{last_fit()}}. For \code{\link[tune:collect_predictions]{collect_predictions()}}, the control option \code{save_pred = TRUE} should have been used.} +\item{...}{Not currently used.} + \item{summarize}{A logical; should metrics be summarized over resamples (\code{TRUE}) or return the values for each individual resample. Note that, if \code{x} is created by \code{\link[tune:last_fit]{last_fit()}}, \code{summarize} has no effect. For the other object @@ -34,7 +42,11 @@ if \code{tune("my_param")} was used).} configurations or just those that made it to the end of the race (the default).} -\item{...}{Not currently used.} +\item{type}{One of \code{"long"} (the default) or \code{"wide"}. When \code{type = "long"}, +output has columns \code{.metric} and one of \code{.estimate} or \code{mean}. +\code{.estimate}/\code{mean} gives the values for the \code{.metric}. When \code{type = "wide"}, +each metric has its own column and the \code{n} and \code{std_err} columns are removed, +if they exist.} } \value{ A tibble. The column names depend on the results and the mode of the diff --git a/man/show_best.Rd b/man/show_best.Rd index 0a52e56..c8fc257 100644 --- a/man/show_best.Rd +++ b/man/show_best.Rd @@ -4,11 +4,25 @@ \alias{show_best.tune_race} \title{Investigate best tuning parameters} \usage{ -\method{show_best}{tune_race}(x, metric = NULL, eval_time = NULL, n = 5, ...) +\method{show_best}{tune_race}( + x, + ..., + metric = NULL, + eval_time = NULL, + n = 5, + call = rlang::current_env() +) } \arguments{ \item{x}{The results of \code{\link[tune:tune_grid]{tune_grid()}} or \code{\link[tune:tune_bayes]{tune_bayes()}}.} +\item{...}{For \code{\link[tune:select_by_one_std_err]{select_by_one_std_err()}} and \code{\link[tune:select_by_pct_loss]{select_by_pct_loss()}}, this +argument is passed directly to \code{\link[dplyr:arrange]{dplyr::arrange()}} so that the user can sort +the models from \emph{most simple to most complex}. That is, for a parameter \code{p}, +pass the unquoted expression \code{p} if smaller values of \code{p} indicate a simpler +model, or \code{desc(p)} if larger values indicate a simpler model. At +least one term is required for these two functions. See the examples below.} + \item{metric}{A character value for the metric that will be used to sort the models. (See \url{https://yardstick.tidymodels.org/articles/metric-types.html} for @@ -23,12 +37,7 @@ default will automatically use the first evaluation time used by \code{x}.} \item{n}{An integer for the maximum number of top results/rows to return.} -\item{...}{For \code{\link[tune:select_by_one_std_err]{select_by_one_std_err()}} and \code{\link[tune:select_by_pct_loss]{select_by_pct_loss()}}, this -argument is passed directly to \code{\link[dplyr:arrange]{dplyr::arrange()}} so that the user can sort -the models from \emph{most simple to most complex}. That is, for a parameter \code{p}, -pass the unquoted expression \code{p} if smaller values of \code{p} indicate a simpler -model, or \code{desc(p)} if larger values indicate a simpler model. At -least one term is required for these two functions. See the examples below.} +\item{call}{The call to be shown in errors and warnings.} } \description{ \code{\link[=show_best]{show_best()}} displays the top sub-models and their performance estimates.