DenseNet121-based multi-label chest X-ray classification pipeline using the CheXpert-small dataset.

This repository is the research and experiment codebase for the capstone project.
The production web service is managed separately in capstone-cxr.

This project trains and evaluates a chest X-ray classification model for five CheXpert target findings:

• Atelectasis
• Cardiomegaly
• Consolidation
• Edema
• Pleural Effusion

The model predicts class-wise probabilities and supports Grad-CAM visualization for explainable inference.

This repository was developed as the research and model experimentation phase of the capstone project.

• CheXpert-small data loading
• Frontal-view-only training policy
• DenseNet121 multi-label classifier
• Uncertainty label policy comparison: U-Ignore, U-Ones, U-Zeros
• BCEWithLogitsLoss with pos_weight
• AUROC and AUPRC evaluation
• F1-based threshold tuning
• Image-level inference
• Grad-CAM visualization
• Reusable inference service functions for later migration

chexpert_poc/
├── chexpert_poc/
│ ├── common/ # config, runtime, shared utilities
│ ├── datasets/ # CheXpert dataset and label handling
│ ├── evaluation/ # metrics, prediction tables, thresholds
│ ├── explain/ # Grad-CAM logic
│ ├── inference/ # inference, postprocess, artifact handling
│ ├── metrics/ # classification metrics
│ ├── models/ # DenseNet121 model definition
│ └── utils/ # training utilities
├── configs/
│ └── base.yaml
├── scripts/
│ ├── train.py
│ ├── eval.py
│ ├── threshold_tune.py
│ ├── error_analysis.py
│ ├── infer.py
│ └── gradcam_demo.py
└── README.md

The dataset is not included in this repository.

Expected local dataset path:

data/chexpert_small/raw/
├── train.csv
├── valid.csv
├── train/
└── valid/

Only frontal-view images are used.

• Atelectasis
• Cardiomegaly
• Consolidation
• Edema
• Pleural Effusion

CheXpert contains uncertain labels. This project compares three uncertainty label policies:

The representative model uses U-Ignore because it achieved the highest test AUROC while avoiding forced positive or negative assignment of uncertain labels.

Representative U-Ignore model:

Model Evaluation Metrics and Threshold Selection

Class-specific thresholds were tuned on the validation set to maximize per-class F1-score.

Grad-CAM is used to visualize model attention over chest X-ray regions.
It is provided as supporting evidence and does not replace clinical interpretation.

Model Inference and Grad-CAM Visualization

Create and activate the virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Check dataset:

python scripts/check_dataset.py --config configs/base.yaml

Train:

python scripts/train.py --config configs/base.yaml

Evaluate:

python scripts/eval.py \
 --config configs/base.yaml \
 --checkpoint outputs/train_runs/<run_id>/checkpoints/best.pt

Tune thresholds:

python scripts/threshold_tune.py \
 --config configs/base.yaml \
 --checkpoint outputs/train_runs/<run_id>/checkpoints/best.pt \
 --criterion f1

Run inference:

python scripts/infer.py \
 --config configs/base.yaml \
 --checkpoint outputs/train_runs/<run_id>/checkpoints/best.pt \
 --input path/to/image.jpg

Run Grad-CAM:

python scripts/gradcam_demo.py \
 --config configs/base.yaml \
 --checkpoint outputs/train_runs/<run_id>/checkpoints/best.pt \
 --input path/to/image.jpg \
 --label "Pleural Effusion"

• This repository is for research and proof-of-concept experiments.
• The development period was 2026.03 – 2026.04.
• It is not a standalone medical device.
• Model outputs should be interpreted only as decision-support information.
• CheXpert data, model checkpoints, logs, and generated outputs are excluded from Git tracking.