ZaksPhysicsLibrary 1.2.2__py3-none-any.whl

PhysicsLibrary/file_parser_generic.py

@@ -0,0 +1,287 @@
+"""
+file_parser_generic.py
+----------------------
+Best-effort parser for arbitrary tabular files.
+
+Supports:
+  .xlsx / .xls  — openpyxl required (pip install openpyxl)
+  .csv          — comma-delimited
+  .tsv          — tab-delimited
+  .txt / .dat / other — delimiter sniffed, then numpy genfromtxt fallback
+
+The key feature is *sub-table detection*: a single sheet or file can contain
+multiple independent tables laid out side-by-side (separated by empty columns)
+or stacked (separated by empty rows).  Each block is returned as a separate
+GenericTable so the user can choose which one to plot.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Public data structure
+# ---------------------------------------------------------------------------
+
+@dataclass
+class GenericTable:
+    name:     str
+    headers:  list[str]
+    data:     np.ndarray        # (n_rows, n_cols) float64; NaN for missing
+    metadata: dict = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def load_any_file(path: str) -> list[GenericTable]:
+    """
+    Parse *path* and return every detected table.
+    Raises ValueError if nothing useful is found.
+    """
+    ext = os.path.splitext(path)[1].lower()
+    if ext in ('.xlsx', '.xls'):
+        return _parse_excel(path)
+    elif ext == '.csv':
+        return _parse_delimited(path, delimiter=',')
+    elif ext == '.tsv':
+        return _parse_delimited(path, delimiter='\t')
+    else:
+        return _parse_text(path)
+
+
+# ---------------------------------------------------------------------------
+# Excel
+# ---------------------------------------------------------------------------
+
+def _parse_excel(path: str) -> list[GenericTable]:
+    try:
+        import openpyxl
+    except ImportError:
+        raise ImportError("Install openpyxl to read .xlsx files:  pip install openpyxl")
+
+    wb = openpyxl.load_workbook(path, data_only=True)
+    tables: list[GenericTable] = []
+
+    for sheet_name in wb.sheetnames:
+        ws = wb[sheet_name]
+        # Load full sheet into a 2-D list, trim trailing all-None rows
+        grid: list[list] = [list(row) for row in ws.iter_rows(values_only=True)]
+        while grid and all(c is None for c in grid[-1]):
+            grid.pop()
+        if not grid:
+            continue
+
+        n_rows = len(grid)
+        n_cols = max(len(r) for r in grid)
+        for r in grid:                          # pad to uniform width
+            while len(r) < n_cols:
+                r.append(None)
+
+        # ── Find empty-column boundaries ──────────────────────────────────
+        empty_col = [
+            all(grid[r][c] is None for r in range(n_rows))
+            for c in range(n_cols)
+        ]
+
+        # Collect contiguous non-empty column spans
+        col_groups: list[tuple[int, int]] = []   # (start_inclusive, end_exclusive)
+        c = 0
+        while c < n_cols:
+            if not empty_col[c]:
+                j = c
+                while j < n_cols and not empty_col[j]:
+                    j += 1
+                col_groups.append((c, j))
+                c = j
+            else:
+                c += 1
+
+        for c_start, c_end in col_groups:
+            sub = _extract_block(grid, n_rows, c_start, c_end)
+            if sub is None:
+                continue
+
+            col_letter_range = f"cols {_col_letter(c_start)}-{_col_letter(c_end - 1)}"
+            tname = (sheet_name if len(col_groups) == 1
+                     else f"{sheet_name} | {col_letter_range}")
+            t = _block_to_table(sub, tname, {'sheet': sheet_name, 'col_start': c_start})
+            if t is not None:
+                tables.append(t)
+
+    return tables
+
+
+def _extract_block(grid: list[list], n_rows: int,
+                   c_start: int, c_end: int) -> Optional[list[list]]:
+    """Slice columns c_start..c_end-1 from grid; trim trailing all-None rows."""
+    sub = [[grid[r][c] for c in range(c_start, c_end)] for r in range(n_rows)]
+    while sub and all(c is None for c in sub[-1]):
+        sub.pop()
+    return sub if len(sub) >= 2 else None
+
+
+def _block_to_table(sub: list[list], name: str, meta: dict) -> Optional[GenericTable]:
+    """
+    Given a 2-D block of raw cells, find the header row, extract numeric data,
+    drop all-NaN rows and columns, and return a GenericTable.
+    """
+    # ── Find header row ────────────────────────────────────────────────────
+    # The header row is the LAST row where >= 50 % of non-None values are strings.
+    header_row = 0
+    for ri, row in enumerate(sub):
+        non_none = [c for c in row if c is not None]
+        if not non_none:
+            continue
+        str_frac = sum(1 for c in non_none if isinstance(c, str)) / len(non_none)
+        if str_frac >= 0.5:
+            header_row = ri
+
+    # ── Build column headers ───────────────────────────────────────────────
+    headers: list[str] = []
+    for ci, val in enumerate(sub[header_row]):
+        if val is not None and str(val).strip():
+            headers.append(str(val).strip())
+        else:
+            # Fall back to nearest non-None value above in the same column
+            label = f"Col{ci + 1}"
+            for prev_ri in range(header_row - 1, -1, -1):
+                pv = sub[prev_ri][ci]
+                if pv is not None and str(pv).strip():
+                    label = str(pv).strip()
+                    break
+            headers.append(label)
+
+    # ── Convert data rows to float ─────────────────────────────────────────
+    data_rows = sub[header_row + 1:]
+    if not data_rows:
+        return None
+
+    float_grid: list[list[float]] = []
+    for row in data_rows:
+        converted = []
+        for v in row:
+            try:
+                converted.append(float(v))   # type: ignore[arg-type]
+            except (TypeError, ValueError):
+                converted.append(float('nan'))
+        float_grid.append(converted)
+
+    arr = np.array(float_grid, dtype=np.float64)
+
+    # Drop all-NaN columns, then all-NaN rows
+    valid_cols = [c for c in range(arr.shape[1]) if not np.all(np.isnan(arr[:, c]))]
+    if not valid_cols:
+        return None
+    arr = arr[:, valid_cols]
+    headers = [headers[c] if c < len(headers) else f"Col{c + 1}" for c in valid_cols]
+
+    valid_rows = [r for r in range(arr.shape[0]) if not np.all(np.isnan(arr[r, :]))]
+    if not valid_rows:
+        return None
+    arr = arr[valid_rows, :]
+
+    return GenericTable(name=name, headers=headers, data=arr, metadata=meta)
+
+
+def _col_letter(i: int) -> str:
+    """0-based column index → Excel column letter (A, B, … Z, AA, AB, …)."""
+    s = ''
+    i += 1
+    while i > 0:
+        i, r = divmod(i - 1, 26)
+        s = chr(65 + r) + s
+    return s
+
+
+# ---------------------------------------------------------------------------
+# CSV / TSV
+# ---------------------------------------------------------------------------
+
+def _parse_delimited(path: str, delimiter: str) -> list[GenericTable]:
+    with open(path, 'r', encoding='utf-8', errors='replace') as fh:
+        rows = [r for r in csv.reader(fh, delimiter=delimiter)]
+    if not rows:
+        return []
+    t = _rows_to_table(rows, os.path.basename(path))
+    return [t] if t is not None else []
+
+
+# ---------------------------------------------------------------------------
+# Plain text (sniff delimiter)
+# ---------------------------------------------------------------------------
+
+def _parse_text(path: str) -> list[GenericTable]:
+    with open(path, 'r', encoding='utf-8', errors='replace') as fh:
+        sample = fh.read(8192)
+
+    # Pick the most-frequent candidate delimiter
+    counts = {'\t': sample.count('\t'), ',': sample.count(','), ';': sample.count(';')}
+    best = max(counts, key=counts.get)
+    if counts[best] > 0:
+        return _parse_delimited(path, best)
+
+    # Last resort: numpy whitespace splitting
+    try:
+        arr = np.genfromtxt(path, comments='#', filling_values=np.nan)
+        if arr.ndim == 1:
+            arr = arr[:, np.newaxis]
+        headers = [f"Col{i + 1}" for i in range(arr.shape[1])]
+        return [GenericTable(name=os.path.basename(path), headers=headers, data=arr)]
+    except Exception:
+        return []
+
+
+# ---------------------------------------------------------------------------
+# Helpers shared by CSV / text paths
+# ---------------------------------------------------------------------------
+
+def _rows_to_table(rows: list[list[str]], name: str) -> Optional[GenericTable]:
+    if not rows:
+        return None
+
+    # Find header row: last row where >= 50 % of non-empty cells are non-numeric
+    header_row = 0
+    for ri, row in enumerate(rows):
+        non_empty = [c for c in row if c.strip()]
+        if not non_empty:
+            continue
+        non_numeric = sum(1 for c in non_empty if not _is_numeric(c))
+        if non_numeric / len(non_empty) >= 0.5:
+            header_row = ri
+
+    headers = [c.strip() or f"Col{i + 1}" for i, c in enumerate(rows[header_row])]
+
+    float_grid: list[list[float]] = []
+    for row in rows[header_row + 1:]:
+        if not any(c.strip() for c in row):
+            continue
+        converted = []
+        for c in row:
+            try:
+                converted.append(float(c))
+            except ValueError:
+                converted.append(float('nan'))
+        float_grid.append(converted)
+
+    if not float_grid:
+        return None
+
+    arr = np.array(float_grid, dtype=np.float64)
+    return GenericTable(name=name, headers=headers, data=arr)
+
+
+def _is_numeric(s: str) -> bool:
+    try:
+        float(s)
+        return True
+    except ValueError:
+        return False
+

PhysicsLibrary/loaders/oxysoft_loader.py

@@ -0,0 +1,235 @@
+"""
+loaders/oxysoft_loader.py
+---------------------------
+Oxysoft / Artinis .txt export parsing (Oxymon, OctaMon, PortaMon, ...).
+
+_parse_oxysoft_txt() is the low-level single-file parser; load_oxysoft()
+concatenates a whole folder of exports; load_oxysoft_file() wraps a
+single file into a Dataset for the "open one file" path.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import Optional
+
+import numpy as np
+
+from ..dataset import Dataset
+
+
+def load_oxysoft(folder_path: str, folder_name: str) -> Dataset:
+    """
+    Parse an Oxysoft TXT export folder.
+    Multiple .txt files are concatenated in alphabetical order.
+    """
+    txt_files = sorted(
+        f for f in os.listdir(folder_path) if f.lower().endswith('.txt')
+    )
+    if not txt_files:
+        raise FileNotFoundError(f"No .txt files found in: {folder_path}")
+
+    all_o2hb:  list[np.ndarray] = []
+    all_hhb:   list[np.ndarray] = []
+    all_events: list[dict]      = []
+    metadata:   dict            = {}
+    ch_labels:  list[str]       = []
+    sample_rate: float          = 0.0
+    first_file = True
+
+    for fname in txt_files:
+        fpath = os.path.join(folder_path, fname)
+        o2hb, hhb, events, meta, labels, fs = _parse_oxysoft_txt(fpath)
+
+        if first_file:
+            metadata    = meta
+            ch_labels   = labels
+            sample_rate = fs
+            first_file  = False
+
+        all_o2hb.append(o2hb)
+        all_hhb.append(hhb)
+        all_events.extend(events)
+
+    # o2hb / hhb: shape (n_channels, n_samples)
+    o2hb_concat = np.concatenate(all_o2hb, axis=1)
+    hhb_concat  = np.concatenate(all_hhb,  axis=1)
+
+    n_ch, n_samp = o2hb_concat.shape
+    duration_s   = n_samp / sample_rate if sample_rate > 0 else 0.0
+
+    # Stack as (2 * n_channels, n_samples): first all O2Hb, then all HHb
+    signals = np.concatenate([o2hb_concat, hhb_concat], axis=0)
+
+    # Channel names: e.g. ['Tx1 O2Hb', 'Tx2 O2Hb', 'Tx3 O2Hb', 'Tx1 HHb', ...]
+    o2hb_names = [f"{l} O2Hb" for l in ch_labels]
+    hhb_names  = [f"{l} HHb"  for l in ch_labels]
+
+    return Dataset(
+        source_format = "Oxysoft",
+        folder_path   = folder_path,
+        folder_name   = folder_name,
+        sample_rate   = sample_rate,
+        num_samples   = n_samp,
+        duration_s    = duration_s,
+        signals       = signals,
+        channel_names = o2hb_names + hhb_names,
+        num_channels  = 2 * n_ch,
+        events        = all_events,
+        metadata      = {
+            **metadata,
+            "n_channels": n_ch,   # how many physical channels (not * 2)
+        },
+    )
+
+
+def load_oxysoft_file(file_path: str) -> Dataset:
+    """Parse a single Oxysoft .txt export into a Dataset."""
+    folder_name = os.path.splitext(os.path.basename(file_path))[0]
+    o2hb, hhb, events, metadata, ch_labels, sample_rate = _parse_oxysoft_txt(file_path)
+    n_ch, n_samp = o2hb.shape
+    signals      = np.concatenate([o2hb, hhb], axis=0)
+    return Dataset(
+        source_format = "Oxysoft",
+        folder_path   = os.path.dirname(file_path),
+        folder_name   = folder_name,
+        sample_rate   = sample_rate,
+        num_samples   = n_samp,
+        duration_s    = n_samp / sample_rate if sample_rate > 0 else 0.0,
+        signals       = signals,
+        channel_names = [f"{l} O2Hb" for l in ch_labels] + [f"{l} HHb" for l in ch_labels],
+        num_channels  = 2 * n_ch,
+        events        = events,
+        metadata      = {**metadata, "n_channels": n_ch},
+    )
+
+
+def _parse_oxysoft_txt(
+    filepath: str,
+) -> tuple[np.ndarray, np.ndarray, list[dict], dict, list[str], float]:
+    """
+    Parse a single Oxysoft .txt file.
+
+    The Oxysoft format has a Legend block that maps column numbers to
+    channel names, followed by a numeric header row (1  2  3 ...) and
+    then the data. Row 0 is absolute baseline and is skipped.
+
+    Returns
+    -------
+    o2hb          : np.ndarray  shape (n_channels, n_samples)
+    hhb           : np.ndarray  shape (n_channels, n_samples)
+    events        : list of {'label': str, 'sample': int}
+    metadata      : dict
+    channel_labels: list[str]  e.g. ['Tx1', 'Tx2', 'Tx3']
+    sample_rate   : float (Hz)
+    """
+    metadata:  dict  = {}
+    events:    list  = []
+    data_rows: list  = []
+    sample_rate      = 0.0
+
+    # Will be filled from the Legend block
+    # col_index → ('O2Hb' | 'HHb', channel_label)
+    col_map: dict[int, tuple[str, str]] = {}
+    event_col: Optional[int] = None
+
+    in_legend       = False
+    in_data         = False
+    fit_factor_col: Optional[int] = None
+
+    with open(filepath, 'r', encoding='utf-8', errors='replace') as fh:
+        for raw_line in fh:
+            line  = raw_line.rstrip('\n')
+            parts = line.split('\t')
+
+            # ---- metadata -----------------------------------------------
+            if not in_legend and not in_data:
+                if 'sample rate' in line.lower():
+                    try:
+                        sample_rate = float(parts[1].strip().split()[0])
+                    except (IndexError, ValueError):
+                        pass
+
+                if line.strip() == 'Legend:':
+                    in_legend = True
+                    continue
+
+            # ---- legend block -------------------------------------------
+            if in_legend:
+                # The column-number header row signals end of legend
+                stripped = [p.strip() for p in parts]
+                if all(p.isdigit() for p in stripped if p):
+                    in_legend = False
+                    in_data   = True
+                    continue
+
+                # Legend rows look like: "2\tRx1 - Tx1 O2Hb (filename)"
+                if len(parts) >= 2:
+                    try:
+                        col_idx  = int(parts[0].strip())
+                        col_desc = parts[1].strip()
+                    except ValueError:
+                        continue
+
+                    if '(Event)' in col_desc or 'Event' in col_desc:
+                        event_col = col_idx - 1   # convert to 0-based
+                    elif 'O2Hb' in col_desc:
+                        m = re.search(r'Tx\d+', col_desc)
+                        label = m.group(0) if m else f"Ch{col_idx}"
+                        col_map[col_idx - 1] = ('O2Hb', label)
+                    elif 'HHb' in col_desc:
+                        m = re.search(r'Tx\d+', col_desc)
+                        label = m.group(0) if m else f"Ch{col_idx}"
+                        col_map[col_idx - 1] = ('HHb', label)
+                    elif 'Fit Factor' in col_desc:
+                        fit_factor_col = col_idx - 1   # 0-based
+                    # TSI%, sample number → ignored
+                continue
+
+            # ---- data section -------------------------------------------
+            if not in_data or len(parts) < 2:
+                continue
+
+            try:
+                row = [float(p) if p.strip() else 0.0 for p in parts]
+            except ValueError:
+                continue
+
+            # Skip row 0 — absolute baseline, not delta values
+            sample_num = int(row[0])
+            if sample_num == 0:
+                continue
+
+            data_rows.append(row)
+
+            # Events
+            if event_col is not None and event_col < len(row):
+                ev = parts[event_col].strip() if event_col < len(parts) else ''
+                if ev and ev != '0':
+                    events.append({'label': ev, 'sample': len(data_rows) - 1})
+
+    if not data_rows:
+        raise ValueError(f"No data rows parsed from {filepath}")
+
+    data = np.array(data_rows, dtype=np.float64)  # (n_samples, n_cols)
+
+    # Sort col_map into ordered O2Hb and HHb columns
+    o2hb_cols = sorted(
+        [(idx, label) for idx, (kind, label) in col_map.items() if kind == 'O2Hb'],
+        key=lambda x: x[1]
+    )
+    hhb_cols = sorted(
+        [(idx, label) for idx, (kind, label) in col_map.items() if kind == 'HHb'],
+        key=lambda x: x[1]
+    )
+
+    channel_labels = [label for _, label in o2hb_cols]
+
+    o2hb = np.array([data[:, idx] for idx, _ in o2hb_cols])  # (n_ch, n_samp)
+    hhb  = np.array([data[:, idx] for idx, _ in hhb_cols])   # (n_ch, n_samp)
+
+    if fit_factor_col is not None and fit_factor_col < data.shape[1]:
+        metadata['fit_factor_mean'] = float(np.mean(data[:, fit_factor_col]))
+
+    return o2hb, hhb, events, metadata, channel_labels, sample_rate

