---
title: "Plots with multiple pages"
author: "Benjamin Guiastrennec"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Plots with multiple pages}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
library(xpose)
options(width = 100)

xpdb <- xpdb_ex_pk

knitr::opts_chunk$set(fig.dpi    = 96,
                      fig.align  = 'center', 
                      fig.height = 4, 
                      fig.width  = 6,
                      out.width  = '75%',
                      comment    = '',
                      message    = FALSE)
```

# Bases of plot faceting
Panels (or faceting) can be created by using the `facets` argument as follows:

* If `facets` is a string e.g `facets = "SEX"`, facets will be created using `ggforce::`[`facet_wrap_paginate`](https://www.rdocumentation.org/packages/ggforce/versions/0.1.1/topics/facet_wrap_paginate)
* If `facets` is a formula e.g `facets = SEX~MED1`, facets will be created using `ggforce::`[`facet_grid_paginate`](https://www.rdocumentation.org/packages/ggforce/versions/0.1.1/topics/facet_grid_paginate)

```{r demo panels, fig.height = 6}
# Example with a string
dv_vs_ipred(xpdb, facets = c('SEX', 'MED1'))

# 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'`.


# Faceting over multiple pages
## Setting the layout
When the arguments `ncol` and `nrow` are set and under the condition that they are more panels to be drawn that can fit on a single page given the selected layout, the multiple page functionality will automatically be enabled.

```{r, message = FALSE}
dv_vs_ipred(xpdb, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1)
```


## Selecting pages
By default all pages will be shown but this can be time consuming. To select only specific pages to be drawn, use the argument `page`.

```{r, messages = TRUE}
dv_vs_ipred(xpdb, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1, page = 1)
```

It is also possible to change the page(s) to be drawn from an already existing `xpose_plot` object via the `print()` function. 

```{r, eval = FALSE}
# Create an xpose_plot, by default page = 1
p1 <- dv_vs_ipred(xpdb, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1)

# Change the page to be drawn
print(p1, page = 2)
```

## Numbering pages
To number pages the keywords `@page` and `@lastpage` can be used to respectively indicate the current page and the total number of pages.

```{r}
dv_vs_ipred(xpdb, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1, page = 1, caption = 'Page @page of @lastpage')
```

To systematically number all generated plots a caption suffix can be defined in the `xp_theme`.
```{r}
xpdb_numbered <- update_themes(xpdb, xp_theme = list(caption_suffix = ', page @page of @lastpage'))

dv_vs_ipred(xpdb_numbered, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1, page = 2)
```

# Saving multiple pages plots
Multiple pages graphs can simply be saved by using the `xpose_save()` function. 

```{r, eval = FALSE}
dv_vs_ipred(xpdb_numbered, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1) %>% 
xpose_save(file = 'dv_vs_ipred_multiple.pdf')
```

The `pdf` format can conveniently store multiple pages within a single document. However other graphical devices (e.g. `'png'`, `'jpg'`) can also be used, simply ensure to have a page counter (i.e. `'%03d'`) added the file name.

```{r, eval = FALSE}
dv_vs_ipred(xpdb_numbered, facets = c('SEX', 'MED1'), ncol = 2, nrow = 1) %>% 
xpose_save(file = '@run_@plotfun_%03d.png')
```