g

.gitignore

@@ -1,4 +1,7 @@
 *.docx
 *.png
 __pycache__/
-.claude/
+.claude/
+*.pdf 
+ 
+ 

data/export_split_by_pathology.py

@@ -0,0 +1,321 @@
+"""
+export_split_by_pathology.py
+----------------------------
+Tải 1 split (mặc định: test) của MIMIC-CXR_resized từ HF, giải nén tar shards,
+rồi đổ ảnh vào thư mục theo 14 nhãn bệnh lý CheXpert.
+
+Vì sao phải làm thế này:
+  - Trên HF, MIMIC-CXR_resized lưu ảnh dưới dạng tar shards (cxr-0000.tar, ...),
+    KHÔNG tách theo split. Ảnh của 1 split nằm rải khắp các shard.
+  - manifest_{train,val,test}.csv mới là nơi biết ảnh nào thuộc split nào, và
+    chứa 14 cột `chex_<Pathology>` (giá trị U-MultiClass: 1/0/-1/blank).
+  - Mỗi study là MULTI-LABEL: 1 ảnh có thể dương tính nhiều bệnh -> được copy
+    vào NHIỀU thư mục (mỗi nhãn positive 1 thư mục).
+
+Quy ước nhãn (giống mimic_cxr_resized_builder._row_to_pnu):
+    "1" / "1.0"   -> positive  -> bỏ vào thư mục <Pathology>/
+    "-1" / "-1.0" -> uncertain -> tuỳ --uncertain
+    "0"/"0.0"/blank -> negative -> bỏ qua
+
+Cấu trúc output (mặc định --uncertain separate):
+    OUT/
+      Cardiomegaly/<dicom>.jpg
+      Pleural_Effusion/<dicom>.jpg
+      No_Finding/<dicom>.jpg
+      _uncertain/Atelectasis/<dicom>.jpg     (nếu --uncertain separate)
+      _summary.csv                            (đếm ảnh mỗi nhãn)
+
+Chạy LOCAL (đã có data) hoặc trên Colab/Kaggle (tự tải từ HF):
+    # tải từ HF rồi export test
+    python data/export_split_by_pathology.py --out ./test_by_pathology
+
+    # đã giải nén sẵn cây files/ ở đâu đó -> bỏ qua tải/giải nén
+    python data/export_split_by_pathology.py --out ./test_by_pathology \
+        --extracted_root /content/data/MIMIC-CXR_resized \
+        --manifest /content/data/MIMIC-CXR_resized/manifest_test.csv
+
+    # export cả split val, dùng hardlink cho đỡ tốn ổ
+    python data/export_split_by_pathology.py --split val --link hardlink
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import os
+import sys
+import tarfile
+from collections import defaultdict
+from pathlib import Path
+
+# 14 nhãn CheXpert — single source of truth.
+try:
+    from model.chexpert_classifier import PATHOLOGIES
+except Exception:
+    # fallback nếu chạy ngoài project (giữ đúng thứ tự).
+    PATHOLOGIES = [
+        "No Finding", "Enlarged Cardiomediastinum", "Cardiomegaly", "Lung Opacity",
+        "Lung Lesion", "Edema", "Consolidation", "Pneumonia", "Atelectasis",
+        "Pneumothorax", "Pleural Effusion", "Pleural Other", "Fracture",
+        "Support Devices",
+    ]
+
+_POS = {"1", "1.0"}
+_UNC = {"-1", "-1.0"}
+
+
+def _safe(name: str) -> str:
+    """Tên thư mục an toàn: 'Pleural Effusion' -> 'Pleural_Effusion'."""
+    return name.replace(" ", "_")
+
+
+def _norm(p: str) -> str:
+    """Chuẩn hoá path để so khớp tar member name <-> manifest image_relpath."""
+    return p.replace("\\", "/").lstrip("/")
+
+
+# ── Phase 1: tải từ HF (manifest + shards) ──────────────────────────────────
+
+def download_from_hf(repo_id: str, split: str, work: Path) -> tuple[Path, list[Path]]:
+    """Tải manifest_<split>.csv + toàn bộ tar shards về `work`.
+    Trả về (manifest_path, [shard_paths])."""
+    from huggingface_hub import snapshot_download
+
+    manifest_name = {"train": "manifest_train.csv",
+                     "val": "manifest_val.csv",
+                     "validate": "manifest_val.csv",
+                     "test": "manifest_test.csv"}[split]
+
+    print(f"[download] snapshot_download {repo_id}:MIMIC-CXR_resized "
+          f"(manifest + shards) -> {work}")
+    snapshot_download(
+        repo_id=repo_id,
+        repo_type="dataset",
+        local_dir=str(work),
+        allow_patterns=[
+            f"MIMIC-CXR_resized/{manifest_name}",
+            "MIMIC-CXR_resized/shards/*.tar",
+        ],
+    )
+    mr = work / "MIMIC-CXR_resized"
+    manifest = mr / manifest_name
+    shards = sorted((mr / "shards").glob("*.tar"))
+    if not manifest.is_file():
+        sys.exit(f"ERROR: không thấy manifest sau khi tải: {manifest}")
+    if not shards:
+        sys.exit(f"ERROR: không thấy tar shard nào dưới {mr/'shards'}")
+    print(f"[download] manifest={manifest.name}  shards={len(shards)}")
+    return manifest, shards
+
+
+# ── Phase 2: đọc manifest -> map ảnh test -> nhãn ───────────────────────────
+
+def load_label_map(manifest: Path):
+    """Trả về dict: image_relpath(norm) -> {'pos': set, 'unc': set, 'report': str|None}."""
+    label_map: dict[str, dict] = {}
+    missing_cols = None
+    with open(manifest, encoding="utf-8", newline="") as f:
+        reader = csv.DictReader(f)
+        cols = reader.fieldnames or []
+        chex_cols = {p: f"chex_{p}" for p in PATHOLOGIES if f"chex_{p}" in cols}
+        missing_cols = [p for p in PATHOLOGIES if f"chex_{p}" not in cols]
+        rel_col = "image_relpath" if "image_relpath" in cols else None
+        if rel_col is None:
+            sys.exit(f"ERROR: manifest thiếu cột 'image_relpath'. Có: {cols}")
+        has_report = "report_relpath" in cols
+        for row in reader:
+            rel = _norm(str(row[rel_col]).strip())
+            pos, unc = set(), set()
+            for path, col in chex_cols.items():
+                v = str(row.get(col, "")).strip()
+                if v in _POS:
+                    pos.add(path)
+                elif v in _UNC:
+                    unc.add(path)
+            rep = _norm(str(row["report_relpath"]).strip()) if has_report else None
+            label_map[rel] = {"pos": pos, "unc": unc, "report": rep or None}
+    if missing_cols:
+        print(f"[labels] CẢNH BÁO: manifest thiếu cột cho: {missing_cols}")
+    if not has_report:
+        print("[labels] CẢNH BÁO: manifest không có cột 'report_relpath' → bỏ qua report")
+    print(f"[labels] {len(label_map):,} ảnh trong manifest")
+    return label_map
+
+
+def gather_reports(shards: list[Path], report_set: set) -> dict:
+    """Pass phụ: rút text của các report cần dùng từ tar (report nằm rải, gom 1 lượt).
+    Report là file .txt nhỏ nên giữ trong RAM thoải mái."""
+    reports: dict[str, bytes] = {}
+    if not report_set:
+        return reports
+    for shard in shards:
+        with tarfile.open(shard, "r") as tf:
+            for m in tf:
+                if not m.isfile():
+                    continue
+                name = _norm(m.name)
+                if name in report_set and name not in reports:
+                    reports[name] = tf.extractfile(m).read()
+    print(f"[reports] rút được {len(reports):,} / {len(report_set):,} report")
+    return reports
+
+
+# ── Phase 3: rút ảnh từ tar -> thư mục theo nhãn ────────────────────────────
+
+def _place(data: bytes, dicom_name: str, paths: set, base: Path,
+           counts: defaultdict, link_mode: str, report: bytes | None = None):
+    """Ghi 1 ảnh (và report cùng tên .txt nếu có) vào nhiều thư mục nhãn."""
+    txt_name = Path(dicom_name).stem + ".txt"
+    first_written: Path | None = None
+    for lab in paths:
+        d = base / _safe(lab)
+        d.mkdir(parents=True, exist_ok=True)
+        dst = d / dicom_name
+        counts[lab] += 1
+        # report .txt đặt cạnh ảnh, cùng tên
+        if report is not None:
+            (d / txt_name).write_bytes(report)
+        if dst.exists():
+            continue
+        if link_mode == "copy" or first_written is None:
+            dst.write_bytes(data)
+            first_written = dst
+        else:
+            try:
+                if link_mode == "hardlink":
+                    os.link(first_written, dst)
+                else:  # symlink
+                    os.symlink(os.path.abspath(first_written), dst)
+            except OSError:
+                dst.write_bytes(data)   # fallback nếu FS không hỗ trợ link
+
+
+def export(shards: list[Path], label_map: dict, out: Path,
+           uncertain: str, link_mode: str, with_report: bool = True):
+    out.mkdir(parents=True, exist_ok=True)
+    unc_base = out / "_uncertain"
+
+    test_set = set(label_map.keys())
+
+    # Gom report cần dùng (1 pass phụ qua tar) trước khi rút ảnh.
+    reports: dict = {}
+    if with_report:
+        report_set = {label_map[k]["report"] for k in test_set
+                      if label_map[k].get("report")}
+        reports = gather_reports(shards, report_set)
+
+    counts_pos: defaultdict = defaultdict(int)
+    counts_unc: defaultdict = defaultdict(int)
+    n_imgs = 0
+    n_no_report = 0
+    seen: set[str] = set()
+
+    for si, shard in enumerate(shards, 1):
+        print(f"[extract] [{si}/{len(shards)}] {shard.name}")
+        with tarfile.open(shard, "r") as tf:
+            for m in tf:
+                if not m.isfile():
+                    continue
+                name = _norm(m.name)
+                if name not in test_set:
+                    continue
+                seen.add(name)
+                ent = label_map[name]
+                pos, unc = ent["pos"], ent["unc"]
+                if not pos and not (uncertain != "skip" and unc):
+                    # không có nhãn positive (toàn negative) -> bỏ qua
+                    if not pos:
+                        continue
+                data = tf.extractfile(m).read()
+                dicom_name = Path(name).name
+                rep = reports.get(ent.get("report")) if with_report else None
+                if with_report and rep is None:
+                    n_no_report += 1
+                n_imgs += 1
+                if pos:
+                    _place(data, dicom_name, pos, out, counts_pos, link_mode, rep)
+                if unc and uncertain != "skip":
+                    if uncertain == "merge":
+                        _place(data, dicom_name, unc, out, counts_unc, link_mode, rep)
+                    else:  # separate
+                        _place(data, dicom_name, unc, unc_base, counts_unc, link_mode, rep)
+
+    if with_report and n_no_report:
+        print(f"[reports] CẢNH BÁO: {n_no_report:,} ảnh không tìm thấy report → chỉ có .jpg")
+
+    missing = test_set - seen
+    print(f"\n[done] ảnh test rút được: {n_imgs:,} / {len(test_set):,} trong manifest")
+    if missing:
+        print(f"[done] CẢNH BÁO: {len(missing):,} ảnh trong manifest không thấy trong shard "
+              f"(ví dụ: {list(missing)[:3]})")
+    print(f"[done] ảnh toàn-negative (không có positive): bỏ qua")
+
+    # _summary.csv
+    summ = out / "_summary.csv"
+    with open(summ, "w", encoding="utf-8", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(["pathology", "positive_images", "uncertain_images"])
+        for p in PATHOLOGIES:
+            w.writerow([p, counts_pos.get(p, 0), counts_unc.get(p, 0)])
+    print(f"[done] thống kê -> {summ}")
+    print("\n  Nhãn                         positive   uncertain")
+    for p in PATHOLOGIES:
+        print(f"  {p:28s} {counts_pos.get(p,0):8d}   {counts_unc.get(p,0):8d}")
+
+
+# ── CLI ─────────────────────────────────────────────────────────────────────
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Export 1 split của MIMIC-CXR_resized thành thư mục theo 14 nhãn bệnh lý.")
+    ap.add_argument("--out", required=True, help="Thư mục output.")
+    ap.add_argument("--split", default="test", choices=["train", "val", "validate", "test"])
+    ap.add_argument("--repo_id", default="hieu3636/cxr-vlm-data")
+    ap.add_argument("--work", default="./_hf_resized_dl",
+                    help="Thư mục cache tải từ HF (khi không dùng --extracted_root).")
+    ap.add_argument("--extracted_root", default=None,
+                    help="Nếu đã có shards giải nén/tar sẵn ở local: trỏ tới thư mục "
+                         "MIMIC-CXR_resized (chứa shards/*.tar). Bỏ qua bước tải HF.")
+    ap.add_argument("--manifest", default=None,
+                    help="Đường dẫn manifest_<split>.csv (mặc định lấy trong dữ liệu đã tải).")
+    ap.add_argument("--uncertain", default="separate",
+                    choices=["separate", "merge", "skip"],
+                    help="Xử lý nhãn uncertain: separate=thư mục _uncertain/<P>; "
+                         "merge=gộp chung <P>; skip=bỏ. Mặc định separate.")
+    ap.add_argument("--link", default="copy", choices=["copy", "hardlink", "symlink"],
+                    help="copy (an toàn nhất) | hardlink/symlink (tiết kiệm ổ khi 1 ảnh nhiều nhãn).")
+    ap.add_argument("--no_report", action="store_true",
+                    help="Không ghi report .txt cạnh ảnh (mặc định CÓ ghi).")
+    a = ap.parse_args()
+
+    out = Path(a.out)
+
+    # 1) Lấy manifest + shards
+    if a.extracted_root:
+        mr = Path(a.extracted_root)
+        shards = sorted((mr / "shards").glob("*.tar")) or sorted(mr.glob("*.tar"))
+        if not shards:
+            sys.exit(f"ERROR: không thấy *.tar dưới {mr} hoặc {mr/'shards'}")
+        if a.manifest:
+            manifest = Path(a.manifest)
+        else:
+            mname = {"train": "manifest_train.csv", "val": "manifest_val.csv",
+                     "validate": "manifest_val.csv", "test": "manifest_test.csv"}[a.split]
+            manifest = mr / mname
+        if not manifest.is_file():
+            sys.exit(f"ERROR: không thấy manifest: {manifest}")
+        print(f"[local] manifest={manifest}  shards={len(shards)}")
+    else:
+        manifest, shards = download_from_hf(a.repo_id, a.split, Path(a.work))
+        if a.manifest:
+            manifest = Path(a.manifest)
+
+    # 2) Đọc nhãn
+    label_map = load_label_map(manifest)
+
+    # 3) Rút ảnh (+ report) -> thư mục nhãn
+    export(shards, label_map, out, a.uncertain, a.link, with_report=not a.no_report)
+    print(f"\nXong. Output: {out.resolve()}")
+
+
+if __name__ == "__main__":
+    main()

data/export_test_by_pathology.ipynb

@@ -0,0 +1,263 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "26283604",
+   "metadata": {},
+   "source": [
+    "# Export tập test MIMIC-CXR_resized → thư mục theo 14 nhãn bệnh lý\n",
+    "\n",
+    "Chỉ cần điền **CONFIG** bên dưới rồi **Run All**.\n",
+    "\n",
+    "- Tải `manifest_test.csv` + tar shards từ HF (`hieu3636/cxr-vlm-data/MIMIC-CXR_resized/`).\n",
+    "- Rút ảnh test, đổ vào `OUT/<Tên_bệnh>/`. Ảnh multi-label → copy vào nhiều thư mục.\n",
+    "- **Kèm report**: mỗi ảnh `<dicom>.jpg` có file `<dicom>.txt` (nội dung report của study đó) đặt ngay cạnh.\n",
+    "- Repo **private** → cần token HF (điền vào `HF_TOKEN`, hoặc đã `huggingface-cli login` thì để trống)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c41dd18e",
+   "metadata": {},
+   "source": [
+    "## 1. CONFIG — chỉnh ở đây"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8fd81f44",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ==== CHỈNH CÁC BIẾN NÀY ====\n",
+    "HF_TOKEN   = \"\"          # token HF (Read là đủ). Để \"\" nếu đã huggingface-cli login.\n",
+    "REPO_ID    = \"hieu3636/cxr-vlm-data\"\n",
+    "SPLIT      = \"test\"      # \"train\" | \"val\" | \"test\"\n",
+    "\n",
+    "OUT        = r\"D:\\USTH\\KLTN\\test_by_pathology\"   # thư mục output\n",
+    "WORK       = r\"D:\\USTH\\KLTN\\_hf_resized_dl\"      # nơi cache tải từ HF\n",
+    "\n",
+    "# Nếu ĐÃ có shards giải nén/tar sẵn ở máy thì trỏ vào đây để KHỎI tải lại,\n",
+    "# ví dụ r\"D:\\USTH\\KLTN\\_hf_resized_dl\\MIMIC-CXR_resized\". Để None = tải từ HF.\n",
+    "EXTRACTED_ROOT = None\n",
+    "\n",
+    "WITH_REPORT = True       # True = ghi kèm <dicom>.txt (report) cạnh mỗi ảnh\n",
+    "UNCERTAIN  = \"separate\"  # \"separate\" (_uncertain/<P>) | \"merge\" | \"skip\"\n",
+    "LINK       = \"copy\"      # \"copy\" | \"hardlink\" | \"symlink\" (hardlink đỡ tốn ổ)\n",
+    "# ============================\n",
+    "print(\"CONFIG ok | split =\", SPLIT, \"| out =\", OUT, \"| with_report =\", WITH_REPORT)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8085defe",
+   "metadata": {},
+   "source": [
+    "## 2. Cài thư viện (chạy 1 lần)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "11afbe51",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Chỉ cần huggingface_hub; tarfile/csv là built-in.\n",
+    "try:\n",
+    "    import huggingface_hub  # noqa\n",
+    "    print(\"huggingface_hub đã có:\", huggingface_hub.__version__)\n",
+    "except ImportError:\n",
+    "    import sys, subprocess\n",
+    "    subprocess.check_call([sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"huggingface_hub\"])\n",
+    "    print(\"đã cài huggingface_hub\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ac53032e",
+   "metadata": {},
+   "source": [
+    "## 3. Logic (không cần sửa)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9ac60a59",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os, csv, tarfile\n",
+    "from collections import defaultdict\n",
+    "from pathlib import Path\n",
+    "\n",
+    "# 14 nhãn CheXpert — đúng thứ tự dùng trong project.\n",
+    "PATHOLOGIES = [\n",
+    "    \"No Finding\", \"Enlarged Cardiomediastinum\", \"Cardiomegaly\", \"Lung Opacity\",\n",
+    "    \"Lung Lesion\", \"Edema\", \"Consolidation\", \"Pneumonia\", \"Atelectasis\",\n",
+    "    \"Pneumothorax\", \"Pleural Effusion\", \"Pleural Other\", \"Fracture\",\n",
+    "    \"Support Devices\",\n",
+    "]\n",
+    "_POS = {\"1\", \"1.0\"}\n",
+    "_UNC = {\"-1\", \"-1.0\"}\n",
+    "_MANIFEST = {\"train\": \"manifest_train.csv\", \"val\": \"manifest_val.csv\",\n",
+    "             \"validate\": \"manifest_val.csv\", \"test\": \"manifest_test.csv\"}\n",
+    "\n",
+    "def _safe(n): return n.replace(\" \", \"_\")\n",
+    "def _norm(p): return p.replace(\"\\\\\", \"/\").lstrip(\"/\")\n",
+    "\n",
+    "def download_from_hf(repo_id, split, work):\n",
+    "    from huggingface_hub import snapshot_download\n",
+    "    mname = _MANIFEST[split]\n",
+    "    print(f\"[download] {repo_id}:MIMIC-CXR_resized (manifest + shards) -> {work}\")\n",
+    "    snapshot_download(\n",
+    "        repo_id=repo_id, repo_type=\"dataset\", local_dir=str(work),\n",
+    "        allow_patterns=[f\"MIMIC-CXR_resized/{mname}\", \"MIMIC-CXR_resized/shards/*.tar\"],\n",
+    "    )\n",
+    "    mr = Path(work) / \"MIMIC-CXR_resized\"\n",
+    "    manifest = mr / mname\n",
+    "    shards = sorted((mr / \"shards\").glob(\"*.tar\"))\n",
+    "    assert manifest.is_file(), f\"không thấy manifest: {manifest}\"\n",
+    "    assert shards, f\"không thấy tar shard dưới {mr/'shards'}\"\n",
+    "    print(f\"[download] manifest={manifest.name}  shards={len(shards)}\")\n",
+    "    return manifest, shards\n",
+    "\n",
+    "def load_label_map(manifest):\n",
+    "    label_map = {}\n",
+    "    with open(manifest, encoding=\"utf-8\", newline=\"\") as f:\n",
+    "        reader = csv.DictReader(f); cols = reader.fieldnames or []\n",
+    "        chex_cols = {p: f\"chex_{p}\" for p in PATHOLOGIES if f\"chex_{p}\" in cols}\n",
+    "        miss = [p for p in PATHOLOGIES if f\"chex_{p}\" not in cols]\n",
+    "        assert \"image_relpath\" in cols, f\"manifest thiếu image_relpath. Có: {cols}\"\n",
+    "        has_report = \"report_relpath\" in cols\n",
+    "        for row in reader:\n",
+    "            rel = _norm(str(row[\"image_relpath\"]).strip())\n",
+    "            pos, unc = set(), set()\n",
+    "            for p, c in chex_cols.items():\n",
+    "                v = str(row.get(c, \"\")).strip()\n",
+    "                if v in _POS: pos.add(p)\n",
+    "                elif v in _UNC: unc.add(p)\n",
+    "            rep = _norm(str(row[\"report_relpath\"]).strip()) if has_report else None\n",
+    "            label_map[rel] = {\"pos\": pos, \"unc\": unc, \"report\": rep or None}\n",
+    "    if miss: print(f\"[labels] CẢNH BÁO thiếu cột: {miss}\")\n",
+    "    if not has_report: print(\"[labels] CẢNH BÁO: manifest không có report_relpath → bỏ qua report\")\n",
+    "    print(f\"[labels] {len(label_map):,} ảnh trong manifest\")\n",
+    "    return label_map\n",
+    "\n",
+    "def gather_reports(shards, report_set):\n",
+    "    \"\"\"Gom text các report cần dùng (1 pass qua tar). Report nhỏ → giữ RAM.\"\"\"\n",
+    "    reports = {}\n",
+    "    if not report_set: return reports\n",
+    "    for shard in shards:\n",
+    "        with tarfile.open(shard, \"r\") as tf:\n",
+    "            for m in tf:\n",
+    "                if not m.isfile(): continue\n",
+    "                name = _norm(m.name)\n",
+    "                if name in report_set and name not in reports:\n",
+    "                    reports[name] = tf.extractfile(m).read()\n",
+    "    print(f\"[reports] rút được {len(reports):,} / {len(report_set):,} report\")\n",
+    "    return reports\n",
+    "\n",
+    "def _place(data, dicom, paths, base, counts, link, report=None):\n",
+    "    txt = Path(dicom).stem + \".txt\"\n",
+    "    first = None\n",
+    "    for lab in paths:\n",
+    "        d = base / _safe(lab); d.mkdir(parents=True, exist_ok=True)\n",
+    "        dst = d / dicom; counts[lab] += 1\n",
+    "        if report is not None: (d / txt).write_bytes(report)\n",
+    "        if dst.exists(): continue\n",
+    "        if link == \"copy\" or first is None:\n",
+    "            dst.write_bytes(data); first = dst\n",
+    "        else:\n",
+    "            try:\n",
+    "                os.link(first, dst) if link == \"hardlink\" else os.symlink(os.path.abspath(first), dst)\n",
+    "            except OSError:\n",
+    "                dst.write_bytes(data)\n",
+    "\n",
+    "def export(shards, label_map, out, uncertain, link, with_report=True):\n",
+    "    out = Path(out); out.mkdir(parents=True, exist_ok=True)\n",
+    "    unc_base = out / \"_uncertain\"\n",
+    "    test_set = set(label_map)\n",
+    "    reports = {}\n",
+    "    if with_report:\n",
+    "        rset = {label_map[k][\"report\"] for k in test_set if label_map[k].get(\"report\")}\n",
+    "        reports = gather_reports(shards, rset)\n",
+    "    cpos, cunc = defaultdict(int), defaultdict(int)\n",
+    "    n_imgs = 0; n_no_rep = 0; seen = set()\n",
+    "    for si, shard in enumerate(shards, 1):\n",
+    "        print(f\"[extract] [{si}/{len(shards)}] {shard.name}\")\n",
+    "        with tarfile.open(shard, \"r\") as tf:\n",
+    "            for m in tf:\n",
+    "                if not m.isfile(): continue\n",
+    "                name = _norm(m.name)\n",
+    "                if name not in test_set: continue\n",
+    "                seen.add(name)\n",
+    "                ent = label_map[name]; pos, unc = ent[\"pos\"], ent[\"unc\"]\n",
+    "                if not pos and not (uncertain != \"skip\" and unc): continue\n",
+    "                data = tf.extractfile(m).read(); dicom = Path(name).name; n_imgs += 1\n",
+    "                rep = reports.get(ent.get(\"report\")) if with_report else None\n",
+    "                if with_report and rep is None: n_no_rep += 1\n",
+    "                if pos: _place(data, dicom, pos, out, cpos, link, rep)\n",
+    "                if unc and uncertain != \"skip\":\n",
+    "                    _place(data, dicom, unc, (out if uncertain == \"merge\" else unc_base), cunc, link, rep)\n",
+    "    if with_report and n_no_rep:\n",
+    "        print(f\"[reports] CẢNH BÁO: {n_no_rep:,} ảnh không thấy report → chỉ có .jpg\")\n",
+    "    missing = test_set - seen\n",
+    "    print(f\"\\n[done] ảnh rút được: {n_imgs:,} / {len(test_set):,} trong manifest\")\n",
+    "    if missing:\n",
+    "        print(f\"[done] CẢNH BÁO: {len(missing):,} ảnh manifest không có trong shard (vd: {list(missing)[:2]})\")\n",
+    "    with open(out / \"_summary.csv\", \"w\", encoding=\"utf-8\", newline=\"\") as f:\n",
+    "        w = csv.writer(f); w.writerow([\"pathology\", \"positive_images\", \"uncertain_images\"])\n",
+    "        for p in PATHOLOGIES: w.writerow([p, cpos.get(p, 0), cunc.get(p, 0)])\n",
+    "    print(\"\\n  Nhãn                         positive   uncertain\")\n",
+    "    for p in PATHOLOGIES:\n",
+    "        print(f\"  {p:28s} {cpos.get(p,0):8d}   {cunc.get(p,0):8d}\")\n",
+    "    return cpos, cunc\n",
+    "\n",
+    "print(\"logic loaded\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f23b1e30",
+   "metadata": {},
+   "source": [
+    "## 4. Run"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "df4a1338",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# token\n",
+    "if HF_TOKEN.strip():\n",
+    "    os.environ[\"HF_TOKEN\"] = HF_TOKEN.strip()\n",
+    "    os.environ[\"HUGGING_FACE_HUB_TOKEN\"] = HF_TOKEN.strip()\n",
+    "\n",
+    "# 1) manifest + shards\n",
+    "if EXTRACTED_ROOT:\n",
+    "    mr = Path(EXTRACTED_ROOT)\n",
+    "    shards = sorted((mr / \"shards\").glob(\"*.tar\")) or sorted(mr.glob(\"*.tar\"))\n",
+    "    manifest = mr / _MANIFEST[SPLIT]\n",
+    "    assert shards, f\"không thấy *.tar dưới {mr}\"\n",
+    "    assert manifest.is_file(), f\"không thấy manifest: {manifest}\"\n",
+    "    print(f\"[local] manifest={manifest}  shards={len(shards)}\")\n",
+    "else:\n",
+    "    manifest, shards = download_from_hf(REPO_ID, SPLIT, WORK)\n",
+    "\n",
+    "# 2) đọc nhãn  3) rút ảnh (+ report)\n",
+    "label_map = load_label_map(manifest)\n",
+    "cpos, cunc = export(shards, label_map, OUT, UNCERTAIN, LINK, with_report=WITH_REPORT)\n",
+    "print(f\"\\nXong! Output: {Path(OUT).resolve()}\")"
+   ]
+  }
+ ],
+ "metadata": {},
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/convert_md.py

@@ -26,7 +26,7 @@ OUTPUT_NAME = None
 # GOP NHIEU FILE THANH 1 BAO CAO:
 #   - De COMBINE = [] (rong)  -> dung che do INPUT o tren (convert tung file rieng).
 #   - Liet ke file theo dung thu tu -> gop thanh 1 file COMBINE_OUTPUT duy nhat.
-COMBINE = ["report_part1.md", "methodology_rewrite.md", "report_part4_5.md"]
+COMBINE = ["report_front.md", "report_part1.md", "methodology_rewrite.md", "report_part4_5.md"]
 COMBINE_OUTPUT = "report.docx"
 
 # =====================================================================

docs/export_eda_figs.py

@@ -0,0 +1,51 @@
+"""
+Trích các biểu đồ EDA đã render sẵn trong output cell của notebook -> file PNG.
+Chay: python export_eda_figs.py   (anh ra docs/figures/)
+
+Neu ban chay lai notebook va cell index doi, sua dict PICKS ben duoi.
+"""
+import base64, json
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+NB_DIR = HERE.parent / "data"
+OUT = HERE / "figures"
+OUT.mkdir(exist_ok=True)
+
+# (notebook, cell_index) -> ten file png
+PICKS = {
+    ("eda_full.ipynb", 25): "eda_chexpert_labels.png",   # P/U/N 14 nhan
+    ("eda_full.ipynb", 17): "eda_views.png",             # view position bar+pie
+    ("eda_full.ipynb", 14): "eda_imgs_per_study.png",    # so anh / study
+    ("eda_full.ipynb", 31): "eda_report_length.png",     # do dai findings/impression
+    ("eda_full.ipynb", 40): "eda_vqa_types.png",         # semantic + content type
+    ("build_subset_local.ipynb", 16): "eda_prevalence_compare.png",  # full vs elig vs subset
+    ("build_subset_local.ipynb", 17): "eda_vqa_compare.png",         # VQA full vs subset
+}
+
+
+def first_png(cell):
+    for o in cell.get("outputs", []):
+        img = (o.get("data", {}) or {}).get("image/png")
+        if img:
+            return img if isinstance(img, str) else "".join(img)
+    return None
+
+
+def main():
+    for (nb_name, idx), out_name in PICKS.items():
+        nb = json.load(open(NB_DIR / nb_name, encoding="utf-8"))
+        if idx >= len(nb["cells"]):
+            print(f"[x] {nb_name}: khong co cell {idx}")
+            continue
+        png_b64 = first_png(nb["cells"][idx])
+        if not png_b64:
+            print(f"[x] {nb_name} cell {idx}: khong co anh output")
+            continue
+        (OUT / out_name).write_bytes(base64.b64decode(png_b64))
+        src = "".join(nb["cells"][idx].get("source", []))
+        print(f"[+] {out_name:<28s} <- {nb_name} cell {idx}  ({src[:55].strip()}...)")
+
+
+if __name__ == "__main__":
+    main()

docs/make_figures.py

@@ -296,12 +296,13 @@ def fig01_pipeline():
 # ---- cac hinh con lai (don gian, den trang) --------------------------------
 
 def fig02_data_pipeline():
-    fig, ax = canvas(132, 24)
+    fig, ax = canvas(136, 24)
     hrow(ax, 12, [
-        (16, 22, "[Local]\nSelection", False),
-        (49, 26, "[Cloud VM]\nImage download", False),
-        (84, 22, "[GPU]\nResize + shard", False),
-        (118, 18, "Unified\nJSON", False),
+        (16, 22, "Data Sources", False),
+        (49, 22, "[Local]\nSelection", False),
+        (82, 26, "[Cloud VM]\nImage download", False),
+        (117, 22, "Resize + shard", False),
+        (151, 18, "Unified\nJSON", False),
     ], h=14)
     ax.text(49, 2, "(download from PhysioNet -> push to Hugging Face)",
             ha="center", fontsize=6.6)

docs/methodology_rewrite.md

@@ -1,14 +1,14 @@
 # 3. Materials and Methods
 
-This chapter describes how the proposed Vision–Language Model (**CXR-VLM**) is built and trained. It is organised in six parts. Section 3.1 gives an end-to-end overview. Section 3.2 defines the key concepts used throughout the chapter. Section 3.3 documents how the MIMIC-CXR corpus is filtered and serialised into the unified instruction format. Section 3.4 describes the four modules of the model and the prompt that ties them together. Section 3.5 specifies the two-stage training schedule. Section 3.6 defines the evaluation protocol.
+This chapter describes how the proposed Vision–Language Model (CXR-VLM) is built and trained. It is organised in six parts. Section 3.1 gives an end-to-end overview. Section 3.2 defines the key concepts used throughout the chapter. Section 3.3 documents how the MIMIC-CXR corpus is analysed, filtered, and serialised into the training format. Section 3.4 describes the four modules of the model and the prompt that ties them together. Section 3.5 specifies the two-stage training schedule. Section 3.6 defines the evaluation protocol.
 
 ---
 
 ## 3.1 Overview
 
-CXR-VLM is a single vision–language network that solves three downstream tasks — **findings generation**, **impression generation**, and **visual question answering (VQA)** — through one shared backbone. The design follows the RaDialog recipe, with two modifications inspired by META-CXR's U-MultiClass and BLIP-2's image–text contrastive alignment:
+CXR-VLM is a single vision–language network that solves three downstream tasks — findings generation, impression generation, and visual question answering (VQA) — through one shared backbone. It couples a frozen image encoder, a trainable projection, and a LoRA-adapted language model, with two design choices aimed at clinical reliability and at fitting a limited compute budget:
 
-- a frozen 14-pathology CheXpert-style classifier whose predictions are serialised into the prompt as a **Positive / Negative / Uncertain (PNU)** string, and
+- a frozen 14-pathology CheXpert-style classifier whose predictions are serialised into the prompt as a Positive / Negative / Uncertain (PNU) string, and
 - an optional contrastive Stage 1 that pre-aligns the projection in a joint image–text space without ever loading the language model.
 
 The full forward path can be summarised as:
@@ -17,7 +17,7 @@ $$
 \mathbf{x}_{518\times518} \xrightarrow{\text{RAD-DINO}} \mathbf{P} \in \mathbb{R}^{B\times 1369\times 768} \xrightarrow{\text{MLP-Proj}} \mathbf{V} \in \mathbb{R}^{B\times 32\times 4096} \xrightarrow{\text{Vicuna-7B + LoRA}} \hat{\mathbf{y}}
 $$
 
-Only the MLP projection, the LoRA adapters on Vicuna, and (when enabled) the ITC head are trained. The image encoder, the CheXpert classifier, and the Vicuna base weights are kept frozen. In total, fewer than **0.3%** of the parameters are trainable (≈ 21.5 M of ≈ 7.1 B).
+Only the MLP projection, the LoRA adapters on Vicuna, and (when enabled) the ITC head are trained. The image encoder, the CheXpert classifier, and the Vicuna base weights are kept frozen. In total, fewer than 0.3% of the parameters are trainable (≈ 21.5 M of ≈ 7.1 B).
 
 ![Hình 3.1. Sơ đồ tổng thể quy trình của CXR-VLM: từ dữ liệu, huấn luyện hai stage, tới suy luận và đánh giá.](figures/fig15_workflow.png)
 
@@ -29,31 +29,31 @@ This section defines the core concepts that the rest of the chapter relies on.
 
 - **Vision–Language Model (VLM).** A model that takes an image together with a text instruction and produces a text response, by mapping visual features into the embedding space of a language model.
 
-- **Chest X-ray report.** A radiology report has two main free-text sections. **Findings** is the detailed, observation-by-observation description of the image; **Impression** is the short clinical summary written *after* the findings. We treat their generation as two separate tasks.
+- **Chest X-ray report.** A radiology report has two main free-text sections. Findings is the detailed, observation-by-observation description of the image; Impression is the short clinical summary written *after* the findings. We treat their generation as two separate tasks.
 
 - **Visual Question Answering (VQA).** Given an image and a natural-language question, the model returns a short answer (often a single word or phrase).
 
-- **Large Language Model (LLM).** A transformer trained on large text corpora to generate human-like text. We use **Vicuna-7B**, a LLaMA-derived instruction-tuned chat model, as the decoder.
+- **Large Language Model (LLM).** A transformer trained on large text corpora to generate human-like text. We use Vicuna-7B, a LLaMA-derived instruction-tuned chat model, as the decoder.
 
-- **Vision Transformer (ViT) and self-supervision.** A ViT splits an image into fixed-size patches and processes them as a token sequence. **RAD-DINO** is a ViT-B/14 trained with DINOv2 self-supervision on chest X-rays; it requires no text labels.
+- **Vision Transformer (ViT) and self-supervision.** A ViT splits an image into fixed-size patches and processes them as a token sequence. RAD-DINO is a ViT-B/14 trained with DINOv2 self-supervision on chest X-rays; it requires no text labels.
 
-- **Parameter-efficient fine-tuning (LoRA / QLoRA).** Instead of updating all weights of the LLM, **LoRA** inserts small trainable low-rank matrices into selected layers and freezes the rest. **QLoRA** additionally keeps the base weights in 4-bit quantisation, which drastically reduces memory.
+- **Parameter-efficient fine-tuning (LoRA / QLoRA).** Instead of updating all weights of the LLM, LoRA inserts small trainable low-rank matrices into selected layers and freezes the rest. QLoRA additionally keeps the base weights in 4-bit quantisation, which drastically reduces memory.
 
 - **Image–Text Contrastive learning (ITC / InfoNCE).** A training objective that pulls the embedding of an image and its matching text together while pushing non-matching pairs apart, using the symmetric InfoNCE loss. It is the mechanism behind Stage 1 alignment.
 
-- **CheXpert labels and U-MultiClass.** CheXpert defines 14 pathology categories. Rather than a binary present/absent label, **U-MultiClass** keeps three states per pathology — **Positive**, **Negative**, **Uncertain** — preserving the clinically important difference between a confident negative and a hedged one.
+- **CheXpert labels and U-MultiClass.** CheXpert defines 14 pathology categories. Rather than a binary present/absent label, U-MultiClass keeps three states per pathology — Positive, Negative, Uncertain — preserving the clinically important difference between a confident negative and a hedged one.
 
 ---
 
 ## 3.3 Data Preparation
 
-The data pipeline runs in three phases, each placed where it is most efficient. **(i) Selection** runs locally on the MIMIC-CXR CSV metadata to decide which studies to keep. **(ii) Image download** runs on a cloud virtual machine (Google Colab): the images chosen in the manifest are downloaded from PhysioNet onto the VM's disk and then pushed to a Hugging Face repository for reuse. This step is done in the cloud rather than on a local machine because the selected image set is too large for the local disk, and the cloud VM also has a faster, more stable connection to PhysioNet. **(iii) Resize and re-shard** runs once on a GPU host so that every training run consumes minimal-size JPEGs. The same subset is reused across all experiments, so the pipeline is run **once** — changing prompt templates or task weights only rebuilds the JSON, not the images.
+The data pipeline runs in three phases, each placed where it is most efficient. (i) Selection runs locally on the MIMIC-CXR CSV metadata to decide which studies to keep. (ii) Image download runs on a cloud virtual machine (Google Colab): the images chosen in the manifest are downloaded from PhysioNet onto the VM's disk and then pushed to a Hugging Face repository for reuse. This step is done in the cloud rather than on a local machine because the selected image set is too large for the local disk, and the cloud VM also has a faster, more stable connection to PhysioNet. (iii) Resize and re-shard runs once on a GPU host so that every training run consumes minimal-size JPEGs. The same subset is reused across all experiments, so the pipeline is run once — changing prompt templates or task weights only rebuilds the JSON, not the images.
 
 ![Hình 3.2. Pipeline dữ liệu 3 phase: selection (local) → image download (VM cloud → Hugging Face) → resize/shard → unified JSON.](figures/fig02_data_pipeline.png)
 
-### 3.3.1 Sources
+### 3.3.1 Sources and dataset overview
 
-All sources come from the public PhysioNet distribution under credentialed access; no manual annotation is performed.
+All data come from the public PhysioNet distribution under credentialed access; no manual annotation is performed.
 
 | Source | Version | Used for |
 |---|---|---|
@@ -61,50 +61,88 @@ All sources come from the public PhysioNet distribution under credentialed acces
 | MIMIC-CXR-JPG | 2.1.0 | Pre-converted JPEG images |
 | MIMIC-Ext-CXR-VQA | 1.0.0 | (image, question, answer) triples |
 | `mimic-cxr-2.0.0-split` | — | Official patient-disjoint train/validate/test split |
-| `mimic-cxr-2.0.0-metadata` | — | `ViewPosition` for frontal selection |
+| `mimic-cxr-2.0.0-metadata` | — | `ViewPosition` (used for frontal selection) |
 | `mimic-cxr-2.0.0-chexpert` | — | 14 pathology labels per study |
 
-### 3.3.2 Selection Pipeline
+An exploratory analysis of the full corpus motivates the design choices below. MIMIC-CXR contains 377,110 images from 227,835 studies of 65,379 patients (on average 1.66 images per study and 3.48 studies per patient).
 
-A four-stage filter chain reduces the ≈ 227,000 MIMIC-CXR studies to a working subset of **50,000 studies (40,000 train / 5,000 validation / 5,000 test)**.
+- **Label imbalance (Hình 3.3).** The 14 CheXpert labels are highly imbalanced: *No Finding* (33% positive), *Support Devices* (29%), *Pleural Effusion* (24%), and *Lung Opacity* (23%) dominate, while *Fracture* (1.9%) and *Pleural Other* (0.9%) are rare — which directly affects the abnormality classifier in Section 4.2.2.
+- **Views (Hình 3.4).** Each study can contain several views. Frontal projections — AP (147,173) and PA (96,161) — together make up the majority; the rest are lateral (LATERAL 82,853, LL 35,133) or have no recorded `ViewPosition` (15,769).
+- **Images per study (Hình 3.5).** Many studies contain two or more images (mean 1.66, up to 11), even though they share a single report.
+- **Report sections (Hình 3.6).** Parsing all reports, a clean Findings section is present in 149,060 studies (65%) and an Impression in 186,865 (82%); many reports therefore lack one section. Findings are longer (median ≈ 45 words) than Impression (median ≈ 16 words).
+- **VQA (Hình 3.7).** MIMIC-Ext-CXR-VQA provides 377,391 (image, question, answer) triples over these images, organised by semantic type (verify / choose / query) and content type (presence, anatomy, attribute, size, …).
 
-- **(a) Frontal-only filtering.** Each DICOM is joined with the metadata CSV; only `ViewPosition ∈ {PA, AP}` rows are kept. A study with several frontal exposures is collapsed to one image, preferring PA over AP. After this step every retained study contributes exactly one image — the assumption behind `image_mode = frontal_only_split`.
-- **(b) Report parsing.** A strict regex accepts a section only if its header is exactly `FINDINGS` or `IMPRESSION`. Synonyms (`CONCLUSION`, `WET READ`, composite headers) are deliberately not merged. A study survives only if **both** sections are present and non-empty — required for `split_cascade`, where the impression prompt uses the ground-truth findings.
-- **(c) Length-based outlier removal.** Per-section word counts are computed; studies above `Q3 + 1.5·IQR` (multi-paragraph teaching reports) or below a small floor are dropped. This trims the long tail without shifting the median.
-- **(d) Stratified patient-disjoint sampling.** Each study is assigned a stratum equal to its rarest positive CheXpert label; the target counts are allocated per stratum proportionally to prevalence. Validation/test pools are filled first from the official split; any overflow is drawn from train and the affected subjects removed from train. The three sets are therefore **patient-disjoint**.
+![Hình 3.3. Phân bố 14 nhãn CheXpert (Positive / Uncertain / Negative) trên toàn bộ MIMIC-CXR — mất cân bằng mạnh: No Finding và Support Devices áp đảo, Fracture và Pleural Other rất hiếm.](figures/eda_chexpert_labels.png)
 
-Distribution preservation is checked by comparing per-pathology prevalence at the raw, eligible-pool, and final-subset levels.
+![Hình 3.4. Phân bố View Position: hai view frontal (AP, PA) chiếm đa số; phần còn lại là lateral (LATERAL, LL).](figures/eda_views.png)
 
-![Hình 3.3. Chuỗi lọc 4 tầng rút gọn corpus MIMIC-CXR còn 50k study.](figures/fig03_selection_funnel.png)
+![Hình 3.5. Số ảnh mỗi study (trung bình 1.66) — rất nhiều study có từ hai ảnh trở lên dù chỉ có một report.](figures/eda_imgs_per_study.png)
+
+![Hình 3.6. Phân bố độ dài (số từ) của Findings và Impression: Impression ngắn hơn nhiều (median ≈ 16 từ so với ≈ 45 từ của Findings).](figures/eda_report_length.png)
+
+![Hình 3.7. Phân bố câu hỏi VQA theo semantic type và content type.](figures/eda_vqa_types.png)
+
+### 3.3.2 Selecting the working subset
+
+We do not train on the full corpus. With no dedicated GPU available, training is done in the cloud, where compute is billed by the hour; repeatedly processing all ≈ 227k studies (≈ 377k images) would be both slow and expensive. A subset of 50,000 studies (40,000 train / 5,000 validation / 5,000 test) is large enough to train and evaluate the model while keeping cloud time and cost manageable, and — as Table 3.1 shows — it preserves the pathology distribution of the full dataset, so results on it remain representative.
+
+A four-stage filter chain produces this subset:
+
+- **(a) One frontal image per study.** Each DICOM is joined with the metadata CSV and only frontal views (`ViewPosition ∈ {PA, AP}`) are kept; if a study has several, it is collapsed to one image, preferring PA over AP. We use a single frontal image per study for two reasons. First, the frontal projection carries the most diagnostic information, and PA is the standard reference view (AP is reserved for bedside/portable exams), so PA is preferred when both exist. Second, we deliberately avoid multi-view training: besides its higher per-study compute, it is noisy here — a study has a single report that does not state which finding belongs to which view, so pairing several images with one report can mislead the model. Multi-view training is left as future work (Section 5).
+- **(b) Both report sections present.** A strict regex accepts a section only if its header is exactly `FINDINGS` or `IMPRESSION`; synonyms (`CONCLUSION`, `WET READ`, composite headers) are not merged. A study survives only if both sections are present and non-empty, because the impression task later conditions on the ground-truth findings (Section 3.4.5).
+- **(c) Length-based outlier removal.** Per-section word counts are computed; studies above `Q3 + 1.5·IQR` (multi-paragraph teaching reports) or below a small floor are dropped, trimming the long tail without shifting the median.
+- **(d) Stratified patient-disjoint sampling.** Each study is assigned a stratum equal to its rarest positive CheXpert label; target counts are allocated per stratum proportionally to prevalence. The validation/test pools are filled first from the official split, any overflow drawn from train with the affected subjects removed from train, so the three sets are patient-disjoint.
+
+After steps (a)–(c) the eligible pool is 108,783 studies (from the 227,835 total), and step (d) samples the final 50,000.
+
+![Hình 3.8. Chuỗi lọc 4 tầng rút gọn corpus MIMIC-CXR còn 50,000 study.](figures/fig03_selection_funnel.png)
+
+**Distribution preserved after selection.** To confirm the subset is representative, Table 3.1 and Hình 3.9 compare the per-pathology positive rate of the full dataset, the eligible pool, and the final subset. The subset tracks the eligible pool almost exactly (largest gap 1.25 pp, on *No Finding*). The eligible pool itself differs from the raw corpus — mainly a higher *No Finding* rate and lower *Support Devices* / *Pleural Effusion* — which is expected, since requiring a clean Findings + Impression section and a frontal view removes many device-heavy ICU portables.
+
+**Table 3.1.** CheXpert positive rate (%) at three stages of selection (largest 8 labels shown; |Δ| = subset − eligible).
+
+| Pathology | Full (%) | Eligible (%) | Subset (%) | \|Δ\| |
+|---|---|---|---|---|
+| No Finding | 33.1 | 51.6 | 52.8 | 1.25 |
+| Support Devices | 29.2 | 8.7 | 8.5 | 0.24 |
+| Pleural Effusion | 23.8 | 12.3 | 11.6 | 0.65 |
+| Lung Opacity | 22.6 | 14.9 | 14.5 | 0.34 |
+| Atelectasis | 20.1 | 11.0 | 10.7 | 0.29 |
+| Cardiomegaly | 19.7 | 6.6 | 6.3 | 0.30 |
+| Edema | 11.9 | 8.0 | 7.6 | 0.46 |
+| Pneumonia | 7.3 | 5.6 | 5.6 | 0.01 |
+
+![Hình 3.9. Tỉ lệ positive của 14 nhãn CheXpert ở ba mức — full dataset, eligible pool, và subset 50k — subset bám sát phân phối gốc.](figures/eda_prevalence_compare.png)
+
+The VQA distribution is likewise preserved: Hình 3.10 shows that the shares of question semantic types, content types, and answer types in the subset closely match the full dataset, so the VQA evaluation on the subset is not biased towards any question category.
+
+![Hình 3.10. Phân bố câu hỏi VQA (semantic type, content type, answer type) — full dataset vs subset 50k: subset bám sát phân phối gốc.](figures/eda_vqa_compare.png)
 
 ### 3.3.3 Storage and Consumption Layout
 
 For each split a manifest is emitted as JSON and CSV. Every row captures one image plus the standard PhysioNet identifiers, the 14 `chex_*` U-MultiClass label columns, and a `has_vqa` flag. The PhysioNet directory layout (`files/pXX/pSUBJ/sSTUDY/<dicom>.jpg`) is preserved so a partial download can be checked against the manifest by path lookup.
 
-Because all training hosts consume the same images, we resize **once** offline. RAD-DINO centre-crops to 518×518 regardless of input, so the full-resolution JPEGs (~2–3 MP each, ~100 GB) are wasteful. Each image is resized so the shortest edge is 518, saved as JPEG quality 90, and packed into ~2 GB tar shards; the 50k subset compresses to ~5–8 GB.
+Because all training hosts consume the same images, we resize once offline. RAD-DINO centre-crops to 518×518 regardless of input, so the full-resolution JPEGs (~2–3 MP each, ~100 GB) are wasteful. Each image is resized so the shortest edge is 518, saved as JPEG quality 90, and packed into ~2 GB tar shards; the 50k subset compresses to ~5–8 GB.
 
-### 3.3.4 Unified Instruction JSON
+### 3.3.4 Training data format
 
-On the training host, a single **builder** turns the resized tree plus manifests and VQA files into one per-sample JSON, with a fixed schema:
+On the training host, a single builder turns the resized images, the manifests, and the VQA files into one JSON file — one entry per training sample — with a fixed schema:
 
 ```
 { image_path, task, target, question, structured_findings, split, study_id, subject_id }
 ```
 
-Two knobs control sample creation:
+Each selected study (one frontal image) yields up to three kinds of sample:
 
-- **`report_mode`** controls the findings/impression decomposition. The experiments use **`split_cascade`**: findings is generated from the image alone, and impression is generated from the image **plus the ground-truth findings** as a textual context block. Studies without findings emit no impression sample.
-- **`image_mode`** controls how multiple views are handled. The experiments use **`frontal_only_split`** (one PA-or-AP image per study), which together with step (a) makes the image–study relationship one-to-one.
+- a findings sample — target is the Findings paragraph, generated from the image and the abnormality (PNU) string;
+- an impression sample — target is the Impression, generated from the image plus the study's ground-truth Findings as context. The impression is thus produced as a short summary of the findings (a findings → impression cascade), which mirrors clinical practice, where the impression is written after the findings; this is also why step (b) requires a clean Findings section;
+- **VQA** samples (when the study has associated questions) — target is the answer, with the question itself acting as the instruction.
 
-| Mode | Behaviour |
-|---|---|
-| `split` | Two independent tasks; each sees only image + PNU string. |
-| `split_cascade` | As above, but impression conditions on the GT findings string (findings → impression summarisation). |
-| `merged` | One `report` task emitting both sections in a single pass. |
+The 14 CheXpert labels are formatted into the PNU string (Section 3.4.3) and written into the `structured_findings` field at build time, so the trainer loads no labels at runtime. For the impression sample, this same field instead carries the ground-truth Findings text.
 
-The 14 CheXpert labels are formatted into the PNU string and written into `structured_findings` at build time, so the trainer loads no labels at runtime. In `split_cascade` the impression sample reuses this same field to carry `Findings: <GT findings>` instead of the PNU string.
+Because there is exactly one frontal image per study, the findings and impression tasks each contribute one sample per study (about 50,000 samples each). VQA, however, is larger — 127,010 question–answer samples in total (102,941 train / 12,189 validation / 11,880 test) — because a single image can be paired with several different questions in MIMIC-Ext-CXR-VQA.
 
-![Hình 3.4. Cách một study sinh ra training sample dưới `split_cascade` + `frontal_only_split`.](figures/fig04_sample_creation.png)
+![Hình 3.11. Một study (một ảnh frontal) sinh ra các training sample: findings (ảnh → findings), impression (ảnh + GT findings → impression), và VQA.](figures/fig04_sample_creation.png)
 
 ---
 
@@ -112,16 +150,16 @@ The 14 CheXpert labels are formatted into the PNU string and written into `struc
 
 The model has four modules — image encoder, MLP projection, CheXpert classifier, and language model with LoRA — plus the prompt format that connects them. Each module is described below by its objective, inputs, outputs, and core logic.
 
-![Hình 3.5. Kiến trúc tổng quan của CXR-VLM (xanh = frozen, cam = trainable).](figures/fig01_pipeline.png)
+![Hình 3.12. Kiến trúc tổng quan của CXR-VLM (xanh = frozen, cam = trainable).](figures/fig01_pipeline.png)
 
 ### 3.4.1 Image Encoder
 
 - **Objective.** Turn a chest X-ray into a dense grid of patch features for the projection.
 - **Input.** A 518×518 image (RAD-DINO's native resolution, matching the offline resize target).
 - **Output.** Patch features `P ∈ R^{1369×768}`; the `[CLS]` token is discarded.
-- **Core logic.** The backbone is Microsoft's **RAD-DINO** (ViT-B/14), self-supervised on ≈ 840k chest X-rays. It is loaded from the HuggingFace hub and kept **entirely frozen**. RAD-DINO is preferred over the original RaDialog backbone BioViL-T because it ships as a standard HuggingFace model (no legacy library pinning Python < 3.11), is trained on roughly an order of magnitude more chest-X-ray data, and produces a patch grid dense enough to capture both global pathology and small focal abnormalities. Freezing is chosen for stability and memory: with the LLM held in 4-bit, gradient flow through an 86 M-parameter ViT would exhaust the activation budget of consumer GPUs.
+- **Core logic.** The backbone is Microsoft's RAD-DINO (ViT-B/14), self-supervised on ≈ 840k chest X-rays. It is loaded from the HuggingFace hub and kept entirely frozen. RAD-DINO is chosen because it ships as a standard HuggingFace model, is trained on a large amount of chest-X-ray data, and produces a patch grid dense enough to capture both global pathology and small focal abnormalities. Freezing is chosen for stability and memory: with the LLM held in 4-bit, gradient flow through an 86 M-parameter ViT would exhaust the activation budget of the GPUs available for this work.
 
-![Hình 3.6. Kiến trúc RAD-DINO (ViT-B/14): ảnh 518×518 → 1369 patch → patch + position embedding → 12 khối Transformer Encoder (frozen) → [CLS] + patch token (768-d).](figures/fig05_patchify.png)
+![Hình 3.13. Kiến trúc RAD-DINO (ViT-B/14): ảnh 518×518 → 1369 patch → patch + position embedding → 12 khối Transformer Encoder (frozen) → [CLS] + patch token (768-d).](figures/fig05_patchify.png)
 
 ### 3.4.2 MLP Projection
 
@@ -140,16 +178,16 @@ $$
 \mathbf{V} = \mathbf{W}_2 \mathbf{H}^{(1)} \in \mathbb{R}^{32\times 4096}
 $$
 
-with `Q₀` a learnable parameter and `CrossAttn` an 8-head attention block. The number of visual tokens (32) follows RaDialog and sits in the empirical sweet spot reported by LLaVA and BLIP-2 — fewer loses spatial detail on small pathologies, more only inflates the LLM sequence length. The 1024-d intermediate `H⁽¹⁾` is the grounding signal of the ITC head; it sits *after* the GELU so the contrastive objective sees an already-nonlinear representation.
+with `Q₀` a learnable parameter and `CrossAttn` an 8-head attention block. We use 32 visual tokens: enough to retain spatial detail on small pathologies without inflating the LLM's sequence length. The 1024-d intermediate `H⁽¹⁾` is the grounding signal of the ITC head; it sits *after* the GELU so the contrastive objective sees an already-nonlinear representation.
 
-![Hình 3.7. Module MLP Projection: 32 query → cross-attention → MLP, với nhánh 1024-d cho ITC head.](figures/fig06_projection.png)
+![Hình 3.14. Module MLP Projection: 32 query → cross-attention → MLP (768 → 1024 → 4096), với nhánh 1024-d cho ITC head.](figures/fig06_projection.png)
 
 ### 3.4.3 CheXpert Abnormality Classifier
 
 - **Objective.** Provide explicit abnormality cues to the prompt as a readable 3-class string instead of a logit vector.
 - **Input.** The global `[CLS]` embedding of RAD-DINO.
 - **Output.** A 14×3 logit tensor → one of {Positive, Negative, Uncertain} per pathology → the PNU string.
-- **Core logic.** A small MLP head on the frozen `[CLS]` embedding, in the U-MultiClass style of META-CXR. The string injected into the prompt looks like:
+- **Core logic.** A small MLP head on the frozen `[CLS]` embedding, predicting three states (positive / negative / uncertain) per pathology. The string injected into the prompt looks like:
 
 ```
 Positive Abnormalities: Cardiomegaly, Pleural Effusion
@@ -157,18 +195,18 @@ Negative Abnormalities: No Finding, Edema, Pneumothorax, ...
 Uncertain Abnormalities: Atelectasis
 ```
 
-Three properties motivate this design. (1) U-MultiClass preserves the negative-vs-uncertain distinction, which binary CheXpert mappings destroy. (2) Expressing labels as text needs no architectural change when labels are missing — the field simply becomes empty and the prompt degrades gracefully. (3) Placing the PNU string between the visual tokens and the instruction lets self-attention route freely between text and image. The classifier is trained separately in Stage 0 and then frozen. During VLM training the ground-truth CSV labels populate the PNU string (oracle setting); at evaluation the classifier predicts its own PNU.
+Three properties motivate this design. (1) The three-state form preserves the negative-vs-uncertain distinction, which binary CheXpert mappings destroy. (2) Expressing labels as text needs no architectural change when labels are missing — the field simply becomes empty and the prompt degrades gracefully. (3) Placing the PNU string between the visual tokens and the instruction lets self-attention route freely between text and image. The classifier is trained separately in Stage 0 and then frozen. During VLM training the ground-truth CSV labels populate the PNU string (oracle setting); at evaluation the classifier predicts its own PNU.
 
-![Hình 3.8. Từ embedding [CLS] của RAD-DINO tới PNU string đưa vào prompt.](figures/fig07_chexpert_pnu.png)
+![Hình 3.15. Từ embedding [CLS] của RAD-DINO tới PNU string đưa vào prompt.](figures/fig07_chexpert_pnu.png)
 
 ### 3.4.4 Language Model and Parameter-Efficient Adaptation
 
 - **Objective.** Generate the findings / impression / answer text conditioned on visual tokens and the prompt.
 - **Input.** The assembled token sequence with the `<image>` placeholder replaced by 32 visual tokens.
 - **Output.** The autoregressive text response.
-- **Core logic.** The decoder is **Vicuna-7B v1.3**, chosen to match the RaDialog baseline and for its clean `USER: … ASSISTANT: …` template (which simplifies label masking). It is loaded in **4-bit NF4 quantisation** (double-quant, compute dtype BF16 on Ampere+ / FP16 on Turing), bringing the resident footprint from ≈ 14 GB down to ≈ 4 GB. Adaptation uses **LoRA**: rank-16 adapters on the four attention projections (`q_proj`, `k_proj`, `v_proj`, `o_proj`) of every block; the feed-forward sublayers are left untouched. With `lora_alpha = 32` and `lora_dropout = 0.05`, the effective scaling is `α/r = 2`.
+- **Core logic.** The decoder is Vicuna-7B v1.3, chosen for its clean `USER: … ASSISTANT: …` chat template (which simplifies label masking) and for offering strong instruction-following at a 7B size that fits the available hardware budget. It is loaded in 4-bit NF4 quantisation (double-quant, compute dtype BF16 on Ampere+ / FP16 on Turing), bringing the resident footprint from ≈ 14 GB down to ≈ 4 GB. Adaptation uses LoRA: rank-16 adapters on the four attention projections (`q_proj`, `k_proj`, `v_proj`, `o_proj`) of every block; the feed-forward sublayers are left untouched. With `lora_alpha = 32` and `lora_dropout = 0.05`, the effective scaling is `α/r = 2`.
 
-![Hình 3.9. Kiến trúc Vicuna-7B (decoder ×32, frozen 4-bit): masked self-attention + feed-forward MLP; LoRA (A→B, r=16) chèn vào q/k/v/o là phần trainable duy nhất.](figures/fig08_lora.png)
+![H��nh 3.16. Kiến trúc Vicuna-7B (decoder ×32, frozen 4-bit): masked self-attention + feed-forward MLP; LoRA (A→B, r=16) chèn vào q/k/v/o là phần trainable duy nhất.](figures/fig08_lora.png)
 
 ### 3.4.5 Prompt Assembly
 
@@ -181,25 +219,25 @@ All three tasks share one prompt skeleton, following Vicuna's v1.1 chat template
 {instruction} ASSISTANT: {target}
 ```
 
-The `<image>` placeholder is a special token (id 32000). At forward time the model finds this single token, replaces its embedding with the 32 visual tokens, and **expands the attention mask, position ids, and label tensor by 31 positions** so the causal mask stays consistent. Visual-token positions in the label tensor are set to **−100** so they are excluded from the loss.
+The `<image>` placeholder is a special token (id 32000). At forward time the model finds this single token, replaces its embedding with the 32 visual tokens, and expands the attention mask, position ids, and label tensor by 31 positions so the causal mask stays consistent. Visual-token positions in the label tensor are set to −100 so they are excluded from the loss.
 
-The task-specific context block is the main difference between `split` and `split_cascade`:
+The task-specific context block differs per task:
 
-- **Findings** — block empty; produce the findings from image + PNU labels.
-- **Impression** — block is the literal `Findings: <GT findings>`; the model conditions on the ground-truth findings and summarises it. (In the code this string is carried through the same `structured_findings` field, replacing the PNU string for the impression sample.)
-- **VQA** — block empty; the question becomes the instruction.
+- **Findings** — block empty; the findings are produced from the image plus the PNU labels.
+- **Impression** — block is the literal `Findings: <ground-truth findings>`; the model conditions on the findings and summarises them.
+- **VQA** — block empty; the question itself becomes the instruction.
 
-Each of findings, impression, and the merged report has ten hand-written instruction paraphrases sampled at training time; at evaluation the first variant is used deterministically. A sample is tokenised with `cutoff_len = 512` and **right-truncation** (the response sits at the right end; left-truncation would destroy the system prompt and PNU block). The label tensor is masked with −100 on every prompt, padding, and visual token, so loss is computed strictly on the assistant response.
+Findings and impression each have ten hand-written instruction paraphrases, sampled at training time; at evaluation the first variant is used deterministically. A sample is tokenised with `cutoff_len = 512` and right-truncation (the response sits at the right end; left-truncation would destroy the system prompt and PNU block). The label tensor is masked with −100 on every prompt, padding, and visual token, so loss is computed strictly on the assistant response.
 
-![Hình 3.10. Cấu trúc prompt và cơ chế mở rộng token `<image>` thành 32 visual token.](figures/fig09_prompt.png)
+![Hình 3.17. Cấu trúc prompt và cơ chế mở rộng token `<image>` thành 32 visual token.](figures/fig09_prompt.png)
 
 ---
 
 ## 3.5 Training Strategy
 
-Training follows a two-stage curriculum modelled on RaDialog, with Stage 1 reformulated as explicit image–text contrastive alignment. The split follows the classic representation-then-instruction division: it is wasteful to drive the LoRA adapters while the projection still emits ill-conditioned visual tokens, and the projection cannot be trained efficiently against the LM loss without paying for a full Vicuna forward at every step. A Stage 0 classifier training precedes both.
+Training uses a two-stage curriculum. Stage 1 first aligns the projection with the report text through explicit image–text contrastive learning; Stage 2 then instruction-tunes the projection together with the LLM's LoRA adapters. The split follows a representation-then-instruction logic: it is wasteful to drive the LoRA adapters while the projection still emits ill-conditioned visual tokens, and the projection cannot be trained efficiently against the language-modelling loss without paying for a full Vicuna forward at every step. A Stage 0 classifier training precedes both.
 
-![Hình 3.11. Lịch huấn luyện hai stage (kèm Stage 0 classifier).](figures/fig10_curriculum.png)
+![Hình 3.18. Lịch huấn luyện hai stage (kèm Stage 0 classifier).](figures/fig10_curriculum.png)
 
 ### 3.5.1 Stage 0 — CheXpert Classifier Head
 
@@ -210,7 +248,7 @@ The PNU classifier is fitted before Stages 1 and 2. It is a small MLP on the fro
 The goal is to specialise the projection (and only the projection) so its visual tokens are linearly aligned with the text representation of the matching report, before any language modelling.
 
 - **Image side.** The 32 intermediate 1024-d tokens are mean-pooled, projected to 128-d, and L2-normalised by the ITC head.
-- **Text side.** The canonical reference sentence per study (findings, falling back to impression) is encoded **once, offline** with `microsoft/BiomedVLP-CXR-BERT-specialized` into a 128-d L2-normalised vector. These are cached as `{study_id → tensor[128]}` and published to the data repo so any host can pull them in seconds.
+- **Text side.** The canonical reference sentence per study (findings, falling back to impression) is encoded once, offline with `microsoft/BiomedVLP-CXR-BERT-specialized` into a 128-d L2-normalised vector. These are cached as `{study_id → tensor[128]}` and published to the data repo so any host can pull them in seconds.
 
 Stage 1 minimises the symmetric InfoNCE loss:
 
@@ -218,11 +256,11 @@ $$
 \mathcal{L}_{\text{ITC}} = -\tfrac{1}{2}\Big[ \sum_{i}\log\frac{\exp(\mathbf{v}_i^\top\mathbf{t}_i/\tau)}{\sum_j \exp(\mathbf{v}_i^\top\mathbf{t}_j/\tau)} + \sum_{i}\log\frac{\exp(\mathbf{t}_i^\top\mathbf{v}_i/\tau)}{\sum_j \exp(\mathbf{t}_i^\top\mathbf{v}_j/\tau)} \Big]
 $$
 
-**Where:** `vᵢ` is the image embedding from projection + ITC head, `tᵢ` the cached text embedding for the same study, and `τ = 0.07` the temperature (following CLIP / CXR-BERT).
+**Where:** `vᵢ` is the image embedding from projection + ITC head, `tᵢ` the cached text embedding for the same study, and `τ = 0.07` the temperature.
 
-The dataset is de-duplicated to one image per `study_id` (the text embedding is study-level). Crucially, Stage 1 loads the model with **`load_llm = False`** — Vicuna is simply not instantiated. Freeing the ≈ 13 GB of Vicuna weights lifts the per-device batch from 8 (Stage 2 budget) to 64–96, which directly enlarges the InfoNCE negative pool. Stage 1 runs for 2 epochs at peak LR `1e-3` with a 5% cosine warm-up; the saved checkpoint is the **projection-only** state dict (the ITC head is discarded, as it has no role at generation time).
+The dataset is de-duplicated to one image per `study_id` (the text embedding is study-level). Crucially, Stage 1 loads the model with `load_llm = False` — Vicuna is simply not instantiated. Freeing the ≈ 13 GB of Vicuna weights lifts the per-device batch from 8 (Stage 2 budget) to 64–96, which directly enlarges the InfoNCE negative pool. Stage 1 runs for 2 epochs at peak LR `1e-3` with a 5% cosine warm-up; the saved checkpoint is the projection-only state dict (the ITC head is discarded, as it has no role at generation time).
 
-![Hình 3.12. Căn chỉnh ảnh–văn bản ở Stage 1 (text embedding precompute offline, loss InfoNCE).](figures/fig11_contrastive.png)
+![Hình 3.19. Căn chỉnh ảnh–văn bản ở Stage 1 (text embedding precompute offline, loss InfoNCE).](figures/fig11_contrastive.png)
 
 ### 3.5.3 Stage 2 — Instruction Tuning
 
@@ -238,15 +276,15 @@ Trainable parameters are the projection's MLP and the LoRA adapters; the encoder
 
 ### 3.5.4 Loss Masking and Image-Token Accounting
 
-The bookkeeping around the `<image>` placeholder deserves explicit mention. The tokenised prompt contains exactly **one** `<image>` token, replaced by 32 visual tokens at forward time. To keep the attention mask, position ids, and labels consistent, the forward pass expands all three by 31 entries at the placeholder: each visual-token mask entry is set to 1, position ids are made contiguous, and the visual span in the labels is filled with −100. The same expansion is applied at inference. This is the most error-prone part of the pipeline — an off-by-one silently shifts the labels and produces a degenerate loss curve — so an integration test asserts that the count of non-−100 label entries is preserved before and after expansion.
+The bookkeeping around the `<image>` placeholder deserves explicit mention. The tokenised prompt contains exactly one `<image>` token, replaced by 32 visual tokens at forward time. To keep the attention mask, position ids, and labels consistent, the forward pass expands all three by 31 entries at the placeholder: each visual-token mask entry is set to 1, position ids are made contiguous, and the visual span in the labels is filled with −100. The same expansion is applied at inference. This is the most error-prone part of the pipeline — an off-by-one silently shifts the labels and produces a degenerate loss curve — so an integration test asserts that the count of non-−100 label entries is preserved before and after expansion.
 
-![Hình 3.13. Masking nhãn — chỉ vùng câu trả lời (response) đóng góp vào loss.](figures/fig12_loss_mask.png)
+![Hình 3.20. Masking nhãn — chỉ vùng câu trả lời (response) đóng góp vào loss.](figures/fig12_loss_mask.png)
 
 ---
 
 ## 3.6 Evaluation Protocol
 
-Evaluation reflects the three downstream tasks. For findings and impression we report **NLG metrics** (lexical, fluency, semantic) plus the **clinical-accuracy** metric standard in chest-X-ray report generation. For VQA we report a short-answer suite plus an optional **LLM-as-judge** evaluation.
+Evaluation reflects the three downstream tasks. For findings and impression we report NLG metrics (lexical, fluency, semantic) plus the clinical-accuracy metric standard in chest-X-ray report generation. For VQA we report a short-answer suite.
 
 | Family | Metric | Tasks |
 |---|---|---|
@@ -256,26 +294,25 @@ Evaluation reflects the three downstream tasks. For findings and impression we r
 | Semantic embedding | BERTScore F1 | findings, impression, VQA |
 | Clinical accuracy | CheXbert macro-F1, P, R | findings, impression |
 | Exact answer | Exact match, token F1 | VQA |
-| Judge model | GPT-4o-mini score (0–5) | VQA (optional) |
 
 ### 3.6.1 Tasks and Held-Out Data
 
-All metrics are computed on the patient-disjoint **test split** (5,000 studies). Inference uses greedy decoding (`do_sample=False`, `num_beams=1`) and the canonical instruction variant (index 0). For findings and impression the model receives the test image plus the PNU string **predicted** by the frozen classifier; the impression prompt additionally receives the ground-truth findings, preserving `split_cascade` consistency. For VQA the question replaces the instruction slot. Maximum new tokens: 300 (findings), 200 (impression), 64 (VQA), matched to the 99th-percentile reference length.
+All metrics are computed on the patient-disjoint test split (5,000 studies). Inference uses greedy decoding (`do_sample=False`, `num_beams=1`) and the canonical instruction variant (index 0). For findings and impression the model receives the test image plus the PNU string predicted by the frozen classifier; the impression prompt additionally receives the ground-truth findings, matching the training setup. For VQA the question replaces the instruction slot. Maximum new tokens: 300 (findings), 200 (impression), 64 (VQA), matched to the 99th-percentile reference length.
 
-![Hình 3.14. Luồng đánh giá theo từng task.](figures/fig13_eval_flow.png)
+![Hình 3.21. Luồng đánh giá theo từng task.](figures/fig13_eval_flow.png)
 
 ### 3.6.2 Natural Language Generation Metrics
 
 - **BLEU.** Corpus-level BLEU-1 and BLEU-4 with NLTK smoothing method 1. Reported for comparability with the RRG literature, but treated as a fluency floor — it correlates weakly with clinical correctness.
-- **ROUGE.** ROUGE-1/2/L F-measures with Porter stemming. ROUGE-L is the most commonly reported single number in prior work (R2Gen, KGAE, RaDialog).
+- **ROUGE.** ROUGE-1/2/L F-measures with Porter stemming. ROUGE-L is the most commonly reported single number for this task.
 - **METEOR.** A weighted token-level F-measure that credits stems and WordNet synonyms (e.g. *cardiomegaly* ↔ *enlarged heart*), with a fragmentation penalty. Of the n-gram-style metrics it correlates best with human judgement on radiology.
 - **BERTScore.** Greedy-aligned cosine similarity between contextual embeddings, aggregated to F1. Captures semantic equivalence the n-gram metrics miss, but has no notion of clinical correctness — it can reward a paraphrase that flips a finding's polarity.
 
 ### 3.6.3 Clinical Correctness: CheXbert F1
 
-CheXbert is a BERT-based labeler mapping a free-text report onto the 14 CheXpert categories. Running it on both the generated and reference reports and comparing the label vectors gives a **factual** correctness measure invariant to paraphrasing. This **Clinical F1** is the primary clinical-accuracy metric used by RaDialog, CheXagent, MAIRA-2 and most RRG work. We report macro-averaged F1, precision, and recall over the 14 pathologies, binarising the labeler's {−1, 0, 1} output by collapsing −1 and 0. When the CheXbert weights are unavailable on a host, the metric degrades gracefully to 0.0 with a warning rather than failing the run.
+CheXbert is a BERT-based labeler mapping a free-text report onto the 14 CheXpert categories. Running it on both the generated and reference reports and comparing the label vectors gives a factual correctness measure invariant to paraphrasing. This Clinical F1 is the de-facto standard clinical-accuracy metric for chest-X-ray report generation. We report macro-averaged F1, precision, and recall over the 14 pathologies, binarising the labeler's {−1, 0, 1} output by collapsing −1 and 0. When the CheXbert weights are unavailable on a host, the metric degrades gracefully to 0.0 with a warning rather than failing the run.
 
-![Hình 3.15. Tính Clinical F1 bằng CheXbert trên report sinh ra và report tham chiếu.](figures/fig14_chexbert_f1.png)
+![Hình 3.22. Tính Clinical F1 bằng CheXbert trên report sinh ra và report tham chiếu.](figures/fig14_chexbert_f1.png)
 
 ### 3.6.4 Visual Question Answering Metrics
 
@@ -284,8 +321,7 @@ VQA targets are short, so the suite differs from generation.
 - **Exact match.** Lower-cased, punctuation-stripped, whitespace-collapsed string equality — the lower bound on correctness; harsh on phrasing but rewards the closed-form yes/no and quantitative questions that dominate the dataset.
 - **Token F1.** F1 between the bags of normalised tokens — the most diagnostic single number for short-answer correctness.
 - **BLEU-1, METEOR, BERTScore.** Reported for symmetry with the generation tasks. BLEU-4 and ROUGE-L are omitted (rarely meaningful / subsumed by token F1).
-- **LLM-as-judge (optional).** For free-form answers where the above misalign with clinical equivalence (e.g. *cardiomegaly* vs *enlarged cardiac silhouette*), GPT-4o-mini is prompted with the question, reference, and prediction and returns an integer 0–5 plus a rationale (G-Eval rubric). We report the mean and its [0, 1] normalisation. The judge runs at temperature 0 with `response_format=json_object`; at most 500 VQA items are sampled to bound cost.
 
 ### 3.6.5 Model Selection and Reporting
 
-Model selection uses `eval_loss` on the validation split (the same causal cross-entropy minimised in training); the best checkpoint by this criterion is evaluated on the test split. We deliberately do **not** select on downstream metrics, to avoid the optimistic bias of optimising the reported signal — and CheXbert F1 in particular is expensive and unstable on small validation samples. Each run writes per-task predictions to `results/{run_id}/predictions_{task}.json` and an aggregated summary to `results/{run_id}/metrics_summary.json`.
+Model selection uses `eval_loss` on the validation split (the same causal cross-entropy minimised in training); the best checkpoint by this criterion is evaluated on the test split. We deliberately do not select on downstream metrics, to avoid the optimistic bias of optimising the reported signal — and CheXbert F1 in particular is expensive and unstable on small validation samples. Each run writes per-task predictions to `results/{run_id}/predictions_{task}.json` and an aggregated summary to `results/{run_id}/metrics_summary.json`.

docs/report_front.md

@@ -0,0 +1,51 @@
+# Acknowledgements
+
+This thesis would not have been possible without the help of many people. My deepest thanks go to my supervisor, [Supervisor name], whose questions, patience, and detailed feedback shaped both the direction of this project and the way I approached it. I am grateful to the lecturers of the Department of Information and Communication Technology at the University of Science and Technology of Hanoi for the foundation they gave me over the past years. Finally, I thank my family and friends, who kept me motivated through the long nights of training runs and debugging that this work demanded.
+
+> *(Điền tên giảng viên hướng dẫn vào `[Supervisor name]`; thêm internal/external supervisor nếu cần.)*
+
+---
+
+# Abstract
+
+This thesis presents CXR-VLM, a vision–language model for chest X-ray interpretation that performs findings generation, impression generation, and visual question answering with a single shared backbone. The model couples a frozen RAD-DINO image encoder with a trainable projection and a Vicuna-7B language model adapted through low-rank (LoRA) adapters, and is explicitly guided by a 14-pathology Positive / Negative / Uncertain (PNU) abnormality signal produced by a CheXpert-style classifier. It is trained with a parameter-efficient two-stage schedule — an image–text contrastive alignment followed by instruction tuning — on a 50,000-study subset of MIMIC-CXR, chosen so that training remains feasible on a limited cloud-compute budget while preserving the pathology distribution of the full dataset. On the held-out test split the model is competitive with established systems on semantic report-generation metrics (ROUGE-L 0.292 and a high METEOR and BERTScore for findings), reaches a visual-question-answering exact match of 0.306 (stronger on closed-ended questions), and its abnormality classifier attains a macro F1 of 0.328. These results show that a frozen-encoder, frozen-LLM design adapted only through a small projection and LoRA adapters can drive three chest-X-ray tasks at once on modest hardware, and point to abnormality classification and clinical-efficacy evaluation as the main directions for further improvement.
+
+---
+
+# List of Abbreviations
+
+| Abbreviation | Meaning |
+|---|---|
+| AI | Artificial Intelligence |
+| AP | Anteroposterior (X-ray view) |
+| BERTScore | BERT-based similarity Score |
+| BLEU | Bilingual Evaluation Understudy |
+| CE | Clinical Efficacy (F1) |
+| CheXbert | BERT-based CheXpert report labeler |
+| CheXpert | Chest eXpert — 14-label chest X-ray labeler |
+| CXR | Chest X-Ray |
+| DINO | self-Distillation with NO labels (DINOv2 self-supervision) |
+| EHR | Electronic Health Record |
+| F1 | F1-score (harmonic mean of precision and recall) |
+| GPU | Graphics Processing Unit |
+| InfoNCE | Info Noise-Contrastive Estimation (loss) |
+| IQR | Interquartile Range |
+| ITC | Image–Text Contrastive (learning) |
+| LLM | Large Language Model |
+| LoRA | Low-Rank Adaptation |
+| METEOR | Metric for Evaluation of Translation with Explicit ORdering |
+| MIMIC-CXR | Medical Information Mart for Intensive Care — Chest X-Ray |
+| MLP | Multi-Layer Perceptron |
+| NF4 | 4-bit NormalFloat quantisation |
+| NLG | Natural Language Generation |
+| PA | Posteroanterior (X-ray view) |
+| PNU | Positive / Negative / Uncertain |
+| QLoRA | Quantised Low-Rank Adaptation |
+| RAD-DINO | Chest-X-ray ViT image encoder (DINOv2-based) |
+| ROUGE | Recall-Oriented Understudy for Gisting Evaluation |
+| RRG | Radiology Report Generation |
+| ViT | Vision Transformer |
+| VLM | Vision–Language Model |
+| VQA | Visual Question Answering |
+
+---

docs/report_part1.md

@@ -2,15 +2,15 @@
 
 ## 1.1 Context and Motivation
 
-The chest X-ray (CXR) is the most frequently performed medical imaging examination in the world, with hundreds of millions of studies acquired every year for the screening and diagnosis of cardiothoracic conditions. Each examination must be read by a radiologist, who then writes a structured free-text report — typically a detailed **Findings** section followed by a concise **Impression**. As imaging volume keeps growing while the number of trained radiologists remains limited, report turnaround time, reader fatigue, and inter-reader variability have become real bottlenecks in clinical workflows.
+The chest X-ray (CXR) is the most frequently performed medical imaging examination in the world, with hundreds of millions of studies acquired every year for the screening and diagnosis of cardiothoracic conditions. Each examination must be read by a radiologist, who then writes a structured free-text report — typically a detailed Findings section followed by a concise Impression. As imaging volume keeps growing while the number of trained radiologists remains limited, report turnaround time, reader fatigue, and inter-reader variability have become real bottlenecks in clinical workflows.
 
-Automatic **radiology report generation (RRG)** aims to ease this burden by drafting a report directly from the image, which the radiologist can then verify and edit. The field has evolved quickly: from early CNN–RNN captioning models, to transformer-based architectures, and most recently to **large vision–language models (VLMs)** such as LLaVA and BLIP-2, whose medical adaptations (RaDialog, LLaVA-Med, CheXagent, MAIRA-2) couple a frozen image encoder with a large language model (LLM) to produce fluent, instruction-following text. In parallel, clinicians often need to ask focused questions about an image — "is there a pleural effusion?", "what is the size of the cardiac silhouette?" — which motivates **visual question answering (VQA)** on chest X-rays.
+Automatic radiology report generation (RRG) aims to ease this burden by drafting a report directly from the image, which the radiologist can then verify and edit. The field has evolved quickly: from early CNN–RNN captioning models, to transformer-based architectures, and most recently to large vision–language models (VLMs) such as LLaVA and BLIP-2, whose medical adaptations (RaDialog, LLaVA-Med, CheXagent, MAIRA-2) couple a frozen image encoder with a large language model (LLM) to produce fluent, instruction-following text. In parallel, clinicians often need to ask focused questions about an image — "is there a pleural effusion?", "what is the size of the cardiac silhouette?" — which motivates visual question answering (VQA) on chest X-rays.
 
-A recurring difficulty is that fluent text is not necessarily *clinically correct*: a model can produce a well-formed report that misses or flips a finding. Abnormality-guided approaches such as META-CXR address this by feeding explicit pathology labels to the language model. This thesis follows that direction: it builds a single VLM that performs findings generation, impression generation, and VQA, guided by an explicit 14-pathology **Positive / Negative / Uncertain (PNU)** signal, so that generation is anchored to detected abnormalities rather than to language priors alone.
+A recurring difficulty is that fluent text is not necessarily *clinically correct*: a model can produce a well-formed report that misses or flips a finding. A natural way to mitigate this is to feed the language model explicit pathology labels, so that generation stays anchored to detected abnormalities rather than to language priors alone. Motivated by this idea, this thesis builds a single VLM that performs findings generation, impression generation, and VQA, guided by an explicit 14-pathology Positive / Negative / Uncertain (PNU) signal.
 
 ## 1.2 Internship objectives
 
-The objective of this internship is to design, implement, and evaluate **CXR-VLM**, a unified vision–language model for chest X-ray interpretation built on a shared RAD-DINO + projection + Vicuna-7B (LoRA) backbone. Concretely, the work targets the following goals:
+The objective of this internship is to design, implement, and evaluate CXR-VLM, a unified vision–language model for chest X-ray interpretation built on a shared RAD-DINO + projection + Vicuna-7B (LoRA) backbone. Concretely, the work targets the following goals:
 
 - **Data pipeline.** Build a reproducible pipeline that filters the MIMIC-CXR corpus and serialises it into a unified instruction format covering findings, impression, and VQA samples.
 - **Abnormality-guided prompting.** Train a CheXpert-style classifier that emits a PNU abnormality string, and inject it into the language-model prompt as clinical guidance.
@@ -32,14 +32,16 @@ The remainder of this report is organised as follows:
 
 ## 2.1 Medical report generation
 
-Early radiology report generation systems adapted natural-image captioning architectures, pairing a CNN image encoder with an RNN/LSTM decoder. These models produced fluent sentences but struggled with the long, multi-sentence structure of radiology reports and with rare but clinically important findings. The introduction of **R2Gen** (Chen et al., 2020) replaced the recurrent decoder with a memory-driven transformer that records report patterns across studies, and **R2GenCMN** (Chen et al., 2021) added a shared cross-modal memory to better align visual and textual features; both became standard baselines on the MIMIC-CXR benchmark. A parallel line of work injected medical prior knowledge through knowledge graphs (e.g. PPKED, KGAE) or retrieval, and emphasised **clinical-efficacy** metrics — comparing the pathology labels extracted from generated and reference reports with the CheXbert labeler — rather than n-gram overlap alone.
+Early radiology report generation systems adapted natural-image captioning architectures, pairing a CNN image encoder with an RNN/LSTM decoder. These models produced fluent sentences but struggled with the long, multi-sentence structure of radiology reports and with rare but clinically important findings. The introduction of R2Gen (Chen et al., 2020) replaced the recurrent decoder with a memory-driven transformer that records report patterns across studies, and R2GenCMN (Chen et al., 2021) added a shared cross-modal memory to better align visual and textual features; both became standard baselines on the MIMIC-CXR benchmark. A parallel line of work injected medical prior knowledge through knowledge graphs (e.g. PPKED, KGAE) or retrieval, and emphasised clinical-efficacy metrics — comparing the pathology labels extracted from generated and reference reports with the CheXbert labeler — rather than n-gram overlap alone.
 
-More recently, the field has shifted to **LLM-based** generators. **RaDialog** (Pellegrini et al., 2023) instruction-tunes a Vicuna LLM on chest X-rays, conditions it on a structured list of CheXpert findings, and adapts it with low-rank (LoRA) adapters, enabling both report generation and conversational interaction. Related foundation-style efforts include **CheXagent**, **MAIRA-2**, **LLaVA-Med**, and **XrayGPT**. To improve clinical grounding, **META-CXR** introduces a *U-MultiClass* formulation that preserves three states per pathology — positive, negative, and uncertain — instead of collapsing them to a binary present/absent label.
+More recently, the field has shifted to LLM-based generators. RaDialog (Pellegrini et al., 2023) instruction-tunes a Vicuna LLM on chest X-rays, conditions it on a structured list of CheXpert findings, and adapts it with low-rank (LoRA) adapters, enabling both report generation and conversational interaction. Related foundation-style efforts include CheXagent, MAIRA-2, LLaVA-Med, and XrayGPT. To improve clinical grounding, META-CXR introduces a *U-MultiClass* formulation that preserves three states per pathology — positive, negative, and uncertain — instead of collapsing them to a binary present/absent label.
 
-The model proposed here follows the RaDialog recipe but differs in three respects: it uses the chest-X-ray-specific **RAD-DINO** encoder instead of BioViL-T; it serialises abnormalities as a META-CXR-style **PNU** string injected into the prompt; and it adds an optional **contrastive Stage 1** that pre-aligns the visual projection with the report text before any language modelling.
+Taken together, these advances — abnormality-aware generation, LLM-based decoding, and parameter-efficient adaptation — motivate the approach taken in this thesis: a single vision–language model that generates findings and impression and answers questions about a chest X-ray, explicitly guided by detected abnormalities. The components and training of this model are described in Section 3.
 
 ## 2.2 Visual question answering
 
-Visual question answering combines image understanding with natural-language reasoning to answer a question about an image. In the medical domain, dedicated datasets such as **VQA-RAD**, **SLAKE**, and **PathVQA** spurred early methods that fuse a CNN image embedding with a question embedding and classify over a fixed answer vocabulary, often with co-attention or meta-learning of the visual features (e.g. MEVF, MMQ). Chest-X-ray-specific resources followed, including **MIMIC-Diff-VQA**, **EHRXQA**, and the large-scale **MIMIC-Ext-CXR-VQA** used in this work, which organises questions by semantic type (verify, choose, query) and by content (presence, anatomy, attribute, size, and others).
+Visual question answering combines image understanding with natural-language reasoning to answer a question about an image. In the medical domain, general benchmarks span radiology and pathology: VQA-RAD (Lau et al., *Scientific Data*, 2018) and SLAKE (Liu et al., *IEEE ISBI*, 2021) cover radiology images of several modalities and body regions — including, but not limited to, the chest — while PathVQA targets pathology microscopy rather than radiographs. Early methods on these benchmarks fuse a CNN image embedding with a question embedding and classify over a fixed answer vocabulary, often with co-attention or meta-learning of the visual features (e.g. MEVF, *MICCAI* 2019; MMQ, *MICCAI* 2021).
 
-Whereas most medical VQA systems treat the task as closed-set classification, recent instruction-tuned VLMs answer in free-form text and can share a single backbone across tasks. CXR-VLM adopts this unified view: VQA is handled by the **same** encoder, projection, and LLM used for report generation, with the question taking the place of the instruction and the same PNU abnormality guidance supplied in the prompt. This lets a single set of weights serve findings, impression, and VQA, and lets the abnormality signal benefit short-answer questions as well as long-form generation.
+Dedicated chest-X-ray VQA resources are more recent. Medical-Diff-VQA / MIMIC-Diff-VQA (Hu et al., *ACM KDD*, 2023) poses difference questions over pairs of MIMIC-CXR images; MIMIC-CXR-VQA, introduced together with EHRXQA (Bae et al., *NeurIPS Datasets & Benchmarks*, 2023), pairs chest X-rays with structured electronic-health-record question answering; and the large-scale MIMIC-Ext-CXR-VQA used in this work organises questions by semantic type (verify, choose, query) and content type (presence, anatomy, attribute, size, and others).
+
+Compared with chest-X-ray report generation, dedicated VQA for chest X-rays is a younger and less standardised area: most existing work contributes datasets or specialised settings (difference questions, EHR-linked QA) and still treats VQA as a standalone closed-set classification problem. This motivates the approach taken here: rather than building a separate VQA classifier, VQA is handled by the same encoder, projection, and language model used for report generation, with the question taking the place of the instruction and the same PNU abnormality guidance supplied in the prompt. A single set of weights therefore serves findings, impression, and VQA, and the abnormality signal benefits short-answer questions as well as long-form generation.

docs/report_part4_5.md

@@ -6,7 +6,7 @@
 
 ### 4.1.1 Dataset and configuration
 
-All experiments use the **MIMIC-CXR_resized** subset described in Section 3.3: 50,000 patient-disjoint studies split into 40,000 train / 5,000 validation / 5,000 test, under the configuration `report_mode = split_cascade` and `image_mode = frontal_only_split` (one PA/AP frontal image per study). Findings and impression targets come from the MIMIC-CXR reports; VQA samples come from **MIMIC-Ext-CXR-VQA**, attached by study. The reported run is `MIMIC-CXR_resized_run_3`, evaluated on the held-out test split with **predicted** PNU guidance (`pnu_source = predicted`), i.e. the abnormality string comes from the frozen CheXpert classifier rather than from ground-truth labels — the realistic inference setting. The VQA test set contains **11,880** question–answer items.
+All experiments use the 50,000-study subset described in Section 3.3: 40,000 train / 5,000 validation / 5,000 test, patient-disjoint, one frontal image per study, with the impression task conditioned on the ground-truth findings. Findings and impression targets come from the MIMIC-CXR reports; VQA samples come from MIMIC-Ext-CXR-VQA, attached by study. The reported run is evaluated on the held-out test split with predicted PNU guidance — the abnormality string comes from the frozen CheXpert classifier rather than from ground-truth labels, which is the realistic inference setting. The VQA data contain 127,010 question–answer items in total (102,941 train / 12,189 validation / 11,880 test); there are far more VQA samples than studies because a single image can be paired with several questions, whereas the findings and impression tasks contribute one sample per study. All metrics below are on the 11,880-item test set.
 
 ### 4.1.2 Implementation and hyperparameters
 
@@ -34,9 +34,9 @@ The model is implemented in PyTorch with HuggingFace `transformers`, `peft` (LoR
 
 ### 4.1.3 Evaluation protocol
 
-Metrics follow Section 3.6. Generation uses greedy decoding with the canonical instruction variant; the maximum number of new tokens is 300 (findings), 200 (impression), and 64 (VQA). For report generation we report BLEU-1/4, ROUGE-1/2/L, METEOR, and BERTScore-F1; for VQA we report exact match, token-F1, micro-F1, BLEU-1, METEOR, and BERTScore-F1. **Clinical correctness** is assessed through the dedicated CheXpert abnormality classifier (Section 4.2.2), which predicts the 14 pathologies directly from the image; the alternative report-level CheXbert-F1 (which re-labels the *generated text*) was not available on the evaluation host and is therefore not reported.
+Metrics follow Section 3.6. Generation uses greedy decoding with the canonical instruction variant; the maximum number of new tokens is 300 (findings), 200 (impression), and 64 (VQA). For report generation we report BLEU-1/4, ROUGE-1/2/L, METEOR, and BERTScore-F1; for VQA we report exact match, token-F1, micro-F1, BLEU-1, METEOR, and BERTScore-F1. Clinical correctness is assessed through the dedicated CheXpert abnormality classifier (Section 4.2.2), which predicts the 14 pathologies directly from the image; the alternative report-level CheXbert-F1 (which re-labels the *generated text*) was not available on the evaluation host and is therefore not reported.
 
-> **Note on cross-paper comparison.** The baseline numbers in Tables 4.2 and 4.5 are quoted as compiled in the META-CXR paper (Edirisinghe et al., 2025, Tables 2–3), which is the closest prior work to ours. NLG scores (BLEU, METEOR, ROUGE, BERTScore) depend on the tokeniser, smoothing, and the specific BERTScore backbone/baseline, so absolute values are only **approximately** comparable across papers; the ordering matters more than the exact digits. In particular our BERTScore-F1 (DistilBERT, no baseline rescaling) is **not** comparable to META-CXR's rescaled BERTScore of 0.426 and is therefore omitted from the comparison table.
+> **Note on cross-paper comparison.** The baseline numbers in Tables 4.2 and 4.5 are quoted as compiled in the META-CXR paper (Edirisinghe et al., 2025, Tables 2–3), which is the closest prior work to ours. NLG scores (BLEU, METEOR, ROUGE, BERTScore) depend on the tokeniser, smoothing, and the specific BERTScore backbone/baseline, so absolute values are only approximately comparable across papers; the ordering matters more than the exact digits. In particular our BERTScore-F1 (DistilBERT, no baseline rescaling) is not comparable to META-CXR's rescaled BERTScore of 0.426 and is therefore omitted from the comparison table.
 
 ## 4.2 Results
 
@@ -68,7 +68,7 @@ The full breakdown for both report tasks is given in Table 4.3. Impression score
 
 ### 4.2.2 Clinical correctness: abnormality classification
 
-Clinical correctness is measured by the CheXpert abnormality classifier (Stage 0), which predicts the 14 pathologies — with an explicit *uncertain* state — directly from the image. This is the same role that META-CXR's MHCAC classifier plays. Table 4.4 gives our per-pathology results. Performance is strongest on common, visually salient categories (No Finding F1 0.785, Pleural Effusion 0.622, Support Devices 0.552, Edema 0.508) and collapses to zero on rare categories with few positives (Enlarged Cardiomediastinum, Pleural Other, Fracture), reflecting the strong class imbalance of MIMIC-CXR. The macro averages over the 14 labels are **precision 0.319, recall 0.377, F1 0.328**; over the 11 labels the model actually predicts (excluding the three degenerate classes) the macro-F1 rises to about **0.42**.
+Clinical correctness is measured by the CheXpert abnormality classifier (Stage 0), which predicts the 14 pathologies — with an explicit *uncertain* state — directly from the image. This is the same role that META-CXR's MHCAC classifier plays. Table 4.4 gives our per-pathology results. Performance is strongest on common, visually salient categories (No Finding F1 0.785, Pleural Effusion 0.622, Support Devices 0.552, Edema 0.508) and collapses to zero on rare categories with few positives (Enlarged Cardiomediastinum, Pleural Other, Fracture), reflecting the strong class imbalance of MIMIC-CXR. The macro averages over the 14 labels are precision 0.319, recall 0.377, F1 0.328; over the 11 labels the model actually predicts (excluding the three degenerate classes) the macro-F1 rises to about 0.42.
 
 **Table 4.4.** CheXpert classifier per-pathology results (test split).
 
@@ -90,7 +90,7 @@ Clinical correctness is measured by the CheXpert abnormality classifier (Stage 0
 | Support Devices | 0.445 | 0.727 | 0.552 |
 | **Macro average (14)** | **0.319** | **0.377** | **0.328** |
 
-Table 4.5 places this in context. Two families of "clinical" F1 appear in the literature: (i) a **dedicated image classifier** F1, as in META-CXR's MHCAC, and (ii) a **report-derived Clinical-Efficacy (CE) F1**, obtained by running the CheXbert labeler on the generated report and comparing label vectors. Our classifier (macro-F1 0.328, ≈ 0.42 on predictable classes) is well below META-CXR's multi-encoder MHCAC classifier (weighted F1 0.73), but lands in the same range as the report-derived CE F1 of recent generation systems (0.31–0.43). These quantities are **not** strictly comparable (image-level vs report-derived; macro vs weighted averaging), so Table 4.5 is a positioning reference, not a like-for-like ranking.
+Table 4.5 places this in context. Two families of "clinical" F1 appear in the literature: (i) a dedicated image classifier F1, as in META-CXR's MHCAC, and (ii) a report-derived Clinical-Efficacy (CE) F1, obtained by running the CheXbert labeler on the generated report and comparing label vectors. Our classifier (macro-F1 0.328, ≈ 0.42 on predictable classes) is well below META-CXR's multi-encoder MHCAC classifier (weighted F1 0.73), but lands in the same range as the report-derived CE F1 of recent generation systems (0.31–0.43). These quantities are not strictly comparable (image-level vs report-derived; macro vs weighted averaging), so Table 4.5 is a positioning reference, not a like-for-like ranking.
 
 **Table 4.5.** Clinical / abnormality F1 in context (MIMIC-CXR test; values as compiled in Edirisinghe et al., 2025, Tables 2–3). †image-level classifier; ‡report-derived CheXbert CE F1.
 
@@ -109,7 +109,7 @@ For cross-domain reference, META-CXR reports a mean F1 of 0.699 on the CheXpert
 
 ### 4.2.3 Visual question answering
 
-Table 4.6 gives the overall VQA results on the 11,880-item test set. Tables 4.7 and 4.8 break the score down by answer type and by question semantic/content type. The model is clearly stronger on **closed-ended** questions (exact match 0.385) than on **open-ended** ones (0.204), and within content types it does best on **size** and **plane** questions and worst on **anatomy** and **attribute** questions.
+Table 4.6 gives the overall VQA results on the 11,880-item test set. Tables 4.7 and 4.8 break the score down by answer type and by question semantic/content type. The model is clearly stronger on closed-ended questions (exact match 0.385) than on open-ended ones (0.204), and within content types it does best on size and plane questions and worst on anatomy and attribute questions.
 
 **Table 4.6.** Overall VQA results (test, 11,880 items).
 
@@ -148,24 +148,26 @@ Table 4.6 gives the overall VQA results on the 11,880-item test set. Tables 4.7
 
 **Report generation.** On findings, CXR-VLM is competitive with established systems on the recall/semantics metrics (ROUGE-L 0.292, strong METEOR) while trailing on BLEU-4 (0.083), where it sits close to RaDialog (0.095). This is the expected profile of an instruction-tuned LLM that rephrases findings rather than reproducing reference n-grams, so BLEU acts as a fluency floor rather than a quality measure. We deliberately do not claim a BLEU/BERTScore state-of-the-art, because those metrics are sensitive to tokenisation and to the BERTScore backbone and are only approximately comparable across papers.
 
-**Impression weakness.** Impression scores are much lower than findings on every metric, even though `split_cascade` feeds the ground-truth findings to the impression prompt and should make the task easier. Likely factors: impressions are short and abstractive (harsh for exact-overlap metrics), the impression task gets a smaller training share, and the model may carry findings-style phrasing into the impression. This is the clearest area for improvement (Section 5).
+**Impression weakness.** Impression scores are much lower than findings on every metric, even though the impression prompt is given the ground-truth findings and should make the task easier. Likely factors: impressions are short and abstractive (harsh for exact-overlap metrics), the impression task gets a smaller training share, and the model may carry findings-style phrasing into the impression. This is the clearest area for improvement (Section 5).
 
 **Clinical correctness.** The Stage-0 CheXpert classifier — our clinical metric — reaches macro-F1 0.328 over 14 labels (≈ 0.42 over the 11 labels it can predict). It is well below META-CXR's dedicated multi-encoder MHCAC classifier (weighted F1 0.73), but comparable to the report-derived clinical-efficacy F1 of recent generation systems (0.31–0.43). The gap to META-CXR is consistent with their heavier design (three fused encoders CNN+ViT+Swin, expert-token cross-attention, class-balanced and contrastive losses) versus our single-encoder MLP head. Because the test-time PNU string is produced by this classifier (`pnu_source = predicted`), its errors propagate into the prompt, so improving it is the highest-leverage next step. Its weakness on rare classes (zero F1 on Enlarged Cardiomediastinum, Pleural Other, Fracture) is a direct symptom of class imbalance.
 
 **VQA.** The model handles closed-ended verification and presence questions far better than open-ended query and attribute questions, mirroring the general difficulty ordering in medical VQA. The strong results on size and plane questions suggest the visual tokens retain coarse geometric information well.
 
-**Limitations.** The evaluation is on a single corpus (MIMIC-CXR); the report-level CheXbert CE F1 was not computed; the PNU guidance is bounded by an imbalanced classifier; impression generation underperforms; and compute constraints fix a small effective batch and a 7B LLM. Cross-paper metric comparison is approximate due to differing implementations.
+**Comparison with prior work.** The same profile appears in recent LLM-based chest-X-ray systems: META-CXR, for instance, also reports a modest BLEU-4 (0.102) while leading on METEOR and BERTScore, which matches our pattern of low n-gram overlap but competitive semantic scores. Our abnormality classifier (macro F1 0.328) is clearly weaker than META-CXR's (weighted F1 0.73), but that system reaches its score with a much heavier design — three fused encoders (CNN, ViT, Swin) plus several auxiliary losses — and its authors themselves note the resulting inference-time complexity as a drawback. Our single-encoder MLP head trades accuracy for a far smaller and simpler model, consistent with the limited-compute goal of this thesis.
+
+**Limitations.** Several limitations qualify these results. (i) Evaluation uses a single corpus (MIMIC-CXR) from one institution, so generalisation to other scanners and patient populations is untested. (ii) The report-level CheXbert clinical-efficacy F1 — the metric that best reflects diagnostic usefulness — was not computed for this run. (iii) The PNU guidance comes from an imbalanced, only moderate classifier, so its errors propagate into generation and VQA. (iv) Like any LLM-based generator, the model can hallucinate fluent but unsupported statements, which lexical metrics do not penalise. (v) Impression generation clearly underperforms findings. (vi) Compute constraints fix a small effective batch, a 7B LLM, and a single-view, single-image setup, with no multi-view or longitudinal (prior-study) context. Cross-paper metric comparison is also only approximate, given differing tokenisers and BERTScore backbones.
 
 ---
 
 # 5. Conclusion and future work
 
-This thesis presented **CXR-VLM**, a unified vision–language model that performs chest-X-ray findings generation, impression generation, and visual question answering with a single RAD-DINO + projection + Vicuna-7B (LoRA) backbone, guided by an explicit Positive/Negative/Uncertain abnormality signal and trained with a parameter-efficient two-stage schedule. On the MIMIC-CXR test split the model is competitive with established systems on semantic report-generation metrics (ROUGE-L 0.292, strong METEOR), its abnormality classifier reaches macro-F1 0.328 (≈ 0.42 on predictable classes) — in the range of report-derived clinical-efficacy F1 of recent work — and it achieves a VQA exact match of 0.306, markedly stronger on closed-ended questions. These results show that a frozen-encoder, frozen-LLM design adapted only through a small projection and LoRA adapters can drive three chest-X-ray tasks at once on modest hardware.
+This thesis presented CXR-VLM, a unified vision–language model that performs chest-X-ray findings generation, impression generation, and visual question answering with a single RAD-DINO + projection + Vicuna-7B (LoRA) backbone, guided by an explicit Positive/Negative/Uncertain abnormality signal and trained with a parameter-efficient two-stage schedule. On the MIMIC-CXR test split the model is competitive with established systems on semantic report-generation metrics (ROUGE-L 0.292, strong METEOR), its abnormality classifier reaches macro-F1 0.328 (≈ 0.42 on predictable classes) — in the range of report-derived clinical-efficacy F1 of recent work — and it achieves a VQA exact match of 0.306, markedly stronger on closed-ended questions. These results show that a frozen-encoder, frozen-LLM design adapted only through a small projection and LoRA adapters can drive three chest-X-ray tasks at once on modest hardware.
 
 Several directions would strengthen the work:
 
 - **Stronger abnormality classifier.** The clearest lever: adopt a META-CXR-style design (multi-encoder fusion, class-balancing or focal loss, contrastive/uncertainty objectives) so the predicted PNU string is more reliable and propagates fewer errors into generation and VQA.
-- **Report-level clinical efficacy.** Run the CheXbert labeler on generated reports to report the standard CE F1 and enable a like-for-like comparison with the literature, plus radiologist or LLM-as-judge assessment.
+- **Report-level clinical efficacy.** Run the CheXbert labeler on generated reports to report the standard CE F1 and enable a like-for-like comparison with the literature, complemented by expert radiologist assessment.
 - **Impression generation.** Investigate and close the gap on impression (dedicated decoding budget, task-specific tuning, or a true end-to-end findings→impression cascade).
 - **Scale and backbones.** Train on more data and views (multi-image studies) and evaluate stronger LLMs (e.g. Llama-3).
 - **Cross-dataset validation.** Evaluate on IU X-ray and CheXpert to measure generalisation beyond MIMIC-CXR.
@@ -191,3 +193,7 @@ Several directions would strengthen the work:
 15. A. E. W. Johnson et al. *MIMIC-CXR-JPG, a Large Publicly Available Database of Labeled Chest Radiographs.* arXiv:1901.07042, 2019.
 16. T. Zhang, V. Kishore, F. Wu, K. Q. Weinberger, Y. Artzi. *BERTScore: Evaluating Text Generation with BERT.* ICLR, 2020.
 17. S. Banerjee, A. Lavie. *METEOR: An Automatic Metric for MT Evaluation with Improved Correlation with Human Judgments.* ACL Workshop, 2005.
+18. J. J. Lau, S. Gayen, A. Ben Abacha, D. Demner-Fushman. *A Dataset of Clinically Generated Visual Questions and Answers about Radiology Images (VQA-RAD).* Scientific Data, 2018.
+19. B. Liu, L.-M. Zhan, L. Xu, L. Ma, Y. Yang, X.-M. Wu. *SLAKE: A Semantically-Labeled Knowledge-Enhanced Dataset for Medical Visual Question Answering.* IEEE ISBI, 2021.
+20. X. Hu et al. *Expert Knowledge-Aware Image Difference Graph Representation Learning for Difference-Aware Medical Visual Question Answering (Medical-Diff-VQA / MIMIC-Diff-VQA).* ACM SIGKDD (KDD), 2023.
+21. S. Bae et al. *EHRXQA: A Multi-Modal Question Answering Dataset for Electronic Health Records with Chest X-ray Images (incl. MIMIC-CXR-VQA).* NeurIPS Datasets & Benchmarks, 2023.

scripts/cxrvlm_colab_inference.ipynb

@@ -745,6 +745,251 @@
     "- For deterministic outputs keep `DO_SAMPLE=False`. For diversity, set `DO_SAMPLE=True, TEMPERATURE=0.7`.\n",
     "- `predict_report()` is the realistic end-to-end pipeline (no GT leakage). `predict(task='report')` only works on runs trained with `report_mode='merged'`.\n"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "qual-md",
+   "metadata": {},
+   "source": [
+    "## 10. Qualitative eval theo nhãn bệnh (GT cạnh prediction)\n",
+    "\n",
+    "Với **mỗi nhãn bệnh** lấy random `QUAL_N_PER_CLASS` mẫu test (study dương tính nhãn đó), rồi:\n",
+    "- Tạo folder `QUAL_OUT/<Tên_bệnh>/<study>/` chứa: ảnh, **GT report** (`report_gt.txt`),\n",
+    "  **GT VQA** (`vqa_gt.json`), và **so sánh** GT↔prediction (`comparison.md`).\n",
+    "- Chạy inference (cascade findings→impression + trả lời các câu VQA của ảnh đó).\n",
+    "- Hiển thị inline: ảnh + GT report vs PRED, GT VQA vs PRED, và **GT PNU** (nhãn CheXpert).\n",
+    "\n",
+    "> Cần tải `manifest`, `vqa`, và **tar shards** của MIMIC-CXR_resized từ HF (shards ~vài GB —\n",
+    "> phần lâu nhất; chỉ tải 1 lần, lần sau cache lại). Nếu chỉ muốn xem nhanh, giảm\n",
+    "> `QUAL_N_PER_CLASS` hoặc rút gọn `QUAL_PATHOLOGIES`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "qual-cfg",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ===== CONFIG qualitative eval =====\n",
+    "QUAL_SPLIT          = 'test'         # 'test' | 'val' | 'train'\n",
+    "QUAL_N_PER_CLASS    = 3              # số mẫu random / nhãn\n",
+    "QUAL_VQA_PER_IMG    = 3              # số câu VQA tối đa hỏi mỗi ảnh (None = tất cả)\n",
+    "QUAL_USE_ORACLE_PNU = False          # True: ĐƯA GT PNU vào model làm structured_findings (oracle)\n",
+    "QUAL_SEED           = 42\n",
+    "QUAL_PATHOLOGIES    = None            # None = đủ 14 nhãn; hoặc list con, vd ['Cardiomegaly','Edema']\n",
+    "\n",
+    "QUAL_DATA_REPO = f'{HF_USER}/cxr-vlm-data'\n",
+    "QUAL_WORK      = WORK / 'qual_data'           # cache tải/giải nén\n",
+    "QUAL_OUT       = WORK / 'qual_by_pathology'   # folder output để duyệt\n",
+    "print('QUAL config ok |', QUAL_SPLIT, '| n/class =', QUAL_N_PER_CLASS,\n",
+    "      '| oracle PNU =', QUAL_USE_ORACLE_PNU)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "qual-pick-md",
+   "metadata": {},
+   "source": [
+    "### 10a. Tải manifest + VQA, chọn mẫu random theo nhãn"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "qual-pick",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import csv, json, random, tarfile, shutil\n",
+    "from pathlib import Path\n",
+    "from huggingface_hub import snapshot_download\n",
+    "from data.mimic_cxr_resized_builder import _row_to_pnu          # GT CheXpert -> PNU string\n",
+    "from data.mimic_cxr_builder import _parse_report               # report .txt -> (findings, impression)\n",
+    "from model.chexpert_classifier import PATHOLOGIES\n",
+    "\n",
+    "def _norm(s): return str(s).replace('\\\\', '/').lstrip('/')\n",
+    "def _safe(s): return s.replace(' ', '_')\n",
+    "\n",
+    "_MANI = {'test':'manifest_test.csv','val':'manifest_val.csv',\n",
+    "         'validate':'manifest_val.csv','train':'manifest_train.csv'}[QUAL_SPLIT]\n",
+    "_VQA  = {'test':'vqa_test.json','val':'vqa_val.json',\n",
+    "         'validate':'vqa_val.json','train':'vqa.json'}[QUAL_SPLIT]\n",
+    "\n",
+    "# 1) manifest + vqa (nhẹ)\n",
+    "snapshot_download(repo_id=QUAL_DATA_REPO, repo_type='dataset', token=os.environ['HF_TOKEN'],\n",
+    "    local_dir=str(QUAL_WORK),\n",
+    "    allow_patterns=[f'MIMIC-CXR_resized/{_MANI}', f'MIMIC-CXR_resized/vqa/{_VQA}'])\n",
+    "_mr      = QUAL_WORK / 'MIMIC-CXR_resized'\n",
+    "manifest = _mr / _MANI\n",
+    "vqa_path = _mr / 'vqa' / _VQA\n",
+    "\n",
+    "# 1 row / study (giữ row đầu)\n",
+    "rows_by_study = {}\n",
+    "with open(manifest, encoding='utf-8', newline='') as f:\n",
+    "    for row in csv.DictReader(f):\n",
+    "        rows_by_study.setdefault(str(row['study_id']).strip(), row)\n",
+    "print(f'{len(rows_by_study):,} studies trong manifest')\n",
+    "\n",
+    "# VQA gom theo dicom (image_id)\n",
+    "vqa_by_dicom = {}\n",
+    "if vqa_path.is_file():\n",
+    "    for v in json.load(open(vqa_path, encoding='utf-8')):\n",
+    "        vqa_by_dicom.setdefault(str(v.get('image_id')).strip(), []).append(v)\n",
+    "print(f'VQA: {sum(len(v) for v in vqa_by_dicom.values()):,} câu / {len(vqa_by_dicom):,} ảnh')\n",
+    "\n",
+    "# 2) chọn random N study dương tính / nhãn\n",
+    "random.seed(QUAL_SEED)\n",
+    "target_labels = QUAL_PATHOLOGIES or PATHOLOGIES\n",
+    "picks = {}\n",
+    "print('\\nNhãn                         #positive  picked')\n",
+    "for lab in target_labels:\n",
+    "    col = f'chex_{lab}'\n",
+    "    pos = [r for r in rows_by_study.values()\n",
+    "           if str(r.get(col, '')).strip() in ('1', '1.0')]\n",
+    "    random.shuffle(pos)\n",
+    "    picks[lab] = pos[:QUAL_N_PER_CLASS]\n",
+    "    print(f'  {lab:28s} {len(pos):6d}   {len(picks[lab])}')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "qual-extract-md",
+   "metadata": {},
+   "source": [
+    "### 10b. Tải shards + rút ảnh/report của các mẫu đã chọn"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "qual-extract",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# files cần rút (ảnh + report của các study đã chọn)\n",
+    "need = set()\n",
+    "for rs in picks.values():\n",
+    "    for r in rs:\n",
+    "        need.add(_norm(r['image_relpath']))\n",
+    "        if r.get('report_relpath'):\n",
+    "            need.add(_norm(r['report_relpath']))\n",
+    "print(f'cần rút {len(need)} file (ảnh + report)')\n",
+    "\n",
+    "# tải toàn bộ shards (ảnh nằm rải) — lâu nhất, cache lại lần sau\n",
+    "print('Tải tar shards (vài GB)…')\n",
+    "snapshot_download(repo_id=QUAL_DATA_REPO, repo_type='dataset', token=os.environ['HF_TOKEN'],\n",
+    "    local_dir=str(QUAL_WORK), allow_patterns=['MIMIC-CXR_resized/shards/*.tar'])\n",
+    "shards = sorted((_mr / 'shards').glob('*.tar'))\n",
+    "print(f'{len(shards)} shards')\n",
+    "\n",
+    "# rút đúng các file cần (1 pass)\n",
+    "extract_root = QUAL_WORK / 'extracted'\n",
+    "extracted = {}\n",
+    "for shard in shards:\n",
+    "    with tarfile.open(shard, 'r') as tf:\n",
+    "        for m in tf:\n",
+    "            if not m.isfile(): continue\n",
+    "            name = _norm(m.name)\n",
+    "            if name in need and name not in extracted:\n",
+    "                dst = extract_root / name\n",
+    "                dst.parent.mkdir(parents=True, exist_ok=True)\n",
+    "                dst.write_bytes(tf.extractfile(m).read())\n",
+    "                extracted[name] = dst\n",
+    "print(f'rút được {len(extracted)} / {len(need)} file')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "qual-run-md",
+   "metadata": {},
+   "source": [
+    "### 10c. Inference + hiển thị GT↔PRED + lưu folder"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "qual-run",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def _fmt_answer(a):\n",
+    "    return ', '.join(map(str, a)) if isinstance(a, list) else str(a)\n",
+    "\n",
+    "def _cmp_block(lab, study, gt_pnu, gt_find, gt_impr, pred, vqa_rows, oracle_used):\n",
+    "    L = [f'PATHOLOGY (picked for): {lab}', f'STUDY: {study}',\n",
+    "         f'oracle PNU fed to model: {oracle_used}', '',\n",
+    "         '### GT CheXpert labels (PNU)', gt_pnu or '(none)', '',\n",
+    "         '### FINDINGS',\n",
+    "         f'[GT]   {gt_find or \"(none)\"}',\n",
+    "         f'[PRED] {pred[\"findings\"]}', '',\n",
+    "         '### IMPRESSION',\n",
+    "         f'[GT]   {gt_impr or \"(none)\"}',\n",
+    "         f'[PRED] {pred[\"impression\"]}']\n",
+    "    if vqa_rows:\n",
+    "        L += ['', '### VQA']\n",
+    "        for i, (q, a_gt, a_pred) in enumerate(vqa_rows, 1):\n",
+    "            L += [f'Q{i}: {q}', f'   [GT]   {a_gt}', f'   [PRED] {a_pred}']\n",
+    "    return '\\n'.join(L)\n",
+    "\n",
+    "QUAL_OUT = Path(QUAL_OUT)\n",
+    "index, n_done, n_skip = [], 0, 0\n",
+    "for lab, rs in picks.items():\n",
+    "    for r in rs:\n",
+    "        img_rel = _norm(r['image_relpath'])\n",
+    "        img_p   = extracted.get(img_rel)\n",
+    "        if img_p is None:\n",
+    "            n_skip += 1; continue\n",
+    "        study = str(r.get('study_id'))\n",
+    "        dicom = Path(img_rel).stem\n",
+    "\n",
+    "        gt_pnu = _row_to_pnu(r)\n",
+    "        rep_p  = extracted.get(_norm(r.get('report_relpath', '')))\n",
+    "        gt_find, gt_impr = _parse_report(rep_p) if rep_p else (None, None)\n",
+    "\n",
+    "        oracle = gt_pnu if QUAL_USE_ORACLE_PNU else None\n",
+    "        pred = predict_report(img_p, structured_findings=oracle)\n",
+    "\n",
+    "        vqas = vqa_by_dicom.get(dicom, [])\n",
+    "        if QUAL_VQA_PER_IMG is not None:\n",
+    "            vqas = vqas[:QUAL_VQA_PER_IMG]\n",
+    "        vqa_rows = []\n",
+    "        for v in vqas:\n",
+    "            a_pred = predict(img_p, task='vqa', question=v['question'],\n",
+    "                             structured_findings=oracle)\n",
+    "            vqa_rows.append((v['question'], _fmt_answer(v.get('answer')), a_pred))\n",
+    "\n",
+    "        block = _cmp_block(lab, study, gt_pnu, gt_find, gt_impr, pred,\n",
+    "                           vqa_rows, QUAL_USE_ORACLE_PNU)\n",
+    "\n",
+    "        # hiển thị inline\n",
+    "        show(img_p, title=f'{lab} | {study} | {r.get(\"view\",\"\")}')\n",
+    "        print('=' * 80); print(block); print('=' * 80, '\\n')\n",
+    "\n",
+    "        # lưu folder\n",
+    "        d = QUAL_OUT / _safe(lab) / study\n",
+    "        d.mkdir(parents=True, exist_ok=True)\n",
+    "        shutil.copy(img_p, d / f'{dicom}.jpg')\n",
+    "        if rep_p: shutil.copy(rep_p, d / 'report_gt.txt')\n",
+    "        (d / 'comparison.md').write_text(block, encoding='utf-8')\n",
+    "        json.dump([{'question': q, 'answer_gt': a, 'answer_pred': p_}\n",
+    "                   for q, a, p_ in vqa_rows],\n",
+    "                  open(d / 'vqa_gt.json', 'w', encoding='utf-8'),\n",
+    "                  ensure_ascii=False, indent=2)\n",
+    "        json.dump({'pathology': lab, 'study_id': study, 'dicom': dicom,\n",
+    "                   'gt_pnu': gt_pnu, 'gt_findings': gt_find, 'gt_impression': gt_impr,\n",
+    "                   'pred_findings': pred['findings'], 'pred_impression': pred['impression'],\n",
+    "                   'oracle_pnu': QUAL_USE_ORACLE_PNU},\n",
+    "                  open(d / 'prediction.json', 'w', encoding='utf-8'),\n",
+    "                  ensure_ascii=False, indent=2)\n",
+    "        index.append({'pathology': lab, 'study_id': study, 'dir': str(d)})\n",
+    "        n_done += 1\n",
+    "\n",
+    "json.dump(index, open(QUAL_OUT / '_index.json', 'w', encoding='utf-8'),\n",
+    "          ensure_ascii=False, indent=2)\n",
+    "print(f'\\nXong: {n_done} mẫu  (skip {n_skip}).  Folder: {QUAL_OUT.resolve()}')"
+   ]
   }
  ],
  "metadata": {

scripts/vertex_eval_job.yaml

@@ -61,7 +61,7 @@ workerPoolSpecs:
     - name: DATASET_NAME
       value: MIMIC-CXR_resized           # 'IU-Xray' | 'MIMIC-CXR' | 'MIMIC-CXR_resized'
     - name: RUN_ID
-      value: MIMIC-CXR_resized_run_1     # which run on HF_RUNS_REPO to evaluate
+      value: MIMIC-CXR_resized_run_3     # which run on HF_RUNS_REPO to evaluate
     # ── Optional ────────────────────────────────────────────────────────────
     - name: HF_RUNS_REPO
       value: hieu3636/cxr-vlm-runs
@@ -87,10 +87,10 @@ workerPoolSpecs:
     # PNU prompt-condition source. 'oracle' = GT chex_* labels from JSON;
     # 'predicted' = run the Stage-0 CheXpert classifier per image (realistic).
     - name: PNU_SOURCE
-      value: oracle                      # 'oracle' | 'predicted'
+      value: predicted                   # 'oracle' | 'predicted'
     # Classifier checkpoint on HF_RUNS_REPO (only used when PNU_SOURCE=predicted).
-    # - name: CHEXPERT_CKPT_PATH
-    #   value: chexpert_classifier/chexpert_mimic_resized.pt
+    - name: CHEXPERT_CKPT_PATH
+      value: chexpert_classifier/chexpert_mimic_resized.pt
     - name: MAX_NEW_TOKENS
       value: "300"
     - name: UPLOAD_RESULTS_TO_HF