Customise priors for outbreaker

Priors can be specified in several ways in outbreaker2 (see details and examples). The most flexible way to specify a prior is to provide a prior function directly. This function must take an argument 'param', which is a list which contains all the states of the parameters and augmented data. See the documentation of create_param for more information.

custom_priors(...)

# S3 method for custom_priors
print(x, ...)

Arguments

...

A list or a series of named, comma-separated functions implementing priors. Each function must have a single argument, which corresponds to a 'outbreaker_param' list.
x

an outbreaker_config object as returned by create_config.

Value

A list of custom functions with class custom_priors. Values set to NULL will be ignored and default functions will be used instead.

Details

There are three ways a user can specify priors:

1) Default: this is what happens when the 'config' has default values of prior parameters.
2) Customized parameters: in this case, the prior functions are the default ones from the package, but will use custom parameters, specified by the user through create_config.

3) Customized functions: in this case, prior functions themselves are specified by the user, through the '...' argument of 'custom_priors'. The requirements is that such functions must have either hard-coded parameters or enclosed values. They will take a single argument which is a list containing all model parameters with the class 'outbreaker_param'. ALL PRIORS functions are expected to return values on a LOG SCALE.

Priors currently used for the model are:

  • mu (mutation rate): default function is an exponential distribution implemented in outbreaker:::cpp_prior_mu. New prior functions should use x$mu to refer to the current value of mu, assuming their argument is called x.

  • pi (reporting probability): default function is a beta distribution implemented in outbreaker:::cpp_prior_pi. New prior functions should use x$pi to refer to the current value of pi, assuming their argument is called x.

  • eps (contact reporting coverage): default function is a beta distribution implemented in outbreaker:::cpp_prior_eps. New prior functions should use x$eps to refer to the current value of eps, assuming their argument is called x.

  • lambda (non-infectious contact rate): default function is a beta distribution implemented in outbreaker:::cpp_prior_lambda. New prior functions should use x$lambda to refer to the current value of lambda, assuming their argument is called x.

See also

See customization vignette for detailed examples on how to customize priors.

Author

Thibaut Jombart (thibautjombart@gmail.com).

Examples


## BASIC CONFIGURATION
custom_priors()

#> 
#> 
#>  ///// outbreaker custom priors ///
#> 
#> class: custom_priors list
#> number of items: 4 
#> 
#> /// custom priors set to NULL (default used) //
#> $mu
#> NULL
#> 
#> $pi
#> NULL
#> 
#> $eps
#> NULL
#> 
#> $lambda
#> NULL
#> 


## SPECIFYING PRIOR PARAMETERS
## - this will need to be passed to outbreaker
default_config <- create_config()
new_config <- create_config(prior_mu = 1e-5,
                        prior_pi = c(2, 1))

## - to check the prior manually, default settings:
param <- list(mu = 0.001, pi = 0.9)
outbreaker2:::cpp_prior_mu(param, default_config)

#> [1] -0.001
outbreaker2:::cpp_prior_pi(param, default_config)

#> [1] 1.35434

outbreaker2:::cpp_prior_mu(param, new_config)

#> [1] -11.51293
outbreaker2:::cpp_prior_pi(param, new_config)

#> [1] 0.5877867

## these correspond to:
dexp(0.001, 0.01, log = TRUE)

#> [1] -4.60518
dbeta(0.9, 2, 1, log = TRUE)

#> [1] 0.5877867


## SPECIFYING A PRIOR FUNCTION

## flat prior for pi between 0.5 and 1
f <- function(x) {ifelse(x$pi > 0.5, log(2), log(0))}
priors <- custom_priors(pi = f)
priors # this should be passed to outbreaker

#> 
#> 
#>  ///// outbreaker custom priors ///
#> 
#> class: custom_priors list
#> number of items: 4 
#> 
#> /// custom priors set to NULL (default used) //
#> $mu
#> NULL
#> 
#> $eps
#> NULL
#> 
#> $lambda
#> NULL
#> 
#> /// custom priors //
#> $pi
#> function(x) {ifelse(x$pi > 0.5, log(2), log(0))}
#> <environment: 0x00000000348b8158>
#> 

## test the prior manually
priors$pi(list(pi=1))

#> [1] 0.6931472
priors$pi(list(pi=.6))

#> [1] 0.6931472
priors$pi(list(pi=.2))

#> [1] -Inf
priors$pi(list(pi=.49))

#> [1] -Inf