Metadata-Version: 2.4
Name: archepy
Version: 0.1.0
Summary: Multi-Subject Archetypal Analysis (MS-AA) for fMRI data, in Python.
Project-URL: Homepage, https://github.com/the-brAIn-lab/archepy
Project-URL: Repository, https://github.com/the-brAIn-lab/archepy
Project-URL: Upstream MATLAB toolbox, https://github.com/JesperLH/Multisubject-Archetypal-Analysis
Project-URL: Original paper, https://doi.org/10.1109/JSTSP.2016.2595103
Author-email: Alex Shepherd <13ashepherd@gmail.com>
License: ================================================================================
        ArchePy — Python port of the Multisubject Archetypal Analysis Toolbox
        ================================================================================
        
        This package (ArchePy) is a Python translation of the MATLAB "Multisubject
        Archetypal Analysis Toolbox" originally developed at the Technical University
        of Denmark (DTU). The Python port is a derivative work and is distributed
        under the same terms as the original toolbox: ACADEMIC AND NON-PROFIT USE
        ONLY. Commercial use requires a separate license from DTU.
        
        Python port copyright (C) 2026 [Alex Shepherd].
        Distributed under the terms of the Multisubject Archetypal Analysis Toolbox
        Software License Agreement, reproduced in full below.
        
        The original MATLAB toolbox is available at:
          https://github.com/JesperLH/Multisubject-Archetypal-Analysis
        
        The original paper is:
          Hinrich, J. L., Bardenfleth, S. E., Røge, R., Churchill, N. W., Madsen,
          K. H., & Mørup, M. (2016). Archetypal Analysis for Modeling Multisubject
          fMRI Data. IEEE Journal on Selected Topics in Signal Processing, 10(7),
          1160-1171. https://doi.org/10.1109/JSTSP.2016.2595103
        
        ================================================================================
        ORIGINAL LICENSE (reproduced verbatim from the upstream MATLAB toolbox)
        ================================================================================
        
        Multisubject Archetypal Analysis Toolbox - Software License Agreement
        
        Multisubject Archetypal Analysis Toolbox Copyright Notice (2016)
        Technical University of Denmark (hereinafter referred to as "DTU").
        All rights reserved. Contact information jesper dot hinrich at gmail dot com.
        
        Article 1 - Definitions
        
        1. The "Software" constitutes any software distributed as part of or pertaining
        to the Multisubject Archetypal Analysis Toolbox as made available online at
        https://brainconnectivity.compute.dtu.dk/ or
        https://github.com/JesperLH/Multisubject-Archetypal-Analysis .
        
        2. "Academic" and "non-profit" use shall mean a user of Software: who is employed
        by, or a student enrolled at, or a scientist legitimately affiliated with an
        academic, non-profit or government institution; and whose use of the
        Software is on behalf of and in the interest of such academic, non-profit
        or government institution and is not on behalf of a commercial entity.
        
        Article 2 - License
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted for academic and non-profit use provided
        that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
        this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.
        
        3. As long as you qualify as an Academic User, DTU hereby grants free access
        to the Software supplied by DTU for non-commercial use only.
        You acknowledge and agree that you may not use the Software for
        commercial purpose without first obtaining a commercial license from DTU.
        
        4. Neither the names of the contributors nor of their affiliated
        institutions may be used to endorse or promote products derived from this
        software without specific prior written permission.
        
        5. WARRANTY DISCLAIMER. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS
        AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
        BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
        FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
        OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
        EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
        OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Keywords: archetypal-analysis,fmri,matrix-factorization,multi-subject,neuroimaging
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free for non-commercial use
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.9
Requires-Dist: numpy>=1.23
Provides-Extra: all
Requires-Dist: cupy-cuda12x>=12.0; extra == 'all'
Requires-Dist: matplotlib>=3.5; extra == 'all'
Requires-Dist: nibabel>=4.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-cov>=4; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: scipy>=1.10; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.1; extra == 'docs'
Requires-Dist: ipykernel; extra == 'docs'
Requires-Dist: myst-parser>=2.0; extra == 'docs'
Requires-Dist: nbsphinx>=0.9; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx<9,>=7.0; extra == 'docs'
Provides-Extra: fmri
Requires-Dist: nibabel>=4.0; extra == 'fmri'
Provides-Extra: gpu
Requires-Dist: cupy-cuda12x>=12.0; extra == 'gpu'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.5; extra == 'viz'
Description-Content-Type: text/markdown

