# sarseej-shrestha/lungnoduleclassification architecture

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

## Overview

This repository implements a lung-nodule classification research workflow over LIDC-IDRI CT scans: prepare nodule-centered positive and hard-negative samples, split patients to avoid leakage, train a three-view classifier, and assess predictions and saliency. The checked-in split and output artifacts reflect this workflow. Source excerpts document preprocessing, dataset loading, training, inference metrics, and Grad-CAM; links for unsampled behavior are limited to what the tree and these excerpts support.

Main entry points: [`src/config.py`](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/config.py) (Configuration), [`src/train.py`](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/train.py) (Fold training), [`src/evaluate.py`](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/evaluate.py) (Model evaluation), [`src/gradcam.py`](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/gradcam.py) (Grad-CAM analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_preprocess["Sample extraction<br/>[preprocess.py]"]
  node_samples["Preprocessed samples"]
  node_splitter["Patient stratification<br/>[splits.py]"]
  node_splitdata["Patient splits"]
  node_dataset["Dataset loading<br/>[dataset.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_learning["Model training"]
  node_trainer["Fold training<br/>[train.py]"]
  node_classifier["Three-view classifier<br/>[model.py]"]
  node_checkpoints["Model checkpoints"]
end

subgraph group_assessment["Assessment"]
  node_evaluator["Model evaluation<br/>[evaluate.py]"]
  node_metrics["Evaluation reports"]
  node_gradcam["Grad-CAM analysis<br/>[gradcam.py]"]
  node_visuals["Saliency overlays"]
end

node_researcher(("Researcher"))
node_ctdata["CT scans"]

node_researcher -->|"runs extraction"| node_preprocess
node_ctdata -->|"provides scans"| node_preprocess
node_preprocess -->|"writes samples"| node_samples
node_researcher -->|"builds splits"| node_splitter
node_splitter -->|"writes patients"| node_splitdata
node_trainer -->|"loads batches"| node_dataset
node_dataset -->|"reads samples"| node_samples
node_dataset -->|"loads splits"| node_splitdata
node_trainer -->|"trains model"| node_classifier
node_trainer -->|"saves checkpoint"| node_checkpoints
node_trainer -->|"writes history"| node_metrics
node_evaluator -->|"loads samples"| node_dataset
node_evaluator -->|"runs inference"| node_classifier
node_evaluator -->|"loads checkpoint"| node_checkpoints
node_evaluator -->|"writes report"| node_metrics
node_gradcam -->|"loads samples"| node_dataset
node_gradcam -->|"computes saliency"| node_classifier
node_gradcam -->|"loads checkpoint"| node_checkpoints
node_gradcam -->|"writes overlays"| node_visuals
node_config -->|"sets parameters"| node_preprocess
node_config -->|"sets parameters"| node_trainer
node_config -->|"sets parameters"| node_classifier
node_config -->|"sets parameters"| node_evaluator
node_config -->|"sets parameters"| node_gradcam

click node_preprocess "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/preprocess.py"
click node_samples "https://github.com/sarseej-shrestha/lungnoduleclassification/tree/main/input/subset6"
click node_splitter "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/splits.py"
click node_splitdata "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/input/splits/patient_splits.json"
click node_dataset "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/dataset.py"
click node_config "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/config.py"
click node_trainer "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/train.py"
click node_classifier "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/model.py"
click node_evaluator "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/evaluate.py"
click node_metrics "https://github.com/sarseej-shrestha/lungnoduleclassification/tree/main/output"
click node_gradcam "https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/gradcam.py"
click node_visuals "https://github.com/sarseej-shrestha/lungnoduleclassification/tree/main/output/gradcam"

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_preprocess,node_samples,node_splitter,node_splitdata,node_dataset,node_config toneBlue
class node_trainer,node_classifier,node_checkpoints toneAmber
class node_evaluator,node_metrics,node_gradcam,node_visuals toneMint
class node_researcher,node_ctdata toneIndigo
```

## Components

### Data preparation

- [Sample extraction](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/preprocess.py): `src/preprocess.py`
- [Preprocessed samples](https://github.com/sarseej-shrestha/lungnoduleclassification/tree/main/input/subset6): `input/subset6`
- [Patient stratification](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/splits.py): `src/splits.py`
- [Patient splits](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/input/splits/patient_splits.json): `input/splits/patient_splits.json`
- [Dataset loading](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/dataset.py): `src/dataset.py`
- [Configuration](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/config.py): `src/config.py`

### Model training

- [Fold training](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/train.py): `src/train.py`
- [Three-view classifier](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/model.py): `src/model.py`
- **Model checkpoints**

### Assessment

- [Model evaluation](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/evaluate.py): `src/evaluate.py`
- [Evaluation reports](https://github.com/sarseej-shrestha/lungnoduleclassification/tree/main/output): `output`
- [Grad-CAM analysis](https://github.com/sarseej-shrestha/lungnoduleclassification/blob/main/src/gradcam.py): `src/gradcam.py`
- [Saliency overlays](https://github.com/sarseej-shrestha/lungnoduleclassification/tree/main/output/gradcam): `output/gradcam`

### Other components

- **Researcher**
- **CT scans**

## Connections

- Researcher → Sample extraction: runs extraction
- CT scans → Sample extraction: provides scans
- Sample extraction → Preprocessed samples: writes samples
- Researcher → Patient stratification: builds splits
- Patient stratification → Patient splits: writes patients
- Fold training → Dataset loading: loads batches
- Dataset loading → Preprocessed samples: reads samples
- Dataset loading → Patient splits: loads splits
- Fold training → Three-view classifier: trains model
- Fold training → Model checkpoints: saves checkpoint
- Fold training → Evaluation reports: writes history
- Model evaluation → Dataset loading: loads samples
- Model evaluation → Three-view classifier: runs inference
- Model evaluation → Model checkpoints: loads checkpoint
- Model evaluation → Evaluation reports: writes report
- Grad-CAM analysis → Dataset loading: loads samples
- Grad-CAM analysis → Three-view classifier: computes saliency
- Grad-CAM analysis → Model checkpoints: loads checkpoint
- Grad-CAM analysis → Saliency overlays: writes overlays
- Configuration → Sample extraction: sets parameters
- Configuration → Fold training: sets parameters
- Configuration → Three-view classifier: sets parameters
- Configuration → Model evaluation: sets parameters
- Configuration → Grad-CAM analysis: sets parameters