---
title: "Save and re-load models"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Save and re-load models}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
library(tidypredict)
```

`tidypredict` splits the translation process in two.  It first parses the model to extract the needed components to produce the prediction.  And second, it uses the object with the parsed information to produce the R formula. Thanks to this two step process, `tidypredict` does not need to parse the model every time.  `tidypredict`'s functions also accept models that have already been parsed.  Additionally, because the parsed model object is a list of basic variables, it is possible to save it in a file.  Currently, the best file format is YAML.

For this article, we will use the following model:

```{r}
model <- lm(mpg ~ (wt + disp) * cyl, data = mtcars)
```

## Parse model

The `parse_model()` function allows to run the first step manually.  It will return an R list object which contains all of the needed information to produce a prediction calculation.  The structure of the parsed model varies based on what kind of model is being processed.  In general, it is consistent in what kind of information it expects from each model type. For example, in the example the `lm()` model object will return variables such as `sigma2`,  which would not be used in other model types, such as decision trees.

```{r}
library(tidypredict)

parsed <- parse_model(model)
str(parsed, 2)
```

Usually, we pass an R model object to functions such as: `tidypredict_fit()`, and `tidypredict_sql()`.  These functions also accept a previously parsed model.

```{r}
tidypredict_fit(parsed)
```



```{r, include = FALSE}
model_file <- tempfile(fileext = ".yml")
tidypredict_save(parsed, model_file)
loaded_model <- tidypredict_load(model_file)
```

## Saving the model

Use `tidypredict_save()` to write the model to a YAML file.

```{r, eval = FALSE}
tidypredict_save(parsed, "my_model.yml")
```

It accepts a fitted model as well, parsing it for you:

```{r, eval = FALSE}
tidypredict_save(model, "my_model.yml")
```

Write the file with `tidypredict_save()` rather than calling `yaml::write_yaml()` yourself. `yaml` writes numbers with 7 significant digits by default, which is not enough to store a split threshold exactly. A tree model saved that way can send rows down a different branch than the model it came from, silently and with no warning.

## Re-load the model

In a new R session, read the file back with `tidypredict_load()`.

```{r, eval = FALSE}
library(tidypredict)

loaded_model <- tidypredict_load("my_model.yml")
```

The preview of the file looks exactly as the preview of the original parsed model.

```{r}
str(loaded_model, 2)
```

`tidypredict` is able to read the new R variable and use it to create the formula.

```{r}
tidypredict_fit(loaded_model)
```

The same variable can be used with other `tidypredict` functions, such as `tidypredict_sql()`

```{r}
tidypredict_sql(loaded_model, dbplyr::simulate_odbc())
```

## `broom`

The `parsed_model` object integrates with `tidy()` from `broom`.

```{r}
tidy(loaded_model)
```