| predict.mmes | R Documentation |
predict method for class "mmes".
## S3 method for class 'mmes'
predict(object, Dtable=NULL, D, levels=NULL, sed=FALSE,
pairwise=FALSE, adjust="none", df=Inf, PEV=TRUE, VarU=TRUE,
observed=FALSE, maxMemoryMB=NULL, target=NULL, ...)
object |
a mixed model of class |
Dtable |
a table specifying the terms to be included or averaged. An "include" term uses the cells matching each prediction row. For categorical random effects these are mapped within the fitted term, including fitted cells without records. Numeric fixed terms retain their evaluated covariate values rather than being replaced by indicators. An "include and average" term means that the included cells of that effect are averaged: each prediction row is divided by the number of cells of the term present with it (for fixed terms this count includes the reference cells absorbed in the intercept). An "average" term alone averages over the selected factor levels. For categorical terms the weights are 1/#levels; numeric fixed terms are evaluated at their covariate settings before averaging. If a term is not considered "include" or "average" is then totally ignored in the BLUP and SE calculation. The default rule to invoke when the user doesn't provide the Dtable is to include and average all terms that match the argument D. Dtable contains only term-level rules, not level selections or numeric
settings. Supply these through the With |
D |
a character string specifying the variable used to extract levels for the rows of the D matrix and its construction. Alternatively, the D matrix (of class dgCMatrix) specifying the matrix to be used for the predictions directly. |
levels |
an optional named list whose names are values of |
sed |
if |
pairwise |
|
adjust |
multiplicity adjustment passed to |
df |
degrees of freedom for pairwise tests: |
PEV |
Logical, default |
VarU |
Logical, default |
observed |
Logical, default |
target |
Optional prediction target for native Laplace fits:
|
maxMemoryMB |
Positive finite workspace budget in decimal MB for
rank-reduced and direct-engine predictions. Defaults to the fitted
|
... |
Further arguments to be passed. |
Direct Gaussian and direct PQL fits support the same classify, explicit
contrast, Dtable, level-selection, SED and pairwise workflows as
Henderson fits. They retain sparse prepared designs and final covariance
inputs when output$coefficientMatrix=TRUE (default), and compute
contrast error covariance in observation space without forming Henderson
equations or requiring postPEV() first. Gaussian uncertainty is
conditional on fitted covariance parameters; PQL uncertainty is additionally
a working-model approximation on the link scale. For PQL set
VarU=FALSE. Coefficient predictions are L_b\hat\beta+L_u\hat u;
formula offsets are not added automatically. These are not future-response
prediction intervals. Older direct fits lacking retained covariance inputs
must be refitted.
This function allows to produce predictions specifying those variables that define the margins of the hypertable to be predicted (argument D). Predictions are obtained for each combination of values of the specified variables that is present in the data set used to fit the model. See vignettes for more details.
For a rank-reduced fit, predict(fit, D="locale:cultivar",
observed=TRUE) constructs sparse averages directly from retained observed
combinations, without generating the locale-by-cultivar Cartesian product.
Returned rows are ordered by first appearance unless levels specifies
their order. Missing-response rows excluded from the fit cannot create
prediction rows. An observed marginal prediction, such as
D="locale", averages the fitted fixed predictor using the observed
records in each locale; it is not an equally weighted or cultivar-adjusted
comparison. Estimability is checked before covariance computation.
Manual random contributions are added in the same public coefficient
coordinates as explicit contrasts, so their prediction-error, sampling
covariance and pairwise calculations follow the fitted engine's usual path.
When include=TRUE alone has random-level restrictions, omitted
coefficient contributions are zeroed without renormalizing the empirical
group weights. Use include=TRUE, average=TRUE for equally weighted
selected co-occurring indicator levels.
For categorical structured random terms, the fitted covariance-coordinate
and main-effect levels define the genetic prediction weights, even when a
cell has no observations. The levels argument can additionally request
fitted levels present only in Gu. Unsupported random designs that
cannot be mapped for all prediction rows produce a warning; an explicit
D matrix can be used for these designs.
Numeric fixed terms, including factor-by-covariate interactions, are
evaluated using the fitted fixed formula and contrasts. Unless overridden,
each numeric variable is set to its mean in the retained fitting data.
Factor levels are equally weighted when averaged. Thus an averaged
Env:cov term with one slope per environment uses
mean(cov)/nlevels(Env) for each slope, not 1/nlevels(Env).
Write D=[L_b,L_u]. The target is t=L_b\beta+L_u u and its
predictor is \hat t=L_b\hat\beta+L_u\hat u. The existing
prediction PEV and VarU matrices are for the linear
combinations represented by the final returned D, after applying
Dtable and levels, not copies of model-level effect variances.
Each covariance matrix has one row and column per requested prediction.
The existing
vcov, optional PEV, and squared std.error refer to
\operatorname{Var}(t-\hat t), not generally to
\operatorname{Var}(\hat t). They are computed from
\operatorname{Var}(t-\hat t)=D C_0^{-1}D',
where C_0 is the original-scale Henderson coefficient matrix defined
in postVarU. For Henderson fits, the stored system C is solved against
contrast transposes and the result multiplied by Cscale. Arbitrary
contrasts work regardless of computeCi; no stored Ci is used.
Direct fits obtain the equivalent joint error covariance blocks in
observation space, as described in postPEV; they also support
singular random-effect covariance, for which G^{-1} need not exist.
With Q=(C_0^{-1})_{uu} and B=(C_0^{-1})_{bb}, the new outputs are
\mathrm{VarU}=L_u(G-Q)L_u',
\mathrm{sampling.vcov}=L_b B L_b'+L_u(G-Q)L_u'.
The BLUE and BLUP have zero sampling cross-covariance, whereas the
fixed/random blocks of the inverse Henderson matrix describe error
covariance and generally are not zero. In particular, subtracting the full
target PEV from L_uGL_u' is incorrect if fixed effects are included.
A fixed-only prediction has zero VarU, but generally nonzero
sampling.vcov and PEV. Random-only predictions satisfy
L_uGL_u'=\mathrm{PEV}+\mathrm{VarU}.
The implementation evaluates full, random-only and fixed-only contrasts using
one operation-local factorization in the selected formulation. Prior products use the term structure
G_k=\Sigma_k\otimes A_k and sparse relationship-precision solves.
Henderson does not construct the observation covariance V or its inverse;
direct fits factor V and use termwise relationship products.
Additional matrices require quadratic storage in the number of predictions.
Rotation and factor-score mappings operate in public effect coordinates.
New fits retain relationship precisions; older ordinary fits attempt model
input reconstruction as described in postVarU.
All covariance outputs use the fitted variance components as fixed,
omitting their estimation uncertainty. They are exact for known components
and plug-in approximations for estimated components, for both ML and REML.
SEDs, pairwise tests and std.error retain their PEV-based meaning;
enabling VarU does not change those calculations. Direct and matrix-free
solveOnly fits lack the stored coefficient system required here.
Categorical familym predictions return a trait-named list
of scalar vectors and labelled categorical probability matrices; link
predictions return ordinal/scalar vectors and nominal logit matrices.
Row order is preserved within each trait, and traits absent from new data
have empty outputs. Conditional prediction retains explicit shared or
.familyCoordinate-specific random effects.
se.fit=TRUE returns matching fit and se.fit lists.
cov.fit=TRUE adds their joint flattened covariance, labelled by
trait, category and within-trait row. Conditional uncertainty includes
estimated ordinal cutpoints while holding covariance/shape coordinates
fixed; uncertainty="full" includes all estimated parameters and
mode dependence. All uncertainty is post-fit and memory-budgeted.
Population prediction integrates the fitted structured latent covariance,
including supplied relationship precision and arbitrary design loadings.
Population standard errors propagate all estimated outer parameters and
report uncertainty="full". Classify aggregation remains unsupported.
Native Laplace fits accept newdata, type, re.form,
se.fit, and cov.fit through .... Random-effect and
observation-space Laplace backends retain the same prediction and
uncertainty targets. Observation fits reconstruct operation-local mode
and fixed-effect Schur solves rather than a random-effect Hessian.
For conditional
predictions at known random-effect levels or zero-random-effect predictions,
se.fit=TRUE returns a list with fit, se.fit, and
cov.fit=NULL. The standard errors use the joint fixed/random
conditional observed-information inverse, with fitted covariance and family
parameters held fixed. Response-scale standard errors use the delta method.
Setting cov.fit=TRUE additionally returns the complete link-scale
or response-scale prediction covariance and requires se.fit=TRUE.
Solve panels are controlled by output$panelSize, and full covariance
workspace is checked against execution$denseMemoryMB. Population-mean
uncertainty is propagated through fixed-effect and covariance-parameter
and family-parameter curvature for supported structured random effects.
This is uncertainty in an integrated mean, not a future-response interval.
Aggregation is not implemented.
With a nontrivial zipoisson(zero=~covariates) formula, prediction
uncertainty instead propagates the joint outer-parameter covariance,
including zero coefficients and cross-covariances. Conditional predictions
also propagate conditional-mode dependence and local latent covariance.
All these calculations occur after fitting; they are local approximations,
not future-response prediction intervals. Zero-formula factor coding,
transformations and offsets are evaluated from the training basis.
Single-family ordinal Laplace fits default to
type="response" (or "probabilities"): a labelled
observation-by-category probability matrix. type="link" returns
the latent predictor and type="mean" the expected numeric category
code. The fitted factor basis, column selection and offsets are reused for
new data. Conditional predictions require known random levels;
re.form=NA sets random effects to zero.
re.form="population" integrates category probabilities with exact
normal convolution for probit and 24-node Gaussian quadrature for logit,
under the same structured latent covariance as other Laplace
population predictions.
Ordinal uncertainty propagates the full outer-parameter covariance,
including cutpoint cross-covariances and conditional-mode dependence;
conditional predictions additionally include local random-mode variance.
Probability se.fit has the same labelled matrix shape as fit.
Probability cov.fit uses column-major order (all prediction rows for
category one, then category two, etc.), with labels category:row.
These are post-fit local approximations, not calibrated response intervals.
Single-family multinomial fits return labelled category
probabilities by default; type="link" returns the K-1
reference-category logits. Conditional prediction requires known random
levels, while re.form=NA sets random effects to zero.
re.form="population" averages category probabilities over the fitted
Gaussian latent distribution, rather than setting random effects
to zero or averaging logits. It supports up to four response categories,
structured temporal/spatial effects, random slopes and supplied relationship
precision, and sums covariance contributions from independent terms.
Each observation uses its actual joint logit covariance.
New independent group levels are allowed provided the fixed-effect design
is supported and the relationship precision is identity. New time/site
coordinates or unknown relationship levels are rejected: the coordinate
basis must be represented when fitting. Conditional prediction can borrow
information for represented latent coordinates without an observed response;
it does not extrapolate to an undefined covariance basis.
Integration uses deterministic tensor normal quadrature on the nonzero
logit-covariance eigenspace: 24- and 32-point rules must agree to within
10^{-6} absolute probability in every cell. The returned 32-point
result is a numerical approximation; rule agreement is not a guaranteed
error bound. Estimated workspace is guarded by
execution$denseMemoryMB. Population type="link" is rejected.
Population se.fit and cov.fit propagate all estimated
outer parameters after fitting and report uncertainty="full";
covariance uses category-major order and labels category:row.
Classify-table aggregation remains unsupported.
se.fit=TRUE returns probability standard
errors by the delta method; conditional uncertainty uses the joint fixed/random conditional
curvature with fitted covariance parameters held fixed. These calculations
happen after fitting; they are not calibrated prediction intervals.
Nominal models additionally accept uncertainty="conditional"
(the unchanged default) or uncertainty="full" through ....
The latter requires se.fit=TRUE and uses the full marginal Laplace
parameter covariance, including free random-covariance coordinates.
Conditional prediction differentiates the fitted random modes as parameters
change and adds random-mode posterior covariance; re.form=NA instead
uses the marginal fixed-coefficient covariance with zero random effects.
Response-scale covariance uses the softmax delta method.
This is a first-order post-fit approximation, not a bootstrap, simultaneous
confidence region, or future-response prediction interval. It requires
valid parameter curvature and respects the dense-memory budget; all
calculations are opt-in and neither change fitting nor its stored object.
pvals |
the table of predictions according to the specified arguments. |
vcov |
The full target prediction-error covariance, always returned. |
PEV |
When requested, identical to |
VarU |
When requested, sampling covariance of the predicted random
contribution only; its diagonal is |
sampling.vcov |
When |
D |
the model matrix for predictions as defined in Welham et al.(2004). |
Dtable |
the compact table specifying the terms to include and terms to be averaged. |
levels |
the named list of level selections and resolved numeric settings
used to construct D. Numeric defaults on the regular prediction path are
retained-data means. With |
observed |
For |
sed, avsed |
when |
pairwise |
when requested: a data frame with |
Giovanny Covarrubias-Pazaran
Welham, S., Cullis, B., Gogel, B., Gilmour, A., and Thompson, R. (2004). Prediction in linear mixed models. Australian and New Zealand Journal of Statistics, 46, 325 - 347.
predict, mmes
data(DT_yatesoats, package="enhancer")
DT <- DT_yatesoats
m3 <- mmes(fixed=Y ~ V + N + V:N ,
random = ~ B + B:MP,
rcov=~units,
data = DT)
m3 <- postPEV(m3, mode = 2)
#############################
## predict means for nitrogen
#############################
Dt <- m3$Dtable; Dt
# first fixed effect just average
Dt[1,"average"] = TRUE
# second fixed effect include
Dt[2,"include"] = TRUE
# third fixed effect include and average
Dt[3,"include"] = TRUE
Dt[3,"average"] = TRUE
Dt
pp=predict(object=m3, Dtable=Dt, D="N")
pp$pvals
#############################
## predict means for variety
#############################
Dt <- m3$Dtable; Dt
# first fixed effect include
Dt[1,"include"] = TRUE
# second fixed effect just average
Dt[2,"average"] = TRUE
# third fixed effect include and average
Dt[3,"include"] = TRUE
Dt[3,"average"] = TRUE
Dt
pp=predict(object=m3, Dtable=Dt, D="V")
pp$pvals
#############################
## predict means for nitrogen:variety
#############################
# prediction matrix D based on (equivalent to classify in asreml)
Dt <- m3$Dtable; Dt
# first fixed effect include and average
Dt[1,"include"] = TRUE
Dt[1,"average"] = TRUE
# second fixed effect include and average
Dt[2,"include"] = TRUE
Dt[2,"average"] = TRUE
# third fixed effect include and average
Dt[3,"include"] = TRUE
Dt[3,"average"] = TRUE
Dt
pp=predict(object=m3, Dtable=Dt, D="N:V")
pp$pvals
#############################
## select levels through the argument, keeping Dtable compact
#############################
Dt <- m3$Dtable
Dt$average[Dt$term %in% c("1", "V", "V:N")] <- TRUE
Dt$include[Dt$term %in% c("N", "V:N")] <- TRUE
p <- predict(m3, D="N", Dtable=Dt,
levels=list(N=c("0.6", "0.2")))
p$pvals
p$levels[["N"]]
p2 <- predict(m3, D="N", Dtable=p$Dtable, levels=p$levels)
all.equal(p$D, p2$D)
## Covariances of the requested linear combinations
p <- predict(m3, D="N", Dtable=Dt, PEV=TRUE, VarU=TRUE)
p$PEV
p$VarU
p$sampling.vcov
randomColumns <- seq.int(nrow(m3$b)+1L, nrow(m3$bu))
randomD <- p$D[,randomColumns,drop=FALSE]
full <- postVarU(m3, mode=2)
all.equal(unname(p$VarU),
unname(as.matrix(randomD %*% full$VarU %*% t(randomD))))
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.