ZaksPhysicsLibrary 1.2.2__tar.gz

zaksphysicslibrary-1.2.2/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/PKG-INFO

@@ -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/PhysicsLibrary/__init__.py

@@ -0,0 +1,59 @@
+"""
+PhysicsLibrary
+--------------
+Data processing and analysis library for Physics Analysis GUI.
+"""
+
+from importlib.metadata import version as _version, PackageNotFoundError
+
+try:
+    __version__ = _version("PhysicsLibrary")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+from .file_parser_generic import load_any_file
+
+from .dataset import (
+    choose_file,
+    detect_format,
+    detect_format_file,
+    DataFormat,
+    Dataset,
+)
+
+from .file_parser import (
+    load_dataset,
+    load_dataset_file,
+)
+
+from .loaders.pt2_loader import load_pt2
+
+from .processing_TDT import (
+    process_tdt_folder,
+    validate_tdt_folder,
+    get_tdt_struct,
+    get_plot_data,
+    correct_bleaching,
+    denoise_signal,
+    get_event_markers,
+)
+
+from .analysis import (
+    get_zscore_slice,
+    smooth_signal,
+    bin_for_heatmap,
+    compute_fft_slice,
+    annotate_fft_peaks,
+    compute_slope_segment,
+    fit_model_to_segment,
+)
+
+from .models import (
+    double_exponential_model,
+    visibility_model,
+    linear_model,
+    single_exponential_model,
+    exponential_rise_model,
+    gaussian_model,
+    sinusoidal_model,
+)

zaksphysicslibrary-1.2.2/PhysicsLibrary/analysis.py

