Less Volume, More Creativity -- Getting Started with the mosaic Package

trellis.par.set(theme = col.mosaic())
  size = 'tiny', 
  tidy = FALSE,
  fig.width = 6, 
  fig.height = 3,
  fig.align = "center",
  out.width = "70%"
options(width = 90)

Project MOSAIC and the mosaic package

NSF-funded project to develop a new way to introduce mathematics, statistics, computation and modeling to students in colleges and universities.

A note about this document

This document was originally created as an R presentation to be used as slides accompanying various presentations. It has been converted into a more traditional document for use as a vignette in the mosaic package.

The examples below use the mosaic and mosaicData packages. An earlier version of this document used lattice graphics, but it has been updated to use ggformula

library(mosaic)  # loads mosaicData and ggformula as well

Less Volume, More Creativity

Many of the guiding principles of the mosaic package reflect the "Less Volume, More Creativity" mantra of Mike McCarthy who had a large poster with those words placed in the "war room" (where assistant coaches decide on the game plan for the upcoming opponent) as a constant reminder not to add too much complexity to the game plan.

A lot of times you end up putting in a lot more volume, because you are teaching fundamentals and you are teaching concepts that you need to put in, but you may not necessarily use because they are building blocks for other concepts and variations that will come off of that ... In the offseason you have a chance to take a step back and tailor it more specifically towards your team and towards your players."

Mike McCarthy, former Head Coach, Green Bay Packers

SIBKIS: See It Big, Keep It Simple

Here is another elegant phrasing of a similar principle.

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.

--- Antoine de Saint-Exupery (writer, poet, pioneering aviator)

Less Volume, More Creativity in R

One key to successfully introducing R is finding a set of commands that is

It is not enough to use R, it must be used elegantly.

Two examples of this principle:

Minimal R

Goal: a minimal set of R commands for Intro Stats

Result: Minimal R Vignette (vignette("MinimalR"))

Much of the work on the mosaic package has been motivated by

A few little details

If you (or your students) are just getting started with R, it is good to keep the following in mind:

R is case sensitive

Arrows and Tab

If all else fails, try ESC

The Most Important Template


The following template is important because we can do so much with it.


goal ( yyy ~ xxx , data = mydata )


It is useful to name the components of the template:


goal (  y  ~  x  , data = mydata )

  We're hiding a bit of complexity in the template, and there will be times that we will want to gussy things up a bit. We'll indicate that by adding ... to the end of the template. Just don't let ... become a distractor early on.


goal (  y  ~  x  , data = mydata , ...)


Other versions

Here are some variations on the template.

# simpler version
goal(~ x, data = mydata)          
# fancier version
goal(y ~ x | z , data = mydata)   
# unified version
goal(formula, data = mydata)     

2 Questions

Using the template generally requires answering two questions. (These questions are useful in the context of nearly all computer tools, just substitute "the computer" in for R in the questions.)


goal (  y  ~  x  , data = mydata )


What do you want R to do? (goal)

What must R know to do that?

How do we make this plot? (Questions)

gf_point(births ~ date, data = Births78) 

What is the Goal?

What does R need to know?

How do we make this plot? (Answers)

What is the Goal?

What does R need to know?

Putting it all together

gf_point(births ~ date, data = Births78) 

Your turn: How do you make this plot?

gf_boxplot(age ~ substance, data = HELPrct, xlab = "substance")

Some things you will need to know:

  1. Command: gf_boxplot()

  2. The data: HELPrct

  3. Variables: age, substance
  4. use ?HELPrct for info about data


gf_boxplot(age ~ substance, data=HELPrct)

Your turn: How about this one?

gf_boxploth(substance ~ age, data = HELPrct)

Some things you will need to know:

  1. Command: gf_boxploth() for horizontal boxplots

  2. The data: HELPrct</code

  3. Variables: age, substance
  4. use ?HELPrct for info about data


gf_boxploth(substance ~ age, data = HELPrct)

Note that we have reversed which variable is mapped to the x-axis and which to the y-axis by reversing their order in the formula and using gf_boxploth() instead of gf_boxplot().

Graphical Summaries: One Variable

gf_histogram(~ age, data = HELPrct) 

Note: When there is one variable it is on the right side of the formula.

Graphical Summaries: Overview

One Variable

  gf_histogram( ~ age, data = HELPrct) 
    gf_density( ~ age, data = HELPrct) 
    gf_boxplot( ~ age, data = HELPrct) 
         gf_qq( ~ age, data = HELPrct) 
   gf_freqpoly( ~ age, data = HELPrct) 

Two Variables

gf_point(i1 ~ age,          data = HELPrct) 
gf_boxplot(age ~ substance, data = HELPrct) 

Note: i1 is the average number of drinks (standard units) consumed per day in the past 30 days (measured at baseline)

The Graphics Template

One variable

plotname ( ~  x  , data = mydata , ...)

  • gf_histogram(), gf_qq(), gf_density(), gf_freqpoly()


Two Variables

