-
Notifications
You must be signed in to change notification settings - Fork 12
/
Copy pathREADME.Rmd
139 lines (98 loc) · 5.54 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
# `devtools::build_readme()` evaluates in `callr:r_safe()` which causes issues
# with butcher's memory profiling. Neither RStudio's Knit button nor
# `rmarkdown::render()` have this issue (#280).
if (identical(Sys.getenv("CALLR_IS_RUNNING"), "true")) {
rlang::abort(c(
"Build this README with `rmarkdown::render()` rather than `devtools::build_readme()`.",
"See tidymodels/butcher#280 for more info."
))
}
```
# butcher <a href="https://butcher.tidymodels.org"><img src="man/figures/logo.png" align="right" height="138" alt="butcher website" /></a>
<!-- badges: start -->
[](https://github.com/tidymodels/butcher/actions/workflows/R-CMD-check.yaml)
[](https://CRAN.R-project.org/package=butcher)
[](https://app.codecov.io/gh/tidymodels/butcher?branch=main)
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
<!-- badges: end -->
## Overview
Modeling or machine learning in R can result in fitted model objects that take up too much memory. There are two main culprits:
1. Heavy usage of formulas and closures that capture the enclosing environment in model training
2. Lack of selectivity in the construction of the model object itself
As a result, fitted model objects contain components that are often redundant and not required for post-fit estimation activities. The butcher package provides tooling to "axe" parts of the fitted output that are no longer needed, without sacrificing prediction functionality from the original model object.
## Installation
Install the released version from CRAN:
```{r, eval = FALSE}
install.packages("butcher")
```
Or install the development version from [GitHub](https://github.com/):
```{r, eval = FALSE}
# install.packages("pak")
pak::pak("tidymodels/butcher")
```
## Butchering
As an example, let's wrap an `lm` model so it contains a lot of unnecessary stuff:
```{r example}
library(butcher)
our_model <- function() {
some_junk_in_the_environment <- runif(1e6) # we didn't know about
lm(mpg ~ ., data = mtcars)
}
```
This object is unnecessarily large:
```{r}
library(lobstr)
obj_size(our_model())
```
When, in fact, it should only be:
```{r}
small_lm <- lm(mpg ~ ., data = mtcars)
obj_size(small_lm)
```
To understand which part of our original model object is taking up the most memory, we leverage the `weigh()` function:
```{r}
big_lm <- our_model()
weigh(big_lm)
```
The problem here is in the `terms` component of our `big_lm`. Because of how `lm()` is implemented in the `stats` package, the environment in which our model was made is carried along in the fitted output. To remove the (mostly) extraneous component, we can use `butcher()`:
```{r}
cleaned_lm <- butcher(big_lm, verbose = TRUE)
```
Comparing it against our `small_lm`, we find:
```{r}
weigh(cleaned_lm)
```
And now it will take up about the same memory on disk as `small_lm`:
```{r}
weigh(small_lm)
```
To make the most of your memory available, this package provides five S3 generics for you to remove parts of a model object:
- `axe_call()`: To remove the call object.
- `axe_ctrl()`: To remove controls associated with training.
- `axe_data()`: To remove the original training data.
- `axe_env()`: To remove environments.
- `axe_fitted()`: To remove fitted values.
When you run `butcher()`, you execute all of these axing functions at once. Any kind of axing on the object will append a butchered class to the current model object class(es) as well as a new attribute named `butcher_disabled` that lists any post-fit estimation functions that are disabled as a result.
## Model Object Coverage
Check out the `vignette("available-axe-methods")` to see butcher's current coverage. If you are working with a new model object that could benefit from any kind of axing, we would love for you to make a pull request! You can visit the `vignette("adding-models-to-butcher")` for more guidelines, but in short, to contribute a set of axe methods:
1. Run `new_model_butcher(model_class = "your_object", package_name = "your_package")`
2. Use butcher helper functions `weigh()` and `locate()` to decide what to axe
3. Finalize edits to `R/your_object.R` and `tests/testthat/test-your_object.R`
4. Make a pull request!
## Contributing
This project is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.
- For questions and discussions about tidymodels packages, modeling, and machine learning, please [post on RStudio Community](https://forum.posit.co/new-topic?category_id=15&tags=tidymodels,question).
- If you think you have encountered a bug, please [submit an issue](https://github.com/tidymodels/butcher/issues).
- Either way, learn how to create and share a [reprex](https://reprex.tidyverse.org/articles/articles/learn-reprex.html) (a minimal, reproducible example), to clearly communicate about your code.
- Check out further details on [contributing guidelines for tidymodels packages](https://www.tidymodels.org/contribute/) and [how to get help](https://www.tidymodels.org/help/).