---
title: Neuron Quantification using AI
emoji: 🔬
colorFrom: gray
colorTo: blue
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
license: mit
---

# Neuron Quantification using AI

Iman Sabir Ezzat, Randa K Ismail, Ayden Chavez, Marisa Zallocchi, PhD, Steven Fernandes, PhD

A HuggingFace app that traces auditory-nerve fibers in confocal z-stacks of the
organ of Corti and quantifies them **per frequency region**, separating
**IHC-innervating** from **OHC-innervating** fibers.

It is an alternative to IMARIS filament tracing that keeps each neuron as a
**single continuous traced element** instead of splitting it into many
threshold-dependent segments.

## Input

- **File type:** Zeiss `.czi` 3D z-stacks. Generic `.tif/.tiff` stacks are also
  accepted for flexibility — including single-plane 2D images and **RGB TIFFs**
  (the R/G/B colour planes are exposed as selectable channels, so a red-neuron /
  blue-nuclei composite works out of the box).
- **Channels:**
  - *Neurofilament* — traces the neuron.
  - *Myo7a* — marks hair cells; used as a reference to separate IHC- vs
    OHC-innervating fibers. IHCs form a single row and OHCs form three adjacent
    rows, so the Myo7a band is used to place the IHC/OHC boundary.
- **Frequency region:** selectable (8/16/22/32/64 kHz), auto-detected from the
  file name when possible.
- Channels are auto-detected from CZI metadata (Alexa-555 → Neurofilament,
  Alexa-405 → Myo7a) but can be reassigned in the UI. Many dyes are recognised
  automatically (405 / 488 / 514 / 555 / 568 / 594 / 633 / 647 / ATTO / Cy…) and
  **every channel in the file is selectable**, so extra markers can be chosen as
  the trace or reference channel.

## What it does

1. Segments and **skeletonises the Neurofilament network in 3D** using physical
   voxel spacing (from CZI metadata, or entered for TIFF).
2. Uses the **Myo7a channel** to place an IHC/OHC boundary. Defining both
   regions is **optional** — you choose the **analysis scope**: *split IHC vs
   OHC*, *inner hair cells only*, or *whole field only* (fast). Choose **inner
   hair cells only** when the image has no outer hair cells: the whole field is
   reported as one IHC region and **no OHC region is invented**. For a split,
   the boundary can be moved, **tilted**, **curved** (for a rotated or curving
   organ), or switched to an **X** or **Z** (depth) split axis while viewing the
   Myo7a preview. The IHC-side selector is worded by image position
   (top/bottom, left/right, shallow/deep) so it can't be misread.
   Optionally, **Detect hair cells** runs **Cellpose** (or a classical
   watershed fallback) on the Myo7a channel to mark hair cells, count them per
   region, and *propose* a boundary + side with a confidence score. When only a
   single hair-cell row is present (no resolvable tunnel of Corti), it declines
   to split and reports **whole-field only** rather than inventing an empty
   IHC/OHC region. Detection can over-mark the tunnel of Corti, so you can
   **override the hair-cell counts manually** for normalization. On dense fields
   this detection is often incomplete, so it is a **visual assist**: the
   quantified numbers come from the deterministic pipeline and the boundary
   stays under your control. If a chosen boundary leaves one region with no
   fibers, the app warns that the split is likely wrong. Detection is much
   better on a GPU Space.
3. Computes, per region (Whole field / IHC / OHC):
   - **Number of fibers** (continuous skeleton components kept by the length
     **and** min/max mean-diameter filters)
   - **Hair cells (Myo7a)** counted in the region (detected or manual), plus
     **fibers per hair cell** and **length per hair cell** for normalization
   - **Thickness / diameter** (from the 3D distance transform)
   - **Length** (µm, spacing-aware)
   - **Branching** (number of branch points)
   - **Fiber direction** — radial (IHC→OHC) vs off-axis ("misdirected") counts
     and % radial
   - **Area covered** within the field of view (µm² and % of FOV)

## Output

- A **black-background image** of the traced neurons in **white** (skeletonised
  trace), a **trace-on-original overlay**, and a colour-coded IHC/OHC overlay.
  A **view toggle** switches the main image between Overlay / Skeleton /
  Original so the trace can be checked on and off against the raw signal.
- An **Excel workbook** with all quantification, organized by frequency region,
  with IHC and OHC fibers reported separately (tidy "Per region" sheet plus
  per-metric frequency × region summary sheets).

The **Batch** tab processes several stacks at once (e.g. all frequency regions
of one cochlea) and compiles one Excel workbook plus a ZIP containing **both**
the black-on-white skeleton image and the trace-on-original overlay for every
file. The gallery shows whichever of the two you pick, and the batch supports
the same *split / inner-hair-cells-only / whole-field* scopes.

## Notes on method

Confocal images of the organ of Corti are dense, so fully separating every
individual axon is inherently ambiguous. This tool traces the network
continuously and reports metrics **per region surrounding the IHCs / OHCs**,
with a human-in-the-loop boundary for reliable IHC vs OHC assignment. The
`sensitivity` control scales the segmentation threshold to capture more or fewer
thin fibers.

## Local run

```bash
pip install -r requirements.txt
python app.py
```