# mgi-lab/osocad-ncct-ssfm architecture

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

- Interactive diagram: https://gitdiagram.com/mgi-lab/osocad-ncct-ssfm
- Repository: https://github.com/mgi-lab/osocad-ncct-ssfm

## Overview

This repository packages a research classifier for opportunistic obstructive coronary artery disease screening on non-contrast chest CT, alongside approved aggregate publication results. The main user workflow is to train or load the classifier, run it on authorized local cohort images and labels, and inspect diagnostic outputs; separate utilities support statistical reanalysis and publication display/export. Patient-level data are not included. The map covers documented capabilities and source-index relationships; unsampled implementations and their detailed wiring are not assumed.

Main entry points: [`code/inference/eval_external.py`](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/inference/eval_external.py) (Cohort evaluation), [`code/metrics/diagnostic_statistics.py`](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/metrics/diagnostic_statistics.py) (Diagnostic statistics), [`code/training/train.py`](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/train.py) (Model training), [`code/plotting/build_github_english_release.py`](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/plotting/build_github_english_release.py) (Public display generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training"]
  node_training_data["Slice dataset<br/>[dataset.py]"]
  node_classifier["CT classifier<br/>[model.py]"]
  node_train["Model training<br/>[train.py]"]
  node_launch["Training launcher<br/>[launch.py]"]
  node_checkpoint["Packaged checkpoint<br/>[best.pth]"]
end

subgraph group_inference["Inference"]
  node_external_eval["Cohort evaluation<br/>[eval_external.py]"]
  node_table2_inference["Table 2 inference"]
end

subgraph group_analysis["Statistics and exports"]
  node_stats["Diagnostic statistics"]
  node_checkpoint_export["Checkpoint table export"]
  node_table_export["Manuscript table export"]
  node_excel_preview["Calcium figure previews"]
end

subgraph group_publication["Publication bundle"]
  node_approved_results["Approved aggregate results"]
  node_display_build["Public display generation"]
  node_submission_check["Bundle verification"]
  node_release_package["Release packaging<br/>[package_release.py]"]
  node_public_pages["README and index<br/>[README.md]"]
end

node_researcher(("Researcher"))
node_study_inputs["Local study inputs"]

node_researcher -->|"starts training"| node_launch
node_study_inputs -.->|"provides cohort data"| node_train
node_train -->|"uses dataset"| node_training_data
node_train -->|"trains model"| node_classifier
node_train -.->|"saves checkpoint"| node_checkpoint
node_researcher -->|"runs evaluation"| node_external_eval
node_study_inputs -->|"supplies local cohorts"| node_external_eval
node_external_eval -->|"uses dataset"| node_training_data
node_external_eval -->|"loads classifier"| node_classifier
node_external_eval -->|"computes metrics"| node_stats
node_researcher -->|"runs comparison"| node_table2_inference
node_table2_inference -->|"uses statistics"| node_stats
node_checkpoint_export -->|"uses statistics"| node_stats
node_table_export -->|"uses statistics"| node_stats
node_researcher -->|"exports tables"| node_table_export
node_researcher -->|"creates previews"| node_excel_preview
node_excel_preview -->|"uses statistics"| node_stats
node_researcher -->|"checks or refreshes"| node_display_build
node_approved_results -->|"renders displays"| node_display_build
node_display_build -->|"updates pages"| node_public_pages
node_researcher -->|"verifies bundle"| node_submission_check
node_researcher -->|"packages artifacts"| node_release_package
node_release_package -->|"validates bundle"| node_submission_check

click node_training_data "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/dataset.py"
click node_classifier "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/model.py"
click node_train "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/train.py"
click node_launch "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/launch.py"
click node_checkpoint "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/models/best.pth"
click node_external_eval "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/inference/eval_external.py"
click node_table2_inference "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/inference/infer_table2_diagnostic_performance.py"
click node_stats "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/metrics/diagnostic_statistics.py"
click node_checkpoint_export "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/metrics/export_checkpoint_table2_excel.py"
click node_table_export "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/plotting/export_manuscript_tables.py"
click node_excel_preview "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/plotting/redraw_calcium_sens_npv_from_excel.py"
click node_approved_results "https://github.com/mgi-lab/osocad-ncct-ssfm/tree/main/paper_plots"
click node_display_build "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/plotting/build_github_english_release.py"
click node_submission_check "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/validation/verify_submission.py"
click node_release_package "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/validation/package_release.py"
click node_public_pages "https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/README.md"

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_training_data,node_classifier,node_train,node_launch,node_checkpoint toneBlue
class node_external_eval,node_table2_inference toneAmber
class node_stats,node_checkpoint_export,node_table_export,node_excel_preview toneMint
class node_approved_results,node_display_build,node_submission_check,node_release_package,node_public_pages toneRose
class node_researcher,node_study_inputs toneIndigo
```

## Components

### Training

- [Slice dataset](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/dataset.py): `code/training/dataset.py`
- [CT classifier](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/model.py): `code/training/model.py`
- [Model training](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/train.py): `code/training/train.py`
- [Training launcher](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/training/launch.py): `code/training/launch.py`
- [Packaged checkpoint](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/models/best.pth): `models/best.pth`

### Inference

- [Cohort evaluation](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/inference/eval_external.py): `code/inference/eval_external.py`
- [Table 2 inference](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/inference/infer_table2_diagnostic_performance.py): `code/inference/infer_table2_diagnostic_performance.py`

### Statistics and exports

- [Diagnostic statistics](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/metrics/diagnostic_statistics.py): `code/metrics/diagnostic_statistics.py`
- [Checkpoint table export](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/metrics/export_checkpoint_table2_excel.py): `code/metrics/export_checkpoint_table2_excel.py`
- [Manuscript table export](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/plotting/export_manuscript_tables.py): `code/plotting/export_manuscript_tables.py`
- [Calcium figure previews](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/plotting/redraw_calcium_sens_npv_from_excel.py): `code/plotting/redraw_calcium_sens_npv_from_excel.py`

### Publication bundle

- [Approved aggregate results](https://github.com/mgi-lab/osocad-ncct-ssfm/tree/main/paper_plots): `paper_plots`
- [Public display generation](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/plotting/build_github_english_release.py): `code/plotting/build_github_english_release.py`
- [Bundle verification](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/validation/verify_submission.py): `code/validation/verify_submission.py`
- [Release packaging](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/code/validation/package_release.py): `code/validation/package_release.py`
- [README and index](https://github.com/mgi-lab/osocad-ncct-ssfm/blob/main/README.md): `README.md`

### Other components

- **Researcher**
- **Local study inputs**

## Connections

- Researcher → Training launcher: starts training (evidence: `README.md`)
- Local study inputs → Model training: provides cohort data
- Model training → Slice dataset: uses dataset (evidence: `code/training/train.py`)
- Model training → CT classifier: trains model (evidence: `code/training/train.py`)
- Model training → Packaged checkpoint: saves checkpoint
- Researcher → Cohort evaluation: runs evaluation (evidence: `README.md`)
- Local study inputs → Cohort evaluation: supplies local cohorts (evidence: `code/inference/eval_external.py`)
- Cohort evaluation → Slice dataset: uses dataset (evidence: `code/inference/eval_external.py`)
- Cohort evaluation → CT classifier: loads classifier (evidence: `code/inference/eval_external.py`)
- Cohort evaluation → Diagnostic statistics: computes metrics (evidence: `code/inference/eval_external.py`)
- Researcher → Table 2 inference: runs comparison (evidence: `README.md`)
- Table 2 inference → Diagnostic statistics: uses statistics (evidence: `code/inference/infer_table2_diagnostic_performance.py`)
- Checkpoint table export → Diagnostic statistics: uses statistics (evidence: `code/metrics/export_checkpoint_table2_excel.py`)
- Manuscript table export → Diagnostic statistics: uses statistics (evidence: `code/plotting/export_manuscript_tables.py`)
- Researcher → Manuscript table export: exports tables (evidence: `README.md`)
- Researcher → Calcium figure previews: creates previews (evidence: `README.md`)
- Calcium figure previews → Diagnostic statistics: uses statistics (evidence: `code/plotting/redraw_calcium_sens_npv_from_excel.py`)
- Researcher → Public display generation: checks or refreshes (evidence: `README.md`)
- Approved aggregate results → Public display generation: renders displays (evidence: `code/plotting/build_github_english_release.py`)
- Public display generation → README and index: updates pages (evidence: `code/plotting/build_github_english_release.py`)
- Researcher → Bundle verification: verifies bundle (evidence: `README.md`)
- Researcher → Release packaging: packages artifacts (evidence: `code/validation/package_release.py`)
- Release packaging → Bundle verification: validates bundle (evidence: `code/validation/package_release.py`)
