Finalize formula designs built outside JAGS_fit()

Completes the formula_design and formula_scale returned by JAGS_formula() in the way JAGS_fit() does before it stores them in a fit. The functions let a caller rebuild the formula design of a fitted model outside JAGS_fit(), for example to replace the design stored with a fit.

JAGS_formula_point_finalize(
  design,
  prior_list,
  formula_data,
  model_data = NULL,
  parameter_names = character()
)

JAGS_formula_scale_finalize(
  formula_scale,
  design = NULL,
  prior_list = list(),
  model_data = NULL,
  owner_scope = "fit"
)

Arguments

design

the formula_design element returned by JAGS_formula(). For JAGS_formula_scale_finalize(), NULL or the finalized design of the parameter, which supplies the parameter name and the random-effect standard deviations whose scalar states are resolved.

prior_list

a named list of the priors of the model: the prior_list returned by JAGS_formula() combined with the other priors of the model, as JAGS_fit() combines them. Expression-point coefficients can read the priors in this list.

formula_data

NULL, a data frame, or a named list: the data the formula was evaluated on (the element of formula_data_list of JAGS_fit() for the parameter).

model_data

NULL or a named list: the JAGS data of the model (JAGS_fit() argument data), which expressions and scalar states can read.

parameter_names

a character vector of the names of the model coordinates (for example JAGS_parameter_names() of a fit) that expressions can read.

formula_scale

the formula_scale element returned by JAGS_formula() (NULL is returned unchanged).

owner_scope

the owner of the completed scale: "fit" for the scale of a fitted model, as JAGS_fit() stores it, or "prior_only" for a design used for prior densities without a fit.

Value

JAGS_formula_point_finalize() returns design, with the point_expression_owner element when it has expression-point coefficients.

JAGS_formula_scale_finalize() returns formula_scale with the completed unscale_design attribute (the resolved state_constants, owner_scope, and complete = TRUE), or NULL for a NULL scale.

Details

JAGS_formula() returns a fresh design and scale. JAGS_fit() completes them for each formula parameter in this order: first JAGS_formula_point_finalize() and the finalization of the expression() terms of the design, then the JAGS data generated by all the formulas are merged into the model data, and, in a second loop over the formula parameters, JAGS_formula_scale_finalize() completes the scale with that merged model data. The completed scale is stored both as the formula_scale of the parameter and as the formula_scale element of its finalized design.

The finalization of the expression() terms and the merge of the formula-generated data are not exported. A design rebuilt with these two functions alone does not carry the finalization of its expression() terms, and the scale is completed with the model_data that is supplied, without the data generated by the formulas.

JAGS_formula_point_finalize() retains, for each fixed coefficient with an expression() point prior and for each expression() point prior named by a multiply_by attribute of the design, the expression, the parent priors it reads, and the data it reads, in the point_expression_owner element of the design. A design without such a coefficient or multiplier is returned unchanged. Malformed or contradictory declarations stop with an error of class BayesTools_formula_point_unavailable (also BayesTools_formula_transform_unavailable) whose field reason names the cause.

JAGS_formula_scale_finalize() resolves the scalar states that the multipliers and standard deviations of the design need from the point coefficients of the scale, the point priors in prior_list, the scalars in model_data, and the constants the scale already holds, and marks the scale as complete for owner_scope. Contradictory sources of one state stop with an error of class BayesTools_formula_transform_unavailable (field reason "contradictory_state_constants"), and a scale without its declarations stops with an error of class BayesTools_refit_required.

See also

JAGS_formula() JAGS_fit() JAGS_formula_design()

Examples

data <- data.frame(x = c(-1, 0, 1, 2, 4))
prior_list <- list(
  intercept = prior("normal", list(0, 1)),
  x         = prior("normal", list(0, 1))
)
formula <- JAGS_formula(~ x, "mu", data, prior_list, formula_scale = TRUE)

design <- JAGS_formula_point_finalize(
  formula$formula_design, formula$prior_list, data
)
scale <- JAGS_formula_scale_finalize(
  formula$formula_scale, design, formula$prior_list
)
attr(scale, "unscale_design")$complete
#> [1] TRUE