Get Factor Scores and the Corresponding Standard Error of Measurement

get_fs() is an S3 generic that extracts factor scores from fitted models. Methods are available for data.frame (fits a CFA internally), lavaan objects, lmerMod objects, and fitted mirt models (single-group SingleGroupClass and multi-group MultipleGroupClass; mirt is a Suggests dependency). Multi-group mirt results carry a trailing group column and a per-group (list) psi attribute.

Usage

get_fs_lavaan(
  lavobj,
  method = c("regression", "Bartlett", "ML", "EB", "mean"),
  corrected_fsT = FALSE,
  vfsLT = FALSE,
  reliability = FALSE,
  prior_mean = NULL,
  prior_cov = NULL,
  sum_items = NULL,
  ...
)

Arguments

lavobj: A lavaan model object when using get_fs_lavaan().
method: Character. Method for computing factor scores. For lavaan and data frame objects: "regression" (default, consistent with lavPredict), "Bartlett", or "mean" (a third, distinct method: sum scores, each score being the plain uncentered mean of the items assigned to its factor, using no latent distribution), with "ML" an alias for "Bartlett" and "EB" an alias for "regression". For merMod objects: "EB" (empirical Bayes, default; identical to the first random-effect term's ranef() estimates) or "ML" (a prior-free, per-cluster OLS estimate of the random effects, using no random-effects prior, analogous to Bartlett scores for lavaan objects). The "ML"/"EB" aliases apply to the lavaan path only; for merMod objects the two strings are distinct methods. Bartlett scores have more desirable properties than regression scores and may be preferred for 2S-PA. method = "mean" takes the item-to-factor assignment from sum_items (auto-derived from the estimated loadings when NULL); it errors when the model was fitted with missing data retained (e.g. FIML/digamma), and is not supported together with corrected_fsT, vfsLT, reliability, prior_mean, or prior_cov.
corrected_fsT: Logical. Whether to correct for the sampling error in the factor score weights when computing the error variance estimates of factor scores. Currently ignored for merMod objects.
vfsLT: Logical. Whether to return the covariance matrix of fsT and fsL, returned as attribute vfsLT; used for second-order SE correction of 2S-PA results. Currently ignored for merMod objects.
reliability: Logical. Whether to return the reliability of factor scores. Available only for single-factor lavaan models; for multi-factor models a warning is issued and no reliability attribute is returned.
prior_mean: An optional numeric vector of length q (the number of latent variables) giving fixed external prior means for the latent variables. NULL (default) uses the lavaan-estimated (group-specific) latent means. Non-NULL values are treated as fixed external priors shared across all lavaan groups. For mirt SingleGroupClass objects it instead sets the factor prior mean used for the EAP scores; the factor-score intercepts (fsb) then vary per observation as Vpost_i %*% solve(psi) %*% prior_mean, i.e. the latent mean scaled by the per-observation shrinkage factor (zero when prior_mean = NULL), where psi is the mirt model's estimated factor covariance. For mirt MultipleGroupClass objects a non-NULL prior_mean (length q) is applied as the factor prior mean to every group (mirt's per-group EAP is otherwise centred on a zero-mean standard-normal prior); each observation's regression form uses the factor covariance of its own group. Only supported for lavaan objects with regression (EB) scoring (and for mirt); reliability = TRUE is not supported together with user-supplied prior_mean/prior_cov, and prior_cov is not supported for mirt. Conceptually similar to the mean argument of mirt::fscores().
prior_cov: An optional numeric q x q covariance matrix (a scalar or 1 x 1 matrix is accepted when q = 1) giving fixed external prior covariance for the latent variables. NULL (default) uses the lavaan-estimated (group-specific) latent covariance. Non-NULL values must be finite, symmetric and positive definite; when q > 1 the matrix must be named (row and column names matching the latent variable names), so its entries map unambiguously onto the model's latent variables. Values are treated as fixed external priors shared across all lavaan groups. Only supported for lavaan objects with regression (EB) scoring; reliability = TRUE is not supported together with user-supplied prior_mean/prior_cov. With corrected_fsT = TRUE or vfsLT = TRUE the supplied covariance is treated as fixed, i.e. no sampling uncertainty from the prior itself is propagated. Conceptually similar to the cov argument of mirt::fscores().
sum_items: A named list mapping each factor name to the item names that make up its sum score, e.g. list(ind60 = c("x1", "x2", "x3"), dem60 = c("y1", "y2", "y3", "y4")). NULL (default) auto-derives the assignment from the estimated loadings, which requires each indicator to load on exactly one factor and every factor to have at least one item. A supplied list must cover all model factors, and each item may belong to only one sum. Only used for lavaan and data frame objects with method = "mean".
...: additional arguments passed to cfa (when object is a data frame). See lavOptions for a complete list.

