Package 'shortr'

Develop Concise but Comprehensive Shortened Versions of Psychometric Instruments

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.

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

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.
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.
algorithm	The combinatorial search algorithm. Must match either "brute.force" or "simulated.annealing". Default is "brute.force".
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 1.
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 0.999.
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 0.001.
n.runs	The number of runs in the simulated annealing search. Must be a non-null positive integer. Default is 1000.
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 NULL. Default is 5107.
verbose	Whether information messages should be printed to the console. Must match either FALSE or TRUE. Default is TRUE.

Details

Let $N$ denote the indices corresponding to the set of items comprised in the original version of a said psychometric instrument, and let $n = |N|$ denote its cardinality, with $n \in \mathbb{N}$. Let $i, j \in N$ denote arbitrary indices. Let $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 $k = |K|$ denote its cardinality, with $k \in \{1, \ldots, n-1\}$. Let $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 $A = A^\top \Leftrightarrow a_{ij} = a_{ji}$ for all $i, j \in N$. Each element $a_{ij}$ represents an association (e.g., a zero-order polychoric correlation coefficient) between the items indexed by $i$ and $j$. Let $K^c = N \setminus K$ denote the complement of $K$ in $N$, with $|K^c| = n - k$. The objective is to identify the subset of indices $K \subset N$ of cardinality $|K| = k$ that maximizes the sum of the absolute values of the associations $a_{ij}$ for all $i \in K$ and $j \in K^c$. Formally, such an identification problem is expressed as follows:

$\max_{K \subset N, |K| = k} \sum_{i \in K} \sum_{j \in K^c} |a_{ij}|$

Value

A list of two named objects pertaining to the solution to the identification problem yielded by the combinatorial search algorithm:

solution.character

A character denoting the subset of items to be comprised in the shortened version of the said psychometric instrument.

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.

References

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

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"
)

---