# charlotteinfante/t5pka architecture

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

- Interactive diagram: https://gitdiagram.com/charlotteinfante/t5pka
- Repository: https://github.com/charlotteinfante/t5pka

## Overview

T5pKa predicts molecular microstates with a sequence-to-sequence model and estimates microscopic pKa values with a regression model. The main user workflow runs prediction from SMILES or input files, tokenizes and batches molecular strings, invokes a trained model, and writes predictions; optional ensemble prediction combines model runs. Separate paths support model pretraining and fine-tuning, evaluation, and SHAP-based interpretation. The README establishes the two-stage prediction capability; source excerpts show selected runtime connections, so unsampled internals are represented conservatively.

Main entry points: [`t5pka/mol_tokenizers.py`](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/mol_tokenizers.py) (Molecule tokenizers), [`t5pka/run_prediction.py`](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_prediction.py) (Prediction runner), [`t5pka/run_trainer.py`](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_trainer.py) (Task fine-tuning), [`t5pka/run_pretrain.py`](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_pretrain.py) (Model pretraining)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prediction["Prediction"]
  node_dispatcher["CLI dispatcher<br/>[__main__.py]"]
  node_predict["Prediction runner<br/>[run_prediction.py]"]
  node_ensemble_predict["Ensemble prediction"]
  node_result["Prediction files"]
end

subgraph group_modeling["Modeling"]
  node_tokenizers["Molecule tokenizers<br/>[mol_tokenizers.py]"]
  node_model["T5 model<br/>[model.py]"]
  node_vocab["Token vocabularies"]
  node_trainer["Training engine<br/>[trainer.py]"]
  node_fine_tune["Task fine-tuning<br/>[run_trainer.py]"]
  node_pretrain["Model pretraining<br/>[run_pretrain.py]"]
  node_checkpoints["Model checkpoints"]
end

subgraph group_data["Data and evaluation"]
  node_dataset["Task datasets<br/>[data_utils.py]"]
  node_evaluation["Prediction evaluation<br/>[evaluation.py]"]
  node_split_data["Ensemble data splitting<br/>[ensemble.py]"]
  node_split_legacy["Legacy data splitting<br/>[ensemble_old.py]"]
  node_convert_data["Seq2seq conversion"]
  node_data_helpers["Molecular data utilities<br/>[utils.py]"]
end

subgraph group_analysis["Interpretation"]
  node_shap["SHAP interpretation<br/>[shap_pka.py]"]
  node_shap_data["SHAP analysis script<br/>[shap_pka.py]"]
end

node_user(("Researcher"))

node_user -->|"starts task"| node_dispatcher
node_dispatcher -->|"dispatches prediction"| node_predict
node_predict -->|"uses"| node_tokenizers
node_predict -->|"builds batches"| node_dataset
node_predict -->|"runs inference"| node_model
node_predict -->|"writes predictions"| node_result
node_ensemble_predict -->|"uses"| node_tokenizers
node_ensemble_predict -->|"builds batches"| node_dataset
node_ensemble_predict -->|"runs inference"| node_model
node_ensemble_predict -->|"writes predictions"| node_result
node_tokenizers -->|"loads vocabulary"| node_vocab
node_predict -->|"uses metrics"| node_evaluation
node_result -->|"evaluates"| node_evaluation
node_dispatcher -->|"dispatches training"| node_fine_tune
node_fine_tune -->|"loads task data"| node_dataset
node_fine_tune -->|"constructs tokenizer"| node_tokenizers
node_fine_tune -->|"configures model"| node_model
node_fine_tune -.->|"trains model"| node_trainer
node_fine_tune -->|"saves checkpoints"| node_checkpoints
node_dispatcher -->|"dispatches pretraining"| node_pretrain
node_pretrain -->|"loads pretrain data"| node_dataset
node_pretrain -->|"constructs tokenizer"| node_tokenizers
node_pretrain -->|"configures model"| node_model
node_pretrain -.->|"trains model"| node_trainer
node_pretrain -->|"saves checkpoints"| node_checkpoints
node_split_data -->|"uses utilities"| node_data_helpers
node_split_legacy -->|"uses utilities"| node_data_helpers
node_shap -->|"explains predictions"| node_model
node_shap -->|"uses"| node_tokenizers
node_shap_data -->|"uses model"| node_model
node_shap_data -->|"uses"| node_tokenizers

