simulateModelCount: Simulate Datasets based on a Fitted Model for Lek Counts
In ClementCalenge/caperpyogm: Estimation of the Number of Male Capercaillie in the Pyrenees Mountains

Description Usage Arguments Details Value Author(s) References See Also Examples

The function simulateModelCount simulate M datasets from a model to lek counts datasets (where M is the number of MCMC iterations used to fit the model). These datasets can be used to assess the goodness of fit of the model. Residuals and prediction can be calculated with residuals and predict.

simulateModelCount(coefs, dataList, verbose = TRUE)

## S3 method for class 'caperpySim'
residuals(object,
                               groupingFactor = c("none", "lek",
                                                  "lekyear", "lekperiod"), 
                               includeGrouping = FALSE, ...)

## S3 method for class 'caperpySim'
predict(object,
                             groupingFactor = c("none", "lek",
                                                "lekyear", "lekperiod"),
                             includeGrouping = FALSE, se.fit = FALSE, ...)

## S3 method for class 'caperpySim'
print(x, ...)

`coefs`	An object of class `mcmc.list` returned by the function `fitModelCount`
`dataList`	An object of class `caperpyData` returned by the function `dataCount2jags`.
`verbose`	logical value indicating whether the function should give information on the progression of the function.
`object,x`	an object of class `"caperpySim"`
`groupingFactor`	character string indicating how to calculate predictions and residuals (see Details)
`includeGrouping`	logical value indicating whether the grouping factor should be included in the output.
`se.fit`	logical value indicating whether the standard error should be calculated for each prediction
`...`	additional arguments that can be passed to the function `print`

The simulation of datasets can be used to assess the goodness of fit of the model to the data (using randomization tests). It can also be calculate residuals and predictions of a model for count data. In practice, we use the parameters generated by each MCMC iteration to simulate a new dataset (i.e., counts that could have been observed under the model). Then, the user can compare an observed summary statistics (e.g. total number of animals detected by the observers summed during the whole period) to the same statistics calculated with each simulated dataset.

The function predict will calculate the mean simulated value for each count (by averaging the simulated values for the count). The function can also be used to predict the mean count for each level of a grouping factor (for example, instead of the mean simulated value for a given count during a given year on a given lek, calculating the mean count on a given lek over all years and count occasions on each simulated dataset, then averaging these mean counts over simulations). Allowed grouping factors are the lek, the lek-year combination, the lek-period combination. "none" indicate that a prediction will be returned for each count occasion.

The function residuals will calculate the standardized residual (using this prediction as predicted value, and using the standard deviation of each simulated value as an estimate of residual variation for this value).

simulateModelCount returns an object of class "caperpySim", which is a list with two elements: (i) an element named origData, which is the original dataset formatted as a data.frame, which contains the results of the N original counts, as well as explanatory variables (regions, leks, period, nbobservers, etc.), and (ii) an element named sim, which is a matrix with N rows and S columns containing the S simulated count datasets according to the model.

residuals.caperpySim and predict.caperpySim return either a vector of numeric values (if both se.fit and includeGrouping are both FALSE) or a data.frame containing the residuals/predictions, and the SE and/or grouping factor.

Clement Calenge clement.calenge@ofb.gouv.fr

Calenge C., Menoni E., Milhau B., Foulche K, Chiffard J., Marchandeau S. (in prep.). The participatory monitoring of the capercaillie in the French Pyrenees.

dataCount2jags for more information on how to fit a model to count data, simBinREY for a list of datasets containing the result of the application of simulateModelCount to various registered models.

## We work on the dataset lekcounts
head(lekcounts)

## We prepare the dataset to fit the model with JAGS
dataList <- dataCount2jags(lekcounts$lek, lekcounts$period,
                           lekcounts$nbobs, lekcounts$nbmales,
                           lekcounts$gr, as.numeric(factor(lekcounts$type)),
                           lekcounts$natun, lekcounts$year)
dataList

## We then fit the model. WARNING!!! THIS COMMAND IS VERY SLOW AND
## CAN TAKE SEVERAL HOURS
## Note that the result is stored as a dataset in the package
## Not run: 
coefModelCountDetectBinREY <- fitModelCount(dataList, "modelCountDetectBinREY")

## End(Not run)


## We then simulate datasets based on these coefficients
## WARNING, THIS IS ALSO RATHER SLOW !!!!!
## Note that the result is also stored as a dataset in the package
## Not run: 
simBinREY <- simulateModelCount(coefModelCountDetectBinREY, dataList)

## End(Not run)

## Residuals vs prediction:
plot(predict(simBinREY), residuals(simBinREY), xlab="predictions",
     ylab="residuals")


## The same plot, but using the lek as a grouping factor
plot(predict(simBinREY, groupingFactor="lek"),
     residuals(simBinREY, groupingFactor="lek"),
     xlab="predictions",
     ylab="residuals")