Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

remove superfluous backticks across pkg documentation #1158

Merged
merged 2 commits into from
Aug 23, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions R/README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
# Some Notes on the Design of `parsnip`
# Some Notes on the Design of parsnip

`parsnip` is trying to solve the issues of unified interfaces for the myriad R modeling functions that have very heterogeneous interfaces and return values. It defines a set of modules, which are specific tasks, such as
The parsnip package is trying to solve the issues of unified interfaces for the myriad R modeling functions that have very heterogeneous interfaces and return values. It defines a set of modules, which are specific tasks, such as

* fitting the model
* obtaining numeric predictions for regression models
* computing different types of predictions for classification and censored regression models

and so on. The list of modules is likely to grow over time to include variable importance scores and so on,.

`caret` was written for the same purpose. The approach there was to encapsulate the modules as functions (see [this directory](https://github.com/topepo/caret/tree/master/models/files) for examples). The issue with having these modules as functions are:
The caret package was written for the same purpose. The approach there was to encapsulate the modules as functions (see [this directory](https://github.com/topepo/caret/tree/master/models/files) for examples). The issue with having these modules as functions are:

* A lot of code duplication.
* More difficult to maintain.
* Any functions in open code had to be a dependency of some sort. This led to a long ago version having about 200 package dependencies which was problematic.

To get around the last point, `caret` _compiles_ these modules into a large list and saves it in the package as an RData file. This avoids `R CMD check` from noticing that code and triggering warnings about dependencies.
To get around the last point, caret _compiles_ these modules into a large list and saves it in the package as an RData file. This avoids `R CMD check` from noticing that code and triggering warnings about dependencies.

## Model Fitting Modules

`parsnip` approaches the problem differently and relies more on using `call` objects for the modules. In the simple cases, the fit module is a list that contains information about the module including the package and function name for the call as well as any default options. For example, for logistic regression using `glm`, the module may look like:
parsnip approaches the problem differently and relies more on using `call` objects for the modules. In the simple cases, the fit module is a list that contains information about the module including the package and function name for the call as well as any default options. For example, for logistic regression using `glm`, the module may look like:

```r
list(
Expand Down Expand Up @@ -77,9 +77,9 @@ The same is true for quosures.

Making predictions is done in a manner similar to fitting models; a call is created in the same way. However, there are additional complexities.

First, the data or model fit object may require some preprocessing to make the predict function work. This does _not_ include executing a formula method on the data but may include coercing the new data into an appropriate format. It can also be used to check for specific fit object requirements. For example, an additional option is required for the `ranger` package to compute class probabilities. The `pre` element of a prediction module can be used to check that the relevant option is set correctly.
First, the data or model fit object may require some preprocessing to make the predict function work. This does _not_ include executing a formula method on the data but may include coercing the new data into an appropriate format. It can also be used to check for specific fit object requirements. For example, an additional option is required for the ranger package to compute class probabilities. The `pre` element of a prediction module can be used to check that the relevant option is set correctly.

Second, there is a high likelihood that the results of executing the prediction code will require post-processing to put the results into a usable format. `ranger`, for example, returns an object of specific class that contains the predicted values for the new data. The `post` element of the prediction module would extract this value and put it into a more consistent format.
Second, there is a high likelihood that the results of executing the prediction code will require post-processing to put the results into a usable format. ranger, for example, returns an object of specific class that contains the predicted values for the new data. The `post` element of the prediction module would extract this value and put it into a more consistent format.

The postprocessor can also be used to coerce the results into a [_tidy format_](https://tidymodels.github.io/model-implementation-principles/model-predictions.html#return-values).

4 changes: 2 additions & 2 deletions R/aaa_models.R
Original file line number Diff line number Diff line change
Expand Up @@ -511,7 +511,7 @@ check_interface_val <- function(x) {
#' and `raw`.
#' @param pkg An options character string for a package name.
#' @param parsnip A single character string for the "harmonized" argument name
#' that `parsnip` exposes.
#' that parsnip exposes.
#' @param original A single character string for the argument name that
#' underlying model function uses.
#' @param value A list that conforms to the `fit_obj` or `pred_obj` description
Expand All @@ -525,7 +525,7 @@ check_interface_val <- function(x) {
#' @keywords internal
#' @details These functions are available for users to add their
#' own models or engines (in a package or otherwise) so that they can
#' be accessed using `parsnip`. This is more thoroughly documented
#' be accessed using parsnip. This is more thoroughly documented
#' on the package web site (see references below).
#'
#' In short, `parsnip` stores an environment object that contains
Expand Down
2 changes: 1 addition & 1 deletion R/add_in.R
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#' Start an RStudio Addin that can write model specifications
#'
#' `parsnip_addin()` starts a process in the RStudio IDE Viewer window
#' that allows users to write code for `parsnip` model specifications from
#' that allows users to write code for parsnip model specifications from
#' various R packages. The new code is written to the current document at the
#' location of the cursor.
#'
Expand Down
6 changes: 3 additions & 3 deletions R/engines.R
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ load_libs <- function(x, quiet, attach = FALSE) {
#'
#' - _Main arguments_ are more commonly used and tend to be available across
#' engines. These names are standardized to work with different engines in a
#' consistent way, so you can use the \pkg{parsnip} main argument `trees`,
#' consistent way, so you can use the parsnip main argument `trees`,
#' instead of the heterogeneous arguments for this parameter from \pkg{ranger}
#' and \pkg{randomForest} packages (`num.trees` and `ntree`, respectively). Set
#' these in your model type function, like `rand_forest(trees = 2000)`.
Expand Down Expand Up @@ -154,10 +154,10 @@ set_engine.default <- function(object, engine, ...) {
#' Display currently available engines for a model
#'
#' The possible engines for a model can depend on what packages are loaded.
#' Some \pkg{parsnip} extension add engines to existing models. For example,
#' Some parsnip extension add engines to existing models. For example,
#' the \pkg{poissonreg} package adds additional engines for the [poisson_reg()]
#' model and these are not available unless \pkg{poissonreg} is loaded.
#' @param x The name of a `parsnip` model (e.g., "linear_reg", "mars", etc.)
#' @param x The name of a parsnip model (e.g., "linear_reg", "mars", etc.)
#' @return A tibble.
#'
#' @examplesIf !parsnip:::is_cran_check()
Expand Down
2 changes: 1 addition & 1 deletion R/extract.R
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@
#' importance/explainers.
#'
#' However, users should not invoke the `predict()` method on an extracted
#' model. There may be preprocessing operations that `parsnip` has executed on
#' model. There may be preprocessing operations that parsnip has executed on
#' the data prior to giving it to the model. Bypassing these can lead to errors
#' or silently generating incorrect predictions.
#'
Expand Down
4 changes: 2 additions & 2 deletions R/model_object_docs.R
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@
#' software will be used. It can be a package name or a technology
#' type.
#'
#' This class and structure is the basis for how \pkg{parsnip}
#' This class and structure is the basis for how parsnip
#' stores model objects prior to seeing the data.
#'
#' @section Argument Details:
Expand All @@ -53,7 +53,7 @@
#' arguments. For example, when calling `mean(dat_vec)`, the object
#' `dat_vec` is immediately evaluated inside of the function.
#'
#' `parsnip` model functions do not do this. For example, using
#' parsnip model functions do not do this. For example, using
#'
#'\preformatted{
#' rand_forest(mtry = ncol(mtcars) - 1)
Expand Down
6 changes: 3 additions & 3 deletions R/repair_call.R
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@
#'
#' `repair_call()` call can adjust the model objects call to be usable by other
#' functions and methods.
#' @param x A fitted `parsnip` model. An error will occur if the underlying model
#' @param x A fitted parsnip model. An error will occur if the underlying model
#' does not have a `call` element.
#' @param data A data object that is relevant to the call. In most cases, this
#' is the data frame that was given to `parsnip` for the model fit (i.e., the
#' is the data frame that was given to parsnip for the model fit (i.e., the
#' training set data). The name of this data object is inserted into the call.
#' @return A modified `parsnip` fitted model.
#' @examplesIf !parsnip:::is_cran_check()
Expand All @@ -21,7 +21,7 @@
#' fit(mpg ~ ., data = mtcars)
#'
#' # In this call, note that `data` is not `mtcars` and the `model = ~TRUE`
#' # indicates that the `model` argument is an `rlang` quosure.
#' # indicates that the `model` argument is an rlang quosure.
#' fitted_model$fit$call
#'
#' # All better:
Expand Down
4 changes: 2 additions & 2 deletions R/tidy_glmnet.R
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
#' tidy methods for glmnet models
#'
#' `tidy()` methods for the various `glmnet` models that return the coefficients
#' for the specific penalty value used by the `parsnip` model fit.
#' @param x A fitted `parsnip` model that used the `glmnet` engine.
#' for the specific penalty value used by the parsnip model fit.
#' @param x A fitted parsnip model that used the `glmnet` engine.
#' @param penalty A _single_ numeric value. If none is given, the value specified
#' in the model specification is used.
#' @param ... Not used
Expand Down
4 changes: 2 additions & 2 deletions R/tidy_liblinear.R
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
#' tidy methods for LiblineaR models
#'
#' `tidy()` methods for the various `LiblineaR` models that return the
#' coefficients from the `parsnip` model fit.
#' @param x A fitted `parsnip` model that used the `LiblineaR` engine.
#' coefficients from the parsnip model fit.
#' @param x A fitted parsnip model that used the `LiblineaR` engine.
#' @param ... Not used
#' @return A tibble with columns `term` and `estimate`.
#' @keywords internal
Expand Down
2 changes: 1 addition & 1 deletion R/translate.R
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@
#' the model fitting function/engine.
#'
#' This function can be useful when you need to understand how
#' `parsnip` goes from a generic model specific to a model fitting
#' parsnip goes from a generic model specific to a model fitting
#' function.
#'
#' **Note**: this function is used internally and users should only use it
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,8 +153,8 @@ rand_forest(mtry = 10, trees = 2000) %>%
#> Target node size: 5
#> Variable importance mode: impurity
#> Splitrule: variance
#> OOB prediction error (MSE): 5.976917
#> R squared (OOB): 0.8354559
#> OOB prediction error (MSE): 5.725636
#> R squared (OOB): 0.8423737
```

A list of all parsnip models across different CRAN packages can be found
Expand Down
2 changes: 1 addition & 1 deletion issue_template.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ name: Bug report or feature request
about: Describe a bug you've seen or make a case for a new feature
---

# PLEASE READ: Making a new issue for `parsnip`
# PLEASE READ: Making a new issue for parsnip


Please follow the template below.
Expand Down
2 changes: 1 addition & 1 deletion man/details_logistic_reg_gee.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/extract-parsnip.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions man/model_spec.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/parsnip_addin.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions man/repair_call.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

494 changes: 494 additions & 0 deletions man/rmd/logistic_reg_gee.html

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion man/rmd/logistic_reg_gee.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Both `gee:gee()` and `gee:geepack()` specify the id/cluster variable using an ar
gee(breaks ~ tension, id = wool, data = warpbreaks, corstr = "exchangeable")
```

With `parsnip`, we suggest using the formula method when fitting:
With parsnip, we suggest using the formula method when fitting:

```r
library(tidymodels)
Expand Down
2 changes: 1 addition & 1 deletion man/rmd/nearest-neighbor.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ nearest_neighbor() %>%
```

For `kknn`, the underlying modeling function used is a restricted version of
`train.kknn()` and not `kknn()`. It is set up in this way so that `parsnip` can
`train.kknn()` and not `kknn()`. It is set up in this way so that parsnip can
utilize the underlying `predict.train.kknn` method to predict on new data. This
also means that a single value of that function's `kernel` argument (a.k.a
`weight_func` here) can be supplied
Expand Down
2 changes: 1 addition & 1 deletion man/set_engine.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions man/set_new_model.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions man/show_engines.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions man/tidy._LiblineaR.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 2 additions & 2 deletions man/tidy._elnet.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/translate.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion vignettes/articles/Submodels.Rmd
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ theme_set(theme_bw())

Some R packages can create predictions from models that are different than the one that was fit. For example, if a boosted tree is fit with 10 iterations of boosting, the model can usually make predictions on _submodels_ that have less than 10 trees (all other parameters being static). This is helpful for model tuning since you can cheaply evaluate tuning parameter combinations which often results in a large speed-up in the computations.

In `parsnip`, there is a method called `multi_predict()` that can do this. It's current methods are:
In parsnip, there is a method called `multi_predict()` that can do this. It's current methods are:

```{r methods}
library(parsnip)
Expand Down
Loading
Loading