Powered by AppSignal & Oban Pro

Colour steps: guide_coloursteps

notebooks/guide_coloursteps.livemd

Colour steps: guide_coloursteps

Mix.install([
  {:giggly, path: Path.join(__DIR__, "..")},
  {:kino, "~> 0.19"}
  ])

alias Giggly.Plot

render = fn plot ->
  plot
  |> Giggly.to_svg()
  |> IO.iodata_to_binary()
  |> Kino.Image.new(:svg)
end

About this notebook

This notebook follows the examples on ggplot2's reference page for guide_coloursteps(), which covers guide_colorsteps() too, in the order the page gives them. Each example shows ggplot2's code first and then Giggly's. An example Giggly cannot draw yet keeps its ggplot2 code and names what it is waiting for, so the page is also a list of what remains.

guide_coloursteps(), or guide_colorsteps() spelled the American way, is the legend of a binned colour or fill scale: a colour bar, as guide_colourbar() draws, but with each bin in one constant colour rather than a gradient. It is the default guide for binned colour scales. Giggly draws it at its defaults, guide: :colorsteps, the default guide of Giggly.Plot.scale_fill_binned/2 and the other binned colour and fill scales, which label the ends with the limits too for show_limits: true, but takes none of its options (guide_coloursteps() with its even.steps option). A plot is described with Giggly.Plot and drawn with Giggly.to_svg/2, which returns an SVG document. The setup cell aliases Giggly.Plot, so the cells write Plot.new/2, and defines render, which draws a plot and shows it below the cell with Kino.Image.

The default for binned colours

R's expand.grid() makes a row for every combination of X1 and X2 from 1 to 10, and value is their product.

df <- expand.grid(X1 = 1:10, X2 = 1:10)
df$value <- df$X1 * df$X2

p <- ggplot(df, aes(X1, X2)) + geom_tile(aes(fill = value))

# Coloursteps guide is the default for binned colour scales
p + scale_fill_binned()

The cell builds the same table, X1 changing fastest, as expand.grid() builds it.

pairs = for x2 <- 1..10, x1 <- 1..10, do: {x1, x2}

df = %{
  "X1" => Enum.map(pairs, fn {x1, _x2} -> x1 end),
  "X2" => Enum.map(pairs, fn {_x1, x2} -> x2 end),
  "value" => Enum.map(pairs, fn {x1, x2} -> x1 * x2 end)
}

p =
  df
  |> Plot.new(%{x: :X1, y: :X2})
  |> Plot.geom_tile(%{fill: :value})

p
|> Plot.scale_fill_binned()
|> render.()

Bins of equal size

# By default each bin in the guide is the same size irrespectively of how
# their sizes relate in data space
p + scale_fill_binned(breaks = c(10, 25, 50))
p
|> Plot.scale_fill_binned(breaks: [10, 25, 50])
|> render.()

Bins in proportion

# This can be changed with the `even.steps` argument
p + scale_fill_binned(
  breaks = c(10, 25, 50),
  guide = guide_coloursteps(even.steps = FALSE)
)

Not in Giggly yet: guide_coloursteps() with its even.steps option, which sizes each bin in the legend in proportion to its range in the data.

Showing the limits

# By default the limits is not shown, but this can be changed
p + scale_fill_binned(guide = guide_coloursteps(show.limits = TRUE))

# (can also be set in the scale)
p + scale_fill_binned(show.limits = TRUE)

Giggly draws the second plot, the scale's own show_limits: labelling the ends of the scale too.

p
|> Plot.scale_fill_binned(show_limits: true)
|> render.()

Not in Giggly yet: for the first plot, guide_coloursteps() with its show.limits option.