Bayesian population model for boreal caribou

Source: R/caribouBayesianPM.R

A Bayesian population model that integrates prior information from Johnson et al.'s (2020) national analysis of demographic-disturbance relationships with local demographic data to project population growth.

caribouBayesianPM(
  survData = system.file("extdata/simSurvData.csv", package = "caribouMetrics"),
  ageRatio = system.file("extdata/simAgeRatio.csv", package = "caribouMetrics"),
  disturbance = system.file("extdata/simDisturbance.csv", package = "caribouMetrics"),
  betaPriors = "default",
  startYear = NULL,
  endYear = NULL,
  Nchains = 4,
  Niter = 15000,
  Nburn = 10000,
  Nthin = 2,
  N0 = 1000,
  survAnalysisMethod = "KaplanMeier",
  assessmentYrs = 1,
  inputList = list(),
  saveJAGStxt = tempdir(),
  quiet = TRUE
)

Arguments

survData

either a path to a csv file or a dataframe containing the columns "Year", "event", "enter" and "exit". Enter and exit are the beginning and end of the time interval and should be a number from 1 to 12 (December) or 0 (See Details). Event is 0 or 1 where 0 means the animal lived and 1 died. See survival::Surv() for more details.

ageRatio

either a path to a csv file or a dataframe containing the columns "Year","Count", and "Class". Where class can be either "calf" or "cow"

disturbance

either a path to a csv file or a dataframe containing the columns "Anthro","fire_excl_anthro", and "Year".

betaPriors

a list of model priors. See getPriors().

startYear, endYear

year defining the beginning of the observation period and the end of the projection period.

Nchains

Number of chains for the MCMC algorithm.

Niter

Number of iterations for the MCMC algorithm.

Nburn

Length of burn-in for the MCMC algorithm.

Nthin

Thinning rate for the MCMC algorithm.

N0

Initial population size.

survAnalysisMethod

Survival analysis method either "KaplanMeier" or "Exponential". The exponential method is only recommended when the number of collared animals (in survData) is small.

assessmentYrs

Number of years over which to assess population growth rate lambda.

inputList

an optional list of inputs with names matching the above. If an argument is included in this list it will override the named argument.

saveJAGStxt

file path. Directory where the JAGS model txt files will be saved. Default is tempdir().

quiet

logical. Should jags run quietly?

Value

a list with elements:

  • result: an rjags model object see R2jags::jags().

  • inData: a list of data that is used as input to the jags model:

    • survDataIn: survival data

    • disturbanceIn: disturbance data

    • ageRatioIn: composition data

Details

The model combines local observations of survival (survData), recruitment based on calf:cow ratios (ageRatio) and anthropogenic disturbance (disturbance) with prior information on the relationship between disturbance and survival and recruitment from the Johnson et al. (2020) national model (getPriors()) to reduce uncertainty and refine parameter estimates.

For a detailed description see the vignette (vignette("BayesianDemographicProjection", package = "caribouMetrics")).

Note: if survData contains values for enter that are > 0 these rows will be dropped to avoid errors when collars are added in the middle of the year. This will reduce the sample size in years when new collars are added.

Examples

# Using observed survival, recruitment and disturbance data
mod <- caribouBayesianPM(
  survData = system.file("extdata/simSurvData.csv",
                         package = "caribouMetrics"),
  ageRatio = system.file("extdata/simAgeRatio.csv",
                         package = "caribouMetrics"),
  disturbance = system.file("extdata/simDisturbance.csv",
                            package = "caribouMetrics"),
  Nchains = 1, Niter = 100, Nburn = 10, Nthin = 2
)
#> using Kaplan-Meier survival model
str(mod, max.level = 2)
#> List of 2
#>  $ result:List of 6
#>   ..$ model             :List of 8
#>   .. ..- attr(*, "class")= chr "jags"
#>   ..$ BUGSoutput        :List of 25
#>   .. ..- attr(*, "class")= chr "bugs"
#>   ..$ parameters.to.save: chr [1:13] "S.annual.KM" "R" "Rfemale" "pop.growth" ...
#>   ..$ model.file        : chr "/tmp/Rtmp9UTfwb/JAGS_run.txt"
#>   ..$ n.iter            : num 100
#>   ..$ DIC               : logi TRUE
#>   ..- attr(*, "class")= chr "rjags"
#>  $ inData:List of 3
#>   ..$ survDataIn   :'data.frame':	35 obs. of  8 variables:
#>   ..$ disturbanceIn:'data.frame':	35 obs. of  5 variables:
#>   ..$ ageRatioIn   :'data.frame':	70 obs. of  3 variables:

# Using simulated observation data
scns <- getScenarioDefaults(projYears = 10, obsYears = 10,
                            obsAnthroSlope = 1, projAnthroSlope = 5,
                            collarCount = 20, cowMult = 5)

simO <- simulateObservations(scns)

out <- caribouBayesianPM(survData = simO$simSurvObs, ageRatio = simO$ageRatioOut,
                          disturbance = simO$simDisturbance,
                          startYear = 2014, Nchains = 1, Niter = 100, Nburn = 10,
                          Nthin = 2)
#> Warning: warning, low sample size of adult females in at least one year
#> using Kaplan-Meier survival model