---

title: "outbreaker2: Rcpp API"

author: "Thibaut Jombart"

date: "`r Sys.Date()`"

output:

   rmarkdown::html_vignette:

     toc: true

     toc_depth: 2

vignette: >

  %\VignetteIndexEntry{outbreaker2: Rcpp API}

  %\VignetteEngine{knitr::rmarkdown}

  %\VignetteEncoding{UTF-8}

---

# List of available functions

The C++ functions bound to R via Rcpp used in *outbreaker2* for priors,

likelihoods and movements are not visible to the user, as they are not exported

by the package. However, advanced users can access these functions using `get_cpp_api()`, which returns an environment with all relevant functions:

```{r}

library(outbreaker2) 

## get all functions in an environment

x <- get_cpp_api()

x

## check content

ls(x)

## all functions are Rcpp bindings to a C++ function

x$cpp_ll_all

```

# Function signatures

These functions take the following arguments:

```{r, arguments}

list_args <- lapply(x, args)[ls(x)]

list_args

```

Arguments are detailed in the next section.

# Arguments

Arguments of the Rcpp-bound C++ functions are:

```{r}

list_formals <- lapply(x, formals)

args <- sort(unique(unlist(lapply(list_formals, names))))

args

```

- **`alpha`**: a vector of integers of length 'N' (number of cases), indicating

    infectors of each case, with values from 1 to N; missing values should be

    `NA`

- **`config`**: a list containing configuration settings as returned by

    `create_config`

- **`custom_function`**: a R function for a custom prior, with a single

    argument, which must be a list of parameters and augmented data with the

    class `outbreaker_param`; returned values must be **on the log scale**

- **`custom_functions`**: a list of R functions obeying the rules of

`custom_function`, named according to the priors; currently available names are:

```{r, echo = FALSE} 

temp <- sub("cpp_prior_", "", ls(x, pattern = "cpp_prior.*"))

setdiff(temp, "all") 

```

- **`custom_ll`**: a R function for a custom likelihood, taking two arguments:

    `data` (see `data`), and `param` (see `param`)

- **`custom_prior`**: same as `custom_function`

- **`data`**: a valid 'outbreaker_data' list

- **`i`**: an integer scalar indicating the index of a case, from 1 to N (number of cases) 

- **`list_custom_ll`**: a list of R functions obeying the rules of `custom_ll`,

    named according to the computed likelihood component; available names are:

```{r, echo = FALSE}

temp <- sub("cpp_ll_", "", ls(x, pattern = "cpp_ll.*"))

setdiff(temp, c("timing", "all"))       

```

- **`param`**: a list containing parameters and augmented data with the class

    `outbreaker_param`

- **`t_inf`**: a vector of integers of length N (number of cases), indicating

    infection dates of each case; missing values should be `NA`

- **`x`**: a vector of integers to be sampled from