---
title: Antigen Puncta Quantification
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
pinned: false
license: mit
---

# Antigen Puncta Quantification (CDA, PTAU, MBP, SYN)

Quantifies antigen fluorescence in microscopy images with antigen-specific
pipelines:

- CDA: identifies and quantifies puncta with similar fluorescence intensity
  while minimizing background signal.
- PTAU: detects and quantifies puncta with similar fluorescence
  characteristics while reducing background noise.
- MBP: identifies MBP fluorescence within cells while excluding background
  signal (area and intensity based).
- SYN: identifies and quantifies smaller, easily missed puncta with similar
  fluorescence intensity (smaller minimum punctum size, more sensitive
  threshold).

## Tabs

- Analyze: single image, detection overlay, summary metrics, per-punctum CSV.
- Calibrate on gold standard: upload gold-standard ROI images with known
  manual counts for CDA, PTAU or SYN; the app runs a supervised search over
  detector settings (punctum size, detection threshold, signal-to-noise
  cutoff, intensity-similarity tolerance) to match your counts, then uses the
  calibrated settings automatically. Parameters can be exported and imported
  as JSON.
- Batch: process many images with the current settings and download a CSV.

## Method

Puncta antigens: Gaussian denoise, smooth-background subtraction,
Laplacian-of-Gaussian blob detection, rejection of low signal-to-noise
candidates (background minimization), then a robust intensity-similarity
filter (keeps puncta whose background-subtracted peak intensity is within a
tolerance band around the population median, using median and median
absolute deviation).

MBP: a coarse cell mask is segmented from a strongly smoothed copy of the
image; MBP-positive fluorescence is thresholded inside cells only, with a
robust fallback threshold that guards against Otsu failure, so background
outside cells never contributes to the measurements.

## Robustness behaviors

These behaviors came out of an adversarial review of the pipeline and are
covered by the self-test:

- The detection scale is capped at background + 50 robust noise sigmas, so
  a single large saturated artifact (dust, a hair) cannot silently suppress
  real detections.
- The intensity-similarity filter is bimodal-aware: when candidates split
  into two clearly separated intensity populations, the brighter population
  is quantified as puncta and dim confusers are rejected as background;
  a small very-bright mode (more than 30x the main population, or under 15
  percent of candidates) is rejected as artifacts instead. The status text
  reports which population was used and warns when rejected candidates
  were brighter than kept ones.
- MBP refuses to fabricate measurements on fields with no distinguishable
  cells (negative controls) and warns when the cell mask may have collapsed
  onto the bright signal in confluent fields.
- Calibration breaks ties between equally accurate settings toward the
  strictest ones, so calibrating on clean gold-standard ROIs does not
  produce over-permissive settings that flood routine images with false
  positives.
- CZYX/TCZYX stacks keep their channel axis through projection, 2-channel
  channel-last images are handled as channels, NaN/Inf padding is
  sanitized, and LZW-compressed TIFFs are supported.

## Input formats

8/16-bit grayscale or RGB TIFF, PNG, JPG. Multi-channel images: choose the
channel in the dropdown. Z-stacks are reduced by maximum intensity
projection.

## Deploying on Hugging Face Spaces

1. Create a new Space at huggingface.co/new-space, SDK: Gradio.
2. Upload `app.py`, `requirements.txt` and this `README.md` to the Space
   repository root.
3. The Space builds and serves the app automatically. No GPU is required.

## Running locally

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

## Verification

`selftest.py` builds synthetic fluorescence images with known ground truth
and checks: puncta recall and precision, rejection of bright artifacts by the
similarity filter, recovery of small SYN-like puncta, MBP area accuracy
inside cells, calibration improvement, and 16-bit TIFF / RGB PNG loading.
Run it with `python selftest.py`.