Changes in version 0.4 (2026-03-31)                   

This release note reflects a direct comparison between the current
package and package_v0.3/nlpsem.

Code quality and documentation improvements

Bug fixes

  - Fixed division-by-zero in getPosterior() entropy calculation when
    nClass = 1.
  - Fixed typo "Accuracys" → "Accuracy" in posterior output display.
  - Fixed missing closing parenthesis in getTVCmodel() documentation for
    Jenss-Bayley curve function.
  - Fixed typo memebership → membership in getSummary().
  - Added missing NULL check for class column in getPosterior() when
    label = TRUE.
  - Added missing model NULL validation in getEstimateStats() for
    likelihood, bootstrap, and combined CIs.
  - Fixed nested any() logic error in validate_res_scale().
  - Fixed [[]] list indexing on numeric vector in getMULTI.initial().
  - Fixed typo "dose not" → "does not" in TVC.initial_helper.R.
  - Fixed getFigure(): Mediation sub-model loop iterated over y_var
    (always length 1) instead of traj_var, and outcome was not indexed —
    only the first trajectory was plotted.
  - Fixed TVC.initial_helper.R: Hardcoded t_var = "T" replaced with the
    actual t_var function parameter when computing TVC initial values.
  - Fixed MED.output_helper.R: Swapped y_var/m_var standard error order
    in 3 output blocks (BLS baseline, LIN longitudinal, BLS
    longitudinal) so SEs match their corresponding estimates.
  - Fixed MED.mxModel_helper.R: Removed quoted strings from mxAlgebra()
    calls in 4 places. mxAlgebra() uses non-standard evaluation (bare
    names); quoted strings are for mxAlgebraFromString().
  - Fixed array indexing in TVC.output_helper.R, MIX.output_helper.R (2
    places), and MGroup.output_helper.R (2 places): Loop assumed
    consecutive records starting at 1; replaced with seq_along() for
    correct indexing with arbitrary record indices.
  - Fixed getPosterior(): Protected entropy calculation from log(0)
    using pmax(prob, .Machine$double.xmin).
  - Fixed getLatentKappa(): Added defensive guard for kappa edge cases
    (kappa >= 1 or <= 0).
  - Fixed getSummary(): Empty latent classes in mixture models now
    handled correctly using factor(membership, levels = 1:nClass) to
    ensure proportions vector matches nClass.
  - Fixed validate_res_scale(): List branch now uses <= 0 / >= 1 to
    match non-list branch (both enforce exclusive bounds as documented).
  - Fixed MIX.initial_helper.R: TVC residual (TVC_starts$residuals) now
    also inflated by 2× when decompose != 0, matching the Y residual
    inflation for mixture model convergence.
  - Fixed MULTI.initial_helper.R: Residual covariance matrix
    off-diagonal indexing used res_cor[traj_i + traj_j - 1] which
    produced wrong indices for 4+ longitudinal outcomes. Replaced with
    sequential counter to correctly map pair (i,j) to res_cor vector
    position.
  - Fixed TVC.initial_helper.R: Added res_cor = NULL default to
    getTVC.initial() signature. Callers in MIX.initial_helper.R and
    MGroup.initial_helper.R omit res_cor when decompose = 0 (where it is
    unused), but the missing default could cause errors if the function
    is refactored.
  - Fixed getMGM() / getMULTI.initial(): Multivariate models now
    preserve the full y_var prefixes provided by the user instead of
    collapsing them to single-letter uppercase prefixes.
  - Fixed MGM.output_helper.R, MGroup.output_helper.R, and
    MIX.output_helper.R: between-process covariance output for 3+
    outcomes/classes no longer appends cumulative estimate blocks or
    corrupts paramOut tables.
  - Fixed MGM.mxModel_helper.R, MGroup.SUBMODEL.MGM_helper.R, and
    MIX.SUBMODEL.MGM_helper.R: Fixed-parameter multivariate covariance
    extraction now works for 3+ outcomes instead of assuming exactly 2
    longitudinal processes.
  - Fixed MED.Initial_helper.R: In longitudinal-predictor mediation
    models, the initial beta_x and beta_m blocks are no longer swapped
    in the outcome regression starts.
  - Fixed TVC.initial_helper.R: decompose = 3 now computes kappa starts
    from the change-from-baseline temporal state implied by the latent
    growth-factor starts, and the nonparametric path now returns finite
    starts instead of falling through to NA.
  - Fixed intrinsic bilinear spline loading expressions across LGCM,
    TVC, MGM, mixture, and multiple-group models by replacing the
    nondifferentiable knot expression with a smooth approximation,
    improving optimizer behavior near the knot.
  - Fixed MIX.output_helper.R: Cluster-TIC coefficient names now scale
    to any number of predictors instead of hard-coding a 3-column naming
    pattern.