@@ -0,0 +1,251 @@
+"""
+analysis.py
+-----------
+Format-agnostic analysis routines for Physics Analysis GUI.
+
+Currently:
+  - Z-Score PETH (get_zscore_slice, smooth_signal, bin_for_heatmap)
+  - FFT (compute_fft_slice, annotate_fft_peaks)
+  - Curve fitting (compute_slope_segment, fit_model_to_segment)
+"""
+
+import numpy as np
+from scipy.signal import detrend, find_peaks
+from scipy.optimize import curve_fit
+
+
+def get_zscore_slice(time_array, signal, center_t, window=30):
+    """
+    Extract and z-score a time window around an event.
+
+    Parameters
+    ----------
+    time_array : array
+    signal : array
+    center_t : float
+        Event time in seconds
+    window : float
+        Total window size in seconds
+
+    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)
+
+    seg_y = signal[start_idx:end_idx]
+    seg_x = time_array[start_idx:end_idx]
+
+    # 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]
+    mu  = np.mean(baseline_period)
+    std = np.std(baseline_period)
+
+    if std < 1e-6:
+        return seg_x, np.zeros_like(seg_y)
+
+    return seg_x, (seg_y - mu) / std
+
+
+def smooth_signal(data, fs, window_sec=0.5):
+    """
+    Moving average smoothing filter.
+
+    Parameters
+    ----------
+    data : array
+    fs : float
+        Sampling frequency in Hz
+    window_sec : float
+        Smoothing window in seconds
+
+    Returns
+    -------
+    array
+        Smoothed signal
+    """
+    window_size = int(fs * window_sec)
+    if window_size % 2 == 0:
+        window_size += 1
+    return np.convolve(data, np.ones(window_size) / window_size, mode='same')
+
+
+def bin_for_heatmap(z_seg, num_bins=300):
+    """
+    Bin a signal into equal segments for heatmap plotting.
+
+    Parameters
+    ----------
+    z_seg : array
+    num_bins : int
+
+    Returns
+    -------
+    array
+        Binned signal
+    """
+    if z_seg is None or len(z_seg) == 0:
+        return np.zeros(num_bins)
+    bin_edges = np.linspace(0, len(z_seg), num_bins + 1).astype(int)
+    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):
+    """
+    Extract a time window around center_t and compute its FFT.
+
+    Applies mean removal and linear detrending before FFT to eliminate
+    the DC spike and slow drift, making physiological frequencies
+    (breathing ~0.3 Hz, heart rate ~1 Hz) visible.
+
+    Parameters
+    ----------
+    time_array : array
+    signal : array
+    center_t : float
+        Center time in seconds
+    fs : float
+        Sampling frequency in Hz
+    window : float
+        Total window size in seconds
+
+    Returns
+    -------
+    freqs : array
+    power : array
+    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)
+
+    seg_y = signal[start_idx:end_idx]
+    seg_x = time_array[start_idx:end_idx]
+
+    if len(seg_y) < 4:
+        return np.array([]), np.array([]), seg_x, seg_y
+
+    seg_y    = detrend(seg_y, type='linear')   # removes mean and linear trend
+    windowed = seg_y * np.hanning(len(seg_y))
+
+    n     = len(windowed)
+    fft_y = np.fft.rfft(windowed)
+    freqs = np.fft.rfftfreq(n, d=1.0 / fs)
+    power = (np.abs(fft_y) ** 2) / n
+
+    return freqs, power, seg_x, seg_y
+
+
+def annotate_fft_peaks(ax_f, freqs, power, color, n_peaks=3):
+    """
+    Find top N peaks in a power spectrum and annotate them with
+    frequency and BPM labels directly on the axes.
+
+    Parameters
+    ----------
+    ax_f   : matplotlib Axes
+    freqs  : array
+    power  : array
+    color  : str
+    n_peaks: int
+    """
+    mask     = freqs >= 0.05
+    f_m      = freqs[mask]
+    p_m      = power[mask]
+    if len(p_m) < 3:
+        return
+    min_prom = 0.05 * p_m.max()
+    peaks, _ = find_peaks(p_m, prominence=min_prom)
+    if len(peaks) == 0:
+        return
+    top = sorted(peaks, key=lambda i: p_m[i], reverse=True)[:n_peaks]
+    for idx in top:
+        freq = f_m[idx]
+        pwr  = p_m[idx]
+        bpm  = freq * 60
+        ax_f.annotate(
+            f"{freq:.2f} Hz\n({bpm:.0f} bpm)",
+            xy=(freq, pwr),
+            xytext=(freq + 0.05, pwr * 0.92),
+            fontsize=7, color=color, fontweight='bold',
+            arrowprops=dict(arrowstyle='->', color=color, lw=0.8),
+        )
+        ax_f.axvline(freq, color=color, lw=0.7, linestyle=':', alpha=0.5)
+
+
+def compute_slope_segment(x_data, y_data, p1_idx, p2_idx, padding_pct=0.05):
+    """
+    Least-squares linear regression slope between two index boundaries.
+
+    Parameters
+    ----------
+    x_data      : array
+    y_data      : array
+    p1_idx      : int
+    p2_idx      : int
+    padding_pct : float   visual context padding
+
+    Returns
+    -------
+    dict with slope, intercept, crop_x, crop_y, x1, y1, x2, y2
+    """
+    idx1, idx2 = sorted([p1_idx, p2_idx])
+
+    fit_x = x_data[idx1:idx2 + 1]
+    fit_y = y_data[idx1:idx2 + 1]
+
+    if len(fit_x) < 2:
+        slope, intercept = 0.0, 0.0
+    else:
+        slope, intercept = np.polyfit(fit_x, fit_y, 1)
+
+    x1, y1 = fit_x[0],  fit_y[0]
+    x2, y2 = fit_x[-1], fit_y[-1]
+
+    pad        = max(5, int(len(x_data) * padding_pct))
+    start_idx  = max(0, idx1 - pad)
+    end_idx    = min(len(x_data) - 1, idx2 + pad)
+
+    return {
+        'slope':     slope,
+        'intercept': intercept,
+        'crop_x':    x_data[start_idx:end_idx + 1],
+        'crop_y':    y_data[start_idx:end_idx + 1],
+        'x1': x1, 'y1': y1,
+        'x2': x2, 'y2': y2,
+    }
+
+
+def fit_model_to_segment(x_seg, y_seg, model_fn, p0_fn):
+    """
+    Fit a model function to a data segment using scipy curve_fit.
+
+    Parameters
+    ----------
+    x_seg    : array
+    y_seg    : array
+    model_fn : callable   f(x, *params) -> y
+    p0_fn    : callable   f(x_seg, y_seg) -> list of initial guesses
+
+    Returns
+    -------
+    dict with popt, y_fit, r2, success, error
+    """
+    try:
+        p0      = p0_fn(x_seg, y_seg)
+        popt, _ = curve_fit(model_fn, x_seg, y_seg, p0=p0, maxfev=10000)
+        y_fit   = model_fn(x_seg, *popt)
+        ss_res  = np.sum((y_seg - y_fit) ** 2)
+        ss_tot  = np.sum((y_seg - y_seg.mean()) ** 2)
+        r2      = 1 - ss_res / ss_tot if ss_tot > 0 else 0.0
+        return {"popt": popt, "y_fit": y_fit, "r2": r2,
+                "success": True, "error": None}
+    except Exception as e:
+        return {"popt": None, "y_fit": np.zeros_like(y_seg),
+                "r2": 0.0, "success": False, "error": str(e)}

zaksphysicslibrary-1.2.2/PhysicsLibrary/dataset.py

