Introduction to pyCyto

pyCyto is a Python workflow package for reproducible analysis of microscopic cytotoxicity assays. It processes time-lapse fluorescence microscopy data through a modular pipeline — from raw images to quantified cell interactions.

What pyCyto Does

pyCyto automates the quantitative analysis of cytotoxicity experiments, where immune effector cells (e.g. T cells) kill target cancer cells under a microscope. The pipeline extracts:

  • Cell tracks — positions, velocities, and lifetimes over time

  • Cell–cell contacts — which cells touch, for how long, and with what frequency

  • Killing events — association between contact events and target cell death

  • Population statistics — survival curves, contact rates, and spatial interaction metrics

Core Concepts

Five Data Types

All data flowing through the pipeline has one of five types, each with a standardized dictionary key:

Type

Key

Description

Image

"image"

Raw or processed pixel arrays (Dask/NumPy)

Label

"label"

Segmentation masks (integer-valued arrays)

Table

"dataframe"

Sparse per-cell feature tables (pandas)

Network

"network"

Cell interaction graphs (NetworkX)

Arbitrary

—

Stage-specific outputs (plots, provenance JSON)

Six Analysis Categories

Category

Input → Output

Examples

Preprocessing

image → image

Normalization, registration, denoising

Segmentation

image → label

Cellpose, StarDist

Tabulation

image/label → table

Region properties, intensity features

Tracking

table → table

TrackMate (via PyImageJ), trackpy

Contact tracing

label/table → network

Cross-cell contact detection (pyclesperanto)

Postprocessing

any → arbitrary

Survival curves, interaction plots, export

Two Ways to Build a Pipeline

  • YAML pipeline (cyto --pipeline my_pipeline.yaml) — declarative, no code required

  • Web GUI — visual DAG editor bundled with the Docker distribution, exports the same YAML

Documentation

Section

For whom

Docker Install

Everyone — get the container running

Pipeline Overview

Understand the full analysis flow

Web GUI Quickstart

Build pipelines visually, no YAML required

Containerized Execution

Advanced Docker task-level configuration

Quick Start

docker compose pull
docker compose up

Open the web GUI at http://localhost:3003, or run a pipeline YAML directly:

docker compose run --rm cyto cyto --pipeline /config/pipeline.yaml -v

See Docker Install for the full setup guide.

Authors