
MCMC control for magComp
magCompControl.RdCreates a control list for magComp(). Negative-binomial settings apply
only when magnitude is fitted; composition_link applies only when
composition is fitted.
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. WithNULL, serial fitting uses R's current RNG state, so an externalset.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; settingnb_sizealone 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_sizeis estimated.- metropolis
List with
adapt(defaultTRUE),batch_length(default 25), andtarget_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_link
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.FALSEprepares 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.
See also
magCompPriors, summary;
the technical guide's Sampler algorithm and Numerical implementation sections
in magComp-package.