# ShortForm

# *News*

# ShortForm v1.0.0

## Breaking Changes

This release standardizes the three top-level algorithm functions’
arguments and, in a few cases, their names, so the same concept is
expressed the same way regardless of which algorithm you’re calling.

- Renamed `antcolony.lavaan()` to `antColony()`, and `tabuShortForm()`
  to `tabuSearch()`, to match `simulatedAnnealing()`’s naming style.
  `antcolony.mplus()` and `tabu.sem()` (the lower-level Tabu function)
  are unchanged.
- Renamed `antColony()`’s `antModel` argument to `initialModel`,
  matching `simulatedAnnealing()`/`tabuSearch()`.
- Unified item/factor specification across all three functions:
  `antColony()`’s `list.items`, `full`, `i.per.f`, and `factors`
  arguments are replaced by `items` (an optional flat vector of
  candidate item names, defaulting to `colnames(data)`) and
  `itemsPerFactor` (target item count per factor); `factors` is now
  always derived from `initialModel`’s syntax, the same way
  `simulatedAnnealing()` already did it. `simulatedAnnealing()`’s
  `maxItems` and `tabuSearch()`’s `numItems` are both renamed to
  `itemsPerFactor` to match, and `tabuSearch()` gains the same optional
  `items` argument.
- Renamed the iteration-count argument to `maxIterations` across all
  three functions (previously `simulatedAnnealing()`’s `maxSteps`,
  `tabuSearch()`’s `niter`, and `antColony()`’s `max.run`).
  `antColony()`’s `steps` argument (its separate, stagnation-based
  stopping rule) is unchanged.
- Unified `bifactor` to a `character` factor name (or `NULL`) across all
  three functions. `simulatedAnnealing()`/`tabuSearch()` previously took
  a logical flag and always assumed the *last* factor in the model
  syntax was the bifactor; they now name it explicitly, matching
  `antColony()`’s existing behavior.
- Replaced `simulatedAnnealing()`’s `fitStatistic`/`maximize` arguments
  with `criterion`/`negateCriterion`, matching
  `tabuSearch()`/`tabu.sem()`. `criterion` now accepts either a
  `character` fit-measure name (e.g. `"cfi"`) or an arbitrary function
  for all three of `simulatedAnnealing()`, `tabuSearch()`, and
  `tabu.sem()` (previously function-only for the latter two).
- Removed `antColony()`’s `summaryfile`/`feedbackfile` arguments and
  their file-writing side effects; the same information is already
  available from the returned object’s `summary`/`final_solution` slots
  and the console progress output. Added a `verbose` argument (matching
  `tabuSearch()`) to control that console progress output.

## Bugfixes

- Fixed tabuSearch crashing with “could not find function ‘%dopar%’”
  when run with parallel = TRUE under CRAN-style core-limited
  environments (e.g., when `_R_CHECK_LIMIT_CORES_` is set)
- Fixed simulatedAnnealing hanging indefinitely when a candidate
  short-form change asked for more item swaps than a factor had
  available capacity
- Fixed tabu.sem crashing when a candidate neighbor failed to refit
  entirely, rather than just failing to converge
- Fixed tabu.sem crashing when every candidate neighbor was invalid or
  already on the tabu list
- Fixed antColony crashing when a partial lavaan.model.specs override
  was supplied, due to an internal default for `ordered` that didn’t
  match the function’s own documented default
- Fixed antColony silently dropping the
  `group`/`group.label`/`group.equal`/`group.partial`/`group.w.free`
  elements of lavaan.model.specs, due to a duplicated `auto.var` entry
  in its internal defaults and those elements never being wired into the
  underlying `lavaan()` call
- Fixed simulatedAnnealing producing a spurious “multiple local function
  definitions for ‘progressCallback’” NOTE under R CMD check, and
  restored its per-step “Current Step” progress output (previously
  assigned to an unreachable code path) for both serial and parallel
  runs
- Fixed simulatedAnnealing and tabu.sem crashing with “missing value
  where TRUE/FALSE needed” whenever a candidate (or the initial) model’s
  criterion value came back NA – most easily triggered by
  under-identified or poorly-specified models. An NA candidate is now
  always treated as worse than the current best, and an NA best is
  always displaced by any valid candidate.

## Updates

- Reworked negateCriterion (tabu.sem, tabuSearch) so it genuinely
  controls whether the search looks for the largest or smallest value of
  the objective/criterion function, rather than requiring users to
  pre-negate their own criterion function beforehand
- Renamed tabu.sem’s `obj` argument to `criterion`, matching tabuSearch
- Changed tabuSearch’s default criterion from a pre-negated `-cfi` to
  plain `cfi`
