knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

Dashboard Tiles, also named Notecards, are a great way to visualize key numbers. They can emphasize results in an easily digestible and colorful format. This package is a more fully featured alternative to infoboxes and valueboxes available from flexdashboard and shinydashboards.

This package uses Twitter's Bootstrap CSS files to provide pleasant aesthetics to the tiles. These buttons are good for embedding in static reports, in Rmd files, and Shiny dashboards. This page will show you how to use the main features of these tiles.

Getting Started

Install the TileMaker package from Github as follows:

# install.packages("TileMaker") ## soon!
devtools::install_github("DataStrategist/TileMaker")
library(TileMaker)

Let's start small:

Solo Box

The solo_box function allows to create a simple colored box.

solo_box(value = 3.3, txt = "My metric")


The solo_box function represents one key value, and should be used to demonstrate an important number inyour reports. There are many ways we can customize this tile, for example:

solo_box(
  value = 42, txt = "My metric", former = 99, size = "lg", icon = "check",
  color = "warning", link = "https://google.com", units = "kg", hover = "Warning reason", textModifier = "h3"
)


Not only can you see many more details, but if you rest your mouse over the button, you should see the text "Warning reason" appear.

Icons

Icons are available using Glyphicons.

div_maker(
  subtitle = "One pic is worth a thousand words", textModifier = "h3",
  solo_box(value = 3.3, txt = "envelope", icon = "envelope"),
  solo_box(value = 3.3, txt = "pushpin", icon = "pushpin"),
  solo_box(value = 3.3, txt = "calendar", icon = "calendar")
)


Click the link above for a full list of available icons. As you can see above, only the name of the icon needs to be supplied, ie "envelope", rather than "gyphicon-envelope".

Size

div_maker(
  subtitle = "supersize it!", textModifier = "h4",
  solo_box(value = 3.3, txt = "extra small", size = "xs"),
  solo_box(value = 3.3, txt = "small", size = "sm"),
  solo_box(value = 3.3, txt = "medium", size = "md"),
  solo_box(value = 3.3, txt = "large", size = "lg")
)


