% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/makeItemsScale.R
\name{makeItemsScale}
\alias{makeItemsScale}
\title{Generate scale items from a summated scale, with desired Cronbach's Alpha}
\usage{
makeItemsScale(
  scale,
  lowerbound,
  upperbound,
  items,
  alpha = 0.8,
  summated = TRUE,
  progress = TRUE
)
}
\arguments{
\item{scale}{(int) a vector or dataframe of the summated rating scale.
Should range from \eqn{lowerbound \times items} to
\eqn{upperbound \times items}}

\item{lowerbound}{(int) lower bound of the scale item
(example: '1' in a '1' to '5' rating)}

\item{upperbound}{(int) upper bound of the scale item
(example: '5' in a '1' to '5' rating)}

\item{items}{(positive, int) k, or number of columns to generate}

\item{alpha}{(posiitve, real) desired \emph{Cronbach's Alpha} for the
new dataframe of items.
Default = '0.8'.}

\item{summated}{logical. If TRUE (default), \code{scale} is assumed to be a
summated scale. If FALSE, the input is treated as a mean scale and will
be multiplied by \code{items} internally.}

\item{progress}{logical. If TRUE (default is \code{interactive()}), a progress
bar is displayed during optimisation.
Set to FALSE for slightly faster execution.}
}
\value{
a dataframe with 'items' columns and 'length(scale)' rows
}
\description{
\code{makeItemsScale()} generates a random dataframe
of scale items based on a predefined summated scale
(such as created by the \code{\link[=lfast]{lfast()}} function),
and a desired \emph{Cronbach's Alpha}.
}
\details{
\subsection{simulated annealing}{

Simulated annealing is used in \code{makeItemsScale()} to search for item
configurations that satisfy several competing objectives simultaneously.
These include achieving a target Cronbach’s alpha, maintaining similar
item means, and preserving constant row sums. Because improving one
objective can worsen another, a simple greedy search often becomes
trapped in suboptimal solutions.

Simulated annealing addresses this by allowing occasional acceptance of
worse solutions early in the search, promoting exploration of the solution
space. As the algorithm progresses, a cooling schedule reduces this
randomness, increasingly favouring improvements across all criteria.
This process enables the function to converge on a balanced solution that
jointly satisfies the desired scale properties, rather than optimizing any
single objective at the expense of others.
}
}
\examples{

summatedScale <- c(16, 11, 14, 7, 10, 13, 16, 13, 12, 14, 8, 11, 8, 18, 8, 13)

newItems <- makeItemsScale(
  scale = summatedScale,
  lowerbound = 1,
  upperbound = 5,
  items = 4,
  alpha = 0.8
)

}
