Package {ggtaichi}

ggtaichi: Taichi diagrams for two data sources

Description

ggtaichi, which is a ggplot2 extension, visualizes data from two different sources on a single grid of taichi (yin-yang) diagrams. Instead of faceting a heatmap by data source, the two sources are combined into one plot, where every cell becomes a taichi symbol whose two fish are filled by the two sources via luminance. Prior to using the package, users should load ggplot2.

ggtaichi functions

The main workhorse is geom_taichi(), which turns every (x, y) cell into a taichi diagram, much like geom_tile() draws a regular heatmap. It is supported by theme_taichi() and remove_padding() for styling. Users should reference the documentation and run the examples in the help files when trying to understand what each argument means visually.

Author(s)

Maintainer: Youzhi Yu yuyouzhi666@icloud.com

See Also

Useful links:

• https://pursuitofdatascience.github.io/ggtaichi/

• https://github.com/PursuitOfDataScience/ggtaichi

• Report bugs at https://github.com/PursuitOfDataScience/ggtaichi/issues

Synthetic café orders: espresso vs. matcha

Description

A small, deliberately synthetic two-source dataset for demos and vignettes: weekly orders (per 100 customers) of espresso and matcha drinks across eight fictional neighbourhoods over a 12-week season. It provides an evergreen alternative to the COVID-era pitts_tg / states_tg data, and because both columns share the same units it is the natural demo for shared_limits / shared_legend in geom_taichi(). The values are simulated with a fixed seed (espresso cools off over the season while matcha picks up, at neighbourhood-specific rates, plus noise); the generating script ships in data-raw/cafes_tg.R in the source repository.

Usage

cafes_tg

Format

A data frame with 96 rows and 4 columns:

week

Week of the season, 1 to 12.

neighbourhood

One of eight fictional neighbourhoods (factor).

espresso

Weekly espresso orders per 100 customers.

matcha

Weekly matcha orders per 100 customers.

Source

Simulated by the package author; see data-raw/cafes_tg.R.

Examples

library(ggplot2)
ggplot(cafes_tg, aes(x = week, y = neighbourhood)) +
  geom_taichi(yin = matcha, yang = espresso, shared_legend = TRUE) +
  theme_taichi()

Taichi

Description

The taichi geom turns each cell of a heatmap-like grid into a taichi (yin-yang) diagram. The two interlocking "fish" of the diagram use luminance to show the values from two data sources on the same plot, so four dimensions of data can be expressed at once: the x and y position of every taichi symbol plus the yin and yang values that fill its two halves. With the optional eyes enabled and mapped to data (see eyes, yin_eye_size, yang_eye_size), a single glyph can carry up to six dimensions.

Usage

geom_taichi(
  yin,
  yang,
  yin_name = NULL,
  yang_name = NULL,
  yin_colors = c("gray100", "gray85", "gray50", "gray35", "gray0"),
  yang_colors = c("#FED7D8", "#FE8C91", "#F5636B", "#E72D3F", "#C20824"),
  yin_scale = NULL,
  yang_scale = NULL,
  angle = NULL,
  eyes = FALSE,
  yin_eye_size = 0.15,
  yang_eye_size = 0.15,
  yin_eye_colour = "white",
  yang_eye_colour = "black",
  shared_limits = FALSE,
  shared_legend = FALSE,
  width = NULL,
  height = NULL,
  alpha = NA,
  na.rm = FALSE,
  colour = NA,
  linewidth = 0.1,
  linetype = 1,
  show.legend = NA,
  ...
)

Arguments

Value

A ggtaichi_plot object: the two fish layers plus the fill scales they need, ready to be added to a ggplot with +. It is not a plot on its own.

Discrete and continuous fills

geom_taichi() inspects the plot data at + time. A numeric yin / yang column gets a continuous scale_fill_gradientn built from yin_colors / yang_colors; a factor, character, or logical column (including computed expressions such as factor(week)) gets a discrete scale_fill_manual whose palette is interpolated from the same color vectors. With the default vectors the discrete palette skips the palest end of the ramp so that no category is invisible on a white panel; an explicitly supplied color vector is used as-is. Supply yin_scale / yang_scale to override the automatic choice entirely.

Because the choice is made when the layer is added, replacing the plot's data afterwards keeps the scales picked for the original data. Swapping in data of the same types is fine; if the new yin / yang columns are of the other kind, ggplot2 reports a "Discrete value supplied to a continuous scale" (or the reverse) at draw time — rebuild the plot rather than substituting its data.

Eyes

