Single Component Adaptative Metropolis (SCAM) algorithm with eigenvector rotation

Description

Performs one iteration of the single component adaptative Metropolis (SCAM) algorithm with eigenvector rotation. scamH is designed to apply the SCAM algorithm for models where a species community is modelled using habitat characteristics whereas scamHT applies the SCAM algorithm to model a community with habitat characteristics and species traits.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
## S3 method for class 'formula'
scamH(formula,data,start,priors,rotationVal,rotationVect,wParamX,wOuterParamX,sdvalue,accept,likelihoodtype="logit",burning=TRUE,rotation=TRUE,iter,...)

## S3 method for class 'HMSCdata'
scamH(data,start,priors,rotationVal,rotationVect,wParamX,wOuterParamX,sdvalue,accept,likelihoodtype="logit",burning=TRUE,rotation=TRUE,iter,...)

## S3 method for class 'HMSCdata'
scamHT(data,start,priors,rotationVal,rotationVect,wParamX,wOuterParamX,sdvalue,accept,likelihoodtype="logit",burning=TRUE,rotation=TRUE,iter,...)

## S3 method for class 'HMSCdata'
scamRandom(data,start,priors,rotationVal,rotationVect,wParamRandom,wOuterParamRandom,wRandomCov,sdvalue,accept,likelihoodtype="logit",burning=TRUE,rotation=TRUE,iter,...)

Arguments

formula

Model formula. The left side presents the response matrix and the right side gives the descriptors with their parameters. (See details)

data

Object of class HMSCdata.

start

Object of class HMSCparam.

priors

Object of class HMSCprior.

rotationVal

Matrix of eigenvalues independently weighting the importance of each parameter for a response variables. The matrix has as many rows as there are response variables and as many columns as parameters.

rotationVect

3-dimensional array where the first two dimensions present eigenvectors (indexed as the second dimension) for each response variables (third dimension).

wParamX

Matrix of the same dimensions as HMSCparam$paramX where the values define the weights each parameter should have when performing the eigenvector rotation.

wOuterParamX

3-dimensional array presenting covariance matrices (the first two dimensions are the rows and columns of the covariance matrix and the third dimension presents the different covariance matrices) used to weight the importance of the parameters for each response variable.

wParamRandom

Matrix of the same dimensions as HMSCparam$paramRandom where the values define the weights each random effect parameter should have when performing the eigenvector rotation.

wOuterParamRandom

3-dimensional array presenting covariance matrices (the first two dimensions are the rows and columns of the covariance matrix and the third dimension presents the different covariance matrices) used to weight the importance of the random effect parameters for each response variable.

wRandomCov

A scalar weighting of the importance of RandomCov when estimating the random effect parameters.

sdvalue

For scamH and scamHT, it is a matrix of standard deviation used when sampling for the regression parameters (columns) of each response variables (row). For scamRandom, it is a list with three components. The first component is a matrix of standard deviation used when sampling for the regression parameters (columns) of each response variables (row), the second component is a matrix of standard deviation used when sampling for the regression parameters for each levels of the random effect (columns) for each response variables (row) and the third component is a scalare used when sampling for RandomVar.

accept

For scamH and scamHT, it is 3-dimensional array where the first dimension is the number of parameters, the second dimension is is the number of response variables and the third dimension is 2. for scamRandom, it is a list with three components. The first component is a 3-dimensional array where the first dimension is the number of parameters, the second dimension is is the number of response variables and the third dimension is 2; the second component is a 3-dimensional array where the first dimension is the number of parameters for each levels of the random effect (columns), the second dimension is the number of response variables and the third dimension is 2; and the third component is a vector of length 2.

likelihoodtype

Character string defining how the likelihood should be calculated. Any unambiguous variation of wording used in this argument is accepted. (See details)

burning

Logical. Whether or not standard deviation should be adapted.

rotation

Logical. Whether or not an eigenvector rotation should be carried out.

iter

Numeric. The number of time scamH has been carried out so far. (See details)

...

Parameters passed to other functions.

Details

For the user the main difference between scamH and scamHT is within the data and start arguments. As for scamRandom, it is specifically designed to estimate the parameter of the random effect and it is specifically it is heavily relying on the data and parameters available in the data and start arguments.

The algorithm implemented in this function assumes that the data follows a multivariate normal distribution. In that instance, it becomes valuable to check the distribution of the posterior to make sure that it is distributed following a pattern that look somewhat like a multivariate normal distribution. A way to do this is to use pairs to study the different models parameters (paramX, paramTr,paramRandom, means, sigma,...), see example in hmscH.

The formula was designed so that it is necessary to include the parameters and the descriptors. This function is thus capable of carrying out non-linear regression analyses. *** IMPORTANT : Although the function will run, the estimation of the parameters for a non-linear model is very difficult and it is unlikely to converge unless many, many (many !!) iterations are carried out.***

Currently, two likelihood have been implemented, the binomial likelihood with a logit link, and the Poisson likelihood.

These functions were designed to converge to an accept ratio of 0.44.

These functions are constructed in such a way that if burning is set to FALSE, by default, rotation will be considered FALSE as well.

These functions are meant to be used within other functions such as hmscH. However, this help file was written for user who want to develop new approaches using this basic algorithm.

Value

start

Object of class HMSCparam.

rotation

List with the following items:

values

Matrix of eigenvalues after the update has been carried out. The matrix has the same dimension as rotationVal. If rotation was set to FALSE, the eigenvalues will be the same as the ones originally given to scamH (or scamHT or scamRandom).

vectors

A 3-dimensional array of eigenvectors after the update has been carried out. The array has the same dimension as rotationVect. If rotation was set to FALSE, the eigenvectors will be the same as the ones originally given to scamH (or scamHT or scamRandom).

For scamH and scamHT:

sdvalue

An object of the same dimension as the argument sdvalue. It presents the standard deviations for associated to each of the X parameter after the update has been carried out. If burning was set to FALSE, sdvalue will be the same as the ones originally given to scamH or scamHT as an argument.

accept

An object of the same dimension as the argument accept. It presents the number of times each new regression parameter has been accepted when estimating the parameters of X. If burning was set to FALSE, accept will be the same as the ones originally given to scamH or scamHT as an argument.

For scamRandom:

sdvalue

A list of three component containing the updated standard deviations. This list includes exactly the same components as the ones first included in the function as argument.

accept

A list of three component containing the updated standard deviations. This list includes exactly the same components as the ones first included in the function as argument.

Note

No example are given for this function because this function is meant to be ran within another function. As explained in the Details section above.

Author(s)

F. Guillaume Blanchet

See Also

hmscH, hmscHT, loglikelihood