Metadata-Version: 2.4
Name: alsi-kim
Version: 0.1.0
Summary: Aggregated Latent Space Index for Binary, Ordinal, and Continuous Data
Author-email: Se-Kang Kim <se-kang.kim@bcm.edu>
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/sekangakim/alsi
Project-URL: CRAN, https://cran.r-project.org/package=alsi
Project-URL: Bug Tracker, https://github.com/sekangakim/alsi/issues
Keywords: ALSI,cALSI,MCA,multiple correspondence analysis,parallel analysis,bootstrap,Tucker congruence,psychometrics,dimensionality reduction,person-level index,clinical,biomedical
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: full
Requires-Dist: pandas>=2.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pandas>=2.0; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# alsi

**Aggregated Latent Space Index for Binary, Ordinal, and Continuous Data**

Python port of the [R alsi package](https://cran.r-project.org/package=alsi) (CRAN, Kim 2026).

[![PyPI](https://img.shields.io/pypi/v/alsi)](https://pypi.org/project/alsi/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Tests](https://img.shields.io/badge/tests-65%20passing-brightgreen)]()
[![CRAN](https://img.shields.io/badge/R%20package-CRAN-276DC3)](https://cran.r-project.org/package=alsi)

---

## Overview

Multivariate data in behavioral and clinical research frequently exhibit
**dimensional multiplicity** - association structure that distributes across
several non-trivial dimensions rather than concentrating in one. The
**Aggregated Latent Space Index (ALSI)** collapses this structure into a
single, stability-validated person-level scalar via three automatic stages:

1. **Parallel analysis** (Horn 1965) - how many dimensions exceed chance?
2. **Bootstrap Procrustes stability** - dual criterion: principal angle < 20 deg AND Tucker phi >= 0.85
3. **Variance-weighted aggregation**: alpha_i = sqrt(sum_k w_k * f_ik^2)

Three complete pipelines cover every common data type:

| Pipeline | Data type | Method | Index |
|---|---|---|---|
| `alsi_workflow()` | Binary (0/1) | Multiple Correspondence Analysis | ALSI (non-negative) |
| `alsi_workflow_ordinal()` | Likert / ordinal | ALS optimal scaling | Ordinal ALSI (signed) |
| `calsi_workflow()` | Continuous | Ipsatized SVD | cALSI (non-negative) |

---

## Installation

```bash
pip install alsi
```

Requirements: Python >= 3.9, numpy >= 1.24, scipy >= 1.10

---

## Quick start

### Continuous data (cALSI)

```python
from alsi import calsi_workflow, wawm4, WAWM4_DOMAINS

result = calsi_workflow(
    wawm4,
    B_pa=2000, B_boot=2000, q=0.95,
    seed=20260206,
    domains=WAWM4_DOMAINS,
)
print(result.summary())
```

### Binary data (ALSI)

```python
from alsi import alsi_workflow, ANR2, ANR2_VARS

result = alsi_workflow(
    ANR2, vars=ANR2_VARS,
    B_pa=2000, B_boot=2000,
    seed=20260123,
)
print(result.summary())
```

### Ordinal data (Ordinal ALSI)

```python
from alsi import alsi_workflow_ordinal, BFI_Extraversion, BFI_ITEMS, BFI_REVERSED_ITEMS

result = alsi_workflow_ordinal(
    BFI_Extraversion,
    items=BFI_ITEMS,
    reversed_items=BFI_REVERSED_ITEMS,
    scale_min=1, scale_max=5,
    n_permutations=100, B_boot=1000,
    seed=12345,
)
print(result.summary())
```

---

## Result fields (consistent across all three pipelines)

```python
result.alphas      # (n,) person-level ALSI values - the main output
result.F           # (n, K*) person coordinates in the retained subspace
result.weights     # (K*,) variance weights w_k = lambda_k / sum(lambda_j)
result.K_PA        # dimensions retained by parallel analysis
result.K_star      # dimensions passing dual stability criterion
result.stability   # full bootstrap Procrustes diagnostics dict
result.summary()   # formatted text summary
```

---

## Lower-level functions

All lower-level functions from the R package are also available:

```python
from alsi import (
    mca_pa,         # parallel analysis for MCA
    mca_bootstrap,  # bootstrap stability for MCA
    mca_align,      # Procrustes alignment for category coordinates
    svd_pa,         # parallel analysis for ipsatized SVD
    svd_bootstrap,  # bootstrap stability for SVD
    svd_align,      # Procrustes alignment for domain loadings
)
```

---

## Built-in datasets

| Name | Shape | Pipeline | Description |
|---|---|---|---|
| `ANR2` | 1261 x 13 | Binary | Psychiatric diagnostic indicators + EDI/BMI outcomes |
| `BFI_Extraversion` | 500 x 10 | Ordinal | Big Five Inventory Extraversion items (Likert 1-5) |
| `wawm4` | 900 x 9 | Continuous | WAIS-IV / WMS-IV cognitive domain scores |

```python
from alsi import ANR2, ANR2_VARS   # ANR2_VARS = the 9 binary columns
from alsi import BFI_Extraversion, BFI_ITEMS, BFI_REVERSED_ITEMS
from alsi import wawm4, WAWM4_DOMAINS
```

---

## R package

CRAN: https://cran.r-project.org/package=alsi
GitHub: https://github.com/sekangakim/alsi

---

## Citation

Kim, S.-K. (2026). *The Aggregated Latent Space Index: A stability-validated
framework for person-level aggregation across binary, ordinal, and continuous
data*. Manuscript submitted for publication.

Kim, S.-K. (2026). *alsi: Aggregated Latent Space Index* (v0.1.0) [Python package].
PyPI. https://pypi.org/project/alsi/

---

## License

GPL-3.0

## Author

Se-Kang Kim, Ph.D.
Psychology Division, Department of Pediatrics
Baylor College of Medicine / Texas Children's Hospital
ORCID: 0000-0003-0928-3396
se-kang.kim@bcm.edu