eyes = TRUE draws the classic taichi dots, each sitting in its own fish's head: the yin eye in the top bulb, the yang eye in the bottom bulb. The size and colour arguments accept either a constant or an (unquoted) data column, so the eyes can encode up to two further variables. A mapped eye-size column is rescaled to radii between 0.05 and 0.3 of the glyph radius, unless all its non-zero values already lie in (0, 0.5], in which case they are used directly as radius proportions. Cells whose eye size is NA or 0 are drawn without an eye, so a column may mix proportions with zeros to suppress individual eyes. A column whose values are all equal gets the midpoint radius, 0.175.

Styling

alpha, colour, linewidth and linetype are layer-wide constants here. Each has a concrete default, so geom_taichi() always passes it to both fish layers as a parameter, and a parameter takes precedence over an inherited mapping: a plot-level aes(linewidth = ...) (or alpha, colour, linetype) has no effect on the glyphs. To drive one of those from a column, build the layers yourself with geom_yin_fish() / geom_yang_fish(), which take all four as ordinary aesthetics.

width and height behave differently, because they default to NULL and are forwarded only when you actually supply them: a plot-level aes(width = ...) does size the cells per row. So the data-driven channels of geom_taichi() are yin, yang, angle, the two eyes, and width / height via aes().

Missing values

A fish whose fill value is NA is painted in the scale's na.value colour (pass e.g. na.value = "transparent" through ... to change it), while na.rm = TRUE silently drops rows with missing positions.

Examples

library(ggplot2)

# taichi with numeric fills

data <- data.frame(x = rep(c(1, 2, 3), 3),
                   y = rep(c(1, 2, 3), each = 3),
                   yin_values = 1:9,
                   yang_values = 9:1)

ggplot(data, aes(x, y)) +
  geom_taichi(yin = yin_values,
              yang = yang_values)

# categorical (discrete) fills are detected automatically

data$yin_class <- rep(c("low", "mid", "high"), 3)

ggplot(data, aes(x, y)) +
  geom_taichi(yin = yin_class,
              yang = yang_values)

# classic eyes, rotation, and data-driven eye sizes

ggplot(data, aes(x, y)) +
  geom_taichi(yin = yin_values,
              yang = yang_values,
              eyes = TRUE,
              yin_eye_size = yang_values,
              angle = 45)

The individual taichi fish layers

Description

'geom_yin_fish()' and 'geom_yang_fish()' each draw one of the two interlocking fish of a taichi symbol per '(x, y)' cell. They are the building blocks that [geom_taichi()] assembles (together with two fill scales and a [ggnewscale::new_scale_fill()] break); use them directly when you want full control — e.g. to bring your own fill scale for a single fish, to stack scales differently, or to draw only one source.

Usage