Value

A data frame containing the factor scores (with prefix "fs_"), the standard errors (with suffix "_se"), the implied loadings of indicator _by_ factor scores, and the error variance-covariance of the factor scores (with prefix "ev_" or "ecov_"). For multi-group lavaan models in "unified" format, a group column is included. The following attributes are attached: * fsT: error covariance of factor scores (matrix or named list by group) * fsL: loading matrix of factor scores (matrix or named list by group) * fsb: intercepts of factor scores (vector or named list by group); with method = "mean" the intercept is the mean of the factor's item intercepts, the measurement intercept of the score regressed on the uncentered latent (same E[fs] - fsL %*% alpha convention as the other methods; equals the score's column mean for models without a mean structure) * scoring_matrix: weights for computing factor scores from the observed data, as a named list. For lavaan models: one score x item matrix per group; with method = "mean" the weights are the item-mean weights, so S %*% y reproduces the raw scores exactly (no centering offset). For merMod models: one num_re x n_j matrix per cluster, where S_j %*% (y_j - X_j %*% beta) with y_j/X_j the cluster's rows of the model response and the fixed-effects design reproduces the cluster's EB scores for method "EB" and the per-cluster OLS (ML) scores for method "ML". * psi: effective (prior-adjusted) covariance matrix of the latent variables (q x q), group-level (not per-pattern), and a point estimate only (no sampling SEs of the latents are attached). Mirrors the fsT shape: a named list keyed by group label for "unified" output; a direct attribute on each group data frame (plus a list-valued attribute on the outer list) for "list" output; for merMod objects a single q x q matrix. With prior_cov supplied it equals the prior (shared across groups), otherwise the per-group lavaan estimate. For merMod objects the matrix is the first random-effects term's VarCorr, with dimnames renamed to match the fsL column names (u0/u1/..., or the legacy u0_eb/u1_eb names). * alpha: effective (prior-adjusted) means of the latent variables (a named vector of length q), with the same group nesting and point-estimate semantics as psi. With prior_mean supplied it equals the prior, otherwise the per-group lavaan estimate; a named zero vector (0 per latent) when the model has no (estimated) mean structure. For merMod objects a named zero vector (random effects are mean zero). * fs_pattern: for lavaan models, a named list by group of list(label, pat) entries. label is a character vector with one entry per case in the group giving that case's observed-indicator pattern name (NA for cases whose indicators are all missing); pat is a logical matrix with rows = indicators and one column per pattern, the columns being named by pattern name.

    For a lavaan group without missing data, its `fsT`/`fsL`/`fsb`/
    `scoring_matrix` elements are the plain matrix/vector for the whole
    group. When a group's cases split into multiple observed-indicator
    patterns (missing data), each such element is instead a named list
    with one entry per pattern; the pattern name is the observed
    indicator names joined with `"+"` in indicator order (e.g.
    `"x1+x3"`).

    With `local = TRUE` and missing data (e.g. `missing = "fiml"`),
    the `fsT`/`fsL`/`fsb`/`scoring_matrix` attributes are instead
    per-row lists (one entry per data row) and the result carries a
    `per_obs = TRUE` attribute (the same convention as mirt's
    `mirt_per_obs`).

    Note: for a single-group lavaan fit in `"unified"` format, the
    per-group attribute wrappers (`fsT`, `fsL`, `fsb`,
    `scoring_matrix`, `psi`, and `alpha`) are each a one-element list
    named with the empty string `""`; `x[[""]]` does not match in R
    list subsetting, so read these attributes positionally (e.g.
    `attr(fs, "fsT")[[1]]`, `attr(fs, "psi")[[1]]`) rather than by
    name.

Details

get_fs_lavaan() is superseded by get_fs(). It is retained for backward compatibility and delegates to get_fs(object, format = "list") internally. New code should call get_fs() directly.

Examples