---
title: "Customize plots"
author: "Benjamin Guiastrennec"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Customize plots}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
library(xpose)
xpdb <- xpdb_ex_pk %>%
vpc_data(opt = vpc_opt(n_bins = 7)) %>%
mutate(VAR = 1)
knitr::opts_chunk$set(fig.dpi = 96,
fig.align = 'center',
fig.height = 4,
fig.width = 4,
out.width = '50%',
comment = '',
message = FALSE)
```
### Plot type
The option `type` allows to control how the data should be represented.
#### Scatter plots
In scatter plots `type` can be any combination of: points `'p'`, lines `'l'`, smooth `'s'`, text `'t'`.
```{r demo type scatter, echo = FALSE, fig.height = 6, fig.width = 6, out.width = '75%'}
gridExtra::grid.arrange(
dv_vs_ipred(xpdb, title = "type = \'p\'", subtitle = NULL, caption = NULL, type = 'p'),
dv_vs_ipred(xpdb, title = "type = \'l\'", subtitle = NULL, caption = NULL, type = 'l'),
dv_vs_ipred(xpdb, title = "type = \'s\'", subtitle = NULL, caption = NULL, type = 's'),
dv_vs_ipred(xpdb, title = "type = \'t\'", subtitle = NULL, caption = NULL, type = 't'),
ncol = 2)
```
#### Distribution plots
In distribution plots `type` can be any combination of: histogram `'h'`, density `'d'`, or rug `'r'`.
```{r demo type distrib, echo = FALSE, fig.height = 3.2, fig.width = 6, out.width = '75%'}
gridExtra::grid.arrange(
res_distrib(xpdb, title = "type = \'h\'", subtitle = NULL, caption = NULL, type = 'h'),
res_distrib(xpdb, title = "type = \'d\'", subtitle = NULL, caption = NULL, type = 'd') + labs(y = NULL),
res_distrib(xpdb, title = "type = \'r\'", subtitle = NULL, caption = NULL, type = 'r'),
ncol = 3)
```
#### VPCs
In visual predictive checks plots `type` can be any combination of: areas `'a'`, lines `'l'`, points `'p'`, text `'t'` or rug `'r'`.
```{r demo type vpc, echo = FALSE, fig.height = 6, fig.width = 6, out.width = '75%'}
gridExtra::grid.arrange(
vpc(xpdb, title = "type = \'a\'", subtitle = NULL, caption = NULL, type = 'a') + theme(legend.position = 'none') ,
vpc(xpdb, title = "type = \'l\'", subtitle = NULL, caption = NULL, type = 'l') + theme(legend.position = 'none'),
vpc(xpdb, title = "type = \'p\'", subtitle = NULL, caption = NULL, type = 'p'),
vpc(xpdb, title = "type = \'t\'", subtitle = NULL, caption = NULL, type = 't'),
vpc(xpdb, title = "type = \'r\'", subtitle = NULL, caption = NULL, type = 'r'),
ncol = 3)
```
### Visual guide
The option `guide` can enable (`TRUE`) or disable (`FALSE`) the visual guide on the graphs such as the line of identity on the `dv_vs_ipred()` type plot or horizontal lines on residual plots (e.g. `res_vs_idv()`).
### Labels
All xpose plots have by default an informative title, subtitle and caption. For example all plots using individual model predictions (IPRED) will display the epsilons' shrinkage. These titles can easily be edited as templates using @keywords which will be replaced by their actual value stored in the summary level of the `xpdb` object when rendering the plots. Keywords are defined by a word preceded by a `@` e.g. `'@ofv'`. A list of all available keyword can be accessed via `help('template_titles')`. The title, subtitle or caption can be disabled by setting them to `NULL`. Suffix can be automatically added to title, subtitle and caption of all plots. The suffixes can be defined in the `xp_theme`.
#### From the plot functions
```{r demo titles}
# Using template titles
dv_vs_ipred(xpdb,
title = '@y vs. @x (@run, obj: @ofv)',
subtitle = 'Based on: @nind subjects and @nobs records',
caption = 'Dir: @dir')
# Disabling all titles
dv_vs_ipred(xpdb, title = NULL, subtitle = NULL, caption = NULL)
# Edit title suffix from the xp_theme for a specific plot
dv_vs_ipred(xpdb, title = 'A title', xp_theme = list(title_suffix = ' | a suffix for @run'))
```
#### Using the `labs` function
Labels can also modified later on by using the `ggplot2::labs()` function in combination with the ggplot2 `+` operator.
```{r demo xpose_labs}
dv_vs_ipred(xpdb) +
labs(title = '@descr',
subtitle = NULL,
caption = 'Based on @nobs observations',
x = 'Individual model predictions (@x)',
y = 'Observations (@y) for @nind subjects')
```
### Modify aesthetics
By default the aesthetics are read from the `xp_theme` level in the xpdb object but these can be modified in any plot function. xpose makes use of the `ggplot2` functions mapping for any layer (e.g. points, lines, etc.) however to direct the mapping to a specific layer, a prefix appealing to the targeted layer should be used. The format is defined as `layer_aesthetic = value`. Hence to change the color of points in ggplot2 the argument `color = 'green'` could be used in `geom_point()`, while in xpose the same could be achieved with `point_color = 'green'`.
In basic goodness-of-fit plots, the layers have been named as: `point_xxx`, `line_xxx`, `smooth_xxx`, `guide_xxx`, `xscale_xxx`, `yscale_xxx` where `xxx` can be any option available in the `ggplot2` layers: `geom_point`, `geom_line`, `geom_smooth`, `geom_abline`, `scale_x_continuous`, etc.
```{r demo aesthetics}
dv_vs_ipred(xpdb,
# Change points aesthetics
point_color = 'blue', point_alpha = 0.5,
point_stroke = 0, point_size = 1.5,
# Change lines aesthetics
line_alpha = 0.5, line_linewidth = 0.5,
line_color = 'orange', line_linetype = 'solid',
# Change smooth aesthetics
smooth_method = 'lm')
```
Aesthetics can also be defined mapped to a variable using the ggplot2 `aes()` function.
```{r demo mapping}
dv_vs_ipred(xpdb, type = 'p', aes(point_color = SEX))
```
### Grouping variable
The argument group defines the grouping variable to be used in the dataset __for the lines only__, by default group is defined to the column `'ID'`. To apply a grouping variable on any other layer, a manual mapping can be made using the argument `xxx_group = variable`
### Panels
Panels (or faceting) can be created by using the `facets` argument as follows:
* If `facets` is a string e.g `facets = "SEX"`, `ggforce::facet_wrap_paginate` will be used
* If `facets` is a formula e.g `facets = SEX~MED1`, `ggforce::facet_grid_paginate` will be used
```{r demo panels, fig.width = 6, fig.height = 6, out.width = '75%'}
# Example with a string
dv_vs_ipred(xpdb, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1, page = 1)
# Example with a formula
dv_vs_ipred(xpdb, facets = SEX~MED1, margins = TRUE)
```
All xpose plot functions accept arguments for `facet_wrap_pagninate` and `facet_grid_paginate` (e.g. `ncol = 2`, `labeller = 'label_both'`, etc.). With the default xpose theme scales are set to `'free'` from one panel to another (`scales = 'free'`), this behavior can be changed with `scales = 'fixed'`, `'free_y'` or `'free_x'`.
For more information on the available faceting options read the help of [`facet_wrap_paginate`](https://www.rdocumentation.org/packages/ggforce/versions/0.1.1/topics/facet_wrap_paginate) and [`facet_grid_paginate`](https://www.rdocumentation.org/packages/ggforce/versions/0.1.1/topics/facet_grid_paginate) from the package ggforce.
### Additional layers
`xpose` offers the opportunity to add any additional layers from `ggplot2`. Hence, a `ggplot2::geom_rug()` layer could be added to the `dv_vs_ipred()` plot along with some annotations (`ggplot2::annotate()`). Note: the additional layers do not inherit from the xpose aesthetic mapping (i.e. colors or other options need to be defined in each layer as shown below).
Layers can also be used to modify the aesthetics scales for example `ggplot2::scale_color_manual()`, or remove a legend `ggplot2::scale_fill_identity()`.
```{r demo layers}
dv_vs_ipred(xpdb) +
geom_rug(alpha = 0.2, color = 'grey50',
sides = 'lb', linewidth = 0.4) +
annotate(geom = 'text',
fontface = 'bold',
color = 'darkred',
size = 3,
label = 'Toxic concentrations', x = 1.35, y = 1.75) +
annotate(geom = 'rect',
alpha = 0.2, fill = 'red',
xmin = 1, xmax = Inf,
ymin = 1, ymax = Inf)
```
### Scales options
The argument `log` allows to log-transform the axes. Accepted values are `x`, `y` or `xy`.
```{r log-scales demo, warning=FALSE}
dv_vs_ipred(xpdb, log = 'xy', subtitle = 'Plot on log scale')
```
Additional arguments can be provided to the scales via the mapping by using the naming convention `xscale_xxx` or `yscale_xxx` where `xxx` is the name of a `ggplot2` scale argument such as `name`, `breaks`, `labels`, `expand`.
```{r scales-options demo}
dv_vs_ipred(xpdb,
xscale_breaks = c(0.3, 0.8, 1.3),
xscale_labels = c('Low', 'Med', 'High'),
xscale_expand = c(0.2, 0),
xscale_name = 'Individual model predictions')
```
### Themes
Theme in `xpose` are easily customizable. Themes are made up of two parts:
- A `ggplot2` (`gg_theme`) theme controlling the aspect of the plot window
- An `xpose` (`xp_theme`) theme controlling the aspect of the layers such as points or lines
Themes can be attached to an `xpdb` when importing the data with `xpose_data()` or using the function `update_themes()` on an xpdb object.
```{r demo themes xpdb, eval = FALSE}
# While creating the xpdb
xpdb <- xpose_data(runno = '001',
gg_theme = theme_minimal(),
xp_theme = theme_xp_xpose4())
# Update a pre-existing xpdb
xpdb <- update_themes(xpdb = xpdb,
gg_theme = theme_bw2(),
xp_theme = list(point_color = 'dodgerblue4',
line_color = 'dodgerblue4'))
```
#### Examples of `gg_theme`:
xpose brings two additional themes (`theme_readable()` and `theme_bw2()`), to those available in `ggplot2`.
```{r demo gg_theme, echo = FALSE, fig.height = 6, fig.width = 6, out.width = '75%'}
gridExtra::grid.arrange(
dv_vs_ipred(xpdb, subtitle = 'theme_grey() [default in ggplot2]', title = NULL, caption = '', facet = 'VAR') + theme_grey(),
dv_vs_ipred(xpdb, subtitle = 'theme_readable() [default in xpose]', title = NULL, caption = '', facet = 'VAR') + theme_readable(),
dv_vs_ipred(xpdb, subtitle = 'theme_bw2()', title = NULL, caption = NULL, facet = 'VAR') + theme_bw2(),
dv_vs_ipred(xpdb, subtitle = 'theme_dark()', title = NULL, caption = NULL, facet = 'VAR') + theme_dark(),
ncol = 2)
```
#### Examples of `xp_theme`:
```{r demo xp_theme, echo = FALSE, fig.height = 3.2, fig.width = 6, out.width = '75%'}
gridExtra::grid.arrange(
dv_vs_ipred(update_themes(xpdb = xpdb, xp_theme = theme_xp_default()),
subtitle = 'xp_theme = theme_xp_default()\nwith theme_bw2()', title = NULL, caption = '', facet = 'VAR') + theme_bw2(),
dv_vs_ipred(update_themes(xpdb = xpdb, xp_theme = theme_xp_xpose4()),
subtitle = 'xp_theme = theme_xp_xpose4()\nwith theme_bw2()', title = NULL, caption = '', facet = 'VAR') + theme_bw2(),
ncol = 2)
```