(Don't worry about the div_maker function for now, it'll be explained later, but for now we're using it to "tie" multiple icons together).

Color

The color argument controls the type of box which dictates the color.

By default, Bootstrap Version 3 is used. 6 colors of boxes are available. It can be customised to use boostrap 4.

div_maker(
  subtitle = "... all the colors of a rainbow", textModifier = "h3",
  solo_box(value = 3.3, txt = "Default", color = "default"),
  solo_box(value = 3.3, txt = "Primary", color = "primary"),
  solo_box(value = 3.3, txt = "Success", color = "success"),
  solo_box(value = 3.3, txt = "Info", color = "info"),
  solo_box(value = 3.3, txt = "Warning", color = "warning"),
  solo_box(value = 3.3, txt = "Danger", color = "danger")
)


solo_box(value = NULL, txt = "Watch the case sensitivity of the color argument!", color = "warning")

Let's go solo_gradient_box!!!

The solo_gradient_box function lets us set targets and limits, and then changes the color depending on the value. Therefore, if a value is high, it'll be green, if it's "medium" it'll be orange, or if it's low, then it'll be red. By default, the target is set to 100 and thresholds are set to 50 and 90, although these are customizeable.

div_maker(
  subtitle = "Default gradients", textModifier = "h4",
  solo_gradient_box(value = 95, txt = "Grade 1"),
  solo_gradient_box(value = 80, txt = "Grade 2"),
  solo_gradient_box(value = 40, txt = "Grade 3")
)


All of these limits are customizeable, so we can change the target or the thresholds (thresholdHigh and thresholdLow). The color is then determined by comparing value/target * 100 to the thresholds.

div_maker(
  subtitle = "Playing with the thresholds", textModifier = "h4",
  solo_gradient_box(value = 24, txt = "Grade 1", target = 50),
  solo_gradient_box(value = 25, txt = "Grade 2", target = 50),
  solo_gradient_box(value = 44, txt = "Grade 2", target = 50),
  solo_gradient_box(value = 45, txt = "Grade 3", target = 50)
)


The arguments thresholdHigh and thresholdLow can be used to change when the values change color from green to orange and from orange to red respectively. For example, the value 95 was used above and had a green color (because the default thresholdHigh of 90 was used), but if we change the thresholdHigh to 96, we see that a value of 95 is still orange.

solo_gradient_box(value = 95, txt = "Customized<br>threshold", thresholdHigh = 96)


By the way, the <br> element in the text argument above forces a line break. Text accepts full html code, natively written.

It's your turn, multi_box!

The multi_box function takes multiple values in one button, providing an easy way to summarize "a few" key values together. I say "a few"... if it's more than 5 perhaps a line or bar chart starts becoming more appropriate? Of course that's a style thing and everybody has their own opinions. Anyways, here's the multi_box:

multi_box(values = c(4, 5, 6), txt = c("Sally", "George", "Mohammed"), icons = c("check", "plus", "calendar"), title = "Candidates")


As you can see, each entry can have it's own icon. The color is not dependant on any value as that would perhaps be confusing. It can be changed manually if desired.

Last but not least, here's the tile_matrix

The tile_matrix function creates several new solo_gradient_boxes and compiles them all into a grid, but the best part about it is that it takes a data.frame or a tibble as input.

suppressPackageStartupMessages(library(dplyr))

df <- tibble(
  values = c(2, 5, 6),
  txt = c("Sally", "George", "Mohammed")
)
tile_matrix(df, values = values, txt = txt, target = 10, thresholdHigh = 60, thresholdLow = 40, textModifier = "h2")

The function takes a dataframe as first value and as such can be used in a tidyverse pipe. For example:

mtcars %>%
  # name of car model is contained in the rowname 
  mutate(names = rownames(.)) %>%
  # let's just take 8 entries:
  sample_n(8) %>% 
  tile_matrix(
    values = "disp", txt = "names",
    target = 400, thresholdHigh = 80, thresholdLow = 50
  )


The concept of the tile_matrix is to provide a quick way to visualize one feature of the dataset. The fact that the thresholds scales automatically to the target is useful, since one need only set the target in order to quickly obtain actionable information.

The number of tiles per column is 4 by default, but is customizeable using the cols argument.

Another example, if one wanted to quickly see average diamond prices by cut, we could do so easily:

library(ggplot2)
diamonds %>% 
  group_by(cut) %>%
  summarize(price = mean(price)) %>%
  tile_matrix(data = ., values = price, txt = cut, target = 4500, roundVal = 0, cols = 5)


Comparing against a former version?

What if we had former diamond prices for the above tileset? Well, we could use the former argument to quickly show if there's an increase or a decrease:

library(ggplot2)
diamonds %>% 
  group_by(cut) %>%
  summarize(price = mean(price)) %>%
  ## Assume there was some former price that was a bit different
  mutate(old_price = price * (1 * runif(n = 5, min = 0.95, max = 1.05))) %>%
  tile_matrix(data = ., values = price, txt = cut, former = old_price, target = 4500, roundVal = 0, cols = 5)


So what exactly does former do? It contextualizes the displayed value in comparison with a former value for that same tile. This is especially useful to measure growth of a metric. In order to show the functionality, let's use a quite contrived scenario in which valuesw range from 1 to 100, but in all cases, the former value was 50. See how the number in the top right corner changes:

suppressPackageStartupMessages(library(dplyr))
df <- tibble(
  values = seq(from = 0, to = 100, by = 10),
  txt = "comparison to 50",
  former = 50
)

## Let's pretend that all previous values were 50... so:
tile_matrix(data = df, values = values, txt = txt, former = former, target = 1000)


Important note: the color changes on the value, not on the former. For now I've forced the boxes to be red by having a high target, but just be clear on what the color is showing in real situations.

Grammar of Tiles

There are a few more bits and bobs, but that's the main features! All that's left is to discuss how to group tiles. For that we have two functions: div_maker and the bluntly named finisher. Individual tiles are put into a div_maker in order to group them in a row, and then those div_maker objects are put into a finisher call to create one object. The finished tile-set either creates a visible block of code or can be saved to a file for convenience by setting the file argument to NULL. Here is a "real-world" example:

Value1 <- 88
Value2 <- 1985
Value3 <- 1.22
Value4 <- 30
Value5 <- 42

## Make the buttons how you like
Button1 <- solo_box(value = Value1, txt = "Speed", units = "mph", color = "danger")
Button2 <- solo_box(value = Value2, txt = "Origin", color = "warning", icon = "flash")
Button3 <- solo_gradient_box(
  value = Value3, txt = "Powah", units = "GW", hover = "Great Scott!",
  target = 1.22, thresholdHigh = 100, thresholdLow = 99
)
Button4 <- solo_box(value = Value4, txt = "Heads turned", units = "K", color = "info")
Button5 <- solo_box(
  value = Value5, txt = "Answer", hover = "Whales rule. Petunias suck",
  link = "https://en.wikipedia.org/wiki/The_Hitchhiker%27s_Guide_to_the_Galaxy", color = "primary"
)

## Combine in 2 rows:
Div1 <- div_maker(subtitle = "Future", textModifier = "h2", Button1, Button2, Button3)
Div2 <- div_maker(subtitle = "Effect", textModifier = "h2", Button4, Button5)

## Now put them all together:
finisher(
  title = "Important block", css = "https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css",
  file = NULL, textModifier = "h1", div_maker(subtitle = "Back to the Future", textModifier = "hi",Div1, Div2)
)


Help! My report broke!

The tilemaker package works by porting bootstrap functionality and controlling the HTML element within. It may affect others elements of your webpage.

A few features are included to try to prevent these effects:

  1. Most of the time, wrapping your buttons or groups of buttons in div_makers, and/or in finishers can be effective.
  2. In some cases, for example in markdown documents that include a Table of Contents, format depends of previous html elements. It is advised to then change the textModifier option. You can change the textModifier from the default h1 to h4 or <br> or anything you think might work in your report.

If you need help not covered here, please use the Issues page.



DataStrategist/TileMaker documentation built on Feb. 1, 2022, 9:29 p.m.