pykrait 0.3.2__tar.gz → 0.3.3__tar.gz

pykrait-0.3.3/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+uv.lock
+
+# Testing
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# Docs
+docs/_build/
+docs/autoapi/
+docs/source/_autosummary/
+docs/make.bat
+docs/Makefile
+
+# IDEs
+.vscode/
+.idea/
+.claude/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Secrets
+.env
+*.pem
+
+# cellpose models
+cellpose_models/

{pykrait-0.3.2 → pykrait-0.3.3}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Phaleanopsis
+Copyright (c) 2026 Phaleanopsis
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

pykrait-0.3.3/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: pykrait
+Version: 0.3.3
+Summary: Python Calcium Recording Analysis and Interpretation Toolbox
+Author-email: phaleanopsis <22663502+phaleanopsis@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aicspylibczi>=3.3.1
+Requires-Dist: bioio-czi>=2.4.0
+Requires-Dist: bioio-imageio
+Requires-Dist: bioio-ome-tiff>=1.1.0
+Requires-Dist: bioio-tifffile>=1.3.0
+Requires-Dist: bioio>=3.2.0
+Requires-Dist: cellpose>=4.0.8
+Requires-Dist: dask>=2025.5.1
+Requires-Dist: fsspec>=2022.8.0
+Requires-Dist: imagecodecs>=2025.3.30
+Requires-Dist: lxml>=5.4.0
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: numcodecs<0.16
+Requires-Dist: numpy>2
+Requires-Dist: ome-types>=0.5.3
+Requires-Dist: ome-zarr>=0.10.2
+Requires-Dist: pandas>=2.3.1
+Requires-Dist: pip>=25.1.1
+Requires-Dist: pydantic<2
+Requires-Dist: pylibczirw>=6.0.1
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: resource-backed-dask-array>=0.1.0
+Requires-Dist: scikit-image>=0.25.2
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: xarray>=2025.12
+Requires-Dist: zarr>=2.15.0
+Requires-Dist: zstandard>=0.23.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2.post1; extra == 'dev'
+Requires-Dist: hatch>=1.14.1; extra == 'dev'
+Requires-Dist: ipywidgets>=8.1.7; extra == 'dev'
+Requires-Dist: myst-parser>=5.0.0; extra == 'dev'
+Requires-Dist: pydata-sphinx-theme>=0.16.1; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.4.1; extra == 'dev'
+Requires-Dist: ruff>=0.11.13; extra == 'dev'
+Requires-Dist: sphinx-autoapi>=3.6.0; extra == 'dev'
+Requires-Dist: sphinx-favicon>=1.0.1; extra == 'dev'
+Requires-Dist: sphinx>=8.1.3; extra == 'dev'
+Requires-Dist: tomli>=2.2.1; extra == 'dev'
+Requires-Dist: twine>=6.1.0; extra == 'dev'
+Provides-Extra: gui
+Requires-Dist: pyside6>=6.9.1; extra == 'gui'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/_static/logo.png" alt="pyKrait" width="200">
+</p>
+
+<h1 align="center">pyKrait</h1>
+
+
+<p align="center">
+  <a href="https://pypi.org/project/pykrait/"><img src="https://img.shields.io/pypi/v/pykrait" alt="PyPI"></a>
+  <a href="https://pypi.org/project/pykrait/"><img src="https://img.shields.io/pypi/pyversions/pykrait" alt="Python versions"></a>
+  <a href="https://github.com/&lt;your-org&gt;/pykrait/actions"><img src="https://img.shields.io/github/actions/workflow/status/&lt;your-org&gt;/pykrait/CI.yaml" alt="CI"></a>
+    <a href="https://pykrait.readthedocs.io"><img src="https://img.shields.io/readthedocs/pykrait" alt="Docs"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+<p align="center">
+  End-to-end pipeline for segmenting cells, detecting calcium peaks,<br>
+  and quantifying oscillation periodicity and spatial synchronicity<br>
+  from time-lapse microscopy.
+</p>
+
+
+<p align="center">
+  <img src="docs/_static/pyKrait_steps.png" alt="Analysis Steps of the pykrait package" width="600">
+</p>
+
+## Overview
+
+pyKrait (**py**thon **C**alcium **r**ecording **a**nalysis and **i**nterpretation **t**oolbox) 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]"`. 
+
+### Standard `venv`
+
+```bash
+python -m venv .venv
+source .venv/bin/activate           # Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install pykrait
+```
+
+### Using `uv`
+
+```bash
+uv venv --python 3.11
+source .venv/bin/activate           # Windows: .venv\Scripts\activate
+uv pip install pykrait
+```
+
+## Quickstart
+
+### Launch the GUI
+
+From inside the activated virtual environment:
+```bash
+python -m pykrait
+```
+
+The GUI walks you through video selection, segmentation, peak detection, periodicity, and synchronicity, and lets you save results to disk.
+
+### Batch process an entire folder
+
+```python
+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.
+
+## Examples
+
+| Scenario | Notebook |
+|----------|----------|
+| Run a folder with custom parameters | [`notebooks/example_batch_with_custom_parameters.ipynb`](notebooks/example_batch_with_custom_parameters.ipynb) |
+| Re-run a folder reusing saved parameters and cached masks | [`notebooks/example_batch_reusing_parameters.ipynb`](notebooks/example_batch_reusing_parameters.ipynb) |
+| 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. **Project** — STD or SUM projection across time, with optional CLAHE.
+3. **Segment** — Cellpose (`cpsam` by default, or a custom model path).
+4. **Extract** — per-cell mean intensity per frame, computed lazily on Dask.
+5. **Detrend** — Blackman-windowed sinc filter (cf. pyBOAT).
+6. **Detect peaks** — `scipy.signal.find_peaks` with width / height / prominence thresholds.
+7. **Periodicity** — STD and CoV of inter-peak intervals, scored against a shuffled-peaks null.
+8. **Adjacency** — neighbour graph from segmented masks (kernel-based proximity).
+9. **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/>**.
+
+## Acknowledgements
+
+pyKrait builds on and heavily uses prior open-source work:
+
+- [Cellpose](https://github.com/MouseLand/cellpose) for cell segmentation
+- [pyBOAT](https://github.com/tensionhead/pyBOAT) for the sinc-filter detrending approach
+- [bioio](https://github.com/bioio-devs/bioio) for image I/O
+- [Dask](https://www.dask.org/) for lazy array computation
+

pykrait-0.3.3/README.md

@@ -0,0 +1,114 @@
+<p align="center">
+  <img src="docs/_static/logo.png" alt="pyKrait" width="200">
+</p>
+
+<h1 align="center">pyKrait</h1>
+
+
+<p align="center">
+  <a href="https://pypi.org/project/pykrait/"><img src="https://img.shields.io/pypi/v/pykrait" alt="PyPI"></a>
+  <a href="https://pypi.org/project/pykrait/"><img src="https://img.shields.io/pypi/pyversions/pykrait" alt="Python versions"></a>
+  <a href="https://github.com/&lt;your-org&gt;/pykrait/actions"><img src="https://img.shields.io/github/actions/workflow/status/&lt;your-org&gt;/pykrait/CI.yaml" alt="CI"></a>
+    <a href="https://pykrait.readthedocs.io"><img src="https://img.shields.io/readthedocs/pykrait" alt="Docs"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+</p>
+<p align="center">
+  End-to-end pipeline for segmenting cells, detecting calcium peaks,<br>
+  and quantifying oscillation periodicity and spatial synchronicity<br>
+  from time-lapse microscopy.
+</p>
+
+
+<p align="center">
+  <img src="docs/_static/pyKrait_steps.png" alt="Analysis Steps of the pykrait package" width="600">
+</p>
+
+## Overview
+
+pyKrait (**py**thon **C**alcium **r**ecording **a**nalysis and **i**nterpretation **t**oolbox) 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]"`. 
+
+### Standard `venv`
+
+```bash
+python -m venv .venv
+source .venv/bin/activate           # Windows: .venv\Scripts\activate
+pip install --upgrade pip
+pip install pykrait
+```
+
+### Using `uv`
+
+```bash
+uv venv --python 3.11
+source .venv/bin/activate           # Windows: .venv\Scripts\activate
+uv pip install pykrait
+```
+
+## Quickstart
+
+### Launch the GUI
+
+From inside the activated virtual environment:
+```bash
+python -m pykrait
+```
+
+The GUI walks you through video selection, segmentation, peak detection, periodicity, and synchronicity, and lets you save results to disk.
+
+### Batch process an entire folder
+
+```python
+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.
+
+## Examples
+
+| Scenario | Notebook |
+|----------|----------|
+| Run a folder with custom parameters | [`notebooks/example_batch_with_custom_parameters.ipynb`](notebooks/example_batch_with_custom_parameters.ipynb) |
+| Re-run a folder reusing saved parameters and cached masks | [`notebooks/example_batch_reusing_parameters.ipynb`](notebooks/example_batch_reusing_parameters.ipynb) |
+| 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. **Project** — STD or SUM projection across time, with optional CLAHE.
+3. **Segment** — Cellpose (`cpsam` by default, or a custom model path).
+4. **Extract** — per-cell mean intensity per frame, computed lazily on Dask.
+5. **Detrend** — Blackman-windowed sinc filter (cf. pyBOAT).
+6. **Detect peaks** — `scipy.signal.find_peaks` with width / height / prominence thresholds.
+7. **Periodicity** — STD and CoV of inter-peak intervals, scored against a shuffled-peaks null.
+8. **Adjacency** — neighbour graph from segmented masks (kernel-based proximity).
+9. **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/>**.
+
+## Acknowledgements
+
+pyKrait builds on and heavily uses prior open-source work:
+
+- [Cellpose](https://github.com/MouseLand/cellpose) for cell segmentation
+- [pyBOAT](https://github.com/tensionhead/pyBOAT) for the sinc-filter detrending approach
+- [bioio](https://github.com/bioio-devs/bioio) for image I/O
+- [Dask](https://www.dask.org/) for lazy array computation
+

{pykrait-0.3.2 → pykrait-0.3.3}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "pykrait"
-version = "0.3.2"
-description = "Python Calcium Recording Analysis and Inference Toolbox"
+version = "0.3.3"
+description = "Python Calcium Recording Analysis and Interpretation Toolbox"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { text = "MIT" }
 authors = [
@@ -10,12 +10,12 @@ authors = [
 requires-python = ">=3.11"
 dependencies = [
     "aicspylibczi>=3.3.1",
-    "bioio>=3.0.0",
+    "bioio>=3.2.0",
     "bioio-czi>=2.4.0",
     "bioio-ome-tiff>=1.1.0",
     "bioio-tifffile>=1.3.0",
     "bioio-imageio",
-    "cellpose>=4.0.5",
+    "cellpose>=4.0.8",
     "dask>=2025.5.1",
     "fsspec>=2022.8.0",
     "imagecodecs>=2025.3.30",
@@ -31,10 +31,12 @@ dependencies = [
     "resource-backed-dask-array>=0.1.0",
     "scikit-image>=0.25.2",
     "scipy>=1.15.3",
-    "xarray>2025",
+    "xarray>=2025.12",
     "pandas>=2.3.1",
     "zstandard>=0.23.0",
     "scikit-learn>=1.7.2",
+    "zarr>=2.15.0",
+    "pylibczirw>=6.0.1",
 ]
 
 [project.optional-dependencies]
@@ -53,7 +55,8 @@ dev = [
     "tomli>=2.2.1",
     "twine>=6.1.0",
     "pytest>=8.4.1",
-    "pytest-cov"
+    "pytest-cov",
+    "myst-parser>=5.0.0",
 ]
 
 [build-system]
@@ -100,9 +103,9 @@ src = ["src"]
 line-length = 88
 target-version = "py311"
 
-[dependency-groups]
-dev = [
-    "build>=1.2.2.post1",
-    "hatch>=1.14.1",
-    "twine>=6.1.0",
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
 ]

{pykrait-0.3.2 → pykrait-0.3.3}/src/pykrait/__main__.py

@@ -1,10 +1,10 @@
 """
-Copyright © 2025 Pentabyteman
+Copyright © 2026 Phaleanopsis
 """
 
 # src/pykrait/__main__.py
 from pykrait.gui.app import AppController
 
 if __name__ == "__main__":
-    controller = AppController()
-    controller.run()
+    app_controller = AppController()
+    app_controller.run()

{pykrait-0.3.2 → pykrait-0.3.3}/src/pykrait/gui/async_workers.py

@@ -1,13 +1,16 @@
-from PySide6.QtCore import QObject, Signal, Slot
 import traceback
+import os
+import tifffile
 import numpy as np
+import pandas as pd
+
+from PySide6.QtCore import QObject, Signal, Slot
+
 from pykrait.io.images import read_label_image, get_pixel_contour_from_label_img
 from pykrait.io.files import read_Txnrois
 from pykrait.preprocessing.segmentation import timelapse_projection
-import tifffile
 from pykrait.preprocessing.timeseries_extraction import extract_mean_intensities, get_adjacency_matrix
 from pykrait.trace_analysis.filtering import detrend_with_sinc_filter
-import os
 
 from pykrait.pipeline.pipeline import (
     AnalysisParameters,
@@ -19,7 +22,8 @@ from pykrait.pipeline.pipeline import (
     calculate_periodic_cells,
     calculate_synchronicity,
     save_analysis_results,
-    save_params
+    save_params,
+    create_roi_dataframe
 )
 
 class ExtractIntensitiesWorker(QObject):
@@ -139,10 +143,7 @@ class ExtractIntensitiesWorker(QObject):
 
 class DetrendWorker(QObject):
     """
-    _summary_
-
-    :param QObject: _description_
-    :type QObject: _type_
+    Worker for detrending the mean intensity traces, wraps the `detrend_with_sinc_filter` function.
     """
 
     finished = Signal(np.ndarray)
@@ -164,6 +165,8 @@ class DetrendWorker(QObject):
             )
             self.finished.emit(detrended)
         except Exception as e:
+            tb = traceback.format_exc()
+            print(f"Error during Detrending: {e}\n{tb}")
             self.error.emit(e)
 
 
@@ -189,6 +192,8 @@ class PeakDetectionWorker(QObject):
             result = [peak_series, analysis_output]
             self.finished.emit(result)
         except Exception as e:
+            tb = traceback.format_exc()
+            print(f"Error during Peak Detection: {e}\n{tb}")
             self.error.emit(e)
 
 
@@ -197,7 +202,7 @@ class PeriodicCellWorker(QObject):
     Worker for finding oscillating ROIs in the peak series, wraps the `find_oscillating_rois` function.
     """
 
-    finished = Signal(AnalysisOutput, np.ndarray, np.ndarray)
+    finished = Signal(AnalysisOutput, np.ndarray, np.ndarray, pd.DataFrame)
     error = Signal(Exception)
 
     def __init__(self, peaks: np.ndarray, analysis_params, analysis_output):
@@ -211,8 +216,12 @@ class PeriodicCellWorker(QObject):
             analysis_output, stds, covs = calculate_periodic_cells(
                 self.peaks, self.analysis_params, self.analysis_output
             )
-            self.finished.emit(analysis_output, stds, covs)
+            roi_dataframe = create_roi_dataframe(self.peaks, stds, covs, analysis_output)
+
+            self.finished.emit(analysis_output, stds, covs, roi_dataframe)
         except Exception as e:
+            tb = traceback.format_exc()
+            print(f"Error during Periodicity Analysis: {e}\n{tb}")
             self.error.emit(e)
 
 
@@ -236,6 +245,8 @@ class AdjacencyMatrixWorker(QObject):
             )
             self.finished.emit(adjacency_matrix, shortest_path_matrix)
         except Exception as e:
+            tb = traceback.format_exc()
+            print(f"Error during Neighbourhood Analysis: {e}\n{tb}")
             self.error.emit(e)
 
 
@@ -264,6 +275,8 @@ class SynchronicityWorker(QObject):
             )
             self.finished.emit(results)
         except Exception as e:
+            tb = traceback.format_exc()
+            print(f"Error during Synchronicity Analysis: {e}\n{tb}")
             self.error.emit(e)
 
 
@@ -287,6 +300,7 @@ class AnalysisSaveWorker(QObject):
         intensities: np.ndarray,
         stds: np.ndarray = None,
         covs: np.ndarray = None,
+        roi_dataframe = None,
         overwrite: bool = False,
     ):
         super().__init__()
@@ -301,6 +315,7 @@ class AnalysisSaveWorker(QObject):
         self.overwrite = overwrite
         self.stds = stds
         self.covs = covs
+        self.roi_dataframe = roi_dataframe
 
     def run(self):
         try:
@@ -315,9 +330,12 @@ class AnalysisSaveWorker(QObject):
                 intensities=self.intensities,
                 stds=self.stds,
                 covs=self.covs,
+                roi_dataframe=self.roi_dataframe,
                 overwrite=self.overwrite,
             )
             self.finished.emit(f"Saved to {self.analysis_output.analysis_folder}")
 
         except Exception as e:
+            tb = traceback.format_exc()
+            print(f"Error during Tracing: {e}\n{tb}")
             self.error.emit(e)

{pykrait-0.3.2 → pykrait-0.3.3}/src/pykrait/gui/mainwindow.py

@@ -909,10 +909,11 @@ class MainWindow(QMainWindow):
         self.periodicity_thread.finished.connect(self.periodicity_thread.deleteLater)
         self.periodicity_thread.start()
 
-    def _periodicity_done(self, analysis_output, stds, covs):
+    def _periodicity_done(self, analysis_output, stds, covs, roi_dataframe):
         self.analysis_output = analysis_output
         self.experimental_stds = stds
         self.experimental_covs = covs
+        self.roi_dataframe = roi_dataframe
 
         # Update the labels with periodicity cutoffs and quantiles
         self.cov_cutoff_value_label.setText(
@@ -1061,6 +1062,7 @@ class MainWindow(QMainWindow):
             intensities=self.intensities,
             stds=self.experimental_stds,
             covs=self.experimental_covs,
+            roi_dataframe=self.roi_dataframe,
             overwrite=self.overwrite_checkbox.isChecked(),
         )
         self.analysis_worker.moveToThread(self.analysis_save_thread)