Skip to content
Winklerlab-HDPublic

About

Image analysis pipeline for synchronized calcium activity

Resources

Stars

2 stars

Watchers

1 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

pyKrait

pyKrait

PyPI Python versions CI Docs License

End-to-end pipeline for segmenting cells, detecting calcium peaks,
and quantifying oscillation periodicity and spatial synchronicity
from time-lapse microscopy.

Analysis Steps of the pykrait package

Overview

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.

Installation

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]".

Using uv

uv venv --python 3.12
source .venv/bin/activate           # Windows: .venv\Scripts\activate
uv pip install 'pykrait[gui]'

Standard venv

python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install "pykrait[gui]"

Quickstart

Launch the GUI

From inside the activated virtual environment:

python -m pykrait

or

uv run python -m pykrait

The GUI then walks you through video selection, segmentation, peak detection, periodicity, and synchronicity, and lets you save results to disk.

Batch process an entire folder

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).

Example Notebooks

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

How it works

For each video, pyKrait runs the following stages:

  1. Load — lazy Dask array via bioio (.czi, .tif, .tiff).
  2. 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.
  3. Project — STD or SUM projection across time, with optional CLAHE.
  4. Segment — Cellpose (cpsam by default, or a custom model path).
  5. Extract — per-cell mean intensity per frame, computed lazily on Dask.
  6. Detrend — Blackman-windowed sinc filter (cf. pyBOAT).
  7. Detect peaks — scipy.signal.find_peaks with width / height / prominence thresholds.
  8. Periodicity — STD and CoV of inter-peak intervals, scored against a shuffled-peaks null.
  9. Adjacency — neighbour graph from segmented masks (kernel-based proximity).
  10. Synchronicity — co-firing peaks within a time window and topological distance, z-scored against label-shuffled controls.

Documentation

Full API reference and tutorials: https://pykrait.readthedocs.io/en/latest/.

Citation

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

Acknowledgements

pyKrait builds on and heavily uses prior open-source work:

  • Cellpose for cell segmentation
  • pyBOAT for the sinc-filter detrending approach
  • bioio for image I/O
  • Dask for lazy array computation

About

Image analysis pipeline for synchronized calcium activity

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages