add_formula()specifies the terms of the model through the usage of a formula.remove_formula()removes the formula as well as any downstream objects that might get created after the formula is used for preprocessing, such as terms. Additionally, if the model has already been fit, then the fit is removed.update_formula()first removes the formula, then replaces the previous formula with the new one. Any model that has already been fit based on this formula will need to be refit.
Usage
add_formula(x, formula, ..., blueprint = NULL)
remove_formula(x)
update_formula(x, formula, ..., blueprint = NULL)Arguments
- x
A workflow
- formula
A formula specifying the terms of the model. It is advised to not do preprocessing in the formula, and instead use a recipe if that is required.
- ...
Not used.
- blueprint
A hardhat blueprint used for fine tuning the preprocessing.
If
NULL,hardhat::default_formula_blueprint()is used and is passed arguments that best align with the model present in the workflow.Note that preprocessing done here is separate from preprocessing that might be done by the underlying model. For example, if a blueprint with
indicators = "none"is specified, no dummy variables will be created by hardhat, but if the underlying model requires a formula interface that internally usesstats::model.matrix(), factors will still be expanded to dummy variables by the model.
Details
To fit a workflow, exactly one of add_formula(), add_recipe(), or
add_variables() must be specified.
Formula Handling
Note that, for different models, the formula given to add_formula()
might be handled in different ways, depending on the parsnip model being
used. For example, a random forest model fit using ranger would not
convert any factor predictors to binary indicator variables. This is
consistent with what ranger::ranger() would do, but is inconsistent
with what stats::model.matrix() would do.
The documentation for parsnip models provides details about how the data
given in the formula are encoded for the model if they diverge from the
standard model.matrix() methodology. Our goal is to be consistent with
how the underlying model package works.
How is this formula used?
To demonstrate, the example below uses lm() to fit a model. The
formula given to add_formula() is used to create the model matrix and
that is what is passed to lm() with a simple formula of
body_mass_g ~ .:
library(parsnip)
library(workflows)
library(magrittr)
library(modeldata)
library(hardhat)
data(penguins)
lm_mod <- linear_reg() %>%
set_engine("lm")
lm_wflow <- workflow() %>%
add_model(lm_mod)
pre_encoded <- lm_wflow %>%
add_formula(body_mass_g ~ species + island + bill_depth_mm) %>%
fit(data = penguins)
pre_encoded_parsnip_fit <- pre_encoded %>%
extract_fit_parsnip()
pre_encoded_fit <- pre_encoded_parsnip_fit$fit
# The `lm()` formula is *not* the same as the `add_formula()` formula:
pre_encoded_fit##
## Call:
## stats::lm(formula = ..y ~ ., data = data)
##
## Coefficients:
## (Intercept) speciesChinstrap speciesGentoo
## -1009.943 1.328 2236.865
## islandDream islandTorgersen bill_depth_mm
## 9.221 -18.433 256.913This can affect how the results are analyzed. For example, to get sequential hypothesis tests, each individual term is tested:
anova(pre_encoded_fit)## Analysis of Variance Table
##
## Response: ..y
## Df Sum Sq Mean Sq F value Pr(>F)
## speciesChinstrap 1 18642821 18642821 141.1482 <2e-16 ***
## speciesGentoo 1 128221393 128221393 970.7875 <2e-16 ***
## islandDream 1 13399 13399 0.1014 0.7503
## islandTorgersen 1 255 255 0.0019 0.9650
## bill_depth_mm 1 28051023 28051023 212.3794 <2e-16 ***
## Residuals 336 44378805 132080
## ---
## Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1Overriding the default encodings
Users can override the model-specific encodings by using a hardhat blueprint. The blueprint can specify how factors are encoded and whether intercepts are included. As an example, if you use a formula and would like the data to be passed to a model untouched:
minimal <- default_formula_blueprint(indicators = "none", intercept = FALSE)
un_encoded <- lm_wflow %>%
add_formula(
body_mass_g ~ species + island + bill_depth_mm,
blueprint = minimal
) %>%
fit(data = penguins)
un_encoded_parsnip_fit <- un_encoded %>%
extract_fit_parsnip()
un_encoded_fit <- un_encoded_parsnip_fit$fit
un_encoded_fit##
## Call:
## stats::lm(formula = ..y ~ ., data = data)
##
## Coefficients:
## (Intercept) bill_depth_mm speciesChinstrap
## -1009.943 256.913 1.328
## speciesGentoo islandDream islandTorgersen
## 2236.865 9.221 -18.433While this looks the same, the raw columns were given to lm() and that
function created the dummy variables. Because of this, the sequential
ANOVA tests groups of parameters to get column-level p-values:
anova(un_encoded_fit)## Analysis of Variance Table
##
## Response: ..y
## Df Sum Sq Mean Sq F value Pr(>F)
## bill_depth_mm 1 48840779 48840779 369.782 <2e-16 ***
## species 2 126067249 63033624 477.239 <2e-16 ***
## island 2 20864 10432 0.079 0.9241
## Residuals 336 44378805 132080
## ---
## Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1Overriding the default model formula
Additionally, the formula passed to the underlying model can also be
customized. In this case, the formula argument of add_model() can be
used. To demonstrate, a spline function will be used for the bill depth:
library(splines)
custom_formula <- workflow() %>%
add_model(
lm_mod,
formula = body_mass_g ~ species + island + ns(bill_depth_mm, 3)
) %>%
add_formula(
body_mass_g ~ species + island + bill_depth_mm,
blueprint = minimal
) %>%
fit(data = penguins)
custom_parsnip_fit <- custom_formula %>%
extract_fit_parsnip()
custom_fit <- custom_parsnip_fit$fit
custom_fit##
## Call:
## stats::lm(formula = body_mass_g ~ species + island + ns(bill_depth_mm,
## 3), data = data)
##
## Coefficients:
## (Intercept) speciesChinstrap speciesGentoo
## 1959.090 8.534 2352.137
## islandDream islandTorgersen ns(bill_depth_mm, 3)1
## 2.425 -12.002 1476.386
## ns(bill_depth_mm, 3)2 ns(bill_depth_mm, 3)3
## 3187.839 1686.996Altering the formula
Finally, when a formula is updated or removed from a fitted workflow, the corresponding model fit is removed.
custom_formula_no_fit <- update_formula(custom_formula, body_mass_g ~ species)
try(extract_fit_parsnip(custom_formula_no_fit))## Error in extract_fit_parsnip(custom_formula_no_fit) :
## Can't extract a model fit from an untrained workflow.
## i Do you need to call `fit()`?Examples
workflow <- workflow()
workflow <- add_formula(workflow, mpg ~ cyl)
workflow
#> ══ Workflow ══════════════════════════════════════════════════════════════
#> Preprocessor: Formula
#> Model: None
#>
#> ── Preprocessor ──────────────────────────────────────────────────────────
#> mpg ~ cyl
remove_formula(workflow)
#> ══ Workflow ══════════════════════════════════════════════════════════════
#> Preprocessor: None
#> Model: None
update_formula(workflow, mpg ~ disp)
#> ══ Workflow ══════════════════════════════════════════════════════════════
#> Preprocessor: Formula
#> Model: None
#>
#> ── Preprocessor ──────────────────────────────────────────────────────────
#> mpg ~ disp