---
title: "Introduction"
author: "Benjamin Guiastrennec"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---
  
```{r, include = FALSE}
library(xpose)

xpdb <- xpdb_ex_pk %>% 
  set_var_types(idv = 'TIME')

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


### Load xpose
The first step is to load xpose in R with the following command:
```r
library(xpose)
```

### Import model output
The function `xpose_data()` collects all model output files and table and organizes them into an R object commonly called `xpdb` which stands for "xpose database".

``` r
xpdb <- xpose_data(runno = '001', dir = 'analysis/model/pk/')
```

### Glimpse at the xpdb
The files attached to an xpdb object can be displayed to the console simply by writing its name to the console or by using the `print()` function.

```{r demo print xpose_data}
xpdb # or print(xpdb)
```

### Model summary
A summary of a model run can be displayed to the console by using the `summary()` function on an xpdb object.

```{r demo xpose summary}
summary(xpdb)
```


### Parameter estimates
A table of parameter estimates can be displayed to the console by using the `prm_table()` function on an xpdb object.

```{r demo prm_table}
prm_table(xpdb)
```


### Listing variables
A list of available variables for plotting can be displayed to the console by using the `list_vars()` function on an xpdb object.

```{r demo list_vars}
list_vars(xpdb)
```

### Pipes
`xpose` makes use of the pipe operator `%>%` from the package [dplyr](https://dplyr.tidyverse.org). Pipes can be used to generate clear workflow.

```{r, eval = FALSE}
xpose_data(runno = '001') %>% 
  dv_vs_ipred() %>% 
  xpose_save(file = 'run001_dv_vs_ipred.pdf')
```

### Editing the xpdb
Multiples edits can be made to the xpdb object. For instance the type (visible using the `list_vars()` function described above) of a variable can be changed. Hence the independent variable (idv) could be changed from `TIME` (default in NONMEM) to `TAD`. All plots using `idv` will then automatically use `TAD`.

```{r, change idv}
# With the TIME default
xpdb %>% 
  dv_vs_idv()

# After IDV reassignment
xpdb %>% 
  set_var_types(idv = 'TAD') %>% 
  dv_vs_idv()
```

### Generating plots
Plotting functions are used as follows:
``` {r demo basic gof}
# DV vs. IPRED plot
dv_vs_ipred(xpdb)

# CWRES vs. PRED plot
res_vs_pred(xpdb, res = 'CWRES')
```


### Saving plots
The `xpose_save` function was designed to facilitate the export of xpose plots. The file extension is guessed from the file name and must match one of .pdf (default), .jpeg, .png, .bmp or .tiff. If no extension is provided as part of the file name a .pdf will be generated. Finally, if the `plot` argument is left empty `xpose_save` will automatically save the last plot that was created or modified.

The `xpose_save()` function is compatible with templates titles and keywords such as `@run` for the run number and `@plotfun` for the name of the plotting function can be used to automatically name files. Learn more about the template titles keywords using `help('template_titles')`. 


```{r, eval = FALSE}
# Save the last generated plot
dv_vs_ipred(xpdb)
xpose_save(file = 'run001_dv_vs_ipred.pdf')

# Template titles can also be used in filename and the directory
xpdb %>% 
 dv_vs_ipred() %>% 
 xpose_save(file = '@run_@plotfun_[@ofv].jpeg', dir = '@dir')
```