---
title: "Covariates"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Covariates}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---

```{r, results='asis', echo=F, message=F, warning=F}
if (campsis::onCran()) {
  cat("This vignette was not built on CRAN. Please check out the online version [here](https://calvagone.github.io/campsis.doc/articles/v03_covariates.html).")
  knitr::knit_exit()
}
```

```{r, results='hide', echo=F, message=F, warning=F}
library(campsis)
```

### Add a body weight covariate into the model

Let's use a simple 1-compartment model to illustrate how covariates are managed by CAMPSIS.

```{r}
model <- model_suite$nonmem$advan1_trans2
```

For this example, we're going to add allometric scaling on the clearance parameter.

```{r}
model <- model %>% replace(Equation("CL", "THETA_CL*exp(ETA_CL)*pow(BW/70, 0.75)"))
model
```

We will infuse 1000 mg with a rate of 200 mg/hour into the central compartment and observe for a day.
The corresponding dataset is as follows:

```{r}
dataset <- Dataset() %>%
    add(Infusion(time=0, amount=1000, rate=200)) %>%
    add(Observations(times=seq(0,24,by=0.5)))
```

To visualize clearly the effect of the covariates, we will disable the inter-individual variability on the model.

```{r}
model <- model %>% disable("IIV")
```

### Constant body weight

Let's define a constant covariate into the dataset. This is done as follows.

```{r}
ds <- dataset %>% setSubjects(5) %>%
  add(Covariate("BW", 70))
```

All simulated subjects will be exactly the same, as IIV was removed.

```{r covariates_constant_bw , fig.align='center', fig.height=4, fig.width=8, message=F}
results <- model %>% simulate(dataset=ds)
spaghettiPlot(results, "CONC")
```

### Fix body weight values (1/subject)

Let's now define 1 body weight per subject. This is done as follows.

```{r}
ds <- dataset %>% setSubjects(5) %>%
  add(Covariate("BW", c(50,60,70,80,90)))
```

Simulated subjects should now be different.

```{r covariates_fixed_bw , fig.align='center', fig.height=4, fig.width=8, message=F}
results <- model %>% simulate(dataset=ds)
spaghettiPlot(results, "CONC")
```

### Uniform distribution

Let's say now that the body weight is a uniform distribution. This can be implemented as follows:

```{r}
ds <- dataset %>% setSubjects(40) %>%
  add(Covariate("BW", UniformDistribution(min=50, max=90)))
```

Simulated weights will then be sampled from a uniform distribution with a min value of 50 and a max value of 90.

```{r covariates_uniform_distribution , fig.align='center', fig.height=4, fig.width=8, message=F}
results <- model %>% simulate(dataset=ds, outvars=c("CONC", "BW"), seed=1)
gridExtra::grid.arrange(spaghettiPlot(results, "BW"), spaghettiPlot(results, "CONC"), nrow=1)
```

### Normal distribution

Let's say now that the body weight is a normal distribution. This can be implemented as follows:

```{r}
ds <- dataset %>% setSubjects(40) %>%
  add(Covariate("BW", NormalDistribution(mean=70, sd=10)))
```

Simulated weights will then be sampled from a normal distribution with a mean of 70 and a standard deviation of 10.

```{r covariates_normal_distribution , fig.align='center', fig.height=4, fig.width=8, message=F}
results <- model %>% simulate(dataset=ds, outvars=c("CONC", "BW"), seed=1)
gridExtra::grid.arrange(spaghettiPlot(results, "BW"), spaghettiPlot(results, "CONC"), nrow=1)
```

### Log-normal distribution

Say now that the body weight is a log-normal distribution. This can be implemented as follows:

```{r}
ds <- dataset %>% setSubjects(40) %>%
  add(Covariate("BW", LogNormalDistribution(meanlog=log(70), sdlog=0.2)))
```

Simulated weights will then be sampled from a log-normal distribution with a median of 70 and a coefficient of variation of 20%.

```{r covariates_lognormal_distribution , fig.align='center', fig.height=4, fig.width=8, message=F}
results <- model %>% simulate(dataset=ds, outvars=c("CONC", "BW"), seed=1)
gridExtra::grid.arrange(spaghettiPlot(results, "BW"), spaghettiPlot(results, "CONC"), nrow=1)
```

### Bootstrap

Body weight can also be bootstrapped from a real dataset.
Let's create a fictive one:

```{r}
bootstrap <- data.frame(ID=c(1,2,3,4,5), BW=c(89,54,60,75,77))
```

```{r}
ds <- dataset %>% setSubjects(10) %>%
  add(Covariate("BW", BootstrapDistribution(data=bootstrap$BW, replacement=TRUE, random=TRUE)))
```

Simulated weights will then be sampled from a log-normal distribution with a median of 70 and a coefficient of variation of 20%.

```{r covariates_bootstrap , fig.align='center', fig.height=4, fig.width=8, message=F}
results <- model %>% simulate(dataset=ds, outvars=c("CONC", "BW"), seed=2)
gridExtra::grid.arrange(spaghettiPlot(results, "BW"), spaghettiPlot(results, "CONC"), nrow=1)
```