# AdipoNeuroMap

**Ex vivo 3D adipose-depot quantification** — sympathetic innervation, adipocyte
size, and crown-like structures (CLS) in cleared (light-sheet / confocal) fat
volumes.

- **Domain**: Obesity (비만)
- **Category**: Animal-experiment tool (ex vivo 3D image quantification)
- **One-liner**: From a transparent fat-depot volume (iWAT / eWAT / BAT),
  quantify the TH⁺ sympathetic nerve network plus adipocytes and CLS in 3D.

> ⚠️ **Medical disclaimer — Research / reference use only.**
> AdipoNeuroMap is a research and reference tool for preclinical
> (animal-model) image analysis. It is **NOT a clinical diagnostic or
> decision-making tool** and must not be used for patient diagnosis or
> treatment. The built-in demo volumes are **procedurally generated synthetic
> data** and do not represent any real animal or patient.

---

## Core features

1. **TH⁺ sympathetic axon network** — 3D segmentation + skeletonization →
   axon density (mm of axon / mm³), branch-point density, mean segment length,
   total length.
2. **Adipocyte 3D size distribution** — interior (membrane / perilipin channel)
   segmentation → equivalent-sphere diameter histogram, mean / median, and
   size-class breakdown (small / medium / large / hypertrophic).
3. **Crown-like structures (CLS)** — detection of F4/80⁺ macrophage rings
   around adipocytes → CLS count, density (/mm³), and a Clarke–Evans
   nearest-neighbour **clustering index** (clustered vs random vs dispersed).
4. **Neuro–adipocyte proximity** — fraction of adipocytes whose centroid lies
   within a contact radius (default 25 µm) of a TH⁺ axon (innervation proxy).
5. **Autofluorescence suppression + synthetic demo** — top-hat-style background
   suppression preprocessing, and a procedural demo generator (branching
   sympathetic tree + packed adipocytes + CLS clusters) that differs per depot.

---

## Requirements

- **Hard dependency**: `numpy` only.
- **Optional (auto-detected, graceful fallback)**: `scipy` (faster/accurate
  labeling, distance transforms, morphology), `scikit-image` (`skeletonize_3d`,
  watershed-style segmentation), `skan` (exact skeleton-graph metrics),
  `tifffile` (read user TIFF stacks).

If `scipy` / `scikit-image` are missing, the tool automatically uses pure-numpy
fallbacks (connected-component flood fill, distance-ridge skeleton, 26-neighbour
degree analysis). `python3 main.py` always runs; quality is highest with scipy
present.

**No network access is ever used.**

---

## Usage

```bash
python3 main.py                      # demo: generate iWAT, eWAT, BAT and compare
python3 main.py --depot eWAT         # single depot, full report + histogram
python3 main.py --summary            # compact comparison table only
python3 main.py --top 5              # also list the 5 largest adipocyte diameters
python3 main.py --depot BAT --quiet  # suppress per-step demo logging
python3 main.py --input stack.tif    # analyze a user TIFF stack (needs tifffile)
python3 main.py --help               # full option list
```

### Options

| Option | Description |
|--------|-------------|
| `--depot {iWAT,eWAT,BAT}` | Analyze a single depot (default: compare all three). |
| `--demo` | Use the built-in synthetic volume (default behaviour). |
| `--input PATH` | Path to a user TIFF stack (`tifffile` optional; falls back to demo if absent/unreadable). |
| `--summary` | Print only the compact comparison table. |
| `--top N` | Also list the N largest adipocyte diameters. |
| `--seed N` | Random seed for the synthetic demo (default 42). |
| `--size N` | Demo volume scale hint (advanced; 0 = default 60×120×120). |
| `--quiet` | Suppress per-step demo logging. |

### User TIFF input

`--input` expects a 3D `(Z,Y,X)` or 4D `(C,Z,Y,X)` / `(Z,Y,X,C)` stack. Channel
order is assumed **TH⁺ (axon), membrane/perilipin (adipocyte), F4/80⁺
(macrophage)**. A single-channel stack is analyzed for axon metrics (adipocyte /
CLS metrics are then approximate). Voxel size defaults to 5 µm — edit
`DEMO_VOXEL_UM` / pass real spacing in code for absolute units.

---

## Files

```
2026-06-01-2-adiponeuromap/
├── main.py                       # Python CLI entry point
├── README.md                     # this file
├── QA.md                         # verification log
└── data/
    ├── reference_params.json     # adipocyte size classes, axon-density ranges,
    │                             # CLS definition, proximity radius, AF params
    └── depot_profiles.csv        # per-depot reference profile (BAT/iWAT/eWAT)
```

---

## Verification checklist

- [ ] `python3 -c "import ast; ast.parse(open('main.py').read())"` — syntax OK
- [ ] `python3 main.py --help` — prints usage
- [ ] `python3 main.py --summary` — prints depot comparison table
- [ ] `python3 main.py --depot eWAT --top 4` — full single-depot report
- [ ] Reference data files load (`data/reference_params.json`,
      `data/depot_profiles.csv`)
- [ ] Numpy-only fallback (scipy / skimage absent) still exits 0
- [ ] Disclaimer printed in CLI banner and footer

See `QA.md` for the recorded run log.

---

## Reference biology (interpretation)

The depot gradients the demo reproduces follow well-described adipose biology:

- **BAT** (interscapular brown): dense TH⁺ sympathetic innervation, small
  multilocular adipocytes, low CLS — thermogenic.
- **iWAT** (inguinal subcutaneous white): intermediate innervation, beiging-
  responsive, moderate adipocyte size.
- **eWAT** (epididymal visceral white): sparse innervation, hypertrophic
  adipocytes, high CLS density (focal inflammation) — a pro-inflammatory
  signature associated with obesity / insulin resistance.

Reference ranges in `data/reference_params.json` are order-of-magnitude guidance
compiled from adipose-clearing / imaging literature, intended for calibrating
the synthetic demo — **not** clinical thresholds.

---

## Sources / methods

- Adipose tissue optical clearing & whole-mount 3D imaging of sympathetic
  innervation (TH⁺) and adipocytes (perilipin / membrane), light-sheet/confocal.
- Crown-like structure (F4/80⁺ macrophage ring) definition as a marker of
  adipose inflammation.
- Clarke–Evans nearest-neighbour index for point-pattern clustering.
- `scikit-image` `skeletonize_3d` and morphology; `skan` skeleton-graph
  summaries (both optional; numpy fallbacks provided).

Guideline context for the broader metabolic workspace: KDA 2023, ADA 2025,
AASLD MASLD 2023, EASL-EASD-EASO MASLD 2024 (not directly used here — this is a
preclinical imaging tool).