Defines a list specifying the structure of the approximate Gaussian process. Custom settings can be supplied which override the defaults.
Arguments
- basis_prop
Numeric, the proportion of time points to use as basis functions. Defaults to
NULL, in which case the number of basis functions is chosen from the lengthscale prior (see Details). Decreasing this value results in a decrease in accuracy but a faster compute time (with increasing it having the opposite effect).- boundary_scale
Numeric, the boundary factor of the approximate Gaussian process relative to the half-range of the time points. Defaults to
NULL, in which case it is chosen from the lengthscale prior (see Details). Not used by the periodic kernel.- ls
A
<dist_spec>giving the prior distribution of the lengthscale parameter of the Gaussian process kernel on the scale of days. Defaults to a Lognormal distribution with mean 21 days, sd 7 days and maximum 60 days:LogNormal(mean = 21, sd = 7, max = 60)(a lower limit of 0 will be enforced automatically to ensure positivity)- alpha
A
<dist_spec>giving the prior distribution of the magnitude parameter of the Gaussian process kernel. Should be approximately the expected standard deviation of the Gaussian process (logged Rt in case of the renewal model, logged infections in case of the nonmechanistic model). Defaults to a half-normal distribution with mean 0 and sd 0.01:Normal(mean = 0, sd = 0.01)(a lower limit of 0 will be enforced automatically to ensure positivity)- kernel
Character string, the type of kernel required. Currently supporting the Matern kernel ("matern"), squared exponential kernel ("se"), Ornstein-Uhlenbeck kernel ("ou"), and the periodic kernel ("periodic").
- matern_order
Numeric, defaults to 3/2. Order of Matérn Kernel to use. Common choices are 1/2, 3/2, and 5/2. If
kernelis set to "ou",matern_orderwill be automatically set to 1/2. Only used if the kernel is set to "matern".- w0
Numeric, defaults to 1.0. Fundamental frequency for periodic kernel. They are only used if
kernelis set to "periodic".
Details
The Gaussian process is approximated using the Hilbert space method of
Riutort-Mayol et al. (2023) doi:10.1007/s11222-022-10167-2
. Its accuracy
depends on the boundary factor and number of basis functions relative to
the lengthscale. Longer lengthscales need a wider boundary, and shorter
lengthscales need more basis functions. By default both are chosen from the
5% and 95% quantiles of the lengthscale prior using the relationships in
Section 4.3.1 of that paper, so that lengthscales in this range are
approximated accurately. The choice of these quantiles is a convention that
covers most of the prior without relying on its extreme tails. The
paper starts from a single initial guess at the lengthscale rather than a
prior range. The Ornstein-Uhlenbeck kernel (Matern with
matern_order = 1/2) is not covered by the paper. Its number of basis
functions uses a relationship derived for it (see gp_approx_constants()).
Its boundary uses the Matern 3/2 relationship, which was not re-derived.
The periodic kernel has no boundary, and its number of basis functions is
chosen from the 5% quantile using Appendix B. After fitting, a warning is
given if the posterior median lengthscale lies
outside the range that the approximation represents accurately.
Examples
# default settings
gp_opts()
#> $basis_prop
#> NULL
#>
#> $boundary_scale
#> NULL
#>
#> $ls
#> - lognormal distribution (max: 60):
#> meanlog:
#> 3
#> sdlog:
#> 0.32
#>
#> $alpha
#> - normal distribution:
#> mean:
#> 0
#> sd:
#> 0.01
#>
#> $kernel
#> [1] "matern"
#>
#> $matern_order
#> [1] 1.5
#>
#> $w0
#> [1] 1
#>
#> attr(,"class")
#> [1] "gp_opts" "list"
# add a custom length scale
gp_opts(ls = LogNormal(mean = 4, sd = 1, max = 20))
#> $basis_prop
#> NULL
#>
#> $boundary_scale
#> NULL
#>
#> $ls
#> - lognormal distribution (max: 20):
#> meanlog:
#> 1.4
#> sdlog:
#> 0.25
#>
#> $alpha
#> - normal distribution:
#> mean:
#> 0
#> sd:
#> 0.01
#>
#> $kernel
#> [1] "matern"
#>
#> $matern_order
#> [1] 1.5
#>
#> $w0
#> [1] 1
#>
#> attr(,"class")
#> [1] "gp_opts" "list"
# use periodic kernel
gp_opts(kernel = "periodic")
#> $basis_prop
#> NULL
#>
#> $boundary_scale
#> NULL
#>
#> $ls
#> - lognormal distribution (max: 60):
#> meanlog:
#> 3
#> sdlog:
#> 0.32
#>
#> $alpha
#> - normal distribution:
#> mean:
#> 0
#> sd:
#> 0.01
#>
#> $kernel
#> [1] "periodic"
#>
#> $matern_order
#> [1] 1.5
#>
#> $w0
#> [1] 1
#>
#> attr(,"class")
#> [1] "gp_opts" "list"
# set the approximation manually
gp_opts(basis_prop = 0.2, boundary_scale = 1.5)
#> $basis_prop
#> [1] 0.2
#>
#> $boundary_scale
#> [1] 1.5
#>
#> $ls
#> - lognormal distribution (max: 60):
#> meanlog:
#> 3
#> sdlog:
#> 0.32
#>
#> $alpha
#> - normal distribution:
#> mean:
#> 0
#> sd:
#> 0.01
#>
#> $kernel
#> [1] "matern"
#>
#> $matern_order
#> [1] 1.5
#>
#> $w0
#> [1] 1
#>
#> attr(,"class")
#> [1] "gp_opts" "list"
