nimbleEcology: custom NIMBLE distributions for ecologists

What is nimbleEcology?

nimbleEcology is an auxiliary nimble package for ecologists. nimbleEcology contains a set of distributions corresponding to some common ecological models. When the package is loaded, these distributions are registered to NIMBLE and can be used directly in models. nimbleEcology contains distributions often used in modeling abundance, occupancy and capture-recapture studies.

Why use nimbleEcology?

Ecological models for abundance, occupancy and capture-recapture often involve many discrete latent states. Writing such models can be error-prone and in some cases can lead to slow MCMC mixing. We’ve put together a collection of distributions in nimble to make writing these models easier

• Easy to use. Using a nimbleEcology distribution is easier than writing out probabilities or hierarchical model descriptions.
• Minimize errors. You don’t have to lose hours looking for the misplaced minus sign; the distributions are checked and tested.
• Integrate over latent states. nimbleEcology implementations integrate or sum likelihoods over latent states. This eliminates the need for sampling these latent variables, which in some cases can provide efficiency gains, and allows maximum likelihood (ML) estimation methods with hierarchical models.

How to use

nimbleEcology can be installed directly from CRAN as follows.

install.packages("nimbleEcology")

Once nimbleEcology is installed, load it using library. It will also load nimble.

library(nimbleEcology)

Note the message indicating which distribution families have been loaded.

Which distributions are available?

The following distributions are available in nimbleEcology.

• dOcc (occupancy model)
• dDynOcc (dynamic occupancy model)
• dHMM (hidden Markov model)
• dDHMM (dynamic hidden Markov model)
• dCJS (Cormack-Jolly-Seber or mark-recapture model)
• dNmixture (N-mixture model)
• dYourNewDistribution Do you have a custom distribution that would fit the package? Are we missing a distribution you need? Let us know! We actively encourage contributions through GitHub or direct communication.

Example code

The following code illustrates a NIMBLE model definition for an occupancy model using nimbleEcology. The model is specified, built, and used to simulate some data according to the occupancy distribution.

library(nimbleEcology)

occ_code <- nimbleCode({
  psi ~ dunif(0, 1)
  p ~ dunif(0, 1)
  for (s in 1:nsite) {
    x[s, 1:nvisit] ~ dOcc_s(probOcc = psi, probDetect = p,
                            len = nvisit)
  }
})

occ_model <- nimbleModel(occ_code,
               constants = list(nsite = 10, nvisit = 5),
               inits = list(psi = 0.5, p = 0.5))

## defining model...

## building model...

## setting data and initial values...

## running calculate on model (any error reports that follow may simply reflect missing values in model variables) ... 
## checking model sizes and dimensions... This model is not fully initialized. This is not an error. To see which variables are not initialized, use model$initializeInfo(). For more information on model initialization, see help(modelInitialization).
## model building finished.

set.seed(94)
occ_model$simulate("x")
occ_model$x

##       [,1] [,2] [,3] [,4] [,5]
##  [1,]    0    0    0    0    0
##  [2,]    0    0    0    0    0
##  [3,]    0    0    0    0    0
##  [4,]    0    0    0    0    0
##  [5,]    1    1    1    0    1
##  [6,]    0    0    0    1    0
##  [7,]    0    0    0    0    0
##  [8,]    0    0    0    0    1
##  [9,]    1    1    1    0    0
## [10,]    0    1    0    0    0

How to learn more

Once the package is installed, you can check out the package vignette with vignette(“nimbleEcology”). Documentation is available for each distribution family using the R syntax ?distribution, for example

?dHMM

For more detail on marginalization in these distributions, see the paper “One size does not fit all: Customizing MCMC methods for hierarchical models using NIMBLE” ([Ponisio et al. 2020])(https://doi.org/10.1002/ece3.6053).