pykrait 0.1.0__py3-none-any.whl

pykrait-0.1.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: pykrait
+Version: 0.1.0
+Summary: Python Calcium Recording Analysis and Inference Toolbox
+Author-email: Pentabyteman <22663502+Pentabyteman@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aicspylibczi>=3.1.1
+Requires-Dist: cellpose>=4.0.5
+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: numpy<2
+Requires-Dist: ome-types>=0.5.3
+Requires-Dist: ome-zarr>=0.10.2
+Requires-Dist: pip>=25.1.1
+Requires-Dist: pydantic<2
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: resource-backed-dask-array>=0.1.0
+Requires-Dist: scikit-image>=0.25.2
+Requires-Dist: scipy>=1.15.3
+Requires-Dist: tifffile<2023.3.15,>=2021.8.30
+Requires-Dist: wrapt>=1.17.2
+Requires-Dist: xarray>2025
+Requires-Dist: xmlschema>=4.0.1
+Requires-Dist: zarr<2.16.0,>=2.6
+Description-Content-Type: text/markdown
+
+# pyKrait - Python Calcium Recording Analysis and Inference Toolbox
+
+![Logo](docs/logo.png)
+
+## Overview
+
+**pyKrait** is a Python package designed to facilitate automated analysis of calcium imaging data. 
+
+## Installation
+
+```bash
+pip install pykrait
+```
+
+## Documentation
+
+See the [docs](docs/) folder for detailed guides and API reference.
+
+## License
+
+This project is licensed under the GNU Lesser General Public License (GLP). See the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please open issues or submit pull requests.

pykrait-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+src/pykrait/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+src/pykrait/io/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/pykrait/io/io.py,sha256=XdFX-QoZZmYa1_fR1QctiDGqclVtfjNbay1aitZRiv8,4943
+src/pykrait/pipeline/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+src/pykrait/pipeline/pipeline.py,sha256=UbQzX-6kyoBbyydlX9ZwanWRen5uoL53brMjpyVMrr8,15933
+src/pykrait/preprocessing/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+src/pykrait/preprocessing/segmentation.py,sha256=VFa6jNYfTMIE4-FFeO972hWCVJfzmCoQZFKt56anMKM,7049
+src/pykrait/preprocessing/timeseries_extraction.py,sha256=QHGIZiY9sjkVHJzFqHQz6o2cG31OSojVjxvQC3pikEY,15421
+src/pykrait/trace_analysis/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+src/pykrait/trace_analysis/filtering.py,sha256=6MWumFKfhK9qfeK1Xt-Koj4GYqoGvI_OxDealEPEkJU,4710
+src/pykrait/trace_analysis/oscillations.py,sha256=vBYRbSibe4Rc7DcMeIjwlLF9n2JMCwSooXP3LM1gWUg,5972
+src/pykrait/trace_analysis/peak_analysis.py,sha256=VHDeZXcWkFy9I06U6LQLYhhnmQkuWIcfNI8R9giVTCw,1214
+pykrait-0.1.0.dist-info/METADATA,sha256=LF7h7DnP-vkMwiF5ba1A7-veMhCn7Pfh_P-F-H50hw8,1534
+pykrait-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pykrait-0.1.0.dist-info/licenses/LICENSE,sha256=l7NeCNGO7EoJzehxXcQ4Gln1go8n95u6RwwWYNk2OAc,1068
+pykrait-0.1.0.dist-info/RECORD,,

pykrait-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pykrait-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pentabyteman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/pykrait/__init__.py

@@ -0,0 +1 @@
+

src/pykrait/io/io.py

@@ -0,0 +1,117 @@
+import os
+import xml.etree.ElementTree as ET
+import dask.array as da
+import warnings
+import re
+from aicsimageio import AICSImage
+
+ALLOWED_IMAGE_EXTENSIONS =[".czi", ".tif", ".tiff"]
+
+def load_timelapse_lazy(
+    file_path: str,
+) -> list[da.Array, float, float, float]:
+    """Load a timelapse image file lazily using AICSImageIO, returning a Dask array of the image data along with the frame interval and pixel sizes.
+
+    Currently supports CZI and TIF/TIFF files. The image data is returned as a Dask array with shape (T, C, Y, X) where T is time, C is channels, Y is height, and X is width. The Z dimension is dropped if it has only one slice.
+
+    :param file_path: input file path to the timelapse image file
+    :type file_path: str
+    :raises TypeError: if filepath is not a string
+    :raises FileNotFoundError: if the file does not exist
+    :raises ValueError: if the extension is not supported
+    :raises ValueError: if the image does not have the expected 5D shape (TCZYX)
+    :raises ValueError: if the image has more than one Z slice and Z cannot be automatically dropped
+    :return: returns a list of a Dask array containing the image data, the frame interval in seconds, and pixel sizes in micrometers (Y, X)
+    :rtype: list[da.Array, float, float, float]
+    """
+    if not isinstance(file_path, str):
+        raise TypeError("file_path must be a string")
+    
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+    
+    ext = os.path.splitext(file_path)[-1].lower()
+    if ext not in ALLOWED_IMAGE_EXTENSIONS:
+        raise ValueError(f"Image to load has the unsupported file format '{ext}'. Supported file formats are: {ALLOWED_IMAGE_EXTENSIONS}")
+
+    # Load with AICSImage using Dask
+    img = AICSImage(file_path, reconstruct_mosaic=False)
+
+    # extract the relevant metadata
+    pixel_sizes = img.physical_pixel_sizes  # Units are in micrometers (µm)
+    y_um = round(pixel_sizes.Y, 2) if pixel_sizes else None
+    x_um = round(pixel_sizes.X, 2) if pixel_sizes else None
+
+    frame_interval = None
+
+    # accessing frame interval from tif/tiff meadata
+    if ext == ".tiff" or ext == ".tif":
+        try:
+            match = re.search(r"finterval=([0-9.]+)", img.metadata)
+            raw_finterval = float(match.group(1))
+            frame_interval = round(raw_finterval, 2) # Output: 1.26
+        except Exception as e:
+            warnings.warn(
+                f"Failed to extract frame interval from TIFF/TIF metadata: {type(e).__name__}: {e}", 
+                UserWarning
+            )
+
+    # accessing frame interval from czi metadata
+    elif ext == ".czi":
+        try:
+            frame_time_elem = img.metadata.findall(".//FrameTime")
+            # select the last FrameTime element if there are multiple and round to 2 decimal places
+            frame_interval = round(float(frame_time_elem[-1].text), 2)
+        except Exception as e:
+            warnings.warn(
+                f"Failed to extract frame interval from CZI metadata: {type(e).__name__}: {e}", 
+                UserWarning
+            )
+
+    # trying to extract frame interval from OME-XML metadata
+    else:
+        try:
+            root = ET.fromstring(img.ome_metadata)
+            namespace = {'ome': 'http://www.openmicroscopy.org/Schemas/OME/2016-06'}
+            pixels_elem = root.find('.//ome:Pixels', namespaces=namespace)
+            if pixels_elem is not None and 'TimeIncrement' in pixels_elem.attrib:
+                frame_interval = float(pixels_elem.attrib['TimeIncrement'])
+        except Exception as e:
+            warnings.warn(
+            f"Failed to extract frame interval from OME-XML: {type(e).__name__}: {e}", 
+            UserWarning
+            )
+    
+    dask_img = img.dask_data  # TCZYX
+
+    if dask_img.ndim != 5:
+        raise ValueError(f"Expected 5D image (TCZYX), but got shape {dask_img.shape}")
+
+    T, C, Z, Y, X = dask_img.shape
+
+    if Z == 1:
+        dask_img = dask_img[:, :, 0, :, :]  # shape: (T, C, Z, Y, X)
+    else:
+        raise ValueError(f"Cannot drop Z dimension automatically: Z={Z}. Consider handling it explicitly.")
+
+    print(f"Returning lazy array of shape {dask_img.shape} (T, C, Y, X)")
+    return dask_img, frame_interval, y_um, x_um
+
+def get_files_from_folder(
+    folder: str,
+    extension: str = ".czi",
+) -> list[str]:
+    """returns all files from a folder with specified extensions.
+
+    :param folder: path to the folder
+    :type folder: str
+    :param extensions: str of file extension (default is ".czi")
+    :type extensions: str
+    :return: list of file paths with the specified extensions
+    :rtype: list[str]
+    """
+    if not os.path.isdir(folder):
+        raise NotADirectoryError(f"Provided path is not a directory: {folder}")
+
+    files = [os.path.join(folder, f) for f in os.listdir(folder) if os.path.isfile(os.path.join(folder, f)) and os.path.splitext(f)[-1].lower() == extension]
+    return files

