
Formula terms for magnitude and composition models
magCompTerms.RdFormula-only markers for magnitude iid, GP, and NNGP effects and composition iid, GP, and NNGP factor terms. These functions are parsed inside model formulas.
Details
Use iid(group) for magnitude group effects, gp(x, y) for a dense
Gaussian process, or nngp(x, y, m = 15) for a nearest-neighbor process.
Each magnitude process has its own estimated variance. Composition uses
factor_iid(group, K = 1), factor_gp(x, y, K = 1), or
factor_nngp(x, y, K = 1, m = 15). Its factors have unit variance. Unconstrained loadings have normal priors;
positive anchor-diagonal loadings have half-normal priors.
For each spatial term, different sampling units must have distinct coordinate
vectors. Exact duplicate locations cause an error during model preparation
that identifies the term and affected unit IDs. Nearby but distinct locations
are allowed. Multiple tree records within one unit and the repeated unit rows
in conditional allocation blocks are allowed; those rows share the unit's
spatial effects. This restriction applies to fitting. Repeated prediction
coordinates share a spatial-effect draw as described in
predict.
Spatial calculations use the specified correlation matrices without diagonal additions or conditional-variance clipping. Failed covariance calculations report an error during initialization, sampling, or prediction.
All terms accept name, a unique nonempty name within the component or
allocation block. Otherwise names such as iid_1 and gp_1 follow
formula order within each type. Use these names for overrides in
magCompPriors and starting; inspect the resolved names with
magCompSettings.
Spatial terms accept cov_model: "exp" (default), "matern",
"sep_exp", "multi_res_sep_exp", or "gneiting".
For a space-time family, supply numeric time as the final coordinate, for example
nngp(x, y, year, cov_model = "sep_exp", m = 15). Repeated sites at
different times are then allowed; repeated full space-time coordinates
for different sampling units remain an error. A spatial-only term on revisited
sites is not supported.
NNGP neighbors use Euclidean spatial distance and absolute time separation,
combined as \(\sqrt{h^2+(s u)^2}\), where st_scale = s defaults to one.
This positive multiplier has spatial units per time unit and affects only
neighbor selection. Covariance calculations use the original spatial and
temporal lags. Ordering and neighbors remain fixed during fitting. Prediction
inherits the same setting and conditions jointly on observed and earlier new
locations.
Covariance priors, starts, and tuning use each term's covariance list.
For example, covariance = list(phi = uniform(0.1, 5)) sets a prior,
covariance = list(phi = 1) sets a start, and
covariance = list(phi = fixed(1)) fixes that parameter.
See magCompCovModels for the kernels, parameter names, and defaults.
Factor terms accept anchors (coefficient-stick names or row indices)
and factor_names. Anchor rows define zeros above the anchor diagonal and
positive, estimated diagonal entries. Automatic anchors use variation in observed continuation
ratios. Default factor names are the anchor categories. Factor rank and anchor
constraints are model specifications; diagonal loadings are estimated under
half-normal priors controlled by loading_variance.
The sampler updates unrestricted working loadings, then jointly changes the
sign of each loading column and its factor scores when needed to make the
anchor positive. This preserves the factor contributions and the specified
priors; returned draws satisfy the anchor constraints.
Colon interactions such as height:iid(stand) or
height:factor_nngp(x, y, K = 1) multiply the latent contribution by the
covariate. Include height separately for an average regression slope.
Multiple terms may be used in each component or allocation block.
Named arguments are limited to those described above. Unknown arguments are rejected. Set priors and initial values through their dedicated interfaces.
Value
These functions stop if evaluated outside a model formula. They specify terms
for magComp() to interpret; they do not generate effects themselves.
See also
magCompPriors, magCompStarting,
magCompNotation; the technical guide's Model terms and Factor
identification sections in magComp-package.