CellFlow

CellFlow is a framework designed for modeling complex perturbations in single-cell data using Flow Matching. It allows researchers to predict single-cell phenotypes resulting from various interventions, such as:

• Single and combinatorial drug treatments
• Genetic perturbations
• Development of perturbed organisms
• Cell fate engineering
• Optimization of organoid growth protocols

CellFlow provides specialized solvers for modeling complex perturbations using flow matching. The primary available solvers are:

• OTFlowMatching: An Optimal Transport-based flow matching solver.
• GENOT: A solver likely focused on generative modeling or specific perturbation types (refer to the full API documentation for specific parameter requirements).

These solvers are accessible via the cellflow.solvers module.

For tasks involving local structure or label propagation, use:

• compute_wknn: Computes weighted k-nearest neighbors (wknn).
• transfer_labels: Transfers labels between data points based on similarity or neighborhood structures.

The module provides three related functions for Principal Component Analysis (PCA) workflows:

• centered_pca: Performs PCA on centered data.
• project_pca: Projects data onto a pre-computed PCA space.
• reconstruct_pca: Reconstructs the original data from its PCA projection.

To represent chemical structures or categorical data for modeling, use:

• get_molecular_fingerprints: Generates molecular fingerprints.
• encode_onehot: Performs one-hot encoding on categorical features.
• annotate_compounds: Annotates chemical compounds with relevant metadata.

Install the cellflow-tools package using pip. Note that cellflow requires Python version >= 3.11.

pip install cellflow-tools

While not strictly required, it is recommended to install rapids-singlecell and cuml alongside cellflow to enable faster preprocessing and downstream functions.

To install these dependencies, follow the official RAPIDS installation instructions: https://rapids-singlecell.readthedocs.io/en/latest/Installation.html

To build and view the documentation locally, navigate to the docs directory and use make html. You can then open the generated HTML file in your browser.

cd docs
make html
open _build/html/index.html

To contribute to CellFlow or run tests and build documentation, you must install the package in editable mode along with the dev and test extras. This ensures all necessary Python packages for testing and documentation generation are available.

cd CellFlow
pip install -e ".[dev,test]"

CellFlow provides built-in sample datasets for testing and demonstration purposes via the cellflow.datasets module. Two available datasets are:

• ineurons: A dataset related to neuron modeling.
• pbmc_cytokines: A dataset related to PBMC (Peripheral Blood Mononuclear Cell) cytokine responses.

You can access these by importing them from the cellflow.datasets module.

from cellflow.datasets import ineurons, pbmc_cytokines

# Use the datasets in your CellFlow workflows