plotname (  y  ~  x  , data = mydata , ...)

  • gf_point(), gf_line(), gf_boxplot()

Your turn

Create a plot of your own choosing with one of these data sets

names(KidsFeet)    # 4th graders' feet
names(Utilities)   # utility bill data
require(NHANES)    # load package
names(NHANES)      # body shape, etc. 

groups and panels

  • Add color = ~group or fill = ~group to overlay with different colors.

  • Use y ~ x | z to create multipanel plots.

Here is an example.

gf_density( ~ age | sex, data = HELPrct, fill = ~ substance)

Beginners can create plots with 3 or 4 variables easily and quickly using this template.

Bells & Whistles

The ggformula graphics system includes lots of bells and whistles including

  • titles
  • axis labels
  • colors
  • sizes
  • transparency
  • etc, etc.

I used to introduce these too early. My current approach:

  • Let the students ask or
  • Let the data analysis drive

An example with some bells and whistles

Births78 <- Births78 %>%
  mutate(weekday = wday(date, label = TRUE, abbr = TRUE))
gf_line(births ~ date, color = ~ weekday, data = Births78)


  • wday() is in the lubridate package
  • This version of the plot reveals a clear weekend (and holiday) pattern. Typically, I like to have students conjecture about the "double wave" pattern and see if we can build plots to test their conjectures.

Numerical Summaries

The mosaic package provides functions that make it simple to create numerical summaries using the same template used for graphing (and later for describing linear models).

Numerical Summaries: One Variable

Big idea:

  • Replace plot name with summary name
  • Nothing else changes
gf_histogram( ~ age, data = HELPrct)  # binwidth = 5 (or 10) might be good here
        mean( ~ age, data = HELPrct)

Other summaries

The mosaic package includes formula aware versions of mean(), sd(), var(), min(), max(), sum(), IQR(), ...

Also provides favstats() to compute our favorites.

favstats( ~ age, data = HELPrct)

favstats() quickly becomes a go-to function in our courses.

df_stats() is similar, but

  • stores the results in a data frame
  • can be used to make custom summary tables
df_stats( ~ age, data = HELPrct)
df_stats( ~ age, data = HELPrct, mean, sd, median, iqr)


tally(~ sex, data = HELPrct)
tally(~ substance, data = HELPrct)
df_stats(~ substance, data = HELPrct, counts, props)

Numerical Summaries: Two Variables

There are three ways to think about this. All do the same thing.

sd(age ~ substance, data = HELPrct)
sd(~ age | substance, data = HELPrct)
sd(~ age, groups = substance, data = HELPrct)  
# note option color = ~ substance is used for graphics
sd(~ age, groups = substance, data = HELPrct)

This makes it possible to easily convert three different types of plots into the (same) corresponding numerical summary.

df_stats() can also be used with multiple variables and provides a different output format.

df_stats(age ~ substance, data = HELPrct, sd)  

Numerical Summaries: Tables

2-way tables are just tallies of 2 variables.

tally(sex ~ substance, data = HELPrct)
tally( ~ sex + substance, data = HELPrct)
df_stats(sex ~ substance, data = HELPrct, counts)

Other output formats are available

tally(sex ~ substance,   data = HELPrct, format = "proportion")
tally(substance ~ sex,   data = HELPrct, format = "proportion", margins = TRUE)
tally(~ sex + substance, data = HELPrct, format = "proportion", margins = TRUE)
tally(sex ~ substance,   data = HELPrct, format = "percent")
df_stats(sex ~ substance,   data = HELPrct, props, percs)

More examples

HELPrct <- mutate(HELPrct, sex = factor(sex, labels = c('F','M')),
                     substance = factor(substance, labels = c('A', 'C', 'H')))
mean(age ~ substance | sex, data = HELPrct)
mean(age ~ substance | sex, data = HELPrct, .format = "table")
  • I've abbreviated some labels to make things fit better. You can do this using mutate() (in the dplyr package) or transform().
  • This also works for median(), min(), max(), sd(), var(), favstats(), etc.

One Template to Rule a Lot

This master template can be used to do a large portion of what needs doing in an Intro Stats course.

  • single and multiple variable graphical summaries
  • single and multiple variable numerical summaries
  • linear models
      mean(age ~ sex, data = HELPrct)
gf_boxplot(age ~ sex, data = HELPrct) 
        lm(age ~ sex, data = HELPrct)
  mean(age ~ sex, data = HELPrct)
    coef(lm(age ~ sex, data = HELPrct))

It can be learned early and practiced often so that students become secure in their ability to use these functions.

Some other things

The mosaic package includes some other things, too

  • data sets (they have now been moved to separate mosaicData and NHANES packages)
  • xtras: xchisq.test(), xpnorm(), xqqmath()
  • these functions add a bit of extra output to the similarly named functions that don't have a leading x
  • mplot()
  • mplot(HELPrct) interactive plot creation
  • replacements for plot() in some situations
  • simplified gf_histogram() controls (e.g., binwidth)
  • simplified ways to add onto lattice plots (gf_refine())


