README.md
1
2<!-- README.md is generated from README.Rmd. Please edit that file -->
3
4# broom <img src="man/figures/logo.png" align="right" width="100" />
5
6<!-- badges: start -->
7
8[](https://github.com/tidymodels/broom)
10[](https://codecov.io/github/tidymodels/broom?branch=master)
12[](https://CRAN.R-project.org/package=broom)
14[](https://CRAN.R-project.org/package=broom)
15<!-- badges: end -->
16
17## Overview
18
19`broom` summarizes key information about models in tidy `tibble()`s.
20`broom` provides three verbs to make it convenient to interact with
21model objects:
22
23 - `tidy()` summarizes information about model components
24 - `glance()` reports information about the entire model
25 - `augment()` adds informations about observations to a dataset
26
27For a detailed introduction, please see `vignette("broom")`.
28
29`broom` tidies 100+ models from popular modelling packages and almost
30all of the model objects in the `stats` package that comes with base R.
31`vignette("available-methods")` lists method availability.
32
33If you aren’t familiar with tidy data structures and want to know how
34they can make your life easier, we highly recommend reading Hadley
35Wickham’s [Tidy Data](https://www.jstatsoft.org/v59/i10).
36
37## Installation
38
39``` r
40# we recommend installing the entire tidyverse
41# modeling set, which includes broom:
42install.packages("tidymodels")
43
44# alternatively, to install just broom:
45install.packages("broom")
46
47# to get the development version from GitHub:
48install.packages("devtools")
49devtools::install_github("tidymodels/broom")
50```
51
52If you find a bug, please file a minimal reproducible example in the
53[issues](https://github.com/tidymodels/broom/issues).
54
55## Usage
56
57`tidy()` produces a `tibble()` where each row contains information about
58an important component of the model. For regression models, this often
59corresponds to regression coefficients. This is can be useful if you
60want to inspect a model or create custom visualizations.
61
62``` r
63library(broom)
64
65fit <- lm(Volume ~ Girth + Height, trees)
66tidy(fit)
67#> # A tibble: 3 x 5
68#> term estimate std.error statistic p.value
69#> <chr> <dbl> <dbl> <dbl> <dbl>
70#> 1 (Intercept) -58.0 8.64 -6.71 2.75e- 7
71#> 2 Girth 4.71 0.264 17.8 8.22e-17
72#> 3 Height 0.339 0.130 2.61 1.45e- 2
73```
74
75`glance()` returns a tibble with exactly one row of goodness of fitness
76measures and related statistics. This is useful to check for model
77misspecification and to compare many models.
78
79``` r
80glance(fit)
81#> # A tibble: 1 x 12
82#> r.squared adj.r.squared sigma statistic p.value df logLik AIC BIC
83#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
84#> 1 0.948 0.944 3.88 255. 1.07e-18 2 -84.5 177. 183.
85#> # … with 3 more variables: deviance <dbl>, df.residual <int>, nobs <int>
86```
87
88`augment` adds columns to a dataset, containing information such as
89fitted values, residuals or cluster assignments. All columns added to a
90dataset have `.` prefix to prevent existing columns from being
91overwritten.
92
93``` r
94augment(fit, data = trees)
95#> # A tibble: 31 x 9
96#> Girth Height Volume .fitted .resid .std.resid .hat .sigma .cooksd
97#> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl>
98#> 1 8.3 70 10.3 4.84 5.46 1.50 0.116 3.79 0.0978
99#> 2 8.6 65 10.3 4.55 5.75 1.60 0.147 3.77 0.148
100#> 3 8.8 63 10.2 4.82 5.38 1.53 0.177 3.78 0.167
101#> 4 10.5 72 16.4 15.9 0.526 0.140 0.0592 3.95 0.000409
102#> 5 10.7 81 18.8 19.9 -1.07 -0.294 0.121 3.95 0.00394
103#> 6 10.8 83 19.7 21.0 -1.32 -0.370 0.156 3.94 0.00840
104#> 7 11 66 15.6 16.2 -0.593 -0.162 0.115 3.95 0.00114
105#> 8 11 75 18.2 19.2 -1.05 -0.277 0.0515 3.95 0.00138
106#> 9 11.1 80 22.6 21.4 1.19 0.321 0.0920 3.95 0.00348
107#> 10 11.2 75 19.9 20.2 -0.288 -0.0759 0.0480 3.95 0.0000968
108#> # … with 21 more rows
109```
110
111### Contributing
112
113We welcome contributions of all types\!
114
115For questions and discussions about tidymodels packages, modeling, and
116machine learning, please [post on RStudio
117Community](https://community.rstudio.com/new-topic?category_id=15https://rstd.io/tidymodels-communitytags=tidymodels,question). If you think you have
118encountered a bug, please [submit an
119issue](https://github.com/tidymodels/broom/issues). Either way, learn
120how to create and share a [reprex](https://reprex.tidyverse.org/articles/articles/learn-reprex.html) (a minimal,
121reproducible example), to clearly communicate about your code. Check out
122further details on [contributing guidelines for tidymodels
123packages](https://www.tidymodels.org/contribute/) and [how to get
124help](https://www.tidymodels.org/help/).
125
126If you have never directly contributed to an R package before, `broom`
127is an excellent place to start. Find an
128[issue](https://github.com/tidymodels/broom/issues/) with the **Beginner
129Friendly** tag and comment that you’d like to take it on and we’ll help
130you get started.
131
132Generally, too, we encourage typo corrections, bug reports, bug fixes
133and feature requests. Feedback on the clarity of the documentation is
134especially valuable\!
135
136If you are interested in adding tidier methods for new model objects,
137please read [this
138article](https://www.tidymodels.org/learn/develop/broom/) on the
139tidymodels website.
140
141We have a [Contributor Code of
142Conduct](https://github.com/tidymodels/broom/blob/master/.github/CODE_OF_CONDUCT.md).
143By participating in `broom` you agree to abide by its terms.
144
){kind=link}
){kind=link}