From d21ae3fee125532fec673cbd7a8ba0c038658814 Mon Sep 17 00:00:00 2001 From: simonpcouch Date: Fri, 28 Oct 2022 16:49:06 -0400 Subject: [PATCH] export extension check helpers --- DESCRIPTION | 2 +- NAMESPACE | 3 ++ R/misc.R | 79 +++++++++++++++++++--------------- man/extension-check-helpers.Rd | 70 ++++++++++++++++++++++++++++++ 4 files changed, 118 insertions(+), 36 deletions(-) create mode 100644 man/extension-check-helpers.Rd diff --git a/DESCRIPTION b/DESCRIPTION index 9c0c3b9a9..b1a6d5e22 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: parsnip Title: A Common API to Modeling and Analysis Functions -Version: 1.0.2.9002 +Version: 1.0.2.9003 Authors@R: c( person("Max", "Kuhn", , "max@rstudio.com", role = c("aut", "cre")), person("Davis", "Vaughan", , "davis@rstudio.com", role = "aut"), diff --git a/NAMESPACE b/NAMESPACE index 442e56aea..de6aaef2e 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -250,6 +250,7 @@ export(predict_time) export(predict_time.model_fit) export(prepare_data) export(print_model_spec) +export(prompt_missing_implementation) export(proportional_hazards) export(rand_forest) export(repair_call) @@ -275,6 +276,8 @@ export(show_call) export(show_engines) export(show_fit) export(show_model_info) +export(spec_is_loaded) +export(spec_is_possible) export(stan_conf_int) export(surv_reg) export(survival_reg) diff --git a/R/misc.R b/R/misc.R index ee6e9bb97..e6e38852c 100644 --- a/R/misc.R +++ b/R/misc.R @@ -54,39 +54,42 @@ mode_filter_condition <- function(mode, user_specified_mode) { rlang::quo(mode == !!mode) } -# Model Specification Checking: -# -# The helpers `spec_is_possible()`, `spec_is_loaded()`, and -# `prompt_missing_implementation()` provide tooling for checking -# model specifications. In addition to the `spec`, `engine`, and `mode` -# arguments, the functions take arguments `user_specified_engine` and -# `user_specified_mode`, denoting whether the user themselves has -# specified the engine or mode, respectively. -# -# `spec_is_possible()` checks against the union of -# -# * the current parsnip model environment and -# * the `model_info_table` of "pre-registered" model specifications -# -# to determine whether a model is well-specified. See -# `parsnip:::read_model_info_table()` for this table. -# -# `spec_is_loaded()` checks only against the current parsnip model environment. -# -# `spec_is_possible()` is executed automatically on `new_model_spec()`, -# `set_mode()`, and `set_engine()`, and `spec_is_loaded()` is executed -# automatically in `print.model_spec()`, among other places. `spec_is_possible()` -# should be used when a model specification is still "in progress" of being -# specified, while `spec_is_loaded` should only be called when parsnip or an -# extension receives some indication that the user is "done" specifying a model -# specification: at print, fit, addition to a workflow, or `extract_*()`, for -# example. -# -# When `spec_is_loaded()` is `FALSE`, the `prompt_missing_implementation()` -# helper will construct an informative message to prompt users to load or -# install needed packages. It's `prompt` argument refers to the prompting -# function to use, usually [cli::cli_inform] or [cli::cli_abort], and the -# ellipses are passed to that function. +#' Model Specification Checking: +#' +#' The helpers `spec_is_possible()`, `spec_is_loaded()`, and +#' `prompt_missing_implementation()` provide tooling for checking +#' model specifications. In addition to the `spec`, `engine`, and `mode` +#' arguments, the functions take arguments `user_specified_engine` and +#' `user_specified_mode`, denoting whether the user themselves has +#' specified the engine or mode, respectively. +#' +#' `spec_is_possible()` checks against the union of +#' +#' * the current parsnip model environment and +#' * the `model_info_table` of "pre-registered" model specifications +#' +#' to determine whether a model is well-specified. See +#' `parsnip:::read_model_info_table()` for this table. +#' +#' `spec_is_loaded()` checks only against the current parsnip model environment. +#' +#' `spec_is_possible()` is executed automatically on `new_model_spec()`, +#' `set_mode()`, and `set_engine()`, and `spec_is_loaded()` is executed +#' automatically in `print.model_spec()`, among other places. `spec_is_possible()` +#' should be used when a model specification is still "in progress" of being +#' specified, while `spec_is_loaded` should only be called when parsnip or an +#' extension receives some indication that the user is "done" specifying a model +#' specification: at print, fit, addition to a workflow, or `extract_*()`, for +#' example. +#' +#' When `spec_is_loaded()` is `FALSE`, the `prompt_missing_implementation()` +#' helper will construct an informative message to prompt users to load or +#' install needed packages. It's `prompt` argument refers to the prompting +#' function to use, usually [cli::cli_inform] or [cli::cli_abort], and the +#' ellipses are passed to that function. +#' @export +#' @keywords internal +#' @rdname extension-check-helpers spec_is_possible <- function(spec, engine = spec$engine, user_specified_engine = spec$user_specified_engine, @@ -115,7 +118,10 @@ spec_is_possible <- function(spec, return(nrow(possibilities) > 0) } -# see notes above spec_is_possible for more information on usage +# see ?add_on_exports for more information on usage +#' @export +#' @keywords internal +#' @rdname extension-check-helpers spec_is_loaded <- function(spec, engine = spec$engine, user_specified_engine = spec$user_specified_engine, @@ -153,7 +159,10 @@ is_printable_spec <- function(x) { # if there's a "pre-registered" extension supporting that setup, # nudge the user to install/load it. # -# see notes above spec_is_possible for more information on usage +# see ?add_on_exports for more information on usage +#' @export +#' @keywords internal +#' @rdname extension-check-helpers prompt_missing_implementation <- function(spec, engine = spec$engine, user_specified_engine = spec$user_specified_engine, diff --git a/man/extension-check-helpers.Rd b/man/extension-check-helpers.Rd new file mode 100644 index 000000000..d6f4b5b3e --- /dev/null +++ b/man/extension-check-helpers.Rd @@ -0,0 +1,70 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/misc.R +\name{spec_is_possible} +\alias{spec_is_possible} +\alias{spec_is_loaded} +\alias{prompt_missing_implementation} +\title{Model Specification Checking:} +\usage{ +spec_is_possible( + spec, + engine = spec$engine, + user_specified_engine = spec$user_specified_engine, + mode = spec$mode, + user_specified_mode = spec$user_specified_mode +) + +spec_is_loaded( + spec, + engine = spec$engine, + user_specified_engine = spec$user_specified_engine, + mode = spec$mode, + user_specified_mode = spec$user_specified_mode +) + +prompt_missing_implementation( + spec, + engine = spec$engine, + user_specified_engine = spec$user_specified_engine, + mode = spec$mode, + user_specified_mode = spec$user_specified_mode, + prompt, + ... +) +} +\description{ +The helpers \code{spec_is_possible()}, \code{spec_is_loaded()}, and +\code{prompt_missing_implementation()} provide tooling for checking +model specifications. In addition to the \code{spec}, \code{engine}, and \code{mode} +arguments, the functions take arguments \code{user_specified_engine} and +\code{user_specified_mode}, denoting whether the user themselves has +specified the engine or mode, respectively. +} +\details{ +\code{spec_is_possible()} checks against the union of +\itemize{ +\item the current parsnip model environment and +\item the \code{model_info_table} of "pre-registered" model specifications +} + +to determine whether a model is well-specified. See +\code{parsnip:::read_model_info_table()} for this table. + +\code{spec_is_loaded()} checks only against the current parsnip model environment. + +\code{spec_is_possible()} is executed automatically on \code{new_model_spec()}, +\code{set_mode()}, and \code{set_engine()}, and \code{spec_is_loaded()} is executed +automatically in \code{print.model_spec()}, among other places. \code{spec_is_possible()} +should be used when a model specification is still "in progress" of being +specified, while \code{spec_is_loaded} should only be called when parsnip or an +extension receives some indication that the user is "done" specifying a model +specification: at print, fit, addition to a workflow, or \verb{extract_*()}, for +example. + +When \code{spec_is_loaded()} is \code{FALSE}, the \code{prompt_missing_implementation()} +helper will construct an informative message to prompt users to load or +install needed packages. It's \code{prompt} argument refers to the prompting +function to use, usually \link[cli:cli_abort]{cli::cli_inform} or \link[cli:cli_abort]{cli::cli_abort}, and the +ellipses are passed to that function. +} +\keyword{internal}