---
license: mit
tags:
  - medical-imaging
  - radiomics
  - ct
  - opscc
  - head-and-neck
  - feature-extraction
  - explainable-ai
language: en
library_name: numpy
---

# AsymmetryNet: 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).

## What this code does

Given a cropped neck CT volume (NIfTI), this pipeline computes three
per-slice asymmetry channels across the full volume in a single pass:

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.

Midline is detected per case via spine-anchored bone-mass/compactness
scoring, not image center or a fixed landmark.

## Outputs (per case)

- 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 code, please cite:
[full citation once accepted/published]

## License

MIT