type = "tile" (alias "heatmap"

[grantmcdermott]

Closes #665

Some quick examples from the documentation:

# library(tinyplot)
pkgload::load_all("~/Documents/Projects/tinyplot/")
#> ℹ Loading tinyplot

# It is recommended to use the dedicated "heatmap" theme for this type
tinytheme("heatmap")

# Correlation matrix of the base `attitude` dataset in "long" form.
catt = as.data.frame(as.table(cor(attitude)), responseName = "Correlation")

tinyplot(Var1 ~ Var2 | Correlation, data = catt, type = "tile")

# slightly fancier version, where we suppress the legend but layer on the values
# as text
tinyplot(
  Var1 ~ Var2 | Correlation, data = catt,
  type = "tile",
  legend = FALSE,
  xlab = NA, ylab = NA,
  main = "Correlation matrix of base attitude dataset"
)
tinyplot_add(type = "text", labels = round(catt$Correlation, 2), col = "white")

# aside: "heatmap" is an alias for "tile"
tinyplot(Var1 ~ Var2 | Correlation, data = catt, type = "heatmap")

# Pass scaled tile widths and heights through type_tile() for a gridded look
tinyplot(
  Var1 ~ Var2 | Correlation, data = catt,
  type = type_tile(width = 0.9, height = 0.9)
)

# default palette is tealgrnn, but easy to pass through a diverging scale if
# your dataset recommends it
m = as.data.frame(as.table(cor(mtcars)), responseName = "Correlation")
tinyplot(
  Var1 ~ Var2 | Correlation, data = m, type = "heatmap",
  palette = "tealrose", col = "white" # white rect borders (optional)
)

# restore theme
tinytheme()

[zeileis]

Some very quick feedback only based on the examples above. (I didn't have time to look at the code or try the examples myself, yet.)

• I like the name "tile" because I feel "heatmap" is too ambiguous.
• Possibly a future "bkde" plot could just set up the data in the format needed and then plot it via "tile".
• What happens if the same tile position is specified multiple times in the data? Are they simply overplotted?
• It might be important to control the mapping of the tile values to the tile colors. For example when plotting correlations, the center color of the diverging palette must be exactly at zero.
• When plotting correlation heatmaps the y-axis would usually be sorted top-down rather than bottom-up in order to match the layout of the matrix. Should this be handled by the user when preparing the data for plotting or should there be some convenience option for it?

[grantmcdermott]

Thanks for the quick feedback @zeileis.

• I like the name "tile" because I feel "heatmap" is too ambiguous.

You mean you'd like to drop "heatmap" even as an alias?

• Possibly a future "bkde" plot could just set up the data in the format needed and then plot it via "tile".

👍

• What happens if the same tile position is specified multiple times in the data? Are they simply overplotted?

Yes, we don't do any checks or transformations. (I think this is probably the right approach.)

• It might be important to control the mapping of the tile values to the tile colors. For example when plotting correlations, the center color of the diverging palette must be exactly at zero.

Agree, but I haven't really thought how we could do that. Unless I'm missing something, we'd need some custom logic on top of colorRamp and co.? Would welcome other ideas if this is something you've done before.

• When plotting correlation heatmaps the y-axis would usually be sorted top-down rather than bottom-up in order to match the layout of the matrix. Should this be handled by the user when preparing the data for plotting or should there be some convenience option for it?

Hmmm. The user can just pass x/ylim = "rev". I'm loathe to enable this by default, though since it would be messy trying to ID when to switch it off (e.g. non-correlation based heatmaps). But we could easily add an example to the docs.

[grantmcdermott]

• It might be important to control the mapping of the tile values to the tile colors. For example when plotting correlations, the center color of the diverging palette must be exactly at zero.

Agree, but I haven't really thought how we could do that. Unless, I'm missing something, we'd need some custom logic on top of colorRamp and co.? Would welcome other ideas if this is something you've done before.

Actually, an easy solution is just to identify the midpoint and then expand the limits symmetrically around that midpoint. BUT the trick is deciding how users should be able to pass through this midpoint to the palette (by limits) logic...

On reflection, I think that this issue should be tackled in a separate PR as part of additional palette customization entry point. Maybe a sister, top-level palette.args argument for capturing and splicing in additional palette functionality? (C.f., #299)

[zeileis]

I've been thinking about this some more and I agree that this should probably go into a separate issue/PR.

Is there currently the possibility to control the range of the by variable in the legend? I couldn't find one.

This would be another option to get the midpoint exactly at 0, namely by setting the by range to c(-1, 1).

This would be useful more generally, e.g., when I want to use exactly the same by color scale for separate plots. When I have a factor by variable this happens automatically but for a continuous by variable I don't know whether this is currently possible.

[zeileis]

Regarding the name: Yes, I would drop the "heatmat" alias as well.