Crunch Deck Cookbook • Crunch

Decks are a way to save a set of analyses so that you or your team can refer back to them later, export to Excel or PowerPoint, or create a Crunch Dashboard. Each deck is made up of a set of slides, and slides can either be analysis or markdown slides. All slides have a title & subtitle, while analysis slides contain an analysis and markdown slides contain markdown formatted text.

While a good slide generally appears simple to the viewer, a lot depends on getting the analysis exactly right, and so creating them does require setting the analysis’s attributes just right. The attributes of a slide’s analysis are:

a query: A set of variables and what calculation to perform (such as a count or mean)
the query environment: Modifiers to the data that the query is performed on, like a filter or weight to use.
dimension transformations: A dimension is a set of items that the calculation is enumerated along (a table based on a categorical array could have the categories in the “rows” dimension and the subvariables in the “columns” dimension). Dimension transformations are modifications to how those dimensions are displayed, such as reordering, renaming or assigning colors.
display settings and visual specifications: There’s a whole other collection of settings such as the type of visualization, number of decimals, and advanced options for how the slide is exported to Excel.

The recipes in this cookbook all start from the pets example dataset (available from newExampleDataset()).

suppressPackageStartupMessages({
    library(purrr)
    library(crunch)
})

options("crunch.show.progress" = FALSE)

ds <- newExampleDataset()

Basic deck and slide manipulation

Creating an analysis slide on a new deck

Problem

You want to create a new deck and add slides to it.

Solution

A deck is created on a dataset with the command newDeck(). It takes the dataset, a title for the deck, and can take is_public=TRUE if the deck should be made public to other users of the dataset (it defaults to FALSE).

After the deck is created, the newSlide() function adds a slide.

deck <- newDeck(ds, "Q3 Pets Deck", is_public = TRUE)
private_deck <- newDeck(ds, "Private Deck")

# If no `vizType` is specified, defaults to a table
slide <- newSlide(deck, ~q1, title = "Table of Favorite Pet")

# Example of setting a vizType and filter
slide <- newSlide(
    deck, 
    mean(ndogs) ~ country, 
    title = "Dot Plot of Mean Dogs by Country",
    display_settings = list(vizType = "dotplot"),
    filter = ds$q1 == "Dog"
)

deck <- refresh(deck)

Creating an analysis slide on an existing deck

Problem

You want to add a slide to a deck that has already been made.

Solution

The decks() function access the decks catalog for a dataset. You can select one name or position and then add to it.

ds <- refresh(ds)
decks(ds)

private_deck <- decks(ds)[["Private Deck"]]

slide <- newSlide(
    private_deck, 
    ~q1, 
    title = "Bar Plot of Favorite Pet", 
    display_settings = list(vizType = "groupedBarPlot")
)

Creating a markdown slide

Problem

You want to add a markdown slide

Solution

You can create a new markdown slide with the function newMarkdownSlide().

slide <- newMarkdownSlide(deck, "This survey included **10,000 participants**!", title = "About")

Adding an image to a markdown slide

Problem

You want to include an image on a markdown slide

Solution

The function markdownSlideImage() helps add an image to a markdown slide. The function takes a path to an image on your local machine, and you use it as an unnamed argument of newMarkdownSlide().

slide <- newMarkdownSlide(
  deck, 
  "This survey was collected by ACME surveys", 
  markdownSlideImage("acme-logo.png"),
)

Editing an existing slide

Problem

You want to edit a slide that’s already been created.

Solution

Slides can be accessed from the deck’s slide catalog, available from the slides() command. You can retrieve them by their title or position.

The helper functions title<-, subtitle<-, query<-, weight<-, filters<-, transforms<-, displaySettings<- and vizSpecs<- help set options on a analysis slide, and the function slideMarkdown<- edits the text of a markdown slide.

# Move title to subtitle and change the title
slide <- slides(deck)[["Table of Favorite Pet"]]
subtitle(slide) <- title(slide)
title(slide) <- "Cats are the most popular"


# Rename a category
slide <- slides(deck)[[2]]
transforms(slide) <- list(
    rows_dimension = makeDimTransform(rename = c("AUS" = "Australia"))
)


# Edit a markdown slide
slide <- slides(deck)[[3]]
slideMarkdown(slide) <- "**Replacement text**"

Deleting slides on a deck

Problem

You want to delete a slide from a deck.

Solution

Access a slide from the slide catalog and then use the delete() command to delete it (it will ask before deleting unless you use command with_consent()).

