How theislab/cellrank works
Project Type and Purpose
• CellRank is a Python package designed for unified fate mapping in multi-view single-cell data. It leverages Markov state modeling to analyze cellular dynamics, estimate fate probabilities, and infer gene expression trends.
• Its core functionality revolves around processing single-cell datasets (often using AnnData objects in the scverse ecosystem), computing kernels (including RNA velocity and pseudotime based ones), running state estimators (e.g., terminal state detection with pyGPCCA), and visualizing outcomes.
File Structure Insights and Architecturally Relevant Directories
• The source code is primarily contained in the “src/cellrank” directory, which is subdivided into several key submodules:
• estimators: Hosts the various algorithms to compute fate probabilities and macrostates. It includes mixins and specific estimators (e.g., terminal states).
• kernels: Provides different kernel implementations and utilities around connectivity, velocity, pseudotime, etc.
• models: Contains wrappers and interfaces for different modeling approaches (sklearn, pygam, etc.).
• pl: Focuses on plotting modules and visualization components (aggregating trends, heatmaps, etc.).
• logging: Handles logging configurations and capabilities.
• settings: Contains configuration classes for managing project settings.
• In addition to the core library, there are extensive documentation folders (docs), testing suites (tests), CI/CD configurations (.github/workflows), and build/deployment configuration files (pyproject.toml, MANIFEST.in).
Main Components
a. User-facing API / Interface:
• Represents the high-level Python package interface that end users or other systems interact with (e.g., main entry points, configuration files, etc.).
b. Core Computational Modules:
• Kernels: Including various methods to represent cellular similarity and transitions (e.g., RNA velocity, pseudotime, etc.).
• Estimators: Modules for computing cellular state estimations and fate probabilities, including specialized processes for terminal state detection.
• Models: Containing multiple implementations (e.g., scikit-learn models, pyGAM models) to interface with the estimators.
c. Utility and Helper Components:
• _utils, logging, and settings: Provide support functions, logging mechanisms, and configuration management for reproducibility and debugging.
d. Visualization Pipeline:
• The “pl” module: which includes functions for plotting trends, heatmaps, and clustering output helping interpret the results.
e. External Dependencies and Ecosystem:
• Integration with the scverse ecosystem and pyGPCCA. This can be represented as external modules or dependencies feeding into the primary computations.
f. Testing and Documentation:
• Testing suite (unit tests in the tests directory) and the robust documentation process (docs folder, Read the Docs config) which ensure reliability and maintainability.
Relationships and Interactions
• Data Flow: Illustrate a logical flow:
• Input Data → Preprocessing/Kernel Computation → Estimation (fate probabilities & state detection via estimators) → Modeling → Visualization.
• Dependencies: The utilities, logging, and settings modules serve as cross-cutting concerns that support all core modules.
• External Interactions: Show integration points with external libraries like scverse and pyGPCCA as well as external data formats (e.g., H5AD files noted in testing ground truth).