An Introduction to Yamlet

Manual Method

Actually, yamlet (think: “just a little yaml”) is a special case of yaml that stores column attributes in one record per column. For instance, to store the fact that data for an imaginary drug trial has a column called ‘ID’, pop open a text file and write

ID:

This in itself is valid yaml! But if you know a label to go with ID, you can add it:

ID: subject identifier

If you have (or expect) a second column with units, you can add it below.

ID: subject identifier
CONC: concentration, ng/mL

A couple of notes here.

• The first thing after a colon must be a space.
• Whatever follows the colon-space is only One Thing.
• That One Thing could be a sequence of Many Things.

To get a sequence, just add square brackets. For instance, above we have said that ‘CONC’ has the label ‘concentration, ng/mL’ but what we really intend is that it has label ‘concentration’ and unit ‘ng/mL’ so we rewrite it as

ID: subject identifier
CONC: [ concentration, ng/mL ]

Now label and units are two different things. Notice we have not explicitly named them. Unless we say otherwise, the yamlet package will treat the first two un-named items as ‘label’ (a short description) and ‘guide’ (a hint about how to interpret the values). ‘guide’ might be units for continuous variables, levels (and possibly labels) for categorical values, format strings for dates and times, or perhaps something else.

The yamlet package gives you five ways of controlling how data items are identified (see details for ?as_yamlet.character). The most direct way is to supply explicit yaml keys:

ID: [ label: subject identifier ]
CONC: [ label: concentration, guide: ng/mL ]

We see that rather complex data can be expressed using only colons, commas, and square brackets. yaml itself also uses curly braces to express “maps”, but for purposes here they are unnecessary.

Note above that we had to add square brackets for ‘ID’ when introducing the second colon (can’t really have two colons at the same level, so to speak). Note also that sequences can be nested arbitrarily deep. We take advantage of this principle to transform ‘guide’ into a set of categorical levels.

ID: [ label: subject identifier ]
CONC: [ label: concentration, guide: ng/mL ]
RACE: [ label: race, guide: [ 0, 1, 2 ]]

or more simply (taking advantage of default keys)

ID: subject identifier
CONC: [ concentration, ng/mL ]
RACE: [ race, [ 0, 1, 2 ]]

So now we have ‘codes’ (levels) for our dataset that represent races. What do these codes mean? We supply ‘decodes’ (labels) as keys.

ID: subject identifier
CONC: [ concentration, ng/mL ]
RACE: [ race, [ white: 0, black: 1, asian: 2 ]]

Elegantly, yaml (and therefore yamlet) gives us a way to represent a code even if we don’t know the decode, and a way to represent a decode even though we don’t know the code. Imagine a dataset is under collaborative development, and we already know that there are some ‘RACE’ values of 0 but we’re not sure what they mean. We also know that there will be some ‘asian’ race values, but we haven’t assigned a code yet. We can write:

ID: subject identifier
CONC: [ concentration, ng/mL ]
RACE: [ race, [ 0, black: 1, ? asian ]]

Automatic Method

The whole point of this exercise (and I’m getting a little ahead of myself) is to have some stored metadata that we can read into R and apply to a data frame as column attributes. If typing square brackets isn’t your thing, you can actually do this backwards by supplying column attributes to a data frame and writing them out!

suppressMessages(library(dplyr))
library(magrittr)
library(yamlet)
x <- data.frame(
  ID = 1, 
  CONC = 1,
  RACE = 1
)

x$ID %<>% structure(label = 'subject identifier')
x$CONC %<>% structure(label = 'concentration', guide = 'ng/mL')
x$RACE %<>% structure(label = 'race', guide = list(white = 0, black = 1, asian = 2))

x %>% as_yamlet %>% as.character %>% writeLines
#> ID: subject identifier
#> CONC: [ concentration, ng/mL ]
#> RACE: [ race, [ white: 0, black: 1, asian: 2 ]]

# or

x %>% as_yamlet %>% as.character %>% writeLines(file.path(tempdir(), 'drug.yaml'))

Example Figure

For example, The yamlet package provides an experimental wrapper for ggplot that uses column attributes to automatically generate informative axis labels and legends.

suppressWarnings(library(ggplot2))
library(dplyr)
library(magrittr)
file <- system.file(package = 'yamlet', 'extdata','quinidine.csv')

file %>% 
  decorate %>% 
  filter(!is.na(conc)) %>% 
  resolve %>%
  ggplot(aes(x = time, y = conc, color = Heart)) + 
  geom_point()

Automatic axis labels and legends using curated metadata as column attributes.

Example Table

The table1 package uses labels and units stored as attributes to enrich table output. In the example below, we use resolve() to re-implement guides as units and factor levels, which is what table1() needs.

suppressMessages(library(table1))
file %>%
  decorate %>% 
  resolve %>% 
  group_by(Subject) %>%
  slice(1) %>%
  table1(~ Age + Weight + Race | Heart, .)