## -----------------------------------------------------------------------------
#| include: false
knitr::opts_chunk$set(collapse = TRUE, comment = "#>", fig.width = 7, fig.height = 4.5,
                      dpi = 96, out.width = "100%")


## -----------------------------------------------------------------------------
#| include: false
library(paintr)


## -----------------------------------------------------------------------------
m <- matrix(1:12, nrow = 3)
mask <- matrix(FALSE, nrow = 3, ncol = 4)
mask[2, ] <- TRUE
mask


## -----------------------------------------------------------------------------
#| fig-alt: "A 3 by 4 grid of the numbers 1 through 12 with its entire second row shaded, so the
#|   cells holding 2, 5, 8, and 11 are highlighted while the rest stay plain."
paint_matrix(m, highlight_area = mask)


## -----------------------------------------------------------------------------
#| fig-alt: "The same 3 by 4 grid of 1 through 12 with its first and third rows shaded, highlighting
#|   the cells 1, 4, 7, 10 and 3, 6, 9, 12 while the middle row stays plain."
paint_matrix(m, highlight_area = highlight_rows(m, c(1, 3)))


## -----------------------------------------------------------------------------
#| fig-alt: "The same 3 by 4 grid with its second and third columns shaded, highlighting the cells
#|   4, 5, 6 and 7, 8, 9."
paint_matrix(m, highlight_area = highlight_columns(m, 2:3))


## -----------------------------------------------------------------------------
#| fig-alt: "The same 3 by 4 grid with three individual cells shaded along a diagonal, the values 1,
#|   8, and 12 at positions [1, 1], [2, 3], and [3, 4], while every other cell stays plain."
points <- rbind(
  c(1, 1),
  c(2, 3),
  c(3, 4)
)
paint_matrix(m, highlight_area = highlight_locations(m, points))


## -----------------------------------------------------------------------------
#| fig-alt: "The same 3 by 4 grid with its first row and fourth column both shaded, so the
#|   highlighted cells form an L: 1, 4, 7, 10 across the top and 10, 11, 12 down the right edge,
#|   meeting at the corner value 10."
paint_matrix(m, highlight_area = highlight_data(m, rows = 1, columns = 4))


## -----------------------------------------------------------------------------
m > 4


## -----------------------------------------------------------------------------
#| fig-alt: "The same 3 by 4 grid with every cell greater than 4 shaded, highlighting the values 5
#|   through 12 while 1, 2, 3, and 4 stay plain; the shaded pattern is exactly the TRUE entries of
#|   the comparison m > 4."
paint_matrix(m, highlight_area = m > 4)


## -----------------------------------------------------------------------------
#| fig-alt: "The same grid with cells greater than 4 shaded, this time in light pink rather than the
#|   default pale yellow, showing that any R colour can fill the highlighted cells."
paint_matrix(m, highlight_area = m > 4, highlight_color = "lightpink")


## -----------------------------------------------------------------------------
#| fig-height: 5
#| fig-alt: "The first six rows of the iris data frame drawn as a table, with the whole Sepal.Width
#|   column shaded to pick it out by name from among Sepal.Length, Petal.Length, Petal.Width, and
#|   Species."
df <- head(iris, 6)
paint_data_frame(df, highlight_area = highlight_columns(df, "Sepal.Width"))


## -----------------------------------------------------------------------------
#| fig-alt: "A list drawn as three side-by-side columns headed $counts, $tags, and $ok of
#|   decreasing length, so the bottom edge is ragged; the $tags column, holding a, b, c, is shaded
#|   to select it by name just as a data frame column would be."
l <- list(counts = c(3, 1, 4, 1), tags = c("a", "b", "c"), ok = c(TRUE, FALSE))
paint_list(l, highlight_area = highlight_columns(l, "tags"))


## -----------------------------------------------------------------------------
#| fig-alt: "The 3 by 4 grid of 1 through 12 with every cell greater than 4 shaded, drawn through
#|   the ggplot2 backend; the highlight is identical to the base-graphics version above, since the
#|   mask is a property of the drawing, not the backend."
gpaint_matrix(m, highlight_area = m > 4)