R/JAGS-formula-predict.R
JAGS_evaluate_formula.RdEvaluates a JAGS formula on a posterior distribution obtained
from a fitted model, through the formula design that JAGS_fit() stores
for the formula parameter (the processed formula, factor levels and
contrasts, and the standardization of predictors). Posterior or prior
draws without a fit are evaluated through the same design, built by
JAGS_formula_draws(). Fits created by BayesTools 0.3.0, which store no
design, must be refitted: they stop with an error of class
BayesTools_refit_required (see JAGS_validate_fit_contract()).
Formula random effects can be evaluated for existing
grouping levels when either standardized latent random effects and covariance
hyperparameters were monitored via random_monitor(latent = TRUE), or
the group-level coefficients were monitored via
random_monitor(coefficients = TRUE); otherwise, and for
random-effect blocks compiled as marginalized, conditional evaluation stops
with an error of class BayesTools_refit_monitoring (also
BayesTools_refit_required).
In a random-effect block of a scalar-correlation structure (CS, HCS, AR1,
HAR, or CAR) compiled group by group, the coefficients of index levels that
a group does not have in the fitted data are drawn from their exact Gaussian
conditional law given the observed levels. This draw is stochastic and
follows set.seed().
Row-indexed external random-effect SD sources, such as
random_sd_source("tau", shape = "row"), are evaluated from latent
random effects only. Model generation automatically monitors the required
latent effects for these blocks. The posterior samples must either contain
source columns named tau[1], ..., tau[N]. When prediction
data are supplied, fitted_rows must explicitly map each
prediction row to its fitted observation index. Alternatively, the source
must provide a
parameter_source() values function for reconstructing row-wise
source values from the posterior samples and supplied prediction data.
An unavailable new-row evaluation of a posterior-indexed row source raises
BayesTools_prediction_new_rows_unavailable (parent
BayesTools_prediction_unavailable), with reason = "posterior_indexed_row_source",
block, the displayed source label, affected prediction rows, and caller
context. It applies where the source of the new rows is needed, under
new_levels = "sample"; with new_levels = "zero" the new rows contribute
zero and need no source. Missing or malformed mappings, invalid source values,
and missing monitored columns retain their own errors.
Literal expression() terms use the replayable subset documented by
JAGS_formula() and are evaluated against prediction data using JAGS-style
row indexing through i.
Array expressions such as X[i, column[i]] pair the coordinates
pointwise. Each index must contain finite positive integers within its
array dimension; scalar indices repeat across a common nonzero vector
length. One-index expressions retain ordinary vector indexing.
Sampled parameter references are reconstructed separately for every posterior
draw. Replaying a fitted formula restores the
stored expression syntax, dependency classification, and fitted data
snapshot. Supply an explicit
expression-free formula to evaluate a selected subset without those offsets.
Inline transformations, offsets, dot expansion, and arbitrary calls are not
supported. Create transformed predictors as explicit columns in data.
Selected existing terms retain fitted factor coding and variable order,
including interactions requested with reversed variable order. Predictors
outside the selected terms are not required. Expression-valued scalar point
coefficients use valid monitors first, otherwise their retained declaration
and owned model data. New prediction rows do not replace that owned data.
Unsupported scalar replay, missing parents, cycles, and malformed values
raise BayesTools_formula_point_unavailable; absent affected owners
require refitting. This replay does not extend bridge prior-expression
eligibility or establish a structural point law from constant draws.
JAGS_evaluate_formula(
fit,
formula = NULL,
parameter,
data = NULL,
prior_list = NULL,
formula_target = NULL,
blocks = NULL,
new_levels = NULL,
fitted_rows = NULL
)model fitted with JAGS_fit() with a formula for
parameter, or posterior draws carrying its formula design
(JAGS_formula_draws()).
formula specifying the right hand side of the assignment (the
left hand side is ignored). If NULL, the fitted formula stored in
formula_design metadata is used. Whether the intercept values are
log-transformed before computing the linear predictor is a property of the
fitted formula: the "log(intercept)" flag stored in formula_design
applies to every formula, also to an explicit one without the
"log(intercept)" attribute. An explicit "log(intercept)"
attribute that disagrees with the stored flag (TRUE for a fitted
formula without a log intercept, or FALSE for one with it) stops
with a BayesTools_formula_transform_unavailable error (reason
"log_intercept_mismatch", fields explicit and stored)
naming both values: omit the attribute or set it to the stored value.
name of the parameter created with the formula
data.frame containing predictors included in the formula. If
NULL, versioned original-scale fitted source data from formula_design
metadata are used.
named list of prior distribution of parameters specified
within the formula. If NULL, fitted priors from formula_design
metadata are used.
formula prediction target. "fixed" evaluates only
the fixed formula contribution. "conditional" evaluates fixed effects plus
fitted or explicitly generated random-effect contributions. NULL (the
default) evaluates the fixed formula of fits without random effects and
stops for fits with random effects, which need an explicit target.
optional random-effect block names used with
formula_target = "conditional". When formula has random-effect terms,
the default is the blocks of those terms and supplied blocks must be among
them.
optional new-level policy used only with
formula_target = "conditional". Use a random_new_levels() object or one
of "error", "zero", or "sample". Grouping levels declared in the
fitted grouping factor but without rows in the fitting data are predicted as
new levels, except in blocks with a known group covariance; see
prior_random().
optional integer vector mapping supplied prediction rows
to fitted observation indices. It is required whenever data is supplied
and a selected random-effect block uses a posterior-indexed row source.
Reordering and duplicate indices are supported. Callback-computed row
sources do not use this mapping. The entries of rows of new random-effect
levels predicted with new_levels = "zero" are ignored, because those rows
contribute zero; they must still be valid fitted observation indices.
JAGS_evaluate_formula returns a matrix of the evaluated posterior samples on
the supplied data.