Skip to content

ackwards 0.3.0

Latest

Choose a tag to compare

@jmgirard jmgirard released this 19 Oct 14:43

Oblique rotation as an option, with partialled edge coefficients and
within-level factor correlations in tidy(). Also fixes to the ESEM engine,
and documentation rewritten in plain English.

Breaking changes

  • ESEM with cor = "spearman" and missing = "fiml" now stops with an
    error.
    Before this fix, the fit ran, but x$r held lavaan's Pearson FIML
    matrix while the object reported cor = "spearman". All edges were Pearson
    under a Spearman label. FIML estimates a multivariate-normal (Pearson)
    matrix on every engine, so it now requires cor = "pearson" for ESEM, as
    it already did for PCA and EFA. To keep a Spearman basis, use
    missing = "pairwise" or "listwise". The warning for ESEM with
    cor = "spearman" now says that lavaan fits Pearson covariances of the raw
    data. Before, it said "Pearson-ML model", which was wrong under WLSMV and
    ULSMV.

New features

  • Oblique rotation as an option. ackwards() gains a rotation
    argument. The default stays "varimax", and default numerical output does
    not change (PCA and EFA factor_cor gain row and column names, see
    below). With engine = "pca" or "efa", it also accepts "oblimin" and
    "promax". The GPArotation package (now in Suggests) is needed for
    "oblimin" with these engines, and for "promax" with engine = "efa". With
    engine = "esem", it also accepts "oblimin" and "geomin". Under an
    oblique rotation, each level stores the engine's factor correlation. The
    scores keep that correlation: EFA and ESEM use the oblique form of the ten
    Berge weights, and PCA uses the oblique components. The variance values
    follow psych's convention for correlated factors. Each edge r is then a
    total correlation. Primary parents, sign alignment, and the diagram still
    use r, and beta in tidy() gives the partialled coefficient. The fit
    prints a message that says so, and print(), summary(), and autoplot()
    label it. prune() warns that its thresholds were set for varimax.
    boot_edges() refits each replicate with the object's rotation. If that
    rotation needs GPArotation, it checks for the package first. A PCA level whose
    oblique rotation fails, or raises an error, ends the hierarchy at the level
    before it, because PCA rotates once. EFA rotates from several random
    starts, so its non-convergence warnings are shown and the level is kept.
    ESEM counts its failed starts, as the first entry under Bug fixes
    describes. An EFA level whose final rotation step failed still ends the
    hierarchy. If the installed psych rotates from one start, any EFA rotation
    warning ends it too. Set seed to reproduce an oblique EFA fit or any ESEM
    fit exactly. A new test checks the oblique results against Forbes's
    reference implementation on her three simulation studies.

  • Within-level factor correlations are carried and shown. Every engine
    now stores the factor correlation it reports for each level. That matrix
    is permuted and sign-flipped in step with the loadings, in place of a
    fixed identity matrix. The new table tidy(x, what = "factor_cor") has
    one row per pair of factors within a level. Its columns are level,
    factor_a, factor_b, and cor. The summary() output prints a
    "Within-level factor correlations" block only when some pair is
    correlated, which means a within-level correlation above 1e-8 in size.
    Under the default varimax rotation every within-level correlation is 0, so
    no number changes and the block is absent.

  • Partialled edge columns. The edge table from tidy() gains beta
    beside r, and the variance table gains r2. The beta column is the
    standardized regression weight of the child factor on all factors of the
    parent level together. It removes the part of r that the other factors
    at the parent level share. The r2 column is the share of a factor's
    score variance that all factors of the level just above account for
    together. It is NA at level 1. Under varimax beta equals r, and
    r2 equals the sum of that factor's squared r values from the level
    above. The two pairs of quantities come apart only when the factors within
    a level are correlated. If a level's within-level score correlation
    cannot be inverted, both are NA, with a warning.

  • tidy(what = "edges") now warns when the within-level score correlation
    of a level is nearly singular, meaning its smallest eigenvalue is below
    1e-2. The factors at that level are then close to collinear, so the
    partialled beta for edges from that level is unstable. beta is still
    reported, and the warning names the level. The package chose this cutoff
    as a numerical guard. It is not a published rule. tidy(what = "variance")
    and summary() do not raise this warning.

  • PCA and EFA factor_cor matrices now carry the level's factor labels as
    row and column names, as the ESEM ones already did.

