Replace Mermaid code blocks with rendered PNG diagrams

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+pipeline_training.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,161 +1,101 @@
----
-license: mit
-language:
-- en
-library_name: pytorch
-pipeline_tag: image-classification
-tags:
-- chexvision
-- medical-imaging
-- chest-xray
-- radiology
-- pytorch
-- multi-label-classification
-datasets:
-- HlexNC/chest-xray-14
----
-
-# CheXVision-ResNet
-
-> **CheXVision** — Deep Learning & Big Data university project.
-> 14-class chest X-ray pathology detection + binary normal/abnormal classification
-> on the NIH Chest X-ray14 dataset (112,120 images).
-
-## Architecture
-
-```mermaid
-graph LR
-    IN["Input
-    3 × 224 × 224"] --> STEM["Stem
-    7×7 Conv · BN · ReLU
-    3→64ch · MaxPool ÷2"]
-    STEM --> S1["Stage 1
-    3× SE-ResBlock
-    64ch"]
-    S1 --> S2["Stage 2 ↓½
-    4× SE-ResBlock
-    128ch"]
-    S2 --> S3["Stage 3 ↓½
-    6× SE-ResBlock
-    256ch"]
-    S3 --> S4["Stage 4 ↓½
-    3× SE-ResBlock
-    512ch"]
-    S4 --> GAP["Global Avg Pool
-    Dropout(0.5)
-    512-dim"]
-    GAP --> MLH["Multilabel Head
-    Linear 512→14
-    sigmoid · 14 pathologies"]
-    GAP --> BH["Binary Head
-    Linear 512→1
-    sigmoid · Normal/Abnormal"]
-    style MLH fill:#2e7d32,color:#fff
-    style BH fill:#1565c0,color:#fff
-    style IN fill:#37474f,color:#fff
-```
-
-## Training Pipeline
-
-```mermaid
-flowchart TD
-    DS[("🗄️ HlexNC/chest-xray-14
-    112,120 chest X-ray images
-    36 parquet shards · ~4.7 GB")] -->|snapshot_download| PREP["📂 data/images/  ·  data/labels.csv
-    train 78,468 · val 11,210 · test 22,442"]
-    PREP --> AUG["Augmentation Pipeline
-    HFlip · Rotate±15° · RandomAffine
-    ColorJitter · GaussianBlur · RandomErasing
-    ImageNet normalize  ⟨mean=[0.485,0.456,0.406]⟩"]
-    AUG --> FWD["⚡ Model Forward Pass
-    torch.cuda.amp.autocast  ·  fp16"]
-    FWD --> ML["multilabel_logits  B×14
-    WeightedBCE + pos_weight
-    14 pathology classes"]
-    FWD --> BIN["binary_logits  B×1
-    BCE loss
-    Normal vs. Abnormal"]
-    ML --> LOSS["Combined Loss
-    1.0 × multilabel  +  0.5 × binary"]
-    BIN --> LOSS
-    LOSS --> BACK["Backward  ·  Grad Clip 1.0
-    Gradient Accumulation ×4
-    effective batch = 128"]
-    BACK --> OPT["AdamW step  ·  CosineAnnealingLR
-    early stop patience = 15"]
-    OPT -->|"↑ val macro AUC-ROC"| BEST["💾 Best Checkpoint
-    model_state + best_val_metrics + config"]
-    BEST -->|upload_model_artifacts| HUB["🤗 HF Hub
-    checkpoint  ·  history.json  ·  model card"]
-```
-
-## Training Metrics
-
-- Best validation macro AUC-ROC: `0.7976`
-- Best validation binary AUC-ROC: `0.7554`
-- Best validation binary F1: `0.6295`
-- Best checkpoint epoch: `65`
-
-
-## Per-Class AUC-ROC at Best Epoch
-
-| Pathology            | AUC-ROC  | Visual        |
-|----------------------|----------|---------------|
-| Atelectasis          | `0.7842` | `████████░░` |
-| Cardiomegaly         | `0.8929` | `█████████░` |
-| Effusion             | `0.8602` | `█████████░` |
-| Infiltration         | `0.6903` | `███████░░░` |
-| Mass                 | `0.8168` | `████████░░` |
-| Nodule               | `0.6634` | `███████░░░` |
-| Pneumonia            | `0.6807` | `███████░░░` |
-| Pneumothorax         | `0.8208` | `████████░░` |
-| Consolidation        | `0.8184` | `████████░░` |
-| Edema                | `0.9103` | `█████████░` |
-| Emphysema            | `0.8355` | `████████░░` |
-| Fibrosis             | `0.7604` | `████████░░` |
-| Pleural_Thickening   | `0.7702` | `████████░░` |
-| Hernia               | `0.8619` | `█████████░` |
-
-## Training Configuration
-
-- Repository: `HlexNC/chexvision-scratch`
-- Dataset: [HlexNC/chest-xray-14](https://huggingface.co/datasets/HlexNC/chest-xray-14) · revision `c4e9a86b`
-- Architecture: Custom residual CNN with Squeeze-Excitation channel attention (depth [3, 4, 6, 3]) trained from scratch with shared features and dual classification heads.
-- Platform: Kaggle GPU kernel (NVIDIA T4 / P100)
-- Batch size: `32` × grad_accum `4` = **effective batch `128`**
-- AMP (fp16): `enabled`
-- Optimizer: AdamW  ·  Scheduler: CosineAnnealingLR
-- Epochs configured: `100`  ·  Early stop patience: `15`
-
-## Intended Use
-
-This model is intended for research and educational work on automated chest X-ray pathology detection.
-It outputs two predictions per image:
-1. **Multi-label scores** — independent sigmoid probability for each of 14 NIH pathologies
-2. **Binary score** — sigmoid probability of any abnormality (Normal vs. Abnormal)
-
-## Limitations
-
-- Not validated for clinical use. Predictions must not substitute professional medical judgment.
-- Trained on NIH Chest X-ray14, which contains noisy radiologist annotations (patient-level labels, not lesion-level).
-- Performance degrades on images from equipment, patient populations, or preprocessing pipelines
-  that differ from the NIH training distribution.
-- Reported AUC metrics are on the validation split, not the held-out test set.
-
-## CheXNet Benchmark Context
-
-CheXNet (Rajpurkar et al., 2017) — the seminal paper establishing DenseNet-121 for chest X-ray
-classification — reported **0.841 macro AUC-ROC** on a comparable split of this dataset.
-CheXVision-DenseNet matches this benchmark. See the
-[CheXVision demo](https://huggingface.co/spaces/HlexNC/chexvision-demo) for live inference.
-
-## Citation
-
-```bibtex
-@misc{chexvision2026,
-  title={CheXVision: Dual-Task Chest X-ray Classification with Custom CNN and DenseNet-121},
-  author={BIG D(ATA) Team},
-  year={2026},
-  howpublished={\url{https://huggingface.co/HlexNC/chexvision-scratch}}
-}
-```
+---
+license: mit
+language:
+- en
+library_name: pytorch
+pipeline_tag: image-classification
+tags:
+- chexvision
+- medical-imaging
+- chest-xray
+- radiology
+- pytorch
+- multi-label-classification
+datasets:
+- HlexNC/chest-xray-14
+---
+
+# CheXVision-ResNet
+
+> **CheXVision** — Deep Learning & Big Data university project.
+> 14-class chest X-ray pathology detection + binary normal/abnormal classification
+> on the NIH Chest X-ray14 dataset (112,120 images).
+
+## Architecture
+
+![SE-ResNet Architecture](arch_scratch.png)
+
+## Training Pipeline
+
+![Training Pipeline](pipeline_training.png)
+
+## Training Metrics
+
+- Best validation macro AUC-ROC: `0.7976`
+- Best validation binary AUC-ROC: `0.7554`
+- Best validation binary F1: `0.6295`
+- Best checkpoint epoch: `65`
+
+
+## Per-Class AUC-ROC at Best Epoch
+
+| Pathology            | AUC-ROC  | Visual        |
+|----------------------|----------|---------------|
+| Atelectasis          | `0.7842` | `████████░░` |
+| Cardiomegaly         | `0.8929` | `█████████░` |
+| Effusion             | `0.8602` | `█████████░` |
+| Infiltration         | `0.6903` | `███████░░░` |
+| Mass                 | `0.8168` | `████████░░` |
+| Nodule               | `0.6634` | `███████░░░` |
+| Pneumonia            | `0.6807` | `███████░░░` |
+| Pneumothorax         | `0.8208` | `████████░░` |
+| Consolidation        | `0.8184` | `████████░░` |
+| Edema                | `0.9103` | `█████████░` |
+| Emphysema            | `0.8355` | `████████░░` |
+| Fibrosis             | `0.7604` | `████████░░` |
+| Pleural_Thickening   | `0.7702` | `████████░░` |
+| Hernia               | `0.8619` | `█████████░` |
+
+## Training Configuration
+
+- Repository: `HlexNC/chexvision-scratch`
+- Dataset: [HlexNC/chest-xray-14](https://huggingface.co/datasets/HlexNC/chest-xray-14) · revision `c4e9a86b`
+- Architecture: Custom residual CNN with Squeeze-Excitation channel attention (depth [3, 4, 6, 3]) trained from scratch with shared features and dual classification heads.
+- Platform: Kaggle GPU kernel (NVIDIA T4 / P100)
+- Batch size: `32` × grad_accum `4` = **effective batch `128`**
+- AMP (fp16): `enabled`
+- Optimizer: AdamW  ·  Scheduler: CosineAnnealingLR
+- Epochs configured: `100`  ·  Early stop patience: `15`
+
+## Intended Use
+
+This model is intended for research and educational work on automated chest X-ray pathology detection.
+It outputs two predictions per image:
+1. **Multi-label scores** — independent sigmoid probability for each of 14 NIH pathologies
+2. **Binary score** — sigmoid probability of any abnormality (Normal vs. Abnormal)
+
+## Limitations
+
+- Not validated for clinical use. Predictions must not substitute professional medical judgment.
+- Trained on NIH Chest X-ray14, which contains noisy radiologist annotations (patient-level labels, not lesion-level).
+- Performance degrades on images from equipment, patient populations, or preprocessing pipelines
+  that differ from the NIH training distribution.
+- Reported AUC metrics are on the validation split, not the held-out test set.
+
+## CheXNet Benchmark Context
+
+CheXNet (Rajpurkar et al., 2017) — the seminal paper establishing DenseNet-121 for chest X-ray
+classification — reported **0.841 macro AUC-ROC** on a comparable split of this dataset.
+CheXVision-DenseNet matches this benchmark. See the
+[CheXVision demo](https://huggingface.co/spaces/HlexNC/chexvision-demo) for live inference.
+
+## Citation
+
+```bibtex
+@misc{chexvision2026,
+  title={CheXVision: Dual-Task Chest X-ray Classification with Custom CNN and DenseNet-121},
+  author={BIG D(ATA) Team},
+  year={2026},
+  howpublished={\url{https://huggingface.co/HlexNC/chexvision-scratch}}
+}
+```