R: Summarizing and plotting Bayesian Survival Trajectory...

summary.basta {BaSTA}

R Documentation

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.type = "traces", trace.name = "theta",
                       densities = FALSE, noCIs = FALSE, minSurv = NULL,
                       ...)

Arguments

`object`	An object of class `basta`.
`x`	An object of class `basta`.
`plot.type`	A character vector indicating the type of plot to be produced. Options are: “`traces`” for the MCMC traces; “`demorates`” for the resulting survival and mortality curves; and “`gof`” for a comparison between the estimated parametric survival function and the life table `lx` variable.
`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.
`densities`	Logical indicating whether to plot the parameter posterior densities instead of the traces.
`noCIs`	Logical indicating whether the 95% credible intervals should be included in the plot.
`minSurv`	Numerical value for the minimum survival level, acts as `xlim` using the survival as reference.
`...`	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.type is set to “demorates”, 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`	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`	Numeric vector with 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 fernando_colchero@eva.mpg.de, Owen R. Jones jones@biology.sdu.dk

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.

Examples

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

## Print summary output:
summary(bastaCMRout)

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

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

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

## Plot predicted mortality and survival:
plot(bastaCMRout, plot.type = "demorates")

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

## Change the color and the legend text:
plot(bastaCMRout, plot.type = "demorates", 
     col = c("dark green", "dark blue"),
     names.legend = c("Females", "Males"))

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

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

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

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

[Package BaSTA version 2.0.0 Index]