IndLTPrior {EcoEnsemble} | R Documentation |
Constructor for the EnsemblePrior
class
Description
Constructors for the EnsemblePrior
class and related classes. These functions are used to encode prior information for the ensemble model. The IndSTPrior
, IndLTPrior
, ShaSTPrior
, and TruthPrior
constructors encapsulate prior information.
Usage
IndLTPrior(
parametrisation_form = "lkj",
var_params = list(1, 1),
cor_params = 1
)
IndSTPrior(
parametrisation_form = "hierarchical",
var_params = list(-3, 1, 8, 4),
cor_params = list(0.1, 0.1, 0.1, 0.1),
AR_params = c(2, 2)
)
ShaSTPrior(
parametrisation_form = "lkj",
var_params = list(1, 10),
cor_params = 1,
AR_params = c(2, 2)
)
TruthPrior(
d,
initial_mean = 0,
initial_var = 100,
rw_covariance = list(2 * d, diag(d))
)
EnsemblePrior(
d,
ind_st_params = IndSTPrior(),
ind_lt_params = IndLTPrior(),
sha_st_params = ShaSTPrior(),
sha_lt_params = 5,
truth_params = TruthPrior(d)
)
Arguments
parametrisation_form |
The parametrisation by which the covariance matrix of the noise of the AR process (in the case of |
var_params |
The parameters characterising the variance of the AR process (in the case of |
cor_params |
The parameters characterising the correlations of the AR process (or the distribution of long-term discrepancies) on the short-term discrepancies. The default value is |
AR_params |
The parameters giving the beta parameters for the prior distribution on the autoregressive parameter of the AR(1) process. The default is |
d |
A |
initial_mean |
A |
initial_var |
A |
rw_covariance |
A |
ind_st_params |
An |
ind_lt_params |
An |
sha_st_params |
A |
sha_lt_params |
A |
truth_params |
A |
Details
IndSTPrior
and ShaSTPrior
discrepancy prior parameter objects contain 4 slots corresponding to:
-
parametrisation_form
- Acharacter
specifying how the priors are parametrised. Currently supported priors are'lkj'
,'inv_wishart'
,'beta'
, or'hierarchical'
('hierarchical'
is only supported forIndSTPrior
objects). -
var_params
- The prior parameters for the discrepancy variances, either alist
of length2
or anumeric
of length4
. See below. -
cor_params
- The correlation matrix parameters, either alist
of length2
or anumeric
of length4
. See below. -
AR_params
- Parameters for the autoregressive parameter as anumeric
of length2
.
IndLTPrior
discrepancy prior parameter objects contain the slots parametrisation_form
, var_params
, and cor_params
.
There are currently four supported prior distributions on covariance matrices. As in Spence et. al. (2018), the individual and shared short-term discrepancy covariances, \Lambda_k
and \Lambda_\eta
, as well as the individual long-term discrepancy covariance, \Lambda_\gamma
, are decomposed into a vector of variances and a correlation matrix
\Lambda = \sqrt{\mathrm{diag}(\pi)} P \sqrt{\mathrm{diag}(\pi)},
where \pi
is the vector of variances for each variable of interest (VoI), and P
is the correlation matrix.
Selecting 'lkj'
, 'inv_wishart'
, 'beta'
, or 'hierarchical'
refers to setting LKJ, inverse Wishart, beta, or hierarchical prior distributions on the covariance matrix respectively. The variance parameters should be passed through as the var_params
slot of the object and the correlation parameters should be passed through as the cor_params
. For 'lkj'
, 'inv_wishart'
, and 'beta'
selections, variances are parameterised by gamma distributions, so the var_params
slot should be a list
of length two, where each element gives the shape and rate parameters for each VoI (either as a single value which is the same for each VoI or a numeric
with the same length as the number of VoI). For example, setting var_params = list(c(5,6,7,8), c(4,3,2,1))
would correspond to a Gamma(5, 4)
prior on the variance of the first VoI, a Gamma(6, 3)
prior on the variance of the second VoI, etc...
The correlations should be in the following form:
If
'lkj'
is selected, thencor_params
should be anumeric
\eta
giving the LKJ shape parameter, such that the probability density is given by (Lewandowski et. al. 2009)f(\Sigma | \eta)\propto \mathrm{det} (\Sigma)^{\eta - 1}.
Variances are parameterised by gamma distributions.
If
'inv_wishart'
is selected, thencor_params
should be alist
containing a scalar value\eta
(giving the degrees of freedom) and a symmetric, positive definite matrixS
(giving the scale matrix). The dimensions ofS
should be the same as the correlation matrix it produces (i.ed \times d
whered
is the number of VoI). The density of an inverse Wishart is given byf(W|\eta, S) = \frac{1}{2^{\eta d/2} \Gamma_N \left( \frac{\eta}{2} \right)} |S|^{\eta/2} |W|^{-(\eta + d + 1)/2} \exp \left(- \frac{1}{2} \mathrm{tr}\left(SW^{-1} \right) \right),
where
\Gamma_N
is the multivariate gamma function and\mathrm{tr \left(X \right)}
is the trace ofX
. Note that inverse Wishart distributions act over the space of all covariance matrices. When used for a correlation matrix, only the subset of valid covariance matrices that are also valid correlation matrices are considered. Variances are parameterised by gamma distributions.If
'beta'
is selected, thencor_params
should be alist
containing two symmetricd
\times
d
matricesA
andB
giving the prior success parameters and prior failure parameters respectively. The correlation between thei
th andj
th VoI is\rho_{i, j}
with\frac{1}{\pi} \tan^{-1} \frac{\rho_{i, j}}{\sqrt{1-\rho_{i, j}^2}} + \frac{1}{2} \sim \mathrm{beta}(A_{i, j}, B_{i, j}).
Variances are parameterised by gamma distributions.
If
'hierarchical'
is selected, then variances are parameterised by log-normal distributions:\log \pi_{k, i} \sim \mathrm{N}(\mu_i, \sigma^2_i)
with priors
\mu_i \sim \mathrm{N}(\alpha_\pi, \beta_\pi),
\sigma^2_i \sim \mathrm{InvGamma}(\gamma_\pi, \delta_\pi).
The
var_params
slot should then be anumeric
of length 4, giving the\alpha_\pi, \beta_\pi, \gamma_\pi, \delta_\pi
hyperparameters respectively. Correlations (\rho_{k, i, j}
where\rho_{k, i, j}
is the correlation between VoIi
andj
for thek
th simulator) are parameterised by hierarchical beta distributions.\frac{\rho_{k, i, j} + 1}{2} \sim \mathrm{beta}(c_{k, i, j}, d_{k, i, j})
with priors
c_{k, i, j} \sim \mathrm{gamma}(\alpha_\rho, \beta_\rho),
d_{k, i, j} \sim \mathrm{gamma}(\gamma_\rho, \delta_\rho).
The
cor_params
slot should be anumeric
of length 4 giving the\alpha_\rho, \beta_\rho, \gamma_\rho, \delta_\rho
hyperparameters. respectively. NOTE: This options is only supported for the individual short-term discrepancy terms.
Priors may also be specified for the autoregressive parameters for discrepancies modelled using autoregressive processes (i.e. for IndSTPrior
and ShaSTPrior
objects). These are parametrised via beta distributions such that the autoregressive parameter R \in (-1,1)
satisfies
\frac{R+1}{2} \sim \mathrm{Beta}(\alpha, \beta)
.
In addition to priors on the discrepancy terms, it is also possible to add prior information on the truth. We require priors on the truth at t=0
. By default, a N(0, 10)
prior is used on the initial values., however this can be configured by the truth_params
argument. The covariance matrix of the random walk of the truth \Lambda_y
can be configured using an inverse-Wishart prior. The truth_params
argument should be a TruthPrior
object.
Value
EnsemblePrior
returns an object of class EnsemblePrior
.
IndSTPrior
returns an object of class IndSTPrior
.
IndLTPrior
returns an object of class IndLTPrior
.
ShaSTPrior
returns an object of class ShaSTPrior
.
TruthPrior
returns an object of class TruthPrior
.
References
Spence et. al. (2018). A general framework for combining ecosystem models. Fish and Fisheries, 19(6):1031-1042.
Examples
##### Different forms of the individual long term discrepancy priors
#LKJ(10) priors on correlation matrices and gamma(5, 3) priors on the variances
ist_lkj <- IndSTPrior("lkj", list(5, 3), 10)#
#Same as above but with an additional beta(2, 4) prior on
#the autoregressive parameter of the AR process.
ist_lkj <- IndSTPrior("lkj", list(5, 3), 10, AR_params = c(2, 4))
#Same as above but with different variance priors for 5 different variables of interest.
#This encodes that there is a gamma(1, 1) prior on the variance of the first variable,
#a gamma(23, 1) on the second variable etc...
ist_lkj <- IndSTPrior("lkj", list(c(1,23,24,6,87), c(1,1,1,1,5)), 10, AR_params = c(2, 4))
#Hierarchical priors with gamma(1,2) and gamma(10, 1) on the variance hyperparameters and
#gamma(3,4), gamma(5,6) on the correlation hyperparameters
ist_hie <- IndSTPrior("hierarchical", list(1,2,10,1), list(3,4,5,6))
#Beta priors via the method of concordance. We have gamma(5,3) priors on the variance
# and beta(40,40) on each of the correlations in the correlation matrix.
ist_bet <- IndSTPrior("beta", list(5, 3), list(matrix(40, 5, 5), matrix(40, 5, 5)))
#Inverse Wishart correlation priors. Gamma(2, 1/3) priors are on the variances and
#inv-Wishart(5, diag(5)) on the correlation matrices.
ist_inW <- IndSTPrior("inv_wishart", list(2, 1/3),list(5, diag(5)))
##### TruthPrior
#Simple default truth prior with 7 variables of interest
truth_def <- TruthPrior(7)
# A more fine-tuned truth prior for an ensemble with 7 species.
truth_cus <- TruthPrior(7, initial_mean = 2, initial_var = 10, rw_covariance = list(10, diag(7)))
#The default priors for an ensemble with 8 variables of interest
priors <- EnsemblePrior(8)
#With 4 variables of interest.
priors <- EnsemblePrior(4)
#Defining custom priors for a model with 4 species.
num_species <- 5
priors <- EnsemblePrior(
d = num_species,
ind_st_params = IndSTPrior("lkj", list(3, 2), 3, AR_params = c(2,4)),
ind_lt_params = IndLTPrior(
"beta",
list(c(10,4,8, 7,6),c(2,3,1, 4,4)),
list(matrix(5, num_species, num_species),
matrix(0.5, num_species, num_species))
),
sha_st_params = ShaSTPrior("inv_wishart",list(2, 1/3),list(5, diag(num_species))),
sha_lt_params = 5,
truth_params = TruthPrior(d = num_species, initial_mean = 5, initial_var = 10,
rw_covariance = list(10, diag(10)))
)