DOCSEARCHbyAlgolia
Submit Docs

waffle R package

repository·master·Indexed 21 days ago

https://github.com/hrbrmstr/waffle

An R package for creating Waffle Chart (square pie chart) visualizations. It integrates with ggplot2 via geom_waffle() and geom_pictogram(), the latter of which supports isotype pictograms using Font Awesome glyphs. The package includes the waffle() function for basic charts, iron() for stitching multiple plots into a vertical layout, and theme_enhance_waffle() for cleaning up chart themes.

Tokens
2.6K
Snippets
9
Records
11
Agent score
24%

What's inside waffle

  1. Install the waffle package

    master

    You can install waffle from CRAN or directly from GitHub using remotes. Note that the CRAN version may be older than the GitHub version.

    To install from CRAN:

    install.packages("waffle")

    To install the latest version from GitHub (requires the remotes package):

    remotes::install_github("hrbrmstr/waffle")
    install.packages("waffle")
# or
remotes::install_github("hrbrmstr/waffle")

  2. Clean up waffle themes with theme_enhance_waffle()

    master
    The theme_enhance_waffle() function is a utility to remove 'theme cruft' from waffle charts. It can be used in conjunction with any other ggplot2 theme (like theme_ipsum_rc() or theme_minimal()) to ensure the waffle chart looks clean and optimized for the square grid layout.

  3. Create basic waffle charts with waffle()

    master

    The waffle() function creates square pie charts (waffle charts) to communicate parts of a whole. It accepts a named vector or a data frame and returns a ggplot2 object.

    Arguments:

    • parts: A named vector or a data frame with values to represent.
    • rows: The number of rows in the grid.
    • size: The size of the squares.
    • colors: A vector of colors for the categories.
    • legend_pos: Position of the legend (e.g., "bottom").
    • title: Title for the plot.
    • xlab: X-axis label.
    • use_glyph: A glyph name (from Font Awesome) to use instead of squares.
    • keep: Boolean. If TRUE (default), it keeps factor levels when stitching plots together with iron().
    # Basic usage with a named vector
parts <- c(80, 30, 20, 10)
waffle(parts, rows = 8)

# Usage with a data frame
parts_df <- data.frame(
  names = LETTERS[1:4],
  vals = c(80, 30, 20, 10)
)
waffle(parts_df, rows = 8)

  4. Use geom_waffle() for ggplot2 integration

    master

    For more control within a ggplot2 workflow, use geom_waffle(). This allows you to use standard ggplot2 layers like facet_wrap(), scale_fill_manual(), and theme().

    Example of faceted waffle charts:

    ggplot(
  data = xdf, 
  aes(fill=parts, values=values)
) +
  geom_waffle(
    color = "white", 
    size = 1.125, 
    n_rows = 6
  ) +
  facet_wrap(~fct, ncol=1)
    ggplot(
  data = xdf, 
  aes(fill=parts, values=values)
) +
  geom_waffle(
    color = "white", 
    size = 1.125, 
    n_rows = 6
  ) +
  facet_wrap(~fct, ncol=1) +
  scale_x_discrete(expand = c(0,0,0,0)) +
  scale_y_discrete(expand = c(0,0,0,0)) +
  ggthemes::scale_fill_tableau(name=NULL) +
  coord_equal() +
  theme_ipsum_rc(grid="") +
  theme_enhance_waffle()
)

  5. Stitch multiple waffle plots together with iron()

    master

    The iron() function provides a vertical, left-aligned layout for multiple waffle plots. This is useful for comparing several waffle charts side-by-side or in a stack while maintaining consistent alignment and padding.

    Usage: Pass multiple ggplot2 objects (created via waffle() or geom_waffle()) to iron().

    Example:

    # Create multiple plots
A <- waffle(parts = c(a=10, b=90), rows = 5)
B <- waffle(parts = c(a=50, b=50), rows = 5)

# Stitch them together
iron(A, B)
    iron(A, B, C)

  6. Create pictogram charts with geom_pictogram()

    master

    The geom_pictogram() function allows you to create isotype pictograms where squares are replaced by glyphs (like Font Awesome icons).

    Key features:

    • Use scale_label_pictogram() to map Font Awesome glyph names to your data labels.
    • Use make_proportional = TRUE to adjust the grid based on values.
    • Use family to specify the Font Awesome font family (e.g., "FontAwesome5Brands-Regular").

    Example:

    # Requires Font Awesome fonts to be installed
library(waffle)
library(ggplot2)

