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,171 +1,105 @@
----
-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-DenseNet
-
-> **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"] --> BB["DenseNet-121 Backbone
-    ImageNet pretrained
-    Dense connectivity
-    7.9M parameters"]
-    BB --> GAP2["Adaptive Avg Pool
-    1024-dim features"]
-    GAP2 --> FL["Feature Layer
-    Linear 1024→512
-    ReLU · Dropout(0.3)"]
-    FL --> MLH["Multilabel Head
-    Linear 512→14
-    sigmoid · 14 pathologies"]
-    FL --> 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
-    style BB fill:#6a1b9a,color:#fff
-```
-
-## Fine-Tuning Strategy
-
-```mermaid
-graph LR
-    P1["🔒 Phase 1
-    Epochs 1–5
-    Backbone frozen
-    Train heads only
-    lr = 0.001"] -->|"Epoch 6
-    unfreeze_backbone()"| P2["🔓 Phase 2
-    Epochs 6–60
-    End-to-end fine-tuning
-    All layers trainable
-    lr = 0.0001"]
-    style P1 fill:#e65100,color:#fff
-    style P2 fill:#6a1b9a,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.8379`
-- Best validation binary AUC-ROC: `0.7831`
-- Best validation binary F1: `0.6680`
-- Best checkpoint epoch: `21`
-
-
-## Per-Class AUC-ROC at Best Epoch
-
-| Pathology            | AUC-ROC  | Visual        |
-|----------------------|----------|---------------|
-| Atelectasis          | `0.8178` | `████████░░` |
-| Cardiomegaly         | `0.8996` | `█████████░` |
-| Effusion             | `0.8888` | `█████████░` |
-| Infiltration         | `0.7083` | `███████░░░` |
-| Mass                 | `0.8910` | `█████████░` |
-| Nodule               | `0.7837` | `████████░░` |
-| Pneumonia            | `0.7181` | `███████░░░` |
-| Pneumothorax         | `0.8731` | `█████████░` |
-| Consolidation        | `0.8128` | `████████░░` |
-| Edema                | `0.8993` | `█████████░` |
-| Emphysema            | `0.8907` | `█████████░` |
-| Fibrosis             | `0.7994` | `████████░░` |
-| Pleural_Thickening   | `0.8311` | `████████░░` |
-| Hernia               | `0.9171` | `█████████░` |
-
-## Training Configuration
-
-- Repository: `HlexNC/chexvision-densenet`
-- Dataset: [HlexNC/chest-xray-14](https://huggingface.co/datasets/HlexNC/chest-xray-14) · revision `c4e9a86b`
-- Architecture: DenseNet-121 transfer learning with a shared feature layer 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: `60`  ·  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-densenet}}
-}
-```
+---
+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-DenseNet
+
+> **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
+
+![DenseNet Architecture](arch_densenet.png)
+
+## Fine-Tuning Strategy
+
+![Fine-Tuning Strategy](finetuning_densenet.png)
+
+## Training Pipeline
+
+![Training Pipeline](pipeline_training.png)
+
+## Training Metrics
+
+- Best validation macro AUC-ROC: `0.8379`
+- Best validation binary AUC-ROC: `0.7831`
+- Best validation binary F1: `0.6680`
+- Best checkpoint epoch: `21`
+
+
+## Per-Class AUC-ROC at Best Epoch
+
+| Pathology            | AUC-ROC  | Visual        |
+|----------------------|----------|---------------|
+| Atelectasis          | `0.8178` | `████████░░` |
+| Cardiomegaly         | `0.8996` | `█████████░` |
+| Effusion             | `0.8888` | `█████████░` |
+| Infiltration         | `0.7083` | `███████░░░` |
+| Mass                 | `0.8910` | `█████████░` |
+| Nodule               | `0.7837` | `████████░░` |
+| Pneumonia            | `0.7181` | `███████░░░` |
+| Pneumothorax         | `0.8731` | `█████████░` |
+| Consolidation        | `0.8128` | `████████░░` |
+| Edema                | `0.8993` | `█████████░` |
+| Emphysema            | `0.8907` | `█████████░` |
+| Fibrosis             | `0.7994` | `████████░░` |
+| Pleural_Thickening   | `0.8311` | `████████░░` |
+| Hernia               | `0.9171` | `█████████░` |
+
+## Training Configuration
+
+- Repository: `HlexNC/chexvision-densenet`
+- Dataset: [HlexNC/chest-xray-14](https://huggingface.co/datasets/HlexNC/chest-xray-14) · revision `c4e9a86b`
+- Architecture: DenseNet-121 transfer learning with a shared feature layer 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: `60`  ·  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-densenet}}
+}
+```