Metadata-Version: 2.4
Name: fapa
Version: 0.1.1
Summary: Factor Analytic Profile Analysis of Ipsatized Data
Author-email: Se-Kang Kim <se-kang.kim@bcm.edu>
License: MIT
Project-URL: Homepage, https://github.com/sekangakim/FAPA
Project-URL: CRAN, https://cran.r-project.org/package=FAPA
Project-URL: Bug Tracker, https://github.com/sekangakim/FAPA/issues
Keywords: FAPA,profile analysis,ipsatization,SVD,parallel analysis,bootstrap,Tucker congruence,BCa,psychometrics,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
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

# fapa

**Factor Analytic Profile Analysis of Ipsatized Data**

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

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

---

## Overview

FAPA is a metric inferential framework for **pattern detection and person-level
reconstruction** in multivariate profile data. After row-centering (ipsatization)
to remove profile elevation, FAPA applies SVD to recover shared core profiles
and individual pattern weights via a three-stage bootstrap verification framework.

### The FAPA workflow

1. **Ipsatization** - remove person-level elevation to isolate within-person pattern structure
2. **Core estimation** - SVD recovers core profiles, person weights, and variance decomposition
3. **Stage 1: Dimensionality** - variance-matched Horn's parallel analysis
4. **Stage 2: Subspace stability** - bootstrap principal angles (Procrustes)
5. **Stage 3: Profile replicability** - Tucker's congruence coefficients
6. **Inference** - BCa bootstrap confidence intervals for core-profile coordinates
7. **Reconstruction** - person-level R2 and pattern weights

---

## Installation

```bash
pip install fapa
```

For pandas support: `pip install "fapa[full]"`

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

---

## Quick start

```python
from fapa import (load_and_ipsatize, fapa_core, fapa_pa,
                  fapa_procrustes, fapa_tucker, fapa_bca,
                  fapa_person, print_pa, print_procrustes,
                  print_tucker, fapa_simdata)

# Step 1: Ipsatize
d = load_and_ipsatize(fapa_simdata)
Xt = d["ipsatized"]          # 500 x 22 EDI-2 matrix, row-sums = 0

# Stage 1: Parallel analysis
pa = fapa_pa(Xt, B=2000, seed=42)
print_pa(pa)
K = pa["n_retain"]           # e.g. 2

# Core estimation
fit = fapa_core(Xt, K=K)
print(f"Variance explained: {fit['cum_var'][-1]*100:.1f}%")

# Stage 2: Subspace stability
pr = fapa_procrustes(Xt, K=K, B=2000, angle_thresh=30, seed=42)
print_procrustes(pr, K_pa=K)

# Stage 3: Profile replicability
tc = fapa_tucker(Xt, K=K, B=2000, cc_thresh=0.85, seed=42)
print_tucker(tc, cc_thresh=0.85, K_pa=K)

# BCa confidence intervals
bca = fapa_bca(Xt, K=K, B=2000, alpha=0.05, seed=42)
print(bca["ci"][0].round(3))   # Core Profile 1 CI table

# Person reconstruction
person = fapa_person(Xt, fit, participants=[0, 1, 2])
print(f"Mean R2 = {person['R2_mean']:.3f}")
```

---

## Built-in dataset

`fapa_simdata` is a 500 x 22 matrix of simulated EDI-2 (Eating Disorder
Inventory-2) subscale scores, with 11 pre-treatment and 11 post-treatment
columns. The latent structure approximates two components: a normative
symptom gradient (CP1) and a pre/post treatment change contrast (CP2).

```python
from fapa import fapa_simdata, FAPA_COLS, FAPA_PRE_COLS, FAPA_POST_COLS
print(fapa_simdata.shape)    # (500, 22)
print(FAPA_PRE_COLS[:3])     # ['Before_1_Dt', 'Before_2_Bu', 'Before_3_Bd']
```

---

## R package

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

---

## Citation

Kim, S.-K. (2024). Factorization of person response profiles to identify
summative profiles carrying central response patterns.
Psychological Methods, 29(4), 723-730. doi:10.1037/met0000568

---

## License

MIT

## Author

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