Type:	Package
Title:	Aggregated Latent Space Index for Binary, Ordinal, and Continuous Data
Version:	0.2.0
Date:	2026-03-03
Description:	Provides three stability-validated pipelines for computing an Aggregated Latent Space Index (ALSI): a binary MCA pipeline (alsi_workflow()), an ordinal pipeline using homals alternating least squares optimal scaling (alsi_workflow_ordinal()), and a continuous ipsatized SVD pipeline (calsi_workflow()). All three pipelines share a common bootstrap dual-criterion stability framework (principal angles and Tucker congruence phi) for determining the number of dimensions to retain before index construction. The package is designed to complement Segmented Profile Analysis (SEPA) and is intended for psychometric scale construction and dimensional reduction in survey and clinical research.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
Imports:	homals, stats, graphics, utils
Suggests:	paran, readxl, openxlsx, testthat (≥ 3.0.0), knitr, rmarkdown, spelling
Depends:	R (≥ 4.1.0)
Language:	en-US
NeedsCompilation:	no
Packaged:	2026-03-04 00:56:11 UTC; sekangkim
Author:	Se-Kang Kim [aut, cre]
Maintainer:	Se-Kang Kim <se-kang.kim@bcm.edu>
Repository:	CRAN
Date/Publication:	2026-03-04 08:40:18 UTC

Fit homals and return person scores, stacked category scores, eigenvalues

Description

Converts ordered-factor columns to plain integers before calling homals. Passing ordered factors directly causes ALS to collapse to a trivial zero-discrimination solution (verified in homals 1.0.11).

Usage

.alsi_fit_homals(X, ndim, suppress_warnings = FALSE, itermax = 1000L)

Arguments

Value

List: Z [n x ndim], C [P x ndim], lambda [ndim], fit (raw object).

Create disjunctive (indicator) matrix from binary data

Description

Create disjunctive (indicator) matrix from binary data

Usage

.alsi_make_disjunctive(X01)

Perform Multiple Correspondence Analysis on binary indicator matrix

Description

Perform Multiple Correspondence Analysis on binary indicator matrix

Usage

.alsi_mca_indicator(Xbin01)

Arguments

Value

List containing MCA results with eigenvalues, coordinates, and masses

Read Excel file with fallback options

Description

Read Excel file with fallback options

Usage

.alsi_read_xlsx(path)

Summarize matrix columns (median and quantiles)

Description

Summarize matrix columns (median and quantiles)

Usage

.alsi_summarise_matrix(X, probs = c(0.05, 0.95))

Perform ipsatized SVD on continuous data (SEPA-style)

Description

Perform ipsatized SVD on continuous data (SEPA-style)

Usage

.alsi_svd_ipsatized(X, K = NULL)

Arguments

Value

List containing SVD results with eigenvalues, coordinates

Convert various formats to binary 0/1

Description

Convert various formats to binary 0/1

Usage

.alsi_to01(x)

ANR2: Binary Psychiatric Comorbidity Dataset

Description

A binary indicator dataset recording the presence (1) or absence (0) of nine psychiatric diagnoses for a sample of patients. The dataset is included as the primary example dataset for the binary MCA pipeline (alsi_workflow).

Usage

data(ANR2)

Format

A data frame with 13 columns:

MDD

Major Depressive Disorder (0/1)

DYS

Dysthymia (0/1)

DEP

Depressive disorder NOS (0/1)

PTSD

Post-Traumatic Stress Disorder (0/1)

OCD

Obsessive-Compulsive Disorder (0/1)

GAD

Generalized Anxiety Disorder (0/1)

ANX

Anxiety disorder NOS (0/1)

SOPH

Social Phobia (0/1)

ADHD

Attention Deficit Hyperactivity Disorder (0/1)

pre_EDI

Pre-treatment EDI score (numeric)

post_EDI

Post-treatment EDI score (numeric)

pre_bmi

Pre-treatment BMI (numeric)

post_bmi

Post-treatment BMI (numeric)

Examples

data(ANR2)
vars <- c("MDD", "DYS", "DEP", "PTSD", "OCD", "GAD", "ANX", "SOPH", "ADHD")

results <- alsi_workflow(ANR2, vars = vars, B_pa = 100, B_boot = 100)

Compute Aggregated Latent Space Index (ALSI)

Description

Calculates ALSI as a variance-weighted Euclidean norm of row principal coordinates within a retained K-dimensional MCA subspace.

Usage

alsi(Fmat, eig, K)

Arguments

Value

S3 object of class alsi containing:

Examples

# Create example data
set.seed(123)
Fmat <- matrix(rnorm(100 * 4), nrow = 100, ncol = 4)
eig <- c(0.5, 0.3, 0.15, 0.05)

# Compute ALSI
a <- alsi(Fmat, eig, K = 3)
print(a)
hist(a$alpha, main = "Distribution of ALSI")

Complete ALSI Analysis Workflow

Description

Runs a complete ALSI analysis including parallel analysis for dimensionality assessment, bootstrap stability evaluation, ALSI computation, and visualization.

