Some diagnostics for fitted dose-response models

Summary method for objects of class rjtrace, as returned by trace_rjMCMC. Produces a text-based summary of: (1) effective sample sizes, (2) acceptance rates, (3) model convergence, (4) posterior model probabilities, and (5) posterior inclusion probabilities (PIPs) for contextual covariates (where appropriate).

# S3 method for rjtrace
summary(
  rj.obj,
  eff.n = TRUE,
  accept.rate = TRUE,
  convergence = TRUE,
  gelman.rubin = 1.1,
  model.ranks = TRUE,
  n.top = 10,
  southall.2019 = TRUE,
  covariate.prob = TRUE,
  ff.prob = TRUE,
  x.off = 0.1,
  rmd = FALSE,
  do.plot = TRUE
)

Arguments

rj.obj	Input rjMCMC object, as returned by trace_rjMCMC.
eff.n	Logical. If TRUE, returns estimates of the effective sample size for each model parameter.
accept.rate	Logical. If TRUE, returns the acceptance rate (calculated after burn-in) for each model parameter.
convergence	Logical. If TRUE, assesses convergence using the multivariate potential scale reduction factor (Gelman-Rubin statistic), as implemented in gelman.diag.
gelman.rubin	Threshold for determining convergence based on the Gelman-Rubin statistic. Defaults to 1.1.
model.ranks	Logical. If TRUE, returns a summary of posterior model probabilities and associated model rankings.
n.top	Number of top-ranking models to display when model.ranks = TRUE.
southall.2019	Logical. Whether to produce a tile plot showing species groupings, as identified in Southall et al. (2019) . This is only relevant if real-world BRS data are being analysed (and therefore, sim = FALSE).
covariate.prob	Logical. If TRUE, returns a summary of posterior inclusion probabilities (PIPs).
ff.prob	Logical. If TRUE, returns a summary of posterior probabilities for each functional form (monophasic vs. biphasic).
x.off	Offset for probability values in tile plots.
rmd	Logical. This is used to create a different layout of plots when exporting results using create_report.
do.plot	Logical. If TRUE, returns diagnostic plots in addition to text-based summaries.

Value

A detailed summary, printed to the R console.

References

Southall BL, Finneran JJ, Reichmuth C, Nachtigall PE, Ketten DR, Bowles AE, Ellison WT, Nowacek DP, Tyack PL (2019). “Marine mammal noise exposure criteria: Updated scientific recommendations for residual hearing effects.” Aquatic Mammals, 45(2). doi: 10.1578/AM.45.2.2019.125 .

See also

simulate_data example_brs summary.rjdata

Author

Phil J. Bouchet

Examples

if (FALSE) {
library(espresso)

# Import the example data, excluding species with sample sizes < 5
# and considering the sonar covariate
mydat <- read_data(file = NULL, min.N = 5, covariates = "sonar") 
summary(mydat)

# Configure the sampler
mydat.config <- configure_rjMCMC(dat = mydat,
                                 model.select = TRUE,
                                 covariate.select = FALSE,
                                 function.select = FALSE,
                                 n.rep = 100)
summary(mydat.config)

# Run the reversible jump MCMC
rj <- run_rjMCMC(dat = mydat.config,
                 n.chains = 2,
                 n.burn = 100,
                 n.iter = 100,
                 do.update = FALSE)
summary(rj)
}