# csogroup/cellcharter architecture

> Architecture diagram of the GitHub repository csogroup/cellcharter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/csogroup/cellcharter
- Repository: https://github.com/csogroup/cellcharter

## Overview

1. **What this repository is**
   CellCharter is a Python library, not an application service. Its architecture is centered on analyzing **spatial omics data** in an `AnnData`-style workflow: input data are transformed, a spatial neighborhood representation is built, clustering is performed, and the results are characterized and visualized.

2. **Core package boundary**
   The installable code lives under `src/cellcharter`. The top-level package is split into a few clear subsystems:
   - `_constants` and `_utils` for shared package-wide settings/helpers
   - `datasets` for bundled example/benchmark datasets
   - `gr` for graph and neighborhood operations
   - `tl` for analysis “tools” and model-based methods
   - `pl` for plotting and result visualization

3. **Data model and main integration point**
   The library is built around a single shared data container rather than custom project-specific objects. From the repo structure and notebooks, the typical integration point is a spatial omics `AnnData` object, which carries expression data, spatial coordinates, graph structure, learned embeddings, cluster assignments, and derived annotations across stages.

4. **Graph / neighborhood subsystem (`gr`)**
   `src/cellcharter/gr` is the spatial topology layer. It contains logic for:
   - building neighborhood graphs from spatial positions
   - aggregating neighbor features
   - grouping cells or neighborhoods
   - computing neighborhood-level comparisons and differential neighborhood signals  
   This is the main data-shaping layer that converts raw spatial measurements into graph-aware features for downstream modeling.

5. **Analysis / modeling subsystem (`tl`)**
   `src/cellcharter/tl` contains the core analytical methods:
   - `gmm`: Gaussian mixture model clustering
   - `autok`: automatic selection of candidate cluster numbers
   - `shape`: spatial domain shape characterization
   - `trvae`: integration with a modified TRVAE model for proteomics workflows  
   This layer consumes graph-derived or latent features and writes cluster/domain results back to the analysis object.

6. **Automatic model selection**
   The `autok` path is a distinct workflow: it evaluates multiple candidate cluster counts and selects stable solutions rather than assuming a single fixed `k`. The test fixtures under `tests/_models/cellcharter_autok_*` show that the repository persists many per-ক candidate model directories, indicating a reproducible multi-run selection process with saved parameters and attributes.

7. **External model dependencies**
   The README makes the main technology boundary explicit:
   - **scVI / scvi-tools** for transcriptomics and epigenomics latent representation / batch correction
   - **scArches TRVAE** for proteomics, with a CellCharter-specific MSE-based variant
   - **TorchGMM** as the maintained Gaussian mixture implementation
   - **PyTorch** as the runtime and serialization layer for trained models  
   CellCharter itself orchestrates these external models rather than reimplementing them.

8. **Visualization subsystem (`pl`)**
   `src/cellcharter/pl` provides plotting wrappers for the main analytical outputs:
   - neighborhood plots
   - group plots
   - shape plots
   - AutoK stability/selection plots  
   This layer is intentionally separate from computation, so diagrams should show it as a consumer of analyzed results rather than part of the core pipeline.

9. **End-to-end flow**
   The repo’s dominant flow is:
   input spatial omics data → optional latent representation / batch correction → spatial graph construction → neighbor aggregation → clustering or AutoK selection → domain characterization (shape, neighborhood enrichment, group comparisons) → plotting/reporting.  
   The graph layer and analysis layer are the two main computational boundaries; plotting is downstream-only.

10. **Artifacts and reproducibility**
   The repository includes saved model artifacts in `tests/_models` and tutorial assets in `docs/notebooks/tutorial_models`. These fixtures show that the library treats trained models as first-class artifacts, with serialized parameters/configuration alongside metadata. That matters architecturally because the pipeline is not just transient computation; it supports reloadable, testable model outputs.

11. **Documentation and quality pipeline**
   `docs/` contains API docs, tutorials, notebooks, and generated examples, while `.github/workflows`, `.pre-commit-config.yaml`, and `pyproject.toml` indicate a standard packaging/testing/release setup. These are support systems around the library, not runtime components, but they explain how the project is validated and distributed.

12. **How to draw the architecture**
   A good diagram would show one central analysis object flowing through three layers:
   - **graph construction / neighborhood feature engineering**
   - **modeling and clustering**
   - **characterization and visualization**  
   with external dependencies attached to the modeling layer (`scvi-tools`, `scArches`, `TorchGMM`, PyTorch) and datasets/docs/tests as supporting inputs and outputs.

Main entry points: [`src/cellcharter/tl/_gmm.py`](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_gmm.py) (GMM), [`src/cellcharter/tl/_autok.py`](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_autok.py) (AutoK), [`src/cellcharter/gr/_build.py`](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_build.py) (Build graph), [`src/cellcharter/tl/_trvae.py`](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_trvae.py) (TRVAE)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core package"]
  node_ann_data[("AnnData<br/>shared data model")]
  node_constants["Constants<br/>package settings<br/>[_pkg_constants.py]"]
  node_utils["Utils<br/>shared helpers<br/>[_utils.py]"]
