mcmc.aggregate.pc: Posterior predictive sampling, aggregtion of abundance...
In NMML/agTrend: Estimate Linear Trends for Aggregated Abundance Data

Description Usage Arguments Details Value

Function for sampling from the posterior predictive distribution of abundance (counts) at individual sites. Then aggregating the counts over the specified aggregation variable.

mcmc.aggregate.pc(start, end, data, obs.formula = NULL, aggregation,
  site.data, abund.name, time.name, site.name, sig.abund, incl.zeros = TRUE,
  forecast = FALSE, ln.adj = 0, upper = Inf, lower = -Inf, burn, iter,
  thin = 1, prior.list = NULL, keep.site.abund = FALSE,
  keep.site.param = FALSE, keep.obs.param = FALSE)

`start`	The starting time for trend estimation
`end`	The end time for trend estimation
`data`	A `data.frame` that contains the abundance survey data.
`obs.formula`	A formula object specifying the model for the observation data
`aggregation`	A factor variable. Aggregation is performed over each level of the factor.
`site.data`	A data frame giving the augmentation model for each site. See 'Details'
`abund.name`	A character string giving the name of the data to be aggregated
`time.name`	A character string giving the name of the time variable
`site.name`	A character string giving the name of the site variable. The variable should be a factor
`sig.abund`	A numeric vector the same length as `nrow(data)` which contains the known observation error standard deviations.
`incl.zeros`	If `incl.zeros=TRUE` (default), and zero inflation models are used, then the zeros become part of the 'true' abundance process and are used for trend estimation and abundance prediction.
`forecast`	A logical indicating whether to allow forecasting aggregations past the last observed time.
`ln.adj`	The adjustment for taking logs of counts if zeros are present, e.g., log(n + ln.adj).
`upper`	A data frame containing the upper bounds for augmentation of each site. See 'Details'
`lower`	A data frame containing the lower bounds for augmentation of each site. See 'Details'
`burn`	The length of burnin for the MCMC augmentation and aggregation.
`iter`	The number of MCMC iterations
`thin`	The amount of thinning of the MCMC sample. e.g., `thin=5` implies keeping every 5th MCMC sample for inference
`prior.list`	A named list containing the prior distributions for the parameters and random effects
`keep.site.abund`	Logical. Should the augmented site abundance be retained.
`keep.site.param`	Logical. Should the site augmentation parameters be retianed.
`keep.obs.param`	Logical. Should the observation parameters (gamma) be retianed.

This function is the workhorse for the agTrend package. It performs MCMC sampling of the posterior predictive distribution of the abundance at each site at each time, N_st. The abundance at each site is modeled, in its most general form, with a zero-inflated, nonparameteric model,

z_st = beta_s0 + beta_s1 * t + omega_st + delta_st if N_st > 0,

where beta_s0 + beta_s1 * t is the linear trend, omega is a process convolution, and delta_st is an iid normal error variable. The zero-inflation part is added via the probit regression model

probit{P(N_st > 0)} = theta_s0 + theta_s1 * t + alpha_st,

where theta_s0 and theta_s1 are linear regression coefficients and alpha is a RW model.

In order to account for observation effects or changing methodology through time one can specify an obs.model. The obs.model is a R formula object that specifies variables in data that can account for differences due to sampling methodology alone. If obs.model is provided, the observation model is specified as

y_st = x_st gamma + z_st + eps_st,

where y_st is the raw observed log abundance, x_st is a vector of covariates used to standardize the observed abundance, gamma is a vector of coefficients, and [eps_st]=N(0,sigma_st^2). Currently, sigma_st is considered to be known and is specified as a column in data by the sig.abund argument. Thus, z_st represents the standardized (wrt the survey method) abundance. See demo(wdpsNonpups) for an example.

For each iteration of the MCMC sampler, the complete data is aggregated (i.e., summed) over all sites within a specified region (defined by the aggregation argument). Thus, one can obtain a posterior predictive sample from the aggregated abundance for every time between the first time in the data set and the last. By using the posterior predictive distribution, we can account for parameter uncertainty at each site as well as sampling variability of the survey. Even though we are using the Bayesian inference paradigm, we still capture the essence of frequentist inference by accounting for the 'replication' of the survey effort by using the predictive distribution even for times and places where we have survey data. Using the aggregations, the average linear trend is calculated for all years from start to end for each MCMC iteration.

The site.data data.frame can be provided to reduce the most general model given above to submodels when there is not adequate data to fit the full model or, if zero-inflation is not necessary. The site.data must be a data.frame with columns

site.name- Column of all the sites in data. The name must be given by site.name
trend- A column of all augmentation models to be used at each site, can be one, any only one, of the following: c("const","lin","RW") for a constant mean, linear mean, RW model respectively. Each generalization includes all previous models, e.g., an RW model contains a linear slope and an intercept.
avail- The same as the trend column, except this specifies the model for the zero-inflation component and can additionally include "none" if a zero-inflation model is not desired.

Examples of this function's use can be seen in the demo(package="agTrend") files.

A named list with the following elements:

`trend.summary`	Summary of the posterior predictive linear trend
`aggregation.summary`	Summary of the site aggregations for every time between the first and last
`site.summary`	A summary of the abundance augmentation for every site and every time.
`mcmc.sample`	A named list containing all of the MCMC sample after thinning.
`original.data`	The original data in `data`.