Bug fixes

  • ESEM now counts failed rotation starts. At each rotated level, lavaan
    keeps the best of 30 random starts (its default). In 0.2.0, ESEM showed no
    rotation warning, and it kept the level even when no start converged. Now
    a warning gives the count of starts that did not converge (for example,
    "3 of 30"), and the level is kept. If no start converged, the kept
    rotation did not converge either. The hierarchy then ends at the level
    before it with a warning. This holds under every ESEM rotation, varimax
    included. Fits where at least one start converges keep the same levels
    and values as before.

  • ESEM with ULSMV on continuous items now fits under the default
    missing = "pairwise".
    Before this fix, ackwards() stopped at level 1
    with a lavaan error, complete data included. lavaan 0.7.2 efa() fails for
    ULSMV on continuous items when it uses all available cases. That setting
    now fits the complete rows, as ML and MLR do, and the edges still come
    from the pairwise correlation matrix. ULSMV on cor = "polychoric" and
    WLSMV are unchanged. The help for missing in ackwards() now says which
    estimators use all available cases. It no longer calls WLSMV and ULSMV
    ordinal-only, and it names the $meta fields that record the setting. The
    estimator table in the engines article no longer calls them ordinal-only
    either.

Documentation

  • Which matrix an edge is exact for. Each between-level edge is implied
    by the correlation matrix the fit uses, and it is exact for that matrix.
    The package description, the README, the help for ackwards(), tidy(),
    and prune(), and five articles now say so. The five articles are the
    introduction, engines, ordinal, recommended-workflow, and Forbes articles.
    Scores computed from the observed items do not in general reproduce the
    edges when that matrix is polychoric or Spearman. The same holds when the
    matrix comes from incomplete data, by pairwise deletion or by
    full-information maximum likelihood (FIML). The ackwards() help names
    the two ESEM settings in which lavaan fits a matrix other than the stored
    x$r. With cor = "spearman" and missing = "pairwise" or
    "listwise", lavaan fits Pearson covariances of the raw data. With
    cor = "pearson" and missing = "pairwise" on data with missing values,
    ML and MLR fit the complete rows, and WLSMV fits the pairwise covariances.
    The package description no longer says that edges can come from
    materialized scores, because no exported function computes them that way.
    It credits Waller (2007) with the closed-form result for principal
    components only. No code or result changed.

  • Where the redundancy chase stops, in the prune() help. Under the
    default redundancy_criterion = "direct", the chase stops at the first
    ancestor level that fails the criterion. A level further up that passes
    again does not restart it. The help now says so, and says that this stop
    follows Forbes's (2023) reference code, ChaseCorrPaths. To bridge such a
    gap by your own judgment, pass the factor to drop to manual. A
    factor that no rule flagged then gets prune_reason = "manual", and manual adds no row to
    x$prune$chains. A new test shows this on component m7f2 of the
    forbes2023 example. The behavior and results of prune() did not
    change.

  • Varimax and oblimin side by side in the engines article. The section on
    orthogonal and oblique rotation now fits EFA to the BFI-25 twice, with
    varimax and with oblimin, in place of the simulated example. It shows the
    oblimin factor correlations within each level. It matches each oblimin
    factor to a varimax factor by Tucker's congruence of loadings. After the
    match, the two primary-parent trees are the same. It lists
    the secondary edges that reach the display cutoff under oblimin, with r
    beside beta, and draws both diagrams. No package function or its output
    changed.

  • Plain-English documentation. The README, the package description, the
    help pages, and all nine articles were revised so that a reader outside
    the field can follow them on one read. Sentences are shorter, and each
    statistical term is explained in plain words where it is first used. No
    function, argument, default, or example changed. The code in the articles
    and the results they show did not change either. The settings that
    reproduce Forbes (2023), the Pearson default with its ordinal-data
    warning, and the descriptive reading of the hierarchy are stated as before.