geom_yin_fish(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  width = NULL,
  height = NULL,
  eyes = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

geom_yang_fish(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  width = NULL,
  height = NULL,
  eyes = FALSE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

Both geoms understand the aesthetics 'x', 'y', 'fill', 'colour', 'linewidth', 'linetype', 'alpha', 'width', 'height', 'angle' (degrees, counter-clockwise), 'eye_size', and 'eye_colour' (the latter two only matter when 'eyes = TRUE'). At 'angle = 0' the yin fish is the left half of the circle plus the top bulb (its head); the yang fish is the right half plus the bottom bulb.

Value

A ggplot2 layer drawing one fish per cell.

Examples

library(ggplot2)
d <- data.frame(x = 1:3, y = 1, value = 1:3)

# a yin-only plot with an ordinary fill scale
ggplot(d, aes(x, y)) +
  geom_yin_fish(aes(fill = value)) +
  scale_fill_viridis_c()

# both fish, manually stacked with ggnewscale
ggplot(d, aes(x, y)) +
  geom_yin_fish(aes(fill = value)) +
  scale_fill_viridis_c(name = "yin") +
  ggnewscale::new_scale_fill() +
  geom_yang_fish(aes(fill = rev(value))) +
  scale_fill_viridis_c(name = "yang", option = "magma")

ggtaichi's ggproto classes

Description

The [ggplot2::ggproto()] objects powering [geom_yin_fish()] and [geom_yang_fish()]. Exported so that extension packages can inherit from them; most users never need to touch these.

Popular Emojis

Description

The most popular emoji of a given week in a given category from the Meltwater Tweet sample, as HTML <img> tags. The vector is aligned row-for-row with pitts_tg, so pitts_emojis[i] is the emoji for the week / category combination in row i of that data set. The tags are meant to be drawn as rich text, e.g. with ggtext::geom_richtext() or annotate("richtext", ...).

Usage

pitts_emojis

Format

A character vector of 270 HTML <img> tags (90 distinct emoji), one per row of pitts_tg.

Note on the image URLs

Each tag points at a remotely hosted PNG on the Emojipedia asset host used when the data was collected in 2020. Those objects are no longer served publicly, so the tags no longer render as pictures on their own. The emoji each tag refers to is still readable from its file name, which ends in the Unicode code point (for example thinking-face_1f914.png is U+1F914); substitute your own image paths or the literal emoji characters to draw them.

Source

The most frequent emoji per week and category in the Meltwater Twitter sample described in pitts_tg, processed by the package author.

Pittsburgh COVID-related Google & Twitter incidence rates

Description

A data set containing the 30-week incidence rates of COVID-related categories in the Pittsburgh Metropolitan Statistical Area (MSA), from week 1 beginning June 1, 2020 to week 30, which ended on the last Sunday of the year. The data columns are introduced below. One quick note about the columns of the data set: week_start is present for illustration purposes, as a reminder of what the week column counts. In other words, it does not participate in any visualization.

Usage

pitts_tg

Format

A data frame with 270 rows and 6 columns:

msa

Metropolitan statistical area (Pittsburgh only).

week

week 1 to week 30.

week_start

The Monday date of the week started.

category

One of 9 COVID-related categories: Covid, General Virus, Masks, Sanitizing, Social Distancing, Symptoms, Tests, Treatment, Working.

Twitter

weekly tweets percentage (%) in the MSA falling into each category.

Google

weekly Google search percentage (%) in the MSA falling into each category.

Source

Just like states_tg, Google is processed from Google Health API, and Twitter from Meltwater, a Twitter vendor. Both data sources are processed by the author of the package.

Remove ggplot2 default padding

Description

ggplot2 pads both continuous and discrete axes with a little expansion, which can make a taichi grid look like it is floating. 'remove_padding()' trims that space. Called with no arguments it inspects the plot it is added to and figures out for itself whether each axis is continuous or discrete; pass '"c"' (continuous) or '"d"' (discrete) explicitly to override the detection, e.g. when the axis mapping is a computed expression the plot data cannot answer for.

Usage

remove_padding(x = NULL, y = NULL, ...)

Arguments

Value

An object that, added to a ggplot, replaces both position scales with padding-free ones.

Examples

library(ggplot2)
d <- data.frame(x = 1:3, y = c("a", "b", "c"), yin = 1:3, yang = 3:1)

# auto-detects x as continuous and y as discrete
ggplot(d, aes(x, y)) +
  geom_taichi(yin = yin, yang = yang) +
  remove_padding()

# explicit override, identical result here
ggplot(d, aes(x, y)) +
  geom_taichi(yin = yin, yang = yang) +
  remove_padding(x = "c", y = "d")

States' COVID-related Google & Twitter incidence rates

Description

A data set containing the 31-week incidence rates of COVID-related categories in 4 states (Florida, Missouri, New York, and Texas), from week 1 beginning June 1, 2020 to week 31, which begins December 28, 2020 and so runs a few days past the end of the year. The data columns are introduced below. One quick note about the columns of the data set: week_start is present for illustration purposes, as a reminder of what the week column counts. In other words, it does not participate in any visualization.

Usage

states_tg

Format

A data frame with 1116 rows and 6 columns:

state

One of the four states: Florida, Missouri, New York, Texas.

week

week 1 to week 31.

week_start

The Monday date of the week started.

category

One of 9 COVID-related categories: Covid, General Virus, Masks, Sanitizing, Social Distancing, Symptoms, Tests, Treatment, Working.

Twitter

weekly tweets percentage (%) in state falling into each category.

Google

weekly Google search percentage (%) in state falling into each category.

Source

Just like pitts_tg, Google is processed from Google Health API, and Twitter from Meltwater, a Twitter vendor. Both data sources are processed by the author of the package.

Plot Themes

Description

A light theme tuned for the taichi grid: it bottoms the legends, drops the panel grid and axis ticks, and gives the canvas a soft off-white background reminiscent of rice paper.

Usage

theme_taichi(
  base_size = 11,
  base_family = "",
  base_line_size = base_size/22,
  base_rect_size = base_size/22
)

Arguments

Value

A theme object that can be added to any ggplot, in the same way as theme_bw().

Opinionated choices

Two of the theme's settings surprise people often enough to be worth spelling out. The y axis title is blanked, on the assumption that the y axis of a taichi grid is a list of category names that already reads as a label — so labs(y = "...") has no visible effect under this theme. Legend text is rotated 90 degrees, which keeps a wide continuous legend from running off the bottom of the plot. Both are ordinary theme elements, so add a theme() call afterwards to put them back:

  + theme_taichi() + theme(axis.title.y = element_text(),
                          legend.text = element_text(angle = 0))

Examples

library(ggplot2)
d <- data.frame(x = 1:3, y = 1:3, yin = 1:3, yang = 3:1)

ggplot(d, aes(x, y)) +
  geom_taichi(yin = yin, yang = yang) +
  theme_taichi()