gghinton: Hinton Diagrams for 'ggplot2'

Description

Provides a 'ggplot2' extension for drawing Hinton diagrams, a visualisation technique for numerical matrices in which the area of each square is proportional to the magnitude of the corresponding entry. For signed data, white squares indicate positive values and black squares indicate negative values on a grey background. Hinton diagrams are especially useful for visualising PCA weight matrices, correlation matrices, and transition matrices.

Author(s)

Maintainer: Robin Foster gghinton@proton.me [copyright holder]

See Also

Useful links:

• https://github.com/robin-foster-rf/gghinton

• Report bugs at https://github.com/robin-foster-rf/gghinton/issues

Hinton diagrams for ggplot2

Description

geom_hinton() draws a Hinton diagram: a grid of squares whose area is proportional to the magnitude of each value. For signed data, positive values are shown as white squares and negative values as black squares on a grey background. For unsigned (non-negative) data the background is omitted and squares are drawn in black.

Usage

geom_hinton(
  mapping = NULL,
  data = NULL,
  stat = "hinton",
  position = "identity",
  ...,
  scale_by = c("panel", "global"),
  background = TRUE,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

stat_hinton(
  mapping = NULL,
  data = NULL,
  geom = "hinton",
  position = "identity",
  ...,
  scale_by = c("panel", "global"),
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Arguments

Value

A ggplot2 layer that can be added to a ggplot2::ggplot() object.

Aesthetics

geom_hinton() understands the following aesthetics (required aesthetics are in bold):

• x: column position (numeric or factor)

• y: row position (numeric or factor)

• weight: the value to display; determines square size and colour

• alpha

• colour (border colour; NA by default, no border)

• fill (overrides the automatic sign-based colour)

• linewidth

• linetype

Computed variables

stat_hinton() adds the following columns to the data:

xmin, xmax, ymin, ymax

Rectangle bounds for each square.

fill

"positive", "negative", or "unsigned".

hinton_signed

Logical; TRUE when the panel contains any negative values. Read by GeomHinton to decide whether to draw the grey background (after scale_fill_hinton() has already replaced the fill labels, making fill == "negative" checks unreliable).

cell_w, cell_h

Inferred cell spacing used to size the background.

Aspect ratio

For squares to appear as squares on screen, add coord_fixed() to your plot. Without it, the cells may appear rectangular if the plot's x and y axes have different scales.

Examples

library(ggplot2)
m <- matrix(c(0.8, -0.3, 0.5, -0.9, 0.1, 0.6, 0.4, -0.7, 0.2), 3, 3)
df <- matrix_to_hinton(m)

ggplot(df, aes(x = col, y = row, weight = weight)) +
  geom_hinton() +
  scale_fill_hinton() +
  coord_fixed() +
  theme_hinton()

English character bigram counts from Alice's Adventures in Wonderland

Description

A 27x27 integer matrix of character-pair (bigram) counts computed from the full text of Alice's Adventures in Wonderland by Lewis Carroll (1865). The source text is Project Gutenberg item 11 (public domain).

Usage

alice_bigrams

Format

A 27 x 27 integer matrix. Row names and column names are c(letters, " ").

Details

The 27 characters are the 26 lower-case letters a-z plus a space character (represented as " "). Non-letter characters in the original text (punctuation, digits, newlines) are ignored, and runs of multiple spaces are collapsed to one before counting.

alice_bigrams[x, y] gives the number of times character x is immediately followed by character y in the processed text.

Source

Project Gutenberg, https://www.gutenberg.org/ebooks/11. Downloaded and processed by data-raw/alice_bigrams.R.

Examples

# Most common bigrams
tail(sort(alice_bigrams), 10)

# "th" count
alice_bigrams["t", "h"]

# Visualise as a Hinton diagram
df <- matrix_to_hinton(alice_bigrams / sum(alice_bigrams))

ggplot2::ggplot(df, ggplot2::aes(x = col, y = row, weight = weight)) +
  geom_hinton() +
  scale_fill_hinton() +
  ggplot2::coord_fixed() +
  theme_hinton()

Convert an object to a tidy data frame for geom_hinton()

Description

Generic function that dispatches to a method appropriate for x. Built-in methods exist for matrix, data.frame, and table.

Usage

as_hinton_df(x, ...)

## S3 method for class 'matrix'
as_hinton_df(x, ...)

## S3 method for class 'data.frame'
as_hinton_df(
  x,
  rowname_col = "row",
  colname_col = "col",
  value_col = "weight",
  ...
)

## S3 method for class 'table'
as_hinton_df(x, ...)

## Default S3 method:
as_hinton_df(x, ...)

Arguments

Value

A data frame suitable for use with geom_hinton().

Examples

m <- matrix(c(1, -2, 3, -4), 2, 2)
as_hinton_df(m)

t <- table(c("a","b","a"), c("x","y","x"))
as_hinton_df(t)

Convert a matrix to a tidy data frame for use with geom_hinton()

Description

Reshapes a numeric matrix into a long-form data frame with one row per matrix entry. Row 1 of the matrix is placed at the top of the resulting plot (highest y value), matching the visual convention of matrix notation.

Usage

matrix_to_hinton(
  x,
  rowname_col = "row",
  colname_col = "col",
  value_col = "weight"
)

Arguments

Value

A data frame with columns named by rowname_col, colname_col, and value_col. If x has row or column names, additional columns row_label and col_label are included.

Examples

m <- matrix(c(0.8, -0.3, 0.5, -0.9, 0.1, 0.6), nrow = 2)
matrix_to_hinton(m)

# Named matrix
rownames(m) <- c("a", "b")
colnames(m) <- c("x", "y", "z")
matrix_to_hinton(m)

Colour scale for Hinton diagrams

Description

Maps the sign-encoding produced by stat_hinton() to the conventional Hinton colour scheme: white for positive values, black for negative values. For unsigned data (all non-negative), all squares are drawn in black.

Usage

scale_fill_hinton(..., values = NULL, guide = "none")

Arguments

Details

This scale is a thin wrapper around ggplot2::scale_fill_manual() with the default legend suppressed. Pass guide = "legend" to restore the legend, or override the values argument to use custom colours.

Value

A ggplot2 scale object.

Examples

library(ggplot2)
m <- matrix(c(0.8, -0.3, 0.5, -0.9, 0.1, 0.6), 2, 3)
df <- matrix_to_hinton(m)

ggplot(df, aes(x = col, y = row, weight = weight)) +
  geom_hinton() +
  scale_fill_hinton() +
  theme_hinton()

A clean ggplot2 theme for Hinton diagrams

Description

Removes grid lines, axis ticks, and panel background, all of which visually interfere with the squares in a Hinton diagram. The grey background for signed diagrams is drawn by geom_hinton() itself and is not affected by this theme.

Usage

theme_hinton(base_size = 11, base_family = "")

Arguments

Value

A ggplot2 theme object.

Examples

library(ggplot2)
m <- matrix(c(0.8, -0.3, 0.5, -0.9, 0.1, 0.6), 2, 3)
df <- matrix_to_hinton(m)

ggplot(df, aes(x = col, y = row, weight = weight)) +
  geom_hinton() +
  scale_fill_hinton() +
  theme_hinton()