natus-erd-reader 0.2.1__tar.gz

natus_erd_reader-0.2.1/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.2.1 — 2026-09-04
+
+Compatibility fixes within the existing schema-9 Quantum layout; no new
+application entry points, hardware calibration or resampling behavior.
+
+- Read the finite positive sample rate from ERD headers instead of requiring
+  2048 Hz. Reject non-finite recording duration and inconsistent segment rates.
+- Interpret STC stored counts separately from stamp spans, verify ETC counts,
+  and preserve leading, internal, trailing and fully empty gaps as NaN.
+- Resolve complete recording filenames case-insensitively with ambiguity and
+  directory-boundary checks. Explicit STC or matching EEG can select among
+  multiple recordings; an unrelated ordinary `.stc` directory is ignored.
+- Keep positional channel-label placeholders, avoid fallback-name collisions
+  and require index selection for genuinely duplicated vendor labels.
+- Add bounded public-API validation examples without a fixed channel label;
+  adapt sample windows to the actual rate and redact unknown error details.
+- Extend synthetic compatibility coverage, add Python 3.13 CI, and test the
+  minimum NumPy 1.24.x dependency on Python 3.10 for Windows and Linux.
+- Preserve all existing read/parser budgets and Python-only runtime surface.
+
+## 0.2.0 — source-only update
+
+Python-library-only release with explicit resource limits. This is a breaking
+change from 0.1.0, and remains experimental research software.
+
+- Remove both installed command-line programs and `python -m natus_erd`.
+- Remove EDF APIs, comparison tools, plotting extras and the local web viewer.
+- Keep native ERD window reads, structural metadata, ENT events and validation.
+- Add `ReadLimits` and `ResourceLimitError`; default output budget is 64 MiB
+  per read, with at most 131,072 samples per call. Reject oversized requests
+  before allocation and NumPy import.
+- Add `iter_samples()` for chunked processing without retaining a full record.
+- Bound metadata reads and ENT parsing; validate compressed-packet lengths and
+  decode through a bounded buffer instead of loading a whole packet.
+- Parse ENT using an independent restricted grammar; never execute input.
+- Load NumPy only when an accepted sample request needs an array. Do not
+  modify global numerical-backend thread settings.
+- Require an explicit recording directory or entry-point file rather than
+  recursively searching broad parent directories.
+- Extend synthetic resource-boundary tests and distribution checks. No
+  operating-system crash-prevention or clinical-safety claim is made.
+
+### Migration from 0.1.0
+
+Use `NatusERDReader` directly from Python; there is no replacement executable.
+`EDFInfo`, `EDFReader` and `EDFSignal` are no longer exported or included.
+Remove optional `plot`/`validation` extras from dependency declarations.
+Split large `read_samples` calls with `iter_samples`, or choose an explicit
+`ReadLimits` policy appropriate to the application. Raising the limits is an
+application decision and requires its own memory planning.
+
+## 0.1.0
+
+Initial research release of the schema-9 Quantum reader, before the bounded
+Python-only API introduced in 0.2.0. The legacy release did not sufficiently
+constrain output allocation, metadata reads or compressed-packet reads.

