# theislab/chemcpa architecture

> Architecture diagram of the GitHub repository theislab/chemcpa, 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/theislab/chemcpa
- Repository: https://github.com/theislab/chemcpa

## Overview

chemCPA predicts single-cell responses to drug perturbations, including drugs not seen during training. The documented workflow is to obtain raw datasets, process them into analysis-ready data, generate or load molecular embeddings, then train the response model. The graph preserves the distinct data-preparation, molecular-representation, and training stages, plus the model’s data and training layers. README descriptions support the overall workflow; sampled source confirms embedding generation/loading, but not every connection among the training modules.

Main entry points: [`chemCPA/lightning_module.py`](https://github.com/theislab/chemcpa/blob/main/chemCPA/lightning_module.py) (Training loop), [`preprocessing/1_lincs.py`](https://github.com/theislab/chemcpa/blob/main/preprocessing/1_lincs.py) (Dataset processing), [`embeddings/rdkit/embedding_rdkit.py`](https://github.com/theislab/chemcpa/blob/main/embeddings/rdkit/embedding_rdkit.py) (Embedding generation), [`raw_data/datasets.py`](https://github.com/theislab/chemcpa/blob/main/raw_data/datasets.py) (Raw datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_raw[("Raw datasets<br/>[datasets.py]")]
  node_download["Dataset downloads<br/>[download_data.py]"]
  node_preprocess["Dataset processing<br/>[1_lincs.py]"]
  node_dataset["Dataset assembly<br/>[dataset.py]"]
  node_datamodule["Perturbation batches"]
end

subgraph group_molecules["Molecular representations"]
  node_embgen["Embedding generation<br/>[embedding_rdkit.py]"]
  node_embedding_families["Embedding models"]
  node_embstore[("Saved embeddings<br/>[embedding.py]")]
  node_embload["Embedding lookup<br/>[embedding.py]"]
end

subgraph group_training["Response modeling"]
  node_trainentry["Training entry<br/>[train_hydra.py]"]
  node_trainer["Training loop"]
  node_model["Response model<br/>[model.py]"]
  node_results["Predicted responses"]
end

node_researcher(("Researcher"))

node_researcher -->|"requests data"| node_download
node_download -->|"retrieves"| node_raw
node_researcher -->|"runs sequentially"| node_preprocess
node_raw -->|"provides inputs"| node_preprocess
node_preprocess -->|"prepares data"| node_dataset
node_researcher -->|"generates embeddings"| node_embgen
node_embedding_families -.->|"encodes molecules"| node_embgen
node_embgen -->|"saves vectors"| node_embstore
node_dataset -->|"supplies samples"| node_datamodule
node_embstore -->|"reads vectors"| node_embload
node_researcher -->|"starts training"| node_trainentry
node_trainentry -->|"configures training"| node_trainer
node_trainer -->|"uses batches"| node_datamodule
node_trainer -->|"loads embeddings"| node_embload
node_trainer -->|"trains"| node_model
node_model -->|"predicts responses"| node_results

click node_raw "https://github.com/theislab/chemcpa/blob/main/raw_data/datasets.py"
click node_download "https://github.com/theislab/chemcpa/blob/main/raw_data/download_data.py"
click node_preprocess "https://github.com/theislab/chemcpa/blob/main/preprocessing/1_lincs.py"
click node_dataset "https://github.com/theislab/chemcpa/blob/main/chemCPA/data/dataset/dataset.py"
click node_datamodule "https://github.com/theislab/chemcpa/blob/main/chemCPA/data/perturbation_data_module.py"
click node_embgen "https://github.com/theislab/chemcpa/blob/main/embeddings/rdkit/embedding_rdkit.py"
click node_embedding_families "https://github.com/theislab/chemcpa/tree/main/embeddings"
click node_embstore "https://github.com/theislab/chemcpa/blob/main/chemCPA/embedding.py"
click node_embload "https://github.com/theislab/chemcpa/blob/main/chemCPA/embedding.py"
click node_trainentry "https://github.com/theislab/chemcpa/blob/main/chemCPA/train_hydra.py"
click node_trainer "https://github.com/theislab/chemcpa/blob/main/chemCPA/lightning_module.py"
click node_model "https://github.com/theislab/chemcpa/blob/main/chemCPA/model.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_raw,node_download,node_preprocess,node_dataset,node_datamodule toneBlue
class node_embgen,node_embedding_families,node_embstore,node_embload toneAmber
class node_trainentry,node_trainer,node_model,node_results toneMint
class node_researcher toneIndigo
```

## Components

### Data preparation

- [Raw datasets](https://github.com/theislab/chemcpa/blob/main/raw_data/datasets.py): `raw_data/datasets.py`
- [Dataset downloads](https://github.com/theislab/chemcpa/blob/main/raw_data/download_data.py): `raw_data/download_data.py`
- [Dataset processing](https://github.com/theislab/chemcpa/blob/main/preprocessing/1_lincs.py): `preprocessing/1_lincs.py`
- [Dataset assembly](https://github.com/theislab/chemcpa/blob/main/chemCPA/data/dataset/dataset.py): `chemCPA/data/dataset/dataset.py`
- [Perturbation batches](https://github.com/theislab/chemcpa/blob/main/chemCPA/data/perturbation_data_module.py): `chemCPA/data/perturbation_data_module.py`

### Molecular representations

- [Embedding generation](https://github.com/theislab/chemcpa/blob/main/embeddings/rdkit/embedding_rdkit.py): `embeddings/rdkit/embedding_rdkit.py`
- [Embedding models](https://github.com/theislab/chemcpa/tree/main/embeddings): `embeddings`
- [Saved embeddings](https://github.com/theislab/chemcpa/blob/main/chemCPA/embedding.py): `chemCPA/embedding.py`
- [Embedding lookup](https://github.com/theislab/chemcpa/blob/main/chemCPA/embedding.py): `chemCPA/embedding.py`

### Response modeling

- [Training entry](https://github.com/theislab/chemcpa/blob/main/chemCPA/train_hydra.py): `chemCPA/train_hydra.py`
- [Training loop](https://github.com/theislab/chemcpa/blob/main/chemCPA/lightning_module.py): `chemCPA/lightning_module.py`
- [Response model](https://github.com/theislab/chemcpa/blob/main/chemCPA/model.py): `chemCPA/model.py`
- **Predicted responses**

### Other components

- **Researcher**

## Connections

- Researcher → Dataset downloads: requests data
- Dataset downloads → Raw datasets: retrieves
- Researcher → Dataset processing: runs sequentially
- Raw datasets → Dataset processing: provides inputs
- Dataset processing → Dataset assembly: prepares data
- Researcher → Embedding generation: generates embeddings
- Embedding models → Embedding generation: encodes molecules
- Embedding generation → Saved embeddings: saves vectors
- Dataset assembly → Perturbation batches: supplies samples
- Saved embeddings → Embedding lookup: reads vectors
- Researcher → Training entry: starts training
- Training entry → Training loop: configures training
- Training loop → Perturbation batches: uses batches
- Training loop → Embedding lookup: loads embeddings
- Training loop → Response model: trains
- Response model → Predicted responses: predicts responses