# ArchePy

**Multi-Subject Archetypal Analysis (MS-AA) for fMRI data, in Python.**

A Python port of the [Multisubject Archetypal Analysis Toolbox](https://github.com/JesperLH/Multisubject-Archetypal-Analysis)
originally developed in MATLAB at the Technical University of Denmark by Hinrich, Bardenfleth, Røge,
Churchill, Madsen, and Mørup. Implements both spatial and temporal MS-AA with optional GPU
acceleration via [CuPy](https://cupy.dev/).

> [!IMPORTANT]
> **Academic / non-profit use only.** This package is distributed under the same license as the
> upstream MATLAB toolbox, which restricts use to academic and non-profit institutions.
> Commercial users must obtain a separate license from DTU. See [LICENSE](LICENSE) for full terms.

> [!NOTE]
> **Related packages.** ArchePy is one of several Python tools for archetypal analysis.
> If MS-AA isn't what you need, you may want:
> - [`archetypes`](https://github.com/aleixalcacer/archetypes) — general scikit-learn-compatible AA (BSD-3).
> - [`py_pcha`](https://github.com/ulfaslak/py_pcha) — Python implementation of PCHA, by one of MS-AA's
>   upstream authors (Mørup).
>
> ArchePy is specifically the multi-subject, heteroscedastic, GPU-accelerated variant for
> neuroimaging, ported from the [DTU MATLAB toolbox](https://github.com/JesperLH/Multisubject-Archetypal-Analysis).

---

## Installation

```bash
# CPU only
pip install archepy

# With GPU acceleration (CUDA 12.x — requires a CUDA-capable NVIDIA GPU)
pip install archepy[gpu]

# With fMRI helpers (NIfTI loading)
pip install archepy[fmri]

# Everything
pip install archepy[all]
```

For development:

```bash
git clone https://github.com/the-brAIn-lab/archepy
cd archepy
pip install -e .[dev]
pytest
```

## Requirements

- **Python** 3.9 or newer.
- **Required:** [NumPy](https://numpy.org/) >= 1.23.
- **Optional, for GPU acceleration:** [CuPy](https://cupy.dev/) (CUDA 12.x via `archepy[gpu]`).
  CUDA 11.x users should install `cupy-cuda11x` manually.
- **Optional, for fMRI helpers:** [nibabel](https://nipy.org/nibabel/) >= 4.0 (via `archepy[fmri]`).
- **Optional, for plotting:** [matplotlib](https://matplotlib.org/) >= 3.5 (via `archepy[viz]`).

The full dependency list is declared in [`pyproject.toml`](pyproject.toml).

## Quick start

```python
import numpy as np
from archepy import Subject, multi_subject_aa

# Each subject's data: a (T, V) array — time points × voxels.
# (For temporal MS-AA, see archepy.multi_subject_aa_T which uses (V, T).)
rng = np.random.default_rng(0)
n_subjects, T, V = 3, 200, 1000

subjects = [
    Subject(
        X=rng.standard_normal((T, V)).astype(float),
        sX=rng.standard_normal((T, V)).astype(float),
    )
    for _ in range(n_subjects)
]

# Fit MS-AA with K=10 archetypes.
results, C, cost, varexpl, elapsed = multi_subject_aa(
    subjects,
    noc=10,
    opts={
        "maxiter": 100,
        "conv_crit": 1e-6,
        "use_gpu": False,           # set True if you installed archepy[gpu]
        "heteroscedastic": True,
        "rngSEED": 42,
    },
)

print(f"Variance explained: {varexpl * 100:.1f}%   ({elapsed:.1f}s, {len(cost)} iters)")
print(f"Shared generator C shape:        {C.shape}")
print(f"Subject 0 archetypal mixture S:  {results[0]['S'].shape}")
print(f"Subject 0 reconstructed XC:      {results[0]['sXC'].shape}")
```

For a fuller end-to-end example using real fMRI data, see
[`examples/01_fit_msaa_flexible.ipynb`](examples/01_fit_msaa_flexible.ipynb).

## What this package contains

| Module | Purpose |
|---|---|
| `archepy.multi_subject_aa` | Spatial MS-AA: archetypes are linear combinations of time points, mixed across voxels. |
| `archepy.multi_subject_aa_T` | Temporal MS-AA: archetypes are linear combinations of voxels, mixed across time. |
| `archepy.Subject` | Per-subject data container (`X`, `sX`). |
| `archepy.furthest_sum` | FurthestSum initialization (CPU). |
| `archepy.init.furthest_sum_gpu` | FurthestSum initialization (GPU, CuPy). |
| `archepy.fmri.estimate_background_noise` | Estimate noise threshold from a NIfTI file. |
| `archepy.fmri.generate_synthetic_noise` | Generate synthetic radial noise maps. |

## Testing

ArchePy includes a smoke-test suite that exercises the FurthestSum
initialization and runs end-to-end MS-AA fits on planted low-rank data.
After installing the dev extras (`pip install -e .[dev]`), run:

```bash
pytest                                          # all tests
pytest --cov=archepy --cov-report=term-missing  # with coverage
```

The full suite finishes in seconds. CI runs the same suite on Linux, macOS,
and Windows across Python 3.9-3.12 — see [`.github/workflows/ci.yml`](.github/workflows/ci.yml).

## Contributing

Contributions are welcome — bug reports, feature requests, documentation
improvements, and pull requests. Please:

- Read [`CONTRIBUTING.md`](CONTRIBUTING.md) for the dev-environment setup,
  code style, and PR workflow.
- Review the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) before participating.
- For non-trivial changes, open an issue first to discuss.

By contributing, you agree that your contributions will be distributed under
the same academic / non-profit terms as the rest of the package.

## Citing

If you use ArchePy in a publication, please cite **both** the original paper and this port:

```bibtex
@article{hinrich2016archetypal,
  title   = {Archetypal Analysis for Modeling Multisubject {fMRI} Data},
  author  = {Hinrich, Jesper L\o{}ve and Bardenfleth, Sophia Elizabeth and
             R\o{}ge, Rasmus and Churchill, Nathan W. and Madsen, Kristoffer H.
             and M\o{}rup, Morten},
  journal = {IEEE Journal on Selected Topics in Signal Processing},
  volume  = {10},
  number  = {7},
  pages   = {1160--1171},
  year    = {2016},
  doi     = {10.1109/JSTSP.2016.2595103}
}

@software{archepy,
  author  = {Alex Shepherd},
  title   = {ArchePy: Multi-Subject Archetypal Analysis for fMRI in Python},
  url     = {https://github.com/the-brAIn-lab/archepy},
  version = {0.1.0},
  year    = {2026}
}
```

## Acknowledgments

This package would not exist without the original MATLAB toolbox by
**Jesper L. Hinrich, Sophia E. Bardenfleth, and Morten Mørup** at DTU's
Section for Cognitive Systems. The Python port preserves their algorithms
faithfully; any bugs in this port are mine alone.

## Status

Alpha. The algorithm code is a direct port of the MATLAB reference and reproduces
its outputs, but the Python API may evolve before 1.0. Pin to an exact version if you
need stability.
