---
title: "Create your dataset"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Create your dataset}
  %\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/v01_dataset.html).")
  knitr::knit_exit()
}
```

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

### Instantiate a dataset

Create a dataset of 3 subjects:

```{r}
ds <- Dataset(subjects=3)
```

Or shortly:

```{r}
ds <- Dataset(3)
```

Check how many subjects are part of this dataset:

```{r}
ds %>% length()
```

See all methods that can be applied on a dataset:

```{r}
methods(class=class(ds))
```

Oh, this looks cool. There are plenty of functions to play with.  
These functions will be illustrated little by little in the other vignettes.  
  
In the next sections below, we'll see how we can add boluses and infusions:

### Add a bolus

A bolus can be created using the constructor `Bolus` and added to the dataset:

```{r}
ds <- ds %>% add(Bolus(time=0, amount=1000))
```

By default, it will be injected into the first compartment (CMT=1). If another compartment needs to be used, the `compartment` argument may be used as follows:

```{r, results='hide'}
Bolus(time=0, amount=1000, compartment=2)
```

Bioavailabilities (`f` argument) and lag times (`lag` argument) can be implemented as well, in the dataset. This will be illustrated in other vignettes.

### Add an infusion

An infusion can be created using the constructor `Infusion` and added to the dataset:

```{r}
ds <- ds %>% add(Infusion(time=0.5, amount=1000))
```

As previously, the default compartment is the first compartment.

Infusion rate (`rate` argument) or duration (`duration` argument), bioavailabilities (`f` argument) and lag times (`lag` argument) can be implemented as well, in the dataset. This will be illustrated in other vignettes.

### Add observations

Observations can be created using the constructor `Observations` and added to the dataset:

```{r}
ds <- ds %>% add(Observations(times=c(0.5, 1)))
```

The default compartment is the first one. Although the compartment number is not useful for simulations (as simulation engines are able to look at all `DV` at once), it can still be useful when exporting a table for a modeling tool.

### Export dataset

So far so good! The dataset contains 5 subjects, 1 bolus and 1 infusion.
We are going to export it to a 2-dimensional table. This step is implicitly done by CAMPSIS when you simulate your model.

```{r}
table <- ds %>% export(dest="RxODE")
table
```

A few explanations need to be given here regarding the following column names:

* ID: this is the subject ID, it always starts at 1. ID's are consecutive in CAMPSIS
* ARM: this is the ARM number. 0 is the default arm.
* RATE: the RATE column (0 for boluses, -1/-2 for a rate/infusion defined in the model, NA when no information is available)
* DOSENO: the dose number. Doses (boluses and infusions) are numbered according to the time they occur.

### Add several arms

Instead of using the default arm (0) in the dataset, several arms can be created and added to the dataset. These arms are independent in the sense the treatment(s) and the observation(s) can be totally different.

To illustrate this, let's create a dataset with two arms.

```{r}
arm1 <- Arm(subjects=2)
arm2 <- Arm(subjects=3)
```

Let's create 2 different treatments:

```{r}
arm1 <- arm1 %>% add(Bolus(time=0, amount=1000))
arm2 <- arm2 %>% add(Bolus(time=0, amount=2000))
```

Observations may also differ:

```{r}
arm1 <- arm1 %>% add(Observations(times=c(0.5, 1)))
arm2 <- arm2 %>% add(Observations(times=c(1, 1.5)))
```

Let's now add these 2 arms into a fresh dataset:

```{r}
ds <- Dataset() %>% add(c(arm1, arm2))
```

We can check how many subjects are part of this dataset:

```{r}
ds %>% length()
```

The resulting exported table is as follows:

```{r}
table <- ds %>% export(dest="RxODE")
table
```