PhysicsLibrary/loaders/pt2_loader.py

@@ -0,0 +1,43 @@
+"""
+loaders/pt2_loader.py
+-----------------------
+Terranova / Prospa .pt2 EFNMR/MRI image parser.
+"""
+
+import numpy as np
+
+
+def load_pt2(path: str) -> np.ndarray:
+    """
+    Parse a Terranova Prospa .pt2 2D NMR/MRI image file.
+
+    The reconstructed magnitude image is stored after the 4-byte marker
+    b'LAER' ('REAL' reversed) as little-endian float32 values.
+
+    Returns
+    -------
+    np.ndarray
+        2D float32 array shaped (n, n).
+    """
+    with open(path, 'rb') as f:
+        raw = f.read()
+
+    pos = raw.find(b'LAER')
+    if pos == -1:
+        raise ValueError("Not a recognised .pt2 file — LAER image marker not found.")
+    pos += 4
+
+    arr = np.frombuffer(raw[pos:], dtype='<f4').copy()
+    n_total = len(arr)
+
+    for n in [16, 32, 64, 128, 256]:
+        if n_total == n * n and np.isfinite(arr).all() and arr.max() > 0:
+            return arr.reshape(n, n)
+
+    sq = int(np.sqrt(n_total))
+    if sq * sq == n_total and np.isfinite(arr).all() and arr.max() > 0:
+        return arr.reshape(sq, sq)
+
+    raise ValueError(
+        f"Could not determine image dimensions ({n_total} floats after LAER)."
+    )

