Skip to contents

Creates a control list for magComp(). Negative-binomial settings apply only when magnitude is fitted; composition_link applies only when composition is fitted.

Usage

magCompControl(n_samples = 2000, n_burn = 1000, n_thin = 1,
               n_chains = 1, n_cores = 1,
               chain_seeds = NULL,
               n_report = 100, nb_size = 1000,
               nb_size_tuning = 0.25,
               metropolis = list(),
               composition_link = c("probit", "logit"),
               run_sampler = TRUE, verbose = TRUE)

Arguments

n_samples

Total number of MCMC iterations per chain, including burn-in. Must be an integer greater than n_burn.

n_burn

Number of initial iterations discarded from each chain.

n_thin

Thinning interval after burn-in. Must leave at least one retained draw per chain.

n_chains

Number of MCMC chains to run from the R side. Chains are run sequentially unless n_cores > 1.

n_cores

Number of R worker processes used for chain-level parallelism on Unix-like systems. Values greater than one fall back to serial execution on platforms without forked processes.

chain_seeds

Optional integer vector of length n_chains. When supplied, each chain is started after setting the corresponding R seed. With NULL, serial fitting uses R's current RNG state, so an external set.seed() can reproduce a fitting and prediction sequence. Supply explicit chain seeds to reproduce parallel fitting under R's default RNG settings.

n_report

Progress reporting interval.

nb_size

Fixed negative-binomial size, or its automatic starting value when size is estimated. By default size is estimated for magnitude formulas without iid or spatial terms and fixed otherwise. Set magCompPriors(magnitude = list(size = NULL)) to fix size explicitly; setting nb_size alone does not change estimation status. Large fixed values approximate Poisson magnitude counts.

nb_size_tuning

Initial random-walk Metropolis tuning standard deviation on the log size scale when nb_size is estimated.

metropolis

List with adapt (default TRUE), batch_length (default 25), and target_accept (default zero, selecting 0.44 for scalar proposals and 0.234 for multivariate proposals). An explicit value between zero and one overrides the target. Covariance blocks use an initial scale search within burn-in, followed by diminishing adaptation of proposal covariance and scale, including after burn-in. The separate size update adapts its scalar scale only during burn-in.

Composition stick-breaking link: "probit" (the default) or "logit". The same link applies to all allocation blocks.

run_sampler

Logical; TRUE (the default) fits the model. FALSE prepares the model and resolves settings without sampling.

verbose

Logical; print sampler progress.

Details

Each chain runs exactly n_samples iterations. The number of retained draws is floor((n_samples - n_burn) / n_thin). The first saved draw is at iteration n_burn + n_thin. Any final iterations after the last thinning boundary still run but are not saved. For example, 25,000 total iterations, 10,000 burn-in iterations, and thinning by 10 retain 1,500 draws per chain. Output array dimensions and prediction metadata count retained draws, not total iterations.

The initial covariance scale search uses at most 20 complete batches and never exceeds burn-in. Each batch contains full sampler sweeps. After that search, adaptation uses gain \((b+1)^{-0.8}\) for adaptive batch number \(b\); the empirical covariance uses the chain states, including rejected proposals. There is one block per magnitude process and one per composition factor. Fixed covariance parameters are excluded. Set adapt = FALSE to use the initial proposal throughout; with no burn-in the initial search is skipped.

The composition link applies to all allocation blocks in a fit. Fitted values and prediction use the matching inverse link when converting composition linear predictors to stick-breaking probabilities.

Value

A magCompControl object.

See also

magCompPriors, summary; the technical guide's Sampler algorithm and Numerical implementation sections in magComp-package.

Examples

magCompControl(n_samples = 25000, n_burn = 10000, n_thin = 10)