linxi-trodes 1.0.0__tar.gz

linxi_trodes-1.0.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: linxi-trodes
+Version: 1.0.0
+Summary: Vibe spike sorting!
+Requires-Python: >=3.12
+Requires-Dist: pandas
+Requires-Dist: numpy

linxi_trodes-1.0.0/README.md

@@ -0,0 +1,49 @@
+# Linxi-Trodes
+
+Linxi-Trodes is forked from [Trodes](https://bitbucket.org/mkarlsso/trodes)
+
+Now this repo provides a python implemented SpikeGadgets DIO data extractor. Please follow the instruction to use it.
+
+Install the package in editable mode:
+
+```bash
+pip install -e .
+```
+
+Use it with a python script:
+
+```python
+from linxi_trodes import TrodesRecParser
+
+# Default mode (legacy behavior): only state transitions are kept.
+parser = TrodesRecParser("path/to/your/recording.rec")
+result = parser.extract_dio(output_dir="path/to/save/dio/")
+# result[channel_name] -> (timestamps: np.uint32[N], states: np.uint8[N])
+
+# Raw packet-sample mode: one record per valid packet, no deduplication.
+# Useful for waveform-style analysis of every digital sample.
+result_raw = parser.extract_dio(
+    output_dir="path/to/save/dio/",
+    return_type="raw",
+)
+# result_raw[channel_name] -> (timestamps: np.uint32[N], states: np.bool_[N])
+```
+
+The `return_type` selector chooses the semantics of the returned arrays and
+the `.dat` files written under `output_dir`. Omitting the argument preserves
+the legacy event-extraction behavior (default is `"event"`). Both modes share
+the same on-disk record layout — five little-endian bytes per record
+(`<uint32 timestamp><uint8 state>`); the difference is only which packets get
+recorded:
+
+- `return_type="event"` — only state-transition edges are written (default).
+- `return_type="raw"` — every valid-packet sample is written (no dedup).
+
+Use it with a simple CLI:
+
+```bash
+python src/linxi_trodes/export_dio.py \
+    "path/to/your/recording.rec" \
+    "path/to/save/dio/" \
+    [--only-export-enabled-dio]
+```

linxi_trodes-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "linxi-trodes"
+version = "1.0.0"
+description = "Vibe spike sorting!"
+requires-python = ">=3.12"
+dependencies = [
+    "pandas",
+    "numpy"
+]
+
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["linxi_trodes*"]
+
+[project.scripts]
+linxi_trode = "linxi_trodes.export_dio:main"

linxi_trodes-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

linxi_trodes-1.0.0/src/Linxi_Trodes.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: linxi-trodes
+Version: 1.0.0
+Summary: Vibe spike sorting!
+Requires-Python: >=3.12
+Requires-Dist: pandas
+Requires-Dist: numpy

linxi_trodes-1.0.0/src/Linxi_Trodes.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+src/Linxi_Trodes.egg-info/PKG-INFO
+src/Linxi_Trodes.egg-info/SOURCES.txt
+src/Linxi_Trodes.egg-info/dependency_links.txt
+src/Linxi_Trodes.egg-info/entry_points.txt
+src/Linxi_Trodes.egg-info/requires.txt
+src/Linxi_Trodes.egg-info/top_level.txt
+src/linxi_trodes/__init__.py
+src/linxi_trodes/_dio_format.py
+src/linxi_trodes/_rec_header.py
+src/linxi_trodes/export_dio.py
+src/linxi_trodes.egg-info/PKG-INFO
+src/linxi_trodes.egg-info/SOURCES.txt
+src/linxi_trodes.egg-info/dependency_links.txt
+src/linxi_trodes.egg-info/entry_points.txt
+src/linxi_trodes.egg-info/requires.txt
+src/linxi_trodes.egg-info/top_level.txt
+tests/test_export_dio.py

linxi_trodes-1.0.0/src/Linxi_Trodes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

linxi_trodes-1.0.0/src/Linxi_Trodes.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+linxi_trode = linxi_trodes.export_dio:main

linxi_trodes-1.0.0/src/Linxi_Trodes.egg-info/requires.txt

@@ -0,0 +1,2 @@
+pandas
+numpy

linxi_trodes-1.0.0/src/Linxi_Trodes.egg-info/top_level.txt

@@ -0,0 +1 @@
+linxi_trodes

linxi_trodes-1.0.0/src/linxi_trodes/__init__.py

@@ -0,0 +1,2 @@
+# Linxi Refactored Trodes DIO Extractor using python implementation
+from .export_dio import TrodesRecParser

linxi_trodes-1.0.0/src/linxi_trodes/_dio_format.py

@@ -0,0 +1,115 @@
+"""Private helper: format the Trodes ``.dat`` text header and filenames.
+
+Extracted from :mod:`linxi_trodes.export_dio` for the
+dio-raw-return-type refactor (task 2). Provides:
+
+* :func:`dio_dat_filename` — the per-channel filename constructor.
+* :func:`write_dat_header` — the standard Trodes text header
+  writer used by both the event-mode and (future) raw-mode paths.
+
+The legacy ``_write_dat_header`` instance method's bytes are
+preserved verbatim: every ``f.write(...)`` line produces the
+exact same ``.dat`` header as before. The new ``mode`` parameter
+is a forward-compatible hook so the raw-mode header variant
+(planned in task 4) can flip a single argument without
+touching this signature again. ``mode="event"`` is the current
+behavior; the parameter is accepted but currently unused.
+
+Only the standard library is used.
+"""
+
+from __future__ import annotations
+
+from typing import BinaryIO
+
+
+def dio_dat_filename(base_name: str, channel_name: str) -> str:
+    """Return the per-channel ``.dat`` filename used by the extractor.
+
+    Format: ``{base_name}.dio_{channel_name}.dat``. ``base_name`` is
+    the ``.rec`` filename without its extension, ``channel_name`` is
+    the digital channel ID (e.g. ``"DIN1"``).
+    """
+    return f"{base_name}.dio_{channel_name}.dat"
+
+
+# On-disk label for each metadata key, matching the legacy parser's
+# literal f-string labels exactly (no whitespace, no transforms).
+_HEADER_LABELS = {
+    "trodes_version": "Trodes_version",
+    "compile_date": "Compile_date",
+    "compile_time": "Compile_time",
+    "qt_version": "QT_version",
+    "commit_tag": "Commit_tag",
+    "controller_firmware": "Controller_firmware",
+    "headstage_firmware": "Headstage_firmware",
+    "controller_serialnum": "Controller_serialnum",
+    "headstage_serialnum": "Headstage_serialnum",
+    "autosettle": "AutoSettle",
+    "smartref": "SmartRef",
+    "gyro": "Gyro",
+    "accelerometer": "Accelerometer",
+    "magnetometer": "Magnetometer",
+}
+
+# Ordered metadata keys written into the .dat text header. Same order
+# as the legacy parser.
+_HEADER_METADATA_KEYS = tuple(_HEADER_LABELS.keys())
+
+
+def write_dat_header(
+    f: BinaryIO,
+    channel_name: str,
+    channel_index: int,
+    channel_is_input: bool,
+    original_filename: str,
+    sampling_rate: float,
+    metadata: dict[str, str],
+    mode: str = "event",
+) -> None:
+    """Write the standard Trodes ``.dat`` text header.
+
+    Parameters mirror the legacy instance method
+    ``TrodesRecParser._write_dat_header``. ``mode`` is accepted as
+    a forward-compatible hook for the raw-event variant (task 4);
+    it is currently a no-op and the event header is always written.
+
+    The bytes written by this function are byte-for-byte identical
+    to the legacy implementation; the SHA-256 of the resulting
+    ``.dat`` file on the deterministic task-1 fixture is therefore
+    preserved (``1a076c2e...ddae7b39ff``).
+    """
+    # The two modes MUST share every header byte except the
+    # description line so existing Trodes readers consume both files.
+    if mode == "raw":
+        description = (
+            b"Description: Sampled data for one digital channel. "
+            b"Display_order is 1-based\n"
+        )
+    else:
+        description = (
+            b"Description: State change data for one digital channel. "
+            b"Display_order is 1-based\n"
+        )
+
+    f.write(b"<Start settings>\n")
+    f.write(description)
+    f.write(f"Direction: {'input' if channel_is_input else 'output'}\n".encode())
+    f.write(f"ID: {channel_name}\n".encode())
+    f.write(f"Display_order: {channel_index + 1}\n".encode())
+    f.write(b"Byte_order: little endian\n")
+    f.write(f"Original_file: {original_filename}\n".encode())
+    f.write(f"Clockrate: {int(sampling_rate)}\n".encode())
+    for key in _HEADER_METADATA_KEYS:
+        f.write(f"{_HEADER_LABELS[key]}: {metadata.get(key, '-1')}\n".encode())
+    f.write(b"Time_offset: 0\n")
+    f.write(
+        f"System_time_at_creation: "
+        f"{metadata.get('system_time_at_creation', '-1')}\n".encode()
+    )
+    f.write(
+        f"Timestamp_at_creation: "
+        f"{metadata.get('timestamp_at_creation', '-1')}\n".encode()
+    )
+    f.write(b"Fields: <time uint32><state uint8>\n")
+    f.write(b"<End settings>\n")

linxi_trodes-1.0.0/src/linxi_trodes/_rec_header.py

@@ -0,0 +1,291 @@
+"""Private helper: parse the XML header of a Trodes ``.rec`` file.
+
+Extracted from :mod:`linxi_trodes.export_dio` for the
+dio-raw-return-type refactor (task 2). Owns the XML header scan,
+device/channel layout calculation, metadata extraction, and the
+``only_export_enabled`` filter; returns a frozen
+:class:`RecHeader` dataclass.
+
+Behavior preserved verbatim against the legacy ``_parse_header``
+instance method: the ``</Configuration>`` guard, the
+``interleavedDataIDByte`` rejection, the Hardware-vs-Global
+fallback, the ``<DigitalIO><Input>`` augmentation, the
+``only_export_enabled`` filter, and the byte-identical print
+summary. Only the standard library is used.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+
+_CONFIG_END_TAG = b"</Configuration>"
+
+
+@dataclass(frozen=True)
+class RecHeader:
+    """Immutable result of parsing a Trodes ``.rec`` XML header.
+
+    Mirrors the instance attributes populated by the legacy
+    ``TrodesRecParser._parse_header``. ``header_channels`` captures
+    every channel declared by the hardware configuration (any
+    ``dataType``); ``dio_channels`` is the digital-only subset
+    consumed by :func:`linxi_trodes.export_dio.extract_dio`.
+    """
+
+    sampling_rate: float
+    num_channels: int
+    header_size: int
+    packet_size: int
+    binary_offset: int
+    metadata: dict[str, str] = field(default_factory=dict)
+    dio_channels: list[dict] = field(default_factory=list)
+    header_channels: list[dict] = field(default_factory=list)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _scan_until_config_close(f) -> bytes:
+    data = b""
+    while _CONFIG_END_TAG not in data:
+        chunk = f.read(1024)
+        if not chunk:
+            break
+        data += chunk
+    return data
+
+
+def _compute_binary_offset(header_data: bytes, f) -> int:
+    """Skip ``\\n`` or ``\\r\\n`` after ``</Configuration>`` (legacy trodes_data convention)."""
+    end_pos = header_data.find(_CONFIG_END_TAG)
+    if end_pos == -1:
+        raise ValueError("Could not find </Configuration> tag in file.")
+    binary_offset = end_pos + len(_CONFIG_END_TAG)
+    f.seek(binary_offset)
+    next_byte = f.read(1)
+    if next_byte == b"\n":
+        binary_offset += 1
+    elif next_byte == b"\r":
+        binary_offset += 1
+        if f.read(1) == b"\n":
+            binary_offset += 1
+    return binary_offset
+
+
+# XML attribute name -> metadata dict key. Same order as the legacy
+# parser; whitespace-stripped on read.
+_METADATA_FIELDS = (
+    ('trodes_version', 'trodesVersion'),
+    ('compile_date', 'compileDate'),
+    ('compile_time', 'compileTime'),
+    ('qt_version', 'qtVersion'),
+    ('commit_tag', 'commitHead'),
+    ('controller_firmware', 'controllerFirmwareVersion'),
+    ('headstage_firmware', 'headstageFirmwareVersion'),
+    ('controller_serialnum', 'controllerSerial'),
+    ('headstage_serialnum', 'headstageSerial'),
+    ('autosettle', 'headstageAutoSettleOn'),
+    ('smartref', 'headstageSmartRefOn'),
+    ('gyro', 'headstageGyroSensorOn'),
+    ('accelerometer', 'headstageAccelSensorOn'),
+    ('magnetometer', 'headstageMagSensorOn'),
+    ('system_time_at_creation', 'systemTimeAtCreation'),
+    ('timestamp_at_creation', 'timestampAtCreation'),
+)
+
+
+def _build_metadata(global_conf) -> dict[str, str]:
+    if global_conf is None:
+        return {}
+    out: dict[str, str] = {}
+    for key, attr in _METADATA_FIELDS:
+        value = global_conf.get(attr, "-1")
+        if value:
+            value = value.strip()
+        out[key] = value
+    return out
+
+
+def _resolve_hardware_config(root):
+    global_conf = root.find("GlobalConfiguration")
+    hw_conf = root.find("HardwareConfiguration")
+    if hw_conf is None:
+        hw_conf = global_conf
+    if hw_conf is None:
+        raise ValueError(
+            "Could not find HardwareConfiguration or GlobalConfiguration in XML"
+        )
+    return global_conf, hw_conf
+
+
+def _build_device_layout(hw_conf):
+    """Sort devices by priority and compute byte offsets per device."""
+    devices = []
+    for device_node in hw_conf.findall("Device"):
+        name = device_node.get("name")
+        priority = int(device_node.get("packetOrderPreference", 0))
+        # Force SysClock to be last, matching the C++/trodes_data logic.
+        if name == "SysClock":
+            priority = 10000
+        devices.append({
+            "name": name,
+            "numBytes": int(device_node.get("numBytes", 0)),
+            "priority": priority,
+            "node": device_node,
+        })
+    devices.sort(key=lambda x: x["priority"])
+
+    xml_header_size = int(hw_conf.get("headerSize", 0))
+    header_size = 0
+    current_offset = 1  # Start after the sync byte.
+    device_offsets: dict[str, int] = {}
+
+    for dev in devices:
+        # If we have a defined headerSize, SysClock must start after it.
+        if dev["name"] == "SysClock" and xml_header_size > 0:
+            # headerSize is in words (2 bytes), so multiply by 2.
+            expected_start = xml_header_size * 2
+            if current_offset < expected_start:
+                current_offset = expected_start
+        device_offsets[dev["name"]] = current_offset - 1
+        current_offset += dev["numBytes"]
+
+    header_size = current_offset - 1
+    return devices, device_offsets, header_size
+
+
+def _collect_header_channels(devices, device_offsets) -> list[dict]:
+    """Every channel declared by hardware config (any dataType).
+
+    Raises ``NotImplementedError`` on interleaved digital channels
+    using the legacy message verbatim.
+    """
+    out: list[dict] = []
+    for dev in devices:
+        dev_offset = device_offsets[dev["name"]]
+        for chan_node in dev["node"].findall("Channel"):
+            data_type = chan_node.get("dataType")
+            if data_type == "digital":
+                if chan_node.get("interleavedDataIDByte", "-1") != "-1":
+                    raise NotImplementedError(
+                        f"Channel '{chan_node.get('id')}' uses interleaved data, "
+                        "which is not currently supported by this Python script."
+                    )
+            out.append({
+                "id": chan_node.get("id"),
+                "device": dev["name"],
+                "dataType": data_type,
+                "startByte": int(chan_node.get("startByte", 0)),
+                "bit": int(chan_node.get("bit", 0)),
+                "input": chan_node.get("input") == "1",
+                "byte_offset": 1 + dev_offset + int(chan_node.get("startByte", 0)),
+            })
+    return out
+
+
+def _dio_from_header_channels(header_channels: list[dict]) -> list[dict]:
+    return [
+        {"name": ch["id"], "byte_offset": ch["byte_offset"],
+         "bit": ch["bit"], "input": ch["input"]}
+        for ch in header_channels if ch["dataType"] == "digital"
+    ]
+
+
+def _append_digital_io_inputs(root, dio_channels: list[dict]) -> None:
+    dio_root = root.find("DigitalIO")
+    if dio_root is None:
+        return
+    for input_node in dio_root.findall("Input"):
+        name = input_node.get("name")
+        if any(ch["name"] == name for ch in dio_channels):
+            continue
+        dio_channels.append({
+            "name": name,
+            "byte_offset": 1,
+            "bit": int(input_node.get("channel", 0)) - 1,
+            "input": True,
+        })
+
+
+def _apply_enabled_filter(root, dio_channels: list[dict]) -> list[dict]:
+    aux_disp = root.find("AuxDisplayConfiguration")
+    if aux_disp is None:
+        aux_disp = root.find("HeaderDisplay")
+    if aux_disp is None:
+        return dio_channels
+    enabled_ids = {child.get("id") for child in aux_disp if child.get("id")}
+    original_count = len(dio_channels)
+    filtered = [ch for ch in dio_channels if ch["name"] in enabled_ids]
+    print(
+        f"Filtered DIO channels: {original_count} -> {len(filtered)} "
+        "(based on enabled config)"
+    )
+    return filtered
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+
+def parse_rec_header(rec_file: str, only_export_enabled: bool = False) -> RecHeader:
+    """Parse the XML header of ``rec_file`` and return a frozen dataclass.
+
+    See module docstring for preserved behaviors. Raises
+    ``ValueError`` on a missing ``</Configuration>``, missing
+    HardwareConfiguration (with no GlobalConfiguration fallback),
+    or missing ``samplingRate`` attribute; raises
+    ``NotImplementedError`` for interleaved digital channels.
+    """
+    with open(rec_file, "rb") as f:
+        header_data = _scan_until_config_close(f)
+        binary_offset = _compute_binary_offset(header_data, f)
+        header_text = header_data[:binary_offset].decode("utf-8", errors="ignore")
+        root = ET.fromstring(header_text)
+
+    global_conf, hw_conf = _resolve_hardware_config(root)
+    metadata = _build_metadata(global_conf)
+
+    sampling_rate_str = hw_conf.get("samplingRate")
+    if sampling_rate_str is None:
+        raise ValueError("Could not find 'samplingRate' attribute in XML header.")
+    sampling_rate = float(sampling_rate_str)
+    num_channels = int(hw_conf.get("numChannels", 0))
+
+    devices, device_offsets, header_size = _build_device_layout(hw_conf)
+    packet_size = 1 + header_size + 4 + 2 * num_channels
+
+    print("Parsed Header:")
+    print(f"  Sampling Rate: {sampling_rate} Hz")
+    print(f"  Num Neural Channels: {num_channels}")
+    print(f"  Device Header Size: {header_size} bytes")
+    print(f"  Total Packet Size: {packet_size} bytes")
+    print(f"  Binary Offset: {binary_offset}")
+
+    header_channels = _collect_header_channels(devices, device_offsets)
+    dio_channels = _dio_from_header_channels(header_channels)
+    _append_digital_io_inputs(root, dio_channels)
+
+    if only_export_enabled:
+        dio_channels = _apply_enabled_filter(root, dio_channels)
+
+    if not dio_channels:
+        print("Warning: No digital channels found in XML header.")
+    else:
+        print(f"Found {len(dio_channels)} digital channels:")
+        for ch in dio_channels:
+            print(f"  - {ch['name']} (Byte {ch['byte_offset']}, Bit {ch['bit']})")
+
+    return RecHeader(
+        sampling_rate=sampling_rate,
+        num_channels=num_channels,
+        header_size=header_size,
+        packet_size=packet_size,
+        binary_offset=binary_offset,
+        metadata=metadata,
+        dio_channels=dio_channels,
+        header_channels=header_channels,
+    )

linxi_trodes-1.0.0/src/linxi_trodes/export_dio.py

@@ -0,0 +1,297 @@
+"""The python implementation of the Trodes DIO extractor.
+
+Reference: `trodes/python/trodes/trodes_data.py`.
+
+The XML/header layout calculation lives in :mod:`linxi_trodes._rec_header`
+and the `.dat` text header formatting in
+:mod:`linxi_trodes._dio_format` (see task 2 of the
+dio-raw-return-type refactor).
+"""
+
+import os
+import struct
+from typing import Literal
+
+import numpy as np
+from tqdm import tqdm
+
+from ._dio_format import dio_dat_filename, write_dat_header
+from ._rec_header import parse_rec_header
+
+
+class TrodesRecParser:
+    def __init__(self, rec_file, only_export_enabled=False, buffer_packets=20000):
+        self.rec_file = rec_file
+        self.only_export_enabled = only_export_enabled
+        self.buffer_packets = buffer_packets
+        self._parse_header()
+
+    def _parse_header(self):
+        header = parse_rec_header(
+            self.rec_file, only_export_enabled=self.only_export_enabled
+        )
+        self.sampling_rate = header.sampling_rate
+        self.packet_size = header.packet_size
+        self.header_size = header.header_size
+        self.binary_offset = header.binary_offset
+        self.metadata = header.metadata
+        self.dio_channels = header.dio_channels
+        self.num_channels = header.num_channels
+
+    def extract_dio(
+        self,
+        output_dir=None,
+        return_type: Literal["event", "raw"] = "event",
+    ):
+        """
+        从 Trodes .rec 文件中提取数字输入/输出 (DIO) 通道的状态变化事件。
+
+        该函数遍历二进制数据包，检测指定的 DIO 通道位是否发生变化。
+        如果检测到状态变化，则记录当前的时间戳和新状态。
+        结果可以同时保存为 .dat 文件并作为字典返回。
+
+        Args
+        ----
+        output_dir (str, optional): 输出目录路径。
+            如果提供，将为每个 DIO 通道创建一个 .dat 文件（格式为 <base_name>.dio_<ch_name>.dat）。
+            文件包含二进制格式的 <timestamp uint32><state uint8>。
+            默认为 None，即不保存文件。
+        return_type (Literal["event", "raw"], optional):
+            选择返回数据的语义模式。默认为 `event`（与原始行为完全一致）。
+            - `event`：仅保留状态跳变点（默认，旧行为不变）。
+              返回的 `states` 是 `np.uint8`。
+            - `raw`：每个有效包返回一条采样，状态不进行去重；
+              返回的 `states` 是 `np.bool_`。
+
+        Returns
+        -------
+        dict: 包含提取数据的字典。
+            键 (key): 通道名称 (str)。
+            值 (value): 一个元组 (timestamps, states):
+                - timestamps (np.ndarray, dtype=np.uint32): 状态发生变化时的采样计数（Clock ticks）。
+                    单位：1 / sampling_rate 秒。
+                - states (np.ndarray): 变化后的新状态（0 表示低电平，1 表示高电平）。
+                    `event` 模式的 dtype 为 `np.uint8`；`raw` 模式的 dtype 为 `np.bool_`。
+
+        Raises
+        ------
+        ValueError
+            当 `return_type` 不是 `event` 也不是 `raw` 时抛出，且在抛出前
+            不会创建 `output_dir`、不会打开任何文件、不会计算 `num_packets`。
+
+        Note
+        ----
+        - 时间戳的单位取决于 header 中定义的 sampling_rate。
+        - 该函数会自动跳过不以同步字节 0x55 开头的数据包。
+        """
+        # 验证 return_type 必须早于任何副作用：此处还在创建 output_dir、
+        # 打开文件、计算 num_packets 之前就抛出 ValueError，确保无效
+        # 输入不会留下空目录或半截文件。
+        if return_type not in ("event", "raw"):
+            raise ValueError(
+                f"Unknown return_type {return_type!r}; expected 'event' or 'raw'."
+            )
+
+        # 没有 DIO 通道时直接返回空字典，避免后面按通道分配缓冲区时出错。
+        if not self.dio_channels:
+            print("No DIO channels to extract.")
+            return {}
+
+        # output_dir 缺失则自动创建；与原版行为保持一致。
+        if output_dir and not os.path.exists(output_dir):
+            os.makedirs(output_dir)
+
+        # 基础文件名来自 .rec 文件名（去后缀），用于生成 .dat 文件名。
+        base_name = os.path.splitext(os.path.basename(self.rec_file))[0]
+        # 写入 .dat 文件头的 Original_file 字段需要原始文件名。
+        original_filename = os.path.basename(self.rec_file)
+
+        # 把每个通道的元数据（name、byte_offset、bit）展开成平行本地列表，
+        # 这样热循环里不再需要按字符串键查找字典，仅按下标访问即可。
+        ch_names = [ch["name"] for ch in self.dio_channels]
+        ch_byte_offsets = [ch["byte_offset"] for ch in self.dio_channels]
+        ch_bits = [ch["bit"] for ch in self.dio_channels]
+        n_channels = len(ch_names)
+
+        # 这三个列表按下标与 ch_names/ch_byte_offsets/ch_bits 对齐：
+        # output_files 用于按通道写入 .dat；last_states 用于 event 模式的去重
+        # 比较；sample_counts 用于汇总打印。
+        output_files: list = [None] * n_channels
+        last_states: list = [None] * n_channels
+        sample_counts: list = [0] * n_channels
+
+        # 按 chunk 累积 typed numpy 数组：每个通道一个 list，最终只在循环外
+        # 做一次 np.concatenate，避免在热路径里反复拼接造成 O(n²) 复制。
+        chunk_ts_lists = {nm: [] for nm in ch_names}
+        chunk_state_lists = {nm: [] for nm in ch_names}
+
+        # 为每个通道打开输出文件并写入文本头部；mode 参数控制描述行的语义。
+        for i, ch in enumerate(self.dio_channels):
+            if output_dir:
+                file_path = os.path.join(output_dir, dio_dat_filename(base_name, ch["name"]))
+                f = open(file_path, "wb")
+                write_dat_header(
+                    f,
+                    channel_name=ch["name"],
+                    channel_index=i,
+                    channel_is_input=ch["input"],
+                    original_filename=original_filename,
+                    sampling_rate=self.sampling_rate,
+                    metadata=self.metadata,
+                    mode=return_type,
+                )
+                output_files[i] = f
+
+        # 计算整个文件中的完整数据包数量（不足一个包的尾部会被静默丢弃）。
+        file_size = os.path.getsize(self.rec_file)
+        data_size = file_size - self.binary_offset
+        num_packets = data_size // self.packet_size
+
+        print(f"Extracting samples from {num_packets} packets...")
+
+        # 把循环里频繁访问的常量提到外面，避免每包重复求值。
+        packet_size = self.packet_size
+        is_event = return_type == "event"            # 仅 event 模式需要去重
+        ts_start = 1 + self.header_size              # 时间戳在包内的固定偏移
+        state_buf_dtype = np.bool_ if return_type == "raw" else np.uint8
+        # align=False 强制每条记录正好 5 字节；"<u4" 强制 timestamp 小端序。
+        rec_dtype = np.dtype([("ts", "<u4"), ("state", "u1")], align=False)
+
+        with open(self.rec_file, "rb") as f:
+            f.seek(self.binary_offset)
+
+            # 每次最多读 buffer_packets 个完整包，避免一次性占用过多内存；
+            # 末尾不足 buffer_size 的部分会在下一轮 read() 返回空 chunk 时退出。
+            buffer_size = self.buffer_packets * packet_size
+
+            with tqdm(total=num_packets, unit="pkt", dynamic_ncols=True) as pbar:
+                while True:
+                    chunk = f.read(buffer_size)
+                    if not chunk:
+                        break
+
+                    # 实际包数可能小于 buffer_packets
+                    # 用整除丢弃尾部不足一包的字节。
+                    actual_packets = len(chunk) // packet_size
+
+                    # 为本 chunk 预分配 typed numpy 缓冲区（按通道各两个）：
+                    # 一个时间戳、一个状态；写满的子数组再 append 到 chunk_*_lists。
+                    # 这种「先占位、按写指针填」的方式避免了 Python list 反复 append。
+                    ts_bufs = [
+                        np.empty(actual_packets, dtype=np.uint32)
+                        for _ in range(n_channels)
+                    ]
+                    state_bufs = [
+                        np.empty(actual_packets, dtype=state_buf_dtype)
+                        for _ in range(n_channels)
+                    ]
+                    # write_idxs[i] 记录第 i 个通道在本 chunk 已写入缓冲区的行数；
+                    # 无效同步字节的包不会推进写指针，因此最终用 [:w] 切片即可丢弃空位。
+                    write_idxs = [0] * n_channels
+
+                    # 内层循环：对 chunk 中的每个完整包做一次解析。
+                    for pi in range(actual_packets):
+                        ps = pi * packet_size
+
+                        # 同步字节过滤：Trodes 用 0x55 标记一个合法数据包的起点；
+                        # 不以 0x55 开头的字节会被跳过，因此时间戳和位值均不可信。
+                        if chunk[ps] != 0x55:
+                            continue
+
+                        # struct.unpack_from 直接在 chunk 上以偏移读取 uint32，
+                        # 避免 struct.unpack(...) 之前先切片 timestamp 字段。
+                        timestamp = struct.unpack_from("<I", chunk, ps + ts_start)[0]
+
+                        for ci in range(n_channels):
+                            # 直接按下标访问字节，再右移指定 bit 位拿到该通道当前电平。
+                            byte_val = chunk[ps + ch_byte_offsets[ci]]
+                            state = (byte_val >> ch_bits[ci]) & 1
+
+                            # event 模式去重：与上一包电平相同则跳过本条采样；
+                            # raw 模式不做这一步，保证每个有效包都产生一条采样。
+                            if is_event and state == last_states[ci]:
+                                continue
+
+                            # 把当前样本写入本 chunk 的 typed 缓冲区对应位置。
+                            w = write_idxs[ci]
+                            ts_bufs[ci][w] = timestamp
+                            state_bufs[ci][w] = state
+                            write_idxs[ci] = w + 1
+                            last_states[ci] = state
+                            sample_counts[ci] += 1
+
+                    # chunk 内部循环结束：按通道把已写入的子数组 append 到
+                    # 跨 chunk 累积列表，并对已打开的输出文件做一次批量写入。
+                    for ci in range(n_channels):
+                        w = write_idxs[ci]
+                        if w == 0:
+                            continue
+                        nm = ch_names[ci]
+                        ts_slice = ts_bufs[ci][:w]
+                        state_slice = state_bufs[ci][:w]
+                        chunk_ts_lists[nm].append(ts_slice)
+                        chunk_state_lists[nm].append(state_slice)
+
+                        if output_files[ci] is not None:
+                            # 用结构化 dtype 一次性构造一批 <IB> 记录并 tobytes()
+                            # 写出；与逐条 struct.pack("<IB", ts, state) 字节完全一致。
+                            records = np.empty(w, dtype=rec_dtype)
+                            records["ts"] = ts_slice
+                            records["state"] = state_slice.astype(np.uint8)
+                            output_files[ci].write(records.tobytes())
+
+                    pbar.update(actual_packets)
+
+        # 关闭所有按通道打开的输出文件；output_files 中的 None 项是未启用
+        # output_dir 时留下的占位，需要跳过。
+        for f in output_files:
+            if f is not None:
+                f.close()
+
+        # 最后再决定一次返回数组的状态 dtype，与 buffer dtype 一致。
+        state_final_dtype = np.bool_ if return_type == "raw" else np.uint8
+        final_results = {}
+        for nm in ch_names:
+            ts_pieces = chunk_ts_lists[nm]
+            st_pieces = chunk_state_lists[nm]
+            if ts_pieces:
+                # 全文件最终只各做一次 np.concatenate；这里就是 first-layer 优化
+                # 「不在热循环里反复拼接」的兑现点。
+                ts_arr = np.concatenate(ts_pieces).astype(np.uint32)
+                state_arr = np.concatenate(st_pieces).astype(state_final_dtype)
+            else:
+                # 没有有效采样（例如整个文件没有 0x55 同步字节）时返回空数组，
+                # 保证调用方仍能拿到正确 dtype 的空结果。
+                ts_arr = np.empty(0, dtype=np.uint32)
+                state_arr = np.empty(0, dtype=state_final_dtype)
+            final_results[nm] = (ts_arr, state_arr)
+
+        print("\nExtraction Summary:")
+        print(f"{'Channel':<25} {'Samples':<10} {'Final State':<10}")
+        print("-" * 50)
+        for ci, ch in enumerate(self.dio_channels):
+            state_str = "High" if last_states[ci] == 1 else "Low"
+            print(f"{ch['name']:<25} {sample_counts[ci]:<10} {state_str:<10}")
+
+        if output_dir:
+            print(f"\nFiles saved in: {output_dir}")
+
+        return final_results
+
+
+def main():
+    import argparse
+
+    arg_parser = argparse.ArgumentParser(description="Extract DIO data from Trodes .rec file.")
+    arg_parser.add_argument("rec_file", help="Path to the .rec file")
+    arg_parser.add_argument("output_dir", help="Directory to save output files")
+    arg_parser.add_argument("--only-export-enabled-dio", action="store_true", help="Only export DIO channels enabled in the configuration")
+
+    args = arg_parser.parse_args()
+
+    parser = TrodesRecParser(args.rec_file, only_export_enabled=args.only_export_enabled_dio)
+    parser.extract_dio(output_dir=args.output_dir)
+
+
+if __name__ == "__main__":
+    main()

linxi_trodes-1.0.0/tests/test_export_dio.py

@@ -0,0 +1,402 @@
+"""Tests for ``linxi_trodes.export_dio.TrodesRecParser``.
+
+Pins the existing event-mode behavior of ``extract_dio`` and specifies the
+contract for the upcoming ``return_type`` selector. The fixture-backed tests
+below are split into:
+
+* **Baseline tests** exercise the default event path on the current code and
+  must pass before any product change is made.
+* **Red-phase tests** pin the new ``raw`` mode, invalid ``return_type``
+  handling, missing-directory behavior, empty-channel semantics,
+  chunk-boundary safety, and malformed-header guard rails. These tests fail
+  on the current code because ``return_type`` is not yet implemented, but
+  their ``pytest --collect-only`` succeeds and the failure messages point
+  at missing behavior (e.g. ``TypeError: extract_dio() got an unexpected
+  keyword argument 'return_type'``).
+
+Only the Python standard library, NumPy, ``struct``, ``xml.etree.ElementTree``,
+and ``pytest`` are imported; no new dependencies are introduced.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from linxi_trodes import TrodesRecParser
+
+# ---------------------------------------------------------------------------
+# Layout constants used by the synthetic .rec fixture builder
+# ---------------------------------------------------------------------------
+
+# Packet layout (1 + 1 + 4 + 0 = 6 bytes):
+#   offset 0: sync byte (0x55 marks valid packets)
+#   offset 1: single DIO device byte (carries the digital bit)
+#   offset 2..6: timestamp, uint32 little-endian
+PACKET_SIZE = 6
+HEADER_SIZE = 1
+DIO_BYTE_OFFSET = 1
+DIO_BIT = 0
+SAMPLING_RATE_HZ = 30_000.0
+CHANNEL_NAME = "DIN1"
+BASE_NAME = "synthetic"
+
+
+# ---------------------------------------------------------------------------
+# Synthetic .rec fixture builder
+# ---------------------------------------------------------------------------
+
+
+def _build_xml_header() -> bytes:
+    """Return the minimal valid Trodes XML header bytes.
+
+    Describes a single Device (``DIO``) with one digital channel
+    (``DIN1``). The closing ``</Configuration>`` tag is followed by a ``\\n``
+    separator that the parser already strips.
+    """
+    xml = (
+        '<?xml version="1.0" encoding="UTF-8"?>\n'
+        '<Configuration>\n'
+        '  <GlobalConfiguration trodesVersion="2.7.2"/>\n'
+        '  <HardwareConfiguration samplingRate="30000" numChannels="0" headerSize="0">\n'
+        '    <Device name="DIO" numBytes="1" packetOrderPreference="0">\n'
+        '      <Channel id="DIN1" dataType="digital" startByte="0" bit="0" input="1"/>\n'
+        '    </Device>\n'
+        '  </HardwareConfiguration>\n'
+        '</Configuration>\n'
+    )
+    return xml.encode("utf-8")
+
+
+def _build_packet(sync: int, dio_byte: int, timestamp: int) -> bytes:
+    """Construct one ``PACKET_SIZE``-byte packet.
+
+    Layout: ``<sync u8><dio u8><timestamp u32 LE>``.
+    """
+    return struct.pack(
+        "<BBI", sync & 0xFF, dio_byte & 0xFF, timestamp & 0xFFFFFFFF
+    )
+
+
+def _build_trailing_partial(fill_byte: int = 0xAA) -> bytes:
+    """Three garbage bytes that the parser must drop (less than PACKET_SIZE)."""
+    return bytes([fill_byte]) * (PACKET_SIZE - 3)
+
+
+def write_synthetic_rec(
+    target: Path,
+    packets: list[tuple[int, int, int]],
+    trailing_partial: bytes = b"",
+) -> Path:
+    """Write a synthetic Trodes ``.rec`` file to ``target``.
+
+    Parameters
+    ----------
+    target : Path
+        Destination file path.
+    packets : list of (sync, dio_byte, timestamp)
+        Per-packet builder arguments. Use ``sync != 0x55`` to mark a packet
+        that the parser must skip.
+    trailing_partial : bytes
+        Bytes appended after the final full packet. Anything shorter than
+        ``PACKET_SIZE`` is silently dropped by the parser.
+    """
+    header = _build_xml_header()
+    body = b"".join(_build_packet(*p) for p in packets) + trailing_partial
+    target.write_bytes(header + body)
+    return target
+
+
+@pytest.fixture
+def synthetic_rec(tmp_path: Path) -> Path:
+    """A deterministic ``.rec`` covering the canonical parser scenarios.
+
+    Contains ten full packets (plus one invalid-sync packet and a trailing
+    three-byte partial) covering repeated states, transitions, the invalid
+    sync-byte rule, a chunk-boundary case (driven by ``buffer_packets=1``
+    in the chunk-boundary test), and a trailing partial packet.
+    """
+    packets = [
+        (0x55, 0x00, 0),  # state=0, baseline
+        (0x55, 0x00, 1),  # state=0 (repeat; event mode drops)
+        (0x55, 0x00, 2),  # state=0 (repeat)
+        (0x55, 0x01, 3),  # transition 0 -> 1
+        (0x55, 0x01, 4),  # state=1 (repeat)
+        (0x55, 0x01, 5),  # state=1 (repeat)
+        (0x55, 0x00, 6),  # transition 1 -> 0
+        (0x00, 0x01, 7),  # INVALID sync byte (parser must skip)
+        (0x55, 0x01, 8),  # transition 0 -> 1
+        (0x55, 0x01, 9),  # state=1 (repeat)
+    ]
+    return write_synthetic_rec(
+        tmp_path / "synthetic.rec",
+        packets=packets,
+        trailing_partial=_build_trailing_partial(),
+    )
+
+
+@pytest.fixture
+def no_valid_packet_rec(tmp_path: Path) -> Path:
+    """A ``.rec`` whose every packet has an invalid sync byte."""
+    packets = [
+        (0x00, 0x00, 0),
+        (0xAA, 0x00, 1),
+        (0x33, 0x01, 2),
+    ]
+    return write_synthetic_rec(tmp_path / "no_valid.rec", packets=packets)
+
+
+@pytest.fixture
+def malformed_xml_rec(tmp_path: Path) -> Path:
+    """A ``.rec`` whose XML header lacks the ``</Configuration>`` terminator."""
+    broken = (
+        b'<?xml version="1.0" encoding="UTF-8"?>\n'
+        b'<Configuration>\n'
+        b'  <GlobalConfiguration/>\n'
+    )
+    target = tmp_path / "broken.rec"
+    target.write_bytes(broken + b"\x55" * 16)
+    return target
+
+
+# ---------------------------------------------------------------------------
+# Helpers for parsing .dat files written by the extractor
+# ---------------------------------------------------------------------------
+
+
+def _read_dat_records(dat_path: Path) -> list[tuple[int, int]]:
+    """Return the ``(timestamp, state)`` tuples after the ``.dat`` text header."""
+    raw = dat_path.read_bytes()
+    end_marker = b"<End settings>\n"
+    end_pos = raw.find(end_marker)
+    assert end_pos != -1, f"<End settings> marker missing from {dat_path}"
+    binary = raw[end_pos + len(end_marker):]
+    records: list[tuple[int, int]] = []
+    for offset in range(0, len(binary), 5):
+        chunk = binary[offset : offset + 5]
+        if len(chunk) < 5:
+            break
+        ts, state = struct.unpack("<IB", chunk)
+        records.append((ts, state))
+    return records
+
+
+def _sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Pre-change baseline tests (must pass on the current code)
+# ---------------------------------------------------------------------------
+
+
+def test_event_default_matches_event_explicit(synthetic_rec: Path) -> None:
+    """Default ``extract_dio()`` returns event-mode arrays.
+
+    Pins the default behavior so the upcoming ``return_type`` selector
+    cannot change what callers get when the keyword is omitted.
+    """
+    parser = TrodesRecParser(str(synthetic_rec))
+    result = parser.extract_dio()
+    assert CHANNEL_NAME in result
+    timestamps, states = result[CHANNEL_NAME]
+    assert timestamps.dtype == np.uint32
+    assert states.dtype == np.uint8
+    np.testing.assert_array_equal(
+        timestamps, np.array([0, 3, 6, 8], dtype=np.uint32)
+    )
+    np.testing.assert_array_equal(
+        states, np.array([0, 1, 0, 1], dtype=np.uint8)
+    )
+
+
+def test_event_bytes_are_byte_identical_to_default(
+    synthetic_rec: Path, tmp_path: Path
+) -> None:
+    """Two consecutive ``extract_dio(output_dir=...)`` runs produce
+    byte-identical event ``.dat`` files."""
+    out_a = tmp_path / "out_a"
+    out_b = tmp_path / "out_b"
+    TrodesRecParser(str(synthetic_rec)).extract_dio(output_dir=str(out_a))
+    TrodesRecParser(str(synthetic_rec)).extract_dio(output_dir=str(out_b))
+    file_a = out_a / f"{BASE_NAME}.dio_{CHANNEL_NAME}.dat"
+    file_b = out_b / f"{BASE_NAME}.dio_{CHANNEL_NAME}.dat"
+    assert file_a.exists(), "expected event .dat to be written to out_a"
+    assert file_b.exists(), "expected event .dat to be written to out_b"
+    assert file_a.read_bytes() == file_b.read_bytes()
+
+
+def test_event_returns_uint32_timestamps_and_uint8_states(
+    synthetic_rec: Path,
+) -> None:
+    """Event mode exposes ``np.uint32`` timestamps and ``np.uint8`` states."""
+    parser = TrodesRecParser(str(synthetic_rec))
+    timestamps, states = parser.extract_dio()[CHANNEL_NAME]
+    assert timestamps.dtype == np.uint32
+    assert states.dtype == np.uint8
+
+
+# ---------------------------------------------------------------------------
+# Red-phase tests (fail on current code because ``return_type`` is not yet
+# implemented; failures must point at missing behavior)
+# ---------------------------------------------------------------------------
+
+
+def test_raw_returns_one_sample_per_valid_packet(synthetic_rec: Path) -> None:
+    """``return_type='raw'`` returns one (timestamp, state) sample per valid
+    packet and skips packets with a non-``0x55`` leading byte."""
+    parser = TrodesRecParser(str(synthetic_rec))
+    timestamps, states = parser.extract_dio(return_type="raw")[CHANNEL_NAME]
+    # 10 packets total; packet with sync byte 0x00 is invalid; the 3-byte
+    # trailing partial is shorter than PACKET_SIZE and is ignored.
+    assert len(timestamps) == 9
+    assert len(states) == 9
+    np.testing.assert_array_equal(
+        timestamps,
+        np.array([0, 1, 2, 3, 4, 5, 6, 8, 9], dtype=np.uint32),
+    )
+
+
+def test_raw_dtype_is_uint32_and_bool(synthetic_rec: Path) -> None:
+    """Raw timestamps are ``np.uint32`` and raw states are ``np.bool_``."""
+    parser = TrodesRecParser(str(synthetic_rec))
+    timestamps, states = parser.extract_dio(return_type="raw")[CHANNEL_NAME]
+    assert timestamps.dtype == np.uint32
+    assert states.dtype == np.bool_
+
+
+def test_raw_retains_repeated_states(synthetic_rec: Path) -> None:
+    """Raw mode does NOT deduplicate; consecutive identical states are kept."""
+    parser = TrodesRecParser(str(synthetic_rec))
+    timestamps, states = parser.extract_dio(return_type="raw")[CHANNEL_NAME]
+    # The three leading state=0 samples remain, the three middle state=1
+    # samples remain, and the closing state=1 samples remain, unlike the
+    # event view which collapses to transitions only.
+    assert bool(states[0]) is False
+    assert bool(states[1]) is False
+    assert bool(states[2]) is False
+    assert bool(states[3]) is True
+    assert bool(states[4]) is True
+    assert bool(states[5]) is True
+    assert bool(states[6]) is False
+    assert bool(states[7]) is True
+    assert bool(states[8]) is True
+    assert len(timestamps) == len(states) == 9
+
+
+def test_raw_files_contain_every_valid_packet(
+    synthetic_rec: Path, tmp_path: Path
+) -> None:
+    """``output_dir`` in raw mode writes one record per valid packet."""
+    out = tmp_path / "raw_out"
+    TrodesRecParser(str(synthetic_rec)).extract_dio(
+        return_type="raw", output_dir=str(out)
+    )
+    dat = out / f"{BASE_NAME}.dio_{CHANNEL_NAME}.dat"
+    records = _read_dat_records(dat)
+    assert len(records) == 9, f"expected 9 raw records, got {len(records)}"
+    assert records == [
+        (0, 0), (1, 0), (2, 0), (3, 1), (4, 1), (5, 1), (6, 0), (8, 1), (9, 1)
+    ]
+
+
+def test_raw_file_records_are_five_bytes_little_endian(
+    synthetic_rec: Path, tmp_path: Path
+) -> None:
+    """Each raw ``.dat`` record is exactly 5 bytes: little-endian uint32 + uint8."""
+    out = tmp_path / "raw_out"
+    TrodesRecParser(str(synthetic_rec)).extract_dio(
+        return_type="raw", output_dir=str(out)
+    )
+    dat = out / f"{BASE_NAME}.dio_{CHANNEL_NAME}.dat"
+    raw = dat.read_bytes()
+    end_marker = b"<End settings>\n"
+    binary = raw[raw.find(end_marker) + len(end_marker):]
+    assert len(binary) == 5 * 9, (
+        f"raw binary region must be 5*9=45 bytes, got {len(binary)}"
+    )
+    # Spot-check little-endian byte ordering: ts=3 -> 03 00 00 00; state=1 -> 01.
+    assert binary[0:5] == struct.pack("<IB", 0, 0)
+    assert binary[5:10] == struct.pack("<IB", 1, 0)
+    assert binary[10:15] == struct.pack("<IB", 2, 0)
+    assert binary[15:20] == struct.pack("<IB", 3, 1)
+    # The 3-byte trailing partial from the input must NOT appear in the output.
+    assert b"\xaa\xaa\xaa" not in binary
+
+
+def test_raw_output_dir_respects_missing_directory(
+    synthetic_rec: Path, tmp_path: Path
+) -> None:
+    """A non-existent ``output_dir`` is created automatically when writing raw ``.dat``."""
+    out = tmp_path / "deep" / "nested" / "raw"
+    assert not out.exists()
+    TrodesRecParser(str(synthetic_rec)).extract_dio(
+        return_type="raw", output_dir=str(out)
+    )
+    assert out.is_dir()
+    assert (out / f"{BASE_NAME}.dio_{CHANNEL_NAME}.dat").exists()
+
+
+def test_invalid_return_type_raises_value_error(synthetic_rec: Path) -> None:
+    """An unknown ``return_type`` raises ``ValueError`` before opening output."""
+    parser = TrodesRecParser(str(synthetic_rec))
+    with pytest.raises(ValueError):
+        parser.extract_dio(return_type="bogus")
+
+
+def test_no_valid_packets_returns_empty_arrays(no_valid_packet_rec: Path) -> None:
+    """A file with no valid packets returns empty raw arrays with the right dtypes."""
+    parser = TrodesRecParser(str(no_valid_packet_rec))
+    result = parser.extract_dio(return_type="raw")
+    assert CHANNEL_NAME in result
+    timestamps, states = result[CHANNEL_NAME]
+    assert len(timestamps) == 0
+    assert len(states) == 0
+    assert timestamps.dtype == np.uint32
+    assert states.dtype == np.bool_
+
+
+def test_event_to_raw_transitions_match(synthetic_rec: Path) -> None:
+    """Compressing raw samples to transitions reproduces event-mode results."""
+    parser = TrodesRecParser(str(synthetic_rec))
+    raw_ts, raw_st = parser.extract_dio(return_type="raw")[CHANNEL_NAME]
+    # Build the event-mode view by selecting transitions only.
+    transitions_ts = [int(raw_ts[0])]
+    transitions_st = [int(raw_st[0])]
+    for i in range(1, len(raw_ts)):
+        if int(raw_st[i]) != transitions_st[-1]:
+            transitions_ts.append(int(raw_ts[i]))
+            transitions_st.append(int(raw_st[i]))
+    # Compare against a fresh event-mode run.
+    parser_event = TrodesRecParser(str(synthetic_rec))
+    event_ts, event_st = parser_event.extract_dio()[CHANNEL_NAME]
+    np.testing.assert_array_equal(
+        np.array(transitions_ts, dtype=np.uint32), event_ts
+    )
+    np.testing.assert_array_equal(
+        np.array(transitions_st, dtype=np.uint8), event_st
+    )
+
+
+def test_chunk_boundary_does_not_lose_packets(synthetic_rec: Path) -> None:
+    """With ``buffer_packets=1`` each chunk holds one packet; no packet is lost."""
+    parser = TrodesRecParser(str(synthetic_rec), buffer_packets=1)
+    timestamps, states = parser.extract_dio(return_type="raw")[CHANNEL_NAME]
+    assert len(timestamps) == 9
+    assert len(states) == 9
+
+
+def test_malformed_xml_raises(malformed_xml_rec: Path) -> None:
+    """A header missing ``</Configuration>`` raises a parse error rather than
+    silently producing empty output.
+
+    Guards the existing header validation so future changes to
+    ``extract_dio`` cannot accidentally swallow header errors (e.g. by
+    silently returning empty results).
+    """
+    with pytest.raises(ValueError):
+        TrodesRecParser(str(malformed_xml_rec))