slide <- slides(deck)[[1]]

if (FALSE) { # Not actually run for example
    delete(slide)
}

Making a deck public (or private)

Problem

You want to change a deck from being private to public (or vice-versa).

Solution

The is.public<- function can set the deck’s status.

is.public(private_deck) <- TRUE # now public

Query types

Queries define the variables and summary measures used for the slide’s analysis. They use the formula notation used by the crunch function crtabs() which is based on base R’s xtabs().

Univariate frequencies

Problem

You want to get the frequencies of a single categorical or multiple response variable.

Solution

The query for a univariate count query puts the variable on the right hand side of a formula (for example ~var).

slide <- newSlide(
    deck, 
    ~q1, 
    title = "Univariate frequency: Favorite Pet"
)

Bivariate frequencies (crosstabs)

Problem

You want to get a crosstab (or a frequency from two variables’ joint distribution)

Solution

The query for a multivariate frequency uses the + to separate the variables on the right hand side of the formula (for example ~var1 + var2).

slide <- newSlide(
    deck, 
    ~q1 + country, 
    title = "Bivariate frequency: Favorite Pet by country"
)

# A third dimension is possible, which will usually result in a tabbed result:
slide <- newSlide(
    deck, 
    ~q1 + country + wave, 
    title = "Trivariate frequency: Favorite Pet by country by wave"
)

Frequencies from a Categorical Array

Problem

You want to get the frequencies from a categorical array variable

Solution

A categorical array contributes two dimensions to the analysis, a “categories” dimension and a “subvariables” dimension. If your query just specifies the variable, by default the categories dimension is used first and the categories second, but you can specify the order by using categories() and subvaribles() functions in your query.

slide <- newSlide(
    deck, 
    ~allpets, 
    title = "Categorical array: default order"
)

slide <- newSlide(
    deck, 
    ~categories(allpets) + subvariables(allpets), 
    title = "Categorical array: categories on rows dimension"
)

The “categories” dimension cannot be the first dimension (used in the “tabs” of the analysis in a Crunch Dashboard) of a slide analysis that has 3 dimensions. Instead, to get the “tabs” dimension have the categorical array variable, choose one category to select, and create a Multiple Response variable out of it.

When trying to make a slide with a categorical array (ca) and another variables(cat), the following table shows the 6 queries that are valid and which dimension the web app will display on each of the “rows”, “columns” and “tabs” dimensions. Here we have chosen to select the category with name = "category" when using selectCategories, but any valid category id or name could be used instead.

query	rows	columns	tabs
`~cat + categories(ca) + subvariables(ca)`	CA categories	CA subvariables	other variable
`~cat + subvariables(ca) + categories(ca)`	CA subvariables	CA categories	other variable
`~subvariables(ca) + categories(ca) + cat`	CA categories	other variable	CA subvariables
`~subvariables(ca) + cat + categories(ca)`	other variable	CA categories	CA subvariables
`~cat + selectCategories(ca, "category")`	other variable	CA subvariables	CA categories
`~selectCategories(ca, "category") + cat`	CA subvariables	other variable	CA categories

Mean of a Numeric variable

Problem

You want to get the mean from a Numeric (Numeric Array) variable

Solution

A numeric summary measure like a mean goes on the left hand side of the formula in a query. The right hand side cannot be empty, but to get the mean of the whole dataset put 1.

slide <- newSlide(
    deck, 
    mean(ndogs) ~ 1,
    title = "Mean Number of Dogs"
)

slide <- newSlide(
    deck, 
    mean(ndogs) ~ country,
    title = "Mean Number of Dogs by Country"
)

Scorecard of aligned Multiple Response variables

Problem

You want to make comparisons of frequencies of a set of Multiple Response variables with the same items (response)

Solution

A scorecard is a rectangular grid of different Multiple Response variables with their items aligned. The query for a scorecard can be created using the scorecard() function.

# There's only one MR available on this dataset, so we repeat the same one twice to illustrate
slide <- newSlide(
    deck, 
    ~scorecard(allpets, allpets), 
    title = "Scorecard"
)

Dimension transforms

Query results have “dimensions”, which are enumerated sets that the calculation’s results are formed in, such as the categories of a categorical variables or the items in a multiple response variables. Their behavior in the slide can be customized using dimension transforms.

A query result generally has up to three dimensions. The first is the “rows_dimension”, second is the “columns” dimension and third is the “tabs_dimension”. When using the transform argument of newSlide() or setting the transforms<- of a slide directly, you form a named list with these dimensions as the names. The helper function makeDimTransform() can also help create the dimension changes.

