# LikertMakeR (development version)

# LikertMakeR 2.0.0 (March 2026)

This release introduces major improvements to the internal algorithms used
to generate synthetic rating-scale data and correlation matrices.

## Breaking changes

  - `makeItemsScale()` has been rewritten and one parameter has been removed. 
  Existing code that used the removed argument, `variance`, 
  will need to be updated.

  - `makeCorrAlpha()` has been completely redesigned - previously flagged in 
  `development version 1.5.0`.
  Some parameters have changed, and the internal algorithm for generating 
  correlation matrices has been replaced to guarantee an assumed underlying 
  single-factor structure.

## New features

  - Added `reliability()`, a new function for computing reliability statistics 
  for rating-scale data - previously flagged in `development version 1.5.0`.
  
  - Added `alpha_sensitivity()`, a new function that computes how 
  Cronbach's alpha changes as a function of scale design parameters.

## Improvements

  - `makeCorrAlpha()` is now substantially faster and more stable when 
  generating correlation matrices that satisfy a target Cronbach's alpha.
  
  - `alpha()` has additional integrity checks

  - Improved numerical stability and diagnostics in correlation-matrix 
  generation.

  - Various documentation improvements and code cleanup.



# LikertMakeR 1.5.0 (February 2026)

## Improvements

### Major Improvements to `makeCorrAlpha()`

#### New constructive correlation generator

`makeCorrAlpha()` has been completely re-engineered. The previous swap-based approach for achieving positive-definite correlation matrices has been replaced with a constructive one-factor generator.

The previous algorithm:

- was slow
- was unable to process large number of items (rare, but sometimes wanted)
- frequently gave results that were more consistent with multi-factor scales
   * e.g., eigenvalues may give two or more values > 1, 


The new algorithm:

- runs more than 150 times faster than the previous version (3000 times faster for large k).
- Guarantees positive definiteness without post-hoc repair.
- Produces stable behaviour across large numbers of items (tested up to k = 40).
- Maintains alpha accuracy within ±0.005 when `alpha_noise = 0`.
- Uses adaptive dispersion control to ensure feasibility at high variance levels.

This results in substantially improved numerical stability and smoother behaviour across the parameter space.


#### `precision` argument removed and replaced with `alpha_noise` argument

A new argument, `alpha_noise`, has been introduced to provide optional random variation around the requested Cronbach’s alpha. 

By default (alpha_noise = 0), the function reproduces the specified alpha deterministically. 
When a small positive value is supplied, the function will generate slightly different reliability values across runs. 

This is particularly useful in teaching and simulation contexts where you may wish to demonstrate natural variation rather than produce the exact same matrix each time. The noise is applied in a way that ensures the resulting alpha always remains within valid bounds.


#### Deprecated argument

- `sort_cors` is now deprecated. It served no useful purpose.


#### Backward compatibility

For most use cases, behaviour remains consistent with previous versions. 
However, users who relied on the previous swap-based construction may observe smoother and more stable correlation structures under the new implementation.

### `summated` parameter added to `makeItemsScale()` function

Added to specify whether the given scale is a summated scale (e.g. 4-20 in integer increments for four 5-point items) or an averaged scale (e.g., 1-5 in 0.25 increments). 

## Maintenance

- Tutorials added to the website

  * infographic to be removed from CRAN
  
  * blog_01 (quick-start tutorial) generates a dataframe.
  
  * blog_2 (t-test tutorial) "reproduces"" published data, runs t-test, effect-sizes, and visualisation. 

---

# LikertMakeR 1.4.0 (February 2026)

## Improvements