xdf %>%
  count(parts, wt = vals) %>%
  ggplot(
    aes(label = parts, values = n)
  ) +
  geom_pictogram(
    n_rows = 10, 
    aes(colour = parts), 
    flip = TRUE, 
    make_proportional = TRUE
  ) +
  scale_label_pictogram(
    name = NULL,
    values = c("apple-alt", "bread-slice", "pizza-slice"),
    labels = c("Fruit", "Sammich", "Pizza")
  )
    xdf %>%
  count(parts, wt = vals) %>%
  ggplot(
    aes(label = parts, values = n)
  ) +
  geom_pictogram(
    n_rows = 10, 
    aes(colour = parts), 
    flip = TRUE, 
    make_proportional = TRUE
  ) +
  scale_color_manual(
    name = NULL,
    values = c("#a40000", "#c68958", "#ae6056"),
    labels = c("Fruit", "Sammich", "Pizza")
  ) +
  scale_label_pictogram(
    name = NULL,
    values = c("apple-alt", "bread-slice", "pizza-slice"),
    labels = c("Fruit", "Sammich", "Pizza")
  ) + 
  coord_equal() + 
  theme_ipsum_rc(grid="") + 
  theme_enhance_waffle()

  7. Reference: Waffle functions and Geoms

    master

    The following core functions and geoms are available in the waffle package:

    Core Functions:

    • waffle: Make waffle (square pie) charts
    • draw_key_pictogram: Legend builder for pictograms
    • fa_grep: Search Font Awesome glyph names for a pattern
    • fa_list: List all Font Awesome glyphs
    • fa5_brand: Font Awesome 5 Brand
    • fa5_solid: Font Awesome 5 Solid
    • install_fa_fonts: Install Font Awesome 5 Fonts
    • iron: Vertical, left-aligned layout for waffle plots
    • scale_label_pictogram: Used with geom_pictogram() to map Font Awesome fonts to labels
    • theme_enhance_waffle: Waffle chart theme cruft remover

    Geoms:

    • geom_pictogram: Pictogram Geom
    • geom_waffle: Waffle (Square pie chart) Geom

  8. Create Waffle Bar Charts with scales

    master

    You can combine geom_waffle() with standard ggplot2 scales to create waffle bar charts. This involves using facet_wrap() to separate categories by a grouping variable and adjusting the y-axis scale to match the multiplier used for the data (e.g., if you divide your data by 10 to fit a grid, your axis labels should multiply by 10).

    # Example of a faceted waffle bar chart
ggplot(
  data = storms_df, 
  aes(fill = status, values = n)
) +
  geom_waffle(
    color = "white", 
    size = .25, 
    n_rows = 10, 
    flip = TRUE
  ) +
  facet_wrap(~year, nrow = 1, strip.position = "bottom") +
  scale_y_continuous(
    labels = function(x) x * 10, 
    expand = c(0,0)
  ) +
  coord_equal()

  9. Use `geom_waffle()` for advanced ggplot2 integration

    master

    For more control within a ggplot2 pipeline, use geom_waffle(). This is useful for faceting, custom themes, and complex layouts.

    Key parameters:

    • n_rows: Number of rows in the grid.
    • size: Size of the squares.
    • colour: Color of the square borders.
    • flip: Boolean to flip the orientation.

    When using geom_waffle(), you typically map fill to a categorical variable and values to the numeric quantity in aes().

    ggplot(
  data = xdf, 
  aes(fill = parts, values = values)
) +
  geom_waffle(
    color = "white", 
    size = 1.125, 
    n_rows = 6
  ) +
  coord_equal()

  10. Create waffle charts with the `waffle()` function

    master

    The waffle() function creates square pie charts (waffle charts) to communicate parts of a whole for categorical quantities. It returns a ggplot2 object. You can pass a named vector or a data frame to the parts argument.

    Key parameters:

    • parts: A named vector or a data frame with two columns (names and values).
    • rows: The number of rows in the grid.
    • size: The size of the squares.
    • colors: A vector of colors for the categories.
    • legend_pos: Position of the legend (e.g., "bottom").
    • use_glyph: (Optional) A glyph name to use instead of squares.
    • glyph_size: (Optional) Size of the glyph.
    • keep: Boolean. If TRUE (default), it keeps factor levels. Set to FALSE to disable.
    # Using a named vector
parts <- c("A" = 80, "B" = 20)
waffle(parts, rows = 8)

# Using a data frame
parts_df <- data.frame(names = c("A", "B"), vals = c(80, 20))
waffle(parts_df, rows = 8)

  11. Create isotype pictograms with `geom_pictogram()`

    master

    The geom_pictogram() function allows you to create isotype pictograms within a ggplot2 workflow. Instead of simple squares, it uses glyphs to represent data.

    Key parameters:

    • n_rows: Number of rows in the grid.
    • size: Size of the glyphs.
    • flip: Boolean to flip the orientation.
    • make_proportional: Boolean to make glyphs proportional.
    • family: Font family for the glyphs (e.g., "FontAwesome5Brands-Regular").

    Note: You often use scale_label_pictogram() to map specific glyph names to your data categories.

    library(ggplot2)
library(waffle)

xdf %>%
  count(parts, wt = vals) %>%
  ggplot(
    aes(label = parts, values = n)
  ) +
  geom_pictogram(
    n_rows = 10, 
    aes(colour = parts), 
    flip = TRUE, 
    make_proportional = TRUE
  ) +
  scale_label_pictogram(
    name = NULL,
    values = c("apple-alt", "bread_slice", "pizza_slice"),
    labels = c("Fruit", "Sammich", "Pizza")
  )