How csogroup/cellcharter works
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: _gmm.py GMM · _autok.py AutoK · _build.py Build graph · _trvae.py TRVAE
Components 22
Core package
Installable library code and shared package-level helpers.
- AnnData · Primary container passed through the library: expression, coordinates, graphs, embeddings, clusters, and annotations.
- Constants · Package-wide constants and shared configuration.
src/cellcharter/_constants/_pkg_constants.py - Utils · Common helper functions used across subsystems.
src/cellcharter/_utils.py
Graph layer
Spatial neighborhood construction and feature aggregation.
- Build graph · Constructs neighborhood graphs from spatial positions.
src/cellcharter/gr/_build.py - Aggregate · Aggregates neighbor features into neighborhood-level representations.
src/cellcharter/gr/_aggr.py - Neighborhoods · Neighborhood-centric graph utilities and comparisons.
src/cellcharter/gr/_nhood.py - Groups · Cell and neighborhood grouping logic.
src/cellcharter/gr/_group.py - Diff nhood · Differential neighborhood analysis and comparison utilities.
Analysis layer
Modeling, clustering, shape characterization, and latent integration.
- GMM · Gaussian mixture model clustering stage.
src/cellcharter/tl/_gmm.py - AutoK · Evaluates candidate cluster counts and selects stable solutions.
src/cellcharter/tl/_autok.py - Shape · Characterizes spatial domain shapes from clustering results.
src/cellcharter/tl/_shape.py - TRVAE · CellCharter-specific integration with modified TRVAE workflows.
src/cellcharter/tl/_trvae.py - scvi-tools · Latent representation and batch correction for transcriptomics and epigenomics.
- TorchGMM · Gaussian mixture implementation used for clustering.
- PyTorch · Training and serialization runtime for learned models.
Visualization
Plotting wrappers for analytical results.
- Nhood plots · Plots neighborhood-level outputs and summaries.
src/cellcharter/pl/_nhood.py - Group plots · Plots group and comparison results.
src/cellcharter/pl/_group.py - Shape plots · Plots shape characterization outputs.
src/cellcharter/pl/_shape.py - AutoK plots · Plots AutoK stability and selection diagnostics.
src/cellcharter/pl/_autok.py
Support assets
Datasets, fixtures, docs, and serialized artifacts used around the library.
- Datasets · Dataset loading and example-data helpers.
src/cellcharter/datasets/_dataset.py - Docs · API docs, tutorials, notebooks, and generated examples.
docs - Model fixtures · Saved AutoK and tutorial model artifacts used for reproducibility and tests.
tests/_models
Connections 23
- 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.