# zeztz-flow

> Self-contained Python package for flow-cytometry FCS analysis.

- Install: `zeztz-flow`
- Import: `import zeztzflow as flow`
- Python: `>=3.9`
- Internal modules: `_experiment`, `_operations`, `_views`, `_utility`, `_fcsparser`

Core workflow:

```python
import matplotlib.pyplot as plt
import zeztzflow as flow

expr = flow.zeztz_exp("path/to/fcs_directory")

cells = flow.auto_gate_FSC_SSC(expr.expr, keep=0.6)
single_cells = flow.auto_gate_FSC_A_H(cells, keep=0.7)

flow.density_plot(single_cells, xchannel="FSC 488/10-A",
                  ychannel="Alexa 647-A", xscale="log", yscale="log")
expr.median_96well(single_cells, channel="Alexa 647-A")

plt.show()
```

Key assumptions:
- FCS files in one directory, names start with well ID (A1..H12)
- Standard 8×12 plate layout
- Event data: `expr.expr.data` (pandas DataFrame)

Helpers by category:

**Loading/Export:** `zeztz_exp(working_dir, merge_dirs=[])`,
`zeztz_exp.median_96well(experiment, channel, interval="\t")`

**Gating:** `assist_gate(experiment, channel, low, high)`,
`auto_gate_FSC_SSC(experiment, keep=0.6)`,
`auto_gate_FSC_A_H(experiment, keep=0.9)`,
`polygon_gate(experiment, xchannel, ychannel, vertices=...)`,
`interactive_gate_preview(experiment, xchannel, ychannel)`,
`apply_drawn_gate(experiment, name)`

**Plotting:** `density_plot(experiment, xchannel, ychannel)`,
`plot_histogram(experiment, channel, huefacet, show_kde=True)`,
`plot_ridgeline(experiment, channel, huefacet, show_kde=True)`,
`channel_info(experiment, channel)`, `flow_style()`

**Subset:** `subset_by_char(experiment, char)`, `subset_by_num(experiment, num)`,
`subset_by_well(experiment, well)`, `cell_count(experiment)`

Constraints:
- Scales: `linear`, `log` only (logicle removed)
- Gating order: FSC/SSC → FSC-A/FSC-H
- Polygon gating: use `interactive_gate_preview()` + `apply_drawn_gate()`
- `subset_by_num` expects strings (`"12"`, not `12`)
- Headless scripts: `matplotlib.use("Agg")` before pyplot import

Docs: `README.md` (overview), `PROJECT_GUIDE.md` (full API),
`AGENTS.md` (agent guide), `THIRD_PARTY_NOTICES.md` (licenses)