click node_dispatcher "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/__main__.py"
click node_predict "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_prediction.py"
click node_ensemble_predict "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/ensemble_prediction.py"
click node_tokenizers "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/mol_tokenizers.py"
click node_model "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/model.py"
click node_dataset "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/data_utils.py"
click node_vocab "https://github.com/charlotteinfante/t5pka/tree/main/t5pka/vocab"
click node_evaluation "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/evaluation.py"
click node_trainer "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/trainer.py"
click node_fine_tune "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_trainer.py"
click node_pretrain "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_pretrain.py"
click node_split_data "https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/ensemble.py"
click node_split_legacy "https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/ensemble_old.py"
click node_convert_data "https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/seq2seq_to_micropka.py"
click node_data_helpers "https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/utils.py"
click node_shap "https://github.com/charlotteinfante/t5pka/blob/main/t5pka/shap_pka.py"
click node_shap_data "https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/shap_pka.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_dispatcher,node_predict,node_ensemble_predict,node_result toneBlue
class node_tokenizers,node_model,node_vocab,node_trainer,node_fine_tune,node_pretrain,node_checkpoints toneAmber
class node_dataset,node_evaluation,node_split_data,node_split_legacy,node_convert_data,node_data_helpers toneMint
class node_shap,node_shap_data toneRose
class node_user toneIndigo
```

## Components

### Prediction

- [CLI dispatcher](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/__main__.py): `t5pka/__main__.py`
- [Prediction runner](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_prediction.py): `t5pka/run_prediction.py`
- [Ensemble prediction](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/ensemble_prediction.py): `t5pka/ensemble_prediction.py`
- **Prediction files**

### Modeling

- [Molecule tokenizers](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/mol_tokenizers.py): `t5pka/mol_tokenizers.py`
- [T5 model](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/model.py): `t5pka/model.py`
- [Token vocabularies](https://github.com/charlotteinfante/t5pka/tree/main/t5pka/vocab): `t5pka/vocab`
- [Training engine](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/trainer.py): `t5pka/trainer.py`
- [Task fine-tuning](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_trainer.py): `t5pka/run_trainer.py`
- [Model pretraining](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/run_pretrain.py): `t5pka/run_pretrain.py`
- **Model checkpoints**

### Data and evaluation

- [Task datasets](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/data_utils.py): `t5pka/data_utils.py`
- [Prediction evaluation](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/evaluation.py): `t5pka/evaluation.py`
- [Ensemble data splitting](https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/ensemble.py): `data_scripts/ensemble.py`
- [Legacy data splitting](https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/ensemble_old.py): `data_scripts/ensemble_old.py`
- [Seq2seq conversion](https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/seq2seq_to_micropka.py): `data_scripts/seq2seq_to_micropka.py`
- [Molecular data utilities](https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/utils.py): `data_scripts/utils.py`

### Interpretation

- [SHAP interpretation](https://github.com/charlotteinfante/t5pka/blob/main/t5pka/shap_pka.py): `t5pka/shap_pka.py`
- [SHAP analysis script](https://github.com/charlotteinfante/t5pka/blob/main/data_scripts/shap_pka.py): `data_scripts/shap_pka.py`

### Other components

- **Researcher**

## Connections

- Researcher → CLI dispatcher: starts task (evidence: `README.md`)
- CLI dispatcher → Prediction runner: dispatches prediction (evidence: `t5pka/__main__.py`)
- Prediction runner → Molecule tokenizers: uses (evidence: `t5pka/run_prediction.py`)
- Prediction runner → Task datasets: builds batches (evidence: `t5pka/run_prediction.py`)
- Prediction runner → T5 model: runs inference (evidence: `t5pka/run_prediction.py`)
- Prediction runner → Prediction files: writes predictions (evidence: `README.md`)
- Ensemble prediction → Molecule tokenizers: uses (evidence: `t5pka/ensemble_prediction.py`)
- Ensemble prediction → Task datasets: builds batches (evidence: `t5pka/ensemble_prediction.py`)
- Ensemble prediction → T5 model: runs inference (evidence: `t5pka/ensemble_prediction.py`)
- Ensemble prediction → Prediction files: writes predictions (evidence: `README.md`)
- Molecule tokenizers → Token vocabularies: loads vocabulary (evidence: `t5pka/mol_tokenizers.py`)
- Prediction runner → Prediction evaluation: uses metrics (evidence: `t5pka/run_prediction.py`)
- Prediction files → Prediction evaluation: evaluates (evidence: `t5pka/evaluation.py`)
- CLI dispatcher → Task fine-tuning: dispatches training (evidence: `t5pka/__main__.py`)
- Task fine-tuning → Task datasets: loads task data (evidence: `t5pka/run_trainer.py`)
- Task fine-tuning → Molecule tokenizers: constructs tokenizer (evidence: `t5pka/run_trainer.py`)
- Task fine-tuning → T5 model: configures model (evidence: `t5pka/run_trainer.py`)
- Task fine-tuning → Training engine: trains model (evidence: `t5pka/run_trainer.py`)
- Task fine-tuning → Model checkpoints: saves checkpoints (evidence: `t5pka/run_trainer.py`)
- CLI dispatcher → Model pretraining: dispatches pretraining (evidence: `t5pka/__main__.py`)
- Model pretraining → Task datasets: loads pretrain data (evidence: `t5pka/run_pretrain.py`)
- Model pretraining → Molecule tokenizers: constructs tokenizer (evidence: `t5pka/run_pretrain.py`)
- Model pretraining → T5 model: configures model (evidence: `t5pka/run_pretrain.py`)
- Model pretraining → Training engine: trains model (evidence: `t5pka/run_pretrain.py`)
- Model pretraining → Model checkpoints: saves checkpoints (evidence: `t5pka/run_pretrain.py`)
- Ensemble data splitting → Molecular data utilities: uses utilities (evidence: `data_scripts/ensemble.py`)
- Legacy data splitting → Molecular data utilities: uses utilities (evidence: `data_scripts/ensemble_old.py`)
- SHAP interpretation → T5 model: explains predictions (evidence: `t5pka/shap_pka.py`)
- SHAP interpretation → Molecule tokenizers: uses (evidence: `t5pka/shap_pka.py`)
- SHAP analysis script → T5 model: uses model (evidence: `data_scripts/shap_pka.py`)
- SHAP analysis script → Molecule tokenizers: uses (evidence: `data_scripts/shap_pka.py`)