- Extended partial lavaan.model.specs overrides (previously only
  supported by antColony) to simulatedAnnealing and tabuSearch, with new
  typo detection for unrecognized element names across all three
  algorithms
- Added a burn\_in argument and whole-number axis ticks to
  simulatedAnnealing’s plot method
- Consolidated TS’s show/summary model-syntax reconstruction into one
  shared internal helper
- Function calls for simulatedAnnealing, tabuSearch, tabu.sem, and
  antColony are now captured with every argument resolved (specified or
  defaulted), including the actual merged lavaan.model.specs used
- Corrected @return documentation for tabu.sem, tabuSearch,
  simulatedAnnealing, and antColony to describe their actual S4 return
  types instead of stale list descriptions
- Consolidated the parallel cluster bootstrap/teardown boilerplate
  shared by antColony, simulatedAnnealing, and tabuSearch into shared
  internal helpers
- Replaced internal `mapply(assign, ...)` variable-splatting with
  `do.call()` (where the values were only ever fed into a single
  downstream `lavaan()` call) or plain named-list access (where a couple
  of values were unpacked for general use), removing several ad hoc
  internal environments in the process
- Added the selected criterion/fit-statistic and its final-model value
  to the show/summary output for SA, TS, and ACO objects
- Added a shared `resolveCriterion()` internal helper so `criterion` can
  be a character fit-measure name or a function everywhere it’s accepted
- Added vignettes

# ShortForm v0.5.9

Note: v0.5.9 was an internal version only and was not released to CRAN;
the changes below were included in the v1.0.0 release.

## Bugfixes

- Fixed simulatedAnnealing crashing when run without maxItems (i.e.,
  full-model rather than short-form usage)
- Fixed tabu.sem and tabuShortForm erroring instead of returning a
  result when no candidate model improved on the initial model
- Fixed simulatedAnnealing’s restart-after-stagnation logic throwing an
  error instead of restarting
- Fixed antcolony.lavaan’s stopping rule comparing the wrong ant
  solutions, and a warning/error check that could crash a run
- Fixed a bug where swapping an item for a short form could silently
  corrupt an unrelated item whose name happened to share a suffix
  (affected simulatedAnnealing and tabuShortForm)

## Updates

- Consolidated the lavaan model syntax-building logic shared by the ACO,
  SA, and Tabu algorithms into common internal helper functions
- Added substantial unit test coverage for the top-level
  antcolony.lavaan, simulatedAnnealing, tabuShortForm, and tabu.sem
  functions
- Deprecated the shortForm argument in simulatedAnnealing; this is now
  determined automatically from maxItems

# ShortForm v0.5.8

## Bugfixes

- Fixed issue in tabuShortForm for certain parallel workflows
- Fixed bug in tabuShortForm when using multidimensional models

## Updates

- Removed dependencies on ggplot2, ggrepel, and tidyr (ACO and TS plot
  methods)
- Added some additional unit tests

=======

# ShortForm v0.5.7

## Bugfixes

- Fixed issue in ACO algorithm where the best model was not properly
  updating
- Corrected use of ggplot within the ACO plot method due to depreciated
  ggplot2 functions
- Fixed issue in SA algorithm where models including factor
  relationships or outcome variables were not specified correctly after
  the initial model

## Updates

- Modernized the README file
- Fixed CI/CD badge since Travis CI no longer works for this project

# ShortForm v0.5.6

- Updates focused on `{antcolony.lavaan}`.
  - lavaan.model.specs now defaults to the default arugments. If a user
    removes the arguments, they will be provided for them. If a user
    overwrites a specific argument (e.g., `estimator = 'wls'`), that
    will be respected.
  - Some minor adjustments to checking fitted models for specific
    warnings/errors that should result in better functioning when these
    do not exist.

# ShortForm v0.5.5

- Further updates to handle changes to `lavaan` error/warning messages
  more gracefully. These should continue into the future for the SA and
  ACo methods without additional issues.

# ShortForm v0.5.4

- Updates to handle changes to `lavaan` error/warning messages
- Fixed internal documentation to match current standards

# ShortForm v0.5.3

- Updates to antcolony.lavaan default `lavaan.model.specs`
- Spelling fixes
- Roxygen manual fixes

# ShortForm v0.5.2

## Bugfixes

- This version fixes minor bugs, most associated with CRAN messages and
  warnings

# ShortForm v0.5.0

## Introduction of S4 Function Classes

- This version (re-)introduces classes to each of the main function
  outputs using S4 methods (instead of the S3 methods present in the
  prior version)
- Each method has a `show` (print), `summary`, and `plot` method that
  provides revamped, concise information about the algorithm