end

subgraph group_graph["Graph layer"]
  node_build["Build graph<br/>spatial topology<br/>[_build.py]"]
  node_aggr["Aggregate<br/>feature aggregation<br/>[_aggr.py]"]
  node_nhood["Neighborhoods<br/>nhood ops<br/>[_nhood.py]"]
  node_group["Groups<br/>grouping ops<br/>[_group.py]"]
  node_diff["Diff nhood<br/>neighborhood signal"]
end

subgraph group_analysis["Analysis layer"]
  node_gmm["GMM<br/>clustering<br/>[_gmm.py]"]
  node_autok["AutoK<br/>model selection<br/>[_autok.py]"]
  node_shape_tl["Shape<br/>domain characterization<br/>[_shape.py]"]
  node_trvae["TRVAE<br/>latent integration<br/>[_trvae.py]"]
  node_scvi(("scvi-tools<br/>external dependency"))
  node_torchgmm(("TorchGMM<br/>external dependency"))
  node_pytorch(("PyTorch<br/>runtime dependency"))
end

subgraph group_viz["Visualization"]
  node_plot_nhood["Nhood plots<br/>visualization<br/>[_nhood.py]"]
  node_plot_group["Group plots<br/>visualization<br/>[_group.py]"]
  node_plot_shape["Shape plots<br/>visualization<br/>[_shape.py]"]
  node_plot_autok["AutoK plots<br/>visualization<br/>[_autok.py]"]
end

subgraph group_support["Support assets"]
  node_datasets["Datasets<br/>bundled data<br/>[_dataset.py]"]
  node_docs["Docs<br/>documentation"]
  node_fixtures[("Model fixtures<br/>serialized artifacts")]
end

node_datasets -->|"load example data"| node_ann_data
node_ann_data -->|"spatial positions"| node_build
node_build -->|"neighbor graph"| node_aggr
node_build -->|"adjacency"| node_nhood
node_build -->|"cells / regions"| node_group
node_aggr -->|"latent features"| node_gmm
node_nhood -->|"neighborhood stats"| node_diff
node_group -->|"group assignments"| node_diff
node_ann_data -->|"input omics"| node_trvae
node_scvi -->|"latent model"| node_trvae
node_pytorch -->|"train / save"| node_trvae
node_torchgmm -->|"mixture backend"| node_gmm
node_gmm -->|"candidate models"| node_autok
node_ann_data -->|"analysis object"| node_autok
node_autok -->|"selected domains"| node_shape_tl
node_gmm -->|"cluster outputs"| node_plot_nhood
node_diff -->|"comparisons"| node_plot_group
node_shape_tl -->|"shape metrics"| node_plot_shape
node_autok -->|"selection diagnostics"| node_plot_autok
node_gmm -->|"saved models"| node_fixtures
node_trvae -->|"tutorial model"| node_fixtures
node_docs -.->|"tutorials"| node_plot_nhood
node_docs -.->|"workflow docs"| node_autok

