Skip to contents

Extracts retained posterior draws without running the sampler or generating predictions. The result has summary() and plot() methods. Draw selection is synchronized across every parameter and latent effect.

Usage

samples(object, ...)

# S3 method for class 'magComp'
samples(object, type = c("parameters", "effects", "combined"),
                              start = 1, thin = 1, chains = NULL,
                              combine_chains = FALSE, group = NULL, ...)

# S3 method for class 'magCompPrediction'
samples(object,
                  type = c("parameters", "effects", "combined"),
                  start = 1, thin = 1, chains = NULL,
                  combine_chains = FALSE, group = NULL, ...)

Arguments

object

A fitted magComp model, or the result of predict(..., summary = "samples", keep_effects = TRUE).

type

"parameters" returns all raw parameter arrays in the component/block/term structure below. Its default summary reports scalar parameters. "effects" selects individual magnitude effects and composition factor scores, including them in summaries and traceplots. "combined" constructs fixed coefficients plus their matching random coefficients at fitted or predicted units. Only coefficients with random-effect terms are returned.

start

First saved draw to retain within each chain, counted after the burn-in and thinning already applied by the fit. Defaults to 1.

thin

Additional thinning interval among saved draws. Defaults to 1.

chains

Chain numbers or names to select, in the requested order. NULL selects all chains.

combine_chains

Pool selected chains after constructing quantities. Original draw and chain identities are retained for summaries and diagnostics.

group

For type = "combined", a column name in the fitted unit data or prediction newdata for averaging within groups, or ".all" for averaging over all units. NULL returns each unit. Averages give each unit equal weight and are calculated within each draw.

...

Additional arguments, currently unused.

Details

For prediction objects, the stored latent draws are those used to construct the response predictions, before any negative-binomial or multinomial draws. Extraction does not generate new effects. The parameter arrays contain the matching subset selected by predict(n_draws = ...); draw identities and original MCMC iterations are preserved. start and thin select positions within that subset. Magnitude effects are indexed by new unit; spatial scores are indexed by new location, and iid composition scores by allocation-block row (including parent context for conditional blocks). Response draws themselves remain available in the prediction object's magnitude, proportion, density, or count components.

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().

For type = "parameters", the returned structure is:


list(
  magnitude = list(
    coefficients = coefficient_draws,
    size = size_draws,                  # only when estimated
    terms = list(term_name = list(
      effects = effect_draws, variance = variance_draws,
      covariance = list(phi = phi_draws) # estimated parameters only
    ))
  ),
  composition = list(blocks = list(block_name = list(
    coefficients = coefficient_draws,
    terms = list(term_name = list(
      loadings = loading_draws, scores = score_draws,
      covariance = list(phi = phi_draws) # estimated parameters only
    ))
  )))
)

Magnitude coefficients and effects are parameter-by-sample matrices. Scalar variance and size arrays have one parameter row; each covariance parameter has an array with one row per factor for which it is estimated. Composition coefficient arrays are stick-by-design-column-by-sample. Loading arrays are stick-by-factor-by-sample; score arrays are group-or-location-by-factor-by-sample. Multiple chains add a final chain dimension to every array. Parameter dimensions and singleton dimensions are retained, and dimnames identify coefficients, sticks, groups, locations, factors, and chains. Sample positions align across the result.

Fixed size and covariance values are omitted from samples. Fixed covariance values are retained by magCompStarting() for restarting the same model. Use magCompSettings to inspect these fixed values. Loading arrays retain the fixed upper-anchor zeros and estimated positive diagonals. Factor variances and smoothing variances are fixed controls and have no posterior sample arrays.

For example, draws$magnitude$terms$stand$variance contains the posterior draws of the variance whose prior is specified by priors$magnitude$terms$stand$variance and whose initial value is starting$magnitude$terms$stand$variance. The prior entry holds inverse-gamma shape and scale; the starting entry holds a single variance.

Use fitted and predict for draws of response quantities. Use magCompStarting with use = "last" or use = "mean" to turn parameter samples into a starting-value list.

Value

An object of class magCompSamples. Raw parameters and effects are nested lists of arrays. Combined coefficients are a named list of saved-draw-by-chain matrices, or vectors when chains are pooled. Their info attribute identifies component, block, coefficient, allocation row, parent context, and fitted or predicted unit or group.

The sample_info attribute records type, retained draw positions, original MCMC iteration numbers, chain identities, grouping, and pooling. Pooled draws are concatenated one chain at a time in the selected order; every chain uses the same selected draw positions.

Combined coefficients

For a magnitude random intercept with both group and spatial terms, the combined coefficient is \(\beta_0 + \delta_{g(i)} + v(s_i)\). A varying slope instead combines its fixed slope with the random coefficients attached to that covariate. A missing fixed counterpart contributes zero.

Composition combinations sum the loading-times-score contributions across all factors and matching terms, then add the corresponding fixed coefficient. They support iid, GP, and NNGP terms and retain conditional parent contexts. Loadings and scores are multiplied within matching draws and chains. Covariates are not multiplied into these coefficients. Response means and observation draws belong to fitted() and predict().

Group averages summarize coefficients over the supplied units, not forest density or abundance. Use standSummary() for area-weighted response summaries. Where several latent terms contribute to one coefficient, all matching terms are included. These are combined coefficients, not separately attributed term effects. New groups or locations require predict() with keep_effects = TRUE, followed by samples() on its result.

Examples

rows <- expand.grid(plot = paste0("p", 1:4), cls = c("a", "b"))
rows$count <- rep(1:4, 2)
rows$area <- 1
rows$stand <- rep(c("s1", "s1", "s2", "s2"), 2)
dat <- magCompData(rows, unit = plot, category = cls, tree_count = count,
                   design = fixedArea(area))
fit <- magComp(dat, magnitude = ~ iid(stand, name = "stand"),
  control = magCompControl(n_samples = 6, n_burn = 3,
    verbose = FALSE))
draws <- samples(fit)
draws$magnitude$coefficients
draws$magnitude$terms$stand$variance
summary(fit, type = "effects")
combined <- samples(fit, type = "combined", group = "stand")
summary(combined)
# Equivalent convenience call:
summary(fit, type = "combined", group = "stand")