
Extract posterior draws and combined coefficients
samples.RdExtracts 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
magCompmodel, or the result ofpredict(..., 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.
NULLselects 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 predictionnewdatafor averaging within groups, or".all"for averaging over all units.NULLreturns 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")