Using a dataset’s palette

Problem

You want to make the colors of a dashboard tile use a pre-defined palette.

Solution

Each Crunch Dataset has a set of color palettes associated with it’s account and folder. You can access the palettes using the palettes() or defaultPalette() functions. Then using the makeDimTransform() function you can use this palette. The colors are used in the order they appear and if more colors are needed than provided by the palette, the default colors are used.

slide <- newSlide(
    deck, 
    ~q1, 
    title = "Favorite pet using default palette",
    display_settings = list(vizType = "groupedBarPlot"),
    transform = list(
        rows_dimension = makeDimTransform(colors = defaultPalette(ds))
    )
)

graph_pal <- palettes(ds)[["purple palette"]]
slide <- newSlide(
    deck, 
    ~categories(petloc) + subvariables(petloc), 
    title = "Pets by location using another palette",
    display_settings = list(vizType = "horizontalBarPlot"),
    transform = list(
        rows_dimension = makeDimTransform(colors = graph_pal)
    )
)

Using a set of colors from R

Problem

You want to make the colors of a dashboard tile use a set of colors you specify in the script

Solution

If you want to specify the colors manually, you can also use a character vector of RGB hex codes.

slide <- newSlide(
    deck, 
    ~q1, 
    title = "Favorite pet using colors from R",
    display_settings = list(vizType = "groupedBarPlot"),
    transform = list(
        rows_dimension = makeDimTransform(colors = c("#af8dc3", "#f7f7f7", "#7fbf7b"))
    )
)

Hiding a dimension item

Problem

You want to hide a dimension item (a category or subvariable) from the slide.

Solution

The hide argument of makeDimTransform() takes a category name or id, if the dimension is made from categories, or a subvariable name or alias if the dimension is made from subvariables (as in a Multiple Response variable or a subvariables dimension of a Categorical Array or Numeric Array).

slide <- newSlide(
    deck, 
    ~q1, 
    title = "Favorite pet excluding birds",
    display_settings = list(vizType = "groupedBarPlot"),
    transform = list(
        rows_dimension = makeDimTransform(hide = "Bird")
    )
)

Display settings and visual specifications

Choosing a graph type

Problem

You want to create a slide with a display type other than table.

Solution

The default display of a tile is the table, but the vizType display setting chooses between other options. The most commonly used vizTypes are: - table (always available) - groupedBarPlot, stackedBarPlot, horizontalBarPlot, horizontalStackedBarPlot (available for queries based on a count in any number of dimensions) - timeplot (available when the second dimension has a time component) - dotplot (available for displays of means) - donut (available only for 1 dimensional count queries)

slide <- newSlide(
    deck, 
    ~q1 + country, 
    title = "Favorite pet by country horizontal bar plot",
    display_settings = list(vizType = "horizontalBarPlot")
)


slide <- newSlide(
    deck, 
    ~q1 + wave, 
    title = "Favorite pet over time timeplot",
    display_settings = list(vizType = "timeplot")
)

Using a slide as a template

Problem

You want to use the settings from an existing slide to create a new one (or modify an existing one).

Solution

The functions displaySettings() and vizSpecs() give access to the settings on an existing slide. This slide can be a slide you’ve created from R or from the web app, so that you can use the visual editor to perfect the look for one slide and then use it for a whole set of slides. You can either set the attributes directly, or use dput() to print out the object in a way that you can copy and paste into your code.

template_deck <- newDeck(ds, "Templates", is_public = TRUE)
slide <- newSlide(
    template_deck, 
    ~q1, 
    title = "Donut with value labels",
    display_settings = list(vizType = "donut", showValueLabels = TRUE),
    viz_specs = list(
        default = list(
            format = list(
                decimal_places = list(percentages = 0L, other = 2L),
                show_empty = FALSE
            )
        )
    )
)

# Setting the slide `display_setting` and `viz_specs` directly:
slide <- newSlide(
    deck, 
    ~country,
    title = "Country donut with value labels",
    display_settings = displaySettings(template_deck[["Donut with value labels"]]),
    viz_specs = vizSpecs(template_deck[["Donut with value labels"]])
)

# How to print out the structure in a format that can be copy and pasted into your code
print(dput(displaySettings(template_deck[["Donut with value labels"]])))

Bulk creation of slides

