ZaksPhysicsLibrary 1.2.2__py3-none-any.whl

PhysicsLibrary/processing_TDT.py

@@ -0,0 +1,273 @@
+"""
+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)

zaksphysicslibrary-1.2.2.dist-info/METADATA

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: ZaksPhysicsLibrary
+Version: 1.2.2
+Summary: Data processing and analysis library for TDT, Oxysoft NIRS, and Terranova EFNMR lab data
+Author: zakgm2
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zakgm2/PhysicsLibrary
+Project-URL: Repository, https://github.com/zakgm2/PhysicsLibrary
+Project-URL: Changelog, https://github.com/zakgm2/PhysicsLibrary/blob/main/CHANGELOG.md
+Keywords: physics,neuroscience,fibre-photometry,NIRS,TDT,EFNMR,signal-processing
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: tdt
+Dynamic: license-file
+
+# PhysicsLibrary
+
+Data processing and analysis library backing [PhysicsAnalysis](https://github.com/zakgm2/PhysicsAnalysis) — file parsing, signal processing, and curve-fitting logic, with no GUI code of its own. Any interface (tkinter, PyQt6, a script, a notebook) can sit on top of it.
+
+---
+
+## What it does
+
+- **Loads lab data** from three instrument formats plus generic tabular files:
+  - **TDT** (Tucker-Davis Technologies) fibre photometry tanks
+  - **Oxysoft / Artinis** (Oxymon, OctaMon, PortaMon …) NIRS `.txt` exports
+  - **Terranova Prospa** `.pt2` EFNMR/MRI 2D images
+  - Generic **Excel / CSV / TSV / plain text**, with automatic sub-table detection for side-by-side data layouts on one sheet
+- **Processes signals** — bleach correction, denoising, Z-score PETH slicing, FFT with peak annotation, slope/segment analysis
+- **Fits curves** — linear, single/double exponential, exponential rise, Gaussian, sinusoidal, and a photon-entanglement visibility model, all via `scipy.optimize.curve_fit`
+
+---
+
+## Structure
+
+```
+PhysicsLibrary/
+  __init__.py            Public API — see below
+  dataset.py              Dataset struct, DataFormat enum, format detection, folder picker
+  file_parser.py           Top-level dispatcher: load_dataset(), load_dataset_file()
+  file_parser_generic.py    Generic Excel/CSV/TSV/text parser with sub-table detection
+  processing_TDT.py          TDT tank reading, bleach correction, denoising, event markers
+  analysis.py                 PETH/Z-score, FFT, slope segments, curve-fit runner
+  models.py                    Parametric model functions for curve fitting
+  loaders/
+    tdt_loader.py               Wraps processing_TDT into a Dataset
+    oxysoft_loader.py            Oxysoft .txt parsing (folder + single-file) into a Dataset
+    pt2_loader.py                 .pt2 EFNMR/MRI image parser
+```
+
+Each loader/parser is single-purpose and has no knowledge of the others — `file_parser.py` is the only place that ties format detection to the right loader.
+
+---
+
+## Installation
+
+```bash
+pip install git+https://github.com/zakgm2/PhysicsLibrary.git
+```
+
+Or as a dependency in another project's `requirements.txt`:
+
+```
+git+https://github.com/zakgm2/PhysicsLibrary.git
+```
+
+### Requirements
+
+- Python 3.10+
+- `numpy`, `scipy`, `tdt` (installed automatically)
+- `openpyxl` — only needed for `.xlsx`/`.xls` files; imported lazily with a clear error if missing when you actually try to load Excel
+
+---
+
+## Usage
+
+```python
+import PhysicsLibrary as pl
+
+# Detect + load a TDT tank or Oxysoft export folder
+fmt     = pl.detect_format(folder_path)
+dataset = pl.load_dataset(folder_path, fmt)
+
+# Or load a single Oxysoft .txt file directly
+dataset = pl.load_dataset_file(file_path)
+
+# Every loader returns the same universal Dataset struct
+dataset.source_format   # "TDT" | "Oxysoft"
+dataset.sample_rate      # Hz
+dataset.signals            # (num_channels, num_samples)
+dataset.channel_names        # list[str]
+dataset.events                # [{'label': str, 'sample': int}, ...]
+```
+
+```python
+# Generic tabular data (Excel/CSV/TSV/text) — returns one GenericTable per
+# detected sub-table, since a single sheet can contain several side-by-side
+tables = pl.load_any_file(path)
+table  = tables[0]
+table.headers   # list[str]
+table.data      # (n_rows, n_cols) float64, NaN for missing
+
+# Terranova .pt2 EFNMR/MRI image — returns a raw 2D array, not a Dataset
+img = pl.load_pt2(path)   # (n, n) float32
+```
+
+```python
+# Analysis
+x_seg, z = pl.get_zscore_slice(time_array, signal, center_t, window=30)
+freqs, power, seg_x, seg_y = pl.compute_fft_slice(time_array, signal, center_t, fs)
+pl.annotate_fft_peaks(ax, freqs, power, color='blue')   # matplotlib peak labels
+
+# Curve fitting
+result = pl.fit_model_to_segment(x_seg, y_seg, pl.single_exponential_model, p0_fn)
+result["popt"], result["r2"], result["y_fit"]
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for the version history.
+
+---
+
+## Public API
+
+Everything importable from `PhysicsLibrary` directly:
+
+| Category | Names |
+|----------|-------|
+| Format detection | `choose_file`, `detect_format`, `detect_format_file`, `DataFormat`, `Dataset` |
+| Loading | `load_dataset`, `load_dataset_file`, `load_any_file`, `load_pt2` |
+| TDT processing | `process_tdt_folder`, `validate_tdt_folder`, `get_tdt_struct`, `get_plot_data`, `correct_bleaching`, `denoise_signal`, `get_event_markers` |
+| Analysis | `get_zscore_slice`, `smooth_signal`, `bin_for_heatmap`, `compute_fft_slice`, `annotate_fft_peaks`, `compute_slope_segment`, `fit_model_to_segment` |
+| Curve fit models | `linear_model`, `single_exponential_model`, `exponential_rise_model`, `double_exponential_model`, `gaussian_model`, `sinusoidal_model`, `visibility_model` |

zaksphysicslibrary-1.2.2.dist-info/RECORD

@@ -0,0 +1,16 @@
+PhysicsLibrary/__init__.py,sha256=ZbnUc62IWDhTcDnSN8tEmxxxQowjhi4kVk4vk0jZ25c,1129
+PhysicsLibrary/analysis.py,sha256=8LfCTWtkQWqDExhMNT37F8ESxrUZ2PsfEdQ1zzQw82s,6804
+PhysicsLibrary/dataset.py,sha256=ZSwsSqtBGrXhwEooakp3jhVHpjVDufSrrDzAvmyk9M8,3769
+PhysicsLibrary/file_parser.py,sha256=YuTLvR0HSNOm7mS8bRiksApPwwHM7dPntuFEHxDxg34,1975
+PhysicsLibrary/file_parser_generic.py,sha256=MzPkIqY7-v483sBo-dZrJdMAlV-nR2fMcnAg-VXAJ_c,10217
+PhysicsLibrary/models.py,sha256=BPtwDShKEvP87o2-Ad-ooHmuPOnb4BKz5hKptH8jJbQ,1556
+PhysicsLibrary/processing_TDT.py,sha256=V0SiIHTPc9mEd_BRnQIeEjRvRbA51GVjCUmKnmBT6I4,6901
+PhysicsLibrary/loaders/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+PhysicsLibrary/loaders/oxysoft_loader.py,sha256=4wRnVoWK-LRu33eHWGL836Jl25J4iG_nYq7C4Hez9Rk,8411
+PhysicsLibrary/loaders/pt2_loader.py,sha256=TnDT5hJNNERiqSVOnYgkOxQ6T0TJJFZ_vyEXwkH0FZM,1130
+PhysicsLibrary/loaders/tdt_loader.py,sha256=M-ZAPeBWFrmPpodkMech3SxFERKBKDbj0tdvq6K_Xzk,1431
+zaksphysicslibrary-1.2.2.dist-info/licenses/LICENSE,sha256=1XfUUox2uGriPywq9k64eQ9UVdssOD-1TRLkNxmU-9Q,1063
+zaksphysicslibrary-1.2.2.dist-info/METADATA,sha256=rCeDu0sXb_b0bWWLAujkZvFbnBRX8etQNDFIRruMRlg,5738
+zaksphysicslibrary-1.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+zaksphysicslibrary-1.2.2.dist-info/top_level.txt,sha256=fv36T4puLkP8aYfW-W96TYH3SpZ4Gq5jm0J9sYqk3f0,15
+zaksphysicslibrary-1.2.2.dist-info/RECORD,,

zaksphysicslibrary-1.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

zaksphysicslibrary-1.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zakgm2
+
+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.

zaksphysicslibrary-1.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+PhysicsLibrary