# theislab/cellrank architecture

> Architecture diagram of the GitHub repository theislab/cellrank, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/theislab/cellrank
- Repository: https://github.com/theislab/cellrank

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    ex1["scverse Ecosystem"]:::external
    ex2["pyGPCCA"]:::external

    %% Input Data
    inData["Raw Single Cell Data"]:::core

    %% Core Processing Pipeline
    subgraph "Core Processing Pipeline"
        api["User-facing API / Interface"]:::user
        kernel["Kernel Computation Module"]:::core
        estimator["Estimation (Fate Probabilities & Terminal States)"]:::core
        model["Modeling Module"]:::core
        viz["Visualization Pipeline"]:::core
    end

    %% Supporting Utilities
    subgraph "Supporting Utilities"
        utils["General Utilities"]:::utils
        log["Logging"]:::utils
        settings["Configuration/Settings"]:::utils
    end

    %% Quality Assurance and Documentation
    subgraph "QA and Documentation"
        test["Testing Suite"]:::testing
        doc["Documentation"]:::testing
    end

    %% Data Flow Connections
    inData -->|"feeds"| api
    ex1 -->|"integrates"| api
    api -->|"triggers"| kernel
    kernel -->|"computes"| estimator
    estimator -->|"informs"| model
    model -->|"outputs"| viz
    ex2 -->|"supports"| estimator

    %% Utility Support (dashed connections)
    utils -.-> api
    utils -.-> kernel
    log -.-> estimator
    settings -.-> model

    %% QA and Documentation Connections (dashed)
    test -.-> api
    doc -.-> api

    %% Click Events for component mapping
    click api "https://github.com/theislab/cellrank/blob/main/src/cellrank/__init__.py"
    click api "https://github.com/theislab/cellrank/blob/main/src/cellrank/datasets.py"
    click kernel "https://github.com/theislab/cellrank/tree/main/src/cellrank/kernels"
    click estimator "https://github.com/theislab/cellrank/tree/main/src/cellrank/estimators"
    click estimator "https://github.com/theislab/cellrank/tree/main/src/cellrank/estimators/terminal_states"
    click model "https://github.com/theislab/cellrank/tree/main/src/cellrank/models"
    click utils "https://github.com/theislab/cellrank/tree/main/src/cellrank/_utils"
    click log "https://github.com/theislab/cellrank/tree/main/src/cellrank/logging"
    click settings "https://github.com/theislab/cellrank/tree/main/src/cellrank/settings"
    click viz "https://github.com/theislab/cellrank/tree/main/src/cellrank/pl"
    click test "https://github.com/theislab/cellrank/tree/main/tests"
    click doc "https://github.com/theislab/cellrank/tree/main/docs"

    %% Styles
    classDef user fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef utils fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef external fill:#F08080,stroke:#000,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