xpnorm(700, mean = 500, sd = 100)
xpnorm(c(300, 700), mean = 500, sd = 100)
phs <- cbind(c(104,189),c(10933,10845))
colnames(phs) <- c("heart attack","no heart attack")
rownames(phs) <- c("aspirin","placebo")


Modeling is really the starting point for the mosaic design.

  • linear models (lm() and glm()) defined the template
  • lattice graphics use the template (so we chose lattice)
  • we added functionality so numerical summaries can be done with the same template
  • additional things added to make modeling easier for beginners

Models as Functions

model <- lm(width ~ length * sex, 
            data = KidsFeet)
Width <- makeFun(model)
Width(length = 25, sex = "B")
Width(length = 25, sex = "G")

Once models have been converted into functions, we can easily add them to our plots using plotFun().

gf_point(width ~ length, data = KidsFeet, 
        color = ~ sex) %>%
  gf_fun(Width(length, sex = "B") ~ length, color = ~"B") %>%
  gf_fun(Width(length, sex = "G") ~ length, color = ~"G")

Resampling -- You can do() it!

If you want to teach using randomization tests and bootstrap intervals, the mosaic package provides some functions to simplify creating the random distirubtions involved.

An example: The Lady Tasting Tea

  • Often used on first day of class

  • Story

  • woman claims she can tell whether milk has been poured into tea or vice versa.

  • Question: How do we test this claim?

trellis.par.set(theme = col.mosaic())
opts_chunk$set(size = 'small', cache = TRUE)
options(width = 90)

We use rflip() to simulate flipping coins


Note: We do this with students who do not (yet) know what a binomial distribution is, so we want to avoid using rbinom() at this point.

Rather than flip each coin separately, we can flip multiple coins at once.

  • easier to consider heads = correct; tails = incorrect than to compare with a given pattern
  • this switch bothers me more than it bothers my students

Now let's do that a lot of times

rflip(10) simulates 1 lady tasting 10 cups 1 time.

We can do that many times to see how guessing ladies do:

do(2) * rflip(10)
  • do() is clever about what it remembers (in many common situations)
  • 2 isn't many -- we'll do many next -- but it is a good idea to take a look at a small example before generating a lot of random data.

Now let's simulate 5000 guessing ladies

Ladies <- do(5000) * rflip(10)
head(Ladies, 2)
gf_histogram(~ heads, data = Ladies, binwidth = 1)

Q. How often does guessing score 9 or 10?

Here are 3 ways to find out

tally( ~ (heads >= 9), data = Ladies)
tally( ~ (heads >= 9), data = Ladies, format = "prop")
 prop( ~ (heads >= 9), data = Ladies)

A general approach to randomization

The Lady Tasting Tea illustrates a 3-step process that can be reused in many situations:

  1. Do it for your data
  2. Do it for "random" data
  3. Do it lots of times for "random" data

  4. definition of "random" is important, but can often be handled by the mosaic functions shuffle() or resample()

Example: Do mean ages differ by sex?

diffmean(age ~ sex, data = HELPrct)
do(1) * 
  diffmean(age ~ shuffle(sex), data = HELPrct)
Null <- do(5000) * 
  diffmean(age ~ shuffle(sex), data = HELPrct)
prop( ~ (abs(diffmean) > 0.7841), data = Null) 
gf_histogram( ~ diffmean, data = Null) %>%
  gf_vline(xintercept = -0.7841) 

Example: Bootstrap CI for difference in means

Bootstrap <- do(5000) * 
  diffmean(age ~ sex, data = resample(HELPrct))

gf_histogram( ~ diffmean, data = Bootstrap) %>%
  gf_vline(xintercept = -0.7841)
cdata( ~ diffmean, data = Bootstrap, p = 0.95)
confint(Bootstrap, method = "quantile")
confint(Bootstrap)  # default uses bootstrap st. err.

Randomization and linear models

do(1) * lm(width ~ length, data = KidsFeet)
do(3) * lm(width ~ shuffle(length), data = KidsFeet)
do(1) * 
  lm(width ~ length + sex, data = KidsFeet)
do(3) * 
  lm(width ~ length + shuffle(sex), data = KidsFeet)
Null <- do(5000) * 
  lm(width ~ length + shuffle(sex), 
                       data = KidsFeet)
gf_histogram( ~ sexG, data = Null, boundary = -0.2325) %>%
  gf_vline(xintercept = -0.2325)
gf_histogram(~ sexG, data = Null, boundary = -0.2325) %>%
  gf_vline(xintercept = -0.2325)
prop(~ (sexG <= -0.2325), data = Null)

Want to learn more?

More mosaic resources can be found at https://www.mosaic-web.org/mosaic/articles/mosaic-resources.html.

The RJournal paper entitled "mosaic Package: Helping Students to `Think with Data' Using R (https://journal.r-project.org/archive/2017/RJ-2017-024/index.html) provides further discussion of the mosaic modeling language and approach to teaching.

Try the mosaic package in your browser

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

mosaic documentation built on Jan. 18, 2021, 5:09 p.m.