src/pykrait/pipeline/__init__.py

@@ -0,0 +1 @@
+

src/pykrait/pipeline/pipeline.py

@@ -0,0 +1,266 @@
+import pandas as pd
+import numpy as np
+import warnings
+from pykrait.io.io import load_timelapse_lazy, get_files_from_folder
+from pykrait.preprocessing.segmentation import create_cellpose_segmentation, timelapse_projection
+from pykrait.preprocessing.timeseries_extraction import extract_mean_intensities, extract_cell_properties, get_adjacency_matrix
+from pykrait.trace_analysis.filtering import detrend_with_sinc_filter
+from pykrait.trace_analysis.peak_analysis import find_peaks
+from pykrait.trace_analysis.oscillations import find_oscillating_rois_from_peak_series
+from dataclasses import dataclass, asdict
+from typing import Literal
+import os
+import tifffile
+
+
+@dataclass
+class AnalysisParameters:
+    """This dataclass holds the modifiable parameters for calcium video analysis.
+
+    :var tproj_type: Type of projection accross T-axis to be used for segmentation; 'std' computes standard deviation, 'sum' computes temporal sum, defaults to std.
+    :vartype tproj_type: Literal['std', 'sum'], optional
+
+    :var CLAHE_normalize: whether to apply CLAHE (Contrast Limited Adaptive Histogram Equalization) normalization to enhance image contrast.
+    :vartype CLAHE_normalize: bool, optional
+
+    :var cellpose_model_path: Path to the Cellpose model used for segmentation. Defaults to "cpsam" for the built-in CPSAM model.
+    :vartype cellpose_model_path: str, optional
+
+    :var frame_interval: time interval between consecutive video frames in seconds, defaults to None. If None provided, the frame interval obtained from the image metadata will be used or it will default to 1 second. The code will output a warning if a frame interval is provided which doesn't match with the metadata frame interval.
+    :vartype frame_interval: float, optional
+
+    :var neighbour_tolerance: Maximum distance in micrometers used to detect neighboring cells. Converted to pixels internally.
+    :vartype neighbour_tolerance: float, optional
+
+    :var sinc_filter_window: Window size for the sinc filter used to detrend the signal, specified in seconds. Converted to frame count internally.
+    :vartype sinc_filter_window: float, optional
+
+    :var peak_min_width: Minimum width at half-maximum of a detected peak in seconds. Converted to frames internally.
+    :vartype peak_min_width: float, optional
+
+    :var peak_max_width: Maximum width at half-maximum of a detected peak in seconds. Converted to frames internally.
+    :vartype peak_max_width: float, optional
+
+    :var peak_prominence: Minimum prominence of a detected peak, defined as the height difference between the peak and its surrounding baseline. Arbitrary units.
+    :vartype peak_prominence: float, optional
+
+    :var peak_min_height: Minimum height of a detected peak in arbitrary units.
+    :vartype peak_min_height: float, optional
+
+    :var std_quantile: Quantile used to threshold based on standard deviation for activity detection.
+    :vartype std_quantile: float, optional
+
+    :var cov_quantile: Quantile used to threshold based on the coefficient of variation for activity detection.
+    :vartype cov_quantile: float, optional
+    """
+    tproj_type: Literal['std', 'sum'] = "std"
+    CLAHE_normalize: bool = True
+    cellpose_model_path: str = "cpsam"
+    frame_interval: float = None
+    neighbour_tolerance: float = 10
+    sinc_filter_window: float = 300
+    peak_min_width: float = 1
+    peak_max_width: float = 40
+    peak_prominence: float = 1000
+    peak_min_height: float = 80
+    std_quantile: float = 0.01
+    cov_quantile: float = 0.01
+    
+
+    def to_pandas(self) -> pd.DataFrame:
+        """Convert the dataclass to a pandas DataFrame."""
+        return pd.DataFrame([asdict(self)])
+
+@dataclass
+class AnalysisOutput:
+    """
+    This dataclass holds the output variables of the pipeline.
+    :var filepath: Path to the calcium imaging video file.
+    :vartype filepath: str
+    :var filename: name of the video file
+    :vartype filename: str
+    :var frame_interval: time interval between frames in seconds
+    :vartype frame_interval: float
+    :var pixel_interval_y: pixel size in y direction in micrometers
+    :vartype pixel_interval_y: float
+    :var pixel_interval_x: pixel size in x direction in micrometers
+    :vartype pixel_interval_x: float
+    :var number_of_cells: number of cells detected in the video
+    :vartype number_of_cells: int
+    :var number_of_frames: number of frames in the video
+    :vartype number_of_frames: int
+    :var normalized_peaks: number of peaks per 100 cells and 10 minutes of recording
+    :vartype normalized_peaks: float
+    :var cells_four_peaks: number of cells with at least 4 peaks detected
+    :vartype cells_four_peaks: int
+    :var std_threshold: calculated threshold for the standard deviation in seconds
+    :vartype std_threshold: float
+    :var random_below_std: number of cells with a standard deviation below the threshold in the random control
+    :vartype random_below_std: int
+    :var experiment_below_std: number of cells with a standard deviation below the threshold in the recording
+    :vartype experiment_below_std: int
+    :var cov_threshold: calculated threshold for the coefficient of variation
+    :vartype cov_threshold: float
+    :var random_below_cov: number of cells with a coefficient of variation below the threshold in the random control
+    :vartype random_below_cov: int
+    :var experiment_below_cov: number of cells with a coefficient of variation below the threshold in the recording
+    :vartype experiment_below_cov: int
+    :var random_1st_neighbour_zscore: z-score of synchronicity of the first neighbours in the random control
+    :vartype random_1st_neighbour_zscore: float
+    :var random_2nd_neighbour_zscore: z-score of synchronicity of the second neighbours in the random control
+    :vartype random_2nd_neighbour_zscore: float
+    :var random_3rd_neighbour_zscore: z-score of synchronicity of the third neighbours in the random control
+    :vartype random_3rd_neighbour_zscore: float
+    :var experiment_1st_neighbour_zscore: z-score of synchronicity of the first neighbours in the recording
+    :vartype experiment_1st_neighbour_zscore: float
+    :var experiment_2nd_neighbour_zscore: z-score of synchronicity of the second neighbours in the recording
+    :vartype experiment_2nd_neighbour_zscore: float
+    :var experiment_3rd_neighbour_zscore: z-score of synchronicity of the third neighbours in the recording
+    :vartype experiment_3rd_neighbour_zscore: float
+    :var pykrait_version: version of the pykrait package used for the analysis
+    :vartype pykrait_version: str
+    :var timestamp: timestamp of the analysis
+    :vartype timestamp: np.datetime64
+    """
+    filepath: str = None
+    filename: str = None
+    frame_interval: float = None
+    pixel_interval_y: float = None
+    pixel_interval_x: float = None
+    number_of_cells: int = None
+    number_of_frames: int = None
+    normalized_peaks: float = None
+    cells_four_peaks: int = None
+    std_threshold: float = None
+    random_below_std: int = None
+    experiment_below_std: int = None
+    cov_threshold: float = None
+    random_below_cov: int = None
+    experiment_below_cov: int = None
+    random_1st_neighbour_zscore: float = None
+    random_2nd_neighbour_zscore: float = None
+    random_3rd_neighbour_zscore: float = None
+    experiment_1st_neighbour_zscore: float = None
+    experiment_2nd_neighbour_zscore: float = None
+    experiment_3rd_neighbour_zscore: float = None
+    pykrait_version: str = None
+    timestamp: np.datetime64 = None
+
+    def to_pandas(self):
+        """Convert the dataclass to a pandas DataFrame."""
+        return pd.DataFrame([asdict(self)])
+    
+
+class CalciumVideo():
+    """
+    _summary_
+    """
+    def __init__(self, video_path:str, params: AnalysisParameters):
+        """
+        _summary_
+
+        :param video_path: path to the calcium video
+        :type video_path: str
+        :param cellpose_model_path: path to the cellpose model, defaults to "cpsam" to use the built-in cellpose model
+        :type cellpose_model_path: str, optional
+        """
+        self.analysis_parameters = params
+        self.analysis_output = AnalysisOutput(filepath=video_path)
+    
+    def run(self) -> AnalysisOutput:
+        """
+        runs the pipeline according to
+        """
+        self.analysis_output.filename = self.analysis_output.filepath.split("/")[-1]
+        print(f"Running analysis on {self.analysis_output.filename}")
+        # Create analysis folder in the parent directory of the video file
+        parent_dir = os.path.dirname(self.analysis_output.filepath)
+        filename_wo_ext = os.path.splitext(self.analysis_output.filename)[0]
+        analysis_folder = os.path.join(parent_dir, f"Analysis_{filename_wo_ext}")
+        os.makedirs(analysis_folder, exist_ok=True)
+
+        # load image data lazily
+        self.timelapse_data, frame_interval, self.analysis_output.pixel_interval_y, self.analysis_output.pixel_interval_x = load_timelapse_lazy(file_path = self.analysis_output.filepath)
+
+        if frame_interval is None and self.analysis_parameters.frame_interval is None:
+            warnings.warn("No frame interval provided in the analysis parameters, and no frame interval could be inferred from the metadata. Defaulting to 1 second.")
+            self.analysis_output.frame_interval = 1  # Default to 1 second if not provided
+        elif self.analysis_parameters.frame_interval is None and frame_interval is not None:
+            self.analysis_output.frame_interval = frame_interval
+        elif frame_interval is not None and self.analysis_parameters.frame_interval != frame_interval:
+            warnings.warn(f"Provided frame_interval ({self.analysis_parameters.frame_interval}) does not match inferred frame_interval ({frame_interval}) from metadata. Using provided value.")
+
+        # perform the zproj
+        self.zproj = timelapse_projection(self.timelapse_data, method=self.analysis_parameters.tproj_type, normalize=self.analysis_parameters.CLAHE_normalize, verbose=True)
+        tifffile.imwrite(os.path.join(analysis_folder, f"{filename_wo_ext}_zproj.ome.tif"), self.zproj.astype(np.uint16), metadata={'axes': 'CYX'}, compression="zlib")
+
+        # create cellpose segmentation    
+        self.masks = create_cellpose_segmentation(self.zproj, cellpose_model_path=self.analysis_parameters.cellpose_model_path)
+        tifffile.imwrite(os.path.join(analysis_folder, f"{filename_wo_ext}_cp_masks.ome.tif"), self.masks.astype(np.uint16), metadata={'axes': 'YX'}, compression="zlib")
+
+        # extracts the mean intensities of the masks
+        self.mean_intensities = extract_mean_intensities(self.timelapse_data, self.masks)
+        self.analysis_output.number_of_frames, self.analysis_output.number_of_cells = self.mean_intensities.shape
+        
+        self.cell_properties = extract_cell_properties(self.masks)
+
+        # convert seconds and µm to frames and pixels
+        neighbour_tolerance_pixels = int(self.analysis_parameters.neighbour_tolerance / self.analysis_output.pixel_interval_x)  # convert micrometers to pixels
+        peak_min_width_frames = int(self.analysis_parameters.peak_min_width / self.analysis_output.frame_interval)  # convert seconds to frames
+        peak_max_width_frames = int(self.analysis_parameters.peak_max_width / self.analysis_output.frame_interval) # convert seconds to frames
+
+        # checking if the parameters are valid
+        if neighbour_tolerance_pixels < 1:
+            warnings.warn(f"Neighbour tolerance of {neighbour_tolerance_pixels} pixels is too small, setting to 1 pixel.")
+            neighbour_tolerance_pixels = 1
+        if peak_min_width_frames < 1:
+            warnings.warn(f"Peak minimum width of {peak_min_width_frames} frames is too small, setting to 1 frame.")
+            peak_min_width_frames = 1
+        if peak_max_width_frames <= peak_min_width_frames:
+            warnings.warn(f"Peak maximum width of {peak_max_width_frames} frames is smaller or equal than peak minimum width of {peak_min_width_frames} seconds, setting to peak minimum width + 1.")
+            peak_max_width_frames = peak_min_width_frames + 1
+        
+        self.adjacency_matrix = get_adjacency_matrix(self.masks, neighbour_tolerance=neighbour_tolerance_pixels)
+
+        self.detrended_timeseries = detrend_with_sinc_filter(signals=self.mean_intensities, 
+                                                             cutoff_period=self.analysis_parameters.sinc_filter_window,
+                                                             sampling_interval=self.analysis_output.frame_interval)
+        
+        self.peak_series = find_peaks(peak_min_width=peak_min_width_frames,
+                                      peak_max_width=peak_max_width_frames,
+                                      peak_prominence=self.analysis_parameters.peak_prominence,
+                                      peak_min_height=self.analysis_parameters.peak_min_height,
+                                      detrended_timeseries=self.detrended_timeseries)
+        
+        peaks_per_100c_per_10_min = (np.sum(self.peak_series) / (self.analysis_output.number_of_cells / 100)) / ((self.analysis_output.number_of_frames * self.analysis_output.frame_interval) / 600) # normalize to 100 cells and 10 minutes of recording
+        self.analysis_output.normalized_peaks = round(peaks_per_100c_per_10_min, 2)
+
+        self.analysis_output.cells_four_peaks = np.sum(np.sum(self.peak_series, axis=0) >= 4)
+        
+        self.analysis_output.std_threshold, self.analysis_output.experiment_below_std, self.analysis_output.random_below_std, self.analysis_output.cov_threshold, self.analysis_output.experiment_below_cov, self.analysis_output.random_below_cov = find_oscillating_rois_from_peak_series(self.peak_series, 
+                                                                                                                                                                                                                                                                                            self.analysis_parameters.std_quantile, 
+                                                                                                                                                                                                                                                                                            self.analysis_parameters.cov_quantile,
+                                                                                                                                                                                                                                                                                            self.analysis_output.frame_interval,
+                                                                                                                                                                                                                                                                                            n_iter=100)
+        # saving the parameters and output to the analysis folder
+        self.analysis_output.to_pandas().to_csv(os.path.join(analysis_folder, f"{filename_wo_ext}_analysis_output.csv"), index=False)
+        self.analysis_parameters.to_pandas().to_csv(os.path.join(analysis_folder, f"{filename_wo_ext}_analysis_parameters.csv"), index=False)
+        return self.analysis_output
+
+
+class BatchExperiment:
+    def __init__(self, folder: str, params: AnalysisParameters, extension:str = ".czi"):
+        files = get_files_from_folder(folder, extension=extension)
+        self.experiments = [CalciumVideo(video_path=video_path, params=params) for video_path in files]
+        self.results = pd.DataFrame()
+
+    def run(self):
+
+        for experiment in self.experiments:
+            result = experiment.run().to_pandas()
+            self.results = pd.concat([self.results, result], ignore_index=True)
+
+
+        
+        
+        

