% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/makeCorrAlpha.R
\name{makeCorrAlpha}
\alias{makeCorrAlpha}
\title{Correlation matrix from Cronbach's Alpha}
\usage{
makeCorrAlpha(
  items,
  alpha,
  variance = 0.1,
  alpha_noise = 0,
  diagnostics = FALSE
)
}
\arguments{
\item{items}{Integer. Number of items (>= 2).}

\item{alpha}{Numeric. Target Cronbach's alpha (0 < alpha < 1).}

\item{variance}{Numeric. Controls heterogeneity of item loadings in the
underlying one-factor model.

Larger values produce greater dispersion among item loadings, which
results in a wider spread of inter-item correlations while preserving
the requested Cronbach's alpha.

Typical guidance:
\itemize{
\item \code{0.05} — near-parallel items (very similar correlations)
\item \code{0.10} — modest heterogeneity (default)
\item \code{0.15} — strong heterogeneity
\item \code{0.20} — very strong heterogeneity
\item \code{> 0.25} — extreme dispersion; internal shrinkage may occur
}

For most applied psychometric scales (k < 20), values between
\code{0.05} and \code{0.15} produce realistic correlation structures.
Values above \code{0.30} are automatically reduced to \code{0.30} to
satisfy algorithm constraints.}

\item{alpha_noise}{Numeric. Controls random variation in the target
Cronbach's alpha before the correlation matrix is constructed.

When \code{alpha_noise = 0} (default), the requested alpha is
reproduced deterministically (subject to numerical tolerance).

When \code{alpha_noise > 0}, a small amount of random variation is
added to the requested alpha prior to constructing the matrix. This
can be useful in teaching or simulation settings where slightly
different reliability values are desired across repeated runs.

Internally, noise is added on the Fisher \emph{z}-transformed scale
to ensure the resulting alpha remains within valid bounds (0, 1).

Typical guidance:
\itemize{
\item \code{0.00} — deterministic alpha (default)
\item \code{0.02} — very small variation
\item \code{0.05} — moderate variation
\item \code{0.10} — substantial variation (caution)
}

Larger values increase the spread of achieved alpha across runs.}

\item{diagnostics}{Logical. If \code{TRUE}, returns a list containing
the matrix and diagnostic information.}
}
\value{
If \code{diagnostics = FALSE}, a positive-definite correlation matrix.
If \code{diagnostics = TRUE}, a list containing:
\itemize{
\item \code{R}: the correlation matrix
\item \code{diagnostics}: list including achieved alpha,
minimum eigenvalue, and internal variance used
}
}
\description{
Generate a Positive-Definite
Correlation Matrix for a target \emph{Cronbach's alpha}.
}
\details{
Constructs a correlation matrix with a specified number of items and
target \emph{Cronbach's alpha} using a constructive one-factor model.

Such a correlation matrix can be applied to the \code{\link[=makeScales]{makeScales()}}
function to generate synthetic data with the predefined alpha.

The algorithm directly builds a positive-definite correlation matrix
by solving for item loadings that reproduce the desired average
inter-item correlation implied by \emph{alpha}.
Unlike earlier versions of this function, this method guarantees positive
definiteness by construction, without \emph{post-hoc} repair.

The function computes the average inter-item correlation implied by the
requested alpha and solves for a one-factor loading structure that
reproduces this value. A small adaptive reduction in dispersion may be
applied when necessary to ensure a valid positive-definite solution.

The constructive generator assumes a single common factor structure,
consistent with typical psychometric scale construction.
}
\examples{

# Example 1
# define parameters
items <- 4
alpha <- 0.85

# apply function
set.seed(42)
cor_matrix <- makeCorrAlpha(
  items = items,
  alpha = alpha
)

# test function output
print(cor_matrix) |> round(3)
alpha(cor_matrix)
eigenvalues(cor_matrix, 1)

# Example 2
# higher alpha, more items, more variability
cor_matrix2 <- makeCorrAlpha(
  items = 8,
  alpha = 0.95,
  variance = 0.10
)

# test output
cor_matrix2 |> round(2)
alpha(cor_matrix2) |> round(3)
eigenvalues(cor_matrix2, 1) |> round(3)

# Example 3
# large random variation around alpha
cor_matrix3 <- makeCorrAlpha(
  items = 6,
  alpha = 0.85,
  alpha_noise = 0.10
)

# test output
cor_matrix3 |> round(2)
alpha(cor_matrix3) |> round(3)
eigenvalues(cor_matrix3, 1) |> round(3)

# Example 4
# with diagnostics
cor_matrix4 <- makeCorrAlpha(
  items = 4,
  alpha = 0.80,
  diagnostics = TRUE
)

# test output
cor_matrix4

}
