improve prompting about missing implementations

[simonpcouch]

Follows up on #732 and #778. The goal here is to tighten the logic for prompts about missing implementations. This PR eliminates false positives and makes sure we always suggest "registered" extension packages when they could be relevant.

To do so, we defer model specification checking for type / engine / mode combinations until we have some sort of clue that the user might be "done" specifying the model (If only we could <-.model_spec😭). This is at:

• print
• fit

...and functions that use either downstream. Some examples of how these prompts used to be raised:

library(parsnip)

# errors with a default engine, though doesn't call out baguette
bag_tree()
#> parsnip could not locate an implementation for `bag_tree` model specifications
#> using the `rpart` engine.
#> Bagged Decision Tree Model Specification (unknown)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: rpart

# bad: still includes default engine in error, bc triggered in bag_tree(),
# and still does not point to baguette
bag_tree() %>%
  set_engine("C5.0")
#> parsnip could not locate an implementation for `bag_tree` model specifications
#> using the `rpart` engine.
#> Bagged Decision Tree Model Specification (unknown)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: C5.0

# this should call out "censored regression" specifically, but does
# not because the error is triggered in bag_tree().
# also does not point to censored
bag_tree() %>%
  set_engine("rpart") %>%
  set_mode("censored regression")
#> parsnip could not locate an implementation for `bag_tree` model specifications
#> using the `rpart` engine.
#> Bagged Decision Tree Model Specification (censored regression)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: rpart

# this is well-defined:
library(censored)
#> Loading required package: survival

bag_tree() %>% 
  set_mode("censored regression") %>% 
  set_engine("rpart")
#> Bagged Decision Tree Model Specification (censored regression)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: rpart

# this errors differently when just censored is loaded
# ought to note that an implementation does live in baguette
bag_tree() %>%
  set_engine("C5.0")
#> Error in `check_spec_mode_engine_val()`:
#> ! Engine 'C5.0' is not supported for `bag_tree()`. See `show_engines('bag_tree')`.

# once baguette is loaded, this is well-defined:
library(baguette)

bag_tree() %>%
  set_engine("C5.0")
#> Bagged Decision Tree Model Specification (unknown)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: C5.0

^{Created on 2022-08-17 by the reprex package (v2.0.1)}

Same code with the dev version:

library(parsnip)

bag_tree()
#> ! parsnip could not locate an implementation for `bag_tree` model
#>   specifications.
#> ℹ The parsnip extension packages censored and baguette implement support for
#>   this specification.
#> ℹ Please install (if needed) and load to continue.
#> Bagged Decision Tree Model Specification (unknown)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: rpart

# now includes correct engine in error
bag_tree() %>%
  set_engine("C5.0")
#> ! parsnip could not locate an implementation for `bag_tree` model
#>   specifications using the `C5.0` engine.
#> ℹ The parsnip extension package baguette implements support for this
#>   specification.
#> ℹ Please install (if needed) and load to continue.
#> Bagged Decision Tree Model Specification (unknown)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: C5.0

# calls out "censored regression" specifically
bag_tree() %>%
  set_engine("rpart") %>%
  set_mode("censored regression")
#> ! parsnip could not locate an implementation for `bag_tree` censored regression
#>   model specifications using the `rpart` engine.
#> ℹ The parsnip extension package censored implements support for this
#>   specification.
#> ℹ Please install (if needed) and load to continue.
#> Bagged Decision Tree Model Specification (censored regression)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: rpart

# this is well-defined:
library(censored)
#> Loading required package: survival

bag_tree() %>% 
  set_mode("censored regression") %>% 
  set_engine("rpart")
#> Bagged Decision Tree Model Specification (censored regression)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: rpart

# this now prompts informatively, as before censored was loaded
bag_tree() %>%
  set_engine("C5.0")
#> ! parsnip could not locate an implementation for `bag_tree` model
#>   specifications using the `C5.0` engine.
#> ℹ The parsnip extension package baguette implements support for this
#>   specification.
#> ℹ Please install (if needed) and load to continue.
#> Bagged Decision Tree Model Specification (unknown)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: C5.0

library(baguette)

# prompt goes away once baguette is loaded
bag_tree() %>%
  set_engine("C5.0")
#> Bagged Decision Tree Model Specification (unknown)
#> 
#> Main Arguments:
#>   cost_complexity = 0
#>   min_n = 2
#> 
#> Computational engine: C5.0

^{Created on 2022-08-30 by the reprex package (v2.0.1)}

This also catches bugs related to how loading one unrelated extension would affect the prompts related to another. PR to extratests to make sure we test this here! There are also additional tests with decision trees there.

On fit(), this same message is elevated to an error.

Open to ideas if we have any other cues that a user may be "done" putting together a model spec—adding to a workflow is another instance, though we'll get "automatic" workflow support otherwise in that it wraps parsnip's print and fit methods. Same with parameter extraction.

[simonpcouch]

Note: this community post points out additional locations where we might want to drop these checks, none of which live in parsnip—workflows::add_model and workflows::extract_parameter_set_dials.workflow. May be worth exporting helpers.

[topepo]

I'll run this with TMwR and our workshop notes to test more.

Can you run revdeps?

[topepo]

These changes will have to propagate to the external extension packages too (e.g. model time)?

We'll also need to update the docs on tidymodels.org too (I believe).

[simonpcouch]

engine_filter_condition and mode_filter_condition (to be renamed re: comment), where these slots are processed, anticipate model objects from external extension packages not having this slot—in those cases, we bypass the additional prompts so that those external extensions fall back to the same errors as before. Those extensions can add the slot and get the prompting introduced in this PR "for free," since these prompts look to a full join of the model environment and model_info_table.

Good thought on the tidymodels.org docs. Will follow-up with a PR there.

[simonpcouch]

Thanks for the review! Running revdeps and addressing comments ATM.

[simonpcouch]

No new problems in revdeps, though I found a backward-compatibility issue that wasn't caught.

[simonpcouch]

The most recent commit exports and documents the relationship between the different checking functions more thoroughly:

The helpers spec_is_possible(), spec_is_loaded(), and
prompt_missing_implementation() provide tooling for checking
model specifications. In addition to the cls, 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.

[github-actions]

This pull request has been automatically locked. If you believe you have found a related problem, please file a new issue (with a reprex: https://reprex.tidyverse.org) and link to this issue.