Code improvements

  - Removed unnecessary I() wrappers from logical conditions across 11
    files.
  - Extracted duplicated validation logic into shared internal helpers
    (validation_helpers.R).
  - Vectorized row-by-row probability matrix computation in
    getPosterior() using sweep()/rowSums().
  - Refactored positional list indexing (starts[[1]][[2]]) to named
    access (starts$Y_starts$covMatrix) across all helper files for
    maintainability.
  - Added as.data.frame(dat) guard in all main functions for tibble
    compatibility.
  - Added validate_res_cor() helper and validation calls in
    getTVCmodel(), getMGM(), getMediation(), getMIX(), and getMGroup().
  - Removed duplicate validate_curveFun_mediation() function (logic
    already in validate_sub_Model()).
  - Eliminated code duplication in getFigure() by removing redundant
    is.null(nClass) / !is.null(nClass) branching.
  - Simplified redundant else if conditions in StandardMethods.R.
  - Data-driven residual initial values: getUNI.GF() now computes
    per-person mean squared residuals from individual model fits and
    returns the median as an attribute. All initial value helpers
    (UNI.initial_helper.R, MULTI.initial_helper.R, TVC.initial_helper.R,
    MED.Initial_helper.R) now use this data-driven estimate instead of
    the var() * res_scale heuristic, with the heuristic retained as a
    fallback. This provides more accurate starting values, especially
    for nonlinear functional forms (EXP, JB, BLS) where the heuristic
    could be orders of magnitude off.
  - Refactored duplicated Wald/likelihood/bootstrap CI code in
    getEstimateStats() into local helpers (.add_wald_CI(),
    .get_likelihood_CI(), .get_bootstrap_CI()).
  - Changed scalar logical operators from &/| to &&/|| in
    validation_helpers.R (7 places) and getFigure.R (3 places) for
    proper short-circuit evaluation.
  - Removed dead code in MIX.initial_helper.R (duplicate order_indices
    assignment).
  - Added 13 NSE global variable declarations to global_vars.R for bare
    names used in mxAlgebra() calls.
  - res_scale is now optional: With data-driven residual estimation,
    users no longer need to specify res_scale. When omitted (default
    NULL), the data-driven estimate is used; if that fails, a fallback
    heuristic of var() * 0.1 is applied. Users can still override with
    an explicit res_scale value if desired.
  - res_cor is now optional: Residual correlation between longitudinal
    outcomes is now estimated from data when res_cor is not specified.
    The estimation uses within-person demeaned residuals correlated
    across trajectory pairs. If estimation fails, a heuristic of 0.3 is
    applied as fallback. This applies to getMGM(), getMediation(),
    getTVCmodel() (when decompose != 0), getMIX(), and getMGroup().
    Users can still override with explicit res_cor values if desired.
  - Automatic parameter naming: When paramOut = TRUE, the names argument
    is now optional. If omitted (default NULL), meaningful parameter
    names are automatically generated based on the model configuration
    (functional form, intrinsic flag, covariates, decompose level,
    etc.). This eliminates the need for users to manually construct long
    parameter name vectors for every model. Users can still supply
    custom names to override the auto-generated labels. Auto-naming is
    supported across all 7 model functions: getLGCM(), getLCSM(),
    getTVCmodel(), getMediation(), getMGM(), getMIX(), and getMGroup().
    A safety net in all output helpers auto-pads with generic labels if
    the name count doesn't match the estimate count.
  - Improved BLS initial values: Bilinear spline (BLS) individual growth
    factor estimation now uses a grid search over 10 candidate knot
    locations (with OLS piecewise-linear fits) instead of a single
    midpoint guess. The top 3 candidates are tried with NLS, using both
    default Gauss-Newton and port algorithms with bounded knot location.
    This reduces NLS failure rates from ~40-46% to ~25% and lowers
    median residual variance by ~40-60%, yielding more accurate starting
    values for BLS models.
  - Added pooled-anchor nonlinear starts for negative exponential,
    Jenss-Bayley, and bilinear spline growth functions. These starts
    preserve person-level pseudo growth factors, so latent mean and
    covariance starts are still estimated from subject-specific values
    rather than from a single pooled trajectory.
  - Added intrinsic-specific stabilization for nonlinear starts in
    univariate, TVC, multivariate, multiple-group, and mixture wrappers,
    including more conservative starts for random
    knot/ratio/acceleration components.
  - Added robust cluster-TIC softmax starts for mixture models:
    predictors are standardized before the multinomial fit, coefficients
    are transformed back to the original scale, and the result is shrunk
    toward intercept-only logits with a fallback for unstable fits or
    constant predictors.
  - Centralized repeated positive-definite repair logic in
    initial_helpers_common.R, added reusable validation helpers in
    validation_helpers.R, and introduced shared helpers for output
    naming and multivariate covariance reduction in
    output_helpers_common.R and multi_cov_helpers.R.

