---
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