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, 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.

Installation

To install parafac2 with standard CPU support:

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:

pip install "parafac2[gpu]"

Or with uv:

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 (Basic familiarity with the python programming languages is recommended to navigate repository).