Skip to contents

Creates prior specifications for magComp. Omitted settings retain automatic defaults. On a prepared model, magCompSettings shows resolved priors and editable starts.

Usage

magCompPriors(magnitude = list(), composition = list())

Arguments

magnitude

Named list overriding magnitude prior defaults; see Details.

composition

Named list overriding composition prior defaults, with optional named blocks and their terms; see Details.

Details

Resolved model settings, starting values, and extracted samples contain only active components. Supplied starting values or nondefault priors for a disabled component are rejected by magComp().

Magnitude prior settings are:

coefficient_variance

Zero-mean normal variance for magnitude regression coefficients; default 100. It is independent of composition priors.

iid_variance, spatial_variance

Default inverse-gamma shape and scale for each magnitude iid or spatial term's variance; both default to c(shape = 2, scale = 1).

size

The default "auto" estimates negative-binomial size with c(shape = 1, rate = 0.01) when the magnitude formula has no iid or spatial terms; otherwise size is fixed at control$nb_size (default 1000). Supply a positive Gamma shape-rate pair to change the prior, or NULL to fix size explicitly. Size estimation is not allowed with magnitude random-effect terms. Composition factor terms do not impose this restriction.

terms

List named by formula term names. Each entry can override variance (inverse-gamma shape and scale) and covariance, a named list of uniform(lower, upper) priors for covariance parameters.

Composition defaults are:

SettingValue
intercept_variance9
slope_variance100
intercept_smoothing_variance1
slope_smoothing_variance4
loading_variance1

Coefficient and unconstrained loading priors are zero-mean normal. Anchor-diagonal loadings are estimated under the same normal prior restricted to \((0,\infty)\), a half-normal prior. loading_variance is the underlying normal variance before truncation: one gives half-normal scale one; four gives scale two. The half-normal variance itself is \(v(1-2/\pi)\), where \(v\) is loading_variance. Fixed upper-anchor zeros have no prior. Smoothing and normal prior variances are fixed hyperparameters, not sampled variances. Composition factor scores retain unit scale.

The default Gamma size prior has mean 100 and a central 95% interval of approximately 2.5 to 369. It is a proper, adjustable prior, not a noninformative one. Larger size means less extra count variation. Use magCompSettings(model) to inspect the resolved prior and estimation status. When size is estimated, starting$magnitude$size overrides its automatic start at control$nb_size.

A named composition$blocks list overrides these defaults for individual allocation blocks. Within each block, a named terms list can override loading_variance and the covariance prior list for each factor term. Within a factor term, the same loading_variance controls its half-normal diagonals and its unconstrained normal loadings. The diagonal Gibbs updates need no tuning parameter. Covariance priors may be shared across factors or specified in named lists by factor. Conditional block names use "child|parent". Magnitude term priors override magnitude defaults; composition block settings override composition defaults, and factor-term settings override their block. magCompCovModels describes covariance families and automatic supports. The prior is uniform on each covariance parameter, not on an effective range.

For inverse-gamma priors, the density is proportional to \(v^{-a-1}\exp(-b/v)\), with shape \(a\) and scale \(b\). Magnitude variance updates are Gibbs steps and need no tuning. Variance-prior parameters must be positive and finite. Covariance bounds must be finite, increasing, and within their parameter domains. Unknown names, unused covariance priors for fixed parameters or iid terms, and incompatible model term/block names are rejected.

Value

A magCompPriors object to pass as magComp(priors = ).

See also

magCompSmooth, magCompSettings, magCompNotation; the technical guide's Prior distributions section in magComp-package.

Examples

# Estimate size with a different Gamma prior (no magnitude random effects).
magCompPriors(magnitude = list(size = c(shape = 2, rate = 0.1)))
# Fix size at the value supplied through magCompControl(nb_size = ...).
magCompPriors(magnitude = list(size = NULL))

magCompPriors(
  magnitude = list(coefficient_variance = 25,
    terms = list(stand = list(variance = c(3, 1)))),
  composition = list(slope_variance = 4,
    blocks = list(dbh = list(intercept_variance = 2,
      terms = list(shape = list(loading_variance = 4)))))
)