---
title: "Yamlet Plot Aesthetics"
author: "Tim Bergsma"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Yamlet Plot Aesthetics}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

## Behavior

Plotting a decorated data.frame in ggplot() has special behavior for aesthetics
defined using yamlet decorations.  If there is only one dataset (typical), the 
aesthetics are coordinated with the (levels of the) corresponding variable.

If one or more additional layers provide non-default data, a single set of
consensus decorations is accumulated, with each successive dataset overriding
all previous decorations where conflicts exist; then, consensus decorations
are enforced on all datasets.

## Example

In the example below, points are plotted using the observed data, then 
summary data is plotted as a separate layer, supplying its own data.
the plot is rendered _without_ decorations (left) and _with_ decorations (right).


```{r message = FALSE}
#| label: Layered Aesthetics
#| fig.width: 5.02
#| fig.height: 3.28

library(magrittr)
library(ggplot2)
library(yamlet)
library(dplyr)
library(metaplot)

set.seed(10)
obs <- data.frame(
  time = 1:100,
  group = c('a','b'),
  concentration = rnorm(100)
)

# observed data
obs %<>% decorate('
  time: [ Time, h ]
  concentration: [ Concentration, ng/mL ]
  group: [ 
    Group, 
    [ a, b ], 
    color: [ green, yellow ] , 
    linetype: [ dashed, dotdash ]
  ]
')

# summary data
sum <- obs %>% group_by(group) %>% summarize(mean = mean(concentration))
sum %<>% undecorate %>% decorate('
  group: [ 
    Subset, 
    [ a, b ], 
    color: [ blue, magenta ], 
    shape: [ 15, 19 ]
  ]
')


q <- obs %>%
  undecorate %>%
  ggplot(aes(time, concentration)) +
  geom_point(aes(color = group, shape = group)) +
  geom_hline(
    data = undecorate(sum), 
    aes(
      yintercept = mean, 
      color = group, 
      linetype = group
    )
  ) + 
  theme(legend.position = "top") +
  labs(subtitle = 'without decorations') +
  symmetric()

p <- obs %>%
  resolve %>%
  ggplot(aes(time, concentration)) +
  geom_point(aes(color = group, shape = group)) +
  geom_hline(
    data = resolve(sum), 
    aes(
      yintercept = mean, 
      color = group, 
      linetype = group
    )
  ) + 
  theme(legend.position = "top") +
  labs(subtitle = 'with decorations') + 
  symmetric()


multiplot(q, p) # %>% devsize(2,2)
```

 * Notice that the label (on the right) for color and shape is 'Subset', not 'Groups',
   because the last layer wins.
 * Likewise, colors are blue and magenta, not green and yellow, because the 
   summary layer was supplied last.
 * The summary layer respects the linetype defined earlier, having
   no such decoration in its own data.
 * The observations layer respects the shapes defined with the summary
   layer, which in fact are not even used by the summary layer.
   
This example is a bit contrived for heuristic value. 
As a best practice, consider specifying all aesthetics in the default data only.

```{r}
sessionInfo()
```