mig.diagnose {bayesMig}

MCMC convergence diagnostics

Description

Runs convergence diagnostics of existing migration Markov chains using the raftery.diag function from the coda package.

Usage

mig.diagnose(
  sim.dir,
  thin = 80,
  burnin = 2000,
  express = FALSE,
  country.sampling.prop = NULL,
  keep.thin.mcmc = FALSE,
  verbose = TRUE
)

mig.raftery.diag(
  mcmc = NULL,
  sim.dir = NULL,
  burnin = 0,
  country = NULL,
  par.names = NULL,
  par.names.cs = NULL,
  country.sampling.prop = 1,
  verbose = TRUE,
  ...
)

estimate.a.hw(mcmc, burnin = 0, thin = NULL)

Arguments

sim.dir

Directory with MCMC simulation results.

thin

Thinning interval.

burnin

Number of iterations to discard from the beginning of the parameter traces.

express

Logical. If TRUE, the convergence diagnostic is run only on the country-independent parameters. If FALSE, the country-specific parameters are included in the diagnostics. The number of countries can be controlled by country.sampling.prop.

country.sampling.prop

Proportion of countries to include in the diagnostics. If it is NULL and express=FALSE, all countries are included. Setting a number between 0 and 1 will determine the proportion of countries to be randomly sampled. For long Markov chains, this argument may significantly influence the runtime of this function.

keep.thin.mcmc

Logical. If TRUE, the thinned traces used for computing the diagnostics are stored on disk.

verbose

Logical value. Switches log messages on and off.

mcmc

A bayesMig.mcmc or bayesMig.mcmc.set object. If not given, the object is loaded from the simulation directory given by sim.dir.

country

Name or code of a country. If it is given, only country-specific parameters parameters of that country are considered.

par.names

Names of country-independent parameters for which the Raftery diagnostics should be computed. By default all parameters are used.

par.names.cs

Names of country-specific parameters for which the Raftery diagnostics should be computed. By default all parameters are used.

...

Additional arguments passed to the mig.coda.list.mcmc function.

Details

The mig.diagnose function invokes the mig.raftery.diag function separately for country-independent parameters and for country-specific parameters. It results in two possible states: red, i.e. it did not converge, and green, i.e. it converged. The resulting object is stored in ‘{sim.dir}/diagnostics/bayesMig.convergence_{thin}_{burnin}.rda’ and can be accessed using the function get.mig.convergence.

Function has.mcmc.converged from the bayesTFR package can be used to check if the existing diagnostics converged.

For details on the mig.raftery.diag function, see tfr.raftery.diag.

The estimate.a.hw function estimates an optimal value for the a.half.width argument in run.mig.mcmc.

Value

mig.diagnose returns an object of class bayesMig.convergence containing summaries of the convergence check inputs and outputs. It has the same structure as bayesTFR.convergence. In addition it has an element a.hw.est which is the estimated value for the a.half.width argument in run.mig.mcmc.

See Also

tfr.raftery.diag, raftery.diag, get.mig.convergence

Examples

# See examples in ?bayesMig and ?get.mig.convergence