Chest X-Ray CNN Classification

An educational deep-learning project for binary chest X-ray image classification: NORMAL vs PNEUMONIA.

The repository demonstrates an end-to-end applied ML workflow including dataset preparation, CNN training, evaluation, metric visualization and confusion-matrix analysis.

Important: This is a portfolio and educational project, not a medical diagnostic system. See MODEL_CARD.md for limitations and intended use.

Project summary

Item	Value
Task	Binary image classification
Input size	224 × 224
Framework	TensorFlow / Keras
Optimizer	Adam
Learning rate	0.001
Loss	Binary Crossentropy
Recorded test accuracy	approximately 83.65%

Dataset split

Split	Images
Train	5,216
Validation	16
Test	624

The validation split is extremely small, so validation metrics should be interpreted cautiously. A larger stratified validation design would be required for stronger conclusions.

Tech stack

• Python
• TensorFlow / Keras
• NumPy
• Matplotlib
• scikit-learn
• Google Colab

Repository structure

Chest_XRay_CNN_Projem/
├── .github/workflows/quality.yml
├── notebook/
│   └── Chest_XRay_CNN_Projem.ipynb
├── scripts/
│   └── validate_project.py
├── docs/
│   ├── index.html
│   └── images/
│       ├── normal.png
│       ├── pneumonia.png
│       ├── accuracy.png
│       ├── loss.png
│       └── confusion_matrix.png
├── report.pdf
├── MODEL_CARD.md
├── EXPERIMENT_PROTOCOL.md
├── SECURITY.md
├── CONTRIBUTING.md
├── LICENSE
├── THIRD_PARTY_NOTICES.md
└── README.md

Workflow

Chest X-ray dataset
        │
        ▼
Preprocessing / resize
        │
        ▼
CNN training
        │
        ▼
Validation monitoring
        │
        ▼
Test evaluation
        │
        ├── accuracy / loss curves
        └── confusion matrix

Reproduce the current experiment

Open the notebook in Google Colab:

https://colab.research.google.com/drive/1QvDpyKWrpE22qfl4iTTptSRBUgG38PCZ

The notebook contains the dataset-loading, model-definition, training and evaluation flow.

Dataset source:

https://www.kaggle.com/datasets/paultimothymooney/chest-xray-pneumonia

For new experiments, use EXPERIMENT_PROTOCOL.md. It defines the expected split metadata, random seeds, preprocessing record, training configuration, metrics and baseline comparisons so future results are comparable rather than one-off notebook runs.

Repository quality gate

The CI workflow intentionally avoids retraining a GPU model on every documentation change. Instead, it enforces a fast reproducibility/portfolio gate that runs on pushes and pull requests.

Run locally:

python scripts/validate_project.py

The validator checks that:

• the tracked Jupyter notebook exists and is valid JSON,
• the notebook uses a supported notebook format,
• it contains both executable code cells and explanatory Markdown cells,
• the Model Card and Experiment Protocol are present,
• security and contribution documentation is present,
• open-source licensing and third-party notices are present.

The latest GitHub Actions run for this quality gate is passing. Model training remains an explicit experiment step rather than a misleading lightweight CI substitute.

Evaluation notes

The recorded test accuracy is approximately 0.8365.

Accuracy alone is not enough for a healthcare-related classification problem. A stronger evaluation should also report:

• precision,
• recall / sensitivity,
• specificity,
• F1 score,
• ROC-AUC,
• confidence intervals,
• calibration behavior.

The repository includes visual evaluation artifacts such as training curves and a confusion matrix.

What this project demonstrates

• building and training a CNN with TensorFlow/Keras,
• preparing an image-classification workflow,
• tracking training and validation behavior,
• evaluating predictions with scikit-learn,
• communicating results through plots and a technical report,
• documenting model limitations responsibly,
• defining a reproducible experiment protocol before comparing new models,
• maintaining a fast CI quality gate for notebook/documentation integrity.

Limitations

• The validation set contains only 16 images.
• Results come from one public dataset and do not establish generalization to other hospitals or populations.
• The binary task simplifies real radiology interpretation substantially.
• The model has no clinical validation.

For the full statement, see MODEL_CARD.md.

Roadmap

• Create a larger stratified validation split
• Add precision, recall, F1 and ROC-AUC reporting
• Apply the documented fixed-seed experiment protocol
• Compare transfer-learning baselines such as MobileNetV2, DenseNet and ResNet
• Add confidence intervals and calibration analysis
• Add an experiment configuration file
• Add lightweight schema checks for exported experiment results

Engineering workflow

• MODEL_CARD.md documents intended use and limitations.
• EXPERIMENT_PROTOCOL.md defines reproducibility requirements for future runs.
• SECURITY.md documents responsible reporting/use boundaries.
• CONTRIBUTING.md and the pull-request checklist define contribution expectations.
• LICENSE covers project-authored source; THIRD_PARTY_NOTICES.md separates dataset/dependency rights.
• .github/workflows/quality.yml keeps the repository-quality gate green and repeatable.
• The open experiment issue tracks the next actual model-evaluation/baseline milestone.

Links

• GitHub Pages project page
• Colab notebook
• Dataset

---

Built by Mahmoud Karzoun.