click node_constants "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/_constants/_pkg_constants.py"
click node_utils "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/_utils.py"
click node_datasets "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/datasets/_dataset.py"
click node_build "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_build.py"
click node_aggr "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_aggr.py"
click node_nhood "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_nhood.py"
click node_group "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_group.py"
click node_gmm "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_gmm.py"
click node_autok "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_autok.py"
click node_shape_tl "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_shape.py"
click node_trvae "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_trvae.py"
click node_plot_nhood "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_nhood.py"
click node_plot_group "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_group.py"
click node_plot_shape "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_shape.py"
click node_plot_autok "https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_autok.py"
click node_docs "https://github.com/csogroup/cellcharter/tree/main/docs"
click node_fixtures "https://github.com/csogroup/cellcharter/tree/main/tests/_models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ann_data,node_constants,node_utils toneBlue
class node_build,node_aggr,node_nhood,node_group,node_diff toneAmber
class node_gmm,node_autok,node_shape_tl,node_trvae,node_scvi,node_torchgmm,node_pytorch toneMint
class node_plot_nhood,node_plot_group,node_plot_shape,node_plot_autok toneRose
class node_datasets,node_docs,node_fixtures toneIndigo
```

## Components

### Core package

Installable library code and shared package-level helpers.

- **AnnData**: shared data model · Primary container passed through the library: expression, coordinates, graphs, embeddings, clusters, and annotations.
- [Constants](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/_constants/_pkg_constants.py): package settings · Package-wide constants and shared configuration. · `src/cellcharter/_constants/_pkg_constants.py`
- [Utils](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/_utils.py): shared helpers · Common helper functions used across subsystems. · `src/cellcharter/_utils.py`

### Graph layer

Spatial neighborhood construction and feature aggregation.

- [Build graph](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_build.py): spatial topology · Constructs neighborhood graphs from spatial positions. · `src/cellcharter/gr/_build.py`
- [Aggregate](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_aggr.py): feature aggregation · Aggregates neighbor features into neighborhood-level representations. · `src/cellcharter/gr/_aggr.py`
- [Neighborhoods](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_nhood.py): nhood ops · Neighborhood-centric graph utilities and comparisons. · `src/cellcharter/gr/_nhood.py`
- [Groups](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/gr/_group.py): grouping ops · Cell and neighborhood grouping logic. · `src/cellcharter/gr/_group.py`
- **Diff nhood**: neighborhood signal · Differential neighborhood analysis and comparison utilities.

### Analysis layer

Modeling, clustering, shape characterization, and latent integration.

- [GMM](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_gmm.py): clustering · Gaussian mixture model clustering stage. · `src/cellcharter/tl/_gmm.py`
- [AutoK](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_autok.py): model selection · Evaluates candidate cluster counts and selects stable solutions. · `src/cellcharter/tl/_autok.py`
- [Shape](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_shape.py): domain characterization · Characterizes spatial domain shapes from clustering results. · `src/cellcharter/tl/_shape.py`
- [TRVAE](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/tl/_trvae.py): latent integration · CellCharter-specific integration with modified TRVAE workflows. · `src/cellcharter/tl/_trvae.py`
- **scvi-tools**: external dependency · Latent representation and batch correction for transcriptomics and epigenomics.
- **TorchGMM**: external dependency · Gaussian mixture implementation used for clustering.
- **PyTorch**: runtime dependency · Training and serialization runtime for learned models.

### Visualization

Plotting wrappers for analytical results.

- [Nhood plots](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_nhood.py): visualization · Plots neighborhood-level outputs and summaries. · `src/cellcharter/pl/_nhood.py`
- [Group plots](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_group.py): visualization · Plots group and comparison results. · `src/cellcharter/pl/_group.py`
- [Shape plots](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_shape.py): visualization · Plots shape characterization outputs. · `src/cellcharter/pl/_shape.py`
- [AutoK plots](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/pl/_autok.py): visualization · Plots AutoK stability and selection diagnostics. · `src/cellcharter/pl/_autok.py`

### Support assets

Datasets, fixtures, docs, and serialized artifacts used around the library.

- [Datasets](https://github.com/csogroup/cellcharter/blob/main/src/cellcharter/datasets/_dataset.py): bundled data · Dataset loading and example-data helpers. · `src/cellcharter/datasets/_dataset.py`
- [Docs](https://github.com/csogroup/cellcharter/tree/main/docs): documentation · API docs, tutorials, notebooks, and generated examples. · `docs`
- [Model fixtures](https://github.com/csogroup/cellcharter/tree/main/tests/_models): serialized artifacts · Saved AutoK and tutorial model artifacts used for reproducibility and tests. · `tests/_models`

## Connections

- Datasets → AnnData: load example data · Bundled datasets populate the shared AnnData workflow.
- AnnData → Build graph: spatial positions · Spatial coordinates and metadata are used to build neighborhood graphs.
- Build graph → Aggregate: neighbor graph · Constructed topology feeds feature aggregation.
- Build graph → Neighborhoods: adjacency · Neighborhood structures are derived from the spatial graph.
- Build graph → Groups: cells / regions · Graph structure supports grouping operations.
- Aggregate → GMM: latent features · Aggregated neighbor features are consumed by clustering.
- Neighborhoods → Diff nhood: neighborhood stats · Neighborhood-level representations support differential analysis.
- Groups → Diff nhood: group assignments · Grouping results feed neighborhood comparisons.
- AnnData → TRVAE: input omics · Proteomics or other omics data are integrated through TRVAE workflows.
- scvi-tools → TRVAE: latent model · External latent representation and batch correction models underpin the integration path.
- PyTorch → TRVAE: train / save · PyTorch provides the runtime and artifact serialization layer.
- TorchGMM → GMM: mixture backend · Clustering is delegated to the maintained GMM implementation.
- GMM → AutoK: candidate models · AutoK orchestrates multiple clustering runs over candidate k values.
- AnnData → AutoK: analysis object · AutoK reads and writes results on the shared container.
- AutoK → Shape: selected domains · Chosen clusterings are characterized spatially.
- GMM → Nhood plots: cluster outputs · Cluster and neighborhood results are visualized.
- Diff nhood → Group plots: comparisons · Differential neighborhood/group results are visualized.
- Shape → Shape plots: shape metrics · Spatial shape characterization drives plotting.
- AutoK → AutoK plots: selection diagnostics · Model-selection summaries are visualized.
- GMM → Model fixtures: saved models · Serialized clustering artifacts support reproducible tests and tutorials.
- TRVAE → Model fixtures: tutorial model · Example trained models are stored for docs and validation.
- Docs → Nhood plots: tutorials · Documentation demonstrates plotting and analysis workflows.
- Docs → AutoK: workflow docs · Docs explain the AutoK selection pipeline.
