# gangcai/scageclock architecture

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

## Overview

scAgeClock is a single-cell transcriptome age-prediction and model-training package. Its main workflow formats AnnData inputs, loads cells and age labels from H5AD files, trains or loads an aging-clock model, and returns per-cell age predictions for evaluation or export. The README also documents cross-validation, alternate model families, GMA feature importance, Monte Carlo dropout prediction, and plotting. The excerpts confirm key loader, model, orchestration, and prediction behavior; links for other documented capabilities are limited to their supported module paths.

Main entry points: [`scageclock/scAgeClock.py`](https://github.com/gangcai/scageclock/blob/main/scageclock/scAgeClock.py) (Training pipeline), [`scageclock/evaluation.py`](https://github.com/gangcai/scageclock/blob/main/scageclock/evaluation.py) (Prediction), [`scageclock/formatting.py`](https://github.com/gangcai/scageclock/blob/main/scageclock/formatting.py) (AnnData formatting), [`data/pytest_data`](https://github.com/gangcai/scageclock/tree/main/data/pytest_data) (H5AD datasets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input preparation"]
  node_formatting["AnnData formatting<br/>[formatting.py]"]
  node_prepare["Input preparation<br/>[prepare_inputs.py]"]
  node_feature_metadata["Feature metadata<br/>[h5ad_var.tsv]"]
  node_h5ad_files["H5AD datasets"]
  node_loader["Dataset loader<br/>[dataloader.py]"]
  node_h5ad_loader["H5AD sampling<br/>[h5ad_dataloader.py]"]
end

subgraph group_workflow["Training and prediction"]
  node_cli["CLI<br/>[cli.py]"]
  node_pipeline["Training pipeline<br/>[scAgeClock.py]"]
  node_evaluation["Prediction<br/>[evaluation.py]"]
end

subgraph group_models["Aging clock models"]
  node_gma["Gated attention"]
  node_ablation["GMA ablation"]
  node_mlp["MLP and linear<br/>[MLP.py]"]
  node_linear["Linear model<br/>[Linear.py]"]
  node_boosted["Boosted trees<br/>[XGBoost.py]"]
  node_catboost["CatBoost<br/>[CatBoost.py]"]
  node_autoencoder["Autoencoder model<br/>[autoencoder.py]"]
  node_model_weights["Trained weights"]
end

subgraph group_results["Evaluation and results"]
  node_metrics["Validation metrics<br/>[utility.py]"]
  node_visualization["Plots and importance<br/>[visualization.py]"]
  node_results_file["Prediction results"]
end

node_user(("Researcher"))

node_user -->|"formats data"| node_formatting
node_formatting -->|"prepares inputs"| node_prepare
node_feature_metadata -->|"defines features"| node_formatting
node_user -->|"runs prediction"| node_cli
node_cli -->|"invokes"| node_evaluation
node_user -->|"starts training"| node_pipeline
node_h5ad_files -->|"provides cells"| node_loader
node_prepare -->|"writes formatted data"| node_h5ad_files
node_pipeline -->|"configures datasets"| node_loader
node_loader -->|"loads batches"| node_h5ad_loader
node_pipeline -->|"selects model"| node_gma
node_pipeline -->|"selects model"| node_ablation
node_pipeline -->|"selects model"| node_mlp
node_pipeline -->|"selects model"| node_linear
node_pipeline -->|"selects model"| node_boosted
node_pipeline -->|"selects model"| node_catboost
node_pipeline -->|"selects model"| node_autoencoder
node_evaluation -->|"loads weights"| node_model_weights
node_evaluation -->|"reads datasets"| node_h5ad_files
node_evaluation -->|"returns predictions"| node_results_file
node_pipeline -->|"computes metrics"| node_metrics
node_pipeline -->|"requests plots"| node_visualization
node_evaluation -.->|"plots performance"| node_visualization
node_user -->|"receives results"| node_results_file

click node_cli "https://github.com/gangcai/scageclock/blob/main/scageclock/cli.py"
click node_formatting "https://github.com/gangcai/scageclock/blob/main/scageclock/formatting.py"
click node_prepare "https://github.com/gangcai/scageclock/blob/main/scageclock/prepare_inputs.py"
click node_feature_metadata "https://github.com/gangcai/scageclock/blob/main/data/metadata/h5ad_var.tsv"
click node_h5ad_files "https://github.com/gangcai/scageclock/tree/main/data/pytest_data"
click node_loader "https://github.com/gangcai/scageclock/blob/main/scageclock/dataloader.py"
click node_h5ad_loader "https://github.com/gangcai/scageclock/blob/main/scageclock/h5ad_dataloader.py"
click node_pipeline "https://github.com/gangcai/scageclock/blob/main/scageclock/scAgeClock.py"
click node_evaluation "https://github.com/gangcai/scageclock/blob/main/scageclock/evaluation.py"
click node_gma "https://github.com/gangcai/scageclock/blob/main/scageclock/model/GatedMultiheadAttention.py"
click node_ablation "https://github.com/gangcai/scageclock/blob/main/scageclock/model/GatedMultiheadAttention_Ablation.py"
click node_mlp "https://github.com/gangcai/scageclock/blob/main/scageclock/model/MLP.py"
click node_linear "https://github.com/gangcai/scageclock/blob/main/scageclock/model/Linear.py"
click node_boosted "https://github.com/gangcai/scageclock/blob/main/scageclock/model/XGBoost.py"
click node_catboost "https://github.com/gangcai/scageclock/blob/main/scageclock/model/CatBoost.py"
click node_autoencoder "https://github.com/gangcai/scageclock/blob/main/scageclock/model/autoencoder.py"
click node_metrics "https://github.com/gangcai/scageclock/blob/main/scageclock/utility.py"
click node_visualization "https://github.com/gangcai/scageclock/blob/main/scageclock/visualization.py"
click node_model_weights "https://github.com/gangcai/scageclock/blob/main/data/trained_models/scAgeClock_GMA_model_state_dict.pth"

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_formatting,node_prepare,node_feature_metadata,node_h5ad_files,node_loader,node_h5ad_loader toneBlue
class node_cli,node_pipeline,node_evaluation toneAmber
class node_gma,node_ablation,node_mlp,node_linear,node_boosted,node_catboost,node_autoencoder,node_model_weights toneMint
class node_metrics,node_visualization,node_results_file toneRose
class node_user toneIndigo
```

## Components

### Input preparation

- [AnnData formatting](https://github.com/gangcai/scageclock/blob/main/scageclock/formatting.py): `scageclock/formatting.py`
- [Input preparation](https://github.com/gangcai/scageclock/blob/main/scageclock/prepare_inputs.py): `scageclock/prepare_inputs.py`
- [Feature metadata](https://github.com/gangcai/scageclock/blob/main/data/metadata/h5ad_var.tsv): `data/metadata/h5ad_var.tsv`
- [H5AD datasets](https://github.com/gangcai/scageclock/tree/main/data/pytest_data): `data/pytest_data`
- [Dataset loader](https://github.com/gangcai/scageclock/blob/main/scageclock/dataloader.py): `scageclock/dataloader.py`
- [H5AD sampling](https://github.com/gangcai/scageclock/blob/main/scageclock/h5ad_dataloader.py): `scageclock/h5ad_dataloader.py`

### Training and prediction

- [CLI](https://github.com/gangcai/scageclock/blob/main/scageclock/cli.py): `scageclock/cli.py`
- [Training pipeline](https://github.com/gangcai/scageclock/blob/main/scageclock/scAgeClock.py): `scageclock/scAgeClock.py`
- [Prediction](https://github.com/gangcai/scageclock/blob/main/scageclock/evaluation.py): `scageclock/evaluation.py`

### Aging clock models

- [Gated attention](https://github.com/gangcai/scageclock/blob/main/scageclock/model/GatedMultiheadAttention.py): `scageclock/model/GatedMultiheadAttention.py`
- [GMA ablation](https://github.com/gangcai/scageclock/blob/main/scageclock/model/GatedMultiheadAttention_Ablation.py): `scageclock/model/GatedMultiheadAttention_Ablation.py`
- [MLP and linear](https://github.com/gangcai/scageclock/blob/main/scageclock/model/MLP.py): `scageclock/model/MLP.py`
- [Linear model](https://github.com/gangcai/scageclock/blob/main/scageclock/model/Linear.py): `scageclock/model/Linear.py`
- [Boosted trees](https://github.com/gangcai/scageclock/blob/main/scageclock/model/XGBoost.py): `scageclock/model/XGBoost.py`
- [CatBoost](https://github.com/gangcai/scageclock/blob/main/scageclock/model/CatBoost.py): `scageclock/model/CatBoost.py`
- [Autoencoder model](https://github.com/gangcai/scageclock/blob/main/scageclock/model/autoencoder.py): `scageclock/model/autoencoder.py`
- [Trained weights](https://github.com/gangcai/scageclock/blob/main/data/trained_models/scAgeClock_GMA_model_state_dict.pth): `data/trained_models/scAgeClock_GMA_model_state_dict.pth`

### Evaluation and results

- [Validation metrics](https://github.com/gangcai/scageclock/blob/main/scageclock/utility.py): `scageclock/utility.py`
- [Plots and importance](https://github.com/gangcai/scageclock/blob/main/scageclock/visualization.py): `scageclock/visualization.py`
- **Prediction results**

### Other components

- **Researcher**

## Connections

- Researcher → AnnData formatting: formats data
- AnnData formatting → Input preparation: prepares inputs
- Feature metadata → AnnData formatting: defines features
- Researcher → CLI: runs prediction
- CLI → Prediction: invokes
- Researcher → Training pipeline: starts training
- H5AD datasets → Dataset loader: provides cells
- Input preparation → H5AD datasets: writes formatted data
- Training pipeline → Dataset loader: configures datasets
- Dataset loader → H5AD sampling: loads batches
- Training pipeline → Gated attention: selects model
- Training pipeline → GMA ablation: selects model
- Training pipeline → MLP and linear: selects model
- Training pipeline → Linear model: selects model
- Training pipeline → Boosted trees: selects model
- Training pipeline → CatBoost: selects model
- Training pipeline → Autoencoder model: selects model
- Prediction → Trained weights: loads weights
- Prediction → H5AD datasets: reads datasets
- Prediction → Prediction results: returns predictions
- Training pipeline → Validation metrics: computes metrics
- Training pipeline → Plots and importance: requests plots
- Prediction → Plots and importance: plots performance
- Researcher → Prediction results: receives results