# djcrocker/caliva architecture

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

- Interactive diagram: https://gitdiagram.com/djcrocker/caliva
- Repository: https://github.com/djcrocker/caliva

## Overview

CALIVA is a missense-variant pathogenicity predictor that turns ClinVar-labeled variants and protein data into structural and sequence features, trains graph and boosted-tree models, and produces calibrated probability predictions. The documented rebuild workflow runs from local cohort and structure preparation through feature generation and graph assembly; training and scoring consume those representations. Other product branches fetch and compare reference-predictor scores, calibrate and evaluate predictions, and analyze model interpretation and errors. Some links are documented in the README rather than shown in sampled source; uncertain implementation links are omitted.

Main entry points: [`src/ml/score_full_cohort.py`](https://github.com/djcrocker/caliva/blob/main/src/ml/score_full_cohort.py) (Cohort scoring), [`src/ml/graph_dataset.py`](https://github.com/djcrocker/caliva/blob/main/src/ml/graph_dataset.py) (Graph dataset), [`src/features/generate_graphs.py`](https://github.com/djcrocker/caliva/blob/main/src/features/generate_graphs.py) (Graph assembly), [`src/ml/train_gnn.py`](https://github.com/djcrocker/caliva/blob/main/src/ml/train_gnn.py) (GNN training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Cohort preparation"]
  node_cohort["Cohort builder<br/>[build_cohort.py]"]
  node_structures["Structure and FoldX prep<br/>[run_foldx.py]"]
  node_integrity["Integrity checks"]
end

subgraph group_features["Protein features"]
  node_esm["ESM embeddings"]
  node_conservation["MSA conservation"]
  node_feature_extract["Variant features"]
  node_interface["Interface features"]
  node_graphs["Graph assembly<br/>[generate_graphs.py]"]
end

subgraph group_models["Modeling"]
  node_graph_data["Graph dataset<br/>[graph_dataset.py]"]
  node_gnn["GNN architectures<br/>[gnn_model.py]"]
  node_gnn_train["GNN training<br/>[train_gnn.py]"]
  node_tree_train["Boosted-tree training"]
  node_ensemble["Ensemble selection"]
  node_scoring["Cohort scoring"]
end

subgraph group_analysis["Calibration and analysis"]
  node_references["Reference score collection"]
  node_comparison["External comparison"]
  node_calibration["Probability calibration"]
  node_acmg["ACMG calibration"]
  node_evaluation["Model evaluation<br/>[evaluate_model.py]"]
  node_interpretation["SHAP interpretation<br/>[shap_analysis.py]"]
  node_error_analysis["Error analysis<br/>[error_analysis.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"prepares cohort"| node_cohort
node_cohort -->|"precedes prep"| node_structures
node_structures -->|"supplies structure features"| node_feature_extract
node_cohort -->|"supplies cohort data"| node_feature_extract
node_feature_extract -->|"provides variant features"| node_graphs
node_esm -->|"adds embeddings"| node_graphs
node_conservation -->|"adds conservation"| node_graphs
node_interface -->|"adds annotations"| node_graphs
node_graphs -->|"loads graph files"| node_graph_data
node_graph_data -->|"provides training data"| node_gnn_train
node_graph_data -->|"provides training data"| node_tree_train
node_gnn_train -->|"trains architecture"| node_gnn
node_gnn_train -->|"uses dataset"| node_graph_data
node_tree_train -->|"uses dataset"| node_graph_data
node_ensemble -->|"selects ensemble members"| node_gnn_train
node_ensemble -->|"selects ensemble members"| node_tree_train
node_ensemble -.->|"supports deployed scoring"| node_scoring
node_scoring -->|"supplies CALIVA predictions"| node_comparison
node_references -.->|"supplies reference scores"| node_comparison
node_scoring -->|"temperature scales scores"| node_calibration
node_calibration -->|"calibrates probabilities"| node_acmg
node_scoring -.->|"evaluates predictions"| node_evaluation
node_tree_train -->|"explains tree model"| node_interpretation
node_scoring -.->|"supports error review"| node_error_analysis
node_structures -.->|"checks outputs"| node_integrity

click node_cohort "https://github.com/djcrocker/caliva/blob/main/src/local/build_cohort.py"
click node_structures "https://github.com/djcrocker/caliva/blob/main/src/local/run_foldx.py"
click node_integrity "https://github.com/djcrocker/caliva/blob/main/src/local/verify_integrity.py"
click node_esm "https://github.com/djcrocker/caliva/blob/main/src/features/generate_esm_embeddings.py"
click node_conservation "https://github.com/djcrocker/caliva/blob/main/src/features/conservation_features.py"
click node_feature_extract "https://github.com/djcrocker/caliva/blob/main/src/features/extract_features.py"
click node_interface "https://github.com/djcrocker/caliva/blob/main/src/features/interface_features.py"
click node_graphs "https://github.com/djcrocker/caliva/blob/main/src/features/generate_graphs.py"
click node_graph_data "https://github.com/djcrocker/caliva/blob/main/src/ml/graph_dataset.py"
click node_gnn "https://github.com/djcrocker/caliva/blob/main/src/ml/gnn_model.py"
click node_gnn_train "https://github.com/djcrocker/caliva/blob/main/src/ml/train_gnn.py"
click node_tree_train "https://github.com/djcrocker/caliva/blob/main/src/ml/train_ensemble_gbdt.py"
click node_ensemble "https://github.com/djcrocker/caliva/blob/main/src/ml/find_best_ensemble.py"
click node_scoring "https://github.com/djcrocker/caliva/blob/main/src/ml/score_full_cohort.py"
click node_references "https://github.com/djcrocker/caliva/blob/main/src/external/fetch_alphamissense.py"
click node_comparison "https://github.com/djcrocker/caliva/blob/main/src/external/external_comparison.py"
click node_calibration "https://github.com/djcrocker/caliva/blob/main/src/external/temperature_scale.py"
click node_acmg "https://github.com/djcrocker/caliva/blob/main/src/external/acmg_calibration.py"
click node_evaluation "https://github.com/djcrocker/caliva/blob/main/src/ml/evaluate_model.py"
click node_interpretation "https://github.com/djcrocker/caliva/blob/main/src/stats/shap_analysis.py"
click node_error_analysis "https://github.com/djcrocker/caliva/blob/main/src/stats/error_analysis.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_cohort,node_structures,node_integrity toneBlue
class node_esm,node_conservation,node_feature_extract,node_interface,node_graphs toneAmber
class node_graph_data,node_gnn,node_gnn_train,node_tree_train,node_ensemble,node_scoring toneMint
class node_references,node_comparison,node_calibration,node_acmg,node_evaluation,node_interpretation,node_error_analysis toneRose
class node_researcher toneIndigo
```

## Components

### Cohort preparation

- [Cohort builder](https://github.com/djcrocker/caliva/blob/main/src/local/build_cohort.py): `src/local/build_cohort.py`
- [Structure and FoldX prep](https://github.com/djcrocker/caliva/blob/main/src/local/run_foldx.py): `src/local/run_foldx.py`
- [Integrity checks](https://github.com/djcrocker/caliva/blob/main/src/local/verify_integrity.py): `src/local/verify_integrity.py`

### Protein features

- [ESM embeddings](https://github.com/djcrocker/caliva/blob/main/src/features/generate_esm_embeddings.py): `src/features/generate_esm_embeddings.py`
- [MSA conservation](https://github.com/djcrocker/caliva/blob/main/src/features/conservation_features.py): `src/features/conservation_features.py`
- [Variant features](https://github.com/djcrocker/caliva/blob/main/src/features/extract_features.py): `src/features/extract_features.py`
- [Interface features](https://github.com/djcrocker/caliva/blob/main/src/features/interface_features.py): `src/features/interface_features.py`
- [Graph assembly](https://github.com/djcrocker/caliva/blob/main/src/features/generate_graphs.py): `src/features/generate_graphs.py`

### Modeling

- [Graph dataset](https://github.com/djcrocker/caliva/blob/main/src/ml/graph_dataset.py): `src/ml/graph_dataset.py`
- [GNN architectures](https://github.com/djcrocker/caliva/blob/main/src/ml/gnn_model.py): `src/ml/gnn_model.py`
- [GNN training](https://github.com/djcrocker/caliva/blob/main/src/ml/train_gnn.py): `src/ml/train_gnn.py`
- [Boosted-tree training](https://github.com/djcrocker/caliva/blob/main/src/ml/train_ensemble_gbdt.py): `src/ml/train_ensemble_gbdt.py`
- [Ensemble selection](https://github.com/djcrocker/caliva/blob/main/src/ml/find_best_ensemble.py): `src/ml/find_best_ensemble.py`
- [Cohort scoring](https://github.com/djcrocker/caliva/blob/main/src/ml/score_full_cohort.py): `src/ml/score_full_cohort.py`

### Calibration and analysis

- [Reference score collection](https://github.com/djcrocker/caliva/blob/main/src/external/fetch_alphamissense.py): `src/external/fetch_alphamissense.py`
- [External comparison](https://github.com/djcrocker/caliva/blob/main/src/external/external_comparison.py): `src/external/external_comparison.py`
- [Probability calibration](https://github.com/djcrocker/caliva/blob/main/src/external/temperature_scale.py): `src/external/temperature_scale.py`
- [ACMG calibration](https://github.com/djcrocker/caliva/blob/main/src/external/acmg_calibration.py): `src/external/acmg_calibration.py`
- [Model evaluation](https://github.com/djcrocker/caliva/blob/main/src/ml/evaluate_model.py): `src/ml/evaluate_model.py`
- [SHAP interpretation](https://github.com/djcrocker/caliva/blob/main/src/stats/shap_analysis.py): `src/stats/shap_analysis.py`
- [Error analysis](https://github.com/djcrocker/caliva/blob/main/src/stats/error_analysis.py): `src/stats/error_analysis.py`

### Other components

- **Researcher**

## Connections

- Researcher → Cohort builder: prepares cohort (evidence: `README.md`)
- Cohort builder → Structure and FoldX prep: precedes prep (evidence: `README.md`)
- Structure and FoldX prep → Variant features: supplies structure features (evidence: `README.md`)
- Cohort builder → Variant features: supplies cohort data (evidence: `README.md`)
- Variant features → Graph assembly: provides variant features (evidence: `src/features/generate_graphs.py`)
- ESM embeddings → Graph assembly: adds embeddings (evidence: `src/features/generate_graphs.py`)
- MSA conservation → Graph assembly: adds conservation (evidence: `src/features/generate_graphs.py`)
- Interface features → Graph assembly: adds annotations (evidence: `README.md`)
- Graph assembly → Graph dataset: loads graph files (evidence: `src/ml/graph_dataset.py`)
- Graph dataset → GNN training: provides training data (evidence: `src/ml/train_gnn.py`)
- Graph dataset → Boosted-tree training: provides training data (evidence: `src/ml/train_ensemble_gbdt.py`)
- GNN training → GNN architectures: trains architecture (evidence: `src/ml/train_gnn.py`)
- GNN training → Graph dataset: uses dataset (evidence: `src/ml/train_gnn.py`)
- Boosted-tree training → Graph dataset: uses dataset (evidence: `src/ml/train_ensemble_gbdt.py`)
- Ensemble selection → GNN training: selects ensemble members (evidence: `src/ml/find_best_ensemble.py`)
- Ensemble selection → Boosted-tree training: selects ensemble members (evidence: `src/ml/find_best_ensemble.py`)
- Ensemble selection → Cohort scoring: supports deployed scoring
- Cohort scoring → External comparison: supplies CALIVA predictions (evidence: `src/external/external_comparison.py`)
- Reference score collection → External comparison: supplies reference scores
- Cohort scoring → Probability calibration: temperature scales scores (evidence: `README.md`)
- Probability calibration → ACMG calibration: calibrates probabilities (evidence: `src/external/acmg_calibration.py`)
- Cohort scoring → Model evaluation: evaluates predictions
- Boosted-tree training → SHAP interpretation: explains tree model (evidence: `src/stats/shap_analysis.py`)
- Cohort scoring → Error analysis: supports error review
- Structure and FoldX prep → Integrity checks: checks outputs
