Introduction to broom

library(knitr)
opts_chunk$set(warning = FALSE, message = FALSE)

broom: let's tidy up a bit

The broom package takes the messy output of built-in functions in R, such as lm, nls, or t.test, and turns them into tidy tibbles.

The concept of "tidy data", as introduced by Hadley Wickham, offers a powerful framework for data manipulation and analysis. That paper makes a convincing statement of the problem this package tries to solve (emphasis mine):

While model inputs usually require tidy inputs, such attention to detail doesn't carry over to model outputs. Outputs such as predictions and estimated coefficients aren't always tidy. This makes it more difficult to combine results from multiple models. For example, in R, the default representation of model coefficients is not tidy because it does not have an explicit variable that records the variable name for each estimate, they are instead recorded as row names. In R, row names must be unique, so combining coefficients from many models (e.g., from bootstrap resamples, or subgroups) requires workarounds to avoid losing important information. This knocks you out of the flow of analysis and makes it harder to combine the results from multiple models. I'm not currently aware of any packages that resolve this problem.

broom is an attempt to bridge the gap from untidy outputs of predictions and estimations to the tidy data we want to work with. It centers around three S3 methods, each of which take common objects produced by R statistical functions (lm, t.test, nls, etc) and convert them into a tibble. broom is particularly designed to work with Hadley's dplyr package (see the broom+dplyr vignette for more).

broom should be distinguished from packages like reshape2 and tidyr, which rearrange and reshape data frames into different forms. Those packages perform critical tasks in tidy data analysis but focus on manipulating data frames in one specific format into another. In contrast, broom is designed to take format that is not in a tabular data format (sometimes not anywhere close) and convert it to a tidy tibble.

Tidying model outputs is not an exact science, and it's based on a judgment of the kinds of values a data scientist typically wants out of a tidy analysis (for instance, estimates, test statistics, and p-values). You may lose some of the information in the original object that you wanted, or keep more information than you need. If you think the tidy output for a model should be changed, or if you're missing a tidying function for an S3 class that you'd like, I strongly encourage you to open an issue or a pull request.

Tidying functions

This package provides three S3 methods that do three distinct kinds of tidying.

Note that some classes may have only one or two of these methods defined.

Consider as an illustrative example a linear fit on the built-in mtcars dataset.

lmfit <- lm(mpg ~ wt, mtcars)
lmfit
summary(lmfit)

This summary output is useful enough if you just want to read it. However, converting it to tabular data that contains all the same information, so that you can combine it with other models or do further analysis, is not trivial. You have to do coef(summary(lmfit)) to get a matrix of coefficients, the terms are still stored in row names, and the column names are inconsistent with other packages (e.g. Pr(>|t|) compared to p.value).

Instead, you can use the tidy function, from the broom package, on the fit:

library(broom)
tidy(lmfit)

This gives you a tabular data representation. Note that the row names have been moved into a column called term, and the column names are simple and consistent (and can be accessed using $).

Instead of viewing the coefficients, you might be interested in the fitted values and residuals for each of the original points in the regression. For this, use augment, which augments the original data with information from the model:

augment(lmfit)

Note that each of the new columns begins with a . (to avoid overwriting any of the original columns).

Finally, several summary statistics are computed for the entire regression, such as R^2 and the F-statistic. These can be accessed with the glance function:

glance(lmfit)

This distinction between the tidy, augment and glance functions is explored in a different context in the k-means vignette.

Other Examples

Generalized linear and non-linear models

These functions apply equally well to the output from glm:

glmfit <- glm(am ~ wt, mtcars, family = "binomial")
tidy(glmfit)
augment(glmfit)
glance(glmfit)

Note that the statistics computed by glance are different for glm objects than for lm (e.g. deviance rather than R^2):

These functions also work on other fits, such as nonlinear models (nls):

nlsfit <- nls(mpg ~ k / wt + b, mtcars, start = list(k = 1, b = 0))
tidy(nlsfit)
augment(nlsfit, mtcars)
glance(nlsfit)

Hypothesis testing

The tidy function can also be applied to htest objects, such as those output by popular built-in functions like t.test, cor.test, and wilcox.test.

tt <- t.test(wt ~ am, mtcars)
tidy(tt)

Some cases might have fewer columns (for example, no confidence interval):

wt <- wilcox.test(wt ~ am, mtcars)
tidy(wt)

Since the tidy output is already only one row, glance returns the same output:

glance(tt)
glance(wt)

augment method is defined only for chi-squared tests, since there is no meaningful sense, for other tests, in which a hypothesis test produces output about each initial data point.

chit <- chisq.test(xtabs(Freq ~ Sex + Class,
  data = as.data.frame(Titanic)
))
tidy(chit)
augment(chit)

Conventions

In order to maintain consistency, we attempt to follow some conventions regarding the structure of returned data.

All functions

tidy functions

augment functions

glance functions



Try the broom package in your browser

Any scripts or data that you put into this service are public.

broom documentation built on July 9, 2023, 5:28 p.m.