PhysicsLibrary/loaders/tdt_loader.py

@@ -0,0 +1,49 @@
+"""
+loaders/tdt_loader.py
+-----------------------
+Wraps processing_TDT's validate + process pipeline and packages the
+result into a universal Dataset.
+"""
+
+import numpy as np
+
+from .. import processing_TDT
+from ..dataset import Dataset
+
+
+def load_tdt(folder_path: str, folder_name: str) -> Dataset:
+    """Load a TDT tank using the existing validate + process pipeline."""
+    valid, msg = processing_TDT.validate_tdt_folder(folder_path)
+    if not valid:
+        raise ValueError(f"TDT validation failed: {msg}")
+
+    result     = processing_TDT.process_tdt_folder(folder_path)
+    signals    = result["corr"]
+    signals_2d = signals[np.newaxis, :]
+    fs         = float(result["fs"])
+    num_samp   = signals.shape[0]
+
+    events = []
+    for marker in result["markers"]:
+        events.append({
+            "label":  marker["label"],
+            "sample": int(round(marker["time"] * fs)),
+        })
+
+    return Dataset(
+        source_format = "TDT",
+        folder_path   = folder_path,
+        folder_name   = folder_name,
+        sample_rate   = fs,
+        num_samples   = num_samp,
+        duration_s    = num_samp / fs if fs > 0 else 0.0,
+        signals       = signals_2d,
+        channel_names = [result["store"]],
+        num_channels  = 1,
+        events        = events,
+        metadata      = {
+            "f0":  result["f0"],
+            "raw": result["raw"],
+            "x":   result["x"],
+        },
+    )

