TMwR: the book source for Tidy Modeling with R

A book repository, ordered the way the book reads

The TMwR repository contains the source for the book Tidy Modeling with R, and the stated purpose of the book is to demonstrate how the tidyverse and tidymodels can be used to produce high quality models.

The file listing is the table of contents. There are twenty-one numbered chapters, and the sequence is the argument of the book: 01-software-modeling, 02-tidyverse, 03-base-r, then the data chapter 04-ames, then 05-data-spending, 06-fitting-models, 07-the-model-workflow, 08-feature-engineering, 09-judging-model-effectiveness, 10-resampling, 11-comparing-models, 12-tuning-parameters, 13-grid-search, 14-iterative-search, 15-workflow-sets, 16-dimensionality-reduction, 17-encoding-categorical-data, 18-explaining-models-and-predictions, 19-when-should-you-trust-predictions, 20-ensemble-models and 21-inferential-analysis.

That ordering is the point of the book, and it is worth reading as a curriculum rather than a reference. The first three chapters are about tooling and about base R, which means the book assumes you are coming from base R rather than from a tidymodels-shaped background. The Ames housing data arrives in chapter four and is then used for the rest of the book, so every later concept is demonstrated on the same dataset that readers have already learned.

The last two chapters are the ones that mark the book as more than a tutorial. Explaining models and predictions comes before when should you trust predictions, and ensembles and inferential analysis come last, so the book ends on the questions of what a model can and cannot tell you rather than on accuracy metrics.

Around the chapters are the files a bookdown project needs: an index.Rmd, a _bookdown.yml, an _common.R for shared setup, an _output.yaml, a DESCRIPTION file, a TMwR.bib bibliography, a TMwR.css stylesheet, a style.css, a references.Rmd, and a pre-proc-table.Rmd for a table built before the book.

Building the book needs remotes, GitHub and bookdown

The readme gives the reproduction steps, and they are short enough to be worth quoting.

First the remotes package:

``` r install.packages("remotes")

Then the repository itself:

r remotes::install_github("tidymodels/TMwR")

The readme is honest about a side effect here. Although the project rigorously tries to use the current CRAN versions of all packages, the command above may install some development versions. That is a property of installing from GitHub, and the sentence is a useful warning for anyone who wants to reproduce the book exactly rather than approximately, since the code in the chapters may behave differently against a development version of a dependency.

The content is created using the bookdown package, and the book is compiled with:

r bookdown::render_book("index.Rmd", "bookdown::gitbook") ```

That produces the HTML files in a directory called _book. The readme also notes that a print version is being published with O'Reilly, and that a PDF version is not currently supported for building. So the gitbook is the only build target here, which is a deliberate simplification and the reason the bookdown configuration lists _bookdown.yml and _output.yaml rather than a set of LaTeX sources.

The repository carries a .Rbuildignore file, which is what tells R not to package the book sources as an R package, and a TMwR.Rproj file, which is the RStudio project definition, so opening the folder in RStudio is enough to get a working environment.

A permissively written but non-commercial licence

The licensing is the detail to read before you plan to reuse any of this, and it is not the licence most people expect from a book in the R world.

The readme states that the work is written under a Contributor Code of Conduct and that the online version is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International Licence. Contributing means agreeing to abide by those terms, which is spelled out as applying to participation such as submitting an issue with suggestions or edits, and the instructions for making contributions are in the contributing.md file.

Three obligations in that licence name are worth noting separately. Attribution means you have to credit the work. Non-commercial means you cannot sell it or use it for a commercial product. Share-alike means a derivative has to be licensed the same way, which is the clause that most affects a course or a company that wanted to adapt a chapter into internal training.

No licence identifier is recorded for the repository, and the terms sit in the LICENSE.md file at the root, and the readme points to the online licence for the version that applies to the published book.

The distinction between the book and the code is worth flagging too. The code in the chapters is teaching code. It is written to be read, with the trade-offs visible, and it is not maintained as a package with a support commitment. If you want a maintained implementation of resampling or tuning, the tidymodels packages themselves are the thing to depend on, and this repository is the argument for how they fit together.

Why a book is the right container for this material

It is worth asking why the tidy modelling workflow is taught as a book rather than as package documentation, since the tidymodels packages have their own reference sites.

The answer visible in the file listing is the chapter sequence. The material is not a set of independent features, it is an argument with a shape: you start with data and a question, you fit a model, you decide whether you can trust it, you tune it, you interpret it, and you find out when to stop. A reference manual documents functions; a book has to make the argument work, and that is what the twenty-one chapter ordering is doing.

The Ames data chapter makes the same point from the other side. The book uses one dataset, the Ames housing data introduced in chapter four, across the following seventeen chapters, so each new concept arrives on ground the reader has already surveyed. A book on the Ames data with a different dataset for each chapter would read as a collection of tutorials, and that is the failure mode the book is explicitly avoiding.

The last two chapters are the clearest evidence of the intent. Inferential analysis and when should you trust predictions are the subjects that a function reference cannot cover, because they are questions about what the modelling process licenses you to claim rather than about what a function returns. Putting them in a book means the earlier chapters are read as a setup for them.

For a reader, the practical implication is that this repository rewards being read in order and does not reward being searched. A tidymodels user who wants a specific function will be better served by the package documentation, and someone who wants to understand why the workflow is shaped this way will find the answer here.

The extras directories are where the practical detail lives

Beyond the twenty-one chapters, the top-level listing has a set of directories and files that are not part of the book's linear argument, and they are where a working project keeps the things that do not fit into prose.

There is an extras/ directory, a latex_extras/ directory, a premade/ directory, a figures/ directory, an images/ directory and an RData/ directory. The RData directory is the interesting one for a book project, because it holds pre-computed objects, and the ames_snippets.R file at the root is a set of R code snippets relating to the Ames data.

There are also media files at the root, bo_search.mp4, sa_search.mp4 and race_results.mp4, which are recordings of search processes that are easier to show than to describe. That is a real characteristic of a book about tuning: the difference between a grid search and an iterative one is not obvious from code alone.

The supporting files complete the picture. A contributors.csv file, an issue_template.md, a code_of_conduct.md, a chi.csv data file, a displaced.Rmd and a pre-proc-table.Rmd, and a .github/ directory with the bookdown build workflow, whose badge is the one at the top of the readme.

The build badge is the visible sign of the whole arrangement. The book is rendered automatically from the R Markdown sources, which means the published site and the repository are the same thing, and a pull request that changes a chapter changes the book.

Editorial conclusion

The TMwR repository suits a reader who wants the tidy modelling workflow explained in full, from a first look at the Ames housing data through resampling, tuning and model explanation, and it suits a bookdown author who wants a real project to look at. It does not suit someone looking for a maintained R package, since the code here is book code that illustrates rather than ships, and the last release tag is from 2022. Before running it, install remotes and the repository from GitHub, read the chapter list in the root, and note that the book builds to HTML only, with no PDF target supported.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. tidymodels/TMwR on GitHub