Skip to contents

Formula-only markers for magnitude iid, GP, and NNGP effects and composition iid, GP, and NNGP factor terms. These functions are parsed inside model formulas.

Usage

iid(...)
gp(...)
nngp(...)
factor_iid(...)
factor_gp(...)
factor_nngp(...)

Arguments

...

Grouping or coordinate column names and term settings described below.

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.

Examples

# These are formula objects, to be supplied to magComp().
~ height + iid(stand, name = "stand") + nngp(x, y, m = 15)
~ height + factor_nngp(x, y, K = 2, name = "spatial")