R/JAGS-formula-scale-transform.R
transform_scale_samples.RdTransforms posterior samples from standardized continuous
predictors back to the original scale. This function is used when predictors
were standardized during model fitting via the formula_scale parameter.
transform_scale_samples(fit, formula_scale = NULL)a model fitted with JAGS_fit(). Matrices of posterior samples
and other fit objects are not supported.
optional nested list containing standardization
information keyed by parameter name, replacing the formula_scale
attribute of fit. Each parameter entry contains scaling info (mean and
sd) for each standardized predictor, e.g.,
list(mu = list(mu_x1 = list(mean = 0, sd = 1))). An entry must name
every predictor that fit standardized for that parameter. The
transformation is derived from the fitted structure stored in fit: the
fixed-effect design, a log intercept, and the random-effect SD structure.
A numeric matrix of posterior samples transformed back to the original predictor scale, with chains merged in their existing order. When no scaling information is supplied, the function returns the sample matrix without changing its values, rather than returning the fitted object.
The function transforms regression coefficients and intercepts to account for predictor standardization, including interactions of any order.
Columns that are not coefficients of the fitted design or random-effect SDs and correlations of a scaled block, such as the totals and allocation nodes of ordered priors, keep their fitted-scale values.
Internal standardized random-effect coordinates (latent xRE_Zx
columns and realized xRE_COEFx columns) are omitted from the returned
matrix. They do not have the same transformation as fixed coefficients or
random-effect covariance summaries and must not be presented as
original-scale coefficients. This omission also applies when no scaling
information is supplied.
For a k-way interaction between standardized predictors, the expansion of
\(\prod_{i} (x_i - \mu_i)/\sigma_i\) contributes to all lower-order terms.
The contribution to a target term T from a source term S (where T is a subset
of S's scaled components) is:
$$(-1)^{|extra|} \cdot \prod_{i \in extra} \mu_i / \prod_{i \in S_{scaled}} \sigma_i$$
where \(extra = S_{scaled} \setminus T_{scaled}\). Terms with a
multiply_by multiplier (see JAGS_formula()) additionally carry the
ratio of the source to the target multiplier, \(m_S / m_T\).
The posterior must contain every lower-order coefficient with a nonzero
contribution from this expansion. If it does not, the function stops rather
than returning an incomplete transformation.
For a fitted object, or formula-scale metadata created by JAGS_formula() or
JAGS_fit(), the fixed-coefficient transformation is derived from the
stored fixed-effect design (persisted factor levels and contrasts) and
verified to reproduce the fitted linear predictor exactly, which also covers
nested terms such as ~ f/x. Formulas whose centered terms induce
lower-order effects that the fitted formula does not contain (e.g.,
~ x + x:f with x standardized) have no original-scale
representation, and the function stops.
The original-scale random-effect SDs and correlations of a block with a
standardized slope are transformed the same way, from the fitted design of
the block: when the standardized block columns equal the original-scale
columns times a matrix \(A\), the block coefficients transform as
\(A u\) and their covariance as \(A \Sigma A'\). A block whose
original-scale design is not spanned by its own columns (a term that would
have to be induced, such as the implied intercept of (0 + x | g)) has
no such matrix. It keeps the pairing of coefficient names only when each
retained contribution has identical fitted categorical coding and every
omitted contribution is unrepresentable by the block's lower-order columns.
Otherwise original-scale output is unavailable, with reason
"original_scale_not_representable"; use fitted-scale output or include
the needed lower-order terms in the block. A block that the fitted design does not hold (hand-built
random-effect SD metadata) is transformed by the same pairing of names.
Invalid arguments, including a formula_scale entry for a formula
parameter the model does not have (also for a model without formula
parameters) or a standardized predictor that
is missing from the posterior, stop with an ordinary error. A condition of
class BayesTools_formula_transform_unavailable (parents
error and condition; the reason field names the
cause, for example "incomplete_formula_scale" (a
formula_scale entry that omits a predictor standardized in the
fitted model; the fields parameter and predictors name them),
"missing_fitted_design",
"original_scale_not_representable",
"original_scale_not_identified",
"homogeneous_scaled_block" (hand-built metadata of a homogeneous-SD
block with a scaled slope, which JAGS_formula() refuses), or
"nonfinite_transform")
reports a transformation that is structurally or numerically unavailable.
A condition of class BayesTools_refit_required reports a fit whose
stored formula declarations are missing or disagree.