@@ -0,0 +1,125 @@
+"""
+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/.
+"""
+
+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
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Dataset:
+    """Universal container returned by every loader."""
+
+    source_format: str                          # 'TDT' | 'Oxysoft'
+    folder_path:   str
+    folder_name:   str
+
+    # timing
+    sample_rate: float = 0.0                    # Hz
+    num_samples: int   = 0
+    duration_s:  float = 0.0                    # seconds
+
+    # signals – shape (num_channels, num_samples)
+    signals: Optional[np.ndarray] = None
+
+    # channel metadata
+    channel_names: list[str] = field(default_factory=list)
+    num_channels:  int       = 0
+
+    # events – list of dicts with at least {'label': str, 'sample': int}
+    events: list[dict] = field(default_factory=list)
+
+    # raw header / metadata blob (format-specific)
+    metadata: dict = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Format detection
+# ---------------------------------------------------------------------------
+
+class DataFormat(Enum):
+    TDT     = auto()
+    OXYSOFT = auto()
+    UNKNOWN = auto()
+
+
+_TDT_EXTENSIONS        = {'.tbk', '.tdx', '.tev', '.tsq', '.sev'}
+_OXYSOFT_HEADER_MARKER = 'Datafile sample rate'
+
+
+def detect_format(folder_path: str) -> DataFormat:
+    """
+    Inspect the contents of *folder_path* and return the matching DataFormat.
+    Priority: TDT first (proprietary extensions), then Oxysoft (.txt marker).
+    """
+    entries    = os.listdir(folder_path)
+    extensions = {os.path.splitext(e)[1].lower() for e in entries}
+
+    if extensions & _TDT_EXTENSIONS:
+        return DataFormat.TDT
+
+    txt_files = [e for e in entries if e.lower().endswith('.txt')]
+    for fname in txt_files:
+        fpath = os.path.join(folder_path, fname)
+        try:
+            with open(fpath, 'r', encoding='utf-8', errors='replace') as fh:
+                for _ in range(30):
+                    if _OXYSOFT_HEADER_MARKER in fh.readline():
+                        return DataFormat.OXYSOFT
+        except OSError:
+            continue
+
+    return DataFormat.UNKNOWN
+
+
+def detect_format_file(file_path: str) -> DataFormat:
+    """
+    Detect the format of a single file (as opposed to a folder).
+    Currently supports Oxysoft .txt exports.
+    """
+    if not file_path.lower().endswith('.txt'):
+        return DataFormat.UNKNOWN
+    try:
+        with open(file_path, 'r', encoding='utf-8', errors='replace') as fh:
+            for _ in range(30):
+                if _OXYSOFT_HEADER_MARKER in fh.readline():
+                    return DataFormat.OXYSOFT
+    except OSError:
+        pass
+    return DataFormat.UNKNOWN

zaksphysicslibrary-1.2.2/PhysicsLibrary/file_parser.py

@@ -0,0 +1,59 @@
+"""
+file_parser.py
+--------------
+Top-level dispatcher: detects the recording format inside a selected
+folder/file and routes to the matching loader, returning a universal
+Dataset struct.
+
+  - TDT  (Tucker-Davis Technologies) – loaders/tdt_loader.py
+  - Oxysoft / Artinis (Oxymon, OctaMon, PortaMon …) – loaders/oxysoft_loader.py
+
+Format detection, the Dataset struct, and folder selection live in
+dataset.py. The .pt2 EFNMR/MRI image format is a standalone parser in
+loaders/pt2_loader.py (it returns a raw image array, not a Dataset).
+
+Usage
+-----
+    from file_parser import detect_format, load_dataset, DataFormat
+
+    fmt = detect_format(folder_path)
+    dataset = load_dataset(folder_path, fmt)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from .dataset import Dataset, DataFormat, detect_format, detect_format_file
+from .loaders.tdt_loader import load_tdt
+from .loaders.oxysoft_loader import load_oxysoft, load_oxysoft_file
+
+
+def load_dataset_file(file_path: str) -> Dataset:
+    """Load a single file and return a Dataset."""
+    fmt = detect_format_file(file_path)
+    if fmt == DataFormat.OXYSOFT:
+        return load_oxysoft_file(file_path)
+    raise ValueError(f"Unrecognised file format: {file_path}")
+
+
+def load_dataset(folder_path: str, fmt: Optional[DataFormat] = None) -> Dataset:
+    """
+    Load a recording folder and return a Dataset.
+    If *fmt* is None, detect_format() is called automatically.
+    """
+    folder_name = os.path.basename(folder_path.rstrip('/\\'))
+
+    if fmt is None:
+        fmt = detect_format(folder_path)
+
+    if fmt is DataFormat.TDT:
+        return load_tdt(folder_path, folder_name)
+    elif fmt is DataFormat.OXYSOFT:
+        return load_oxysoft(folder_path, folder_name)
+    else:
+        raise ValueError(
+            f"Could not identify a supported data format in: {folder_path}\n"
+            "Expected TDT proprietary files (.Tbk/.tev/…) or an Oxysoft .txt export."
+        )