Update README.md

README.md

@@ -2,55 +2,64 @@
 license: mit
 tags:
   - medical-imaging
-  - self-supervised-learning
+  - radiomics
   - ct
   - opscc
-  - hpv-status
-  - radiology
-  - multi-institutional
+  - head-and-neck
+  - feature-extraction
+  - explainable-ai
 language: en
-library_name: pytorch
+library_name: numpy
 ---
 
-# AsymmetryNet
+# AsymmetryNet: Asymmetry Attention Mechanism (AAM)
 
-Segmentation-free framework for predicting HPV status in oropharyngeal
-squamous cell carcinoma (OPSCC) from contrast-enhanced neck CT, using a
-radiologist-inspired Asymmetry Attention Mechanism (AAM).
+Segmentation-free feature extraction for radiologist-inspired left-right
+asymmetry in head and neck CT, developed for HPV status prediction in
+oropharyngeal squamous cell carcinoma (OPSCC).
 
-## Overview
+## What this code does
 
-AsymmetryNet combines three feature streams, none requiring manual or
-automated tumor segmentation:
+Given a cropped neck CT volume (NIfTI), this pipeline computes three
+per-slice asymmetry channels across the full volume in a single pass:
 
-- **AAM (24 features)**: airway effacement, nodal/soft-tissue asymmetry,
-  and necrosis, computed via spine-anchored midline detection and
-  mirrored left-right comparison.
-- **MIRP radiomics (185 features)**: first-order, morphological, and
-  texture features extracted within AAM-defined regions.
-- **Imaging encoders**: four candidate backbones compared head-to-head,
-  DINOv2, SwinUNETR, SuPreM, and 3D ResNet18.
+1. **Ch1 — Airway lesion**: seeded region growing from the airway lumen,
+   bounded by Sobel-detected soft-tissue edges, constrained to the side
+   of airway deviation from a spine-anchored midline.
+2. **Ch2 — Nodal/soft-tissue asymmetry**: mirrored left-right comparison
+   of fat-plane and soft-tissue density about the same midline.
+3. **Ch3 — Necrosis**: per-case, histogram-derived HU-windowed fluid
+   detection, restricted to the union of the Ch1 and Ch2 regions.
 
-Evaluated on a pooled multi-institutional cohort (n=1,359; HECKTOR, TCIA
-OPC-Radiomics, MICCAI/MD Anderson, and an MGB institutional cohort) using
-both a stratified pooled holdout and leave-one-institution-out (LOIO)
-cross-validation.
+Midline is detected per case via spine-anchored bone-mass/compactness
+scoring, not image center or a fixed landmark.
 
-## Repository contents
+## Outputs (per case)
 
-- `train_mae_swin3d.py` — **deprecated**, from an earlier iteration of
-  this project (custom 3D MAE-Swin SSL pretraining). Retained for
-  provenance; not used in the current manuscript's pipeline.
-- [additional current pipeline scripts to be added — see note below]
+- A QC plot (5 representative slices x 5 panels: CT+midline+spine,
+  Sobel-cleaned edge map, and the three asymmetry channels).
+- A 4D heatmap NIfTI (`D x H x W x 3`, channels = [airway_lesion, nodal,
+  necrosis]) for downstream radiomic feature extraction (e.g., MIRP)
+  restricted to these asymmetry-defined regions.
+- A row of ~40 rich per-case features (areas, extents, laterality
+  ratios, 3D weighted centroids per channel) appended to a CSV.
+
+## Usage
+
+Set `BASE`, `CROP_DIR`, and `MASTER` at the top of the script to your
+own paths. Input volumes are expected as normalized (0-1) or raw-HU
+NIfTI crops at `{CROP_DIR}/{dataset}/{case_id}/crop224.nii.gz`; the
+master index CSV needs `case_id`, `dataset`, `extracted` (bool), and
+optionally `hpv_norm` columns.
+
+Parallelized via `ProcessPoolExecutor` and resumable: interrupting and
+restarting skips cases already written to the output CSV.
 
 ## Citation
 
-If you use this work, please cite:
+If you use this code, please cite:
 [full citation once accepted/published]
 
-## Data availability
+## License
 
-Institutional (MGB) data are proprietary and not redistributable. Public
-sources (HECKTOR, TCIA OPC-Radiomics, MICCAI/Kaggle) are available from
-their original repositories under their respective data use terms; see
-the manuscript's Data Availability statement for details.
+MIT