Usage

alsi_workflow(
  data,
  vars,
  B_pa = 2000,
  B_boot = 2000,
  q = 0.95,
  seed = 20260123
)

Arguments

Value

List (returned invisibly) containing all analysis objects:

Examples

data(ANR2)
vars <- c("MDD", "DYS", "DEP", "PTSD", "OCD", "GAD", "ANX", "SOPH", "ADHD")
results <- alsi_workflow(
  data   = ANR2,
  vars   = vars,
  B_pa   = 100,
  B_boot = 100
)
results$pa
results$boot
results$alsi

Ordinal ALSI pipeline via homals ALS optimal scaling

Description

Runs the four-stage ordinal ALSI pipeline:

1. Permutation parallel analysis (column-wise shuffle preserves marginals, destroys inter-item structure) determines K_PA.

2. Reference homals fit followed by varimax rotation on the stacked category score matrix (the loading analogue in homogeneity analysis). The same rotation matrix is applied to person scores.

3. Bootstrap dual-criterion stability. For each resample, homals is refitted and the category score matrix is Procrustes-aligned to the reference. Principal angle and Tucker congruence phi are computed on the same post-Procrustes matrix. K* is the largest k where ALL dimensions 1..k satisfy BOTH criteria simultaneously.

4. Eigenvalue-weighted linear ALSI index from K* retained rotated person scores (result can be negative; z-standardized version also returned).

Usage

alsi_workflow_ordinal(
  data,
  items,
  reversed_items = character(0L),
  scale_min = 1L,
  scale_max = 5L,
  n_permutations = 100L,
  pa_percentile = 95,
  B_boot = 1000L,
  angle_threshold_deg = 20,
  tucker_threshold = 0.85,
  seed = 12345L,
  itermax = 1000L,
  verbose = TRUE
)

Arguments

Value

An S3 object of class "alsi_ordinal" with components:

ALSI_index

Numeric vector (n). Raw eigenvalue-weighted linear composite. Can be negative.

ALSI_z

Numeric vector (n). Z-standardized ALSI.

K_PA

Integer. Dimensions retained by parallel analysis.

K_star

Integer. Final model order after dual-criterion selection.

Z_ref

Matrix n x K_PA. Varimax-rotated person scores.

C_ref

Matrix P x K_PA. Varimax-rotated stacked category scores.

lambda_rot

Numeric vector (K_PA). Eigenvalues (invariant to varimax rotation).

stability_table

Data frame. Per-dimension stability metrics (eigenvalue, angle, Tucker phi, pass/fail, grade).

pa_table

Data frame. Parallel analysis results per dimension.

n_skipped

Integer. Bootstrap replicates discarded due to non-convergence or degenerate resamples.

call

The matched call.

References

de Leeuw, J., & Mair, P. (2009). Gifi methods for optimal scaling in R: The package homals. Journal of Statistical Software, 31(4), 1-21.

Gifi, A. (1990). Nonlinear multivariate analysis. Wiley.

Lorenzo-Seva, U., & ten Berge, J. M. F. (2006). Tucker's congruence coefficient as a meaningful index of factor similarity. Methodology, 2, 57-64.

Takane, Y., Young, F. W., & de Leeuw, J. (1977). Nonmetric individual differences multidimensional scaling: An alternating least squares method with optimal scaling features. Psychometrika, 42, 7-67.

Compute Continuous Aggregated Latent Space Index (cALSI)

Description

Calculates cALSI as a variance-weighted Euclidean norm of row coordinates within a retained K-dimensional ipsatized SVD subspace.

Usage

calsi(F, eig, K)

Arguments

Value

S3 object of class calsi containing:

Demonstrate what cALSI adds beyond SEPA

Description

Demonstrate what cALSI adds beyond SEPA

Usage

calsi_vs_sepa_demo(data, K = 4, B_boot = 2000, seed = 20260206)

Arguments

Value

List with comparison results

Complete cALSI Workflow for Continuous Data

Description

Integrates parallel analysis, bootstrap stability, and cALSI computation.

Usage

calsi_workflow(
  data,
  B_pa = 2000,
  B_boot = 2000,
  q = 0.95,
  seed = 20260206,
  K_override = NULL
)

Arguments

Value

List containing all analysis objects

Compare SEPA plane-wise summaries with cALSI

Description

Compare SEPA plane-wise summaries with cALSI

Usage

compare_sepa_calsi(fit, K, target_ids = NULL)

Arguments

Value

Data frame comparing SEPA and cALSI person-level indices

Align MCA solution via Procrustes rotation with sign anchoring

Description

Performs orthogonal Procrustes rotation to align a set of category coordinates to a reference solution, then applies sign correction to maximize agreement with the reference on each dimension.

Usage

mca_align(G, Gref)

Arguments

Value

List containing:

Examples

# Create example matrices
set.seed(123)
Gref <- matrix(rnorm(20), nrow = 10, ncol = 2)
G <- Gref %*% matrix(c(0.8, 0.6, -0.6, 0.8), 2, 2)

