readmanager 1.2.0

Read, write and convert OpenBCI signal recordings (.raw/.xml/.tag)

readmanager

Read, write and convert OpenBCI signal recordings stored in the OBCI file format (.raw / .xml / .tag).

Installation

pip install readmanager            # core (numpy only)
pip install readmanager[mne]       # + MNE-Python conversion
pip install readmanager[balance]   # + Wii Balance Board analysis (scipy)
pip install readmanager[all]       # everything

Requires Python 3.10+.

Quick start

from obci_readmanager.signal_processing.read_manager import ReadManager

# Open a recording (three files: .raw, .xml, .tag)
mgr = ReadManager(
    "recording.obci.xml",
    "recording.obci.raw",
    "recording.obci.tag",
)

# Access signal parameters
print(mgr.get_param("sampling_frequency"))
print(mgr.get_param("channels_names"))

# Get all samples as a numpy array (channels x samples)
samples = mgr.get_samples()

# Get samples for a single channel
fp1 = mgr.get_channel_samples("Fp1")

# Get samples in microvolts (applies gain and offset calibration)
uv = mgr.get_microvolt_samples()

# Iterate over tags (event markers)
for tag in mgr.iter_tags():
    print(tag["name"], tag["start_timestamp"])

Smart tags

Smart tags extract signal segments aligned to event markers:

from obci_readmanager.signal_processing.smart_tags_manager import SmartTagsManager
from obci_readmanager.signal_processing.tags.smart_tag_definition import SmartTagDurationDefinition

# Define: 1 second of signal after each "stimulus" tag
tag_def = SmartTagDurationDefinition(
    start_tag_name="stimulus",
    start_offset=0.0,
    end_offset=0.0,
    duration=1.0,
)

smart_mgr = SmartTagsManager(
    tag_def,
    "recording.obci.xml",
    "recording.obci.raw",
    "recording.obci.tag",
)

for smart_tag in smart_mgr.iter_smart_tags():
    data = smart_tag.get_samples()  # channels x samples for this epoch
    print(data.shape)

MNE-Python conversion

# ReadManager -> MNE Raw
raw_mne = mgr.get_mne_raw()

# MNE Raw -> ReadManager
mgr2 = ReadManager.from_mne(raw_mne)

# Smart tags -> MNE Epochs
epochs = smart_mgr.get_mne_epochs()

OBCI file format

An OpenBCI recording consists of three files:

File	Content
.obci.raw	Binary signal data (channels interleaved, float64 by default)
.obci.xml	Recording metadata: channel names, sampling frequency, gains, offsets
.obci.tag	Event markers in XML format (name, timestamp, duration, description)

License

GNU General Public License v3 or later (GPLv3+).

Originally developed by BrainTech and the Faculty of Physics, University of Warsaw.