diff --git a/README.Rmd b/README.Rmd index e7419df..dd9e27d 100644 --- a/README.Rmd +++ b/README.Rmd @@ -85,9 +85,12 @@ sem_model <- ' ' fit_sem <- sem(sem_model, data = HolzingerSwineford1939) -compared_estimates <- compare_model_estimates(CFA = fit_mlr, SEM = fit_sem, select = "se_p") +compared_estimates <- compare_model_estimates( + CFA = fit_mlr, + SEM = fit_sem, + select = "se_p" +) compared_estimates -format_results(compared_estimates, table_args = list(select = "{estimate} ({ci})|{p}")) ``` ## Learn more @@ -97,3 +100,6 @@ format_results(compared_estimates, table_args = list(select = "{estimate} ({ci}) - SEM + estimates article: - Reporting + visualization article: - Development roadmap: [ROADMAP.md](ROADMAP.md) + + + diff --git a/README.md b/README.md index e247028..feafc28 100644 --- a/README.md +++ b/README.md @@ -72,9 +72,12 @@ sem_model <- ' ' fit_sem <- sem(sem_model, data = HolzingerSwineford1939) -compared_estimates <- compare_model_estimates(CFA = fit_mlr, SEM = fit_sem, select = "se_p") +compared_estimates <- compare_model_estimates( + CFA = fit_mlr, + SEM = fit_sem, + select = "se_p" +) compared_estimates -format_results(compared_estimates, table_args = list(select = "{estimate} ({ci})|{p}")) ``` ## Learn more @@ -87,3 +90,5 @@ format_results(compared_estimates, table_args = list(select = "{estimate} ({ci}) - Reporting + visualization article: - Development roadmap: [ROADMAP.md](ROADMAP.md) + + diff --git a/ROADMAP.md b/ROADMAP.md index 7be4843..da0dee2 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,99 +1,76 @@ # Development Roadmap & Versioning Plan -This document outlines the development plan and versioning strategy for the `psymetrics` package. It serves as a portable, high-level guide for development priorities. +This document is the high-level roadmap for `psymetrics`. It is meant to answer two questions quickly: -While this file contains the overall plan, day-to-day discussion and detailed technical specifications for each task live in the linked GitHub Issues. +1. What is already done? +2. What is the next milestone? -## **Current Status & Progress** +Detailed technical discussion for each milestone lives in the linked GitHub Issues. -* 🚧 In Progress: `v0.4.0` - Implement `compare_model_estimates()` +## Status at a glance - Current milestone work is focused on parameter-level comparisons across fitted models. +- ✅ Latest completed milestone: `v0.4.0` - Implement `compare_model_estimates()` + - Added parameter-level comparison for fitted `lavaan` models. + - Integrated with `print()`, `format_results()`, and `save_table()`. + - Expanded tests and pkgdown-facing documentation. + - Tracked in **[Issue #18](https://github.com/brianmsm/psymetrics/issues/18)**. - - **Goal:** - - Add `compare_model_estimates()` for comparing parameter estimates across two or more models. - - Provide output compatible with existing formatting and export workflows (`print()`, `format_results()`, and `save_table()`). - - Complete acceptance criteria tracked in **[Issue #18](https://github.com/brianmsm/psymetrics/issues/18)**. +- ⏭ Next planned milestone: `v0.5.0` - Implement `plot_model_fit()` + - Goal: add a visual workflow for fit indices. + - Tracked in **[Issue #19](https://github.com/brianmsm/psymetrics/issues/19)**. -* ✅ Completed: `v0.3.0` - Implement `model_estimates()` +## Recently completed milestones - - Added `model_estimates()` support for `lavaan` CFA/SEM workflows. - - Integrated `model_estimates` with formatting and DOCX export pipelines. - - Expanded tests and documentation for extraction, formatting, and export behavior. - - Completed milestone acceptance criteria tracked in **[Issue #17](https://github.com/brianmsm/psymetrics/issues/17)** (implemented via **[PR #44](https://github.com/brianmsm/psymetrics/pull/44)**, merged on February 25, 2026). +- ✅ **`v0.4.0`** - Implement `compare_model_estimates()` *(completed March 6, 2026)* +- ✅ **`v0.3.0`** - Implement `model_estimates()` *(completed February 25, 2026)* +- ✅ **`v0.2.0`** - Extend SEM support across existing workflows *(completed February 8, 2026)* -* ✅ Completed: `v0.2.0` - Extend Existing Functions for SEM - - - Officially validated and documented SEM support for fitted `lavaan` objects in `model_fit()`, `compare_model_fit()`, and `plot_factor_loadings()`. - - Expanded SEM coverage for structural models, growth models, multigroup/multilevel contexts, categorical estimators, missing-data handling, and non-converged/path-only edge cases. - - Completed milestone acceptance criteria tracked in **[Issue #25](https://github.com/brianmsm/psymetrics/issues/25)**. - -* ✅ Completed: `v0.1.9.x` - Stability & Documentation Polish - - - Expanded `testthat` coverage for core workflows and edge cases. - - Improved formatting/messaging behavior and aligned documentation with current implementation. - -* ✅ Completed: `v0.1.5` - Stability & Testing Release - - - Added an initial `testthat` suite covering `model_fit`, `compare_model_fit`, plotting, and `save_table`. +Earlier stabilization milestones (`v0.1.9.x`, `v0.1.5`) focused on testing, messaging, and documentation polish. --- -## **Future Roadmap** - -### **Phase 1: Complete and Consolidate `lavaan` Workflow (CFA & SEM)** - -The focus of this phase is to build a robust and feature-complete workflow for models fitted with `lavaan`, covering both Confirmatory Factor Analysis (CFA) and general Structural Equation Models (SEM). - -* [x] **`v0.2.0`**: **Extend Existing Functions for SEM.** *(Completed on February 8, 2026)* - - - *Goal*: Officially support SEM in `model_fit`, `compare_model_fit`, and `plot_factor_loadings`. - - *Details*: **[Issue #25](https://github.com/brianmsm/psymetrics/issues/25)** - -* [x] **`v0.3.0`**: Implement `model_estimates()` for parameter extraction. *(Completed on February 25, 2026)* - - - *Details*: **[Issue #17](https://github.com/brianmsm/psymetrics/issues/17)** - -* [ ] **`v0.4.0`**: Implement `compare_model_estimates()` for parameter comparison. - - - *Details*: **[Issue #18](https://github.com/brianmsm/psymetrics/issues/18)** - -* [ ] **`v0.5.0`**: Implement `plot_model_fit()` for visualizing fit indices. +## Roadmap by phase - - *Details*: **[Issue #19](https://github.com/brianmsm/psymetrics/issues/19)** - -* [ ] **`v0.6.0`**: Enhance `compare_model_fit()` for Measurement Invariance (MG-CFA). +### Phase 1: Complete and consolidate the `lavaan` workflow - - *Details*: **[Issue #20](https://github.com/brianmsm/psymetrics/issues/20)** - -* [ ] **`v0.7.0`**: Create a helper function for specifying invariance models. +The goal of this phase is a robust, end-to-end CFA/SEM workflow for models fitted with `lavaan`. - - *Details*: **[Issue #21](https://github.com/brianmsm/psymetrics/issues/21)** - -* [ ] **`v0.8.0`**: Add Excel (`.xlsx`) export functionality to `save_table()`. +- [x] **`v0.2.0`**: Extend existing functions for SEM + - Officially support SEM in `model_fit()`, `compare_model_fit()`, and `plot_factor_loadings()`. + - Details: **[Issue #25](https://github.com/brianmsm/psymetrics/issues/25)** - - *Details*: **[Issue #22](https://github.com/brianmsm/psymetrics/issues/22)** - +- [x] **`v0.3.0`**: Implement `model_estimates()` + - Add parameter extraction for `lavaan` CFA/SEM workflows. + - Details: **[Issue #17](https://github.com/brianmsm/psymetrics/issues/17)** -### **Phase 2: Expansion to Other Models & Packages** +- [x] **`v0.4.0`**: Implement `compare_model_estimates()` + - Add parameter comparison across two or more fitted models. + - Details: **[Issue #18](https://github.com/brianmsm/psymetrics/issues/18)** -This phase will commence after the core `lavaan` functionality is stable and complete. +- [ ] **`v0.5.0`**: Implement `plot_model_fit()` + - Add visual summaries for fit indices. + - Details: **[Issue #19](https://github.com/brianmsm/psymetrics/issues/19)** -* [ ] **`v0.9.0`**: **Add full support for `lavaan` EFA models.** +- [ ] **`v0.6.0`**: Enhance `compare_model_fit()` for measurement invariance (MG-CFA) + - Details: **[Issue #20](https://github.com/brianmsm/psymetrics/issues/20)** - - *Goal*: Extend all relevant functions to be compatible with Exploratory Factor Analysis models fitted with `lavaan`. - -* [ ] **`v0.10.0`**: **Add full support for `mirt` objects.** +- [ ] **`v0.7.0`**: Create a helper for specifying invariance models + - Details: **[Issue #21](https://github.com/brianmsm/psymetrics/issues/21)** - - *Goal*: Extend all functions to be compatible with models from the `mirt` package. - -* [ ] **`v0.11.0`**: **Add full support for `psych` EFA objects.** +- [ ] **`v0.8.0`**: Add Excel (`.xlsx`) export support to `save_table()` + - Details: **[Issue #22](https://github.com/brianmsm/psymetrics/issues/22)** - - *Goal*: Extend all functions to be compatible with EFA models from the `psych` package. +### Phase 2: Expand support to other model classes +This phase starts after the core `lavaan` workflow is stable. -## **Final Milestone: Stable Release** +- [ ] **`v0.9.0`**: Add full support for `lavaan` EFA models +- [ ] **`v0.10.0`**: Add full support for `mirt` objects +- [ ] **`v0.11.0`**: Add full support for `psych` EFA objects -* [ ] **`v1.0.0`**: **Stable & Complete Release.** +## Final milestone - - *Goal*: All features are implemented, documented, and thoroughly tested. The package API is considered reliable and stable. Comprehensive documentation, including tutorials (vignettes), is complete. +- [ ] **`v1.0.0`**: Stable and complete release + - All planned core features are implemented, documented, and thoroughly tested. + - The package API is considered reliable and stable. + - Tutorials and long-form documentation are complete. diff --git a/index.md b/index.md index 157178a..f02b3ef 100644 --- a/index.md +++ b/index.md @@ -18,6 +18,7 @@ The package currently focuses on `lavaan` CFA and SEM workflows. - Fit extraction with `model_fit()` - Fit comparison with `compare_model_fit()` - Parameter extraction with `model_estimates()` + - Parameter comparison with `compare_model_estimates()` - Reporting with `format_results()` and `save_table()` - Loading visualization with `plot_factor_loadings()` - In development: @@ -28,7 +29,7 @@ The package currently focuses on `lavaan` CFA and SEM workflows. ```r # install.packages("pak") -pak::pak("brianmsm/psymetrics@v0.3.0") +pak::pak("brianmsm/psymetrics@v0.4.0") ``` ## Recommended path @@ -56,3 +57,5 @@ Issues and feature requests are welcome: GitHub issues: + + diff --git a/vignettes/sem-and-estimates-lavaan.Rmd b/vignettes/sem-and-estimates-lavaan.Rmd index 4249369..bff9a3a 100644 --- a/vignettes/sem-and-estimates-lavaan.Rmd +++ b/vignettes/sem-and-estimates-lavaan.Rmd @@ -148,9 +148,11 @@ compare_model_estimates( ) ``` -## Override the layout for a specific output +## Render the same comparison in another layout -The `select` value stored in the object is the default layout. For one-off exports or alternate views, override it in `format_results()` with `table_args`. +In most cases, prefer setting `select` directly in `compare_model_estimates()`. That keeps the default presentation close to where the comparison is created. + +`format_results(..., table_args = list(select = ...))` is useful when you already have a comparison object and want to render the same aligned estimates in a different way for a specific output. This works because the `compare_model_estimates()` result keeps the underlying estimate, standard error, confidence interval, and p-value columns needed to rebuild the display later. ```{r, eval=has_lavaan} format_results( @@ -172,11 +174,14 @@ format_results( ## When to use each layer -Use `compare_model_estimates(select = ...)` when you want the object itself to carry a default presentation. +Start with `compare_model_estimates(select = ...)` when you know the layout you want most of the time. + +Use `format_results(..., table_args = list(select = ...))` when you want an alternate console view, export, or manuscript-ready layout from the same stored comparison object without recomputing the comparison. -Use `format_results(..., table_args = list(select = ...))` when you want a temporary view for a particular report, export, or presentation without changing the object's default layout. +If you do not need that flexibility, staying with `select` inside `compare_model_estimates()` is the simpler option. ## Next steps - Continue with [Reporting and visualization](reporting-and-visualization.html). - See function-level details in the [Reference](../reference/index.html). +