pyama

pyama is the core processing library providing algorithms, data models, CLI tools, and a FastAPI server for microscopy image analysis. It is used by pyama-react and pyama-acdc.

Installation

# Install pyama as part of the workspace
uv pip install -e pyama/

Docker

See the Installation Guide for running the API server in Docker.

Main Components

I/O Utilities (pyama.io)

Load and work with microscopy data:

from pyama.io import load_microscopy_file

# Load microscopy file (ND2 or Pos* TIFF folders)
reader, metadata = load_microscopy_file(Path("path/to/file.nd2"))

# Access metadata
print(f"Positions: {metadata.n_positions}")
print(f"Channels: {metadata.channel_names}")
print(f"Frames: {metadata.n_frames}")

Key Functions:

  • load_microscopy_file(): Load ND2 or TIFF microscopy data

  • get_microscopy_frame(): Extract single frames

  • load_config(), save_config(): Load/save ProcessingConfig from YAML

Processing Pipeline (pyama.apps.processing)

Orchestrated pipeline via run_orchestrator (or CLI pyama processing execute):

from pyama.apps.processing import run_orchestrator, WorkflowWorker
from pyama.io import load_config, load_microscopy_file
from pathlib import Path

reader, metadata = load_microscopy_file(Path("data.nd2"))
config = load_config(Path("config.yaml"))

success, result = run_orchestrator(
    reader=reader,
    metadata=metadata,
    config=config,
    output_dir=Path("output"),
)

Channel configuration (pyama.types.pipeline.Channels):

  • pc: dict[int, list[str]] – one phase contrast channel with features (area, aspect_ratio)

  • fl: dict[int, list[str]] – fluorescence channels with features (intensity_total)

Pipeline Steps:

  1. Copying: Extract frames from ND2/TIFF to raw.zarr

  2. Segmentation: LOG-STD or Cellpose (requires PC channel)

  3. Tracking: IoU or btrack (requires PC channel)

  4. Background Estimation: Tiled interpolation (requires FL channels)

  5. Cropping: Extract cell crops to crops.zarr

  6. Extraction: Feature traces to traces/position_{id}.csv

Key behavior: config.params.copy_only=True skips steps 2–6. Position selection uses config.params.positions (e.g. "all", "0:10").

Merge Processing (pyama.apps.processing.merge)

Combine trace CSVs from multiple samples:

from pyama.apps.processing.merge import run_merge_traces

summary = run_merge_traces(
    input_dir=Path("output/traces"),
    sample_yaml=Path("samples.yaml"),
    output_dir=Path("output/traces_merged"),
)

Analysis (pyama.apps.analysis)

Fit models to trace data:

from pyama.apps.analysis.fit import fit_model, get_fit_model_details, list_fit_models

# List models
models = list_fit_models()

# Fit merged sample
result = fit_merged_sample(
    input_dir=Path("traces_merged"),
    feature="intensity_total_ch_1",
    sample="control",
    model_name="maturation",
)

Available Models: trivial, maturation, maturation_blocked

Feature Extraction (pyama.apps.processing.extract)

Built-in features:

  • Phase contrast (pyama.apps.processing.extract.pc): area, aspect_ratio

  • Fluorescence (pyama.apps.processing.extract.fl): intensity_total

API Server (pyama.api.server)

FastAPI app via create_app():

  • Processing: tasks, config schema, merge

  • Data: microscopy metadata, workspace validation

  • Visualization: crops REST + WebSocket

  • Analysis: merged features, plots, compare, fit (when enabled)

Key Data Structures

MicroscopyMetadata (pyama.types.microscopy)

metadata.n_positions   # Number of positions/FOVs
metadata.n_channels    # Number of channels
metadata.n_frames      # Time frames
metadata.channel_names

ProcessingConfig (pyama.types.pipeline)

config = ProcessingConfig(
    channels=Channels(pc={0: ["area"]}, fl={1: ["intensity_total"]}),
    params=ProcessingParams(positions="all", n_workers=4, copy_only=False),
)

Extending pyama

Adding Custom Features

Add PC or FL features in pyama/apps/processing/extract/pc/ or fl/, then register in the respective __init__.py.

Adding Custom Models

Add models in pyama/apps/analysis/fit/ and register for discovery.

API Reference (Key Functions)

  • run_orchestrator(), WorkflowWorker: Pipeline execution

  • load_microscopy_file(), get_microscopy_frame(): I/O

  • load_config(), save_config(): Config YAML

  • run_merge_traces(): Merge traces by sample

  • generate_merged_trace_plots(): Analysis plots

Examples

See pyama/tests/processing/ and pyama/tests/api/ for working examples.

Integration

  • pyama-react: React + Electron desktop client (Processing, Visualization, Analysis, Chat)

  • pyama-acdc: Cell-ACDC integration plugin