Sometimes you want to make many slides with related formatting to create a document that gives a good high level overview of a dataset. The [tabBook()] function is designed to create a basic “top line” report of simple crosstabs from a multitable, and is probably the first thing you should check if you’re thinking of making bulk analyses. However, tabBook() does not allow for all of the customization possible in a slide.

The trickiest part of bulk creating slides from R is iterating over the variables. The general behind all of these cookbook recipes is to get a list of variable aliases, iterate over them using them to get other variable metadata. The trickiest part is to create a query formula from a string, but the as.formula() function helps with this. This cookbook uses base R functions lapply() and paste0(), but the “tidyverse” functions purrr::walk() and glue::glue() are well-suited to this task.

Basic top line for entire dataset

Problem

You want to create a simple report for every variable in a dataset.

Solution

Use the variables() function to get the variables from a dataset, and the aliases() function to get their aliases. Then use lapply() to iterate over the variable aliases and construct the slide using paste0() and as.formula().

deck <- newDeck(ds, "Full Dataset Topline Deck", is_public = TRUE)

var_aliases <- aliases(variables(ds))

slides <- lapply(var_aliases, function(alias) {
    slide_query <- as.formula(paste0("~", alias))
    slide_title <- paste0("Topline - ", name(ds[[alias]]))
    
    newSlide(deck, slide_query, title = slide_title)
})

Slides for variables within a particular folder

Problem

You want to create a simple report for every variable in a particular folder.

Solution

The variables() function can also work on a folder, so we can make a deck from variables in a folder in a similar way to making one for a whole dataset.

deck <- newDeck(ds, "Folder Topline Deck", is_public = TRUE)

folder <- cd(ds, "Key Pet Indicators")
var_aliases <- aliases(variables(folder))

slides <- lapply(var_aliases, function(alias) {
    slide_query <- as.formula(paste0("~", alias))
    slide_title <- paste0("Topline - ", name(ds[[alias]]))
    
    newSlide(deck, slide_query, title = slide_title)
})

Problem

You want to create crosstabs for many variables across a set of variables.

Solution

You can use lapply() to iterate over both the row and column variables of the crosstab.

deck <- newDeck(ds, "Crosstabs Deck", is_public = TRUE)

demo_vars <- aliases(variables(cd(ds, "Dimensions")))
var_aliases <- setdiff(aliases(variables(ds)), demo_vars) # don't cross demo vars with themselves

slides <- lapply(var_aliases, function(alias) {
    # Add a slide before crosstabs of the univariate frequency
    all_query <- as.formula(paste0("~", alias))
    all_title <- paste0("Frequency - ", name(ds[[alias]]))
    
    newSlide(deck, all_query, title = all_title)
    
    lapply(demo_vars, function(demo_alias) {
        crosstab_query <- as.formula(paste0("~", demo_alias, " + ", alias))
        crosstab_title <- paste0("Crosstab - ", name(ds[[alias]]), " by ", name(ds[[demo_alias]]))
        
        newSlide(deck, crosstab_query, title = crosstab_title)
    })
})

Slides based on variable type

Problem

You want to create a report with slides that vary based on the variable’s type.

Solution

You can create functions that create slides for a particular variable type and then choose which function to use based on the variable’s type while iterating.

cat_slide <- function(alias, ds, deck) {
    slide_query <- as.formula(paste0("~", alias))
    slide_title <- paste0(name(ds[[alias]]))
    newSlide(
        deck, 
        slide_query,
        title = slide_title,
        display_settings = list(vizType = "donut")
    )
}

mr_slide <- function(alias, ds, deck) {
    slide_query <- as.formula(paste0("~", alias))
    slide_title <- paste0(name(ds[[alias]]))
    newSlide(
        deck, 
        slide_query,
        title = slide_title,
        display_settings = list(vizType = "groupedBarPlot")
    )
}

numeric_slide <- function(alias, ds, deck) {
    slide_query <- as.formula(paste0("mean(", alias, ") ~ wave"))
    slide_title <- paste0(name(ds[[alias]]), " over time")
    newSlide(
        deck, 
        slide_query,
        title = slide_title,
        display_settings = list(vizType = "timeplot")
    )
}

deck <- newDeck(ds, "Slides Customized by Variable Type", is_public = TRUE)

var_aliases <- c("q1", "allpets", "ndogs")
slides <- lapply(var_aliases, function(alias) {
    switch(
        type(ds[[alias]]),
        "categorical" = cat_slide(alias, ds, deck),
        "multiple_response" = mr_slide(alias, ds, deck),
        "numeric" = numeric_slide(alias, ds, deck),
    )
})