# Align G to Gref
aligned <- mca_align(G, Gref)
print(aligned$G_aligned)

Bootstrap-Based Subspace Stability Assessment

Description

Evaluates reproducibility of retained MCA dimensions via bootstrap resampling. Quantifies stability using Procrustes principal angles (subspace-level) and Tucker's congruence coefficients (dimension-level).

Usage

mca_bootstrap(data, vars, K, B = 2000, seed = 20260123, verbose = TRUE)

Arguments

Value

S3 object of class mca_bootstrap containing:

Examples

# Using included ANR2 dataset
data(ANR2)
vars <- c("MDD", "DYS", "DEP", "PTSD", "OCD", "GAD", "ANX", "SOPH", "ADHD")
boot <- mca_bootstrap(ANR2, vars = vars, K = 3, B = 100)
print(boot)

Parallel Analysis for MCA Dimensionality Assessment

Description

Compares observed MCA eigenvalues against reference distributions from permuted data to identify statistically meaningful dimensions.

Usage

mca_pa(
  data,
  vars,
  B = 2000,
  q = 0.95,
  seed = 20260123,
  max_dims = 20,
  verbose = TRUE
)

Arguments

Value

S3 object of class mca_pa containing:

Examples

# Using included ANR2 dataset
data(ANR2)
vars <- c("MDD", "DYS", "DEP", "PTSD", "OCD", "GAD", "ANX", "SOPH", "ADHD")
pa <- mca_pa(ANR2, vars = vars, B = 100)
print(pa$K_star)

Plot Category Projections in MCA Space

Description

Visualizes category coordinates in a 2D MCA subspace and optionally displays projections onto the aggregated ALSI direction.

Usage

plot_category_projections(
  fit,
  K,
  alpha_vec = NULL,
  dim_pair = c(1, 2),
  cex = 0.8,
  top_n = 15
)

Arguments

Value

No return value, called for side effects. The function creates a scatter plot of category coordinates in the specified 2D subspace, with category labels displayed. If alpha_vec is provided, it also prints the top categories ranked by their absolute projection onto the ALSI direction to the console.

Examples

data(ANR2)
vars <- c("MDD", "DYS", "DEP", "PTSD", "OCD", "GAD", "ANX", "SOPH", "ADHD")
pa <- mca_pa(ANR2, vars = vars, B = 100, verbose = FALSE)
fit <- pa$fit
plot_category_projections(fit, K = pa$K_star)

Plot Domain Loadings in SVD Space

Description

Visualizes domain loadings in a 2D subspace (biplot-style).

Usage

plot_domain_loadings(fit, dim_pair = c(1, 2), cex = 1)

Arguments

Plot Subspace Stability Diagnostics

Description

Creates diagnostic plots showing distributions of principal angles and Tucker congruence coefficients across bootstrap resamples.

Usage

plot_subspace_stability(boot_obj)

Arguments

Value

No return value, called for side effects. The function creates a two-panel figure with: (1) boxplots of principal angles (left panel), showing the distribution of subspace similarity across bootstrap resamples for each dimension; and (2) boxplots of Tucker congruence coefficients (right panel), showing dimension-level replicability with reference lines at phi = 0.85 (good) and phi = 0.95 (excellent).

Examples

data(ANR2)
vars <- c("MDD", "DYS", "DEP", "PTSD", "OCD", "GAD", "ANX", "SOPH", "ADHD")
boot <- mca_bootstrap(ANR2, vars = vars, K = 3, B = 100)
plot_subspace_stability(boot)

Plot Subspace Stability Diagnostics for Continuous Data

Description

Plot Subspace Stability Diagnostics for Continuous Data

Usage

plot_subspace_stability_cont(boot_obj)

Arguments

Align SVD solution via Procrustes rotation with sign anchoring

Description

Align SVD solution via Procrustes rotation with sign anchoring

Usage

svd_align(B, Bref)

Arguments

Value

List with aligned coordinates and rotation matrix

Bootstrap-Based Subspace Stability Assessment for Ipsatized SVD

Description

Evaluates reproducibility of retained dimensions via bootstrap resampling. Uses Procrustes principal angles (subspace-level) and Tucker's congruence coefficients (dimension-level).

Usage

svd_bootstrap(data, K, B = 2000, seed = 20260206, verbose = TRUE)

Arguments

Value

S3 object of class svd_bootstrap

Parallel Analysis for Ipsatized SVD Dimensionality Assessment

Description

Uses the paran package (Horn's parallel analysis with Longman-Allen-Chabassol bias adjustment) for dimensionality assessment, ensuring compatibility with SEPA methodology. Falls back to a built-in method if paran is unavailable.

Usage

svd_pa(data, B = 2000, q = 0.95, seed = 20260206, graph = TRUE, verbose = TRUE)

Arguments

Details

This function primarily uses the paran package, which implements Horn's parallel analysis with the bias adjustment described in Longman, Cota, Holden, & Fekken (1989). This is the same method used in SEPA.

The paran package should be installed: install.packages("paran")

Value

S3 object of class svd_pa containing: