# dls5-omics/cellnavi architecture

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

- Interactive diagram: https://gitdiagram.com/dls5-omics/cellnavi
- Repository: https://github.com/dls5-omics/cellnavi

## Overview

CellNavi is a gene-graph-aware deep-learning framework for predicting perturbation genes from single-cell transcriptomic profiles. Its main workflow prepares cells and graph-derived features, fine-tunes a pretrained encoder to classify perturbations, and evaluates predictions or emits per-gene logits. The graph also retains the documented pretraining capability and key inference branches. Source excerpts show dataset preparation, model calls, and training; tutorial validation and result-generation internals were not sampled, so those entrypoints are represented only at the documented level.

Main entry points: [`cellnavi/trainer/trainer.py`](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/trainer/trainer.py) (Fine-tune trainer), [`cellnavi/data_provider/dataset.py`](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/data_provider/dataset.py) (Cell dataset), [`cellnavi/model/pretrain_model.py`](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/pretrain_model.py) (Pretrained encoder), [`tutorials/load_results.py`](https://github.com/dls5-omics/cellnavi/blob/main/tutorials/load_results.py) (Perturbation logits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_train_data["Training dataset"]
  node_test_data["Test dataset"]
  node_gene_graph["Gene graphs"]
  node_dataset["Cell dataset<br/>[dataset.py]"]
  node_train_loader["Training loader<br/>[train_loader.py]"]
  node_validation_loader["Validation loader"]
end

subgraph group_models["Modeling"]
  node_pretrain_weights["Pretrained weights"]
  node_finetune["Perturbation classifier<br/>[finetune_model.py]"]
  node_pretrain["Pretrained encoder<br/>[pretrain_model.py]"]
  node_attention["Transformer layers<br/>[attention.py]"]
  node_count_encoding["Count encoding"]
end

subgraph group_train["Training"]
  node_train_script["Launch training<br/>[launch_train.sh]"]
  node_config["Run configuration<br/>[config.json]"]
  node_trainer["Fine-tune trainer<br/>[trainer.py]"]
  node_checkpoints["Model checkpoints"]
end

subgraph group_results["Evaluation and results"]
  node_validate_script["Run validation<br/>[start_validate.py]"]
  node_results_script["Generate logits<br/>[load_results.py]"]
  node_validation["Validation metrics<br/>[start_validate.py]"]
  node_gene_logits["Perturbation logits<br/>[load_results.py]"]
  node_applications["Biological applications"]
end

node_user(("Researcher"))

node_user -->|"launches"| node_train_script
node_user -->|"requests metrics"| node_validate_script
node_user -->|"requests logits"| node_results_script
node_train_script -->|"starts training"| node_trainer
node_trainer -->|"reads settings"| node_config
node_dataset -->|"reads profiles"| node_train_data
node_dataset -->|"reads profiles"| node_test_data
node_dataset -->|"reads graph matrices"| node_gene_graph
node_train_loader -->|"loads batches"| node_dataset
node_validation_loader -->|"loads batches"| node_dataset
node_trainer -->|"iterates"| node_train_loader
node_trainer -->|"initializes"| node_validation_loader
node_trainer -->|"trains"| node_finetune
node_trainer -->|"loads and saves"| node_checkpoints
node_trainer -->|"loads if needed"| node_pretrain_weights
node_finetune -->|"encodes cells"| node_pretrain
node_pretrain -->|"applies layers"| node_attention
node_pretrain -->|"encodes counts"| node_count_encoding
node_validate_script -->|"evaluates"| node_validation
node_results_script -->|"produces"| node_gene_logits
node_validation -->|"evaluates on"| node_test_data
node_gene_logits -->|"scores perturbations"| node_test_data
node_gene_logits -->|"supports discovery"| node_applications

click node_train_script "https://github.com/dls5-omics/cellnavi/blob/main/tutorials/launch_train.sh"
click node_validate_script "https://github.com/dls5-omics/cellnavi/blob/main/tutorials/start_validate.py"
click node_results_script "https://github.com/dls5-omics/cellnavi/blob/main/tutorials/load_results.py"
click node_config "https://github.com/dls5-omics/cellnavi/blob/main/config.json"
click node_dataset "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/data_provider/dataset.py"
click node_train_loader "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/data_provider/train_loader.py"
click node_validation_loader "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/data_provider/validation_loader.py"
click node_trainer "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/trainer/trainer.py"
click node_finetune "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/finetune_model.py"
click node_pretrain "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/pretrain_model.py"
click node_attention "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/attention.py"
click node_count_encoding "https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/rawcount_encoding.py"
click node_validation "https://github.com/dls5-omics/cellnavi/blob/main/tutorials/start_validate.py"
click node_gene_logits "https://github.com/dls5-omics/cellnavi/blob/main/tutorials/load_results.py"

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_train_data,node_test_data,node_gene_graph,node_dataset,node_train_loader,node_validation_loader toneBlue
class node_pretrain_weights,node_finetune,node_pretrain,node_attention,node_count_encoding toneAmber
class node_train_script,node_config,node_trainer,node_checkpoints toneMint
class node_validate_script,node_results_script,node_validation,node_gene_logits,node_applications toneRose
class node_user toneIndigo
```

## Components

### Data preparation

- **Training dataset**
- **Test dataset**
- **Gene graphs**
- [Cell dataset](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/data_provider/dataset.py): `cellnavi/data_provider/dataset.py`
- [Training loader](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/data_provider/train_loader.py): `cellnavi/data_provider/train_loader.py`
- [Validation loader](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/data_provider/validation_loader.py): `cellnavi/data_provider/validation_loader.py`

### Modeling

- **Pretrained weights**
- [Perturbation classifier](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/finetune_model.py): `cellnavi/model/finetune_model.py`
- [Pretrained encoder](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/pretrain_model.py): `cellnavi/model/pretrain_model.py`
- [Transformer layers](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/attention.py): `cellnavi/model/attention.py`
- [Count encoding](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/model/rawcount_encoding.py): `cellnavi/model/rawcount_encoding.py`

### Training

- [Launch training](https://github.com/dls5-omics/cellnavi/blob/main/tutorials/launch_train.sh): `tutorials/launch_train.sh`
- [Run configuration](https://github.com/dls5-omics/cellnavi/blob/main/config.json): `config.json`
- [Fine-tune trainer](https://github.com/dls5-omics/cellnavi/blob/main/cellnavi/trainer/trainer.py): `cellnavi/trainer/trainer.py`
- **Model checkpoints**

### Evaluation and results

- [Run validation](https://github.com/dls5-omics/cellnavi/blob/main/tutorials/start_validate.py): `tutorials/start_validate.py`
- [Generate logits](https://github.com/dls5-omics/cellnavi/blob/main/tutorials/load_results.py): `tutorials/load_results.py`
- [Validation metrics](https://github.com/dls5-omics/cellnavi/blob/main/tutorials/start_validate.py): `tutorials/start_validate.py`
- [Perturbation logits](https://github.com/dls5-omics/cellnavi/blob/main/tutorials/load_results.py): `tutorials/load_results.py`
- **Biological applications**

### Other components

- **Researcher**

## Connections

- Researcher → Launch training: launches
- Researcher → Run validation: requests metrics
- Researcher → Generate logits: requests logits
- Launch training → Fine-tune trainer: starts training
- Fine-tune trainer → Run configuration: reads settings
- Cell dataset → Training dataset: reads profiles
- Cell dataset → Test dataset: reads profiles
- Cell dataset → Gene graphs: reads graph matrices
- Training loader → Cell dataset: loads batches
- Validation loader → Cell dataset: loads batches
- Fine-tune trainer → Training loader: iterates
- Fine-tune trainer → Validation loader: initializes
- Fine-tune trainer → Perturbation classifier: trains
- Fine-tune trainer → Model checkpoints: loads and saves
- Fine-tune trainer → Pretrained weights: loads if needed
- Perturbation classifier → Pretrained encoder: encodes cells
- Pretrained encoder → Transformer layers: applies layers
- Pretrained encoder → Count encoding: encodes counts
- Run validation → Validation metrics: evaluates
- Generate logits → Perturbation logits: produces
- Validation metrics → Test dataset: evaluates on
- Perturbation logits → Test dataset: scores perturbations
- Perturbation logits → Biological applications: supports discovery