EcoEnsemble (version 1.1.2)

IndLTPrior: 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)
)

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.

Arguments

parametrisation_form

The parametrisation by which the covariance matrix of the noise of the AR process (in the case of IndSTPrior and ShaSTPrior objects or the covariance of the distribution of long-term discrepancies for IndLTPrior objects) is decomposed. The default is hierarchical for IndSTPrior objects, and lkj otherwise. See details.

var_params

The parameters characterising the variance of the AR process (in the case of IndSTPrior and ShaSTPrior objects or the variance of the distribution of long-term discrepancies for IndLTPrior objects) on the discrepancy. The default value is list(-3, 1, 8, 4) for IndSTPrior objects, list(1, 1) for IndLTPrior objects, and list(1, 10) for ShaSTPrior objects. See details.

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 in this case is to use list(0.1,0.1,0.1,0.1) for IndSTPrior objects, and 1 for IndLTPrior and ShaSTPrior objects. See details.

AR_params

The parameters giving the beta parameters for the prior distribution on the autoregressive parameter of the AR(1) process. The default is c(2,2). See details.

d

A numeric specifying the number of variables of interest in the ensemble.

initial_mean

A numeric giving the mean of the normal distribution giving the prior on the initial value of the random walk. This is the same value for each variable Default value is 0.

initial_var

A numeric giving the variance of the normal distribution giving the prior on the initial value of the random walk. This is the same value for each variable Default value is 100.

rw_covariance

A list of length 2 containing the inverse-Wishart parameters for the covariance of the random walk of the truth. The default value is list(2*d, diag(d)).

ind_st_params

An IndSTPrior object specifying priors for the individual short-term discrepancies \(z_k^{(t)}\). The default value is IndSTPrior("hierarchical", list(-3, 1, 8, 4), list(0.1, 0.1, 0.1, 0.1), c(2, 2)).

ind_lt_params

An IndLTPrior object specifying priors for the individual long-term discrepancies \(\gamma_k\). The default value is IndLTPrior("lkj",list(1, 1), 1).

sha_st_params

A ShaSTPrior object specifying priors for the shared short-term discrepancies \(\eta^{(t)}\). The default value is ShaSTPrior("lkj",list(1, 10), 1, c(2,2)).

sha_lt_params

A numeric of length d or 1 containing the standard deviations for the normal prior used on the shared short-term discrepancy \(\mu\). If a single value is supplied, this is repeated for each variable of interest. The default value is 5.

truth_params

A TruthPrior object specifying priors for the processes on the truth \(y^{(t)}\). The default value is TruthPrior(d).

Details

IndSTPrior and ShaSTPrior discrepancy prior parameter objects contain 4 slots corresponding to:

1. parametrisation_form - A character specifying how the priors are parametrised. Currently supported priors are 'lkj', 'inv_wishart', 'beta', 'hierarchical', or 'hierarchical_beta_conjugate' ('hierarchical' and 'hierarchical_beta_conjugate' are only supported for IndSTPrior objects).

2. var_params - The prior parameters for the discrepancy variances, either a list of length 2 or a numeric of length 4. See below.

3. cor_params - The correlation matrix parameters, either a list of length 2, a numeric of length 3 or a numeric of length 4. See below.

4. AR_params - Parameters for the autoregressive parameter as a numeric of length 2.

IndLTPrior discrepancy prior parameter objects contain the slots parametrisation_form, var_params, and cor_params.

There are currently five 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', 'hierarchical' or 'hierarchical_beta_conjugate' refers to setting LKJ, inverse Wishart, beta or hierarchical (with gamma-distributed hyperparameters or beta-conjugate-distributed hyperparameters) 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, then cor_params should be a numeric \(\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, then cor_params should be a list containing a scalar value \(\eta\) (giving the degrees of freedom) and a symmetric, positive definite matrix \(S\) (giving the scale matrix). The dimensions of \(S\) should be the same as the correlation matrix it produces (i.e \(d \times d\) where \(d\) is the number of VoI). The density of an inverse Wishart is given by $$f(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 of \(X\). 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, then cor_params should be a list containing two symmetric d\(\times\)d matrices \(A\) and \(B\) giving the prior success parameters and prior failure parameters respectively. The correlation between the ith and jth 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' or 'hierarchical_beta_conjugate' 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 a numeric 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 VoI \(i\) and \(j\) for the \(k\)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).$$ NOTE: These options is only supported for the individual short-term discrepancy terms.

• If 'hierarchical' is selected, then the cor_params slot should be a numeric of length 4 giving the \(\alpha_\rho, \beta_\rho, \gamma_\rho, \delta_\rho\) hyperparameters. respectively. NOTE: This option is only supported for the individual short-term discrepancy terms.

• If 'hierarchical_beta_conjugate' is selected, then the cor_params slot should be a numeric of length 3. Denoting the values by \(r,s,k\), they map to the hyperparameters \(p, q, k\) of the beta conjugate distribution via \(k = k\), \(p^{-1/k} = (1+e^{-s})(1+e^{-r})\) and \(q^{1/k} = e^{-r}(1+e^{-s})^{-1}(1+e^{-r})^{-1}\). The density of the beta conjugate distribution is defined up to a constant of proportionality by $$p(\alpha_\rho, \beta_\rho\,|\,p, q, k) \propto \frac{\Gamma(\alpha_\rho + \beta_\rho)^{k}p^{\alpha_\rho}q^{\beta_\rho}}{\Gamma(\alpha_\rho)^{k}\Gamma(\beta_\rho)^{k}}\,.$$ NOTE: This option 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.

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

#Hierarchical priors with gamma(1,2) and gamma(10, 1) on the variance hyperparameters and
#the beta conjugate prior with parameters (p = 0.75, q = 0.75, k = 0.2) on the
#correlation hyperparameters
ist_hie_beta_conj <- IndSTPrior("hierarchical_beta_conjugate",
list(1,2,10,1), list(0.75,0.75,0.2))

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