DeathScope is a label-free image-analysis pipeline for single-cell detection and phenotyping of programmed cell death in Incucyte phase-contrast time-lapse imaging. This repository contains the public code release associated with the manuscript DeathScope: A label-free AI framework for single-cell analysis of regulated cell death in Incucyte imaging.

The released workflows include:

• a YOLOv8-based detector for apoptosis and necroptosis
• RMH inference (random cropping -> multiple predictions -> heatmap) for full-frame probability maps
• an optional ConvNeXt-based second-stage classifier to split apoptosis-like regions into apoptosis versus pyroptosis
• training and batch-inference utilities used to generate manuscript figures and kinetics tables

Results Demo

MEFs undergoing T/S/V-induced necroptosis visualized with DeathScope:

Click the preview above to open the full-resolution MP4: A2_2_death_image_green_wphase.mp4

Status

This repository contains the public code release for the core DeathScope detection, heatmap inference, ConvNeXt refinement, and training workflows described in the manuscript. Example datasets, trained model assets, training notebooks, and manuscript-supporting documentation are included where appropriate.

Repository Layout

.
├── README.md
├── LICENSE
├── requirements.txt
├── pyproject.toml
├── CITATION.cff
├── configs/
│   ├── README.md
│   └── cell_dataset.yaml
├── docs/
│   ├── A2_2_death_image_green_wphase.gif
│   ├── A2_2_death_image_green_wphase.mp4
│   ├── README.md
│   └── deathscope_logo.png
├── examples/
│   ├── README.md
│   ├── ConvNeXt_data_demo/
│   └── mef_tsv_demo/
├── models/
│   ├── README.md
│   ├── pyroptosis/
│   │   ├── classes.json
│   │   └── model_best.pth
│   └── yolo/
│       └── deathscope_yolov8l.pt
├── outputs/
│   └── logs/
├── scripts/
│   ├── README.md
│   └── batch_predict.py
├── src/
│   └── deathscope/
│       ├── __init__.py
│       ├── cell_detector.py
│       ├── cli.py
│       └── pyro_classifier.py
└── training/
    ├── README.md
    ├── ConvNeXt/
    │   ├── README.md
    │   ├── ConvNeXt-Large_DataPreparation.ipynb
    │   ├── ConvNeXt-Large_plot.ipynb
    │   ├── ConvNeXt-Large_training.ipynb
    │   └── ConvNeXt-Large_prediction.ipynb
    └── YOLO/
        ├── README.md
        ├── train_yolo.ipynb
        └── train_yolo_script.py

Method Summary

The manuscript describes a two-stage workflow:

1. Phase-contrast images are processed with a YOLOv8 detector trained on fluorescence-anchored annotations generated with FluoroBoxer.
2. For full-frame inference, DeathScope uses RMH aggregation: many random overlapping crops are scored independently and merged into apoptosis and necroptosis heatmaps in image coordinates.
3. In the optional pyroptosis extension, apoptosis-like regions are passed to a ConvNeXt classifier that reassigns them to apoptosis or pyroptosis.

The code in src/deathscope/cell_detector.py implements the detector, tiling logic, RMH heatmap generation, batch export, and image overlays. The code in src/deathscope/pyro_classifier.py implements the optional second-stage pyroptosis classifier.

Installation

Python 3.11 is the tested baseline for the current repository state. Use Python 3.11 or 3.12 for installation. Python 3.13 is not currently supported by the pinned dependency set in this repository.

Create an environment and install the dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

For editable installation of the repository package entry points:

pip install -e .

If you are currently using python3.13, create a python3.11 or python3.12 environment instead:

python3.11 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

Then confirm the CLI is available:

deathscope-batch-predict --help

Notes:

• Install a PyTorch build appropriate for your platform and CUDA stack if you need GPU inference or training.
• The repository currently pins Python dependencies for reproducibility of the code release, not for minimal installation size.

Quick Start

1. Batch heatmap inference on an Incucyte-style dataset

Expected directory structure:

dataset_name/
├── Phase/
│   ├── image_001.png
│   └── ...
└── Green/
    ├── image_001.png
    └── ...

Run the standard apoptosis/necroptosis pipeline on the included example dataset:

deathscope-batch-predict \
  --input-root examples \
  --pattern "mef_tsv_demo" \
  --model models/yolo/deathscope_yolov8l.pt \
  --desired-coverage 20

Run the pyroptosis-enabled workflow:

deathscope-batch-predict \
  --input-root examples \
  --pattern "mef_tsv_demo" \
  --model models/yolo/deathscope_yolov8l.pt \
  --desired-coverage 20 \
  --pyro

Outputs are written next to the dataset folders as:

• per-frame overlay images
• per-dataset CSV summaries
• Incucyte-style aggregated CSV tables by well and by time
• run logs and JSON summaries under outputs/logs/

2. Programmatic usage

import cv2
from deathscope import CellDetector

detector = CellDetector("models/yolo/deathscope_yolov8l.pt")
image = cv2.imread("path/to/phase_image.png", cv2.IMREAD_GRAYSCALE)

apoptosis_map, necroptosis_map, background_map = detector.predict_with_heatmap(
    image,
    conf=0.5,
    iou=0.5,
    desired_coverage=20,
)

Training

YOLO detector training is documented under training/YOLO/README.md. The script entry point is:

python training/YOLO/train_yolo_script.py --data configs/cell_dataset.yaml --model yolov8l.pt

ConvNeXt classifier preparation, training, plotting, and prediction notebooks are documented under training/ConvNeXt/README.md.

Inputs And Outputs

Inputs

• 8-bit phase-contrast images for inference
• optional green-channel images for comparison to SYTOX Green or related fluorescence-derived readouts
• YOLO-format detection labels for training

Outputs

• crop-level or full-frame detection results
• apoptosis and necroptosis probability heatmaps
• optional pyroptosis reassignment maps
• per-image and aggregated kinetics CSV files
• overlay PNGs for visual inspection

Limitations

• The current implementation is optimized for 2D Incucyte-style phase-contrast imaging.

• The current two-stage stacked pipeline remains limited because pyroptosis was implemented as a second-stage classifier rather than a native detector class, and training was restricted to Bone marrow-derived macrophage images under limited conditions. Thus, this module serves primarily as a proof of concept for extending the core framework.

• Ground-truth generation and biological validation depend on the experimental design described in the manuscript and are not fully reproduced by this repository alone.

Citation

If you use DeathScope, cite the manuscript and the archived software release described in CITATION.cff.