# 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

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

### Docker

See the [Installation Guide](../getting-started/installation.md#docker-api-server) for running the API server in Docker.

## Main Components

### I/O Utilities (`pyama.io`)

Load and work with microscopy data:

```python
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`):

```python
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:

```python
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:

```python
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`)

```python
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`)

```python
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