parafac2 1.6.0__tar.gz

parafac2-1.6.0/PKG-INFO

@@ -0,0 +1,73 @@
+Metadata-Version: 2.4
+Name: parafac2
+Version: 1.6.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: 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).

parafac2-1.6.0/README.md

@@ -0,0 +1,42 @@
+# 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).

parafac2-1.6.0/parafac2/__init__.py

@@ -0,0 +1,20 @@
+"""
+Main exports.
+"""
+
+from .backend import GPUMatrix, get_backend, to_gpu
+from .compress import CompressedData, compress_dataset
+from .normalize import prepare_dataset
+from .parafac2 import parafac2_init, parafac2_nd, store_pf2
+
+__all__ = [
+    "CompressedData",
+    "GPUMatrix",
+    "compress_dataset",
+    "get_backend",
+    "parafac2_init",
+    "parafac2_nd",
+    "prepare_dataset",
+    "store_pf2",
+    "to_gpu",
+]