- New `reliability()` function:
  Calculates various reliability statistics:
  
  - Cronbach's alpha ($\alpha$)
  
  - McDonald's omega-total ($\omega_t$)
  
  - Guttman's lambda 6 ($\lambda 6$)
  
  - Zumbo's ordinal alpha (Cronbach's alpha from polychoric correlations)
  
  - ordinal-omega-total (McDonald's omega total from polychoric correlations)
  
  - coefficient H
  
  with bootstrapped Confidence Intervals for each as an option.

- correlateScales() function runs 3 to 8 times faster

  - due to some pre-calculation and vectorisation replacing "for loops"

  
## Maintenance

- Fixed typos and simplified examples.

- removed redundant `makeItems()` function

- reduced length of **README** file and moved most content to vignettes





# LikertMakeR 1.3.0 (2025-11-24)

## Improvements

- New `makeScalesRegression()` function: 
   Generates synthetic rating-scale data that replicates reported regression
   results, and then returns 
   
   1. a data frame that provides the requested statistical properties and
   
   2. a correlation matrix and summary moments of the data frame, plus
   
   3. diagnostic statistics, including comparison of target values against 
      achieved values. 
      
- `makeScales()` function replaces `makeItems()` function:
    
   - I finally worked out how to turn a single value into a vector of 
    length `k`. 
   - Embarrassingly straightforward.
    
- Updated version of `makeCorrAlpha()` function produces a more 
  "natural-looking" correlation matrix, plus diagnostics:

   - previous version sorted correlations in the correlation matrix to improve 
     likelihood of extracting a positive-definite matrix. 
     Fast, but unnatural results.
   - I have applied a slightly faster algorithm for rearranging the correlations 
     in a draft matrix to produce one that is positive-definite.   
   - Additional parameter `sort_cors = FALSE`. 
     If `TRUE`, results are similar to the earlier version of `makeCorrAlpha()`.
     A little faster but not as "natural-looking".
   - Additional parameter `diagnostics = FALSE`.
     If `TRUE`, returns a list containing the correlation matrix and a 
     diagnostics list (target/achieved alpha, average inter-item correlation, 
     eigenvalues, PD flag, and key arguments).
     If `FALSE` (default), returns the correlation matrix only. 
     
- Updated version of `lfast()` function

   - runs slightly faster
   
   

## Maintenance

- new vignette for the new function `makeScalesRegression()`.

- updated examples for `makeScales()` function.

- updated badges in readme file.



# LikertMakeR 1.2.0 (2025-10-10)

## Improvements

- New `makeRepeated()` function : 
   takes summary statistics that are reported in a typical repeated-measures 
   ANOVA study, and then returns 
   
   1. a correlation matrix of the vectors of repeated measures and
   
   2. a data frame based on the correlation matrix and summary moments, plus
   
   3. diagnostic statistics, including possible F-statistics based on information provided. 
   
- #lfast_validation# vignette shows that #LikertMaker# does a remarkably good 
   job of replicating real rating-scale data.


## Maintenance

- Vignettes are too large with so many images, so CRAN files include only 
the #LikertMakeR_vignette# file. Two vignettes that validate `lfast()` 
and `makeCorrLoadings()` appear only in the package website.




# LikertMakeR 1.1.0 (2025-05-26)

## Improvements

- new `makePaired()` function:
  takes summary statistics from a paired-sample t-test and produces a data frame of rating-scale data that would deliver such summary statistics

- `lcor()` function rewrite: 
    previous version used a very systematic swapping of values in each column to minimise the difference between data correlation and a target correlation matrix. This algorithm had the effect of causing extreme values in each column to be highly-correlated (or lowly correlated as applicable), and leaving middle-values relatively uncorrelated. This property was probably not noticeable in most cases but was apparent when the range of scale values was great.

## Maintenance

- Vignettes minor updates.


# LikertMakeR 1.0.2 (2025-04-25)

## Improvements

- Some test examples updated.

## Maintenance

- Vignettes updated.

# LikertMakeR 1.0.1 (2025-04-07)

## Improvements

- Vignettes are now properly registered and included in the build.
- Improved documentation: two vignettes now illustrate package usage:
  - `LikertMakeR vignette`
  - `makeCorrLoadings validation`
- Updated `DESCRIPTION` metadata to comply with CRAN requirements.

## Maintenance

- Switched vignette engine to `knitr::rmarkdown` for better compatibility with CRAN and development tools.

# LikertMakeR 1.0.0 (2025-04-03)

## makeCorrLoadings() function added

makeCorrLoadings() generates a correlation matrix of
inter-item correlations based on item factor loadings as might be seen in
_Exploratory Factor Analysis_ (**EFA**) or a _Structural Equation Model_
(**SEM**).

Such a correlation matrix can be applied to the \code{makeItems()}
function to generate synthetic data with those predefined factor structures.


# LikertMakeR 1.0.0 (2025-01-08)

## update version number to correct major.minor.patch format

No update from V 0.4.5.

This will be the new numbered for submission to CRAN


# LikertMakeR 0.4.5 (2025-01-07)

## makePaired() function added

_makePaired()_ generates a dataframe of two paired vectors to emulate data 
for a paired-sample t-test


# LikertMakeR 0.4.0 (2024-11-17)

## target Cronbach's Alpha added to makeItemsScale() function 

generated scale items now defined by a target Cronbach's Alpha, 
as well as by variance within each scale item.
This latest version adds a little randomness to the selection of 
candidate row vectors.



# LikertMakeR 0.3.0 (2024-05-18)

## more randomness in swaps task to makeCorrAlpha() function

correlation matrix usually has values sorted lowest to highest. This happens less often 



# LikertMakeR 0.2.6 (2024-05-11)

## added 'precision' parameter to makeCorrAlpha() function

'precision' adds random variation around the target Cronbach's Alpha. Default = '0' (no variation giving Alpha exact to two decimal places)




# LikertMakeR 0.2.5 (2024-04-20)

## added correlateScales() function

Create a dataframe of correlated scales  from different dataframes of scale items



# LikertMakeR 0.2.2 (2024-03-31)

## added makeItemsScale() function

Generate rating-scale items from a given summated scale




# LikertMakeR 0.2.0 (2024-03-02)

## For submission to CRAN

Faster and more accurate functions: **_lcor()_** & **_lfast()_**

These replace the old **_lcor()_** & **_lfast()_** with the previous **_lcor_C()_** & **_lfast_R()_**


# LikertMakeR 0.1.9 (2024-02-11)

### Added a new functions: **_makeCorrAlpha()_**, **_makeItems()_**, _alpha()_, _eigenvalues()_

 * _makeCorrAlpha()_ constructs a random correlation matrix of given 
  dimensions and predefined Cronbach's Alpha. 

 * _makeItems()_ generates synthetic rating-scale data with predefined 
  first and second moments and a predefined correlation matrix

 * _alpha()_ calculate Cronbach's Alpha from a given correlation matrix
  or a given dataframe
  
 * _eigenvalues()_ calculates eigenvalues of a correlation matrix with 
  an optional scree plot  


# LikertMakeR 0.1.7 (2024-02-02)

### Added a new function: **_lcor_C()_**

* _lcor_C()_ is a C++ implementation of the _lcor()_ function. 
It should run considerably faster than _lcor()_.
When I'm confident that _lcor_C()_ works as well or better 
than _lcor()_, then I shall replace _lcor()_ with the C++ 
implementation in an update to CRAN. 



# LikertMakeR 0.1.6 (2024-01-18)

* Made code and examples more tidy - this makes code a few nanoseconds faster

* Added some further in-line comments. 

* setting up for some C++ mods to make lcor() faster, and to introduce make_items() function.




# LikertMakeR 0.1.5 (2022-12-20)

### Initial CRAN release

* Added references to DESCRIPTION file and expanded citations to vignettes

* Reduced runtime by setting target to zero instead of -Inf. 

* Specified one thread instead of attempting Parallel




