Metadata-Version: 2.4
Name: parafac2
Version: 1.8.0
Summary: An implementation of PARAFAC2 that handles sparsity for single cell data.
Keywords: parafac2,tensor decomposition,single-cell,anndata
Author: Aaron Meyer
Author-email: Aaron Meyer <git@asmlab.org>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Dist: numpy>=2.2
Requires-Dist: scipy>=1.18
Requires-Dist: tensorly>=0.8.1
Requires-Dist: tqdm>=4.68
Requires-Dist: anndata>=0.12
Requires-Dist: mlx ; platform_machine == 'arm64' and sys_platform == 'darwin' and extra == 'gpu'
Requires-Dist: cupy-cuda12x[ctk] ; sys_platform != 'darwin' and extra == 'gpu'
Requires-Dist: nvmath-python ; sys_platform != 'darwin' and extra == 'gpu'
Requires-Dist: sparse-dot-mkl>=0.9 ; platform_machine == 'x86_64' and extra == 'mkl'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/meyer-lab/parafac2
Project-URL: Documentation, https://meyer-lab.github.io/parafac2/
Project-URL: Repository, https://github.com/meyer-lab/parafac2
Project-URL: Issues, https://github.com/meyer-lab/parafac2/issues
Provides-Extra: gpu
Provides-Extra: mkl
Description-Content-Type: text/markdown

# Integrative, high-resolution analysis of single cells across experimental conditions with PARAFAC2

`parafac2` contains the code for the PARAFAC2 (Pf2) python package, a tensor decomposition technique, used in our study for identifying variation patterns in single-cell populations across conditions. In our [study](https://www.biorxiv.org/content/10.1101/2024.07.29.605698v1.article-info), we discovered association patterns to specific cell populations, genes, and experimental conditions in both a drug perturbational study and systemic lupus erythematosus cohort study. 

Full package documentation is available at [meyer-lab.github.io/parafac2](https://meyer-lab.github.io/parafac2/).

## Installation
To install `parafac2` with standard CPU support:
```bash
pip install parafac2
```

### Hardware Acceleration (`[gpu]` extra)
`parafac2` supports hardware acceleration (`mlx` on Apple Silicon and `cupy` on Linux/Windows) via a single `gpu` extra:

```bash
pip install "parafac2[gpu]"
```

Or with `uv`:
```bash
uv sync --extra gpu
```

Environment markers automatically select `mlx` when on macOS Apple Silicon, and `cupy` on other platforms. If no GPU backend is installed, `parafac2` falls back to CPU computation seamlessly.

## Input Requirements
1. Your AnnData object must include an observations `column condition_unique_idxs` that is a 0-indexed array of which condition each cell is derived from along with the cell barcode 
Preprocessing your data
2. Your AnnData object must be preprocessed (removed doublets, normalized, log transformed) before running the algorithm
3. The function `parafac2_nd` is the Pf2 algorithm with various parameters that can be altered such as rank, tolerance, etc. 

## Outputs
The output of `parafac2_nd` is the first AnnData object and the reconstruction error (R2X). The results of `parafac2_nd` are added to the AnnData object. These include: 
1. The weights for each component `X.uns["Pf2_weights"]`
2. The factors with respect to each dimension in the data where `X.uns[“Pf2_A”]` is the condition factors, `X.uns[“Pf2_B”]` is the eigen-state factors, and `X.varm[“Pf2_C”]` is the genes, where the width of the matrix is the rank used for the algorithm
3. Each cell will have the corresponding values for the projections, `X.obsm["projections"]`, where the width of the matrix is the rank used for the algorithm
4. In addition, each cell has the corresponding weighted projections for each cell in the `X.obsm["weighted_projections"]` for all components, to determine how each cell related to each component pattern, where the width of the matrix is the rank used for the algorithm
5. We recommend implementing an embedding algorithm such as PaCMAP or UMAP on the `X.obsm["projections"]` to visualize cell-to-cell heterogeneity, creating a new columns coined `X.obsm["embedding"]` for example

## Examples
You can find example scripts that load single-cell scRNA-seq data across conditions, implement Pf2, and various ways to interpret and plot Pf2 on Github via the [RISE repository](https://github.com/meyer-lab/RISE) (Basic familiarity with the python programming languages is recommended to navigate repository).
