docs-simplify-roadmap-formatting-vignette

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: <https://brianmsm.github.io/psymetrics/articles/sem-and-estimates-lavaan.html>
 - Reporting + visualization article: <https://brianmsm.github.io/psymetrics/articles/reporting-and-visualization.html>
 - Development roadmap: [ROADMAP.md](ROADMAP.md)
+
+
+

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:
   <https://brianmsm.github.io/psymetrics/articles/reporting-and-visualization.html>
 - Development roadmap: [ROADMAP.md](ROADMAP.md)
+
+

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.

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: <https://github.com/brianmsm/psymetrics/issues>
 
+
+

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).
+