Skip to contents

Fits a Bayesian model in which a scalar magnitude describes overall density and a composition allocates that magnitude among categories. For fixed-area stems, plot counts follow a negative-binomial total with multinomial allocation. For point sampling, the count model describes in-tree tallies and the magnitude is basal area per unit area.

Usage

magComp(data, family = fixedAreaStems(), magnitude = ~1,
        composition = ~1, smooth = magCompSmooth(),
        priors = magCompPriors(), starting = list(),
        control = magCompControl(), tuning = list(), ...)

Arguments

data

A magCompData object, or a data frame with its preparation arguments supplied through ....

family

A response family: fixedAreaStems (the default) or pointBasalArea.

magnitude

One-sided formula for the scalar magnitude component. Use NULL to fit composition only. See magCompTerms for group and spatial terms.

composition

A one-sided formula for a single-category response, or a magCompComposition specification with one formula per allocation block. Use NULL to fit magnitude only.

smooth

Composition smoothing from magCompSmooth.

priors

Prior settings from magCompPriors.

starting

Partial or complete starting-value list. Omitted values receive automatic starts. Use the starting template from magCompSettings; see magCompStarting for its structure.

control

MCMC settings from magCompControl. Sampling is the default. To inspect settings without sampling, use run_sampler = FALSE.

tuning

Optional covariance proposal standard deviations, organized like starting with a covariance list in each spatial term. Values are on the bounded-logit scale; default 0.1. See magCompCovModels.

...

Arguments passed to magCompData when data is a data frame.

Details

Explicit NULL disables a component; omitting either formula still uses its intercept-only default ~1. At least one component is required. With composition = NULL, fit total counts without category labels or sum the supplied category counts. With magnitude = NULL, fit category allocation conditional on observed totals. Composition may still have one categorical response or the existing parent/child structure, with different covariates, factors, and smoothing in each block. Composition-only fitting requires integer category counts, not proportions, and does not require areas.

Only active components are initialized, sampled, and reported in parameter settings, starts, samples, and diagnostics. Nondefault priors or starting values for disabled components are rejected. Smoothing is unused and must remain at its default when composition is disabled. fitted, predict, magCompCV, and ppcSummary support each configuration; standSummary aggregates their density or magnitude samples using explicit represented land areas.

Both components support regression effects. Magnitude formulas can add iid, GP, or NNGP effects; composition formulas can add corresponding factor terms. Colon interactions allow covariates to multiply latent effects. See magCompTerms for syntax and identification constraints.

The composition_link control selects probit (the default) or logit. The selected link applies to all allocation blocks, fitted values, and predictions. Ordered composition coefficients can use RW1 or RW2 smoothing.

Each magnitude process term has an estimated variance. Composition factors have unit variance, with positive estimated anchor-diagonal loadings and zeros above the anchor diagonal. Covariance parameters are estimated unless their starting entry uses fixed(value); see magCompCovModels for family-specific defaults. Negative-binomial size is estimated by default under a Gamma(shape = 1, rate = 0.01) prior when the magnitude formula has no latent process terms. With magnitude iid or spatial terms, size is fixed at control$nb_size (default 1000). See magCompPriors to change the prior or explicitly fix size in a regression-only magnitude model.

Use magCompSettings to inspect the resolved model, priors, and starts. The technical guide linked from magComp-package gives the model and sampler details; magCompNotation connects its symbols to software parameter names.

Value

An object of class magComp. Use samples for posterior parameter arrays, summary for parameter summaries, and fitted or predict for response quantities.

Examples

rows <- expand.grid(plot = paste0("p", 1:8),
                    dbh_class = c("small", "large"))
rows$count <- c(8, 5, 9, 6, 3, 7, 4, 5, 2, 4, 1, 3, 6, 2, 5, 4)
rows$area <- 0.05
rows$height <- rep(seq(-1, 1, length.out = 8), 2)
dat <- magCompData(rows, unit = plot, category = dbh_class,
                   tree_count = count, design = fixedArea(area))

# A short run to illustrate the interface, not assess convergence.
set.seed(1)
fit <- magComp(dat, magnitude = ~ height, composition = ~ height,
  control = magCompControl(n_samples = 60, n_burn = 20, verbose = FALSE))
summary(fit)
fitted(fit, type = "density")$density
predict(fit, data.frame(height = c(-0.5, 0.5)), area = 0.05)$count