biosigIO

A Python package for biosignal import/export and manipulation across modalities (EEG, EMG, iEEG, MEG, and behavioral/marker streams). biosigIO provides a unified Recording interface for loading data from many acquisition systems and archives (EEGLAB, Delsys Trigno, OTB, EDF/BDF, WFDB, XDF, MEG/CTF and BrainVision via MNE, and proprietary electrophysiology such as Intan/Blackrock via python-neo) and exporting it to standardized and serving formats (EDF/BDF, Parquet, Arrow, Zarr) with harmonized metadata.

The determination of the EDF/BDF format is based on the dynamic range of the data. If the data is within the range of 16-bit integers (~90dB), the EDF format is used. Otherwise, the BDF format is used. This is to ensure that the data is stored in the most efficient format possible. This determination is made automatically using SVD decomposition and/or FFT to determine the dynamic range of the data. (Alternatively, the user can override the format selection by explicitly indicating their desired format).

Documentation

The documentation including installation instructions, examples, and API reference is available at https://neuromechanist.github.io/biosigio/.

Features

• Import biosignal recordings from many systems and archives:

  • EEGLAB set files (supported)
  • Delsys Trigno (supported)
  • OTB Systems (supported)
  • EDF/BDF(+) (supported, including annotations)
  • WFDB (supported, including annotations)
  • XDF/Lab Streaming Layer (supported, multi-stream)
  • MEG: .fif and CTF .ds via MNE (supported; meg extra)
  • BrainVision .vhdr via MNE (supported; meg extra)
  • Proprietary electrophysiology via python-neo: Intan, Blackrock, Spike2, Plexon, Micromed, Neuralynx (supported; neo extra)
  • Generic CSV (supported with auto-detection)
  • Noraxon (planned)

• Smart import:

  • Automatic file format detection based on extension
  • Specialized format detection for CSV files
  • Custom importers for system-specific formats
  • Automatic annotation/event loading (WFDB, EDF+/BDF+, and EEGLAB .set) into the events table, embedded back on EDF+/BDF+ export and carried in the Parquet/Arrow/Zarr serialization formats
  • LSL timestamp preservation for XDF files (for synchronization)

• Export to standardized formats:

  • EDF/BDF(+) with channels.tsv metadata (automatically selects format based on signal properties, preserves annotations)

• Serialization & serving (see docs):

  • Parquet and Arrow/Feather: lossless columnar round-trip (analytics, fast IPC); requires the arrow extra
  • Zarr: cloud-native serving store (one store serves viewing, inference, and training), a derived downsampled copy; requires the zarr extra

• Data manipulation:

  • Channel selection
  • Metadata handling
  • Event/Annotation handling (access, add)
  • Basic signal visualization
  • Raw data access and modification

Installation

biosigIO uses UV for Python environment and package management.

From PyPI (recommended)

uv pip install biosigio

(If your own project is uv-managed, use uv add biosigio to track it as a dependency.)

From source

git clone https://github.com/neuromechanist/biosigio.git
cd biosigio
uv pip install .

Usage

Basic Example

from biosigio import Recording

# Load data with automatic format detection
rec = Recording.from_file('data.csv')  # Format detected from file extension

# Load data with explicit importer
rec = Recording.from_file('data.csv', importer='trigno')

# Plot specific channels
rec.plot_signals(['EMG1', 'EMG2'])

# Export to EDF or BDF (format automatically determined)
rec.to_edf('output.edf')

Generic CSV Import

# Import a generic CSV file
rec = Recording.from_file('data.csv', importer='csv',
                   sample_frequency=1000,  # Required if no time column
                   has_header=True,        # Whether file has header row
                   channel_names=['EMG_L', 'EMG_R', 'ACC_X'])

Channel Selection

# Select specific channels
subset_emg = rec.select_channels(['EMG1', 'EMG2', 'ACC1'])

# Select all channels of a specific type
emg_only = rec.select_channels(channel_type='EMG')

# Plot selected channels
subset_emg.plot_signals()

Metadata Handling

# Set metadata
rec.set_metadata('subject', 'S001')
rec.set_metadata('condition', 'resting')

# Get metadata
subject = rec.get_metadata('subject')

Development

Setup

1. Clone the repository:

git clone https://github.com/neuromechanist/biosigio.git
cd biosigio

2. Install for development (editable install with dev dependencies):

uv sync --extra dev

Running Tests

uv run pytest

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

Acknowledgment

This project is partially supported by a Meta Reality Labs gift to @sccn and NIH 5R01NS047293.