summary.basta: Summarizing and plotting Bayesian Survival Trajectory...

In BaSTA: Age-Specific Survival Analysis from Incomplete Capture-Recapture/Recovery Data

Summarizing and plotting Bayesian Survival Trajectory Analysis (BaSTA) model outputs.

Description

These functions are all generic methods for class basta.

Usage

## S3 method for class 'basta'
summary(object, ...)
## S3 method for class 'basta'
print(x, ...)
## S3 method for class 'basta'
plot(x, plot.trace = TRUE, trace.name = "theta", 
    fancy = FALSE,...)

Arguments

object	An object of class basta.
x	An object of class basta.
plot.trace	A logical argument. If TRUE the raw parameter traces are plotted, else, the predictive intervals for the resulting survival probability and mortality rates are plotted.
trace.name	Character string indicating the set of parameters or posteriors to be plotted. The options are: “theta” to plot the survival model parameters; “gamma” to plot the proportional hazards parameters (if it applies, else plot.basta returns an error); “pi” to plot the recapture probabilities; and "post" to plot the conditional posteriors for the parameters and for the latent ages at death, and the full posterior for the model.
fancy	A logical argument indicating to plot a combined plot of trace densities and estimated vital rates.
...	Additional arguments passed to functions print, summary and plot (see details).

Details

For objects of class basta, the print function returns three summary elements describing the model and its results, namely: call, run, coefficients and, if convergence was reached, the DIC values for model fit. call describes the basic model used (i.e. exponential, Gompertz, Weibull or logistic), the shape chosen, “simple”, “Makeham” or “bathtub”, the covariate structure chosen, “fused”, “prop.haz” or “all.in.mort” and which covariates (if any) were categorical and which continuous. Argument digits can be used for number formatting (see summary() or signif() for details).

The summary element coefficients prints out the estimated coefficients for all parameters in the model, as well as their standard errors and 95% upper and lower credible intervals. It also includes a measure of serial autocorrelation for each parameter calculated from the thinned parameter chains, an update rate per parameter, and the potential scale reduction factor for each parameter as a measure of convergence (Gelman et al. 2004).

Function summary includes all the previous elements, as well as a summary description of the priors and jump standard deviations for all survival parameters, a calibration of the Kullback-Leibler discrepancy as a measure of parameter similarities for those parameters associated to categorical covariates (McCulloch 1989), and a measure of model fit based on the deviance information criterion (DIC) (Spiegelhalter et al. 2002).

Function plot takes objects of class basta to create trace plots or, if the argument for plot.trace is set to FALSE, it plots estimated survival probabilities and mortality rates with their 95% predictive intervals. If argument plot.trace is set to FALSE, argument xlim can be used to define a range of ages to visualize survival and mortality trends. Also, if logical argument noCI is set to TRUE, credible intervals around survival and mortality are not plotted, leaving only the mean trends. This can be handy when several categorical covariates have been evaluated and the plots get too crowded.

Other arguments for plot include names.legend to indicate alternative names for the legend of vital rates plots. Also, when plot.trace is FALSE, argument xlim can be changed to display only a subest of the support. When argument noCI is TRUE, then the credible intervals around the vital rates are not displayed.

Value

Function summary() outputs the folowing values:

coefficients	A matrix with estimated coefficients (i.e. mean values per parameter on the thinned sequences after burnin), which includes standard errors, upper and lower 95% credible intervals, update rates per parameter (commonly the same for all survival and proportional hazards parameters), serial autocorrelation on the thinned sequences and the potential scale reduction factor for convergence (see Convergence value below).
DIC	Basic deviance information criterion (DIC) calculations to be used for model selection (Spiegelhalter et al. 2002).
KullbackLeibler	List with Kullback-Leibler discrepancy matrices between pair of parameters for categorical covariates (McCulloch 1989, Burnham and Anderson 2001) and McCulloch's (1989) calibration measure. If only one simulation was ran or if no convergence was reached, then the returned value is “Not calculated”.
convergence	A matrix with convergence coefficients based on potential scale reduction as described by Gelman et al. (2004). If only one simulation was ran, then the returned value is “Not calculated”.
modelSpecs	Model specifications inidicating the model, the shape and the covariate structure that were specified by the user.
settings	A vector indicating the number of iterations for each MCMC, the burn in sequence, the thinning interval, and the number of simulations that were run.

Author(s)

Fernando Colchero [e-mail], Owen R. Jones [e-mail] and Maren Rebke [e-mail]

References

Gelman, A., Carlin, J.B., Stern, H.S. and Rubin, D.B. (2004) Bayesian data analysis. 2nd edn. Chapman & Hall/CRC, Boca Raton, Florida, USA.

McCulloch, R.E. (1989) Local model influence. Journal of the American Statistical Association, 84, 473-478.

Spiegelhalter, D.J., Best, N.G., Carlin, B.P. and Van Der Linde, A. (2002) Bayesian measures of model complexity and fit. Journal of the Royal Statistical Society: Series B 64, 583-639.

See also:

Colchero, F. and J.S. Clark (2012) Bayesian inference on age-specific survival from capture-recapture data for censored and truncated data. Journal of Animal Ecology. 81(1):139-149.

Colchero, F., O.R. Jones and M. Rebke. (2012) BaSTA: an R package for Bayesian estimation of age-specific survival from incomplete mark-recapture/recovery data with covariates. Method in Ecology and Evolution. DOI: 10.1111/j.2041-210X.2012.00186.x

See Also

basta

Examples

## Load BaSTA output:
data("sim1Out", package = "BaSTA")

## Print summary output:
summary(sim1Out)

## Plot traces for mortality parameters (theta):
plot(sim1Out)

## Plot traces for proportional hazards parameters (gamma):
plot(sim1Out, trace.name = "gamma")

## Plot traces for recapture probability(ies) (pi):
plot(sim1Out, trace.name = "pi")

## Plot predicted mortality and survival:
plot(sim1Out, plot.trace = FALSE)

## Change the color for each covariate on 
## the predicted vital rates:
plot(sim1Out, plot.trace = FALSE, 
     col = c("dark green", "dark blue"))

## Change the color and the legend text:
plot(sim1Out, plot.trace = FALSE, 
     col = c("dark green", "dark blue"),
     names.legend = c("Females", "Males"))

## Plot predicted mortality and survival 
## between 2 and 8 years of age:
plot(sim1Out, plot.trace = FALSE, xlim = c(2, 8))

## Plot predicted mortality and survival 
## between 2 and 8 years of age without
## credible intervals:
plot(sim1Out, plot.trace = FALSE, xlim = c(2, 8), 
     noCI = TRUE)

## Plot parameter densities and predicted vital  
## rates in the same plot (i.e. fancy):
plot(sim1Out, fancy = TRUE)

## Change colors and legend names for the 
## "fancy" plot:
plot(sim1Out, fancy = TRUE, col = c("dark green", "dark blue"),
     names.legend = c("Females", "Males"))

BaSTA documentation built on Oct. 5, 2022, 5:06 p.m.