Author: Thibaut Jombart
Date: 2025-12-16

# outbreaker2: Rcpp API

#### Thibaut Jombart

#### 2025-12-16

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

    library(outbreaker2)

    ## get all functions in an environment
    x <- get_cpp_api()
    x

    ## <environment: 0x0000024057370e28>

    ## check content
    ls(x)

    ##  [1] "cpp_ll_all"               "cpp_ll_contact"
    ##  [3] "cpp_ll_genetic"           "cpp_ll_reporting"
    ##  [5] "cpp_ll_timing"            "cpp_ll_timing_infections"
    ##  [7] "cpp_ll_timing_sampling"   "cpp_move_alpha"
    ##  [9] "cpp_move_eps"             "cpp_move_kappa"
    ## [11] "cpp_move_lambda"          "cpp_move_mu"
    ## [13] "cpp_move_pi"              "cpp_move_swap_cases"
    ## [15] "cpp_move_t_inf"           "cpp_prior_all"
    ## [17] "cpp_prior_eps"            "cpp_prior_lambda"
    ## [19] "cpp_prior_mu"             "cpp_prior_pi"

    ## all functions are Rcpp bindings to a C++ function
    x$cpp_ll_all

    ## function (data, param, i = NULL, custom_functions = NULL)
    ## {
    ##     .Call(`_outbreaker2_cpp_ll_all`, data, param, i, custom_functions)
    ## }
    ## <bytecode: 0x00000240573620d0>
    ## <environment: namespace:outbreaker2>

# Function signatures

These functions take the following arguments:

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

    ## $cpp_ll_all
    ## function (data, param, i = NULL, custom_functions = NULL)
    ## NULL
    ##
    ## $cpp_ll_contact
    ## function (data, param, i = NULL, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_ll_genetic
    ## function (data, param, i = NULL, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_ll_reporting
    ## function (data, param, i = NULL, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_ll_timing
    ## function (data, param, i = NULL, custom_functions = NULL)
    ## NULL
    ##
    ## $cpp_ll_timing_infections
    ## function (data, param, i = NULL, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_ll_timing_sampling
    ## function (data, param, i = NULL, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_move_alpha
    ## function (param, data, list_custom_ll = NULL)
    ## NULL
    ##
    ## $cpp_move_eps
    ## function (param, data, config, custom_ll = NULL, custom_prior = NULL)
    ## NULL
    ##
    ## $cpp_move_kappa
    ## function (param, data, config, list_custom_ll = NULL)
    ## NULL
    ##
    ## $cpp_move_lambda
    ## function (param, data, config, custom_ll = NULL, custom_prior = NULL)
    ## NULL
    ##
    ## $cpp_move_mu
    ## function (param, data, config, custom_ll = NULL, custom_prior = NULL)
    ## NULL
    ##
    ## $cpp_move_pi
    ## function (param, data, config, custom_ll = NULL, custom_prior = NULL)
    ## NULL
    ##
    ## $cpp_move_swap_cases
    ## function (param, data, list_custom_ll = NULL)
    ## NULL
    ##
    ## $cpp_move_t_inf
    ## function (param, data, list_custom_ll = NULL)
    ## NULL
    ##
    ## $cpp_prior_all
    ## function (param, config, custom_functions = NULL)
    ## NULL
    ##
    ## $cpp_prior_eps
    ## function (param, config, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_prior_lambda
    ## function (param, config, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_prior_mu
    ## function (param, config, custom_function = NULL)
    ## NULL
    ##
    ## $cpp_prior_pi
    ## function (param, config, custom_function = NULL)
    ## NULL

Arguments are detailed in the next section.

# Arguments

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

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

    ## [1] "config"           "custom_function"  "custom_functions" "custom_ll"
    ## [5] "custom_prior"     "data"             "i"                "list_custom_ll"
    ## [9] "param"

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

    ## [1] "eps"    "lambda" "mu"     "pi"

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

    ## [1] "contact"           "genetic"           "reporting"
    ## [4] "timing_infections" "timing_sampling"

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