# 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](docker-install.md) | Everyone — get the container running |
| [Pipeline Overview](pipeline.md) | Understand the full analysis flow |
| [Web GUI Quickstart](webgui-quickstart.md) | Build pipelines visually, no YAML required |
| [Containerized Execution](containerized_execution.md) | Advanced Docker task-level configuration |

---

## Quick Start

```bash
docker compose pull
docker compose up
```

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

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

See [Docker Install](docker-install.md) for the full setup guide.

---

## Authors

- Jacky Ka Long Ko: [ka.ko@kennedy.ox.ac.uk](mailto:ka.ko@kennedy.ox.ac.uk)
- Veronika Pfannenstill: [veronika.pfannenstill@stx.ox.ac.uk](mailto:veronika.pfannenstill@stx.ox.ac.uk)
- Samuel Alber: [salber@berkeley.edu](mailto:salber@berkeley.edu)