ZaksPhysicsLibrary 1.2.2__tar.gz → 1.4.0__tar.gz

{zaksphysicslibrary-1.2.2 → zaksphysicslibrary-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ZaksPhysicsLibrary
-Version: 1.2.2
+Version: 1.4.0
 Summary: Data processing and analysis library for TDT, Oxysoft NIRS, and Terranova EFNMR lab data
 Author: zakgm2
 License-Expression: MIT

{zaksphysicslibrary-1.2.2 → zaksphysicslibrary-1.4.0}/PhysicsLibrary/__init__.py

@@ -7,14 +7,13 @@ Data processing and analysis library for Physics Analysis GUI.
 from importlib.metadata import version as _version, PackageNotFoundError
 
 try:
-    __version__ = _version("PhysicsLibrary")
+    __version__ = _version("ZaksPhysicsLibrary")
 except PackageNotFoundError:
     __version__ = "unknown"
 
 from .file_parser_generic import load_any_file
 
 from .dataset import (
-    choose_file,
     detect_format,
     detect_format_file,
     DataFormat,

{zaksphysicslibrary-1.2.2 → zaksphysicslibrary-1.4.0}/PhysicsLibrary/analysis.py

@@ -14,26 +14,40 @@ from scipy.signal import detrend, find_peaks
 from scipy.optimize import curve_fit
 
 
-def get_zscore_slice(time_array, signal, center_t, window=30):
+def get_zscore_slice(time_array, signal, center_t, window=None, pre=None, post=None):
     """
     Extract and z-score a time window around an event.
 
+    Supports either a symmetric `window` (split evenly before/after
+    center_t, legacy behaviour) or an asymmetric `pre`/`post` pair — e.g.
+    10s before the event and 20s after. If pre/post are given they take
+    precedence over window.
+
     Parameters
     ----------
     time_array : array
     signal : array
     center_t : float
         Event time in seconds
-    window : float
-        Total window size in seconds
+    window : float or None
+        Total window size in seconds, split evenly before/after center_t.
+        Ignored if pre/post are given.
+    pre : float or None
+        Seconds before center_t to include. Defaults to window/2.
+    post : float or None
+        Seconds after center_t to include. Defaults to window/2.
 
     Returns
     -------
     (time segment, z-scored signal)
     """
-    half_win  = window / 2
-    start_idx = np.searchsorted(time_array, center_t - half_win)
-    end_idx   = np.searchsorted(time_array, center_t + half_win)
+    if pre is None or post is None:
+        half_win = (window if window is not None else 30) / 2
+        pre  = pre  if pre  is not None else half_win
+        post = post if post is not None else half_win
+
+    start_idx = np.searchsorted(time_array, center_t - pre)
+    end_idx   = np.searchsorted(time_array, center_t + post)
 
     seg_y = signal[start_idx:end_idx]
     seg_x = time_array[start_idx:end_idx]
@@ -41,8 +55,11 @@ def get_zscore_slice(time_array, signal, center_t, window=30):
     # Clip extreme artefacts before z-scoring so outliers don't dominate the baseline std.
     seg_y = np.clip(seg_y, -5, 5)
 
-    baseline_end    = len(seg_y) // 2
-    baseline_period = seg_y[:baseline_end]
+    # Baseline is the pre-event portion — the part of the window that
+    # actually precedes the event, not just "the first half of the segment"
+    # (those differ once pre != post).
+    baseline_mask   = seg_x < center_t
+    baseline_period = seg_y[baseline_mask] if baseline_mask.any() else seg_y
     mu  = np.mean(baseline_period)
     std = np.std(baseline_period)
 
@@ -95,7 +112,7 @@ def bin_for_heatmap(z_seg, num_bins=300):
     return np.array([np.mean(z_seg[bin_edges[i]:bin_edges[i+1]]) for i in range(num_bins)])
 
 
-def compute_fft_slice(time_array, signal, center_t, fs, window=30):
+def compute_fft_slice(time_array, signal, center_t, fs, window=None, pre=None, post=None):
     """
     Extract a time window around center_t and compute its FFT.
 
@@ -103,6 +120,10 @@ def compute_fft_slice(time_array, signal, center_t, fs, window=30):
     the DC spike and slow drift, making physiological frequencies
     (breathing ~0.3 Hz, heart rate ~1 Hz) visible.
 
+    Supports either a symmetric `window` (split evenly before/after
+    center_t, legacy behaviour) or an asymmetric `pre`/`post` pair. If
+    pre/post are given they take precedence over window.
+
     Parameters
     ----------
     time_array : array
@@ -111,8 +132,13 @@ def compute_fft_slice(time_array, signal, center_t, fs, window=30):
         Center time in seconds
     fs : float
         Sampling frequency in Hz
-    window : float
-        Total window size in seconds
+    window : float or None
+        Total window size in seconds, split evenly before/after center_t.
+        Ignored if pre/post are given.
+    pre : float or None
+        Seconds before center_t to include. Defaults to window/2.
+    post : float or None
+        Seconds after center_t to include. Defaults to window/2.
 
     Returns
     -------
@@ -121,9 +147,13 @@ def compute_fft_slice(time_array, signal, center_t, fs, window=30):
     seg_x : array
     seg_y : array
     """
-    half_win  = window / 2
-    start_idx = np.searchsorted(time_array, center_t - half_win)
-    end_idx   = np.searchsorted(time_array, center_t + half_win)
+    if pre is None or post is None:
+        half_win = (window if window is not None else 30) / 2
+        pre  = pre  if pre  is not None else half_win
+        post = post if post is not None else half_win
+
+    start_idx = np.searchsorted(time_array, center_t - pre)
+    end_idx   = np.searchsorted(time_array, center_t + post)
 
     seg_y = signal[start_idx:end_idx]
     seg_x = time_array[start_idx:end_idx]

{zaksphysicslibrary-1.2.2 → zaksphysicslibrary-1.4.0}/PhysicsLibrary/dataset.py

@@ -2,8 +2,8 @@
 dataset.py
 ----------
 The universal Dataset container returned by every loader, plus format
-detection and folder selection. No parsing logic lives here — that's in
-loaders/.
+detection. No parsing logic lives here — that's in loaders/. No GUI
+concerns either — folder/file selection is a caller responsibility.
 """
 
 from __future__ import annotations
@@ -11,33 +11,11 @@ from __future__ import annotations
 import os
 from dataclasses import dataclass, field
 from enum import Enum, auto
-from tkinter import filedialog
 from typing import Optional
 
 import numpy as np
 
 
-# ---------------------------------------------------------------------------
-# Folder selection
-# ---------------------------------------------------------------------------
-
-def choose_file(parent_window=None) -> tuple[Optional[str], Optional[str]]:
-    """
-    Opens a native folder selection dialog.
-
-    Returns
-    -------
-    (folder_path, folder_name)  or  (None, None) if cancelled.
-    """
-    folder_path = filedialog.askdirectory(
-        parent=parent_window,
-        title="Open Lab Data Folder",
-    )
-    if not folder_path:
-        return None, None
-    return folder_path, os.path.basename(folder_path)
-
-
 # ---------------------------------------------------------------------------
 # Universal output struct
 # ---------------------------------------------------------------------------

zaksphysicslibrary-1.4.0/PhysicsLibrary/processing_TDT.py

@@ -0,0 +1,387 @@
+"""
+processing_TDT.py
+-----------------
+Signal processing pipeline for TDT (Tucker-Davis Technologies) fibre photometry data.
+
+Handles loading, bleaching correction, denoising, and event marker extraction.
+Depends on the `tdt` Python SDK for reading tank files.
+"""
+
+import os
+
+import numpy as np
+from scipy.optimize import curve_fit
+from scipy.signal import butter, filtfilt
+import tdt
+
+from .models import double_exponential_model as double_exponential
+
+
+def validate_tdt_folder(path):
+    """
+    Validate whether a directory contains a TDT recording block.
+
+    Parameters
+    ----------
+    path : str
+        Path to the TDT data folder.
+
+    Returns
+    -------
+    tuple
+        (bool, str)
+        - True + folder name if valid
+        - False + error message if invalid
+    """
+    if not path:
+        return False, "No folder selected."
+
+    has_tbk = any(fname.endswith('.Tbk') for fname in os.listdir(path))
+
+    if has_tbk:
+        return True, os.path.basename(path)
+    else:
+        return False, "Invalid Folder: No TDT block files (.Tbk) found."
+
+
+def process_tdt_folder(folder_path):
+    """
+    Full photometry processing pipeline for a TDT recording.
+
+    Steps:
+    1. Load TDT block
+    2. Extract 465 nm (signal) and optional 415 nm (reference)
+    3. Perform regression-based motion correction
+    4. Correct photobleaching trend
+    5. Compute ΔF/F
+    6. Denoise signal
+    7. Extract event markers
+
+    Parameters
+    ----------
+    folder_path : str
+        Path to TDT recording folder.
+
+    Returns
+    -------
+    dict
+        Processed signals and metadata:
+        - x: time vector
+        - raw: corrected fluorescence signal
+        - corr: final ΔF/F (denoised)
+        - dff: same as corr (alias)
+        - f0: bleaching baseline
+        - fs: sampling frequency
+        - store: signal label
+        - markers: behavioral event markers
+    """
+    data_struct = get_tdt_struct(folder_path)
+    streams = data_struct.streams.keys()
+
+    name_465 = next((s for s in streams if '465' in s), None)
+    name_415 = next((s for s in streams if '415' in s), None)
+
+    if not name_465:
+        raise ValueError("No 465 signal found")
+
+    x, y_465, fs = get_plot_data(data_struct, name_465)
+
+    if name_415:
+        _, y_415, _ = get_plot_data(data_struct, name_415)
+        p = np.polyfit(y_415, y_465, 1)
+        y_fit = np.polyval(p, y_415)
+        y_final = y_465 - y_fit
+        display_name = f"Corrected {name_465} (via {name_415})"
+    else:
+        y_final = y_465
+        display_name = f"{name_465} (Uncorrected)"
+
+    _, trend = correct_bleaching(y_final, fs)
+
+    f0  = np.maximum(trend, 1e-6)
+    dff = (y_final - f0) / f0
+    dff = denoise_signal(dff, fs, cutoff=5)
+
+    return {
+        "x":       x,
+        "raw":     y_final,
+        "corr":    dff,
+        "dff":     dff,
+        "f0":      f0,
+        "fs":      fs,
+        "store":   display_name,
+        "markers": get_event_markers(data_struct),
+    }
+
+
+def get_tdt_struct(path):
+    """
+    Load a Tucker-Davis Technologies (TDT) recording block.
+
+    Streams and scalars are read in a single call (unaffected by the issue
+    below). Epoc stores are auto-discovered from the block's own headers
+    and then read ONE STORE AT A TIME, each with its own fresh
+    tdt.read_block() call:
+
+    - The `tdt` SDK has a bug where reading multiple epoc stores together
+      breaks if any store has a mismatched onset/offset count (e.g. a
+      strobe/epoch that was still active when the recording was stopped —
+      a completely normal way for a session to end). Reading one store per
+      call sidesteps it; a store that still fails to a genuine data issue
+      is skipped with a warning rather than crashing the entire load.
+    - Store names must come from each store's own `.name` attribute, not
+      the header dict's key — TDT sanitizes store codes containing `/`
+      into a trailing-underscore Python attribute name (e.g. dict key
+      "EE1_" but the real store code passed to `store=` is "EE1/").
+    - Epoc reads must NOT reuse the cached `headers=` object from the
+      initial header scan — doing so carries over the same mismatched
+      onset/offset state that causes the crash in the first place. Only
+      the streams/scalars read benefits from header reuse.
+
+    This entirely auto-discovers whatever stores a given recording
+    contains — nothing about store names/types is hardcoded, so it works
+    for any TDT block regardless of how it was configured in Synapse.
+
+    Parameters
+    ----------
+    path : str
+        Folder containing TDT data.
+
+    Returns
+    -------
+    object
+        Parsed TDT data structure (data.streams, data.epocs, data.scalars).
+    """
+    import warnings
+
+    heads = tdt.read_block(path, headers=1)
+    if heads is None:
+        raise Exception("TDT returned an empty object.")
+
+    data = tdt.read_block(path, headers=heads, evtype=['streams', 'scalars'], verbose=0)
+    if data is None:
+        raise Exception("TDT returned an empty object.")
+
+    epoc_stores = [(key, s.name) for key, s in heads.stores.items()
+                   if getattr(s, 'type_str', None) == 'epocs']
+
+    for key, real_name in epoc_stores:
+        try:
+            # No headers= reuse here — see docstring.
+            ep = tdt.read_block(path, store=real_name, evtype=['epocs'], verbose=0)
+        except Exception as e:
+            warnings.warn(
+                f"Skipping epoc store '{key}' ({real_name}): {e}",
+                RuntimeWarning, stacklevel=2,
+            )
+            continue
+        if not ep.epocs:
+            continue
+        store_key = next(iter(ep.epocs.keys()))
+        setattr(data.epocs, key, ep.epocs[store_key])
+
+    return data
+
+
+def get_plot_data(data, store_name, channel=0, max_points=None):
+    """
+    Extract time-series data from a TDT stream.
+
+    Parameters
+    ----------
+    data : object
+        TDT data structure
+    store_name : str
+        Stream name (e.g., 'x465A')
+    channel : int
+        Channel index
+    max_points : int or None
+        Optional downsampling limit
+
+    Returns
+    -------
+    tuple
+        (time array, signal array, sampling frequency)
+    """
+    stream = data.streams[store_name]
+    fs     = stream.fs
+
+    data_2d = np.atleast_2d(stream.data)
+    if channel >= data_2d.shape[0]:
+        channel = 0
+
+    y_full = data_2d[channel, :]
+
+    if max_points:
+        ds_factor = max(1, len(y_full) // max_points)
+        y = y_full[::ds_factor]
+        x = np.arange(len(y)) * (ds_factor / fs)
+    else:
+        y = y_full
+        x = np.arange(len(y)) / fs
+
+    return x, y, fs
+
+
+def correct_bleaching(y, fs):
+    """
+    Estimate and correct photobleaching using masked curve fitting.
+
+    Returns
+    -------
+    corrected : array
+        Bleaching-corrected signal
+    trend : array
+        Estimated baseline trend
+    """
+    x = np.arange(len(y)) / fs
+
+    threshold = np.median(y)
+    mask = y > threshold
+    x_fit, y_fit = x[mask], y[mask]
+
+    if len(y_fit) < 100:
+        return y, np.zeros_like(y)
+
+    k_guess   = np.percentile(y_fit, 10)
+    total_amp = np.max(y_fit) - k_guess
+    p0        = [total_amp * 0.6, 0.05, total_amp * 0.4, 0.0001, k_guess]
+    lower     = [0, 0, 0, 0, k_guess * 0.8]
+    upper     = [np.inf, 1, np.inf, 0.1, np.max(y_fit)]
+
+    try:
+        popt, _ = curve_fit(double_exponential, x_fit, y_fit, p0=p0,
+                            bounds=(lower, upper), maxfev=10000)
+        trend = double_exponential(x, *popt)
+    except Exception:
+        # curve_fit failed — fall back to log-linear fit as a rough trend estimate
+        import warnings
+        warnings.warn(
+            "correct_bleaching: double-exponential fit failed; falling back to log-linear trend.",
+            RuntimeWarning, stacklevel=2,
+        )
+        coeffs = np.polyfit(x_fit, np.log(np.maximum(y_fit, 1e-6)), 1)
+        trend  = np.exp(np.polyval(coeffs, x))
+
+    corrected = y - trend + trend[0]
+    return corrected, trend
+
+
+def get_event_markers(data):
+    """
+    Extract behavioral event markers from every populated TDT epoc store.
+
+    A recording can easily have a dozen+ epoc stores (I/O strobes, Epoch
+    Event Storage, free-text notes, a 1-second Tick reference, ...) —
+    every one of them becomes its own marker group here, tagged by store
+    name via the 'store' key, so a caller (e.g. a GUI) can let the user
+    toggle each store's markers independently instead of dumping every
+    store onto the plot at once (which overlaps into an unreadable mess).
+
+    Every epoc is a state that goes high (onset) and later low (offset) —
+    for a lever press that's press/release, for a pump or light that's
+    on/off. Both are emitted here, each tagged with a 'phase' key ('high'
+    for onset, 'low' for offset), so a caller can decide per store whether
+    it cares about both edges (e.g. how long the pump ran) or only one
+    (e.g. just the press, not the release) instead of that decision being
+    baked into the library.
+
+    The 'Note' store keeps its original behaviour: each onset becomes a
+    marker labeled with the actual note text (from Notes.txt), and has no
+    offset/'low' marker — free-text annotations are instantaneous, not a
+    state with a duration. Every other epoc store gets one 'high' marker
+    per onset and one 'low' marker per offset, both labeled with the store
+    name.
+
+    Nothing about which stores exist is hardcoded — this walks whatever
+    data.epocs actually contains, so it works for any TDT block.
+
+    Returns
+    -------
+    list of dict
+        Each dict contains:
+        - time  : float
+        - label : str
+        - color : str
+        - store : str   (source epoc store name, for grouping/toggling)
+        - phase : str   ('high'=onset, 'low'=offset; omitted for Note markers)
+    """
+    if not hasattr(data, 'epocs'):
+        return []
+
+    # Experiment-specific label→colour mapping for Note text; every other
+    # store cycles through a fixed palette so each store gets a distinct,
+    # consistent colour across redraws.
+    note_color_map = {'Clap': 'red', 'Sucrose': 'green', 'Stop': 'blue'}
+    palette = ['black', 'purple', 'orange', 'saddlebrown', 'teal', 'magenta',
+               'darkgreen', 'navy', 'gray', 'olive']
+
+    markers = []
+    store_keys = sorted(k for k in data.epocs.keys())
+
+    for i, store_key in enumerate(store_keys):
+        epoc = data.epocs[store_key]
+        onsets = getattr(epoc, 'onset', [])
+        if len(onsets) == 0:
+            continue
+
+        display_name = store_key.rstrip('_')  # cosmetic: TDT pads slash-containing codes with a trailing "_"
+
+        if store_key == 'Note':
+            notes = getattr(epoc, 'notes', [])
+            for n, t in zip(notes, onsets):
+                note_str = n.decode() if isinstance(n, bytes) else str(n)
+                note_str = note_str.strip()
+                markers.append({
+                    'time':  float(t),
+                    'label': note_str,
+                    'color': note_color_map.get(note_str, 'black'),
+                    'store': display_name,
+                })
+        else:
+            color = palette[i % len(palette)]
+            for t in onsets:
+                markers.append({
+                    'time':  float(t),
+                    'label': display_name,
+                    'color': color,
+                    'store': display_name,
+                    'phase': 'high',
+                })
+            offsets = getattr(epoc, 'offset', [])
+            for t in offsets:
+                # TDT represents a strobe still active at recording end with
+                # offset=inf — not a real timestamp, nothing to plot.
+                if not np.isfinite(t):
+                    continue
+                markers.append({
+                    'time':  float(t),
+                    'label': display_name,
+                    'color': color,
+                    'store': display_name,
+                    'phase': 'low',
+                })
+
+    return markers
+
+
+def denoise_signal(signal, fs, cutoff=5, order=2):
+    """
+    Low-pass Butterworth filter for ΔF/F signals.
+
+    Parameters
+    ----------
+    cutoff : float
+        Cutoff frequency in Hz
+    order : int
+        Filter order
+
+    Returns
+    -------
+    array
+        Filtered signal
+    """
+    nyquist       = fs / 2
+    normal_cutoff = cutoff / nyquist
+    b, a          = butter(order, normal_cutoff, btype='low', analog=False)
+    return filtfilt(b, a, signal)

{zaksphysicslibrary-1.2.2 → zaksphysicslibrary-1.4.0}/ZaksPhysicsLibrary.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ZaksPhysicsLibrary
-Version: 1.2.2
+Version: 1.4.0
 Summary: Data processing and analysis library for TDT, Oxysoft NIRS, and Terranova EFNMR lab data
 Author: zakgm2
 License-Expression: MIT

{zaksphysicslibrary-1.2.2 → zaksphysicslibrary-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ZaksPhysicsLibrary"
-version = "1.2.2"
+version = "1.4.0"
 description = "Data processing and analysis library for TDT, Oxysoft NIRS, and Terranova EFNMR lab data"
 requires-python = ">=3.10"
 readme = "README.md"

zaksphysicslibrary-1.2.2/PhysicsLibrary/processing_TDT.py

@@ -1,273 +0,0 @@
-"""
-processing_TDT.py
------------------
-Signal processing pipeline for TDT (Tucker-Davis Technologies) fibre photometry data.
-
-Handles loading, bleaching correction, denoising, and event marker extraction.
-Depends on the `tdt` Python SDK for reading tank files.
-"""
-
-import os
-
-import numpy as np
-from scipy.optimize import curve_fit
-from scipy.signal import butter, filtfilt
-import tdt
-
-from .models import double_exponential_model as double_exponential
-
-
-def validate_tdt_folder(path):
-    """
-    Validate whether a directory contains a TDT recording block.
-
-    Parameters
-    ----------
-    path : str
-        Path to the TDT data folder.
-
-    Returns
-    -------
-    tuple
-        (bool, str)
-        - True + folder name if valid
-        - False + error message if invalid
-    """
-    if not path:
-        return False, "No folder selected."
-
-    has_tbk = any(fname.endswith('.Tbk') for fname in os.listdir(path))
-
-    if has_tbk:
-        return True, os.path.basename(path)
-    else:
-        return False, "Invalid Folder: No TDT block files (.Tbk) found."
-
-
-def process_tdt_folder(folder_path):
-    """
-    Full photometry processing pipeline for a TDT recording.
-
-    Steps:
-    1. Load TDT block
-    2. Extract 465 nm (signal) and optional 415 nm (reference)
-    3. Perform regression-based motion correction
-    4. Correct photobleaching trend
-    5. Compute ΔF/F
-    6. Denoise signal
-    7. Extract event markers
-
-    Parameters
-    ----------
-    folder_path : str
-        Path to TDT recording folder.
-
-    Returns
-    -------
-    dict
-        Processed signals and metadata:
-        - x: time vector
-        - raw: corrected fluorescence signal
-        - corr: final ΔF/F (denoised)
-        - dff: same as corr (alias)
-        - f0: bleaching baseline
-        - fs: sampling frequency
-        - store: signal label
-        - markers: behavioral event markers
-    """
-    data_struct = get_tdt_struct(folder_path)
-    streams = data_struct.streams.keys()
-
-    name_465 = next((s for s in streams if '465' in s), None)
-    name_415 = next((s for s in streams if '415' in s), None)
-
-    if not name_465:
-        raise ValueError("No 465 signal found")
-
-    x, y_465, fs = get_plot_data(data_struct, name_465)
-
-    if name_415:
-        _, y_415, _ = get_plot_data(data_struct, name_415)
-        p = np.polyfit(y_415, y_465, 1)
-        y_fit = np.polyval(p, y_415)
-        y_final = y_465 - y_fit
-        display_name = f"Corrected {name_465} (via {name_415})"
-    else:
-        y_final = y_465
-        display_name = f"{name_465} (Uncorrected)"
-
-    _, trend = correct_bleaching(y_final, fs)
-
-    f0  = np.maximum(trend, 1e-6)
-    dff = (y_final - f0) / f0
-    dff = denoise_signal(dff, fs, cutoff=5)
-
-    return {
-        "x":       x,
-        "raw":     y_final,
-        "corr":    dff,
-        "dff":     dff,
-        "f0":      f0,
-        "fs":      fs,
-        "store":   display_name,
-        "markers": get_event_markers(data_struct),
-    }
-
-
-def get_tdt_struct(path):
-    """
-    Load a Tucker-Davis Technologies (TDT) recording block.
-
-    Parameters
-    ----------
-    path : str
-        Folder containing TDT data.
-
-    Returns
-    -------
-    object
-        Parsed TDT data structure.
-    """
-    data = tdt.read_block(path)
-    if data is None:
-        raise Exception("TDT returned an empty object.")
-    return data
-
-
-def get_plot_data(data, store_name, channel=0, max_points=None):
-    """
-    Extract time-series data from a TDT stream.
-
-    Parameters
-    ----------
-    data : object
-        TDT data structure
-    store_name : str
-        Stream name (e.g., 'x465A')
-    channel : int
-        Channel index
-    max_points : int or None
-        Optional downsampling limit
-
-    Returns
-    -------
-    tuple
-        (time array, signal array, sampling frequency)
-    """
-    stream = data.streams[store_name]
-    fs     = stream.fs
-
-    data_2d = np.atleast_2d(stream.data)
-    if channel >= data_2d.shape[0]:
-        channel = 0
-
-    y_full = data_2d[channel, :]
-
-    if max_points:
-        ds_factor = max(1, len(y_full) // max_points)
-        y = y_full[::ds_factor]
-        x = np.arange(len(y)) * (ds_factor / fs)
-    else:
-        y = y_full
-        x = np.arange(len(y)) / fs
-
-    return x, y, fs
-
-
-def correct_bleaching(y, fs):
-    """
-    Estimate and correct photobleaching using masked curve fitting.
-
-    Returns
-    -------
-    corrected : array
-        Bleaching-corrected signal
-    trend : array
-        Estimated baseline trend
-    """
-    x = np.arange(len(y)) / fs
-
-    threshold = np.median(y)
-    mask = y > threshold
-    x_fit, y_fit = x[mask], y[mask]
-
-    if len(y_fit) < 100:
-        return y, np.zeros_like(y)
-
-    k_guess   = np.percentile(y_fit, 10)
-    total_amp = np.max(y_fit) - k_guess
-    p0        = [total_amp * 0.6, 0.05, total_amp * 0.4, 0.0001, k_guess]
-    lower     = [0, 0, 0, 0, k_guess * 0.8]
-    upper     = [np.inf, 1, np.inf, 0.1, np.max(y_fit)]
-
-    try:
-        popt, _ = curve_fit(double_exponential, x_fit, y_fit, p0=p0,
-                            bounds=(lower, upper), maxfev=10000)
-        trend = double_exponential(x, *popt)
-    except Exception:
-        # curve_fit failed — fall back to log-linear fit as a rough trend estimate
-        import warnings
-        warnings.warn(
-            "correct_bleaching: double-exponential fit failed; falling back to log-linear trend.",
-            RuntimeWarning, stacklevel=2,
-        )
-        coeffs = np.polyfit(x_fit, np.log(np.maximum(y_fit, 1e-6)), 1)
-        trend  = np.exp(np.polyval(coeffs, x))
-
-    corrected = y - trend + trend[0]
-    return corrected, trend
-
-
-def get_event_markers(data):
-    """
-    Extract behavioral event markers from TDT epoc data.
-
-    Returns
-    -------
-    list of dict
-        Each dict contains:
-        - time
-        - label
-        - color
-    """
-    if not hasattr(data.epocs, 'Note'):
-        return []
-
-    notes  = data.epocs.Note.notes
-    onsets = data.epocs.Note.onset
-
-    # Experiment-specific label→colour mapping; unknown labels default to black.
-    color_map = {'Clap': 'red', 'Sucrose': 'green', 'Stop': 'blue'}
-    markers   = []
-
-    for n, t in zip(notes, onsets):
-        note_str = n.decode() if isinstance(n, bytes) else str(n)
-        note_str = note_str.strip()
-        markers.append({
-            'time':  t,
-            'label': note_str,
-            'color': color_map.get(note_str, 'black'),
-        })
-    return markers
-
-
-def denoise_signal(signal, fs, cutoff=5, order=2):
-    """
-    Low-pass Butterworth filter for ΔF/F signals.
-
-    Parameters
-    ----------
-    cutoff : float
-        Cutoff frequency in Hz
-    order : int
-        Filter order
-
-    Returns
-    -------
-    array
-        Filtered signal
-    """
-    nyquist       = fs / 2
-    normal_cutoff = cutoff / nyquist
-    b, a          = butter(order, normal_cutoff, btype='low', analog=False)
-    return filtfilt(b, a, signal)