if_analysis_multichannel

Multichannel single-cell immunofluorescence analysis with brightfield-refined cell boundaries, nuclear/cytoplasmic quantification, and per-cell co-localization metrics

Requirements

• numpy>=1.23
• pandas>=1.5
• scipy>=1.10
• scikit-image>=0.21
• matplotlib>=3.7
• tifffile>=2023.2.3

Core script: if_analysis_multichannel_v1.py.

---

Features

• Multi-channel support
  • Single marker: 3.tiff.
  • Multiple markers: 3X.tiff (e.g. 3R.tiff, 3G.tiff, 3Cy5.tiff), each treated as a separate protein channel.
• Nuclear segmentation
  • Gaussian smoothing + Otsu thresholding on DAPI.
  • Distance transform + peak_local_max seeds.
  • Watershed-based splitting of touching nuclei.
• Cell boundary detection
  • Permissive fluorescence mask from 1.tiff.
  • Nucleus-dilated support.
  • Brightfield (4.tiff) Scharr gradient as watershed landscape.
  • Nuclei as seeds for coarse cell regions.
  • Morphological Geodesic Active Contours (MorphGAC) on brightfield for final refinement.
• Per-cell quantification
  • Nuclear vs cytoplasmic masks for each cell.
  • Background estimation (global + local ring) for every channel.
  • Total and mean intensities in whole cell, nucleus, and cytoplasm.
  • Nuclear-to-cytoplasmic ratio (NCR) and nuclear fraction per marker.
  • Binary and categorical nuclear localization calls per marker.
• Co-localization metrics
  • Per-cell Pearson correlation between every marker pair.
  • Overlap fractions (Manders-like) for each pair and direction.
• TIFF metadata & physical units
  • TIFF/OME pixel size parsing for µm-scale areas.
  • Magnification and expected cell count accepted as metadata and soft QC hints.
• Structured output
  • cell_measurements.csv:
    • geometry, areas, DAPI metrics
    • per-marker intensities, ratios, SNR
    • localization states, z-scores
    • per-pair co-localization
    • QC flags (exclude_from_core_analysis, exclude_reason)
  • cells_labeled.png:
    • composite overlay (from 1.tiff)
    • yellow cell boundaries, magenta nuclear boundaries
    • cell IDs (white or cyan) at centroids

---

Input files and naming convention

All images for a single field of view must be in one directory:

• 1.tiff — composite IF image (RGB or RGBA). Used for visualization and a permissive fluorescence mask.
• 2.tiff — DAPI/nuclear stain. DAPI is assumed to be mainly in the blue channel.
• 3.tiff or 3X.tiff images — protein channel(s):
  • If 3.tiff exists:
    • Treated as a single marker with internal name P.
  • If 3.tiff does not exist and one or more 3*.tiff files are present:
    • Each 3X.tiff is treated as a separate marker.
      • Example: 3R.tiff → marker R
      • Example: 3G.tiff → marker G
      • Example: 3Cy5.tiff → marker CY5
  • Files may be grayscale or RGB/RGBA; RGB channels are converted to luminance.
• 4.tiff — brightfield image (RGB/RGBA). Used to refine cell boundaries.

Any additional channels should follow the 3X.tiff convention.

---

Usage

Place 1.tiff, 2.tiff, the 3.tiff / 3X.tiff marker files, and 4.tiff in a directory, e.g.:

data/U87MG_example/ - 1.tiff - 2.tiff - 3R.tiff - 3G.tiff - 4.tiff

Run:

python if_analysis_multichannel_v1.py -i data/U87MG_example

• If --magnification or --expected_cells are omitted, the script interactively prompts for them (press Enter to skip).