src/pykrait/preprocessing/__init__.py

@@ -0,0 +1 @@
+

src/pykrait/preprocessing/segmentation.py

@@ -0,0 +1,176 @@
+import dask.array as da
+import numpy as np
+import warnings
+import os
+from cellpose import models
+from tqdm.dask import TqdmCallback
+from typing import Literal
+from skimage import exposure
+
+def _scale_to_uint16(arr: np.ndarray) -> np.ndarray:
+    """Wraps skimage's rescale_intensity to convert an array to 16-bit unsigned integer format.
+
+    :param arr: input array
+    :type arr: np.ndarray
+    :return: returns the input array scaled to 16-bit unsigned integer format.
+    :rtype: np.ndarray
+    """
+    return exposure.rescale_intensity(arr, out_range='uint16').astype(np.uint16)
+
+def _fast_time_sum(timelapse: da.Array) -> np.ndarray:
+    T, C, Y, X = timelapse.shape
+
+    # Rechunk T so blocks are as large as memory allows
+    rechunked = timelapse.rechunk({0: "auto"})
+
+    # Reduce each T-chunk to (1, C, Y, X)
+    partial_sums = rechunked.map_blocks(
+        lambda block: block.sum(axis=0, keepdims=True),
+        dtype=timelapse.dtype,
+        chunks=(1, C, Y, X)
+    )
+
+    # Sum across all (1, C, Y, X) blocks
+    final_sum = partial_sums.sum(axis=0)
+
+    return final_sum
+
+def _fast_time_std(timelapse: da.Array) -> np.ndarray:
+    """
+    Efficiently computes standard deviation over the time axis (axis=0) of a T,C,Y,X dask array.
+    Uses Dask-native operations for parallel execution and memory efficiency.
+    
+    :param timelapse: Dask array with shape (T, C, Y, X)
+    :return: Dask array of shape (C, Y, X) with std computed over T
+    """
+    T, C, Y, X = timelapse.shape
+
+    # Rechunk T to optimize chunk sizes
+    rechunked = timelapse.rechunk({0: "auto"})
+
+    # First pass: compute mean per block and total sum
+    partial_sums = rechunked.map_blocks(
+        lambda block: block.sum(axis=0, keepdims=True),
+        dtype=timelapse.dtype,
+        chunks=(1, C, Y, X)
+    )
+    total_sum = partial_sums.sum(axis=0)
+    mean = total_sum / T
+
+    # Second pass: compute squared differences from mean per block
+    def squared_diff_block(block, mean):
+        return ((block - mean) ** 2).sum(axis=0, keepdims=True)
+
+    # Broadcast mean to match chunk shapes
+    partial_squared_diffs = rechunked.map_blocks(
+        squared_diff_block,
+        mean,
+        dtype=timelapse.dtype,
+        chunks=(1, C, Y, X)
+    )
+
+    # Sum all squared diffs and divide by T (or T-1 for sample std)
+    total_squared_diff = partial_squared_diffs.sum(axis=0)
+    std = da.sqrt(total_squared_diff / T)
+
+    return std
+
+def timelapse_projection(lazy_timelapse: da.array, normalize:bool=True, method: Literal["std", "sum"] = "std", verbose: bool = True) -> np.ndarray:
+    """
+    Computes a T-projection of a timelapse to be used for cell segmentation. 
+
+    :param lazy_timelapse: 4D dask array representing the timelapse, with shape order "TCYX".
+    :type lazy_timelapse: da.array
+    :param normalize: If True, applies CLAHE normalization.
+    :type normalize: bool, optional
+    :param method: method to be used for the projection, either "std" or "sum" for sum, defaults to "std"
+    :type method: Literal["std", "sum"], optional, optional
+    :param verbose: whether to output progress bar, defaults to True
+    :type verbose: bool, optional
+    :raises TypeError: if input is not a dask array
+    :raises ValueError: if input does not have 4 dimensions
+    :raises ValueError: if unknown T-proj method
+    :return: 3D "CYX" numpy array containing the standard deviation for each pixel across all frames in 16-bit.
+    :rtype: np.ndarray
+    """    
+
+    # Check if the input is a 4D dask array
+    if not isinstance(lazy_timelapse, da.Array):
+        raise TypeError("Input must be a dask array.")
+
+    if lazy_timelapse.ndim != 4:
+        raise ValueError("Input timelapse must be a 4D array with shape TCYX.")
+    
+    T, C, Y, X = lazy_timelapse.shape
+    if T < C or T > Y or T > X or C > Y or C > X:
+        warnings.warn(f"Input array shape of {lazy_timelapse.shape} is unusual. Is it in TCYX order?", UserWarning)
+    
+    #lazy_timelapse = lazy_timelapse.rechunk({0: -1, 2: "auto", 3: "auto"})
+    if method == "std":
+        if verbose:
+            with TqdmCallback(desc="Computing STD projection"):
+                t_proj = _fast_time_std(lazy_timelapse).compute(scheduler='threads')
+        else:
+            t_proj = _fast_time_std(lazy_timelapse).compute(scheduler='threads')
+        t_proj = np.nan_to_num(t_proj, nan=0.0)  # Replace NaNs with 0
+        t_proj = _scale_to_uint16(t_proj)  # Scale to uint16
+    elif method == "sum":
+        if verbose:
+            with TqdmCallback(desc="Computing SUM projection"):
+                t_proj = _fast_time_sum(lazy_timelapse).compute(scheduler='threads')
+        else:
+            t_proj = _fast_time_sum(lazy_timelapse).compute(scheduler='threads')
+    else:
+        raise ValueError("T-Projection Method must be either 'std' or 'sum'.")
+
+    if normalize:
+        # Enhance contrast per channel (C, Y, X)
+        enhanced = np.empty_like(t_proj)
+        for c in range(t_proj.shape[0]):
+            enhanced[c] = _scale_to_uint16(exposure.equalize_adapthist(t_proj[c]))
+    else:
+        enhanced = _scale_to_uint16(t_proj)
+
+    return enhanced
+
+def create_cellpose_segmentation(image:np.ndarray, cellpose_model_path:str) -> np.ndarray:
+    """
+    Wrapper function to create a label image from an input image using a prespecified cellpose model.
+    
+    :param image: image to be processed with cellpose.
+    :type image: ndarray
+    :param cellpose_model_path: path to the cellpose model file. Can also be cpsam if using cellpose-4 and the standard builtin model.
+    :type cellpose_model_path: str
+
+    :return label_img: The generated label image.
+    :rtype: np.ndarray
+    
+    :raises FileNotFoundError: If the Cellpose model path does not exist.
+    :raises ValueError: If the input std image is not a 2D array.
+    :raises RuntimeError: If the Cellpose model fails to load with both GPU and CPU backends.
+    """
+
+    # check if the model path exists
+    if cellpose_model_path != "cpsam" and not os.path.isfile(cellpose_model_path):
+        raise FileNotFoundError("Cellpose model not found at {}".format(cellpose_model_path))
+    #TODO: check if the model was trained using the same cellpose version
+
+    if image.ndim > 3:
+        raise ValueError("Input image must be a 2D (YX) or 3D (CYX) array but got shape {}".format(image.shape))
+    
+    # setting up the cellpose segmentation, trying GPU first and falling back to CPU if it fails
+    try:
+        model = models.CellposeModel(gpu=True, pretrained_model = cellpose_model_path)
+    except Exception as e:
+        print(f"Error loading Cellpose model wiht GPU backend due to: {e}")
+        try:
+            model = models.CellposeModel(gpu=False, pretrained_model=cellpose_model_path)
+        except Exception as e:
+            raise RuntimeError(f"Failed to load Cellpose model with CPU backend due to: {e}")
+        
+    mask, _, _ = model.eval(image)
+
+    if np.max(mask) == 0:
+        warnings.warn("The generated mask contains only zeros. No cells were detected.", UserWarning)
+
+    return mask