natus_erd_reader-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Use Python 3.10 or newer. A clean development environment is recommended:
+
+```shell
+python -m venv .venv
+# Activate the environment using the command appropriate for your shell.
+python -m pip install -e ".[dev]"
+python -m unittest discover -v -s tests -t .
+python -m build
+python -m twine check dist/*
+python tools/check_dist.py dist
+```
+
+All automated tests generate synthetic recordings at runtime. Do not add
+clinical recordings, patient names, event text, exported waveforms, local
+credentials or derived plots to issues, pull requests, commits or artifacts.
+When reporting a format problem, supply sanitized structural metadata and a
+synthetic reproducer where possible.
+
+Keep unsupported schemas and headboxes explicit. Do not silently reuse the
+Quantum calibration for unverified hardware. Changes to packet decoding need
+tests for absolute values, delta sentinels, shorted channels and packet edges.
+Resource-boundary tests must intercept oversized requests or use synthetic
+bounded input; do not actually allocate gigabytes to test rejection paths.
+Keep metadata-only imports free of NumPy and never alter the user's global
+numerical-backend settings from package code.
+
+CI sets `OPENBLAS_NUM_THREADS=1` and `OMP_NUM_THREADS=1` for the test runner
+to keep backend initialization predictable. These are application-side test
+settings, not package behavior or a substitute for an operating-system memory
+limit. Backend-specific failure diagnosis should record the actual environment
+and avoid unsafe reproduction on a user's machine.
+
+The installed distribution exposes Python APIs only. Do not add executables,
+web assets, EDF readers, optional plotting dependencies or real data to it.
+`tools/check_dist.py` is a development audit script, not an installed command.
+
+## Release checklist
+
+1. Update the versions in `pyproject.toml` and `src/natus_erd/__init__.py`.
+2. Update `CHANGELOG.md`; run the unit suite and distribution audit from a
+   clean staging tree so removed files cannot survive in build caches.
+3. Confirm `git ls-files` contains no recordings, reports or credentials.
+4. Merge to `main` and wait for CI to succeed.
+5. Push an annotated `vX.Y.Z` tag. The release workflow builds and attaches a
+   wheel and source archive to the GitHub release.
+
+6. For an explicitly authorized PyPI publication, configure a PyPI Trusted
+   Publisher for owner `ms903`, repository `natus-erd-reader`, workflow
+   `publish-pypi.yml`, and environment `pypi`. A new PyPI project requires a
+   pending publisher under the account's Publishing settings. See the
+   [official PyPI setup guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+7. Manually run `publish-pypi.yml` with the released tag. It audits the existing
+   GitHub Release archives and uploads those same files using short-lived OIDC
+   credentials. It does not rebuild them or require a stored PyPI API token.
+
+PyPI publication is a separate, explicitly authorized step, not triggered by
+ordinary pushes or by the GitHub Release workflow. Never commit credentials.

natus_erd_reader-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ms903 and natus-erd-reader contributors
+
+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.

natus_erd_reader-0.2.1/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md LICENSE THIRD_PARTY_NOTICES.md CHANGELOG.md CONTRIBUTING.md SECURITY.md
+include pyproject.toml MANIFEST.in
+recursive-include src/natus_erd *.py py.typed
+recursive-include tests *.py
+recursive-include tools *.py
+recursive-include examples *.py
+prune data
+prune figures
+prune reports
+prune .github
+global-exclude __pycache__ *.py[cod] *.erd *.etc *.stc *.eeg *.ent *.edf *.bdf *.npy *.npz

natus_erd_reader-0.2.1/PKG-INFO

@@ -0,0 +1,289 @@
+Metadata-Version: 2.4
+Name: natus-erd-reader
+Version: 0.2.1
+Summary: Resource-bounded Python reader for Natus NeuroWorks schema-9 ERD recordings
+Author: ms903 and natus-erd-reader contributors
+License-Expression: MIT AND BSD-3-Clause
+Project-URL: Homepage, https://github.com/ms903/natus-erd-reader
+Project-URL: Repository, https://github.com/ms903/natus-erd-reader
+Project-URL: Issues, https://github.com/ms903/natus-erd-reader/issues
+Project-URL: Changelog, https://github.com/ms903/natus-erd-reader/blob/main/CHANGELOG.md
+Keywords: eeg,seeg,natus,neuroworks,erd
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# natus-erd-reader
+
+[![Tests and package build](https://github.com/ms903/natus-erd-reader/actions/workflows/ci.yml/badge.svg)](https://github.com/ms903/natus-erd-reader/actions/workflows/ci.yml)
+
+A small Python library for native Natus NeuroWorks ERD recordings. It reads
+sample windows through the STC/ETC indexes, decodes schema-9 packets and
+extracts ENT annotations. It has **no command-line application, web server,
+EDF reader, plotting tool or vendor SDK dependency**.
+
+Version 0.2.1 adds header-driven sample rates and compatibility fixes while
+preserving bounded file reads and allocations. Python 3.10+ is
+required; NumPy is the only runtime dependency and is imported only when a
+valid sample-read request needs an array. Opening a recording and inspecting
+metadata or events do not initialize NumPy.
+
+This is **experimental research software**, not a certified diagnostic device.
+It is not affiliated with or endorsed by Natus. The supported hardware/layout
+is deliberately narrow, and no guarantee is made against operating-system,
+driver, hardware or numerical-library failures.
+
+## Installation
+
+With Python 3.10 or newer, install **0.2.1** directly from GitHub Releases
+(no Git installation or manual download required):
+
+```shell
+python -m pip install --upgrade "https://github.com/ms903/natus-erd-reader/releases/download/v0.2.1/natus_erd_reader-0.2.1-py3-none-any.whl"
+```
+
+Run this command in the Python environment where you want to use the reader.
+NumPy is installed automatically if needed. To preserve an existing,
+compatible NumPy installation, add `--no-deps`.
+
+Once the version is available on [PyPI](https://pypi.org/project/natus-erd-reader/),
+it can also be installed by name:
+
+```shell
+python -m pip install --upgrade "natus-erd-reader==0.2.1"
+```
+
+The GitHub Release command above does not depend on PyPI availability.
+
+Check the installed version without loading NumPy or opening a recording:
+
+```shell
+python -c "from importlib.metadata import version; print(version('natus-erd-reader'))"
+```
+
+For development source from the current `main` branch, or from a local checkout:
+
+```shell
+python -m pip install --upgrade "https://github.com/ms903/natus-erd-reader/archive/refs/heads/main.zip"
+python -m pip install .
+```
+
+Tagged releases are listed in
+[GitHub Releases](https://github.com/ms903/natus-erd-reader/releases).
+The distribution name is
+`natus-erd-reader`; the import name is `natus_erd`.
+
+## Read a small window
+
+```python
+from math import ceil
+
+from natus_erd import NatusERDReader
+
+# Pass the recording directory itself, or its .stc, .eeg or .erd file.
+reader = NatusERDReader.open(r"D:\path\to\recording")
+print(reader.info)  # Structural counts, not patient header fields.
+
+# Start is inclusive; stop is exclusive. Both are sample numbers.
+# Target one second, using the actual ERD header rate and recording length.
+stop = min(reader.info.n_samples, ceil(reader.info.sample_rate))
+data = reader.read_samples(0, stop, channels=[0, 1])
+print(data.shape, data.dtype)  # (2, stop), float64
+
+digital = reader.read_samples(0, stop, channels=[0, 1], units="digital")
+events = reader.read_events()
+```
+
+Arrays have shape `(channels, samples)`, always with `float64` dtype. The
+default unit is microvolts (`units="uV"`); `"digital"` returns decoded native
+counts without clipping to int16. Channel selection accepts zero-based
+indices or names and preserves the requested order. Omitting `channels`
+selects the first 256 signal channels. Shorted channels and known gaps are
+returned as `NaN`, not zero.
+STC stored-sample counts can be smaller than the stamp-defined time span;
+the ETC packet stamps determine where samples are present. Leading, internal
+and trailing gaps remain on the original time axis: they are not removed,
+interpolated or compressed. Reads crossing a gap retain it as `NaN`.
+
+Sample rates are read from the ERD header, not assumed to be 2048 Hz. For
+example, 2048 samples cover four seconds at 512 Hz and one second at 2048 Hz.
+The reader does not resample. A one-second request at an unusually high rate
+can exceed the unchanged resource limits; use a shorter window or chunks.
+
+Sample zero corresponds to the first STC stamp. `sample_to_stamp()` and
+`stamp_to_sample()` convert between relative sample positions and native
+stamps. `reader.info`, `reader.channels`, `reader.read_events()` and
+`reader.validate()` expose structural metadata, channel descriptions, events
+and a structural validation report, respectively. Validation is not a
+complete decoding or clinical validation of every sample.
+
+The reader does not recursively search arbitrary parent directories. Pass
+the actual recording directory and keep its index and segment files together.
+Filenames are matched case-insensitively, including their extensions, but
+ambiguous case-folded duplicates are rejected. In a directory containing
+multiple recordings, pass an explicit `.stc` or its matching `.eeg`; a
+directory or `.erd` alone cannot select a unique recording. An ENT file is
+optional; `.ent.old` is used only if `.ent` is absent, never to conceal a
+corrupt `.ent`. Missing channel labels receive positional fallback names;
+ambiguous vendor labels must be selected by index.
+Only completed, static recordings are supported: do not modify the files or
+continue acquisition into them while a reader is open. Size, timestamp and
+file-identity checks detect some concurrent changes, but detection is
+best-effort and does not provide a consistent snapshot of changing files.
+
+## Keep larger reads bounded
+
+The default output budget is **64 MiB per `read_samples` call**. A request
+that would exceed it raises `ResourceLimitError` before allocating the output
+or importing NumPy. An output needs `selected_channels × samples × 8` bytes.
+Thus a one-second, two-channel read at 2048 Hz needs 32 KiB for its output;
+reading an entire long recording at once is intentionally rejected.
+There is also a default limit of **131,072 samples per call** (64 seconds at
+2048 Hz), even when only one channel is selected, to bound decoding work.
+
+Process long recordings incrementally:
+
+```python
+for chunk in reader.iter_samples(
+    start=0,
+    stop=reader.info.n_samples,
+    chunk_samples=20480,
+    channels=[0, 1],
+    units="uV",
+):
+    # Analyze or write this chunk, then let it go before requesting the next.
+    print(chunk.shape)
+```
+
+Each chunk is checked against the same read budget. **Do not collect all
+chunks into a list** unless you deliberately want to retain that memory.
+The caller owns arrays returned by the reader; repeated reads retained by
+the caller can still consume arbitrary memory.
+
+For a stricter output policy:
+
+```python
+from natus_erd import NatusERDReader, ReadLimits
+
+reader = NatusERDReader.open(
+    r"D:\path\to\recording",
+    limits=ReadLimits(max_read_bytes=16 * 1024 * 1024),
+)
+```
+
+Metadata lengths, parser complexity and packet sizes are also checked before
+large reads. Packet decoding uses a bounded input buffer rather than reading
+the entire compressed packet into memory. Invalid offsets, truncated data,
+overlap and unsupported layouts raise explicit errors. These checks limit
+the reader's own resource requests; **they are not a process-wide memory
+limit or a sandbox**.
+
+Other defaults include 8 MiB per metadata file or compressed packet, 256 KiB
+per ENT record, 4,096 ENT records, parser depth 32 and a cache of four segment
+indexes. `ReadLimits` exposes these policies explicitly; increasing a limit
+should follow an assessment of the input and available resources.
+
+### NumPy backend resource use
+
+Some NumPy builds initialize a multi-threaded numerical backend with a large
+memory footprint, even though this reader does not need matrix multiplication.
+The package does not modify process-wide thread settings or environment
+variables. On a memory-constrained system, an application may explicitly set
+its own backend policy **before importing NumPy or any library that imports
+it**, for example at the very start of the application:
+
+```python
+import os
+
+os.environ["OPENBLAS_NUM_THREADS"] = "1"  # For an OpenBLAS-backed NumPy build.
+
+from natus_erd import NatusERDReader
+```
+
+This setting is backend-specific and is not a remedy or guarantee for kernel
+crashes. If a machine has frozen or restarted, do not retry an unbounded
+workload; investigate the operating-system failure separately.
+
+## Supported format and errors
+
+The supported layout is ERD schema 9, base schema 1, Quantum headbox type 20:
+276 recorded channels, 8-bit delta base and 6 discarded bits. Any finite
+positive header sample rate is accepted if its recording duration is finite;
+there is no sample-rate whitelist. All segments must have the same rate.
+This does not extend support to other hardware or per-channel sampling rates.
+STC schema 1, ETC schema 3 and ENT schema 3 are supported, each with base
+schema 1. The ERD layout must contain a single headbox, an identity physical
+channel mapping and a frequency-factor value of 32767 for every channel.
+The first 256 channels use the Quantum AC calibration:
+
+```text
+uV = digital × (-8711 / (2**21 - 0.5)) × 2**discard_bits
+```
+
+The last 20 auxiliary channels remain in `reader.channels` and can be read
+as digital counts, but have no verified physical-unit conversion. Native
+UTF-8 segment and montage names are supported. ENT is parsed as data with a
+restricted, bounded grammar; it is never evaluated as Python code.
+Notes with unsupported or malformed text syntax may be skipped; a restricted
+fallback extracts channel names from recognized nonstandard montage fields.
+Consequently, `read_events()` is not guaranteed to include every annotation
+stored by the vendor. Invalid binary lengths, schemas and exceeded parser
+budgets still raise errors rather than being silently skipped.
+
+`.eeg` is an accepted entry point, not the sample-data source. Samples come
+from `.stc`/`.etc` indexes and `.erd` payloads. Other schemas/headboxes,
+`Decimated`, video, EDF and additional auxiliary calibration are out of scope.
+
+- `UnsupportedFormatError`: unsupported format or hardware layout.
+- `DataIntegrityError`: malformed, truncated or inconsistent input.
+- `ResourceLimitError`: a configured resource limit would be exceeded.
+- `NatusERDError`: common base class for these reader exceptions.
+
+Ordinary invalid API arguments may raise `TypeError`, `ValueError` or
+`IndexError`. Filesystem failures may propagate the corresponding `OSError`.
+
+## Privacy, testing and maintenance
+
+The library does not upload recordings or contact network services. Channel
+labels and ENT event text can contain sensitive information; avoid printing
+or sharing them without reviewing them. Only generic source and synthetic
+tests belong in this repository. Real recordings, event text and derived
+patient outputs must not be distributed.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the test/build workflow and
+[SECURITY.md](SECURITY.md) for resource-limit boundaries. Public API changes
+from 0.1.0 are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## 中文速览
+
+这是只提供 Python API 的 Natus ERD 读取包，不再包含命令行、网页、EDF 或绘图功能。
+支持的范围限定为 schema 9 / Quantum headbox 20。默认单次输出上限为 64 MiB；
+采样率从 ERD 文件头读取，不再固定为 2048 Hz；采样空档保留原时间轴并返回 NaN。
+长记录请使用 `iter_samples()` 分块处理，不要把所有块保留在内存中。
+读取器会检查文件长度、索引和解析资源上限，但不能保证避免操作系统或硬件故障。
+仅查看记录信息和事件不会初始化 NumPy；真正读取数组时才加载它。
+
+## License
+
+See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)
+for applicable terms and retained attribution. Both are included in source
+and wheel distributions.