Skip to content

Add read_openephys_binary and catalogue-based probe construction for OpenEphys#406

Open
h-mayorquin wants to merge 5 commits intoSpikeInterface:mainfrom
h-mayorquin:separate_open_ephys
Open

Add read_openephys_binary and catalogue-based probe construction for OpenEphys#406
h-mayorquin wants to merge 5 commits intoSpikeInterface:mainfrom
h-mayorquin:separate_open_ephys

Conversation

@h-mayorquin
Copy link
Collaborator

@h-mayorquin h-mayorquin commented Mar 11, 2026

This adds read_openephys_binary(settings_file, oebin_file, stream_name), a new reader for Open Ephys binary format recordings that uses both settings.xml (probe geometry) and structure.oebin (binary data layout) to build probes. It also refactors read_openephys to use catalogue-based probe construction, fixing contact_id consistency with SpikeGLX. See #405 for the broader discussion on separating probe construction from wiring.

Both readers now follow the same pattern as read_spikeglx (introduced in PR #383): build the full probe from the catalogue via build_neuropixels_probe, then combine it with data from the source files to determine which electrodes are active and how they map to the data. For SpikeGLX, the source file is the .meta file (IMRO table). For Open Ephys, the settings.xml provides electrode positions (via ELECTRODE_XPOS/ELECTRODE_YPOS) or electrode indices (via SELECTED_ELECTRODES), which are matched against the catalogue probe geometry to select the active contacts. read_openephys_binary additionally reads the structure.oebin to set device_channel_indices. As proposed in SpikeInterface/spikeinterface#4435, the oebin contains per-channel electrode_index metadata (added in neuropixels-pxi plugin v0.5.0, January 2023) that maps each binary file column to its electrode index. When available and non-zero, read_openephys_binary uses this for wiring. For older recordings where electrode_index is missing or all zeros, it falls back to identity wiring, which is correct because the binary .dat file is always written in channel-number order (as confirmed by Josh Siegle). The existing read_openephys is kept for backward compatibility and always sets identity wiring since it has no oebin.

Because both readers now derive contact_ids from the catalogue probe, this also fixes #394 (OpenEphys contact_ids inconsistent with SpikeGLX). The previous code reverse-engineered electrode IDs from positions, which produced different IDs than SpikeGLX for probes where OpenEphys positions don't exactly match the canonical geometry. @chrishalcrow identified the affected datasets in the existing test data (OE_Neuropix-PXI-NP-Ultra, OE_6.7_enabled_disabled_Neuropix-PXI, OE_Neuropix-PXI-QuadBase). A new consistency test verifies that for these and other datasets, the contact_ids from read_openephys are a subset of the catalogue probe's contact_ids.

Other changes:

  • Each contact in read_openephys_binary is annotated with plugin_channel_key (the XML CHANNELS key, e.g. "CH0", "CH29"), distinct from neo's channel_name which comes from the oebin and uses different naming conventions.
  • Two new test datasets (NP2014 single-shank, NP1032 4-shank) with paired settings.xml + structure.oebin files.
  • There is an edge case described in Test data labeled NP1100 has electrode positions inconsistent with NP1100 catalogue geometry #407 which I am addressing here.

@h-mayorquin h-mayorquin self-assigned this Mar 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

OpenEphys contact_ids inconsistent with SpikeGLX when SELECTED_ELECTRODES is not available

1 participant