EVOLUTION-MANAGER
Edit File: broom.html
<!DOCTYPE html> <html> <head> <meta charset="utf-8" /> <meta name="generator" content="pandoc" /> <meta http-equiv="X-UA-Compatible" content="IE=EDGE" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="date" content="2020-06-25" /> <title>Introduction to broom</title> <script>// Hide empty <a> tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) --> // v0.0.1 // Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020. document.addEventListener('DOMContentLoaded', function() { const codeList = document.getElementsByClassName("sourceCode"); for (var i = 0; i < codeList.length; i++) { var linkList = codeList[i].getElementsByTagName('a'); for (var j = 0; j < linkList.length; j++) { if (linkList[j].innerHTML === "") { linkList[j].setAttribute('aria-hidden', 'true'); } } } }); </script> <style type="text/css">code{white-space: pre;}</style> <style type="text/css" data-origin="pandoc"> code.sourceCode > span { display: inline-block; line-height: 1.25; } code.sourceCode > span { color: inherit; text-decoration: inherit; } code.sourceCode > span:empty { height: 1.2em; } .sourceCode { overflow: visible; } code.sourceCode { white-space: pre; position: relative; } div.sourceCode { margin: 1em 0; } pre.sourceCode { margin: 0; } @media screen { div.sourceCode { overflow: auto; } } @media print { code.sourceCode { white-space: pre-wrap; } code.sourceCode > span { text-indent: -5em; padding-left: 5em; } } pre.numberSource code { counter-reset: source-line 0; } pre.numberSource code > span { position: relative; left: -4em; counter-increment: source-line; } pre.numberSource code > span > a:first-child::before { content: counter(source-line); position: relative; left: -1em; text-align: right; vertical-align: baseline; border: none; display: inline-block; -webkit-touch-callout: none; -webkit-user-select: none; -khtml-user-select: none; -moz-user-select: none; -ms-user-select: none; user-select: none; padding: 0 4px; width: 4em; color: #aaaaaa; } pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; } div.sourceCode { } @media screen { code.sourceCode > span > a:first-child::before { text-decoration: underline; } } code span.al { color: #ff0000; font-weight: bold; } /* Alert */ code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ code span.at { color: #7d9029; } /* Attribute */ code span.bn { color: #40a070; } /* BaseN */ code span.bu { } /* BuiltIn */ code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ code span.ch { color: #4070a0; } /* Char */ code span.cn { color: #880000; } /* Constant */ code span.co { color: #60a0b0; font-style: italic; } /* Comment */ code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ code span.do { color: #ba2121; font-style: italic; } /* Documentation */ code span.dt { color: #902000; } /* DataType */ code span.dv { color: #40a070; } /* DecVal */ code span.er { color: #ff0000; font-weight: bold; } /* Error */ code span.ex { } /* Extension */ code span.fl { color: #40a070; } /* Float */ code span.fu { color: #06287e; } /* Function */ code span.im { } /* Import */ code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ code span.kw { color: #007020; font-weight: bold; } /* Keyword */ code span.op { color: #666666; } /* Operator */ code span.ot { color: #007020; } /* Other */ code span.pp { color: #bc7a00; } /* Preprocessor */ code span.sc { color: #4070a0; } /* SpecialChar */ code span.ss { color: #bb6688; } /* SpecialString */ code span.st { color: #4070a0; } /* String */ code span.va { color: #19177c; } /* Variable */ code span.vs { color: #4070a0; } /* VerbatimString */ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ </style> <script> // apply pandoc div.sourceCode style to pre.sourceCode instead (function() { var sheets = document.styleSheets; for (var i = 0; i < sheets.length; i++) { if (sheets[i].ownerNode.dataset["origin"] !== "pandoc") continue; try { var rules = sheets[i].cssRules; } catch (e) { continue; } for (var j = 0; j < rules.length; j++) { var rule = rules[j]; // check if there is a div.sourceCode rule if (rule.type !== rule.STYLE_RULE || rule.selectorText !== "div.sourceCode") continue; var style = rule.style.cssText; // check if color or background-color is set if (rule.style.color === '' && rule.style.backgroundColor === '') continue; // replace div.sourceCode by a pre.sourceCode rule sheets[i].deleteRule(j); sheets[i].insertRule('pre.sourceCode{' + style + '}', j); } } })(); </script> <style type="text/css">body { background-color: #fff; margin: 1em auto; max-width: 700px; overflow: visible; padding-left: 2em; padding-right: 2em; font-family: "Open Sans", "Helvetica Neue", Helvetica, Arial, sans-serif; font-size: 14px; line-height: 1.35; } #TOC { clear: both; margin: 0 0 10px 10px; padding: 4px; width: 400px; border: 1px solid #CCCCCC; border-radius: 5px; background-color: #f6f6f6; font-size: 13px; line-height: 1.3; } #TOC .toctitle { font-weight: bold; font-size: 15px; margin-left: 5px; } #TOC ul { padding-left: 40px; margin-left: -1.5em; margin-top: 5px; margin-bottom: 5px; } #TOC ul ul { margin-left: -2em; } #TOC li { line-height: 16px; } table { margin: 1em auto; border-width: 1px; border-color: #DDDDDD; border-style: outset; border-collapse: collapse; } table th { border-width: 2px; padding: 5px; border-style: inset; } table td { border-width: 1px; border-style: inset; line-height: 18px; padding: 5px 5px; } table, table th, table td { border-left-style: none; border-right-style: none; } table thead, table tr.even { background-color: #f7f7f7; } p { margin: 0.5em 0; } blockquote { background-color: #f6f6f6; padding: 0.25em 0.75em; } hr { border-style: solid; border: none; border-top: 1px solid #777; margin: 28px 0; } dl { margin-left: 0; } dl dd { margin-bottom: 13px; margin-left: 13px; } dl dt { font-weight: bold; } ul { margin-top: 0; } ul li { list-style: circle outside; } ul ul { margin-bottom: 0; } pre, code { background-color: #f7f7f7; border-radius: 3px; color: #333; white-space: pre-wrap; } pre { border-radius: 3px; margin: 5px 0px 10px 0px; padding: 10px; } pre:not([class]) { background-color: #f7f7f7; } code { font-family: Consolas, Monaco, 'Courier New', monospace; font-size: 85%; } p > code, li > code { padding: 2px 0px; } div.figure { text-align: center; } img { background-color: #FFFFFF; padding: 2px; border: 1px solid #DDDDDD; border-radius: 3px; border: 1px solid #CCCCCC; margin: 0 5px; } h1 { margin-top: 0; font-size: 35px; line-height: 40px; } h2 { border-bottom: 4px solid #f7f7f7; padding-top: 10px; padding-bottom: 2px; font-size: 145%; } h3 { border-bottom: 2px solid #f7f7f7; padding-top: 10px; font-size: 120%; } h4 { border-bottom: 1px solid #f7f7f7; margin-left: 8px; font-size: 105%; } h5, h6 { border-bottom: 1px solid #ccc; font-size: 105%; } a { color: #0033dd; text-decoration: none; } a:hover { color: #6666ff; } a:visited { color: #800080; } a:visited:hover { color: #BB00BB; } a[href^="http:"] { text-decoration: underline; } a[href^="https:"] { text-decoration: underline; } code > span.kw { color: #555; font-weight: bold; } code > span.dt { color: #902000; } code > span.dv { color: #40a070; } code > span.bn { color: #d14; } code > span.fl { color: #d14; } code > span.ch { color: #d14; } code > span.st { color: #d14; } code > span.co { color: #888888; font-style: italic; } code > span.ot { color: #007020; } code > span.al { color: #ff0000; font-weight: bold; } code > span.fu { color: #900; font-weight: bold; } code > span.er { color: #a61717; background-color: #e3d2d2; } </style> </head> <body> <h1 class="title toc-ignore">Introduction to broom</h1> <h4 class="date">2020-06-25</h4> <div id="broom-lets-tidy-up-a-bit" class="section level1"> <h1>broom: let’s tidy up a bit</h1> <p>The broom package takes the messy output of built-in functions in R, such as <code>lm</code>, <code>nls</code>, or <code>t.test</code>, and turns them into tidy tibbles.</p> <p>The concept of “tidy data”, <a href="http://www.jstatsoft.org/v59/i10">as introduced by Hadley Wickham</a>, 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):</p> <blockquote> <p><strong>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.</strong> 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. <strong>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.</strong></p> </blockquote> <p>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 (<code>lm</code>, <code>t.test</code>, <code>nls</code>, etc) and convert them into a tibble. broom is particularly designed to work with Hadley’s <a href="https://github.com/tidyverse/dplyr">dplyr</a> package (see the <a href="broom_and_dplyr.html">broom+dplyr</a> vignette for more).</p> <p>broom should be distinguished from packages like <a href="https://CRAN.R-project.org/package=reshape2">reshape2</a> and <a href="https://github.com/tidyverse/tidyr">tidyr</a>, 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 <em>not</em> in a tabular data format (sometimes not anywhere close) and convert it to a tidy tibble.</p> <p>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 <a href="http://github.com/tidymodels/broom/issues">open an issue</a> or a pull request.</p> <div id="tidying-functions" class="section level2"> <h2>Tidying functions</h2> <p>This package provides three S3 methods that do three distinct kinds of tidying.</p> <ul> <li><code>tidy</code>: constructs a tibble that summarizes the model’s statistical findings. This includes coefficients and p-values for each term in a regression, per-cluster information in clustering applications, or per-test information for <code>multtest</code> functions.</li> <li><code>augment</code>: add columns to the original data that was modeled. This includes predictions, residuals, and cluster assignments.</li> <li><code>glance</code>: construct a concise <em>one-row</em> summary of the model. This typically contains values such as R^2, adjusted R^2, and residual standard error that are computed once for the entire model.</li> </ul> <p>Note that some classes may have only one or two of these methods defined.</p> <p>Consider as an illustrative example a linear fit on the built-in <code>mtcars</code> dataset.</p> <div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb1-1"><a href="#cb1-1"></a>lmfit <-<span class="st"> </span><span class="kw">lm</span>(mpg <span class="op">~</span><span class="st"> </span>wt, mtcars)</span> <span id="cb1-2"><a href="#cb1-2"></a>lmfit</span></code></pre></div> <pre><code>## ## Call: ## lm(formula = mpg ~ wt, data = mtcars) ## ## Coefficients: ## (Intercept) wt ## 37.285 -5.344</code></pre> <div class="sourceCode" id="cb3"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb3-1"><a href="#cb3-1"></a><span class="kw">summary</span>(lmfit)</span></code></pre></div> <pre><code>## ## Call: ## lm(formula = mpg ~ wt, data = mtcars) ## ## Residuals: ## Min 1Q Median 3Q Max ## -4.5432 -2.3647 -0.1252 1.4096 6.8727 ## ## Coefficients: ## Estimate Std. Error t value Pr(>|t|) ## (Intercept) 37.2851 1.8776 19.858 < 2e-16 *** ## wt -5.3445 0.5591 -9.559 1.29e-10 *** ## --- ## Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1 ## ## Residual standard error: 3.046 on 30 degrees of freedom ## Multiple R-squared: 0.7528, Adjusted R-squared: 0.7446 ## F-statistic: 91.38 on 1 and 30 DF, p-value: 1.294e-10</code></pre> <p>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 <code>coef(summary(lmfit))</code> 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. <code>Pr(>|t|)</code> compared to <code>p.value</code>).</p> <p>Instead, you can use the <code>tidy</code> function, from the broom package, on the fit:</p> <div class="sourceCode" id="cb5"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb5-1"><a href="#cb5-1"></a><span class="kw">library</span>(broom)</span> <span id="cb5-2"><a href="#cb5-2"></a><span class="kw">tidy</span>(lmfit)</span></code></pre></div> <pre><code>## # A tibble: 2 x 5 ## term estimate std.error statistic p.value ## <chr> <dbl> <dbl> <dbl> <dbl> ## 1 (Intercept) 37.3 1.88 19.9 8.24e-19 ## 2 wt -5.34 0.559 -9.56 1.29e-10</code></pre> <p>This gives you a tabular data representation. Note that the row names have been moved into a column called <code>term</code>, and the column names are simple and consistent (and can be accessed using <code>$</code>).</p> <p>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 <code>augment</code>, which augments the original data with information from the model:</p> <div class="sourceCode" id="cb7"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb7-1"><a href="#cb7-1"></a><span class="kw">augment</span>(lmfit)</span></code></pre></div> <pre><code>## # A tibble: 32 x 9 ## .rownames mpg wt .fitted .resid .std.resid .hat .sigma .cooksd ## <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> ## 1 Mazda RX4 21 2.62 23.3 -2.28 -0.766 0.0433 3.07 1.33e-2 ## 2 Mazda RX4 Wag 21 2.88 21.9 -0.920 -0.307 0.0352 3.09 1.72e-3 ## 3 Datsun 710 22.8 2.32 24.9 -2.09 -0.706 0.0584 3.07 1.54e-2 ## 4 Hornet 4 Drive 21.4 3.22 20.1 1.30 0.433 0.0313 3.09 3.02e-3 ## 5 Hornet Sportabo… 18.7 3.44 18.9 -0.200 -0.0668 0.0329 3.10 7.60e-5 ## 6 Valiant 18.1 3.46 18.8 -0.693 -0.231 0.0332 3.10 9.21e-4 ## 7 Duster 360 14.3 3.57 18.2 -3.91 -1.31 0.0354 3.01 3.13e-2 ## 8 Merc 240D 24.4 3.19 20.2 4.16 1.39 0.0313 3.00 3.11e-2 ## 9 Merc 230 22.8 3.15 20.5 2.35 0.784 0.0314 3.07 9.96e-3 ## 10 Merc 280 19.2 3.44 18.9 0.300 0.100 0.0329 3.10 1.71e-4 ## # … with 22 more rows</code></pre> <p>Note that each of the new columns begins with a <code>.</code> (to avoid overwriting any of the original columns).</p> <p>Finally, several summary statistics are computed for the entire regression, such as R^2 and the F-statistic. These can be accessed with the <code>glance</code> function:</p> <div class="sourceCode" id="cb9"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb9-1"><a href="#cb9-1"></a><span class="kw">glance</span>(lmfit)</span></code></pre></div> <pre><code>## # A tibble: 1 x 12 ## r.squared adj.r.squared sigma statistic p.value df logLik AIC BIC ## <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> ## 1 0.753 0.745 3.05 91.4 1.29e-10 1 -80.0 166. 170. ## # … with 3 more variables: deviance <dbl>, df.residual <int>, nobs <int></code></pre> <p>This distinction between the <code>tidy</code>, <code>augment</code> and <code>glance</code> functions is explored in a different context in the <a href="https://www.tidymodels.org/learn/statistics/k-means/">k-means vignette</a>.</p> </div> <div id="other-examples" class="section level2"> <h2>Other Examples</h2> <div id="generalized-linear-and-non-linear-models" class="section level3"> <h3>Generalized linear and non-linear models</h3> <p>These functions apply equally well to the output from <code>glm</code>:</p> <div class="sourceCode" id="cb11"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb11-1"><a href="#cb11-1"></a>glmfit <-<span class="st"> </span><span class="kw">glm</span>(am <span class="op">~</span><span class="st"> </span>wt, mtcars, <span class="dt">family =</span> <span class="st">"binomial"</span>)</span> <span id="cb11-2"><a href="#cb11-2"></a><span class="kw">tidy</span>(glmfit)</span></code></pre></div> <pre><code>## # A tibble: 2 x 5 ## term estimate std.error statistic p.value ## <chr> <dbl> <dbl> <dbl> <dbl> ## 1 (Intercept) 12.0 4.51 2.67 0.00759 ## 2 wt -4.02 1.44 -2.80 0.00509</code></pre> <div class="sourceCode" id="cb13"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb13-1"><a href="#cb13-1"></a><span class="kw">augment</span>(glmfit)</span></code></pre></div> <pre><code>## # A tibble: 32 x 9 ## .rownames am wt .fitted .resid .std.resid .hat .sigma .cooksd ## <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> ## 1 Mazda RX4 1 2.62 1.50 0.635 0.680 0.126 0.803 0.0184 ## 2 Mazda RX4 Wag 1 2.88 0.471 0.985 1.04 0.108 0.790 0.0424 ## 3 Datsun 710 1 2.32 2.70 0.360 0.379 0.0963 0.810 0.00394 ## 4 Hornet 4 Drive 0 3.22 -0.897 -0.827 -0.860 0.0744 0.797 0.0177 ## 5 Hornet Sportabout 0 3.44 -1.80 -0.553 -0.572 0.0681 0.806 0.00647 ## 6 Valiant 0 3.46 -1.88 -0.532 -0.551 0.0674 0.807 0.00590 ## 7 Duster 360 0 3.57 -2.33 -0.432 -0.446 0.0625 0.809 0.00348 ## 8 Merc 240D 0 3.19 -0.796 -0.863 -0.897 0.0755 0.796 0.0199 ## 9 Merc 230 0 3.15 -0.635 -0.922 -0.960 0.0776 0.793 0.0242 ## 10 Merc 280 0 3.44 -1.80 -0.553 -0.572 0.0681 0.806 0.00647 ## # … with 22 more rows</code></pre> <div class="sourceCode" id="cb15"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb15-1"><a href="#cb15-1"></a><span class="kw">glance</span>(glmfit)</span></code></pre></div> <pre><code>## # A tibble: 1 x 8 ## null.deviance df.null logLik AIC BIC deviance df.residual nobs ## <dbl> <int> <dbl> <dbl> <dbl> <dbl> <int> <int> ## 1 43.2 31 -9.59 23.2 26.1 19.2 30 32</code></pre> <p>Note that the statistics computed by <code>glance</code> are different for <code>glm</code> objects than for <code>lm</code> (e.g. deviance rather than R^2):</p> <p>These functions also work on other fits, such as nonlinear models (<code>nls</code>):</p> <div class="sourceCode" id="cb17"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb17-1"><a href="#cb17-1"></a>nlsfit <-<span class="st"> </span><span class="kw">nls</span>(mpg <span class="op">~</span><span class="st"> </span>k <span class="op">/</span><span class="st"> </span>wt <span class="op">+</span><span class="st"> </span>b, mtcars, <span class="dt">start =</span> <span class="kw">list</span>(<span class="dt">k =</span> <span class="dv">1</span>, <span class="dt">b =</span> <span class="dv">0</span>))</span> <span id="cb17-2"><a href="#cb17-2"></a><span class="kw">tidy</span>(nlsfit)</span></code></pre></div> <pre><code>## # A tibble: 2 x 5 ## term estimate std.error statistic p.value ## <chr> <dbl> <dbl> <dbl> <dbl> ## 1 k 45.8 4.25 10.8 7.64e-12 ## 2 b 4.39 1.54 2.85 7.74e- 3</code></pre> <div class="sourceCode" id="cb19"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb19-1"><a href="#cb19-1"></a><span class="kw">augment</span>(nlsfit, mtcars)</span></code></pre></div> <pre><code>## # A tibble: 32 x 14 ## .rownames mpg cyl disp hp drat wt qsec vs am gear carb ## <chr> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> ## 1 Mazda RX4 21 6 160 110 3.9 2.62 16.5 0 1 4 4 ## 2 Mazda RX… 21 6 160 110 3.9 2.88 17.0 0 1 4 4 ## 3 Datsun 7… 22.8 4 108 93 3.85 2.32 18.6 1 1 4 1 ## 4 Hornet 4… 21.4 6 258 110 3.08 3.22 19.4 1 0 3 1 ## 5 Hornet S… 18.7 8 360 175 3.15 3.44 17.0 0 0 3 2 ## 6 Valiant 18.1 6 225 105 2.76 3.46 20.2 1 0 3 1 ## 7 Duster 3… 14.3 8 360 245 3.21 3.57 15.8 0 0 3 4 ## 8 Merc 240D 24.4 4 147. 62 3.69 3.19 20 1 0 4 2 ## 9 Merc 230 22.8 4 141. 95 3.92 3.15 22.9 1 0 4 2 ## 10 Merc 280 19.2 6 168. 123 3.92 3.44 18.3 1 0 4 4 ## # … with 22 more rows, and 2 more variables: .fitted <dbl>, .resid <dbl></code></pre> <div class="sourceCode" id="cb21"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb21-1"><a href="#cb21-1"></a><span class="kw">glance</span>(nlsfit)</span></code></pre></div> <pre><code>## # A tibble: 1 x 9 ## sigma isConv finTol logLik AIC BIC deviance df.residual nobs ## <dbl> <lgl> <dbl> <dbl> <dbl> <dbl> <dbl> <int> <int> ## 1 2.77 TRUE 0.0000000288 -77.0 160. 164. 231. 30 32</code></pre> </div> <div id="hypothesis-testing" class="section level3"> <h3>Hypothesis testing</h3> <p>The <code>tidy</code> function can also be applied to <code>htest</code> objects, such as those output by popular built-in functions like <code>t.test</code>, <code>cor.test</code>, and <code>wilcox.test</code>.</p> <div class="sourceCode" id="cb23"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb23-1"><a href="#cb23-1"></a>tt <-<span class="st"> </span><span class="kw">t.test</span>(wt <span class="op">~</span><span class="st"> </span>am, mtcars)</span> <span id="cb23-2"><a href="#cb23-2"></a><span class="kw">tidy</span>(tt)</span></code></pre></div> <pre><code>## # A tibble: 1 x 10 ## estimate estimate1 estimate2 statistic p.value parameter conf.low conf.high ## <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> ## 1 1.36 3.77 2.41 5.49 6.27e-6 29.2 0.853 1.86 ## # … with 2 more variables: method <chr>, alternative <chr></code></pre> <p>Some cases might have fewer columns (for example, no confidence interval):</p> <div class="sourceCode" id="cb25"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb25-1"><a href="#cb25-1"></a>wt <-<span class="st"> </span><span class="kw">wilcox.test</span>(wt <span class="op">~</span><span class="st"> </span>am, mtcars)</span> <span id="cb25-2"><a href="#cb25-2"></a><span class="kw">tidy</span>(wt)</span></code></pre></div> <pre><code>## # A tibble: 1 x 4 ## statistic p.value method alternative ## <dbl> <dbl> <chr> <chr> ## 1 230. 0.0000435 Wilcoxon rank sum test with continuity correc… two.sided</code></pre> <p>Since the <code>tidy</code> output is already only one row, <code>glance</code> returns the same output:</p> <div class="sourceCode" id="cb27"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb27-1"><a href="#cb27-1"></a><span class="kw">glance</span>(tt)</span></code></pre></div> <pre><code>## # A tibble: 1 x 10 ## estimate estimate1 estimate2 statistic p.value parameter conf.low conf.high ## <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> ## 1 1.36 3.77 2.41 5.49 6.27e-6 29.2 0.853 1.86 ## # … with 2 more variables: method <chr>, alternative <chr></code></pre> <div class="sourceCode" id="cb29"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb29-1"><a href="#cb29-1"></a><span class="kw">glance</span>(wt)</span></code></pre></div> <pre><code>## # A tibble: 1 x 4 ## statistic p.value method alternative ## <dbl> <dbl> <chr> <chr> ## 1 230. 0.0000435 Wilcoxon rank sum test with continuity correc… two.sided</code></pre> <p><code>augment</code> 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.</p> <div class="sourceCode" id="cb31"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb31-1"><a href="#cb31-1"></a>chit <-<span class="st"> </span><span class="kw">chisq.test</span>(<span class="kw">xtabs</span>(Freq <span class="op">~</span><span class="st"> </span>Sex <span class="op">+</span><span class="st"> </span>Class, </span> <span id="cb31-2"><a href="#cb31-2"></a> <span class="dt">data =</span> <span class="kw">as.data.frame</span>(Titanic)))</span> <span id="cb31-3"><a href="#cb31-3"></a><span class="kw">tidy</span>(chit)</span></code></pre></div> <pre><code>## # A tibble: 1 x 4 ## statistic p.value parameter method ## <dbl> <dbl> <int> <chr> ## 1 350. 1.56e-75 3 Pearson's Chi-squared test</code></pre> <div class="sourceCode" id="cb33"><pre class="sourceCode r"><code class="sourceCode r"><span id="cb33-1"><a href="#cb33-1"></a><span class="kw">augment</span>(chit)</span></code></pre></div> <pre><code>## # A tibble: 8 x 9 ## Sex Class .observed .prop .row.prop .col.prop .expected .resid .std.resid ## <fct> <fct> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> <dbl> ## 1 Male 1st 180 0.0818 0.104 0.554 256. -4.73 -11.1 ## 2 Female 1st 145 0.0659 0.309 0.446 69.4 9.07 11.1 ## 3 Male 2nd 179 0.0813 0.103 0.628 224. -3.02 -6.99 ## 4 Female 2nd 106 0.0482 0.226 0.372 60.9 5.79 6.99 ## 5 Male 3rd 510 0.232 0.295 0.722 555. -1.92 -5.04 ## 6 Female 3rd 196 0.0891 0.417 0.278 151. 3.68 5.04 ## 7 Male Crew 862 0.392 0.498 0.974 696. 6.29 17.6 ## 8 Female Crew 23 0.0104 0.0489 0.0260 189. -12.1 -17.6</code></pre> </div> </div> <div id="conventions" class="section level2"> <h2>Conventions</h2> <p>In order to maintain consistency, we attempt to follow some conventions regarding the structure of returned data.</p> <div id="all-functions" class="section level3"> <h3>All functions</h3> <ul> <li>The output of the <code>tidy</code>, <code>augment</code> and <code>glance</code> functions is <em>always</em> a tibble.</li> <li>The output never has rownames. This ensures that you can combine it with other tidy outputs without fear of losing information (since rownames in R cannot contain duplicates).</li> <li>Some column names are kept consistent, so that they can be combined across different models and so that you know what to expect (in contrast to asking “is it <code>pval</code> or <code>PValue</code>?” every time). The examples below are not all the possible column names, nor will all tidy output contain all or even any of these columns.</li> </ul> </div> <div id="tidy-functions" class="section level3"> <h3>tidy functions</h3> <ul> <li>Each row in a <code>tidy</code> output typically represents some well-defined concept, such as one term in a regression, one test, or one cluster/class. This meaning varies across models but is usually self-evident. The one thing each row cannot represent is a point in the initial data (for that, use the <code>augment</code> method).</li> <li>Common column names include: <ul> <li><code>term</code>"" the term in a regression or model that is being estimated.</li> <li><code>p.value</code>: this spelling was chosen (over common alternatives such as <code>pvalue</code>, <code>PValue</code>, or <code>pval</code>) to be consistent with functions in R’s built-in <code>stats</code> package</li> <li><code>statistic</code> a test statistic, usually the one used to compute the p-value. Combining these across many sub-groups is a reliable way to perform (e.g.) bootstrap hypothesis testing</li> <li><code>estimate</code></li> <li><code>conf.low</code> the low end of a confidence interval on the <code>estimate</code></li> <li><code>conf.high</code> the high end of a confidence interval on the <code>estimate</code></li> <li><code>df</code> degrees of freedom</li> </ul></li> </ul> </div> <div id="augment-functions" class="section level3"> <h3>augment functions</h3> <ul> <li><code>augment(model, data)</code> adds columns to the original data. <ul> <li>If the <code>data</code> argument is missing, <code>augment</code> attempts to reconstruct the data from the model (note that this may not always be possible, and usually won’t contain columns not used in the model).</li> </ul></li> <li>Each row in an <code>augment</code> output matches the corresponding row in the original data.</li> <li>If the original data contained rownames, <code>augment</code> turns them into a column called <code>.rownames</code>.</li> <li>Newly added column names begin with <code>.</code> to avoid overwriting columns in the original data.</li> <li>Common column names include: <ul> <li><code>.fitted</code>: the predicted values, on the same scale as the data.</li> <li><code>.resid</code>: residuals: the actual y values minus the fitted values</li> <li><code>.cluster</code>: cluster assignments</li> </ul></li> </ul> </div> <div id="glance-functions" class="section level3"> <h3>glance functions</h3> <ul> <li><code>glance</code> always returns a one-row tibble. <ul> <li>The only exception is that <code>glance(NULL)</code> returns an empty tibble.</li> </ul></li> <li>We avoid including arguments that were <em>given</em> to the modeling function. For example, a <code>glm</code> glance output does not need to contain a field for <code>family</code>, since that is decided by the user calling <code>glm</code> rather than the modeling function itself.</li> <li>Common column names include: <ul> <li><code>r.squared</code> the fraction of variance explained by the model</li> <li><code>adj.r.squared</code> <span class="math inline">\(R^2\)</span> adjusted based on the degrees of freedom</li> <li><code>sigma</code> the square root of the estimated variance of the residuals</li> </ul></li> </ul> </div> </div> </div> <!-- code folding --> <!-- dynamically load mathjax for compatibility with self-contained --> <script> (function () { var script = document.createElement("script"); script.type = "text/javascript"; script.src = "https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"; document.getElementsByTagName("head")[0].appendChild(script); })(); </script> </body> </html>