delsys 0.1.0__tar.gz

delsys-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  test:
+    name: pytest (Python ${{ matrix.python-version }} on ${{ matrix.platform }})
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+        platform: [ubuntu-22.04, macos-latest, windows-latest]
+    runs-on: ${{ matrix.platform }}
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package + dev deps
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run pytest
+        run: pytest

delsys-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.hypothesis/
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Type-checker caches
+.mypy_cache/
+.ruff_cache/
+
+# Sphinx build artifacts
+docs/_build/
+
+# Generated by Delsys side-channel files (not part of fixtures)
+*_dropped_samples.txt
+*_ekginfo.json
+*_ica_settings.json
+
+# Local sample data (reference files; not committed)
+_data/
+samples/
+
+# Transient resume notes from assistant sessions
+RESUME.md
+
+# Maintainer-only release runbook
+PUBLISH.md

delsys-0.1.0/.readthedocs.yaml

@@ -0,0 +1,29 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats:
+  - pdf
+  - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

delsys-0.1.0/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+First public release. The package is a standalone extraction and polish of the
+Delsys CSV loader that previously lived in
+`immersionToolbox/immersionlab/delsys.py` for several years. The
+`immersionlab.delsys` module is now a thin shim that re-exports `delsys`, so
+existing callers continue to work without code changes.
+
+### Added
+
+- Modular package layout under `src/delsys/`: `log`, `sensor`, `signals`,
+  `emg`, `ekg`, plus internal `_parse`, `_metadata`, `_constants`, `_util`.
+- `Log.find()` — typed query API for sensors, modality bundles, or raw
+  signals, with filters by modality / side / location / sensor number / name.
+- Direct typed accessors on `Log`: `lf.emg`, `lf.ekg`, `lf.acc`, `lf.gyro`,
+  `lf.fsr`, `lf.analog`, `lf.vo2master`, `lf.hrstrap`. Side accessors
+  `lf.left` / `lf.right` / `lf.center` return lists of `Sensor`.
+- `EMG.rms()` — clean RMS amplitude pipeline (shift_baseline → highpass →
+  lowpass → notch → running RMS) producing an envelope at the requested
+  output sampling rate.
+- `Log.add_sensor_group()` for user-defined groupings.
+- `_metadata.py` module holding the three foundational namedtuples
+  (`SensorLog`, `SensorInfo`, `SigInfoDelsys`) — extracted to break the
+  `signals.py` ↔ `sensor.py` import cycle.
+- Sensor metadata is now stored in `pysampled.Data.meta['sensor']` and
+  propagates automatically through filtering, slicing, and resampling.
+- Type hints (PEP 484) on every public function/method signature.
+- Google-style docstrings throughout, ready for Sphinx + napoleon.
+- Test suite: 94 tests across `test_parse.py`, `test_log.py`,
+  `test_signals.py`, `test_emg.py`, `test_ekg.py` with fixtures for all
+  five header formats (EMGworks, Discover 1.4.2 / 1.5.0 / 1.6.4 / 1.7.0).
+- `scripts/make_fixture.py` for trimming real CSVs into committable fixtures.
+- Standalone PyPI-publishable package with `pyproject.toml`.
+
+### Changed
+
+- **Minimum Python is now 3.10** (was 3.9). Bumped because a required
+  dependency (`neurokit2`) ships PEP 604 union syntax (``X | None``) at
+  module-import time, which fails on 3.9. Python 3.9 itself reached
+  end-of-life in October 2025.
+- **Bug fix:** `VO2Master` column ordering — all 8 channel properties used
+  to map to column 1; now correctly map to columns 0..7 per
+  `SUBCHANNEL_MAP['VO2']`.
+- **Bug fix:** `_parse_sig_name` raises `ValueError` for an unknown modality
+  instead of silently `print`ing and then raising a less-helpful `KeyError`
+  downstream.
+- **Bug fix:** `_detect_parser` raises `ValueError` instead of bare
+  `Exception` when link data is exported without time-series columns.
+- **Bug fix:** Frame-count invariant in the Discover parsers uses explicit
+  `if not ...: raise ValueError(...)` (was `assert`, which is disabled by
+  `python -O`).
+- **Bug fix:** VO2 / HR detection in `_parse_sig_name_discover` uses
+  `if`/`elif`/`else` (was two `if`s, with the second checking `'HR'`
+  substring rather than `'HR Strap'` — could mis-trigger).
+- **Bug fix:** `EMG.process()` preserves sensor metadata on the result
+  (was lost via direct `self.__class__(...)` construction).
+- **Bug fix:** `EMG.process()` no longer mutates `self._history` in place;
+  history is built fresh on the new instance.
+- **Bug fix:** `EMG.tkeo()` history entry is a single tuple (was a
+  list-containing-tuple).
+- O(N×M) sensor lookup inside the per-channel parser loops replaced with a
+  pre-built `{sensor_number: SensorInfo}` dict (O(1) per channel).
+- All regexes hoisted to module-level constants in `_parse.py`.
+- Build backend: standalone `pyproject.toml` (no longer dependent on
+  `immersionToolbox`'s build setup).
+- Dependencies trimmed: only `pysampled`, `numpy`, `scipy`, `pandas`,
+  `matplotlib`, `scikit-learn`, `heartpy`, `neurokit2`. No
+  `immersionlab.utils`, no `pntools.sampled`.
+
+### Removed
+
+- `DataMod` base class — modality classes (`Signal`, `IMU`, `FSR`,
+  `VO2Master`, `EMG`, `EKG`) now inherit from `pysampled.Data` directly.
+  `envelope2` was upstreamed to pysampled in the same release window.
+- `ica.py` (the accelerometer-impact ICA cleaning utility) — its scope
+  didn't match the package's primary purpose (EMG-from-EKG cleaning).
+  A `Log`-integrated EMG/EKG cleaning method is planned for a follow-up
+  release; see `TODO.md` for the design questions.
+- `decreturn` decorator and the `to=` parameter from `EMG.process_nk`,
+  `EMG.get_features_nk`, `EMG.get_features`, `EKG.process_nk`,
+  `EKG.get_features_hp`. These methods now return a plain `dict`; callers
+  wrap with `pd.DataFrame(...)` if they want a tabular result.
+- `EKG.find_rpeaks_hp`, `EKG.find_rpeaks_nk`, `EKG.clean_rpeaks`,
+  `EKG.hrv`, `EKG.find_rr`, `EKG.find_rr_nk`, `EKG._get_sav_name` —
+  alternative R-peak back-ends, the manual JSON-annotation workflow, and
+  related downstream methods. `EKG.find_rpeaks_pn` (alias `find_rpeaks`)
+  remains as the canonical detector.
+- `if __name__ == '__main__'` smoke-test block with hard-coded UNC paths
+  from the original monolithic file.
+
+### Provenance
+
+Extracted from `C:/dev/immersionToolbox/immersionlab/delsys.py` (1316 lines
+monolithic). Built on top of [pysampled](https://github.com/praneethnamburi/pysampled).

delsys-0.1.0/LICENSE

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

delsys-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: delsys
+Version: 0.1.0
+Summary: Load and analyze Delsys CSV exports as ``pysampled.Data`` time series.
+Author-email: Praneeth Namburi <praneeth.namburi@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: scikit-learn
+Requires-Dist: heartpy
+Requires-Dist: neurokit2
+Requires-Dist: pysampled>=1.1.1
+Requires-Dist: pytest>=7 ; extra == "dev"
+Requires-Dist: pytest-cov ; extra == "dev"
+Requires-Dist: black ; extra == "dev"
+Requires-Dist: isort ; extra == "dev"
+Project-URL: Documentation, https://delsys.readthedocs.io
+Project-URL: Homepage, https://github.com/praneethnamburi/delsys
+Project-URL: Issues, https://github.com/praneethnamburi/delsys/issues
+Provides-Extra: dev
+
+# delsys
+
+[![src](https://img.shields.io/badge/src-github-blue)](https://github.com/praneethnamburi/delsys)
+[![PyPI - Version](https://img.shields.io/pypi/v/delsys.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/delsys/)
+[![Documentation Status](https://readthedocs.org/projects/delsys/badge/?version=latest)](https://delsys.readthedocs.io)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/praneethnamburi/delsys/main/LICENSE)
+
+*Load Delsys CSV exports into Python as `pysampled.Data` time series.*
+
+`delsys` reads CSV files exported from EMGworks and Trigno Discover, normalizes their
+many per-format quirks (header layouts, sub-channel orderings, link-device
+asynchrony), resamples each channel to a configurable per-modality target
+rate, and groups the result into per-sensor modality bundles (EMG, EKG,
+IMU, FSR, VO2 Master, HR Strap, Analog) ready for analysis.
+
+## Installation
+
+```sh
+pip install delsys
+```
+
+For local development:
+
+```sh
+git clone https://github.com/praneethnamburi/delsys
+pip install -e "./delsys[dev]"
+```
+
+## Quickstart
+
+```python
+import delsys
+
+lf = delsys.Log("path/to/Trial.csv", sensor_map="path/to/delsys_channelmap.txt")
+
+# Direct accessors — list of typed bundles, one per sensor with that modality.
+lf.emg                            # list of EMG bundles
+lf.ekg                            # list of EKG bundles
+lf.acc, lf.gyro                   # tri-axial IMU bundles
+lf.fsr                            # 4-channel FSR bundles
+lf.analog                         # raw Analog signals
+lf.vo2master                      # VO2 Master link device (8 channels)
+lf.hrstrap                        # HR Strap link device
+
+# Side accessors return whole Sensor objects.
+lf.left, lf.right, lf.center
+
+# Filtered queries.
+lf.find(modality="EMG", side="R")              # right-side EMG bundles
+lf.find(location="Forearm")                    # any sensor at "Forearm"
+lf.find(sensor_number=5)
+lf.find(modality="EMG", as_="signal")          # raw per-channel Signal objects
+
+# A typical EMG envelope pipeline.
+for emg in lf.emg:
+    envelope = emg.process(amp_kind="envelope2")
+    rms = emg.rms(envelope_sr=240)             # clean RMS amplitude pipeline
+```
+
+See the full API reference at <https://delsys.readthedocs.io>.
+
+## Channelmap files (optional)
+
+When you pass `sensor_map="path/to/delsys_channelmap.txt"` to `Log()`, that
+file labels each sensor number with a sensor type and a body-location tag.
+This lets you query by side (`lf.find(side="R")`) and by location
+(`lf.find(location="Forearm")`).
+
+The format is one sensor per line, three fields separated by `" - "`:
+
+```
+Ch 1 - EMG - LBicep
+Ch 2 - EMG - RBicep
+Ch 11 - EKG - Chest
+Ch 12 - Sync - Optitrack Recording Gate
+Ch 19 - Quattro - LForearmExtensors (A-Index, B-Middle, C-Ring, D-Little)
+Ch 21 - FSR - LFoot (1-Heel, 2-OuterEdge, 3-Ball, 4-Toe)
+```
+
+- **Field 1**: any text whose last whitespace-token is the sensor's channel
+  number (`Ch 1`, `Channel 01`, `1` all work).
+- **Field 2**: a type tag (free text — common values: `EMG`, `Quattro`,
+  `Snap`, `EKG`, `FSR`, `Sync`).
+- **Field 3**: a location label. Its *first character* is interpreted as the
+  side (`L`/`R`/`C` for left/right/center). Anything else still loads but
+  won't match `lf.find(side=...)`.
+
+Trailing parenthetical notes are informational only — they remain in
+`location` but the parser doesn't extract sub-channel labels from them.
+Blank lines and lines without two `" - "` separators are silently skipped.
+
+A more comprehensive reference file lives at
+[`examples/delsys_channelmap.txt`](https://github.com/praneethnamburi/delsys/blob/main/examples/delsys_channelmap.txt).
+
+## Supported export formats
+
+- EMGworks
+- Trigno Discover 1.4.2
+- Trigno Discover 1.5.0
+- Trigno Discover 1.6.4 (with and without link devices)
+- Trigno Discover 1.7.0
+
+## Supported sensors
+
+EMG (Avanti single, Duo, Quattro, Snap-Lead), EKG, ACC, GYRO, FSR, Analog,
+VO2 Master (link), HR Strap (link).
+
+## Scope and contributions
+
+Supported sensor types are limited to those the maintainer has access to.
+Delsys ships other hardware (e.g. SmO2/Thb appear as stubs in `TARGET_SR`
+but are not exercised end-to-end). Contributions adding parsers and tests
+for additional sensors are very welcome.
+
+If you'd like to contribute, the dev install above pulls `pytest`, `black`,
+and `isort`. Format with `black` and `isort` before opening a PR:
+
+```sh
+isort src/ tests/ scripts/
+black src/ tests/ scripts/
+pytest
+```
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/praneethnamburi/delsys/blob/main/LICENSE) for details.
+
+## Contact
+
+[Praneeth Namburi](https://praneethnamburi.com)
+
+Project link: <https://github.com/praneethnamburi/delsys>
+
+## Acknowledgments
+
+This package was developed as part of the ImmersionToolbox initiative at the
+[MIT.nano Immersion Lab](https://immersion.mit.edu). Thanks to NCSOFT for
+supporting this initiative.
+

delsys-0.1.0/README.md

@@ -0,0 +1,138 @@
+# delsys
+
+[![src](https://img.shields.io/badge/src-github-blue)](https://github.com/praneethnamburi/delsys)
+[![PyPI - Version](https://img.shields.io/pypi/v/delsys.svg?logo=pypi&label=PyPI&logoColor=gold)](https://pypi.org/project/delsys/)
+[![Documentation Status](https://readthedocs.org/projects/delsys/badge/?version=latest)](https://delsys.readthedocs.io)
+[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/praneethnamburi/delsys/main/LICENSE)
+
+*Load Delsys CSV exports into Python as `pysampled.Data` time series.*
+
+`delsys` reads CSV files exported from EMGworks and Trigno Discover, normalizes their
+many per-format quirks (header layouts, sub-channel orderings, link-device
+asynchrony), resamples each channel to a configurable per-modality target
+rate, and groups the result into per-sensor modality bundles (EMG, EKG,
+IMU, FSR, VO2 Master, HR Strap, Analog) ready for analysis.
+
+## Installation
+
+```sh
+pip install delsys
+```
+
+For local development:
+
+```sh
+git clone https://github.com/praneethnamburi/delsys
+pip install -e "./delsys[dev]"
+```
+
+## Quickstart
+
+```python
+import delsys
+
+lf = delsys.Log("path/to/Trial.csv", sensor_map="path/to/delsys_channelmap.txt")
+
+# Direct accessors — list of typed bundles, one per sensor with that modality.
+lf.emg                            # list of EMG bundles
+lf.ekg                            # list of EKG bundles
+lf.acc, lf.gyro                   # tri-axial IMU bundles
+lf.fsr                            # 4-channel FSR bundles
+lf.analog                         # raw Analog signals
+lf.vo2master                      # VO2 Master link device (8 channels)
+lf.hrstrap                        # HR Strap link device
+
+# Side accessors return whole Sensor objects.
+lf.left, lf.right, lf.center
+
+# Filtered queries.
+lf.find(modality="EMG", side="R")              # right-side EMG bundles
+lf.find(location="Forearm")                    # any sensor at "Forearm"
+lf.find(sensor_number=5)
+lf.find(modality="EMG", as_="signal")          # raw per-channel Signal objects
+
+# A typical EMG envelope pipeline.
+for emg in lf.emg:
+    envelope = emg.process(amp_kind="envelope2")
+    rms = emg.rms(envelope_sr=240)             # clean RMS amplitude pipeline
+```
+
+See the full API reference at <https://delsys.readthedocs.io>.
+
+## Channelmap files (optional)
+
+When you pass `sensor_map="path/to/delsys_channelmap.txt"` to `Log()`, that
+file labels each sensor number with a sensor type and a body-location tag.
+This lets you query by side (`lf.find(side="R")`) and by location
+(`lf.find(location="Forearm")`).
+
+The format is one sensor per line, three fields separated by `" - "`:
+
+```
+Ch 1 - EMG - LBicep
+Ch 2 - EMG - RBicep
+Ch 11 - EKG - Chest
+Ch 12 - Sync - Optitrack Recording Gate
+Ch 19 - Quattro - LForearmExtensors (A-Index, B-Middle, C-Ring, D-Little)
+Ch 21 - FSR - LFoot (1-Heel, 2-OuterEdge, 3-Ball, 4-Toe)
+```
+
+- **Field 1**: any text whose last whitespace-token is the sensor's channel
+  number (`Ch 1`, `Channel 01`, `1` all work).
+- **Field 2**: a type tag (free text — common values: `EMG`, `Quattro`,
+  `Snap`, `EKG`, `FSR`, `Sync`).
+- **Field 3**: a location label. Its *first character* is interpreted as the
+  side (`L`/`R`/`C` for left/right/center). Anything else still loads but
+  won't match `lf.find(side=...)`.
+
+Trailing parenthetical notes are informational only — they remain in
+`location` but the parser doesn't extract sub-channel labels from them.
+Blank lines and lines without two `" - "` separators are silently skipped.
+
+A more comprehensive reference file lives at
+[`examples/delsys_channelmap.txt`](https://github.com/praneethnamburi/delsys/blob/main/examples/delsys_channelmap.txt).
+
+## Supported export formats
+
+- EMGworks
+- Trigno Discover 1.4.2
+- Trigno Discover 1.5.0
+- Trigno Discover 1.6.4 (with and without link devices)
+- Trigno Discover 1.7.0
+
+## Supported sensors
+
+EMG (Avanti single, Duo, Quattro, Snap-Lead), EKG, ACC, GYRO, FSR, Analog,
+VO2 Master (link), HR Strap (link).
+
+## Scope and contributions
+
+Supported sensor types are limited to those the maintainer has access to.
+Delsys ships other hardware (e.g. SmO2/Thb appear as stubs in `TARGET_SR`
+but are not exercised end-to-end). Contributions adding parsers and tests
+for additional sensors are very welcome.
+
+If you'd like to contribute, the dev install above pulls `pytest`, `black`,
+and `isort`. Format with `black` and `isort` before opening a PR:
+
+```sh
+isort src/ tests/ scripts/
+black src/ tests/ scripts/
+pytest
+```
+
+## License
+
+Distributed under the MIT License. See [LICENSE](https://github.com/praneethnamburi/delsys/blob/main/LICENSE) for details.
+
+## Contact
+
+[Praneeth Namburi](https://praneethnamburi.com)
+
+Project link: <https://github.com/praneethnamburi/delsys>
+
+## Acknowledgments
+
+This package was developed as part of the ImmersionToolbox initiative at the
+[MIT.nano Immersion Lab](https://immersion.mit.edu). Thanks to NCSOFT for
+supporting this initiative.

delsys-0.1.0/TODO.md

@@ -0,0 +1,88 @@
+# TODO
+
+Items deferred during the initial standalone-package extraction.
+
+## Coverage snapshot (2026-05-09)
+
+Recorded after Phase E. Overall **81% line / 74% branch** across 766 statements.
+Treat as informational — the user's direction was *measure-and-report only* for
+0.1.0; no new tests were written to chase numbers.
+
+| Module | Line cov | Branch cov | Note |
+|---|---|---|---|
+| `__init__.py` | 100% | n/a | Re-exports + module docstring. |
+| `_constants.py` | 100% | n/a | Constants only. |
+| `_metadata.py` | 100% | n/a | Three namedtuples. |
+| `signals.py` | 96% | 98% | Sensor / shape / column properties exercised by F3. |
+| `_parse.py` | 95% | 93% | Three uncovered branches: `_fix_corrupted_sensor_names` early-return for empty replace dict, an EMGworks edge case, two link-parser error paths. |
+| `sensor.py` | 90% | 90% | Uncovered: `Sensor.get_signal()` priority-sequence walk (lines 122–126). |
+| `ekg.py` | 81% | 73% | Uncovered: `process_nk` (no integration test), `get_features_hp` (no integration test), `_get_t_noisy_segments` non-empty branch, `flip_signal` re-detection on already-flipped signal. |
+| `emg.py` | 80% | 80% | Uncovered: `_freq_funcs` lambdas (the freq-domain feature dict only verified by key, not by per-feature value), `process_nk`, `get_features_nk`. |
+| `_util.py` | 78% | 60% | Uncovered: the `EMG`-prefix early-return path of `_mod_to_attr` is exercised only by lower-case input; uppercase input not directly tested. |
+| **`log.py`** | **57%** | **47%** | Biggest gap. Uncovered: `__getitem__` / `_getitem_onekey` legacy lookup (lines 437–473), `export_to_csv` (603–633), several `find()` branches (501–530), the `_combine_signal_sensor_info` error path with the channelmap-mismatch traceback (256–260). |
+
+Follow-ups (deferred to 0.1.1+):
+
+- **`log.py` coverage push.** The legacy `__getitem__` and `export_to_csv`
+  paths are public surface — a few targeted tests would close the biggest
+  branch-coverage gap. The legacy bracket lookup is a candidate for
+  deprecation, so test value depends on whether we plan to keep or remove
+  it.
+- **`emg.py` / `ekg.py` NeuroKit-backed features.** `process_nk`,
+  `get_features_nk`, `process_nk` (EKG), `get_features_hp` are uncovered.
+  These wrap upstream libraries; tests would mostly verify the dict-shape
+  contract.
+
+To regenerate this snapshot::
+
+    pytest --cov
+
+(Source filter, branch tracking, and exclude rules live in
+`[tool.coverage.run]` / `[tool.coverage.report]` in `pyproject.toml`.)
+
+## Post-0.1.0 roadmap
+
+- **EMG/EKG artifact cleaning at the `Log` level.** Port `C:\dev\pn-projects\projects\emg_ica_cleaning.py` (multi-stage pipeline: harmonization → preprocess → ICA-based ECG suppression with auto-component-detection by lagged correlation → ACC-guided motion regression with safety gates) into `delsys` as a `Log.clean_emg_ekg_artifact(...)` method. The integration work is to (a) gather all EMG `Signal`s + the EKG `Signal` (and optional per-EMG ACC predictors) from `lf`, (b) run the pipeline, (c) splice cleaned samples back into `lf.signals` per channel and rebuild affected `EMG` bundles in `lf.sensors[*].emg`, since `EMG._sig` is constructed by stacking signals at `Sensor.__init__` time. The previous ACC-only `ica.py` was removed in 0.1.0 because it didn't serve this stated primary purpose.
+
+## Resampling defaults (post-0.1.0)
+
+- **Reconsider the `TARGET_SR` defaults.** Currently every modality has a non-`None` default rate, so loading a CSV always resamples. A "preserve native rate" mode is conceptually attractive but not a five-minute change. Open design questions:
+
+    1. EMGworks parser (`_parse_dataframe_emgworks`) doesn't handle a `None` target rate; needs a "skip resample" branch like the Discover-basic parser.
+    2. Link devices (VO2 Master, HR Strap) are *asynchronous* — they have no native sampling rate, so `pysampled.uniform_resample` always needs a target. The "all-None" idea has no clean answer here. Possible fallback: pick rate from the median inter-sample interval, or require an explicit value just for link devices.
+    3. API surface: a `mode='native'`/`'analysis'` knob vs. just changing default `TARGET_SR` values? The latter is a breaking change for downstream code that depends on current uniform rates.
+
+  Per-modality `None` is already supported via explicit `target_sr={'EMGS': None, ...}`, so power users have an escape hatch today.
+
+## Restructure / API
+
+- **`Sensor.__init__` modality dispatch.** It uses an if/elif chain on modality strings to choose which class to instantiate. A small `MODALITY_REGISTRY` mapping `{'EMG': EMG, 'EKG': EKG, ...}` would be cleaner and would make adding modalities (e.g. SmO2/Thb that already appear in `TARGET_SR`) one-line changes.
+
+- **`Log.__getitem__` overloading.** Mixes sensor-lookup and signal-lookup based on key type (int, single-letter, modality string, location, name). Works but is undiscoverable. The new `lf.find(...)` is the public-facing replacement; `__getitem__` could be deprecated when there's a transition window.
+
+- **VO2 / HR identity.** `VO2_SENSOR_NUM` and `HR_SENSOR_NUM` are placeholder integers chosen to not collide with Trigno-base sensor numbers. Brittle if Delsys ever ships a third link device. A real fix identifies link sensors by type rather than number — would also clean up the special-cased branches in `_parse_sig_name_discover` and `Sensor.__init__`.
+
+## Pre-existing in-code TODOs
+
+- **EKG**: "Slicing will not work well with the cached rpeak indices. TODO: modify the `__getitem__` method."
+- **`_parse_dataframe_discover_with_link`**: "Make the exception explicit. The 13.5 ms sampling-rate calculation only applies for trigno base, not link devices."
+- **VO2 link**: "VO2 can start delayed (fill these data points with zeros), VO2 can finish before the other system."
+- **`discover_basic` parser path**: "Check if this works for a file with timestamps exported." Needs a fixture with timestamps but no link sensors.
+
+## Domain / units
+
+- VO2Master `VO2_absolute` returns raw CSV values (~37000 for moderate exercise). Likely a units issue, not a column-mapping one — verify against a known-correct VO2 reading and add unit conversion if needed.
+
+## Stage 4 status (added 2026-05-08)
+
+All six features have docs + tests in `tests/`:
+
+1. ✅ CSV header parsing — `tests/test_parse.py` (22 tests).
+2. ✅ End-to-end `Log` loading — `tests/test_log.py` (20 tests, parametrized over all 7 fixtures).
+3. ✅ Signal classes — `tests/test_signals.py` (30 tests).
+4. ✅ `EMG.process` envelope pipeline — `tests/test_emg.py` (14 tests).
+5. ✅ `EKG` R-peak detection — `tests/test_ekg.py` (NeuroKit's `ecg_simulate`).
+6. ✅ ICA cleaning — `tests/test_ica.py` (using a `Log`-shaped mock).
+
+Fixtures live under `tests/fixtures/` and are generated from `_data/` via
+`scripts/make_fixture.py`.

delsys-0.1.0/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)