src/pykrait/preprocessing/timeseries_extraction.py

@@ -0,0 +1,329 @@
+import numpy as np
+import pandas as pd
+import warnings
+import dask.array as da
+from dask import delayed, compute
+from tqdm.dask import TqdmCallback
+from scipy.sparse.csgraph import floyd_warshall
+from scipy.spatial import KDTree
+from scipy.sparse import lil_matrix
+from functools import lru_cache
+from skimage.measure import regionprops_table, regionprops
+from skimage.segmentation import find_boundaries
+from scipy.spatial.distance import cdist
+
+def _legacy_extract_mean_intensities(numpy_timelapse:np.ndarray, masks:np.ndarray) -> np.ndarray:
+    """
+    This function computes the mean intensity of each cell across all frames in a timelapse, given a label image that identifies 
+    the regions. It returns a 2D numpy array where each row corresponds to a cell and each column corresponds to a frame, containing the
+    mean intensity of each cell per frame. 
+
+    Note: If the input timelapse has multiple channels, only the first channel (C=0) will be used for intensity calculations. 
+    
+    It expectes the 4D-numpy array with order "TCYX" to be fully loaded into memory. Loading the dataframe into memory and running this function takes more memory and longer than the lazy version.
+
+    :param numpy_timelapse: A 4D-numpy array with order "TCYX", fully loaded into memory. 
+    :type numpy_timelapse: np.ndarray
+    :param masks: A 2D numpy array containing labels for each region as label image.
+    :type masks: np.ndarray
+
+    :return: a cell x time numpy ndarray containing the mean intensity of each cell per frame of shape (n_cells, T).
+    :rtype: np.ndarray
+    """
+    if not isinstance(numpy_timelapse, np.ndarray):
+        raise TypeError("Input must be a numpy array.")
+    if numpy_timelapse.ndim != 4:
+        raise ValueError("Input timelapse must be a 4D array with shape TCYX.")
+    if masks.ndim != 2:
+        raise ValueError("Masks must be a 2D array representing the label image.")
+    if masks.shape[0] != numpy_timelapse.shape[2] or masks.shape[1] != numpy_timelapse.shape[3]:
+        raise ValueError("Masks shape (Y,X: {}, {}) must match the spatial dimensions of the timelapse (Y,X: {}, {}).".format(
+            masks.shape[0], masks.shape[1], numpy_timelapse.shape[2], numpy_timelapse.shape[3]))
+    
+    # check that the timelapse is in TCYX order
+    T, C, Y, X = numpy_timelapse.shape
+    if T < C or T > Y or T > X or C > Y or C > X:
+        warnings.warn(f"Input array shape of {numpy_timelapse.shape} is unusual. Is it in TCYX order?", UserWarning)
+    if C > 1:
+        warnings.warn("Input timelapse has multiple channels. Only the first channel (C=0) will be used for intensity calculations.", UserWarning)
+    
+    video = numpy_timelapse[:,0,:,:].squeeze()  # Ensure it's 3D (T, Y, X)
+
+    roi_properties = regionprops_table(label_image=masks,
+                                       intensity_image=video.transpose(1,2,0),
+                                       properties=("label", "intensity_mean"),
+                                       separator=",")
+    intensity_array = np.array(list(roi_properties.values())[1:])
+    
+    return intensity_array
+
+
+def _compute_mean_for_frame(frame:np.ndarray, masks:np.array) -> np.ndarray:
+    """Helper function to compute the mean intensity of each cell for a single frame.
+    It uses regionprops_table from skimage.measure to compute the mean intensities.
+
+    :param frame: A 4D dask array with order "TCYX", fully loaded into memory.
+    :type frame: np.ndarray
+    :param masks: The label image for the frame.
+    :type masks: np.ndarray    
+
+    :return: a numpy array containing the mean intensity of each cell for the specified timepoint.
+    :rtype: np.ndarray
+    """
+    props = regionprops_table(label_image=masks, intensity_image=frame, properties=("label", "intensity_mean"))
+    return np.array(props["intensity_mean"])
+
+
+def extract_mean_intensities(dask_timelapse:da.Array, masks:np.ndarray, verbose:bool=True) -> np.ndarray:
+    """
+    This function computes the mean intensity of each cell across all frames in a timelapse, given a label image that identifies 
+    the regions.
+
+    Note: If the input timelapse has multiple channels, only the first channel (C=0) will be used for intensity calculations.  
+    It uses dask to lazily compute the mean intensities for each ROI and timepoint and does not load the entire timelapse into memory.
+
+    :param dask_timelapse: A 4D dask array with order "TCYX", fully loaded into memory.
+    :type dask_timelapse: da.Array
+    :param masks: A 2D numpy array containing labels for each region as label image.
+    :type masks: np.ndarray
+    :param verbose: if True, shows the progress bar for the computation.
+    :type verbose: bool
+    :raises TypeError: If the input is not a dask array.
+    :raises ValueError: If the input timelapse is not a 4D array or if the masks do not match the spatial dimensions of the timelapse. 
+
+    :return: a T x n_rois numpy array containing the mean intensity of each cell per frame
+    :rtype: np.ndarray
+    """
+    if not isinstance(dask_timelapse, da.Array):
+        raise TypeError("Input must be a dask array.")
+    if dask_timelapse.ndim != 4:
+        raise ValueError("Input timelapse must be a 4D array with shape TCYX and not shape {}.".format(dask_timelapse.shape))
+    if masks.ndim != 2:
+        raise ValueError("Masks must be a 2D array representing the label image and not shape {}.",format(masks.shape))
+    if masks.shape[0] != dask_timelapse.shape[2] or masks.shape[1] != dask_timelapse.shape[3]:
+        raise ValueError("Masks shape (Y,X: {}, {}) must match the spatial dimensions of the timelapse (Y,X: {}, {}).".format(
+            masks.shape[0], masks.shape[1], dask_timelapse.shape[2], dask_timelapse.shape[3]))
+    # check that the timelapse is in TCYX order
+    T, C, Y, X = dask_timelapse.shape
+    if T < C or T > Y or T > X or C > Y or C > X:
+        warnings.warn(f"Input array shape of {dask_timelapse.shape} is unusual. Is it in TCYX order?", UserWarning)
+    if C > 1:
+        warnings.warn("Input timelapse has multiple channels. Only the first channel (C=0) will be used for intensity calculations.", UserWarning)
+
+    dask_timelapse = dask_timelapse.rechunk({0: 1, 1: 1})
+    n_rois = np.max(masks)
+
+    dask_frames = dask_timelapse[:, 0, :, :]  # shape: (T, Y, X)
+
+    def block_func(block):  # block has shape (1, Y, X)
+        frame = block[0]  # shape (Y, X)
+        means = _compute_mean_for_frame(frame, masks)  # shape (n_rois,)
+        return means[np.newaxis, :]  # shape (1, n_rois)
+
+    mean_dask = da.map_blocks(
+        block_func,
+        dask_frames,
+        dtype=np.float32,
+        chunks=(1, n_rois),   # Must match output shape per block
+        drop_axis=(1, 2),     # Drop Y, X axes
+        new_axis=1            # Add n_rois axis
+    )
+
+    if verbose:
+        with TqdmCallback(desc="Computing mean intensities"):
+            mean_intensities = mean_dask.compute(scheduler="threads")
+    else:
+        mean_intensities = mean_dask.compute(scheduler="threads")
+
+    return mean_intensities  # shape: (T, n_rois)
+
+
+def extract_cell_properties(masks:np.ndarray) -> tuple:
+    """
+    Returns cell properties (area, axis lengths, perimeter) and positions (centroid coordinates) of each cell in the label image.
+
+    
+    :param masks: input label image
+    :type masks: np.ndarray
+
+    :return cell_properties: pandas dataframe of cell properties
+    :rtype cell_properties: pd.DataFrame
+    :return cell_positions: (nd.array of size len(roi) x 2, np.uint16): pixel positions of every roi
+    :rtype cell_positions: np.ndarray
+    """
+
+    cell_properties = regionprops_table(label_image=masks,
+                                        intensity_image=masks,
+                                        properties=("label", "centroid",
+                                                    "intensity_max", "area", 
+                                                    "axis_major_length", 
+                                                    "axis_minor_length", 
+                                                    "perimeter"),
+                                        separator=",")
+    # to get the 0-indexed index array of labels
+    cell_indices = cell_properties['intensity_max'].astype(int) - 1
+
+    cell_properties['label'] = cell_indices
+    cell_properties = pd.DataFrame(cell_properties)
+
+    ypos = cell_properties['centroid,0']
+    xpos = cell_properties['centroid,1']
+
+    # maximum pixel value of masks is number of labels/cells
+    cell_positions = np.zeros((masks.max(), 2), dtype=np.uint16)
+    cell_positions[:, 0] = xpos[cell_indices].astype(np.uint16)
+    cell_positions[:, 1] = ypos[cell_indices].astype(np.uint16)
+
+    return cell_properties, cell_positions
+
+
+def _legacy_get_adjacency_matrix(masks: np.ndarray, neighbour_tolerance: int) -> tuple[np.ndarray, np.ndarray]:
+    """Computes the adjacency matrix and shortest path matrix for the given mask with ROIs using pairwise distances between all boundary pixels.
+
+    :param masks: _description_
+    :type masks: np.ndarray
+    :param neighbour_tolerance: _description_
+    :type neighbour_tolerance: int
+    :return: _description_
+    :rtype: tuple[np.ndarray, np.ndarray]
+    """
+    n_labels = masks.max()
+    adjacency_matrix = np.zeros((n_labels, n_labels), dtype=np.uint8)
+
+    props = regionprops(masks)
+    all_boundary_pixels = []
+    pixel_labels = []
+
+    for region in props:
+        label = region.label
+        region_mask = (masks == label)
+        boundary = find_boundaries(region_mask, mode="outer")
+        coords = np.argwhere(boundary)
+        all_boundary_pixels.append(coords)
+        pixel_labels.extend([label - 1] * len(coords))
+
+    if len(all_boundary_pixels) == 0:
+        shortest_path_matrix = np.triu(floyd_warshall(adjacency_matrix), k=1)
+        return adjacency_matrix, shortest_path_matrix
+
+    all_boundary_pixels = np.vstack(all_boundary_pixels)
+    pixel_labels = np.array(pixel_labels)
+
+    tree = KDTree(all_boundary_pixels)
+    pairs = tree.query_pairs(r=neighbour_tolerance)
+
+    for idx1, idx2 in pairs:
+        label1 = pixel_labels[idx1]
+        label2 = pixel_labels[idx2]
+        if label1 != label2:
+            adjacency_matrix[label1, label2] = 1
+            adjacency_matrix[label2, label1] = 1
+
+    shortest_path_matrix = np.triu(floyd_warshall(adjacency_matrix), k=1)
+    return adjacency_matrix, shortest_path_matrix
+
+
+@lru_cache(maxsize=32)
+def _generate_distance_kernel(neighbour_tolerance: int) -> np.ndarray:
+    """Generates a circular distance kernel for the given neighbour tolerance to identify pixels within bounds
+
+    :param neighbour_tolerance: integer defining the maximum distance between two pixels to be considered neighbours.
+    :type neighbour_tolerance: int
+    :return: returns a 2D numpy array of shape (2 * neighbour_tolerance + 1, 2 * neighbour_tolerance + 1) where each pixel is either 0 or 1, indicating whether the pixel is within the neighbour tolerance.
+    :rtype: np.ndarray
+    """
+    size = 2 * neighbour_tolerance + 1
+    coords = np.indices((size, size)).reshape(2, -1).T
+    center = np.array([[neighbour_tolerance, neighbour_tolerance]])
+    distances = cdist(center, coords).reshape(size, size)
+    return (distances <= neighbour_tolerance).astype(np.uint8)
+
+
+def _process_region(region, masks: np.ndarray, circular_kernel: np.ndarray, kernel_radius:int) -> list:
+    """Helper function to process each region and find pairs of adjacent masks
+
+    :param region: region object from skimage.measure.regionprops
+    :type region: _type_
+    :param masks: label image containing the ROIs for each cell
+    :type masks: np.ndarray
+    :param circular_kernel: kernel used to identify pixels within the neighbour tolerance
+    :type circular_kernel: np.ndarray
+    :param kernel_radius: _description_
+    :type kernel_radius: int
+    :return: returns a list of tuples, where each tuple contains the indices of two adjacent regions (i, j) such that i < j.
+    :rtype: list
+    """
+    h, w = masks.shape
+    label = region.label
+    region_mask = masks == label
+    boundary = find_boundaries(region_mask, mode='outer')
+    ys, xs = np.argwhere(boundary).T
+
+    found_pairs = set()
+
+    for y, x in zip(ys, xs):
+        y_start = max(0, y - kernel_radius)
+        y_end = min(h, y + kernel_radius + 1)
+        x_start = max(0, x - kernel_radius)
+        x_end = min(w, x + kernel_radius + 1)
+
+        patch = masks[y_start:y_end, x_start:x_end]
+
+        ky_start = kernel_radius - (y - y_start)
+        ky_end = ky_start + (y_end - y_start)
+        kx_start = kernel_radius - (x - x_start)
+        kx_end = kx_start + (x_end - x_start)
+
+        mask_patch = circular_kernel[ky_start:ky_end, kx_start:kx_end]
+        visible_labels = np.unique(patch[mask_patch > 0])
+
+        for neighbor_label in visible_labels:
+            if neighbor_label == 0 or neighbor_label == label:
+                continue
+            i, j = label - 1, neighbor_label - 1
+            found_pairs.add((min(i, j), max(i, j)))  # Sort to avoid duplicates
+
+    return list(found_pairs)
+
+
+def get_adjacency_matrix(masks: np.ndarray, neighbour_tolerance: int, verbose: bool=True) -> tuple[np.ndarray, np.ndarray]:
+    """Computes the adjacency matrix and shortest path matrix for ROIs within the neighbour_tolerance in the given mask.
+
+    :param masks: 2D label image where the value of every ROI is equal to its index. A pixel value of 0 indicates the image background.
+    :type masks: np.ndarray
+    :param neighbour_tolerance: maximum distance between two ROIs to still be considered neighbours, in pixels.
+    :type neighbour_tolerance: int
+    :param verbose: if true, prints a progress bar for adjacency matrix construction, defaults to True
+    :type verbose: bool, optional
+    :return: returns a ROI x ROI adjacency matrix, where the element at (i, j) is 1 if ROI i and ROI j are neighbours, and 0 otherwise. Also returns a shortest path matrix, where the element at (i, j) is the length of the shortest path between ROI i and ROI j.
+    :rtype: tuple[np.ndarray, np.ndarray]
+
+    In benchmarking, this function is about 25x faster than the legacy version _legacy_get_adjacency_matrix, which uses cdist to compute the distances between all pairs of ROIs. However, they do not produce exactly the same adjacency matrix. 
+    _legacy_get_adjacency_matrix identifies ca. 1.7% more pairs of adjacent ROIs than this function, which is likely due to edge cases around the kernel radius and the way boundaries are defined here.
+    """
+    n_labels = masks.max()
+    kernel_radius = neighbour_tolerance
+    circular_mask = _generate_distance_kernel(neighbour_tolerance)
+
+    props = regionprops(masks)
+
+    tasks = [
+        delayed(_process_region)(region, masks, circular_mask, kernel_radius)
+        for region in props
+    ]
+
+    # If verbose is True, use TqdmCallback to show progress
+    if verbose:
+        with TqdmCallback(desc="Computing adjacency matrix"):
+            region_pairs = compute(*tasks)
+    else:
+        region_pairs = compute(*tasks)
+
+    adjacency_matrix = lil_matrix((n_labels, n_labels), dtype=np.uint8)
+    for pairs in region_pairs:
+        for i, j in pairs:
+            adjacency_matrix[i, j] = 1
+            adjacency_matrix[j, i] = 1
+
+    shortest_path_matrix = floyd_warshall(adjacency_matrix, directed=False, unweighted=True)
+    return adjacency_matrix.toarray(), np.triu(shortest_path_matrix, k=1)

