# HepatoFabric3D — 3D liver fibrosis network topology & zonation quantifier

> **RESEARCH / EDUCATIONAL USE ONLY — NOT a clinical diagnosis or
> decision-making tool.** Connectivity thresholds and stage mappings are
> illustrative defaults for the built-in procedural synthetic generator and are
> **not** validated against histology. Do not use for patient care.

## Purpose

In MASLD/MASH research, fibrosis is routinely scored on **2D** sections as a
collagen **area fraction (%)**. But two samples with the *same* collagen area%
can have radically different **3D network architecture**: isolated periportal
collagen (no spanning septa) versus a connected bridging network linking portal
tracts and central veins. That 3D **connectivity / bridging topology** is what
distinguishes early fibrosis from bridging fibrosis (F3) and cirrhosis (F4) — and
2D histomorphometry largely misses it.

HepatoFabric3D quantifies, from a cleared/confocal/SHG liver-lobe **volume**:

1. **Collagen 3D segmentation → skeleton → graph** — connected components,
   skeleton branch/end points, and a **connectivity index** (bridging septa per
   portal node, weighted by mean septum completeness).
2. **Portal–central axis classification** — bridging septa labeled as
   **portal–portal (PP)** vs **portal–central (PC)**, with a node graph
   (components, largest component, max degree, circuit rank / cycles).
3. **Ductular reaction (CK19⁺ biliary)** — 3D branching: components, branch
   points, branches-per-component.
4. **Steatosis zonation gradient** — periportal (zone 1) vs pericentral (zone 3)
   droplet density, with a signed zonation gradient.
5. **"Same 2D area%, different 3D connectivity" comparison report** — an
   F1→F4 synthetic series where collagen area% rises gradually but connectivity
   and bridging septa diverge, plus an automatically selected key-insight pair.

## Domain & category

- **Domain:** MASLD (metabolic dysfunction-associated steatotic liver disease) / MASH.
- **Category:** animal-experiment tool — *ex vivo* 3D image quantification.

## Core features (recap)

| # | Feature | Output |
|---|---------|--------|
| ① | Collagen 3D segmentation + skeleton + graph | components, skeleton voxels, branch/end points, **connectivity index** + band |
| ② | Portal–central axis bridging classification | PP / PC septa counts, mean completeness, node-graph topology |
| ③ | Ductular reaction 3D branching | components, branch points, branches/component |
| ④ | Steatosis zonation gradient | periportal vs pericentral droplet fraction, signed gradient + direction |
| ⑤ | "2D area% same, 3D connectivity differs" report | comparison table + auto key-insight pair |

## Requirements

- **Required:** Python 3.8+, `numpy`.
- **Optional (graceful fallback — `python3 main.py` always runs):**
  - `scipy` → labeling / distance transform / smoothing (else pure-numpy union-find + BFS-distance fallback)
  - `scikit-image` → true 3D skeletonization (else distance-map medial-axis fallback)
  - `networkx` → graph topology (else manual union-find graph summary)
  - `tifffile` → required only for `--input` (user TIFF stacks)

No network access, no paid APIs, no GPU dependency. The default run is fully
synthetic and offline.

## Run

```bash
# Default: generate synthetic F1–F4 volumes, full report + comparison
python3 main.py

# Compact one-line-per-stage summary
python3 main.py --summary

# Single stage
python3 main.py --stage F3

# Top-N stages by connectivity index
python3 main.py --top 2

# Machine-readable output
python3 main.py --json
python3 main.py --stage F2 --json

# Analyze a user TIFF stack (needs optional 'tifffile')
python3 main.py --input path/to/collagen_stack.tif

# Reproducibility override
python3 main.py --seed 12345
```

### `--input` notes

User volumes are treated as a **single-channel collagen proxy**: portal nodes are
inferred as local maxima of the blurred volume, central nodes are offset
heuristically, and ductular/zonation metrics reuse the same channel (clearly
labeled as approximate in the output). For full multi-channel analysis
(collagen + CK19 + lipid), use separate channel stacks and run them individually.

## Verification checklist

- [ ] `python3 -c "import ast; ast.parse(open('main.py').read())"` parses cleanly.
- [ ] `python3 main.py --help` shows all options.
- [ ] `python3 main.py --summary` prints F1–F4 with **monotonically increasing**
      connectivity index (0.0 → ~1.2) while area% rises gradually.
- [ ] Forcing scipy/skimage/networkx absent still runs (numpy fallback backends).
- [ ] `data/fibrosis_reference.json` loads and lists stages F1–F4 + 4 bands.
- [ ] `--input` on a missing/absent-tifffile path errors gracefully (no crash).

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

## Data / reference

- `data/fibrosis_reference.json` — synthetic stage parameters (F1–F4),
  connectivity-index bands, volume defaults, and an **educational** mapping of
  NASH-CRN (Kleiner 2005) and Ishak (1995) fibrosis staging.

### Source references (for the staging *vocabulary*, not validated thresholds)

- Kleiner DE et al. *Hepatology* 2005 — NASH CRN fibrosis stage F0–F4.
- Ishak K et al. *J Hepatol* 1995 — modified HAI fibrosis 0–6.
- The numeric connectivity thresholds, completeness fractions, and synthetic
  geometry are **author-defined defaults for the procedural demo**, not derived
  from or validated against real histology.

## Medical disclaimer

This software is for **research and educational use only**. It is **not** a
medical device, **not** a diagnostic tool, and **not** intended to inform
clinical decision-making. Synthetic outputs and any analysis of user data are
illustrative. Fibrosis staging for patient care must be performed by qualified
pathologists/clinicians using validated methods.