f

data/eda_reports.ipynb

@@ -22,7 +22,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 27,
+   "execution_count": 1,
    "id": "b60b7147",
    "metadata": {},
    "outputs": [
@@ -50,7 +50,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 28,
+   "execution_count": 2,
    "id": "b666d219",
    "metadata": {},
    "outputs": [
@@ -91,7 +91,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 29,
+   "execution_count": 3,
    "id": "09774f4c",
    "metadata": {},
    "outputs": [
@@ -220,7 +220,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 30,
+   "execution_count": 4,
    "id": "f1441bde",
    "metadata": {},
    "outputs": [
@@ -252,7 +252,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 31,
+   "execution_count": 5,
    "id": "325c65bc",
    "metadata": {},
    "outputs": [
@@ -322,7 +322,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 32,
+   "execution_count": 6,
    "id": "a0258afb",
    "metadata": {},
    "outputs": [
@@ -407,7 +407,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 33,
+   "execution_count": 7,
    "id": "eb43a4e7",
    "metadata": {},
    "outputs": [
@@ -469,7 +469,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 34,
+   "execution_count": 8,
    "id": "b77d7356",
    "metadata": {},
    "outputs": [
@@ -556,7 +556,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 35,
+   "execution_count": 9,
    "id": "6751ebf0",
    "metadata": {},
    "outputs": [
@@ -599,7 +599,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 36,
+   "execution_count": 10,
    "id": "b9725823",
    "metadata": {},
    "outputs": [
@@ -635,7 +635,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 37,
+   "execution_count": 11,
    "id": "3eda946d",
    "metadata": {},
    "outputs": [
@@ -681,7 +681,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 38,
+   "execution_count": 12,
    "id": "cb90ae2f",
    "metadata": {},
    "outputs": [
@@ -722,7 +722,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "C:\\Users\\admin\\AppData\\Local\\Temp\\ipykernel_19432\\723391630.py:1: DeprecationWarning: DataFrameGroupBy.apply operated on the grouping columns. This behavior is deprecated, and in a future version of pandas the grouping columns will be excluded from the operation. Either pass `include_groups=False` to exclude the groupings or explicitly select the grouping columns after groupby to silence this warning.\n",
+      "C:\\Users\\admin\\AppData\\Local\\Temp\\ipykernel_6580\\723391630.py:1: DeprecationWarning: DataFrameGroupBy.apply operated on the grouping columns. This behavior is deprecated, and in a future version of pandas the grouping columns will be excluded from the operation. Either pass `include_groups=False` to exclude the groupings or explicitly select the grouping columns after groupby to silence this warning.\n",
       "  subset_stats = df.groupby(\"subset\").apply(lambda g: pd.Series({\n"
      ]
     }
@@ -746,7 +746,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 39,
+   "execution_count": 13,
    "id": "6c67fbf2",
    "metadata": {},
    "outputs": [
@@ -800,7 +800,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 40,
+   "execution_count": 14,
    "id": "98cf393e",
    "metadata": {},
    "outputs": [
@@ -820,7 +820,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "C:\\Users\\admin\\AppData\\Local\\Temp\\ipykernel_19432\\2479082378.py:2: DeprecationWarning: DataFrameGroupBy.apply operated on the grouping columns. This behavior is deprecated, and in a future version of pandas the grouping columns will be excluded from the operation. Either pass `include_groups=False` to exclude the groupings or explicitly select the grouping columns after groupby to silence this warning.\n",
+      "C:\\Users\\admin\\AppData\\Local\\Temp\\ipykernel_6580\\2479082378.py:2: DeprecationWarning: DataFrameGroupBy.apply operated on the grouping columns. This behavior is deprecated, and in a future version of pandas the grouping columns will be excluded from the operation. Either pass `include_groups=False` to exclude the groupings or explicitly select the grouping columns after groupby to silence this warning.\n",
       "  split_stats = df.groupby(\"split\").apply(lambda g: pd.Series({\n"
      ]
     }
@@ -849,7 +849,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 41,
+   "execution_count": 15,
    "id": "7d26ee8f",
    "metadata": {},
    "outputs": [
@@ -888,7 +888,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 42,
+   "execution_count": 16,
    "id": "a647d42b",
    "metadata": {},
    "outputs": [
@@ -930,7 +930,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 43,
+   "execution_count": 17,
    "id": "6f420beb",
    "metadata": {},
    "outputs": [
@@ -938,7 +938,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "C:\\Users\\admin\\AppData\\Local\\Temp\\ipykernel_19432\\441297132.py:8: FutureWarning: \n",
+      "C:\\Users\\admin\\AppData\\Local\\Temp\\ipykernel_6580\\441297132.py:8: FutureWarning: \n",
       "\n",
       "Passing `palette` without assigning `hue` is deprecated and will be removed in v0.14.0. Assign the `x` variable to `hue` and set `legend=False` for the same effect.\n",
       "\n",
@@ -974,7 +974,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 44,
+   "execution_count": 18,
    "id": "2d4f87ba",
    "metadata": {},
    "outputs": [
@@ -1006,7 +1006,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 45,
+   "execution_count": 19,
    "id": "9e7ac126",
    "metadata": {},
    "outputs": [
@@ -1077,7 +1077,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 46,
+   "execution_count": 20,
    "id": "d3fa9af1",
    "metadata": {},
    "outputs": [
@@ -1151,7 +1151,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 47,
+   "execution_count": 21,
    "id": "6f5ba746",
    "metadata": {},
    "outputs": [
@@ -1218,7 +1218,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 48,
+   "execution_count": 22,
    "id": "47f751e4",
    "metadata": {},
    "outputs": [
@@ -1282,6 +1282,86 @@
     "    print(f\"  {report_path(row)}   sections: {row['section_headers']}\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "609330c1",
+   "metadata": {},
+   "source": [
+    "### 4. Copy các report bất thường ra thư mục riêng\n",
+    "\n",
+    "Copy file `.txt` của các report bất thường vào `OUT_DIR`, chia subfolder theo loại:\n",
+    "`outlier_findings/`, `outlier_impression/`, `short_findings/`, `short_impression/`, `unusual_sections/`.\n",
+    "\n",
+    "- `COPY_ALL = False` → chỉ copy đúng `N` ví dụ đang hiển thị ở các cell trên.\n",
+    "- `COPY_ALL = True`  → copy **toàn bộ** report của mỗi nhóm."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "id": "820581ef",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "  outlier_findings    : copied 3,905  (missing 0)\n",
+      "  outlier_impression  : copied 4,257  (missing 0)\n",
+      "  short_findings      : copied    50  (missing 0)\n",
+      "  short_impression    : copied    74  (missing 0)\n",
+      "  unusual_sections    : copied     9  (missing 0)\n",
+      "\n",
+      "Tong cong da copy 8,295 file -> D:\\USTH\\KLTN\\cxr-vlm-data\\eda_outlier_reports\n"
+     ]
+    }
+   ],
+   "source": [
+    "import shutil\n",
+    "\n",
+    "OUT_DIR  = Path(r\"D:\\USTH\\KLTN\\cxr-vlm-data\\eda_outlier_reports\")\n",
+    "COPY_ALL = True   # False: chi copy N vi du; True: copy toan bo moi nhom\n",
+    "N        = 10      # so vi du moi nhom khi COPY_ALL=False\n",
+    "\n",
+    "\n",
+    "def _select(frame, sort_col=None, ascending=False, random_state=42):\n",
+    "    \"\"\"Lay toan bo (COPY_ALL) hoac N dong (sort theo sort_col neu co, else sample).\"\"\"\n",
+    "    if COPY_ALL:\n",
+    "        return frame\n",
+    "    if sort_col is not None:\n",
+    "        return frame.nlargest(N, sort_col) if not ascending else frame.nsmallest(N, sort_col)\n",
+    "    return frame.sample(min(N, len(frame)), random_state=random_state)\n",
+    "\n",
+    "\n",
+    "# Dinh nghia cac nhom: ten subfolder -> dataframe da chon\n",
+    "groups = {\n",
+    "    \"outlier_findings\":   _select(df[df[\"findings_len\"]   > thresh_f], \"findings_len\"),\n",
+    "    \"outlier_impression\": _select(df[df[\"impression_len\"] > thresh_i], \"impression_len\"),\n",
+    "    \"short_findings\":     _select(short_f),\n",
+    "    \"short_impression\":   _select(short_i),\n",
+    "    \"unusual_sections\":   _select(no_fi[no_fi[\"section_headers\"].apply(\n",
+    "                              lambda s: bool(set(h.strip().upper() for h in str(s).split(\"|\")) & other_set)\n",
+    "                          )] if len(has_other) else no_fi),\n",
+    "}\n",
+    "\n",
+    "total_copied = 0\n",
+    "for name, frame in groups.items():\n",
+    "    dest = OUT_DIR / name\n",
+    "    dest.mkdir(parents=True, exist_ok=True)\n",
+    "    n_ok = n_miss = 0\n",
+    "    for _, row in frame.iterrows():\n",
+    "        src = CXR_ROOT / \"files\" / row[\"subset\"] / f\"p{row['subject_id']}\" / f\"s{row['study_id']}.txt\"\n",
+    "        if src.exists():\n",
+    "            shutil.copy2(src, dest / f\"s{row['study_id']}.txt\")\n",
+    "            n_ok += 1\n",
+    "        else:\n",
+    "            n_miss += 1\n",
+    "    total_copied += n_ok\n",
+    "    print(f\"  {name:<20}: copied {n_ok:>5,}  (missing {n_miss})\")\n",
+    "\n",
+    "print(f\"\\nTong cong da copy {total_copied:,} file -> {OUT_DIR}\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "40d7d2b0",
@@ -1292,7 +1372,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 49,
+   "execution_count": 24,
    "id": "6043d581",
    "metadata": {},
    "outputs": [
@@ -1350,7 +1430,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 50,
+   "execution_count": 25,
    "id": "941cd135",
    "metadata": {},
    "outputs": [
@@ -1413,7 +1493,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 51,
+   "execution_count": 26,
    "id": "158a6ce2",
    "metadata": {},
    "outputs": [
@@ -1480,7 +1560,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 52,
+   "execution_count": 27,
    "id": "7fd31f29",
    "metadata": {},
    "outputs": [

data/mimic_cxr_builder.py

@@ -461,6 +461,12 @@ def build_mimic_cxr_instruct_json(
                     "split": split_label,
                     "study_id": study,
                     "subject_id": subj,
+                    # MIMIC-CXR-VQA question taxonomy (for per-category eval).
+                    "content_type":  row.get("content_type"),
+                    "semantic_type": row.get("semantic_type"),
+                    "answer_type":   ("closed"
+                                      if str(answer).strip().lower() in ("yes", "no")
+                                      else "open"),
                 })
                 n_vqa += 1
 

data/mimic_cxr_resized_builder.py

@@ -405,6 +405,14 @@ def build_mimic_cxr_resized_instruct_json(
                     "split": split_label,
                     "study_id":  study_str,
                     "subject_id": subj_str,
+                    # MIMIC-CXR-VQA question taxonomy — carried through so
+                    # evaluation can break metrics down per category. answer_type
+                    # is derived: yes/no → closed, otherwise open (multi-label).
+                    "content_type":  row.get("content_type"),
+                    "semantic_type": row.get("semantic_type"),
+                    "answer_type":   ("closed"
+                                      if str(answer).strip().lower() in ("yes", "no")
+                                      else "open"),
                 })
                 n_vqa += 1
 

docs/convert_md.py

@@ -0,0 +1,111 @@
+"""
+Convert file Markdown (.md) sang Word (.docx) / HTML / PDF bang pandoc.
+
+CACH DUNG: chi can BAM CHAY (Run trong VSCode/PyCharm, hoac double-click).
+Khong can go lenh / khong can nhap args. Chinh cau hinh o khoi CONFIG ben duoi.
+
+CAI 1 LAN (neu chua co): python -m pip install pypandoc_binary
+"""
+
+# =====================================================================
+#  CONFIG  --  SUA TRUC TIEP O DAY ROI BAM CHAY
+# =====================================================================
+
+# File can convert. Co the la:
+#   - 1 ten file:      "methodology_rewrite.md"
+#   - nhieu file:      ["methodology_rewrite.md", "bai2.md"]
+#   - tat ca file .md: "ALL"
+INPUT = "methodology_rewrite.md"
+
+# Dinh dang dau ra: "docx" | "html" | "pdf"
+OUTPUT_FORMAT = "docx"
+
+# Ten file dau ra. De None thi tu dat trung ten file goc (chi dung khi INPUT la 1 file).
+OUTPUT_NAME = None
+
+# =====================================================================
+#  (Khong can sua tu day tro xuong)
+# =====================================================================
+
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+
+
+def ensure_pypandoc():
+    try:
+        import pypandoc  # noqa: F401
+        return
+    except ImportError:
+        print("[!] Chua co pypandoc. Dang cai 'pypandoc_binary' (kem san pandoc)...")
+        import subprocess
+        subprocess.check_call(
+            [sys.executable, "-m", "pip", "install", "--quiet", "pypandoc_binary"]
+        )
+        print("[+] Cai xong.")
+
+
+def convert_one(md_path: Path, to_fmt: str, out_path: Path | None) -> Path:
+    import pypandoc
+
+    if not md_path.exists():
+        raise FileNotFoundError(f"Khong tim thay file: {md_path}")
+
+    if out_path is None:
+        out_path = md_path.with_suffix("." + to_fmt)
+
+    extra_args = ["--toc", "--toc-depth=3"]
+    if to_fmt == "html":
+        extra_args += ["--standalone", "--mathjax", "--embed-resources"]
+    elif to_fmt == "pdf":
+        extra_args += ["-V", "geometry:margin=2.5cm"]
+
+    pypandoc.convert_file(
+        str(md_path), to_fmt, outputfile=str(out_path), extra_args=extra_args
+    )
+    return out_path
+
+
+def resolve_inputs(inp) -> list[Path]:
+    if isinstance(inp, str) and inp.upper() == "ALL":
+        return sorted(HERE.glob("*.md"))
+    if isinstance(inp, (list, tuple)):
+        return [(HERE / x) if not Path(x).is_absolute() else Path(x) for x in inp]
+    p = Path(inp)
+    return [p if p.is_absolute() else HERE / p]
+
+
+def main():
+    ensure_pypandoc()
+
+    md_files = resolve_inputs(INPUT)
+    if not md_files:
+        print("[!] Khong tim thay file .md nao de convert.")
+        return
+
+    many = len(md_files) > 1
+    for md in md_files:
+        out = None
+        if OUTPUT_NAME and not many:
+            out = Path(OUTPUT_NAME)
+            if not out.is_absolute():
+                out = HERE / out
+        try:
+            result = convert_one(md, OUTPUT_FORMAT, out)
+            print(f"[+] {md.name} -> {result.name}")
+        except Exception as e:  # noqa: BLE001
+            print(f"[x] Loi voi {md.name}: {e}")
+            if OUTPUT_FORMAT == "pdf":
+                print("    -> PDF can mot LaTeX engine (MiKTeX/TeX Live). "
+                      "Thu doi OUTPUT_FORMAT='html' roi in PDF tu trinh duyet.")
+
+
+if __name__ == "__main__":
+    main()
+    # Giu cua so terminal mo khi double-click tren Windows
+    try:
+        if sys.stdin and sys.stdin.isatty():
+            input("\nXong. Nhan Enter de dong...")
+    except Exception:
+        pass

docs/methodology_figure_placements.md

@@ -0,0 +1,121 @@
+# Gợi ý vị trí chèn sơ đồ trong Methodology
+
+> Danh sách các chỗ nên thêm hình (ngoài Figure pipeline tổng quan ở §Overview đã có). Mỗi mục ghi rõ: **anchor** (chèn ở đâu trong `methodology (1).tex`), **nội dung sơ đồ**, **caption gợi ý**, **độ ưu tiên**. Bạn xem rồi chọn cái nào làm.
+>
+> Ký hiệu ưu tiên: ⭐⭐⭐ rất nên có (paper/thesis nào cũng vẽ) · ⭐⭐ nên có · ⭐ tuỳ chọn.
+
+---
+
+## A. Phần Data Preparation (§sec:data)
+
+### A1. Sơ đồ data pipeline 3 phase ⭐⭐⭐
+- **Anchor:** ngay sau đoạn mở đầu §Data Preparation (đoạn "...operates in three logical phases: selection / image transfer / resize and re-shard...", ~dòng 244–255), trước §Sources.
+- **Nội dung:** flow ngang 3 phase → output: `[SSD: CSV metadata] → Selection → [Cloud notebook] → Image transfer (PhysioNet) → [GPU host] → Resize + tar shard → Unified JSON`. Đánh dấu nơi chạy (SSD/cloud/GPU) và artefact trung gian.
+- **Caption:** "Three-phase offline data pipeline. Heavy linear-cost work (DICOM join, parsing, resize) runs once; the training loop only consumes the unified JSON + resized image tree."
+- *Tương đương Figure 2.3 của report mẫu — gần như bắt buộc.*
+
+### A2. Funnel lọc 4 tầng (selection) ⭐⭐⭐
+- **Anchor:** đầu §Selection Pipeline (sec:selection, ~dòng 283–288), hoặc ngay sau paragraph (d) Stratified sampling.
+- **Nội dung:** sơ đồ phễu (funnel) thu hẹp dần: `~227k studies → (a) frontal-only → (b) report parse (cần cả Findings+Impression) → (c) length-outlier removal → (d) stratified patient-disjoint sampling → 50k (40k/5k/5k)`. Ghi số study còn lại sau mỗi tầng nếu có.
+- **Caption:** "Four-stage filter chain reducing the full MIMIC-CXR corpus to the 50,000-study working subset."
+- *Rất "ăn điểm" và dễ hiểu; nên có số liệu thật ở mỗi tầng.*
+
+### A3. Sơ đồ rẽ nhánh report_mode / image_mode → samples ⭐⭐
+- **Anchor:** sau bảng `tab:reportmodes` (~dòng 418), trong §Unified Instruction JSON.
+- **Nội dung:** 1 study → (image_mode: frontal_only_split → 1 ảnh) → (report_mode: split_cascade → 2 sample: `findings` từ ảnh; `impression` từ ảnh + GT findings). Minh hoạ cascade nối findings→impression.
+- **Caption:** "How one study is serialised into training samples under `report_mode=split_cascade` and `image_mode=frontal_only_split`."
+
+---
+
+## B. Phần Model Architecture (§sec:arch)
+
+### B1. RAD-DINO patchification ⭐⭐
+- **Anchor:** trong §Image Encoder (sec:encoder), sau câu "...emits 1369 patch tokens of dimension 768... class token is discarded..." (~dòng 453–456).
+- **Nội dung:** `518×518 image → ViT-B/14 chia patch 14×14 → grid 37×37 = 1369 tokens (768-d) [+ CLS bị loại]`. Có thể thêm overlay heatmap minh hoạ patch.
+- **Caption:** "RAD-DINO patchification: a 518×518 chest X-ray becomes 1369 patch tokens (768-d); the [CLS] token is dropped before projection."
+
+### B2. Chi tiết module MLP Projection ⭐⭐⭐
+- **Anchor:** trong §MLP Projection (sec:projection), ngay sau khối align equations (eq:tap, ~dòng 501) hoặc cuối tiểu mục.
+- **Nội dung:** `Patch features P (1369×768) + 32 learnable query Q0 → CrossAttn 8-head → H0 (32×768) → Linear W1 + GELU + Dropout → H1 (32×1024) [TAP cho ITC head] → Linear W2 → V (32×4096)`. Đánh dấu nhánh 1024-d rẽ sang ITC head.
+- **Caption:** "MLP projection module. A 32-query cross-attention pool compresses 1369 patch tokens; the 1024-d intermediate is the tap point routed to the ITC head (Stage 1) or onward to the LLM (Stage 2)."
+- *Module trung tâm của model — nên vẽ kỹ.*
+
+### B3. CheXpert classifier → PNU string ⭐⭐
+- **Anchor:** trong §CheXpert Classifier (sec:chex), sau khối verbatim ví dụ PNU (~dòng 537) hoặc cuối tiểu mục.
+- **Nội dung:** `RAD-DINO [CLS] embedding → MLP head → 14×3 logits (per-label argmax) → format_pnu() → PNU 3-section string → chèn vào prompt giữa visual tokens và instruction`. Phân biệt nhánh train (GT từ CSV) vs eval (classifier tự predict).
+- **Caption:** "Auxiliary CheXpert head: the global RAD-DINO embedding is mapped to a 14×3 (Positive/Negative/Uncertain) tensor and serialised into the PNU prompt block."
+
+### B4. LoRA injection trên attention block ⭐⭐
+- **Anchor:** trong §Language Model and PEFT (sec:llm), sau đoạn mô tả LoRA trên q/k/v/o (~dòng 584–593).
+- **Nội dung:** 1 transformer block: base weight W (4-bit NF4, frozen) + adapter `ΔW = B·A` (rank 16, trainable) trên q/k/v/o; FFN để nguyên. Có thể thêm công thức `h = Wx + (α/r)·BAx`.
+- **Caption:** "LoRA adaptation: rank-16 low-rank adapters on q/k/v/o of every Vicuna block; the 4-bit base weights stay frozen, the feed-forward sublayers are untouched."
+
+### B5. Anatomy của prompt + `<image>` expansion ⭐⭐⭐
+- **Anchor:** trong §Prompt Assembly (sec:prompt), sau khối verbatim prompt skeleton (~dòng 606) và/hoặc sau đoạn mô tả expand 31 vị trí (~dòng 608–615).
+- **Nội dung:** hai phần:
+  1. **Prompt anatomy** — thanh ngang chia slot, tô màu theo task: `[SYSTEM] [<image>] [PNU block] [task context: GT findings / empty] [instruction] [ASSISTANT: target]`.
+  2. **Image-token expansion** — `1 <image> placeholder → thay bằng 32 visual tokens → attention mask & label tensor nở thêm 31 vị trí; vùng visual + prompt + pad gán -100`.
+- **Caption:** "Prompt assembly and image-token expansion. The single `<image>` placeholder is replaced by 32 visual tokens; attention mask, position ids, and labels are expanded by 31, with all non-target positions masked to −100."
+- *Quan trọng cho phần dễ sai nhất của pipeline (loss masking).*
+
+---
+
+## C. Phần Training Strategy (§sec:training)
+
+### C1. Sơ đồ curriculum 3 stage ⭐⭐⭐
+- **Anchor:** đầu §Training Strategy, sau đoạn intro (~dòng 665–674), trước §Stage 0.
+- **Nội dung:** 3 khối nối tiếp, mỗi khối ghi module frozen/trainable + loss:
+  - `Stage 0`: RAD-DINO frozen → MLP head (BCE, U-MultiClass).
+  - `Stage 1 (ITC)`: encoder frozen, projection+ITC head trainable, **LLM không load**, loss InfoNCE.
+  - `Stage 2`: encoder+classifier+base-LLM frozen, projection+LoRA trainable, loss causal CE.
+  Mũi tên: projection weights Stage 1 → nạp vào Stage 2.
+- **Caption:** "Two-stage training curriculum (preceded by the Stage 0 classifier). Stage 1 aligns the projection contrastively without loading Vicuna; Stage 2 loads the full model and instruction-tunes projection + LoRA."
+
+### C2. Sơ đồ contrastive Stage 1 (kiểu CLIP) ⭐⭐⭐
+- **Anchor:** trong §Stage 1 (sec:stage1), sau equation InfoNCE (eq:itc, ~dòng 720).
+- **Nội dung:** hai nhánh:
+  - Image: `image → RAD-DINO → projection → ITC head → mean-pool → 128-d L2-norm`.
+  - Text (offline): `findings (fallback impression) → CXR-BERT → 128-d L2-norm → cache {study_id → tensor}`.
+  - Ma trận tương đồng `B×B`, đường chéo = positive, InfoNCE đối xứng.
+- **Caption:** "Stage 1 image–text contrastive alignment. Text embeddings are precomputed offline with CXR-BERT; only the projection + ITC head receive gradients."
+
+### C3. Sơ đồ loss masking (label tensor) ⭐⭐
+- **Anchor:** trong §Loss Masking and Image-Token Accounting (~dòng 781–797).
+- **Nội dung:** một dải token tuyến tính tô màu: `[system −100][32 visual −100][PNU −100][instruction −100][pad −100]` vs `[assistant response: loss được tính]`. Minh hoạ chỉ vùng response đóng góp cross-entropy.
+- **Caption:** "Label masking. Cross-entropy is computed strictly on assistant-response tokens; system prompt, visual span, PNU block, instruction, and padding are all set to −100."
+
+---
+
+## D. Phần Evaluation (§sec:eval) — nếu giữ trong Methodology
+
+### D1. Sơ đồ luồng evaluation ⭐
+- **Anchor:** đầu §Evaluation Protocol hoặc trong §Tasks and Held-Out Data (~dòng 877–896).
+- **Nội dung:** `test image → [CheXpert PNU predicted] (+ GT findings nếu impression) → model greedy decode → hypothesis → {NLG metrics: BLEU/ROUGE/METEOR/BERTScore} + {Clinical: CheXbert F1} + {VQA: EM/token-F1/LLM-judge}`.
+- **Caption:** "Evaluation flow per task, from test image to the metric families reported."
+
+### D2. Sơ đồ CheXbert F1 ⭐
+- **Anchor:** trong §Clinical Correctness (sec:clinical-f1, ~dòng 938–961).
+- **Nội dung:** `generated report + reference report → CheXbert labeler → 2 vectors 14 nhãn → binarise (−1,0→neg) → macro-F1/P/R`.
+- **Caption:** "Clinical F1: both generated and reference reports are labeled by CheXbert; the 14-label vectors are compared after binarisation."
+
+---
+
+## Tổng hợp ưu tiên
+
+| # | Sơ đồ | Mục | Ưu tiên |
+|---|---|---|---|
+| A1 | Data pipeline 3 phase | §Data Prep | ⭐⭐⭐ |
+| A2 | Funnel lọc 4 tầng | §Selection | ⭐⭐⭐ |
+| B2 | MLP Projection chi tiết | §Projection | ⭐⭐⭐ |
+| B5 | Prompt anatomy + `<image>` expansion | §Prompt | ⭐⭐⭐ |
+| C1 | Curriculum 3 stage | §Training | ⭐⭐⭐ |
+| C2 | Contrastive Stage 1 (CLIP-style) | §Stage 1 | ⭐⭐⭐ |
+| A3 | report_mode/image_mode → samples | §JSON | ⭐⭐ |
+| B1 | RAD-DINO patchification | §Encoder | ⭐⭐ |
+| B3 | CheXpert → PNU | §CheXpert | ⭐⭐ |
+| B4 | LoRA injection | §LLM | ⭐⭐ |
+| C3 | Loss masking | §Masking | ⭐⭐ |
+| D1 | Luồng evaluation | §Eval | ⭐ |
+| D2 | CheXbert F1 | §Clinical F1 | ⭐ |
+
+> Nếu muốn, tôi có thể chèn sẵn các marker `% [INSERT FIGURE Xn: ...]` vào đúng vị trí trong `methodology (1).tex` (chỉ là comment, không ảnh hưởng biên dịch) để bạn thấy ngay chỗ nào cần hình khi mở file.

docs/methodology_revision_plan.md

@@ -0,0 +1,157 @@
+# Kế hoạch chỉnh sửa Methodology cho khớp văn phong thesis USTH
+
+> Tài liệu này so sánh `docs/methodology (1).tex` (bản hiện tại, viết theo văn phong paper RaDialog/META-CXR/BLIP-2) với report tham khảo của anh khoá trên (`main.pdf` — *Multi-Agent AI System for Industrial Machine Maintenance*, USTH Bachelor Thesis 2025), và liệt kê những gì cần chỉnh để bản methodology của bạn "na ná" report thesis đó. **Chưa sửa `.tex` — chỉ là plan để bạn duyệt.**
+
+---
+
+## 1. Report tham khảo có cấu trúc & văn phong gì?
+
+**Cấu trúc toàn luận văn (4 chương):**
+1. **Introduction** — Problem Statement / Objectives / Expected Outcomes / Thesis structure
+2. **Methodology** — Key Concepts and Definitions → Dataset → System Architecture → Agents (mô tả từng module) → Reasoning Strategy
+3. **Experiments and Results** — Experimental Setup (Datasets, Environment) → Results and Discussion
+4. **Conclusion** — Summary / Limitations / Future Work
++ Front matter: Acknowledgements, Abstract, **List of Abbreviations**, List of Figures, List of Tables
+
+**Đặc điểm văn phong (cấp độ undergraduate, KHÔNG phải paper):**
+- Mở đầu chương Methodology bằng tiểu mục **"Key Concepts and Definitions"** — định nghĩa từng khái niệm nền (Agent, LLM, ReAct/CoT, LangGraph) *trước khi* dùng. Đây là phần bản của bạn **đang thiếu hoàn toàn**.
+- Mỗi module/thành phần được mô tả theo **template bullet cố định**: `Objective:` / `Input:` / `Output:` / `Core Logic:`. Rất dễ đọc, rất "thesis USTH".
+- **Nhiều hình** (mỗi agent có 1 sơ đồ kiến trúc/flowchart riêng) và **nhiều bảng** (overview dataset, config, hyperparameters, sample output).
+- Văn xuôi **đơn giản, mô tả** — câu ngắn, đôi khi xưng "I" ("I selected…", "I leverage…"). Ít biện luận kiểu nghiên cứu.
+- Equation đánh số đơn giản (Eq 1, Eq 2…), giải thích ký hiệu bằng bullet `Where:`.
+- **Evaluation/metrics nằm ở chương Experiments**, KHÔNG nằm trong Methodology.
+- Có **bảng ví dụ output thật** (Sample Output from Alert Agent) để minh hoạ.
+- Bibliography kiểu **IEEE đánh số `[1]`** kèm URL.
+
+---
+
+## 2. Methodology hiện tại của bạn đang như thế nào?
+
+- 1 chương duy nhất, văn phong **paper top-tier**: Overview → Data Preparation → Model Architecture → Training Strategy → **Evaluation Protocol**.
+- Văn xuôi **rất dày, học thuật cao** (đoạn dài, biện luận kiểu "ablations show…", "sweet spot in grid search over {1,2,4}", confidence interval bootstrap…).
+- Chỉ có **1 hình** (TikZ pipeline). Có equation đẹp, vài bảng tốt.
+- **Không có** phần định nghĩa khái niệm nền.
+- **Có** cả Evaluation Protocol đầy đủ trong methodology (report tham khảo đẩy phần này sang Experiments).
+- Bibliography kiểu `natbib`/`abbrvnat` (citep), khác kiểu IEEE số của report mẫu.
+
+> Kết luận: nội dung của bạn **đầy đủ và chất lượng hơn** report mẫu, nhưng **văn phong & cách trình bày lệch hẳn** sang phong cách paper. Để "na ná thesis USTH" thì cần *hạ altitude*, *bullet-hoá*, *thêm hình/bảng*, và *thêm phần định nghĩa khái niệm*.
+
+---
+
+## 3. Bảng khác biệt chính & hướng xử lý
+
+| Khía cạnh | Report mẫu (main.pdf) | Bản của bạn hiện tại | Cần chỉnh |
+|---|---|---|---|
+| Mở đầu chương | "Key Concepts and Definitions" định nghĩa nền | Vào thẳng Overview | **Thêm** tiểu mục Key Concepts |
+| Mô tả module | Bullet `Objective/Input/Output/Core Logic` | Văn xuôi dày | **Bullet-hoá** từng module |
+| Hình minh hoạ | Nhiều (mỗi module 1 sơ đồ) | 1 hình pipeline | **Thêm** 3–5 hình |
+| Bảng | Overview, config, hyperparams, **sample output** | Có hyperparams, datasources, modes | **Thêm bảng sample output** |
+| Văn phong | Đơn giản, undergrad, đôi khi "I" | Dày, paper, hedging nhiều | **Hạ altitude**, cắt biện luận thừa |
+| Evaluation | Ở chương Experiments | Trong Methodology | **Cân nhắc tách** sang Experiments |
+| Equation | Đơn giản + `Where:` bullet | Đẹp nhưng dày | Giữ, thêm `Where:` giải thích ký hiệu |
+| Abbreviations | Có bảng riêng | Không | **Thêm** List of Abbreviations |
+| Bibliography | IEEE số `[n]` + URL | natbib abbrvnat | (tuỳ template chung của luận văn) |
+
+---
+
+## 4. Khuyến nghị chỉnh sửa cụ thể
+
+### 4.1. Thêm tiểu mục "Key Concepts and Definitions" (ưu tiên cao)
+Đặt ngay sau phần Overview, định nghĩa ngắn gọn (mỗi mục 2–4 câu, có thể kèm 1 hình) các khái niệm:
+- **Vision–Language Model (VLM)** — mô hình kết hợp ảnh + ngôn ngữ.
+- **Chest X-ray report**: phân biệt **Findings** vs **Impression**; **VQA**.
+- **Large Language Model / Vicuna** — vai trò decoder.
+- **Vision Transformer (ViT) & self-supervised (DINOv2) → RAD-DINO**.
+- **LoRA / PEFT / QLoRA (4-bit NF4)** — định nghĩa "parameter-efficient".
+- **Image–Text Contrastive (ITC) / InfoNCE** — học căn chỉnh ảnh–văn bản.
+- **CheXpert 14 pathologies & U-MultiClass (Positive/Negative/Uncertain)**.
+
+> Lý do: report mẫu dành hẳn §2.1 cho việc này; người chấm USTH quen đọc định nghĩa nền trước khi vào hệ thống.
+
+### 4.2. Bullet-hoá mô tả từng module (ưu tiên cao)
+Áp dụng template của report mẫu cho 4 module trong §Model Architecture. Ví dụ cho **MLP Projection**:
+
+```
+Objective: Pool patch features thành số token cố định và bridge không gian
+           vision (768-d) → LLM (4096-d).
+Input:     Patch features P ∈ R^{B×1369×768} từ RAD-DINO (frozen).
+Output:    Visual tokens V ∈ R^{B×32×4096}; nhánh phụ xuất 1024-d cho ITC head.
+Core Logic: 32 learnable query → cross-attention 8-head → MLP (GELU, dropout)
+           → linear ra 4096-d. (kèm Eq. cross-attn)
+```
+Làm tương tự cho: Image Encoder, CheXpert Classifier, Language Model + LoRA. Giữ lại các equation hiện có, chỉ tách phần biện luận dài thành câu mô tả ngắn.
+
+### 4.3. Thêm hình minh hoạ (ưu tiên cao — report mẫu rất "ăn điểm" nhờ hình)
+Đề xuất tối thiểu 4 hình:
+1. **Data preparation pipeline** (giống Fig 2.3 của mẫu): selection → resize/shard → unified JSON. (Hiện chỉ mô tả bằng chữ ở §Data Preparation.)
+2. **Two-stage training schedule** — sơ đồ Stage 0 (CheXpert) → Stage 1 (ITC, không load LLM) → Stage 2 (instruction tuning), kèm ô "frozen/trainable".
+3. **Projection module detail** — query tokens → cross-attn → MLP → (ITC head / LLM).
+4. **Prompt assembly** — minh hoạ chèn `<image>` (1 token → 32 visual token) + PNU block + instruction.
+
+> Hình pipeline TikZ hiện tại giữ nguyên làm Figure tổng quan ở Overview.
+
+### 4.4. Thêm bảng "Sample Output" (ưu tiên trung bình)
+Report mẫu có Table 2.7/2.8 ví dụ output thật → rất thuyết phục. Bạn nên thêm:
+- **Bảng ví dụ một training sample hoàn chỉnh**: prompt (system + `<image>` + PNU + instruction) → target findings.
+- **Bảng ví dụ PNU string** sinh ra từ CheXpert classifier.
+- (Nếu có) ví dụ findings/impression model sinh ra vs ground-truth.
+
+### 4.5. Hạ altitude văn phong (ưu tiên trung bình)
+- Cắt/giảm các câu biện luận kiểu nghiên cứu sâu: "monotone improvement as batch grew from 8 to 64", "diverged within ~300 steps", "0.3% of best validation contrastive accuracy", "bootstrap 1000 resamples"… → giữ kết luận, bỏ chi tiết thí nghiệm (chuyển sang chương Experiments nếu muốn).
+- Rút ngắn đoạn dài thành câu mô tả + bullet.
+- Cho phép xưng "I"/"we" nhất quán như report mẫu (mẫu dùng "I").
+
+### 4.6. Cân nhắc tách Evaluation Protocol sang chương Experiments (ưu tiên trung bình)
+Report mẫu để toàn bộ metrics ở **Chapter 3 — Experiments and Results** (Experimental Setup → Results). Bản của bạn đang để Evaluation Protocol trong Methodology.
+- **Phương án A (giống mẫu nhất):** chuyển §Evaluation Protocol → chương Experiments, mục "Evaluation Metrics".
+- **Phương án B (giữ trong Methodology):** giữ nhưng rút gọn, bỏ phần Reporting/bootstrap CI (đẩy sang Experiments).
+→ *Cần bạn quyết theo template chung của luận văn.*
+
+### 4.7. Front matter & tiểu tiết (ưu tiên thấp)
+- Thêm **List of Abbreviations**: CXR, VLM, LLM, RRG, VQA, LoRA, QLoRA, PEFT, ITC, InfoNCE, PNU, ViT, MLP, BLEU, ROUGE, NLG, MIMIC-CXR, RAD-DINO, CheXbert…
+- Đồng bộ **bibliography style** với template luận văn (nếu khoa yêu cầu IEEE số `[n]` thì đổi từ natbib `abbrvnat`).
+- Đảm bảo mọi hình/bảng đều được **ref trong văn** (mẫu làm rất kỹ điều này).
+
+---
+
+## 5. Outline đề xuất cho chương Methodology (sau chỉnh)
+
+```
+Chapter: Methodology
+  X.1 Overview                         (giữ, kèm Figure pipeline tổng quan)
+  X.2 Key Concepts and Definitions     (MỚI — §4.1)
+       VLM · Findings/Impression/VQA · LLM/Vicuna · ViT/RAD-DINO ·
+       LoRA/QLoRA · ITC/InfoNCE · CheXpert U-MultiClass (PNU)
+  X.3 Dataset / Data Preparation       (giữ; THÊM Figure pipeline dữ liệu)
+       Sources · Selection · Storage/Resize · Unified JSON
+  X.4 Model Architecture               (bullet-hoá theo §4.2)
+       Image Encoder · MLP Projection · CheXpert Classifier · LLM + LoRA
+       · Prompt Assembly (THÊM Figure prompt + bảng sample)
+  X.5 Training Strategy                (giữ; THÊM Figure 3-stage; hạ altitude §4.5)
+       Stage 0 · Stage 1 (ITC) · Stage 2 · Hyperparameters table
+  [X.6 Evaluation Protocol]            (CÂN NHẮC chuyển sang Experiments — §4.6)
+```
+
+---
+
+## 6. Checklist thực thi (khi bạn duyệt xong)
+
+- [ ] Viết tiểu mục **Key Concepts and Definitions** (§4.1)
+- [ ] Bullet-hoá 4 module + Prompt Assembly theo `Objective/Input/Output/Core Logic` (§4.2)
+- [ ] Vẽ **4 hình** TikZ: data pipeline, 3-stage training, projection detail, prompt assembly (§4.3)
+- [ ] Thêm **bảng sample**: training sample đầy đủ, PNU string (§4.4)
+- [ ] **Hạ altitude** văn phong, cắt biện luận thí nghiệm thừa (§4.5)
+- [ ] Quyết & xử lý **Evaluation Protocol** (giữ rút gọn / chuyển sang Experiments) (§4.6)
+- [ ] Thêm **List of Abbreviations**; đồng bộ bibliography style (§4.7)
+- [ ] Kiểm tra mọi figure/table đều được cross-ref trong văn
+
+---
+
+## 7. Lưu ý về nội dung (đối chiếu code/CLAUDE.md)
+
+Nội dung methodology hiện tại **khớp tốt** với CLAUDE.md (RAD-DINO 518×518, 1369 patch token, projection 32 token 4096-d, ITC InfoNCE τ=0.07, LoRA r16/α32 trên q/k/v/o, QLoRA NF4, split_cascade + frontal_only_split, PNU 3-section…). Vài điểm cần bạn xác nhận lại với số liệu thật khi viết Experiments (không ảnh hưởng cấu trúc):
+- Các con số sweep/grid-search (batch 16/32/64/96, lr 1e-4/2e-4/5e-4) — nếu là **minh hoạ/giả định** thì nên chuyển thành mô tả định tính, tránh khẳng định kết quả chưa chạy.
+- Số study subset (40k/5k/5k), Δ prevalence <0.7pp — xác nhận đúng số liệu pipeline thật của bạn.
+- Eval thresholds (max new tokens 300/200/64) — khớp config thật.
+
+> Những điểm này thuộc về *độ chính xác số liệu*, sẽ chốt khi viết chương Experiments; không cản trở việc tái cấu trúc văn phong ở trên.

docs/methodology_rewrite.md

@@ -0,0 +1,315 @@
+# Chapter 2. Methodology
+
+> **Ghi chú cho bạn:** đây là bản methodology viết lại theo văn phong thesis USTH (đơn giản hơn, bullet-hoá theo `Objective/Input/Output/Core Logic`, thêm phần *Key Concepts*, hạ altitude so với bản `.tex` paper-style). Các chú thích chèn biểu đồ được đặt ngay dưới đoạn liên quan dưới dạng `> 📊 **(Thêm biểu đồ: …)**`. Cấu hình giả định xuyên suốt: `report_mode = split_cascade`, `image_mode = frontal_only_split`.
+
+This chapter describes how the proposed Vision–Language Model (**CXR-VLM**) is built and trained. It is organised in five parts. Section 2.1 gives an end-to-end overview. Section 2.2 defines the key concepts used throughout the chapter. Section 2.3 documents how the MIMIC-CXR corpus is filtered and serialised into the unified instruction format. Section 2.4 describes the four modules of the model and the prompt that ties them together. Section 2.5 specifies the two-stage training schedule. Section 2.6 defines the evaluation protocol.
+
+---
+
+## 2.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:
+
+- 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:
+
+$$
+\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).
+
+> 📊 **(Thêm biểu đồ — pipeline tổng quan):** sơ đồ end-to-end `CXR image → RAD-DINO (frozen) → MLP Projection (trainable) → Vicuna-7B + LoRA (trainable) → Findings/Impression/Answer`, với nhánh CheXpert classifier (frozen) bơm PNU string vào prompt. Tô màu xanh = frozen, cam = trainable. *(Đây là hình duy nhất bản cũ đã có — giữ lại làm Figure tổng quan.)*
+
+---
+
+## 2.2 Key Concepts and Definitions
+
+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.
+
+- **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.
+
+- **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.
+
+- **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.
+
+> 📊 **(Thêm biểu đồ — tuỳ chọn):** một hình nhỏ minh hoạ ViT patchification hoặc khái niệm contrastive (ảnh ↔ text kéo gần/đẩy xa) có thể đặt ở đây để minh hoạ định nghĩa, nếu muốn phần này trực quan hơn.
+
+---
+
+## 2.3 Data Preparation
+
+The data pipeline runs in three phases, each tuned to a different bottleneck: **selection** runs on a local SSD where the MIMIC-CXR CSV metadata lives; **image transfer** runs on a cloud notebook so PhysioNet's authenticated transfer can saturate the network; and **resize / re-shard** runs once on a GPU host so 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.
+
+> 📊 **(Thêm biểu đồ — A1, ưu tiên cao):** sơ đồ data pipeline 3 phase: `[SSD] Selection → [Cloud notebook] Image transfer (PhysioNet) → [GPU host] Resize + tar shard → Unified JSON`. Đánh dấu nơi chạy và artefact trung gian. *(Tương đương Figure 2.3 của report mẫu.)*
+
+### 2.3.1 Sources
+
+All sources come from the public PhysioNet distribution under credentialed access; no manual annotation is performed.
+
+| Source | Version | Used for |
+|---|---|---|
+| MIMIC-CXR | 2.1.0 | Radiology report `.txt` files |
+| 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-chexpert` | — | 14 pathology labels per study |
+
+### 2.3.2 Selection Pipeline
+
+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)**.
+
+- **(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**.
+
+Distribution preservation is checked by comparing per-pathology prevalence at the raw, eligible-pool, and final-subset levels.
+
+> 📊 **(Thêm biểu đồ — A2, ưu tiên cao):** sơ đồ phễu (funnel) thu hẹp dần qua 4 tầng `(a)→(b)→(c)→(d)`, ghi số study còn lại sau mỗi tầng: `~227k → … → 50k (40k/5k/5k)`.
+
+### 2.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.
+
+### 2.3.4 Unified Instruction JSON
+
+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:
+
+```
+{ image_path, task, target, question, structured_findings, split, study_id, subject_id }
+```
+
+Two knobs control sample creation:
+
+- **`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.
+
+| 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 and written into `structured_findings` at build time, so the trainer loads no labels at runtime.
+
+> 📊 **(Thêm biểu đồ — A3, ưu tiên trung bình):** sơ đồ rẽ nhánh `1 study → (frontal_only_split: 1 ảnh) → (split_cascade: sample findings [ảnh] + sample impression [ảnh + GT findings])`, minh hoạ quan hệ cascade findings→impression.
+
+---
+
+## 2.4 Model Architecture
+
+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.
+
+### 2.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.
+
+> 📊 **(Thêm biểu đồ — B1, ưu tiên trung bình):** `518×518 image → ViT-B/14 patch 14×14 → grid 37×37 = 1369 tokens (768-d) [+ CLS bị loại]`.
+
+### 2.4.2 MLP Projection
+
+- **Objective.** Pool a long, variable-length patch sequence into a fixed visual-token budget, and bridge the vision space (768-d) to the LLM space (4096-d).
+- **Input.** Patch features `P ∈ R^{1369×768}`.
+- **Output.** 32 visual tokens `V ∈ R^{32×4096}`; a 1024-d intermediate is also exposed as a tap point for the ITC head.
+- **Core logic.** A perceiver-style block with 32 learnable query tokens. The forward pass is:
+
+$$
+\mathbf{H}^{(0)} = \operatorname{CrossAttn}(\mathbf{Q}_0, \mathbf{P}, \mathbf{P}) \in \mathbb{R}^{32\times 768}
+$$
+$$
+\mathbf{H}^{(1)} = \operatorname{Dropout}(\operatorname{GELU}(\mathbf{W}_1 \mathbf{H}^{(0)})) \in \mathbb{R}^{32\times 1024}
+$$
+$$
+\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.
+
+> 📊 **(Thêm biểu đồ — B2, ưu tiên cao):** chi tiết module: `P (1369×768) + 32 query Q₀ → CrossAttn 8-head → H⁰ (32×768) → Linear W₁+GELU+Dropout → H¹ (32×1024) [TAP → ITC head] → Linear W₂ → V (32×4096)`.
+
+### 2.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:
+
+```
+Positive Abnormalities: Cardiomegaly, Pleural Effusion
+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.
+
+> 📊 **(Thêm biểu đồ — B3, ưu tiên trung bình):** `RAD-DINO [CLS] → MLP head → 14×3 logits → format_pnu() → PNU 3-section string → chèn vào prompt`. Phân biệt nhánh train (GT từ CSV) vs eval (classifier predict).
+
+### 2.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`.
+
+> 📊 **(Thêm biểu đồ — B4, ưu tiên trung bình):** một transformer block: base weight W (4-bit NF4, frozen) + adapter `ΔW = B·A` (rank 16, trainable) trên q/k/v/o; FFN frozen. Kèm `h = Wx + (α/r)·BAx`.
+
+### 2.4.5 Prompt Assembly
+
+All three tasks share one prompt skeleton, following Vicuna's v1.1 chat template:
+
+```
+{SYSTEM_PROMPT} USER: <image>
+{PNU structured findings}
+{task-specific context block}
+{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 task-specific context block is the main difference between `split` and `split_cascade`:
+
+- **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.
+- **VQA** — block empty; the question 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.
+
+> 📊 **(Thêm biểu đồ — B5, ưu tiên cao):** hai phần — (1) *prompt anatomy*: thanh ngang chia slot tô màu `[SYSTEM][<image>][PNU][context: GT findings/empty][instruction][ASSISTANT: target]`; (2) *image-token expansion*: `1 <image> → 32 visual tokens`, mask & label nở thêm 31, vùng non-target gán −100.
+
+---
+
+## 2.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.
+
+> 📊 **(Thêm biểu đồ — C1, ưu tiên cao):** curriculum 3 stage nối tiếp, mỗi khối ghi frozen/trainable + loss: `Stage 0 (CheXpert head, BCE)` → `Stage 1 (projection + ITC head, InfoNCE, LLM không load)` → `Stage 2 (projection + LoRA, causal CE)`. Mũi tên: projection weights Stage 1 → nạp vào Stage 2.
+
+### 2.5.1 Stage 0 — CheXpert Classifier Head
+
+The PNU classifier is fitted before Stages 1 and 2. It is a small MLP on the frozen RAD-DINO `[CLS]` embedding, optimised under 14 independent binary cross-entropies on the `chex_*` manifest columns with U-MultiClass targets. Training takes minutes once the patch features are cached; the checkpoint is then loaded read-only by both later stages.
+
+### 2.5.2 Stage 1 — Contrastive Alignment
+
+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.
+
+Stage 1 minimises the symmetric InfoNCE loss:
+
+$$
+\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).
+
+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).
+
+> 📊 **(Thêm biểu đồ — C2, ưu tiên cao):** sơ đồ contrastive kiểu CLIP — nhánh image `image→RAD-DINO→projection→ITC head→mean-pool→128-d L2`, nhánh text offline `findings→CXR-BERT→128-d L2 cache`, ma trận tương đồng B×B (đường chéo = positive), InfoNCE đối xứng.
+
+### 2.5.3 Stage 2 — Instruction Tuning
+
+Stage 2 rebuilds the full model with `load_llm = True`, loads the Stage 1 projection weights, and switches to the autoregressive objective. The dataset returns mixed batches by task weight (findings 30% / impression 20% / VQA 50% for MIMIC-CXR; weights renormalise when VQA is absent). The loss is the standard causal cross-entropy:
+
+$$
+\mathcal{L}_{\text{LM}} = -\frac{1}{|\mathcal{T}|}\sum_{(t,y)\in\mathcal{T}} \log p_\theta(y_t \mid y_{<t}, \mathbf{V}, \mathbf{c})
+$$
+
+**Where:** `T` is the set of positions where the label is not −100 (assistant response only), `V` the 32 visual tokens, and `c` the textual prompt context.
+
+Trainable parameters are the projection's MLP and the LoRA adapters; the encoder and classifier stay frozen. Stage 2 runs for 10 epochs at peak LR `2e-4` with a 5% cosine warm-up; the effective batch size is fixed at 16 across hardware by trading per-device batch against gradient accumulation. The optimiser is AdamW with FP32 master weights for the projection and LoRA, the 4-bit base Vicuna acting as a quantised constant.
+
+### 2.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.
+
+> 📊 **(Thêm biểu đồ — C3, ưu tiên trung bình):** dải token tuyến tính tô màu `[system −100][32 visual −100][PNU −100][instruction −100][pad −100]` vs `[assistant response: loss tính]`, minh hoạ chỉ vùng response đóng góp cross-entropy.
+
+### 2.5.5 Hyperparameters
+
+| Hyperparameter | Stage 1 (ITC) | Stage 2 |
+|---|---|---|
+| Trainable modules | Projection + ITC head | Projection + LoRA |
+| Frozen modules | Encoder, classifier; LLM not loaded | Encoder, classifier, base LLM |
+| Loss | Symmetric InfoNCE | Causal CE |
+| Temperature τ | 0.07 | — |
+| Epochs | 2 | 10 |
+| Peak learning rate | 1e-3 | 2e-4 |
+| LR schedule | cosine, 5% warm-up | cosine, 5% warm-up |
+| Weight decay | 0.01 | 0.01 |
+| Effective batch size | 64–96 | 16 |
+| Mixed precision | BF16 (Ampere+) / FP16 (T4) | BF16 / FP16 |
+| LLM quantisation | — | 4-bit NF4, double-quant |
+| LoRA (r, α, dropout) | — | (16, 32, 0.05) |
+| LoRA modules | — | {q, k, v, o}_proj |
+| Cutoff length | — | 512 tokens |
+| Optimiser | AdamW | AdamW |
+
+---
+
+## 2.6 Evaluation Protocol
+
+> **Ghi chú cho bạn:** report mẫu để toàn bộ metrics ở chương Experiments. Nếu theo đúng cấu trúc đó thì có thể chuyển mục 2.6 này sang Chapter 3. Tôi giữ ở đây để file method tự đủ; bạn quyết sau.
+
+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.
+
+| Family | Metric | Tasks |
+|---|---|---|
+| Lexical n-gram | BLEU-1, BLEU-4 | findings, impression, VQA |
+| | ROUGE-1/2/L | findings, impression |
+| Fluency / synonym | METEOR | findings, impression, VQA |
+| 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) |
+
+### 2.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.
+
+> 📊 **(Thêm biểu đồ — D1, tuỳ chọn):** luồng evaluation `test image → [CheXpert PNU] (+GT findings nếu impression) → greedy decode → hypothesis → {NLG} + {CheXbert F1} + {VQA: EM/token-F1/judge}`.
+
+### 2.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).
+- **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.
+
+### 2.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.
+
+> 📊 **(Thêm biểu đồ — D2, tuỳ chọn):** `generated report + reference report → CheXbert labeler → 2 vectors 14 nhãn → binarise → macro-F1/P/R`.
+
+### 2.6.4 Visual Question Answering Metrics
+
+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.
+
+### 2.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`.

docs/stratified_sampling.md

@@ -0,0 +1,661 @@
+# Stratified Sampling for the CXR-VLM Subset
+
+> A complete, worked explanation of how the 50 k MIMIC-CXR subset is drawn from the ~140 k eligible pool so that every CheXpert pathology and every VQA question type ends up with the same relative frequency in the subset as in the pool.
+>
+> **English version → §1**
+> **Vietnamese version → §2**
+
+---
+
+## §1. English version
+
+### 1.1. The problem this solves
+
+After the filter chain (frontal only → both findings + impression → length outlier removal), we are left with an *eligible pool* of roughly 140 000 studies. We want to keep only 50 000 of them — 40 k for train, 5 k for val, 5 k for test — for cost and storage reasons.
+
+The naive approach is to draw 50 000 studies **uniformly at random** from the pool. Mathematically this gives the correct *expected* distribution for every label, but it has a fatal flaw for rare pathologies: high variance.
+
+Concretely: "Pleural Other" is positive in about 0.5 % of the pool, i.e. ~700 studies. If we draw 50 000 of 140 000, the count of Pleural Other in the subset follows a hypergeometric distribution. Some draws will give us 240 such studies, others will give us 180 — a relative variance of ±10 %. For VQA, the rare semantic types (e.g. "choose") suffer the same problem.
+
+The training loss never sees individual labels, so this doesn't break training. But the **evaluation** suffers: with only 200 examples of a rare pathology in the test set, the per-pathology F1 score has wide confidence intervals — the noise drowns out the signal we want to measure.
+
+**Stratified sampling** fixes this by giving rare-label studies a *guaranteed* quota instead of leaving them to chance.
+
+### 1.2. The algorithm — five steps
+
+#### Step 1 — Compute pool-level pathology prevalence
+
+Count, for each of the 14 CheXpert labels, how many studies in the eligible pool have that label positive (`= 1`).
+
+```
+Pleural Other         700 / 140 000 = 0.50 %
+Lung Lesion         2 940 / 140 000 = 2.10 %
+Fracture            2 520 / 140 000 = 1.80 %
+Pneumothorax        4 200 / 140 000 = 3.00 %
+Pneumonia          12 600 / 140 000 = 9.00 %
+Consolidation      11 200 / 140 000 = 8.00 %
+Lung Opacity       30 800 / 140 000 = 22.00 %
+Atelectasis        33 740 / 140 000 = 24.10 %
+Pleural Effusion   29 400 / 140 000 = 21.00 %
+Cardiomegaly       25 900 / 140 000 = 18.50 %
+Edema              14 000 / 140 000 = 10.00 %
+Enlarged Card.     11 200 / 140 000 = 8.00 %
+Support Devices    51 800 / 140 000 = 37.00 %
+No Finding         33 740 / 140 000 = 24.10 %
+```
+
+(Numbers are illustrative but close to real MIMIC-CXR statistics. The point is the *ordering*.)
+
+#### Step 2 — Sort labels by rarity
+
+Lowest prevalence first:
+
+```
+rare_order = [ Pleural Other, Fracture, Lung Lesion, Pneumothorax,
+               Consolidation, Enlarged Cardiomediastinum, Pneumonia,
+               Edema, Cardiomegaly, Pleural Effusion, Lung Opacity,
+               Atelectasis, No Finding, Support Devices ]
+```
+
+#### Step 3 — Assign each study a single *stratum*
+
+A study often has *multiple* positive labels. We need to put it in exactly one bucket. Rule: **walk `rare_order` top to bottom; the first label that is positive becomes the study's stratum**.
+
+```
+Study with Cardiomegaly=1, Pleural_Effusion=1, others=0
+  → walk rare_order: Pleural_Other? no. Fracture? no. Lung_Lesion? no.
+    Pneumothorax? no. ... Cardiomegaly? YES.
+  → stratum = Cardiomegaly
+
+Study with Pleural_Other=1, Cardiomegaly=1, others=0
+  → walk rare_order: Pleural_Other? YES.
+  → stratum = Pleural_Other   (the rare label wins)
+
+Study with No_Finding=1 only
+  → stratum = No_Finding
+
+Study with all labels 0 or blank
+  → stratum = "None"
+```
+
+This rule has a critical consequence: every study positive for a rare label is *captured* into that label's stratum, where it cannot be drowned out by more common companions.
+
+After this pass, every study has exactly one stratum. Count studies per stratum:
+
+```
+Pleural_Other              ~  600   (some of the 700 PO studies have an even rarer label)
+Fracture                   ~ 2 200
+Lung_Lesion                ~ 2 500
+Pneumothorax               ~ 3 500
+Consolidation              ~ 9 000
+Enlarged Cardiomediast.    ~ 9 000
+Pneumonia                  ~10 000
+Edema                      ~11 000
+Cardiomegaly               ~18 000
+Pleural_Effusion           ~12 000
+Lung_Opacity               ~ 8 000
+Atelectasis                ~ 6 200
+No_Finding                 ~33 000
+None                       ~15 000
+                            -------
+TOTAL                       140 000
+```
+
+Note that the stratum size for Cardiomegaly (~18 000) is *less than* the number of studies positive for Cardiomegaly (~25 900). The ~7 900 difference are studies where Cardiomegaly is positive but a rarer label is also positive, so they ended up in that rarer stratum. This is the whole point.
+
+#### Step 4 — Allocate a sampling quota per stratum, proportional to stratum size
+
+```python
+quota[j] = round( |stratum_j| / N × n )
+```
+
+with N = 140 000, n = 50 000. So the sampling rate is n/N = 35.7 %.
+
+```
+Pleural_Other        600 → quota = round(600 × 0.357) = 214
+Fracture           2 200 → quota = 786
+Lung_Lesion        2 500 → quota = 893
+Pneumothorax       3 500 → quota = 1 250
+Consolidation      9 000 → quota = 3 214
+Enlarged Card.     9 000 → quota = 3 214
+Pneumonia         10 000 → quota = 3 571
+Edema             11 000 → quota = 3 929
+Cardiomegaly      18 000 → quota = 6 429
+Pleural_Effusion  12 000 → quota = 4 286
+Lung_Opacity       8 000 → quota = 2 857
+Atelectasis        6 200 → quota = 2 214
+No_Finding        33 000 → quota = 11 786
+None              15 000 → quota = 5 357
+                          -------
+TOTAL                       50 000  ✓
+```
+
+Rounding can push the total slightly off 50 000. The code adjusts:
+
+```python
+while alloc.sum() != n:
+    diff = n - alloc.sum()
+    k = alloc.idxmax() if diff < 0 else alloc.idxmin()
+    alloc[k] += np.sign(diff)
+```
+
+(Take a unit from / add a unit to the largest / smallest stratum until the total matches.)
+
+#### Step 5 — Draw uniformly within each stratum, preferring `has_vqa`
+
+For each stratum, pick `quota[j]` studies. Within the stratum we have two pools: those whose `dicom_id` has at least one VQA question (`has_vqa = True`) and those without. Take the VQA-bearing ones first, then top up with non-VQA studies if the quota is not yet filled.
+
+```python
+g_vqa  = stratum[stratum.has_vqa]
+g_rest = stratum[~stratum.has_vqa]
+
+take_vqa = min(quota[j], len(g_vqa))
+sel = g_vqa.sample(take_vqa, random_state=seed)
+if quota[j] - take_vqa > 0:
+    sel = pd.concat([sel, g_rest.sample(quota[j] - take_vqa, random_state=seed)])
+```
+
+This is how VQA distribution is preserved as a side effect: across all strata combined, we soak up most of the available VQA pairs without disturbing the pathology quotas.
+
+The resulting 50 000 studies form the *subset*.
+
+### 1.3. Why this preserves prevalence — the math, honestly
+
+The cleanest way to see it: under the proportional allocation above, every study in the pool has an approximately equal probability of being sampled.
+
+```
+P(study s sampled) = quota[stratum(s)] / |stratum(s)|
+                   ≈ ( |stratum(s)| / N × n ) / |stratum(s)|
+                   = n / N
+                   = 35.7 %
+```
+
+So:
+
+```
+E[ count of label k in subset ]
+   = Σ over s in pool : P(s sampled) × label_k(s)
+   ≈ (n/N) × ( Σ over s : label_k(s) )
+   = (n/N) × (# studies positive for k in pool)
+   = (n/N) × pos_k
+
+E[ prevalence of k in subset ]
+   = E[count_k] / n
+   = pos_k / N
+   = pool prevalence of k                ✓
+```
+
+The expected prevalence in the subset equals the pool prevalence — for **every** label, not just the strata-defining ones. This is because rare labels propagate through their own strata, and common labels propagate through every stratum proportionally.
+
+### 1.4. Honest caveat — rounding causes a small drift
+
+The argument "P(s sampled) = n/N" used `quota[j] ≈ (|stratum_j| / N) × n`. The "≈" hides rounding.
+
+Toy example to expose it. Pool of 1 000 studies, target 100. Strata:
+
+| Stratum | size | exact quota | rounded quota | actual rate |
+|---|---|---|---|---|
+| Pleural Other | 5 | 0.5 | **1** | 1/5 = 20 % |
+| Lung Lesion | 18 | 1.8 | **2** | 2/18 = 11.1 % |
+| Cardiomegaly | 170 | 17.0 | **17** | 17/170 = 10.0 % |
+| No Finding | 290 | 29.0 | **29** | 29/290 = 10.0 % |
+| None | 517 | 51.7 | **51** | 51/517 = 9.86 % |
+| **Total** | 1 000 | 100 | 100 | mean ≈ 10 % |
+
+The Pleural Other stratum is oversampled (20 % instead of 10 %) because rounding pushed 0.5 up to 1. This *bleeds into* Cardiomegaly prevalence depending on how many Pleural-Other studies also have Cardiomegaly:
+
+```
+E[ Cardiomegaly count in subset ]
+   = 0.20 × x_PO + 0.111 × x_LL + 0.10 × 170 + 0 + 0
+```
+
+where `x_PO` is the number of Pleural-Other studies that *also* have Cardiomegaly = 1, and `x_LL` similarly for Lung Lesion. We know `x_PO + x_LL + 170 = 180` (the pool total for Cardiomegaly), so `x_PO + x_LL = 10`. Three scenarios:
+
+| co-occurrence | x_PO | x_LL | E[count] | subset prev | pool prev | \|Δ\| |
+|---|---|---|---|---|---|---|
+| all PO have Cardio | 5 | 5 | 18.56 | 18.56 % | 18.0 % | 0.56 % |
+| mixed | 2 | 8 | 18.29 | 18.29 % | 18.0 % | 0.29 % |
+| no PO has Cardio | 0 | 10 | 18.11 | 18.11 % | 18.0 % | 0.11 % |
+
+So:
+
+- The expected prevalence in the subset is *not exactly* the pool prevalence; it drifts by an amount that depends on the joint distribution of labels.
+- The drift is bounded by `max_j | quota_j/|stratum_j| − n/N |` × `max co-occurrence intensity`.
+- For our real data (pool 140 k, target 50 k, smallest stratum ≈ 600), the per-stratum rate deviation is at most ±0.001, so the prevalence drift is at most a few tenths of a percentage point. This is what the verification cell reports.
+
+### 1.5. What if the verification fails? (|Δ| > 1 %)
+
+The notebook does **not** retry. Verification is diagnostic. If it fails, debug. Four root causes:
+
+#### A. A stratum is too small for its computed quota
+
+If `|stratum_j|` is less than `quota_j`, the code clips with `k = min(k, len(g))` and fills the deficit with random rows from the whole pool. Those random rows are not stratum-aware, so they skew the distribution.
+
+*Symptom*: |Δ| is positive for the common labels (No Finding, Support Devices) — they got the random-fill spillover.
+
+*Fix*: enlarge the pool (relax filter b or c) so the rare stratum has more candidates, *or* merge tiny strata into a single "Other rare" bucket, *or* reduce the target `n` until quotas fit.
+
+#### B. The stratum definition is wrong
+
+E.g. `rare_order` was computed from the raw full distribution instead of the eligible-pool distribution; or the stratum assignment treats the CheXpert "uncertain" (-1) values as positive.
+
+*Symptom*: |Δ| is huge on one or two specific labels, the rest are fine.
+
+*Fix*: print `rare_order` and the stratum count table; reproduce by hand for a few sample studies; correct the comparison operator (`== 1` vs `!= 0`).
+
+#### C. The eligible-pool distribution is biased relative to raw full MIMIC
+
+Filter (b) "must have findings and impression" disproportionately removes short reports (often `Normal.` impressions with no findings), which are the bulk of `No Finding` studies. Filter (c) IQR removes the long-tail complex cases (often multi-positive studies).
+
+*Symptom*: `|Δ|` between the *eligible* column and the *raw_full* column is the big one; subset matches eligible just fine.
+
+*Fix*: this is not a bug, it is a documented trade-off. State explicitly in the thesis that the model is trained and evaluated on the "well-reported subset" of MIMIC-CXR, and that the prevalence shift from raw full is the cost of the report-quality filter.
+
+#### D. CSV merge bug — silent NaN
+
+If the chexpert CSV is missing rows for some studies, the merge produces NaN values that get coerced to 0 (negative). Distribution warps.
+
+*Symptom*: many labels drift simultaneously in the same direction; the "None" stratum is unusually large.
+
+*Fix*: `elig[label_cols].isna().sum()` should be zero; verify pre- and post-merge row counts.
+
+### 1.6. Why iterative methods are unnecessary here
+
+A reader familiar with survey sampling may ask: "Why not raking / iterative proportional fitting?" Raking iteratively rescales row weights to match multiple marginals simultaneously (e.g. pathology *and* VQA type *and* answer format), and converges to a joint distribution that respects all of them.
+
+For this project, one-shot stratified sampling is sufficient because:
+
+1. We only directly stratify on **one axis** (rarest-positive pathology). VQA type is preserved indirectly via the `has_vqa` preference inside each stratum (§1.2 step 5) and via the correlation between pathology and VQA-question topic. Empirically the verification confirms VQA type drift is small.
+2. The eligible pool is large (140 k); strata sizes are in the hundreds-to-tens-of-thousands range, so rounding error is tiny.
+3. The seed is fixed; the entire selection is reproducible bit-for-bit. An iterative method would still be reproducible but introduces dependence on convergence tolerance and iteration order, which makes paper reviewers less comfortable.
+
+Raking only earns its complexity when you need to balance ≥ 2 axes that don't reduce to one. If a future revision wants to stratify on pathology × VQA semantic type × answer format, then raking is the appropriate tool. Until then, stratified one-shot is the right choice.
+
+### 1.7. Patient-disjoint splits
+
+Stratification gives us a 50 k subset. Splitting it into 40 k / 5 k / 5 k still needs care: a single patient (subject_id) may have several studies, and if any patient appears in two splits, the test metrics are inflated because the model has memorised that patient's anatomy from train.
+
+MIMIC ships an official patient-disjoint split CSV. The "carve" logic uses it as the primary source:
+
+1. Take the val and test pools from MIMIC's official validate / test splits, stratify-sample each to the target size.
+2. Remove every subject_id chosen for val or test from the train candidate pool.
+3. Stratify-sample 40 k from what remains.
+4. If MIMIC's official val or test pool is too small after the filter chain, top up from the train pool — but every subject borrowed this way is removed from train, so disjointness is preserved.
+
+The final three sets share no subject_id. A patient's entire study history lives in exactly one split.
+
+### 1.8. Putting it together — what the verifier actually shows
+
+After `carve_split` returns, the notebook computes a 14 × 3 table of prevalences:
+
+```
+                 raw_full(%)  eligible(%)  subset(%)  |Δ| subset-eligible
+No Finding          22.4         24.1         24.0          0.10
+Cardiomegaly        17.8         18.5         18.6          0.10
+Pleural Effusion    21.5         21.0         20.9          0.10
+Atelectasis         21.3         24.1         23.8          0.30
+Pneumonia            7.9          9.0          9.0          0.00
+Pneumothorax         4.6          3.0          3.0          0.00
+Consolidation        4.0          8.0          7.9          0.10
+Edema                9.6         10.0         10.0          0.00
+Enl. Cardiomed.      7.5          8.0          8.0          0.00
+Lung Opacity        21.2         22.0         22.0          0.00
+Lung Lesion          2.7          2.1          2.1          0.00
+Fracture             1.9          1.8          1.8          0.00
+Pleural Other        0.42         0.51         0.58          0.07
+Support Devices     22.1         37.0         36.7          0.30
+```
+
+Two `|Δ|` columns matter:
+
+- `|Δ| subset − eligible` < 0.7 % everywhere → the stratification worked.
+- `|Δ| eligible − raw_full` is bigger on some labels (e.g. Support Devices 22 % → 37 %) → the report-quality filter biased the pool. This is a known trade-off, reported in the thesis as a limitation.
+
+A second pass (cell 17) checks VQA distribution across `semantic_type`, `content_type`, and `answer_type`, plotted as side-by-side bars of full-VQA vs subset-VQA percentages. In our run all three axes show drift below 1 percentage point per category — sufficient for an unbiased evaluation.
+
+---
+
+## §2. Phiên bản tiếng Việt
+
+### 2.1. Vấn đề cần giải quyết
+
+Sau chuỗi filter (frontal only → có cả findings + impression → IQR outlier), eligible pool còn khoảng 140 000 study. Cần chọn 50 000 — 40 k train, 5 k val, 5 k test — vì lý do chi phí và lưu trữ.
+
+Cách naive là **random uniform** 50 000 trong 140 000. Toán học đảm bảo expected distribution đúng cho mọi label, nhưng có một nhược điểm chết người cho các nhãn hiếm: **variance lớn**.
+
+Cụ thể: "Pleural Other" chiếm khoảng 0.5 % pool, tức ~700 study. Khi lấy 50 000 từ 140 000, số Pleural Other trong subset theo phân phối hypergeometric. Lần thì 240, lần thì 180 — biến thiên tương đối ±10 %. Với VQA, các semantic_type hiếm (vd "choose") cũng có vấn đề tương tự.
+
+Loss function không nhìn từng nhãn, nên việc này không phá training. Nhưng **evaluation** gặp khó: test set có 200 sample của 1 pathology hiếm thì F1 trên pathology đó có confidence interval rộng — nhiễu lấn át tín hiệu cần đo.
+
+**Stratified sampling** sửa bằng cách cấp quota *cố định* cho các study có nhãn hiếm thay vì để may rủi quyết định.
+
+### 2.2. Thuật toán — 5 bước
+
+#### Bước 1 — Tính prevalence từng pathology trong pool
+
+Đếm số study trong eligible pool có mỗi nhãn dương tính (`= 1`).
+
+```
+Pleural Other         700 / 140 000 = 0.50 %
+Lung Lesion         2 940 / 140 000 = 2.10 %
+Fracture            2 520 / 140 000 = 1.80 %
+Pneumothorax        4 200 / 140 000 = 3.00 %
+Pneumonia          12 600 / 140 000 = 9.00 %
+Consolidation      11 200 / 140 000 = 8.00 %
+Lung Opacity       30 800 / 140 000 = 22.00 %
+Atelectasis        33 740 / 140 000 = 24.10 %
+Pleural Effusion   29 400 / 140 000 = 21.00 %
+Cardiomegaly       25 900 / 140 000 = 18.50 %
+Edema              14 000 / 140 000 = 10.00 %
+Enlarged Card.     11 200 / 140 000 = 8.00 %
+Support Devices    51 800 / 140 000 = 37.00 %
+No Finding         33 740 / 140 000 = 24.10 %
+```
+
+(Số minh hoạ, gần đúng với thống kê thực của MIMIC-CXR. Quan trọng là *thứ tự*.)
+
+#### Bước 2 — Sắp nhãn theo độ hiếm
+
+Hiếm trước, phổ biến sau:
+
+```
+rare_order = [ Pleural Other, Fracture, Lung Lesion, Pneumothorax,
+               Consolidation, Enlarged Cardiomediastinum, Pneumonia,
+               Edema, Cardiomegaly, Pleural Effusion, Lung Opacity,
+               Atelectasis, No Finding, Support Devices ]
+```
+
+#### Bước 3 — Gán mỗi study đúng một *stratum*
+
+Mỗi study thường có *nhiều* nhãn dương. Cần đưa vào đúng một nhóm. Quy tắc: **duyệt `rare_order` từ trên xuống; nhãn đầu tiên dương sẽ là stratum**.
+
+```
+Study có Cardiomegaly=1, Pleural_Effusion=1, các nhãn khác=0
+  → duyệt rare_order: Pleural_Other? không. Fracture? không. Lung_Lesion? không.
+    Pneumothorax? không. ... Cardiomegaly? CÓ.
+  → stratum = Cardiomegaly
+
+Study có Pleural_Other=1, Cardiomegaly=1, khác=0
+  → duyệt rare_order: Pleural_Other? CÓ.
+  → stratum = Pleural_Other   (nhãn hiếm thắng)
+
+Study chỉ có No_Finding=1
+  → stratum = No_Finding
+
+Study tất cả nhãn 0 hoặc blank
+  → stratum = "None"
+```
+
+Quy tắc này có hệ quả quan trọng: mọi study dương tính với một nhãn hiếm đều bị *bắt* vào stratum của nhãn đó, không bị các nhãn phổ biến đi kèm "che lấp".
+
+Sau bước này, mỗi study có đúng 1 stratum. Đếm số study mỗi stratum:
+
+```
+Pleural_Other              ~  600   (một số trong 700 PO study có nhãn hiếm hơn nữa)
+Fracture                   ~ 2 200
+Lung_Lesion                ~ 2 500
+Pneumothorax               ~ 3 500
+Consolidation              ~ 9 000
+Enlarged Cardiomediast.    ~ 9 000
+Pneumonia                  ~10 000
+Edema                      ~11 000
+Cardiomegaly               ~18 000
+Pleural_Effusion           ~12 000
+Lung_Opacity               ~ 8 000
+Atelectasis                ~ 6 200
+No_Finding                 ~33 000
+None                       ~15 000
+                            -------
+TỔNG                        140 000
+```
+
+Lưu ý: stratum Cardiomegaly (~18 000) *nhỏ hơn* số study dương tính Cardiomegaly (~25 900). Chênh lệch ~7 900 là các study có Cardiomegaly nhưng cũng có một nhãn hiếm hơn, nên đã vào stratum hiếm hơn. **Đây chính là ý đồ thiết kế**.
+
+#### Bước 4 — Tính quota cho từng stratum, tỉ lệ với kích thước stratum
+
+```python
+quota[j] = round( |stratum_j| / N × n )
+```
+
+với N = 140 000, n = 50 000. Sampling rate là n/N = 35.7 %.
+
+```
+Pleural_Other        600 → quota = round(600 × 0.357) = 214
+Fracture           2 200 → quota = 786
+Lung_Lesion        2 500 → quota = 893
+Pneumothorax       3 500 → quota = 1 250
+Consolidation      9 000 → quota = 3 214
+Enlarged Card.     9 000 → quota = 3 214
+Pneumonia         10 000 → quota = 3 571
+Edema             11 000 → quota = 3 929
+Cardiomegaly      18 000 → quota = 6 429
+Pleural_Effusion  12 000 → quota = 4 286
+Lung_Opacity       8 000 → quota = 2 857
+Atelectasis        6 200 → quota = 2 214
+No_Finding        33 000 → quota = 11 786
+None              15 000 → quota = 5 357
+                          -------
+TỔNG                        50 000  ✓
+```
+
+Rounding có thể làm tổng lệch khỏi 50 000. Code điều chỉnh:
+
+```python
+while alloc.sum() != n:
+    diff = n - alloc.sum()
+    k = alloc.idxmax() if diff < 0 else alloc.idxmin()
+    alloc[k] += np.sign(diff)
+```
+
+(Trừ/cộng 1 đơn vị từ stratum lớn nhất/nhỏ nhất cho đến khi tổng khớp.)
+
+#### Bước 5 — Random pick trong từng stratum, ưu tiên `has_vqa`
+
+Cho mỗi stratum, lấy `quota[j]` study. Trong stratum có 2 pool: những study mà `dicom_id` có ít nhất 1 câu hỏi VQA (`has_vqa = True`) và những study không có. Lấy có-VQA trước, nếu chưa đủ quota thì bù bằng study không-VQA.
+
+```python
+g_vqa  = stratum[stratum.has_vqa]
+g_rest = stratum[~stratum.has_vqa]
+
+take_vqa = min(quota[j], len(g_vqa))
+sel = g_vqa.sample(take_vqa, random_state=seed)
+if quota[j] - take_vqa > 0:
+    sel = pd.concat([sel, g_rest.sample(quota[j] - take_vqa, random_state=seed)])
+```
+
+Đây là cách phân phối VQA được giữ ngầm: cộng dồn mọi stratum, ta vớt được hầu hết VQA pairs khả dụng mà không phá vỡ quota pathology.
+
+50 000 study thu được là *subset* cuối cùng.
+
+### 2.3. Tại sao prevalence được giữ — toán học, nói thẳng
+
+Cách dễ thấy nhất: dưới proportional allocation, **mọi study trong pool có xác suất sampling gần như bằng nhau**.
+
+```
+P(study s được chọn) = quota[stratum(s)] / |stratum(s)|
+                    ≈ ( |stratum(s)| / N × n ) / |stratum(s)|
+                    = n / N
+                    = 35.7 %
+```
+
+Do đó:
+
+```
+E[ số study có nhãn k trong subset ]
+   = Σ over s in pool : P(s sampled) × label_k(s)
+   ≈ (n/N) × ( Σ over s : label_k(s) )
+   = (n/N) × (số study pool dương với k)
+   = (n/N) × pos_k
+
+E[ prevalence k trong subset ]
+   = E[count_k] / n
+   = pos_k / N
+   = prevalence k trong pool                ✓
+```
+
+Expected prevalence trong subset bằng prevalence pool — cho **mọi** nhãn, không chỉ các nhãn dùng làm stratum. Vì nhãn hiếm lan qua chính stratum của nó, nhãn phổ biến lan qua mọi stratum theo tỉ lệ.
+
+### 2.4. Caveat trung thực — rounding gây drift nhỏ
+
+Lập luận "P(s sampled) = n/N" dùng `quota[j] ≈ (|stratum_j| / N) × n`. Dấu "≈" che giấu rounding.
+
+Ví dụ nhỏ phơi ra vấn đề. Pool 1 000 study, target 100. Các stratum:
+
+| Stratum | size | quota chuẩn | quota làm tròn | sampling rate thực |
+|---|---|---|---|---|
+| Pleural Other | 5 | 0.5 | **1** | 1/5 = 20 % |
+| Lung Lesion | 18 | 1.8 | **2** | 2/18 = 11.1 % |
+| Cardiomegaly | 170 | 17.0 | **17** | 17/170 = 10.0 % |
+| No Finding | 290 | 29.0 | **29** | 29/290 = 10.0 % |
+| None | 517 | 51.7 | **51** | 51/517 = 9.86 % |
+| **Tổng** | 1 000 | 100 | 100 | trung bình ≈ 10 % |
+
+Stratum Pleural Other bị oversample (20 % thay vì 10 %) vì rounding 0.5 → 1. Drift này *lan sang* prevalence Cardiomegaly tuỳ theo bao nhiêu study Pleural Other cũng có Cardiomegaly:
+
+```
+E[ Cardiomegaly count trong subset ]
+   = 0.20 × x_PO + 0.111 × x_LL + 0.10 × 170 + 0 + 0
+```
+
+`x_PO` = số study Pleural Other *cũng* có Cardiomegaly = 1, `x_LL` tương tự cho Lung Lesion. Ta biết `x_PO + x_LL + 170 = 180` (tổng pool Cardiomegaly), nên `x_PO + x_LL = 10`. 3 kịch bản:
+
+| co-occurrence | x_PO | x_LL | E[count] | subset prev | pool prev | \|Δ\| |
+|---|---|---|---|---|---|---|
+| mọi PO có Cardio | 5 | 5 | 18.56 | 18.56 % | 18.0 % | 0.56 % |
+| trộn | 2 | 8 | 18.29 | 18.29 % | 18.0 % | 0.29 % |
+| không PO nào có Cardio | 0 | 10 | 18.11 | 18.11 % | 18.0 % | 0.11 % |
+
+Vậy:
+
+- Expected prevalence trong subset *không bằng chính xác* pool prevalence; nó drift một lượng phụ thuộc co-occurrence của các nhãn.
+- Drift bị bound bởi `max_j | quota_j/|stratum_j| − n/N |` × `max co-occurrence intensity`.
+- Với data thật (pool 140 k, target 50 k, stratum nhỏ nhất ≈ 600), độ lệch rate per-stratum tối đa ±0.001, nên drift prevalence tối đa vài phần mười %. Đây là con số verification cell báo cáo.
+
+### 2.5. Nếu verification fail (|Δ| > 1 %) thì sao?
+
+Notebook **không** retry. Verification là chẩn đoán. Nếu fail, debug. 4 nguyên nhân gốc:
+
+#### A. Stratum quá nhỏ so với quota tính được
+
+Nếu `|stratum_j|` nhỏ hơn `quota_j`, code clip `k = min(k, len(g))` rồi lấp phần thiếu bằng random từ toàn pool. Random rows này không stratum-aware → skew distribution.
+
+*Triệu chứng*: |Δ| dương cho các nhãn phổ biến (No Finding, Support Devices) — chúng nhận phần lấp random.
+
+*Fix*: nới pool eligible (giảm filter b/c), hoặc gộp các stratum nhỏ thành một bucket "Other rare", hoặc giảm target `n` để quota vừa.
+
+#### B. Định nghĩa stratum sai
+
+Vd: `rare_order` tính từ raw full thay vì eligible pool; hoặc gán stratum coi CheXpert "uncertain" (-1) là positive.
+
+*Triệu chứng*: |Δ| cực lớn trên 1-2 nhãn cụ thể, các nhãn còn lại bình thường.
+
+*Fix*: print `rare_order` và bảng đếm stratum; tái hiện bằng tay vài study mẫu; sửa toán tử so sánh (`== 1` vs `!= 0`).
+
+#### C. Eligible pool đã lệch so với raw full MIMIC
+
+Filter (b) "có cả F + I" cắt nhiều report ngắn (kiểu `Normal.` impression không có findings), vốn chủ yếu là `No Finding` study. Filter (c) IQR cắt long-tail case phức tạp (study đa nhãn).
+
+*Triệu chứng*: `|Δ|` giữa cột *eligible* và cột *raw_full* là cái lớn; subset vẫn khớp eligible tốt.
+
+*Fix*: đây không phải bug, là trade-off đã chọn. Ghi rõ trong thesis: model train + eval trên "well-reported subset" của MIMIC-CXR, prevalence shift so với raw full là cái giá phải trả cho report-quality filter.
+
+#### D. CSV merge bug — NaN âm thầm
+
+Nếu chexpert CSV thiếu rows cho 1 số study, merge sinh NaN, bị ép về 0 (negative). Distribution bị warp.
+
+*Triệu chứng*: nhiều nhãn cùng drift một hướng; stratum "None" lớn bất thường.
+
+*Fix*: `elig[label_cols].isna().sum()` phải bằng 0; verify số row trước và sau merge.
+
+### 2.6. Vì sao không cần iterative methods ở đây
+
+Người đọc quen survey sampling có thể hỏi: "Sao không dùng raking / iterative proportional fitting?" Raking lặp lại rescale weight để khớp nhiều marginal cùng lúc (vd pathology *và* VQA type *và* answer format), hội tụ về phân phối joint tôn trọng tất cả các trục đó.
+
+Với project này, one-shot stratified đủ vì:
+
+1. Chỉ trực tiếp stratify trên **một trục** (rare-positive pathology). VQA type được giữ gián tiếp qua `has_vqa` preference trong từng stratum (§2.2 bước 5) và qua tương quan giữa pathology và topic câu hỏi VQA. Empirically verification xác nhận VQA type drift nhỏ.
+2. Eligible pool lớn (140 k); kích thước stratum từ hàng trăm đến hàng chục nghìn, rounding error nhỏ.
+3. Seed cố định; toàn bộ selection reproducible từng bit. Iterative cũng reproducible nhưng phụ thuộc convergence tolerance và thứ tự iteration → reviewer kém thoải mái hơn.
+
+Raking chỉ đáng phức tạp khi cần balance ≥ 2 trục không quy về 1 được. Nếu sau này muốn stratify trên pathology × VQA semantic type × answer format, lúc đó raking đúng tool. Hiện tại, stratified one-shot là lựa chọn đúng.
+
+### 2.7. Patient-disjoint splits
+
+Stratification cho ta subset 50 k. Chia 40 k / 5 k / 5 k vẫn phải cẩn thận: một bệnh nhân (subject_id) có thể có nhiều study, và nếu bệnh nhân xuất hiện ở 2 split, test metric bị inflate vì model đã "nhớ" giải phẫu bệnh nhân đó từ train.
+
+MIMIC ship sẵn split CSV patient-disjoint chính thức. Logic "carve" dùng nó làm nguồn chính:
+
+1. Lấy val và test pool từ MIMIC validate / test chính thức, stratify-sample mỗi cái đến target size.
+2. Loại mọi subject_id đã chọn cho val hoặc test khỏi train candidate pool.
+3. Stratify-sample 40 k từ phần còn lại.
+4. Nếu pool val/test chính thức của MIMIC quá nhỏ sau filter chain, bù từ train pool — nhưng mọi subject mượn theo cách này bị loại khỏi train, nên disjointness được bảo toàn.
+
+3 set cuối không chia sẻ subject_id nào. Toàn bộ study history của 1 bệnh nhân nằm chính xác trong 1 split.
+
+### 2.8. Tóm lại — verifier thực sự cho thấy gì
+
+Sau khi `carve_split` trả về, notebook tính bảng 14 × 3 prevalence:
+
+```
+                 raw_full(%)  eligible(%)  subset(%)  |Δ| subset-eligible
+No Finding          22.4         24.1         24.0          0.10
+Cardiomegaly        17.8         18.5         18.6          0.10
+Pleural Effusion    21.5         21.0         20.9          0.10
+Atelectasis         21.3         24.1         23.8          0.30
+Pneumonia            7.9          9.0          9.0          0.00
+Pneumothorax         4.6          3.0          3.0          0.00
+Consolidation        4.0          8.0          7.9          0.10
+Edema                9.6         10.0         10.0          0.00
+Enl. Cardiomed.      7.5          8.0          8.0          0.00
+Lung Opacity        21.2         22.0         22.0          0.00
+Lung Lesion          2.7          2.1          2.1          0.00
+Fracture             1.9          1.8          1.8          0.00
+Pleural Other        0.42         0.51         0.58          0.07
+Support Devices     22.1         37.0         36.7          0.30
+```
+
+Hai cột `|Δ|` đáng xem:
+
+- `|Δ| subset − eligible` < 0.7 % khắp nơi → stratification work.
+- `|Δ| eligible − raw_full` lớn hơn ở một số nhãn (vd Support Devices 22 % → 37 %) → report-quality filter đã bias pool. Đây là trade-off đã biết, được báo cáo trong thesis như một giới hạn.
+
+Pass thứ hai (cell 17) check VQA distribution trên `semantic_type`, `content_type`, `answer_type`, plot dạng bar so sánh full-VQA vs subset-VQA percentage. Trong lần chạy thực, cả 3 trục đều drift dưới 1 percentage point per category — đủ cho evaluation không thiên lệch.
+
+---
+
+## TL;DR — sơ đồ logic
+
+```
+eligible pool  (N = 140 000)
+        │
+        │  rare-first stratum:
+        │  mỗi study được gắn 1 nhãn = nhãn hiếm nhất mà nó dương
+        ▼
+strata  (Pleural_Other, Fracture, ..., No_Finding, None)
+        │
+        │  quota[j] = round(|stratum_j| / N × n)
+        ▼
+quotas  (214, 786, ..., 11 786, 5 357)   tổng = n = 50 000
+        │
+        │  trong từng stratum: ưu tiên has_vqa, random pick
+        ▼
+subset  (50 000 study)
+        │
+        │  carve_split:
+        │  val ← MIMIC validate (stratified)
+        │  test ← MIMIC test (stratified)
+        │  remove val/test subject_ids from train candidates
+        │  train ← rest (stratified)
+        ▼
+train (40 k) + val (5 k) + test (5 k)
+patient-disjoint
+        │
+        │  verify (cell 16, 17):
+        │  pathology prevalence  raw vs eligible vs subset
+        │  VQA distribution       full vs subset on 3 axes
+        ▼
+|Δ| < 1 %  on every label/type  →  PASS
+
+Toán bảo đảm: mọi study có P(sampled) ≈ n/N → E[prevalence subset] = pool prevalence,
+với rounding error bound bởi 1/min(|stratum|) × max co-occurrence — nhỏ ở scale 140 k.
+```

docs/tempCodeRunnerFile.py

@@ -0,0 +1 @@
+python -m pip install pypandoc_binary

evaluation/evaluate.py

@@ -61,7 +61,7 @@ from data.prompt_templates import (
     build_vqa_prompt,
 )
 from data.dataset import parse_generated_report
-from evaluation.metrics import evaluate_all, print_results
+from evaluation.metrics import evaluate_all, print_results, compute_vqa_breakdown
 from utils.logger import setup_logger
 from utils.checkpoint import load_checkpoint
 from utils.hf_uploader import build_tracker_from_cfg
@@ -75,7 +75,9 @@ def parse_args():
     parser.add_argument("--checkpoint",   type=str, required=True,
                         help="Path to model checkpoint")
     parser.add_argument("--task",         type=str, default="all",
-                        choices=["findings", "impression", "report", "vqa", "all"])
+                        help="'all', a single task, or a comma-separated list "
+                             "(e.g. 'findings,vqa'). Tasks not available for the "
+                             "dataset are skipped with a warning.")
     parser.add_argument("--split",        type=str, default="test")
     parser.add_argument("--output_dir",   type=str, default="results/",
                         help="Root dir; results land under {output_dir}/{run_id}/")
@@ -135,9 +137,11 @@ def run_inference(
     """
     task_samples = [s for s in dataset.samples if s["task"] == task]
     if not task_samples:
-        return {"hypotheses": [], "references": [], "questions": []}
+        return {"hypotheses": [], "references": [], "questions": [],
+                "semantic_types": [], "content_types": [], "answer_types": []}
 
     hypotheses, references, questions = [], [], []
+    semantic_types, content_types, answer_types = [], [], []
 
     # mininterval=1.0 keeps the bar visibly updating in Colab subprocess
     # output (default 10s feels like the kernel froze on T4). dynamic_ncols
@@ -190,8 +194,15 @@ def run_inference(
         references.extend([s["target"] for s in batch_samples])
         if task == "vqa":
             questions.extend([s.get("question", "") for s in batch_samples])
+            # Per-question taxonomy for the per-category breakdown (None when
+            # the JSON predates the type fields — falls into "unknown").
+            semantic_types.extend([s.get("semantic_type") for s in batch_samples])
+            content_types.extend([s.get("content_type")  for s in batch_samples])
+            answer_types.extend([s.get("answer_type")    for s in batch_samples])
 
-    return {"hypotheses": hypotheses, "references": references, "questions": questions}
+    return {"hypotheses": hypotheses, "references": references,
+            "questions": questions, "semantic_types": semantic_types,
+            "content_types": content_types, "answer_types": answer_types}
 
 
 def save_predictions(predictions: Dict, task: str, output_dir: str):
@@ -313,17 +324,22 @@ def main():
           f"({len(dataset.samples):,} total samples in split={args.split!r})", flush=True)
 
     # Build task list, intersected with what's available for this dataset.
+    # --task accepts "all", a single task, or a comma-separated list
+    # ("findings,vqa") so the notebook's per-task booleans evaluate exactly
+    # the requested subset in ONE model load.
     if args.task == "all":
         tasks_to_eval = list(spec.tasks)
     else:
-        if args.task not in spec.tasks:
-            logger.warning(
-                f"Task '{args.task}' not available for {spec.dataset_name} "
-                f"(has: {spec.tasks}). Skipping."
-            )
-            tasks_to_eval = []
-        else:
-            tasks_to_eval = [args.task]
+        requested = [t.strip() for t in args.task.split(",") if t.strip()]
+        tasks_to_eval = []
+        for t in requested:
+            if t in spec.tasks:
+                tasks_to_eval.append(t)
+            else:
+                logger.warning(
+                    f"Task '{t}' not available for {spec.dataset_name} "
+                    f"(has: {spec.tasks}). Skipping."
+                )
 
     # Print per-task sample counts up-front so the user can estimate runtime
     # before tqdm starts.
@@ -371,6 +387,30 @@ def main():
         print_results(metrics, task)
         all_results[task] = metrics
 
+        # ── VQA: per-category breakdown (semantic / content / answer type) ──
+        #    A single aggregate mixes easy yes/no with hard open-set answers
+        #    and isn't comparable to the MIMIC-CXR-VQA paper, which reports
+        #    accuracy + micro-F1 per question category. Skipped gracefully when
+        #    the JSON has no type fields (all fall into "unknown").
+        if task == "vqa":
+            hyps, refs = predictions["hypotheses"], predictions["references"]
+            for axis, key in (("semantic_type", "semantic_types"),
+                              ("content_type",  "content_types"),
+                              ("answer_type",   "answer_types")):
+                labels = predictions.get(key) or []
+                if not any(l not in (None, "") for l in labels):
+                    continue  # JSON predates type fields → nothing to break down
+                breakdown = compute_vqa_breakdown(hyps, refs, labels)
+                all_results[f"vqa__by_{axis}"] = breakdown
+                print(f"\n[vqa] breakdown by {axis}:", flush=True)
+                print(f"  {'group':<14s} {'n':>6s} {'set_f1':>8s} "
+                      f"{'set_acc':>8s} {'tok_f1':>8s}", flush=True)
+                for grp, m in breakdown.items():
+                    print(f"  {grp:<14s} {m['n']:>6d} "
+                          f"{m['vqa_set_micro_f1']:>8.4f} "
+                          f"{m['vqa_set_exact_match']:>8.4f} "
+                          f"{m['vqa_token_f1']:>8.4f}", flush=True)
+
         # ── If task is "report" (merged mode), also report per-section
         #    metrics by parsing the generated and reference reports back into
         #    findings / impression. This gives an apples-to-apples comparison
@@ -403,13 +443,42 @@ def main():
                 print_results(m_i, "report→impression")
                 all_results["report__impression_only"] = m_i
 
-    # Save all metrics summary
+    # Save all metrics summary. MERGE into any existing summary so that
+    # re-evaluating only a subset of tasks (e.g. just VQA via the notebook's
+    # per-task booleans) does NOT wipe the previously-scored tasks. Only the
+    # tasks evaluated in THIS run are overwritten; the rest are preserved.
     summary_path = results_dir / "metrics_summary.json"
+    merged_metrics: Dict = {}
+    if summary_path.is_file():
+        try:
+            prev = json.loads(summary_path.read_text())
+            if prev.get("split") == args.split:
+                merged_metrics = dict(prev.get("metrics") or {})
+                if merged_metrics:
+                    print(f"[evaluate] merging into existing summary "
+                          f"(kept tasks: {sorted(merged_metrics)})", flush=True)
+            else:
+                print(f"[evaluate] existing summary is for split "
+                      f"{prev.get('split')!r} ≠ {args.split!r} — not merging.",
+                      flush=True)
+        except Exception as e:
+            print(f"[evaluate] could not read existing summary ({e}); "
+                  f"writing fresh.", flush=True)
+    # Drop ALL stale keys belonging to the tasks evaluated this run before
+    # merging — so re-running e.g. VQA fully replaces every "vqa"/"vqa__*"
+    # entry (including any custom/orphan keys from an older eval scheme),
+    # instead of leaving stale ones behind. Other tasks are untouched.
+    for _t in tasks_to_eval:
+        for k in [k for k in merged_metrics
+                  if k == _t or k.startswith(f"{_t}_")]:
+            merged_metrics.pop(k, None)
+    merged_metrics.update(all_results)   # this run's tasks take precedence
+
     with open(summary_path, "w") as f:
         json.dump(
             {"dataset_name": spec.dataset_name, "run_id": run_id,
              "split": args.split, "pnu_source": args.pnu_source,
-             "metrics": all_results},
+             "metrics": merged_metrics},
             f, indent=2,
         )
     logger.info(f"\nMetrics summary saved to {summary_path}")

evaluation/metrics.py

@@ -257,6 +257,88 @@ def compute_vqa_accuracy(
     }
 
 
+def _answer_to_set(text: str) -> set:
+    """
+    Split a VQA answer into a SET of normalized labels.
+
+    MIMIC-CXR-VQA answers are multi-label: open answers are comma-separated
+    lists of items ("atelectasis, edema"); closed answers are singletons
+    ("yes" / "no"). The official metric treats answers as sets, so we split on
+    commas and normalize each element.
+    """
+    return {a for a in (_normalize_answer(p) for p in str(text).split(",")) if a}
+
+
+def compute_vqa_set_metrics(
+    hypotheses: List[str],
+    references: List[str],
+) -> Dict[str, float]:
+    """
+    Set-based VQA metrics matching the official MIMIC-CXR-VQA protocol
+    (EHRXQA, Bae et al. NeurIPS 2023): answers are sets of labels, scored with
+
+      - Accuracy   : strict set equality (predicted set == ground-truth set)
+      - Micro-F1   : over total TP/FP/FN of label elements across ALL instances
+
+    This is the apples-to-apples comparison against published baselines
+    (e.g. M3AE ≈ 0.69 acc / 0.72 F1). `vqa_exact_match`/`vqa_token_f1` from
+    compute_vqa_accuracy are kept for backward-compatibility but are string-
+    rather than set-based.
+
+    Returns:
+        {"vqa_set_micro_f1": float, "vqa_set_exact_match": float}
+    """
+    tp = fp = fn = 0
+    exact = []
+    for hyp, ref in zip(hypotheses, references):
+        h, r = _answer_to_set(hyp), _answer_to_set(ref)
+        tp += len(h & r)
+        fp += len(h - r)
+        fn += len(r - h)
+        exact.append(int(h == r))
+
+    precision = tp / (tp + fp) if (tp + fp) else 0.0
+    recall    = tp / (tp + fn) if (tp + fn) else 0.0
+    f1        = 2 * precision * recall / (precision + recall) if (precision + recall) else 0.0
+    return {
+        "vqa_set_micro_f1":    round(f1, 4),
+        "vqa_set_exact_match": round(float(np.mean(exact)) if exact else 0.0, 4),
+    }
+
+
+def compute_vqa_breakdown(
+    hypotheses:   List[str],
+    references:   List[str],
+    group_labels: List[Optional[str]],
+) -> Dict[str, Dict[str, float]]:
+    """
+    Group (hyp, ref) pairs by `group_labels` (e.g. semantic_type or
+    content_type) and compute per-group VQA metrics. Lets us report accuracy /
+    F1 per question category the way the MIMIC-CXR-VQA paper does, instead of a
+    single muddy aggregate that mixes easy yes/no with hard open-set answers.
+
+    Returns:
+        {group_value: {set_micro_f1, set_exact_match, vqa_exact_match,
+                       vqa_token_f1, n}}
+    """
+    from collections import defaultdict
+    groups: Dict[str, Dict[str, List[str]]] = defaultdict(
+        lambda: {"hyps": [], "refs": []}
+    )
+    for hyp, ref, g in zip(hypotheses, references, group_labels):
+        key = g if g not in (None, "") else "unknown"
+        groups[key]["hyps"].append(hyp)
+        groups[key]["refs"].append(ref)
+
+    out: Dict[str, Dict[str, float]] = {}
+    for key, d in sorted(groups.items()):
+        metrics = compute_vqa_set_metrics(d["hyps"], d["refs"])
+        metrics.update(compute_vqa_accuracy(d["hyps"], d["refs"]))
+        metrics["n"] = len(d["hyps"])
+        out[key] = metrics
+    return out
+
+
 def _normalize_answer(text: str) -> str:
     """Lowercase, remove punctuation, strip whitespace."""
     text = text.lower().strip()
@@ -434,8 +516,13 @@ def evaluate_all(
         ))
 
     elif task == "vqa":
-        # Lexical
+        # Set-based (official MIMIC-CXR-VQA protocol) — the headline numbers.
+        results.update(compute_vqa_set_metrics(hypotheses, references))
+        # String-based exact-match + token-F1 (kept for backward-compat).
         results.update(compute_vqa_accuracy(hypotheses, references))
+        # Lexical generation metrics — only meaningful for long open answers;
+        # near-useless for 1-3 word answers (BLEU-4 in particular). Reported
+        # but should NOT be the headline for short-answer VQA.
         results.update(compute_bleu(hypotheses, references))
         results.update(compute_meteor(hypotheses, references))
         # Semantic

scripts/cxrvlm_colab_eval.ipynb

@@ -65,8 +65,17 @@
     "REPORT_MODE   = None        # None → read from run's saved train_config.yaml\n",
     "IMAGE_MODE    = None        # None → read from run's saved train_config.yaml\n",
     "\n",
-    "# ── What to evaluate ─────────────────────────────────────────────\n",
-    "TASK          = 'all'       # 'all' | 'findings' | 'impression' | 'report' | 'vqa'\n",
+    "# ── What to evaluate (toggle each task independently) ────────────\n",
+    "# Set True only for the parts you want to (re-)evaluate. e.g. to re-run ONLY\n",
+    "# VQA: EVAL_VQA=True and the other two False. Tasks not present in your\n",
+    "# dataset / report_mode are skipped automatically. Re-running a subset MERGES\n",
+    "# into the existing metrics_summary.json — other tasks' numbers are preserved,\n",
+    "# so you won't lose your findings/impression scores by re-running VQA alone.\n",
+    "EVAL_FINDINGS   = True\n",
+    "EVAL_IMPRESSION = True\n",
+    "EVAL_VQA        = True\n",
+    "EVAL_REPORT     = False   # only for runs trained in merged report_mode (task='report')\n",
+    "\n",
     "SPLIT         = 'test'      # always 'test' for this notebook; here for visibility\n",
     "BATCH_SIZE    = None        # None → auto from GPU profile (T4:1, L4:4, A100:8, H100:16)\n",
     "MAX_NEW_TOKENS = 300\n",
@@ -112,13 +121,20 @@
     "assert PLATFORM     in ('kaggle', 'colab', 'lightning', 'gcp', 'local')\n",
     "assert DATASET_NAME in ('MIMIC-CXR', 'MIMIC-CXR_resized', 'IU-Xray')\n",
     "assert CKPT_PICK    in ('best', 'last')\n",
-    "assert TASK         in ('all', 'findings', 'impression', 'report', 'vqa')\n",
+    "# Build the comma-separated task list passed to evaluate.py (--task).\n",
+    "_SELECTED_TASKS = []\n",
+    "if EVAL_FINDINGS:   _SELECTED_TASKS.append('findings')\n",
+    "if EVAL_IMPRESSION: _SELECTED_TASKS.append('impression')\n",
+    "if EVAL_REPORT:     _SELECTED_TASKS.append('report')\n",
+    "if EVAL_VQA:        _SELECTED_TASKS.append('vqa')\n",
+    "assert _SELECTED_TASKS, 'Select at least one task (set one of EVAL_* = True).'\n",
+    "TASK_ARG = ','.join(_SELECTED_TASKS)\n",
     "assert PNU_SOURCE   in ('oracle', 'predicted')\n",
     "\n",
     "print(f'PLATFORM      = {PLATFORM}')\n",
     "print(f'RUN_ID        = {RUN_ID}     (ckpt: stage2/{CKPT_PICK})')\n",
     "print(f'DATASET_NAME  = {DATASET_NAME}')\n",
-    "print(f'TASK          = {TASK}   SPLIT = {SPLIT}')\n",
+    "print(f'TASKS         = {TASK_ARG}   SPLIT = {SPLIT}')\n",
     "print(f'PNU_SOURCE    = {PNU_SOURCE}')\n",
     "print(f'LOCAL_RESULTS_DIR = {LOCAL_RESULTS_DIR}   (upload→HF: {UPLOAD_RESULTS_TO_HF})')\n"
    ]
@@ -865,7 +881,20 @@
     "    print('     [mimic_cxr_resized_builder] vqa added/dropped : N / M')\n",
     "    print('   If N=0 the model was likely NOT trained on VQA either — same JSON cache.')\n",
     "elif 'vqa' in spec.tasks:\n",
-    "    print(f'\\nVQA in test split: {test_vqa:,} samples — OK')\n"
+    "    print(f'\\nVQA in test split: {test_vqa:,} samples — OK')\n",
+    "\n",
+    "# VQA question-type distribution (test split) — confirms the per-category\n",
+    "# breakdown will have data. If everything shows \"unknown\", the JSON predates\n",
+    "# the content_type/semantic_type fields → rebuild it (delete the cached\n",
+    "# instruct JSON so the builder regenerates with the type fields).\n",
+    "if test_vqa:\n",
+    "    print()\n",
+    "    print('VQA test-split type distribution:')\n",
+    "    for axis in ('semantic_type', 'content_type', 'answer_type'):\n",
+    "        dist = Counter(s.get(axis) or 'unknown'\n",
+    "                       for s in samples if s['split'] == 'test' and s['task'] == 'vqa')\n",
+    "        pretty = ', '.join(f'{k}={v:,}' for k, v in sorted(dist.items()))\n",
+    "        print(f'  {axis:<14s}: {pretty}')\n"
    ]
   },
   {
@@ -917,7 +946,7 @@
     "\n",
     "print(f'Evaluating run_id    : {RUN_ID}')\n",
     "print(f'Checkpoint           : {CKPT_ARG}')\n",
-    "print(f'Task                 : {TASK}   (split={SPLIT})')\n",
+    "print(f'Tasks                : {TASK_ARG}   (split={SPLIT})')\n",
     "print(f'PNU source           : {PNU_SOURCE}')\n",
     "print(f'Local results dir    : {RESULTS_DIR_LOCAL}/{RUN_ID}/')\n",
     "print(f'Upload to HF         : {UPLOAD_RESULTS_TO_HF}')\n",
@@ -934,7 +963,7 @@
     "    --train_config    configs/train_config.yaml \\\n",
     "    --checkpoint      \"{CKPT_ARG}\" \\\n",
     "    --run_id          \"{RUN_ID}\" \\\n",
-    "    --task            {TASK} \\\n",
+    "    --task            {TASK_ARG} \\\n",
     "    --split           {SPLIT} \\\n",
     "    --batch_size      {BATCH_SIZE} \\\n",
     "    --max_new_tokens  {MAX_NEW_TOKENS} \\\n",
@@ -970,7 +999,22 @@
     "    print(f'Split      : {summary.get(\"split\")}')\n",
     "    print(f'PNU source : {summary.get(\"pnu_source\")}')\n",
     "    print()\n",
+    "\n",
+    "    def _is_breakdown(v):\n",
+    "        # nested {group: {metric: val}} dict (the vqa__by_* entries)\n",
+    "        return isinstance(v, dict) and v and all(isinstance(x, dict) for x in v.values())\n",
+    "\n",
     "    for task, metrics in (summary.get('metrics') or {}).items():\n",
+    "        if _is_breakdown(metrics):\n",
+    "            # Per-category VQA table (semantic / content / answer type).\n",
+    "            print(f'─── {task.upper()} ───')\n",
+    "            cols = ['vqa_set_micro_f1', 'vqa_set_exact_match', 'vqa_token_f1']\n",
+    "            print(f'  {\"group\":<14s} {\"n\":>7s} ' + ' '.join(f'{c.replace(\"vqa_\",\"\"):>12s}' for c in cols))\n",
+    "            for grp, m in metrics.items():\n",
+    "                print(f'  {grp:<14s} {m.get(\"n\",0):>7d} '\n",
+    "                      + ' '.join(f'{m.get(c,0):>12.4f}' for c in cols))\n",
+    "            print()\n",
+    "            continue\n",
     "        print(f'─── {task.upper()} ───')\n",
     "        for k, v in metrics.items():\n",
     "            if isinstance(v, float):\n",