Documentation

  - Added @seealso cross-references linking related functions across
    all 14 exported functions.
  - Added @noRd to all 44 internal helper files to suppress unnecessary
    .Rd generation.
  - Added introductory vignette (nlpsem_overview) with package overview
    and quick-start guide.
  - Expanded getMGroup_examples vignette with a second example
    (quadratic LGCM with TICs).
  - Added explanatory comment to global_vars.R.
  - Added NEWS.md changelog.
  - Added \examples{} sections to ModelSummary and printTable S4
    generics.
  - Fixed LaTeX math mode ($95\%$) to plain text in KappaOutput class
    documentation.
  - Shortened DESCRIPTION title to comply with CRAN < 65 character
    guideline.
  - Fixed typo "loadigs" → "loadings" in comments across 10 helper
    files.
  - Fixed typo "his function" → "This function" in
    LGCM.mxModel_helper.R.
  - Fixed typo "model.It" → "model. It" in getEstimateStats.R roxygen.
  - Fixed typo "Calcualte" → "Calculate" in getLatentKappa.R example.
  - Fixed grammar "if want to" → "if you want to" in
    validation_helpers.R.
  - Fixed misleading comments in getMIX.R and getMGroup.R (said "latent
    change score model" instead of "mixture model" / "multiple group
    model").
  - Synchronized the vignette code with the regenerated examples in
    inst/extdata.
  - Updated package- and function-level references from preprint /
    "advance online publication" wording to the final journal citations
    where available.
  - Added vignette build metadata to DESCRIPTION (knitr, rmarkdown, and
    VignetteBuilder) and added the introductory nlpsem_overview
    vignette.

Testing and infrastructure

  - Added a tests/testthat suite covering validation helpers, automatic
    parameter naming, nonlinear growth-factor starts, mediation starts,
    and multivariate regression cases.
  - Refreshed the saved example objects in inst/extdata/*.RData and
    aligned the vignettes with those regenerated examples.

                  Changes in version 0.3 (2023-09-12)                   

Initial CRAN release

Model types

  - Univariate latent growth curve models (getLGCM()) and latent change
    score models (getLCSM()), with optional time-invariant covariates
    (TICs).
  - Models with time-varying covariates (getTVCmodel()).
  - Multivariate longitudinal models (getMGM()) and longitudinal
    mediation models (getMediation()).
  - Multiple-group models (getMGroup()) for comparing trajectories
    across manifested groups.
  - Longitudinal mixture models (getMIX()) for identifying latent
    trajectory classes.

Supported growth curve functions

  - Linear, quadratic, negative exponential, Jenss-Bayley, and bilinear
    spline functional forms.
  - Intrinsically nonlinear specification for negative exponential,
    Jenss-Bayley, and bilinear spline models.

Post-processing and inference

  - getSummary(): Model fit statistics (number of parameters, -2LL, AIC,
    BIC).
  - getEstimateStats(): P-values and confidence intervals (Wald,
    likelihood-based, and bootstrap).
  - getFigure(): Visualization of estimated growth trajectories with
    confidence intervals.
  - getLRT(): Likelihood ratio test for nested model comparison.
  - getIndFS(): Individual factor scores.
  - getPosterior(): Posterior class probabilities for mixture models.
  - getLatentKappa(): Cohen's kappa for latent class agreement.

Data

  - Included RMS_dat, a processed sample from the ECLS-K:2011 study for
    demonstration purposes.