# Introduction to baffle

The package `baffle` stands for `base waffle` implements waffle charts in base R graphics. Waffles are square pie charts that visualize relative quantities using colored squares. Modern waffles charts are not limited to squares and use various dimensions and symbols.

## Basic waffles

The `baffle::waffle` accepts a vector of abundancies `x` and constructs waffle chart accordingly. The vector of abundancies must be a numeric integer vector. For example, if we wish to visualize the difference between `3` apples and `8` oranges, all we need to type is:

    waffle(c(3,8))

By default, `waffle` tries to create a square matrices and uses the categorical `Set 1` palette, if there are 9 or less objects, and the continuous `Zissou` palette otherwise. Colors and dimensions can be specified specifying the `col`, `nrow` and `ncol` arguments.

    par(mfrow=c(1, 3))
    waffle(c(25, 75), col=c("red", "gray"))
    waffle(c(25, 75), col=c("blue", "gray"), ncol=5)
    waffle(c(25, 75), col=c("darkgreen", "gray"), nrow=5)

`baffle` fills the waffle by rows from the bottomleft corner. To change this, you can specify the `byrow` and `from` arguments:

    par(mfrow=c(2,2))
    waffle(c(13, 12), col=c("darkorchid", "gray"))
    waffle(c(13, 12), col=c("skyblue", "gray"), from="topright")
    waffle(c(13,12), col=c("tomato", "gray"), byrow=FALSE)
    waffle(c(13,12), col=c("springgreen", "gray"), from="bottomright", byrow=FALSE)

### Workhorse functions

Waffles in `baffle` are created by three basic functions:

`waffle` allows one to plot waffles directly, as demonstrated above. It constructs the waffle matrix using the `design` function and then plots the waffle matrix with the `waffle.mat` function. In most cases, `waffle` is all one needs.

`design` is a function responsible for transforming the vector of abundances into a waffle matrix. Waffle matrix is a matrix of integers, each integer corresponds to the item in the abundance vector, with empty cells having value `NA`. Design is used internally by the `waffle` function, or it can be used directly create a design matrix that can be then modified, such as to merge multiple design matrices.

`waffle.mat` is the function responsible for plotting the waffle matrix. The matrix is transformed into a grid and a square corresponding to each cell of the matrix is plotted at each point of the grid. `waffle.mat` expect a matrix in the format produced by `design`, but custom matrices can be provided as well.

## Unstacked Waffles

Traditional waffles are squared pie charts are used to display proportion of some whole. Some modern examples use waffles as bar charts, there the waffles are “unstacked” and abundance of each element is displayed side by side.

    par(mar=c(4,0,0,0))
    cyl = table(mtcars$cyl)
    waffle(cyl, stacked=FALSE, gap=1)
    legend("top", horiz=TRUE, bty="n", inset=0.9, xpd=TRUE,
        legend=names(cyl), cex=2,
        fill=palette.colors(length(cyl), "Set 1"), border=NA,
        title="Number of cylinders\n in 'mtcars'")

## Squares, Circles, Polygons

Waffle plots are typically represented by coloured squares. Many modern examples favour different shapes to make themselves more graphically distinct. The `waffle` function is flexible and accepts a plotting function. Any function will do as long as it accepts `x` and `y` coordinates and the diameter of plotted object is slightly smaller than one.

`baffle` comes with several of such functions, the default `square`, `rectangle`, `circle`, `ellipse`, regular convex polygon `rcpoly`. See `?Shapes` for more information. These functions are similar to the `graphics::symbols()`.

These functions are vectorized, in fact even the `f` argument in the `waffle` is vectorized, so multiple polygons can be plotted effortesly.

For example, we can represent the number of cylinders in the above example with regular n-sided polygons.

    par(mar=c(4,0,0,0))
    cyl = table(mtcars$cyl)
    waffle(cyl, stacked=FALSE, gap=1, f=rcpoly, n=as.numeric(names(cyl)))
    legend("top", horiz=TRUE, bty="n", inset=0.9, xpd=TRUE,
        legend=names(cyl), cex=2,
        fill=palette.colors(length(cyl), "Set 1"), border=NA,
        title="Number of cylinders\n in 'mtcars'")

Shame that the `legend` does not allow for such flexibility!

## Text and Points

As noted above, any function that prints to `x` and `y` coordinates can be used! The `base` functions `points` and `text` are already conforming and can be readily used.

Only setting their size can be a bit problematic. `1/strheight(s)` and `1/strwidth(s)` is the most answer, but these can be called only after the plotting window is defined. So one has to either check multiple values and select the most fitting one, which would be `4` in this example, or write a wrapper around `text` that calculates the label dimensions and selects the appropriate value. Since the plotting functions are called after the dimensions are set, one can now use `strheight` and `strwidth` to establish the text dimensions.

    autotext = function(x, y, labels, d=0.9, ...){
        cex = min(1/strheight(labels), 1/strwidth(labels))*d
        text(x, y, labels, cex=cex, ...)
        }

    par(mar=c(4,0,0,0))
    cyl = table(mtcars$cyl)
    waffle(cyl, stacked=FALSE, gap=1, f=autotext, labels=names(cyl))
    legend("top", horiz=TRUE, bty="n", inset=0.9, xpd=TRUE,
        legend=names(cyl), cex=2,
        fill=palette.colors(length(cyl), "Set 1"), border=NA,
        title="Number of cylinders\n in 'mtcars'")

This demonstrates how easy is to improve or convert existing functions to be perfectly useable by baffle.

## Bitmaps

To make things easier, `baffle` provides a wrapper around the base R’s `rasterImage` (in the `graphics` namespace) with the same interface as other shape functions.

To read raster images (such as `png`) use the lightweight `png` package. We then plot the original as well as a single colour representation of it using `waffle` and the `rasters` function.

    library("png")
    path = system.file("img/Rlogo.png", package="png")
    imgR = imgG = imgB = img = readPNG(path)
    imgR[,,c(2,3)] = 0
    imgG[,,c(1,3)] = 0
    imgB[,,c(1,2)] = 0
    waffle(c(1,1,1,1), f=rasters, image=list(img, imgR, imgG, imgB), rotate=c(0,30,60,90))