src/pykrait/trace_analysis/__init__.py

@@ -0,0 +1 @@
+

src/pykrait/trace_analysis/filtering.py

@@ -0,0 +1,114 @@
+import numpy as np
+from math import pi
+from scipy.signal import fftconvolve
+from scipy.ndimage import gaussian_filter1d
+
+def _blackman_sinc_filter_kernel(kernel_window: int, cutoff_freq: float) -> list[float]:
+    """Generates a Blackman windowed sinc filter kernel
+
+    :param kernel_window: window size for the kernel, must be even
+    :type kernel_window: int
+    :param cutoff_freq: cut-off frequency, oscillations of lower frequencies will be blocked
+    :type cutoff_freq: float
+    :return: returns the filter kernel as a list of floats
+    :rtype: list
+
+    See the pyBOAT paper (https://www.biorxiv.org/content/10.1101/2020.04.29.067744v2) and Chapter 16 of the The Scientist and Engineer's Guide to Digital Signal Processing (https://www.dspguide.com/ch16/1.htm) for more details.
+    """
+    if kernel_window % 2 != 0:
+        raise ValueError("Filter kernel window must be even")
+    
+    kernel = np.zeros(kernel_window + 1, dtype=float)
+    midpoint = kernel_window / 2
+
+    for n in range(kernel_window + 1):
+        if n == midpoint:
+            val = 2 * pi * cutoff_freq
+        else:
+            val = np.sin(2 * pi * cutoff_freq * (n - midpoint)) / (n - midpoint)
+        # Apply Blackman window
+        val *= (0.42 - 0.5 * np.cos(2 * pi * n / kernel_window) + 0.08 * np.cos(4 * pi * n / kernel_window))
+        kernel[n] = val
+
+    kernel /= np.sum(kernel)
+    return kernel
+
+def _convolve_signals_with_kernel(signals: np.ndarray, filter_kernel: list) -> np.ndarray:
+    """Convolve a 2D array of signals with a filter kernel using FFT convolution. 
+
+    :param signals: 2D numpy array of shape (T x n_rois)
+    :type signals: np.ndarray
+    :param filter_kernel: kernel to convolve with, must be odd length
+    :type filter_kernel: list
+    :raises ValueError: raises a ValueError if the filter kernel length is not odd
+    :return: 2D numpy array of convolved signals in the shape (T x n_rois)
+    :rtype: np.ndarray
+    """
+    kernel_length = len(filter_kernel)
+    if kernel_length % 2 == 0:
+        raise ValueError("Filter kernel length must be odd")
+
+    # Convert to 1D array if needed
+    filter_kernel = np.asarray(filter_kernel).flatten()
+
+    # Pad signals along time axis (axis=0)
+    left_padding = signals[kernel_length - 1:0:-1, :]
+    right_padding = signals[-2:-kernel_length - 1:-1, :]
+    padded_signals = np.concatenate([left_padding, signals, right_padding], axis=0)
+
+    # Apply convolution along axis=0 (time)
+    convolved = fftconvolve(padded_signals, filter_kernel[:, None], mode='valid', axes=0)
+
+    # Extract center portion to match input shape
+    start = (kernel_length - 1) // 2
+    end = start + signals.shape[0]
+    result = convolved[start:end, :]
+
+    return result
+
+def detrend_with_sinc_filter(
+    signals: np.ndarray,
+    cutoff_period: float,
+    sampling_interval: float
+) -> np.ndarray:
+    """Applies a Blackman-windowd sinc filter to a 2D array of signals to detrend them. Frequencies lower than the cutoff frequency will be blocked, while higher frequencies will pass through unaffected. 
+    
+    See the pyBOAT paper (https://www.biorxiv.org/content/10.1101/2020.04.29.067744v2) and Chapter 16 of the The Scientist and Engineer's Guide to Digital Signal Processing (https://www.dspguide.com/ch16/1.htm) for more details.
+
+    :param signals: 2D numpy array of shape (T x n_rois)
+    :type signals: np.ndarray
+    :param cutoff_period: cutoff period in [time units], lower frequencies will be blocked
+    :type cutoff_period: float
+    :param sampling_interval: sampling interval in [time units] of the signals
+    :type sampling_interval: float
+    :return: returns the detrended signals as a 2D numpy array of shape (T x n_rois)
+    :rtype: np.ndarray
+    """
+    signal_length, _ = signals.shape
+
+    kernel_window = signal_length - 1
+    if kernel_window % 2 != 0:
+        kernel_window -= 1  # Make kernel window even
+
+    cutoff_frequency = sampling_interval / cutoff_period  # Cutoff freq in sampling units
+
+    filter_kernel = _blackman_sinc_filter_kernel(kernel_window, cutoff_frequency)
+    smoothed_signals = _convolve_signals_with_kernel(signals, filter_kernel)
+
+    detrended_signals = signals - smoothed_signals
+    return detrended_signals
+
+def smooth_gauss(signal:np.ndarray, sigma:float) -> np.ndarray:
+    """Applies a Gaussian smoothing filter to the 2D input signal.
+
+    :param signal: 2D numpy array of shape (T x n_rois)
+    :type signal: np.ndarray
+    :param sigma: Standard deviation for the Gaussian kernel.
+    :type sigma: float
+    :return: The smoothed signal of shape (T x n_rois).
+    :rtype: np.ndarray
+    """
+    if sigma <= 0:
+        return signal
+
+    return gaussian_filter1d(signal, sigma, axis=0)