- Functions have been updated to accommodate these changes

## Parallelized Short Form Functions

- Some short form functions have been modified to work with parallel
  processors, resulting in noticeably faster results particularly when
  the solution space is larger (e.g., more starting items) or with more
  complex models
  - This has resulted in some function argument changes. Please check
    any code that was written with older versions!

## Minor cleanup

- Removed some unneeded code

# ShortForm 0.4.6

## Updated argument check

- The argument check for fit statistics (ACO, SA) were updated to
  include fit statistics related to the “WLSMV” estimator (i.e, for
  ordered data).

## Bugfixes

- A bug in the SA function that sometimes resulted in improper items has
  been fixed.

- A bug in the Tabu short form function that caused the Tabu list to be
  erased if the best criterion value was reached has been fixed.

# ShortForm 0.4.5

## Extra arugment checks

- There are now additional checks for the function arguments related to
  the fit statistics (ACO, SA) and the fit statistic tests (ACO) with
  informative warnings for when the function arguments are not valid.

# ShortForm 0.4.2

## Introduction of Function Classes

- This version introduces classes to each of the main function outputs
  (`antcolony.lavaan` == “antcolony”, `simulatedAnnealing` ==
  “simulatedAnnealing”, `tabuShortForm` == “tabu”)

- This will allow for `plot` and `print` methods for each of these
  functions

## Broken functionality: antcolony\_plot

- The function `antcolony_plot` was replaced with `plot.antcolony` (aka,
  a plot method)

## New functionality: S3 method for plotting

- With the addition of classes, a plot method and accompanying
  documentation has been added.

- Future updates will expand S3 methods for `print()` and `summary()`

## Bugfixes

- Bugfixes to the main functions when using them to create shortforms of
  bifactor models.
- They should now produce actual bifactor shortforms (in 0.4.1,
  sometimes the item names would be cut off in later iterations
  *F**I**X**E**D*
  and the relationship between latent variables would be changed when
  they should have been kept constant
  *F**I**X**E**D*
  ).

## Added a package loading message

- Now, when using an interactive R session, a package message is printed
  out (with a little Penguin holding it all up)!

# ShortForm 0.4.1

## New functionality: Simulated Annealing

- The Simulated Annealing (SA) algorithm has been added to the package,
  with a single user-facing function `simulatedAnnealing()`.
- SA can be used on anything lavaan can run, though the current
  implementation focuses on traditional confirmatory models using
  `lavaan::cfa()`. However, there are plans for more user control in the
  modeling process to allow for other model defaults.

## New functionality: Tabu Search (Short Form)

- An adaptation of the Tabu search to short form creation has been
  added.

## New functionality: ACO Plots

- The `antcolony_lavaan()` function has been modified so that it no
  longer will print a `summaryfile.txt`. Rather, the function maintains
  the old summary file as an internal object and returns it after
  completion,
- The new function `antcolony_plot()` takes the results from
  `antcolony_lavaan()` and creates three graphs: (a) a plot showing how
  pheremone levels change as the algorithm progresses, (b) a plot
  showing how the mean value of the regression coefficients changes as
  the algorithm progresses, and (c) a plot showing how the mean variance
  explained changes as the algorithm progresses.

## New functionality: Bifactor Models

- Each of the short form functions utilizing lavaan
  (`antcolony.lavaan()`, `simulatedAnnealing()`, `tabuShortForm()`) are
  capable of handling bifactor models.
- In theory, this means relatively arbitrary models can be specified as
  well, but the functions utilize the “~” and “~~” operators for the
  additional functionality as well as the `bifactor` logical option. No
  guarantee that an arbitrary model will work beyond those currently
  tested.

### Minor revisions

- The lavaan-based functions all have more controlled output to the R
  console. This is most noticeable with the `antcolony.lavaan()`
  function.

# ShortForm 0.4.0

## New functionality: Tabu Search

- The Tabu search has been added to the package, with user-facing
  functions `tabu.sem()` and `search.prep()` for most of the heavy
  lifting and various helper and internal functions. The code was taken
  primarily from Carl Falk and Katerina Marcoulides (see Marcoulides, K.
  M., & Falk, C. F. (2018). Model Specification Searches in Structural
  Equation Modeling with R. Structural Equation Modeling: A
  Multidisciplinary Journal, 1-8.). These have been tested in limited
  circumstances, so please report any bugs as you find them!

## Minor changes

- NEWS.md created.
- Description file updated.
- Authorship has been updated and URLs have been added to the ant colony
  functions.
- No bugs have been found in the package thus far, but just a reminder
  for any users that bug reports are helpful and welcome.
