Metadata-Version: 2.4
Name: pams-kim
Version: 0.1.0
Summary: Profile Analysis via Multidimensional Scaling
Author: Donghoh Kim
Author-email: Se-Kang Kim <se-kang.kim@bcm.edu>
License: MIT
Project-URL: Homepage, https://github.com/sekangakim/pams
Project-URL: CRAN, https://cran.r-project.org/package=pams
Keywords: PAMS,profile analysis,MDS,SMACOF,ipsatization,bootstrap,BCa,psychometrics,longitudinal,clinical
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
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.
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
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"
Dynamic: license-file

# pams-kim

**Profile Analysis via Multidimensional Scaling (PAMS)**

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

[![PyPI](https://img.shields.io/pypi/v/pams-kim)](https://pypi.org/project/pams-kim/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-41%20passing-brightgreen)]()
[![CRAN](https://img.shields.io/badge/R%20package-CRAN-276DC3)](https://cran.r-project.org/package=pams)

---

## Overview

PAMS identifies population-level core response profiles from cross-sectional
or longitudinal person-score data using nonmetric multidimensional scaling
(SMACOF algorithm). Each person profile is decomposed into:

- **Level component**: person mean across subscales
- **Pattern component**: ipsatized subscores (within-person variation)

PAMS fits a nonmetric MDS solution to the J x J inter-variable distance matrix,
bootstraps the solution to generate empirical sampling distributions, and
computes BCa confidence intervals for each core profile coordinate.

**Key features:**
- Nonmetric MDS via SMACOF (de Leeuw & Mair, 2009) or classical metric MDS
- BCa bootstrap CIs for core profile coordinates
- Person-level weights, R-squared, and profile correlations
- Optional individual bootstrap CIs for selected participants
- Longitudinal support (time-ordered subscale columns)

References: Kim & Kim (2024) doi:10.20982/tqmp.20.3.p230

---

## Installation

pip install pams-kim

Requirements: Python >= 3.9, numpy >= 1.24, scipy >= 1.10, scikit-learn >= 1.3

---

## Quick start

```python
import numpy as np
from pams import BootSmacof

# Toy example (matches R PAMS documentation)
rng = np.random.default_rng(42)
toy_data = rng.normal(10, 2, (50, 5))

result = BootSmacof(
    testdata    = toy_data,
    participant = [0, 1, 2],   # row indices for individual CIs
    mds         = "smacof",
    type        = "ordinal",
    distance    = "euclid",
    nprofile    = 2,
    direction   = [1, 1],
    cl          = 0.95,
    nBoot       = 2000,
    testname    = ["S1", "S2", "S3", "S4", "S5"],
)

print(f"Stress: {result['MDS']['stress']:.4f}")
print(f"Mean R2: {result['WeightmeanR2']:.3f}")
print(result["MDSsummary"][0].round(3))  # Core Profile 1 with BCa CIs
```

---

## Output fields

result["MDS"]            # dict with conf (J x K) and stress
result["MDSsummary"]     # list of K DataFrames -- BCa CIs per core profile
result["MDSprofile"]     # list of K arrays (nBoot, J) -- bootstrap distributions
result["stresssummary"]  # one-row DataFrame of bootstrap stress
result["MDSR2"]          # (K,) R² confirming non-collinearity of core profiles
result["Weight"]         # (n, 2K+2) person weights, level, R², correlations
result["WeightmeanR2"]   # mean person R² across all persons
result["WeightB"]        # bootstrap weight summary for participants
result["PcorrB"]         # bootstrap partial correlations for participants

---

## Lower-level functions

```python
from pams import (
    intervar_distance,  # J x J inter-variable distance matrix
    smacof_mds,         # SMACOF nonmetric MDS
    classical_mds,      # Torgerson classical metric MDS
    apply_direction,    # sign flipping for core profiles
)
```

---

## R package

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

---

## Citation

Kim, S.-K., & Kim, D. (2024). Utility of profile analysis via multidimensional
scaling in R for the study of person response profiles in cross-sectional and
longitudinal data. The Quantitative Methods for Psychology, 20(3), 230-247.
doi:10.20982/tqmp.20.3.p230

---

## License

MIT

## Authors

Se-Kang Kim, Ph.D. -- se-kang.kim@bcm.edu
Baylor College of Medicine / Texas Children's Hospital

Donghoh Kim, Ph.D.