src/pykrait/trace_analysis/oscillations.py

@@ -0,0 +1,114 @@
+import numpy as np
+from typing import Tuple
+
+def calculate_std_cov(peak_series: np.ndarray, frame_interval: float) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    calculates the standard deviation and coefficient of variation (cov) of the peak intervals for each ROI in the peak series.
+
+    :param peak_series: T x n_roi binary array with 1s at the peak locations and 0s elsewhere
+    :type peak_series: np.ndarray
+    :param frame_interval: frame interval in seconds of the recording
+    :type frame_interval: float
+    :return: returns standard deviation (sd) and coefficient of variation (cov) of the peak intervals for each ROI
+    :rtype: Tuple[np.ndarray, np.ndarray]
+    """
+    # could probably be further sped up with proper vectorization
+
+    peak_indices = [np.nonzero(col)[0] for col in peak_series.T]
+    peak_diff = [np.ediff1d(indices) * frame_interval for indices in peak_indices]
+    peak_std = [np.std(row) for row in peak_diff]
+    peak_cov = [np.std(row) / np.mean(row) if len(row) > 1 and np.mean(row) != 0 else np.nan for row in peak_diff]
+
+    return np.asarray(peak_std), np.asarray(peak_cov)
+
+def calculate_std_cov_thresholds(filtered_peak_series:np.ndarray, std_quantile:float, cov_quantile:float, frame_interval:float, n_iter:int=100) -> Tuple[float, float]:
+    """
+    finds the threshold of standard deviation and coefficient of variation for the random control data.
+
+    :param filtered_peak_series: (T x n_roi) binary array with 1s at the peak locations and 0s elsewhere, where n_roi are ROIs with at least 4 peaks
+    :type filtered_peak_series: np.ndarray
+    :param std_quantile: quantile for standard deviation threshold
+    :type std_quantile: float
+    :param cov_quantile: quantile for coefficient of variation threshold
+    :type cov_quantile: float
+    :param n_iter: number of iterations for random control
+    :type n_iter: 100
+    :param frame_interval: frame interval of the recording in seconds
+    :type frame_interval: float
+    :return: returns the standard deviation and coefficient of variation thresholds for the random control data
+    :rtype: Tuple[float, float]
+    """
+    # for the random control, generate a stacked peak series
+    stacked_peak_series = np.hstack([filtered_peak_series] * n_iter)
+    
+    # shuffle each column independently
+    T, n = stacked_peak_series.shape
+    idx = np.argsort(np.random.rand(T, n), axis=0)
+    stacked_peak_series = np.take_along_axis(stacked_peak_series, idx, axis=0)
+
+    # calculate std and cv for each column
+    stds, cvs = calculate_std_cov(stacked_peak_series, frame_interval)
+
+    # calculate the quantiles
+    std_threshold = np.quantile(stds, std_quantile)
+    cov_threshold = np.quantile(cvs, cov_quantile)
+
+    return std_threshold, cov_threshold
+
+def find_oscillating_rois(filtered_peak_series: np.ndarray, std_threshold: float, cov_threshold: float, frame_interval: float) -> Tuple[float, int, int, float, int, int]:
+    """
+    finds the oscillating ROIs based on the standard deviation and coefficient of variation thresholds.
+
+    :param filtered_peak_series: T x n_roi binary array with 1s at the peak locations and 0s elsewhere
+    :type filtered_peak_series: np.ndarray
+    :param std_threshold: threshold for standard deviation of peak intervals
+    :type std_threshold: float
+    :param cov_threshold: threshold for coefficient of variation of peak intervals
+    :type cov_threshold: float
+    :param frame_interval: frame interval in seconds of the recording
+    :type frame_interval: float
+    :return: returns the threshold, number of ROIs above the threshold for experimental data and random control data for std and cov respectively.
+    :rtype: Tuple[float, int, int, float, int, int]
+    """
+
+    # experimental data
+    exp_stds, exp_covs = calculate_std_cov(filtered_peak_series, frame_interval)
+    num_exp_stds = np.sum(exp_stds < std_threshold)
+    num_exp_covs = np.sum(exp_covs < cov_threshold)
+
+    # random control data
+    T, n = filtered_peak_series.shape
+    idx = np.argsort(np.random.rand(T, n), axis=0)
+    shuffled_peak_series = np.take_along_axis(filtered_peak_series, idx, axis=0)
+    rand_stds, rand_covs = calculate_std_cov(shuffled_peak_series, frame_interval)
+    num_rand_stds = np.sum(rand_stds < std_threshold)
+    num_rand_covs = np.sum(rand_covs < cov_threshold)
+
+    return std_threshold, num_exp_stds, num_rand_stds, cov_threshold, num_exp_covs, num_rand_covs
+
+def find_oscillating_rois_from_peak_series(peak_series: np.ndarray, std_quantile: float, cov_quantile: float, frame_interval: float, n_iter: int = 100) -> Tuple[float, int, int, float, int, int]:
+    """
+    finds the oscillating ROIs based on the standard deviation and coefficient of variation thresholds.
+
+    :param peak_series: T x n_roi binary array with 1s at the peak locations and 0s elsewhere
+    :type peak_series: np.ndarray
+    :param std_quantile: quantile for standard deviation threshold
+    :type std_quantile: float
+    :param cov_quantile: quantile for coefficient of variation threshold
+    :type cov_quantile: float
+    :param n_iter: number of iterations for random control
+    :type n_iter: int
+    :param frame_interval: frame interval in seconds of the recording
+    :type frame_interval: float
+    :return: returns the threshold, number of ROIs above the threshold for experimental data and random control data for std and cov respectively.
+    :rtype: Tuple[float, int, int, float, int, int]
+    """
+
+    # filter the peak series to only include ROIs with at least 4 peaks
+    filtered_peak_series = peak_series[:, np.sum(peak_series, axis=0) >= 4]
+
+    # calculate the thresholds for standard deviation and coefficient of variation
+    std_threshold, cov_threshold = calculate_std_cov_thresholds(filtered_peak_series, std_quantile, cov_quantile, frame_interval, n_iter)
+
+    # find the oscillating ROIs based on the thresholds
+    return find_oscillating_rois(filtered_peak_series, std_threshold, cov_threshold, frame_interval)

src/pykrait/trace_analysis/peak_analysis.py

@@ -0,0 +1,29 @@
+from scipy.signal import find_peaks as scipy_find_peaks
+import numpy as np
+
+def find_peaks(peak_min_width:int, peak_max_width:int, peak_prominence:float, peak_min_height:float, detrended_timeseries:np.ndarray) -> np.ndarray:
+    """wrapper function for scipy's find_peaks function
+    
+    :param peak_min_width: minimum width at half-maximum of peak in frames
+    :type peak_min_width: int
+    :param peak_max_width: maximum width at half-maxumim of peak in frames
+    :type peak_max_width: int
+    :param peak_prominence: minimum prominence of peak
+    :type peak_prominence: float
+    :param min_peak_height: minimum height of peak
+    :type min_peak_height: float
+    :param timeseries: the timeseries to find the peaks on
+    :type timeseries: ndarray
+
+    :return: returns a (T x n_roi) np.ndarray with 1s at the peak locations and 0s elsewhere
+    :rtype: np.ndarray
+    """
+    
+    peak_series = np.zeros(detrended_timeseries.shape)
+
+    for i in range(0, detrended_timeseries.shape[1]):
+        peaks, _ = scipy_find_peaks(detrended_timeseries[:,i], width = (peak_min_width, peak_max_width), height=peak_min_height, prominence = peak_prominence)
+        peak_series[peaks,i] = 1
+
+    return peak_series
+