End-to-end pipeline for segmenting cells, detecting calcium peaks,
and quantifying oscillation periodicity and spatial synchronicity
from time-lapse microscopy.
pyKrait (python Calcium recording analysis and interpretation toolbox) automatically processes calcium-imaging videos (.czi, .tif, .tiff) and computes calcium activity, peak statistics, periodicity scores, and neighbour-aware synchronicity z-scores.
It is recommended to install pyKrait in a virtual environment using either venv or uv. The graphical user interface is optional, install it with pip install "pykrait[gui]".
uv venv --python 3.12
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install 'pykrait[gui]'python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install "pykrait[gui]"From inside the activated virtual environment:
python -m pykraitor
uv run python -m pykraitThe GUI then walks you through video selection, segmentation, peak detection, periodicity, and synchronicity, and lets you save results to disk.
from pykrait.pipeline.pipeline import BatchExperiment, AnalysisParameters
from pykrait.io.files import concat_analysis_files
experiment = BatchExperiment(
folder="/path/to/videos",
params=AnalysisParameters(),
extension=".czi",
)
experiment.run()
concat_analysis_files("/path/to/videos", filetype="output")This produces one Analysis_<video>/ directory per video and an analysis_output_overview.csv at the root of the folder.
To analyze videos in subfolders, pass recursive=True; to analyze only some of the acquisitions, pass filter_string / exclude_string (e.g. filter_string="*_timeseries.czi", where a pattern with *, ? or [] matches the whole file name and anything else matches as a substring).
| Scenario | Notebook |
|---|---|
| Run a folder with custom parameters | notebooks/example_batch_with_custom_parameters |
| Re-run a folder reusing saved parameters and cached masks | notebooks/example_batch_reusing_parameters |
| Inspect or refine a single video interactively | Launch the GUI: python -m pykrait |
For each video, pyKrait runs the following stages:
- Load — lazy
Daskarray viabioio(.czi,.tif,.tiff). - Correct motion (optional, off by default) — align every frame to a template, either by a rigid translation or by a mesh-based / polynomial optical-flow warp.
- Project — STD or SUM projection across time, with optional CLAHE.
- Segment — Cellpose (
cpsamby default, or a custom model path). - Extract — per-cell mean intensity per frame, computed lazily on Dask.
- Detrend — Blackman-windowed sinc filter (cf. pyBOAT).
- Detect peaks —
scipy.signal.find_peakswith width / height / prominence thresholds. - Periodicity — STD and CoV of inter-peak intervals, scored against a shuffled-peaks null.
- Adjacency — neighbour graph from segmented masks (kernel-based proximity).
- Synchronicity — co-firing peaks within a time window and topological distance, z-scored against label-shuffled controls.
Full API reference and tutorials: https://pykrait.readthedocs.io/en/latest/.
If you use pyKrait, please cite the preprint: Hebach, N. R., Olshausen, N., Schlag, J., Mayer, C. D., Henkenjohann, J., Kraft, T., Bang, S., Thommek, C., Nürnberg, C., Horsak, N. E., Hoffmann, D. C., Kourtesakis, A., Porzberg, N., Flores Valle, A., Linke, C. Z., Yang, Y., Azorín, D. D., Hausmann, D., Venkataramani, V., … Karreman, M. A. (2026). Collective cancer cell calcium activity drives brain metastasis. bioRxiv, 2026.05.10.723715. https://doi.org/10.64898/2026.05.10.723715
pyKrait builds on and heavily uses prior open-source work:

