Gibbs Samplers

GibbsBase	Base class for Gibbs samplers of species spatial occupancy models.
LogitICARGibbs	Gibbs sample using logit link and ICAR model for spatial random effects.
LogitRSRGibbs	Gibbs sampler using logit link and RSR model for spatial random effects.
ProbitRSRGibbs	Sampler using probit link and RSR model for spatial random effects.

Base Sampler

class occuspytial.gibbs.base.GibbsBase(Q, W, X, y, hparams=None, random_state=None)

Base class for Gibbs samplers of species spatial occupancy models.

Parameters

Qnp.ndarray

Spatial precision matrix of spatial random effects.

WDict[int, np.ndarray]

Dictionary of detection corariates where the keys are the site numbers of the surveyed sites and the values are arrays containing the design matrix of each corresponding site.

Xnp.ndarray

Design matrix of species occupancy covariates.

yDict[int, np.ndarray]

Dictionary of survey data where the keys are the site numbers of the surveyed sites and the values are number arrays of 1’s and 0’s where 0’s indicate “no detection” and 1’s indicate “detection”. The length of each array equals the number of visits in the corresponding site.

hparams{None, Dict[str, Union[float, np.ndarray]}, optional

Hyperparameters of the occupancy model. valid keys for the dictionary are:

• a_mu: mean of the normal prior of detection covariates.

• a_prec: precision matrix of the normal prior of detection covariates.

• b_mu: mean of the normal prior of occupancy covariates.

• b_prec: precision matrix of the normal prior of occupancy covariates.

• tau_rate: rate parameter of the Gamma prior of the spatial parameter.

• tau_shape: shape parameter of the Gamma prior of the spatial parameter.

random_state{None, int, numpy.random.SeedSequence}

A seed to initialize the bitgenerator.

Attributes

chainChain

Posterior chain object. An instance of occuspytial.chain.Chain

distsFixedState

Container for conditional probability distribution instances of posterior parameters.

fixedFixedState

A Container for fixed values and parameters who’s values remain constant during sampling. This variable must be an instance of FixedState.

rngnumpy.random.Generator

Instance of numpy’s Generator class, which exposes a number of random number generating methods.

stateState

A container to store model parameter values and other variables whose values change at various stages during sampling.

copy()

Create a copy of this classes’s instance.

Returns

outself

A copy of this object’s instance with the same attribute values.

sample(size, burnin=0, start=None, chains=2, progressbar=True)

Obtain posterior samples of the parameters of interest.

Only parameters {alpha, beta, tau} are stored after sampling, meaning the conditional detection and occupancy covariate coefficients, plus the posterior spatial parameter \(\\tau\) .

Parameters

sizeint

The number of total samples to generate.

burninint, optional

The number of initial samples to discard as “burnin” samples. burnin must be less than size.

start{None, Dict[str, np.ndarray]}, optional

Starting values of the parameters alpha, beta, tau and eta.

chainsint, optional

Number of chains to generate in parallel. Defauls to 1.

progressbarbool, optional

Whether to display the progress bar during sampling. Defaults to True.

Returns

outPosteriorParameter

Posterior samples of the parameters of interest.

Raises

ValueError

If the burnin values is larger than the number of samples requested or when the number of chains is not a positive integer.

step()

Step through one iteration of the sampler.

This method should execute the parameter update steps the Gibbs sampler should take in order to complete one iteration of the sampler.

Raises

NotImplementedError

If sample method is called but subclass does not implement a step method.

Logit link based

class occuspytial.gibbs.logit.LogitICARGibbs(Q, W, X, y, hparams=None, random_state=None)

Bases: occuspytial.gibbs.base.GibbsBase

Gibbs sample using logit link and ICAR model for spatial random effects.

Parameters

Qnp.ndarray

Spatial precision matrix of spatial random effects.

WDict[int, np.ndarray]

Dictionary of detection corariates where the keys are the site numbers of the surveyed sites and the values are arrays containing the design matrix of each corresponding site.

Xnp.ndarray

Design matrix of species occupancy covariates.

yDict[int, np.ndarray]

Dictionary of survey data where the keys are the site numbers of the surveyed sites and the values are number arrays of 1’s and 0’s where 0’s indicate “no detection” and 1’s indicate “detection”. The length of each array equals the number of visits in the corresponding site.

hparams{None, Dict[str, Union[float, np.ndarray]}, optional

Hyperparameters of the occupancy model. valid keys for the dictionary are:

• a_mu: mean of the normal prior of detection covariates.

• a_prec: precision matrix of the normal prior of detection covariates.

• b_mu: mean of the normal prior of occupancy covariates.

• b_prec: precision matrix of the normal prior of occupancy covariates.

• tau_rate: rate parameter of the Gamma prior of the spatial parameter.

• tau_shape: shape parameter of the Gamma prior of the spatial parameter.

random_state{None, int, numpy.random.SeedSequence}

A seed to initialize the bitgenerator.

pertubfloat, optional

The value by which to pertube the diagonal of the spatial precision matrix in order to stabilize the cholesky factorization of the posterior precision matrix of the \(\\eta\) parameter. This is sometimes referred to as modified cholesky decompostion [1] . It helps get numerically stable samples from the conditional distribution of this parameter.

See also

occuspytial.gibbs.probit.ProbitRSRGibbs

A gibbs sampler using a probit link function

Notes

The algorithm developed here is the same as the one presented in [2] except the model used to account for spatial correlation is the Intrinsic Conditional Autoregressive (ICAR) model. A polya-gamma random variable distribution is used in a data augmentation strategy in order to obtain known conditional distributions to sample from, thus arising the Gibbs sampler impelemented here. Details of the sampler are explained in [2] .

References

1

McSweeney, T. Modified Cholesky Decomposition and Applications. 2017; Masters thesis, University of Manchester.

2(1,2)

Clark, AE, Altwegg, R. Efficient Bayesian analysis of occupancy models with logit link functions. Ecol Evol. 2019; 9: 756– 768. https://doi.org/10.1002/ece3.4850.

Methods

sample(size, burnin=0, start=None, chains=1, progressbar=True)

step()

Complete one gibbs sampler update.

The method should not be called directly. It is called internally by the sample method.

class occuspytial.gibbs.logit.LogitRSRGibbs(Q, W, X, y, hparams=None, random_state=None, r=0.5, q=None)

Bases: occuspytial.gibbs.logit.LogitICARGibbs

Gibbs sampler using logit link and RSR model for spatial random effects.

This algorithm is an implementation of the gibbs sampler in [1] where a Reduced Spatial Regression (RSR) model is used to account for spatial autocorrelation in a single-season site occupancy model.

Parameters

Qnp.ndarray

Spatial precision matrix of spatial random effects.

WDict[int, np.ndarray]

Dictionary of detection corariates where the keys are the site numbers of the surveyed sites and the values are arrays containing the design matrix of each corresponding site.

Xnp.ndarray

Design matrix of species occupancy covariates.

yDict[int, np.ndarray]

Dictionary of survey data where the keys are the site numbers of the surveyed sites and the values are number arrays of 1’s and 0’s where 0’s indicate “no detection” and 1’s indicate “detection”. The length of each array equals the number of visits in the corresponding site.

hparams{None, Dict[str, Union[float, np.ndarray]}, optional

Hyperparameters of the occupancy model. valid keys for the dictionary are:

• a_mu: mean of the normal prior of detection covariates.

• a_prec: precision matrix of the normal prior of detection covariates.

• b_mu: mean of the normal prior of occupancy covariates.

• b_prec: precision matrix of the normal prior of occupancy covariates.

• tau_rate: rate parameter of the Gamma prior of the spatial parameter.

• tau_shape: shape parameter of the Gamma prior of the spatial parameter.

random_state{None, int, numpy.random.SeedSequence}

A seed to initialize the bitgenerator.

rfloat, optional

The threshold of non-negative eigenvalues to keep of the Moran matrix to form the RSR precision matrix. Defaults to 0.5, meaning only columns of the Moran matrix that have corresponding eigenvalues greater than 0.5 will be used. If q is set, then this parameter is ignored.

qint, optional

The number of columns of the Moran matrix to use in order to form the spatial precision matrix of the RSR model. If this parameter is used, then the value of the r parameter is ignore. If the value is None, then the default value of r is used to create the spatial precision matrix of the RSR model. Defaults to None.

See also

occuspytial.gibbs.logiit.LogitICARGibbs

The same sampler but using an ICAR model.

occuspytial.gibbs.probit.ProbitRSRGibbs

A gibbs sampler using a probit link function.

References

1

Clark, AE, Altwegg, R. Efficient Bayesian analysis of occupancy models with logit link functions. Ecol Evol. 2019; 9: 756– 768. https://doi.org/10.1002/ece3.4850.

Methods

sample(size, burnin=0, start=None, chains=1, progressbar=True)

Probit link based

class occuspytial.gibbs.probit.ProbitRSRGibbs(Q, W, X, y, hparams=None, random_state=None, r=0.5, q=None)

Bases: occuspytial.gibbs.base.GibbsBase

Sampler using probit link and RSR model for spatial random effects.

This algorithm is an implementation of the gibbs sampler in [1] where a Reduced Spatial Regression (RSR) model is used to account for spatial autocorrelation in a single-season site occupancy model, but a probit link function is used instead of a logit.

Parameters

Qnp.ndarray

Spatial precision matrix of spatial random effects.

WDict[int, np.ndarray]

Dictionary of detection corariates where the keys are the site numbers of the surveyed sites and the values are arrays containing the design matrix of each corresponding site.

Xnp.ndarray

Design matrix of species occupancy covariates.

yDict[int, np.ndarray]

Dictionary of survey data where the keys are the site numbers of the surveyed sites and the values are number arrays of 1’s and 0’s where 0’s indicate “no detection” and 1’s indicate “detection”. The length of each array equals the number of visits in the corresponding site.

hparams{None, Dict[str, Union[float, np.ndarray]}, optional

Hyperparameters of the occupancy model. valid keys for the dictionary are:

• a_mu: mean of the normal prior of detection covariates.

• a_prec: precision matrix of the normal prior of detection covariates.

• b_mu: mean of the normal prior of occupancy covariates.

• b_prec: precision matrix of the normal prior of occupancy covariates.

• tau_rate: rate parameter of the Gamma prior of the spatial parameter.

• tau_shape: shape parameter of the Gamma prior of the spatial parameter.

random_state{None, int, numpy.random.SeedSequence}

A seed to initialize the bitgenerator.

rfloat, optional

The threshold of non-negative eigenvalues to keep of the Moran matrix to form the RSR precision matrix. Defaults to 0.5, meaning only columns of the Moran matrix that have corresponding eigenvalues greater than 0.5 will be used. If q is set, then this parameter is ignored.

qint, optional

The number of columns of the Moran matrix to use in order to form the spatial precision matrix of the RSR model. If this parameter is used, then the value of the r parameter is ignore. If the value is None, then the default value of r is used to create the spatial precision matrix of the RSR model. Defaults to None.

See also

occuspytial.gibbs.probit.LogitRSRGibbs

The RSR gibbs sampler using a Logit link function.

Notes

When the assumption that the random effect \(\\epsilon\) is normally distributed fails to hold, then a functional form misspecification issue arises: if the model is still estimated as a probit model, the estimators of the coefficients \(\\beta\) are inconsistent [1].

References

1(1,2)

Joachim Inkmann(2000). Misspecified heteroskedasticity in the panel probit model: A small sample comparison of GMM and SML estimators. Journal of Econometrics, 97(2), 227-259

Methods

sample(size, burnin=0, start=None, chains=1, progressbar=True)

step()

Step through one iteration of the sampler.

This method should execute the parameter update steps the Gibbs sampler should take in order to complete one iteration of the sampler.

Raises

NotImplementedError

If sample method is called but subclass does not implement a step method.