% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/shortr.R
\encoding{UTF-8}
\name{shortr}
\alias{shortr}
\title{Develop Concise but Comprehensive Shortened Versions of Psychometric Instruments}
\usage{
shortr(
  n.mat,
  k,
  algorithm = base::c("brute.force", "simulated.annealing"),
  start.temp = 1,
  cool.fact = 0.999,
  stop.temp = 0.001,
  n.runs = 1000,
  seed = 5107,
  verbose = TRUE
)
}
\arguments{
\item{n.mat}{The symmetric matrix of associations (e.g., of zero-order polychoric correlation coefficients) computed from the set of items comprised in the original version of the said psychometric instrument. Must be a symmetric matrix of numeric.}

\item{k}{The number of items in the subset of items to be comprised in the shortened version of the said psychometric instrument. Must be a non-null positive integer.}

\item{algorithm}{The combinatorial search algorithm. Must match either \code{"brute.force"} or \code{"simulated.annealing"}. Default is \code{"brute.force"}.}

\item{start.temp}{The starting temperature in the simulated annealing search. Must be a non-null positive numeric lying within the interval (0, 1], and must be greater than stop.temp, the stopping temperature. Default is \code{1}.}

\item{cool.fact}{The cooling factor in the simulated annealing search. Must be a non-null positive numeric lying within the interval (0, 1). Default is \code{0.999}.}

\item{stop.temp}{The stopping temperature in the simulated annealing search. Must be a non-null positive numeric lying within the interval (0, 1), and must be less than start.temp, the starting temperature. Default is \code{0.001}.}

\item{n.runs}{The number of runs in the simulated annealing search. Must be a non-null positive integer. Default is \code{1000}.}

\item{seed}{The random number generator state for random number generation in the simulated annealing search. Must be a non-null positive integer or must match \code{NULL}. Default is \code{5107}.}

\item{verbose}{Whether information messages should be printed to the console. Must match either \code{FALSE} or \code{TRUE}. Default is \code{TRUE}.}
}
\value{
A list of two named objects pertaining to the solution to the identification problem yielded by the combinatorial search algorithm:
\describe{
\item{\strong{solution.character}}{A character denoting the subset of items to be comprised in the shortened version of the said psychometric instrument.}
\item{\strong{solution.numeric}}{A numeric denoting the sum of the absolute values of the associations between the subset of items to be comprised in the shortened version of the said psychometric instrument and the subset of items not to be comprised in the shortened version of the said psychometric instrument.}
}
}
\description{
Operationalizes the identification problem of which subset of items should be kept in the shortened version of a said psychometric instrument to best represent the set of items comprised in the original version of the said psychometric instrument.
}
\details{
Let \eqn{N} denote the indices corresponding to the set of items comprised in the original version of a said psychometric instrument, and let \eqn{n = |N|} denote its cardinality, with \eqn{n \in \mathbb{N}}. Let \eqn{i, j \in N} denote arbitrary indices. Let \eqn{K \subset N} denote the indices corresponding to the subset of items to be comprised in the shortened version of the said psychometric instrument, and let \eqn{k = |K|} denote its cardinality, with \eqn{k \in \{1, \ldots, n-1\}}. Let \eqn{A = (a_{ij}) \in \mathbb{R}^{n \times n}} denote a symmetric matrix of associations (e.g., of zero-order polychoric correlation coefficients) computed from the set of items comprised in the original version of the said psychometric instrument, satisfying \eqn{A = A^\top \Leftrightarrow a_{ij} = a_{ji}} for all \eqn{i, j \in N}. Each element \eqn{a_{ij}} represents an association (e.g., a zero-order polychoric correlation coefficient) between the items indexed by \eqn{i} and \eqn{j}. Let \eqn{K^c = N \setminus K} denote the complement of \eqn{K} in \eqn{N}, with \eqn{|K^c| = n - k}. The objective is to identify the subset of indices \eqn{K \subset N} of cardinality \eqn{|K| = k} that maximizes the sum of the absolute values of the associations \eqn{a_{ij}} for all \eqn{i \in K} and \eqn{j \in K^c}. Formally, such an identification problem is expressed as follows:\cr\cr
\deqn{\max_{K \subset N, |K| = k} \sum_{i \in K} \sum_{j \in K^c} |a_{ij}|}
}
\examples{
n.mat <- (
  stats::runif(n = 25^2, min = -1, max = 1) |>
  base::matrix(nrow = 25, ncol = 25) |>
  (\(m) (m + base::t(m)) / 2)() |>
  (\(m) {base::diag(m) <- 0; m})()
)

shortr::shortr(
  n.mat = n.mat,
  k = 5,
  algorithm = "brute.force"
)

}
\references{
Fournier, L., Heeren, A., Baggio, S., Clark, L., Verdejo-García, A., Perales, J. C., & Billieux, J. (2026). \emph{shortr: Develop concise but comprehensive shortened versions of psychometric instruments} (\emph{R} package version 1.0.3) [Computer software]. \doi{10.32614/CRAN.package.shortr}
}