PhysicsLibrary/models.py

@@ -0,0 +1,62 @@
+"""
+models.py
+---------
+Parametric model functions for curve fitting via scipy.optimize.curve_fit.
+
+Each function follows the signature  f(x, *params) -> y  so they can be
+passed directly to fit_model_to_segment in analysis.py.
+"""
+
+import numpy as np
+
+
+def visibility_model(beta, a, v, beta_c, period):
+    """
+    Photon-entanglement visibility model.
+
+    Parameters
+    ----------
+    beta   : array  Polarizer angle (degrees or radians)
+    a      : float  Amplitude of the sinusoid
+    v      : float  Visibility (0–1)
+    beta_c : float  Angular offset / centre
+    period : float  Period of the oscillation
+
+    Returns
+    -------
+    array
+    """
+    return (a / 2) * (1 - v * np.sin((beta - beta_c) / period))
+
+
+def double_exponential_model(x, a, b, c, d, k):
+    """
+    Physical model of fluorophore bleaching.
+    y = a*exp(-b*x) + c*exp(-d*x) + k
+    """
+    return a * np.exp(-b * x) + c * np.exp(-d * x) + k
+
+
+def linear_model(x, m, b):
+    """y = mx + b"""
+    return m * x + b
+
+
+def single_exponential_model(x, a, b, c):
+    """y = a * exp(-b*x) + c"""
+    return a * np.exp(-b * x) + c
+
+
+def exponential_rise_model(x, a, b, c):
+    """y = a * (1 - exp(-b*x)) + c   — rising exponential (e.g. venous occlusion)"""
+    return a * (1 - np.exp(-b * x)) + c
+
+
+def gaussian_model(x, a, mu, sigma):
+    """y = a * exp(-(x-mu)^2 / (2*sigma^2))"""
+    return a * np.exp(-((x - mu) ** 2) / (2 * sigma ** 2))
+
+
+def sinusoidal_model(x, a, f, phi, c):
+    """y = a * sin(2*pi*f*x + phi) + c"""
+    return a * np.sin(2 * np.pi * f * x + phi) + c