GitHub Actions Python build GitHub Actions Python tests Codecov PyPi version Conda version Documentation Status Zenodo archive

pybv

pybv is a lightweight I/O utility for the BrainVision data format.

The BrainVision data format is a recommended data format for use in the Brain Imaging Data Structure.

The documentation can be found under the following links:

About the BrainVision data format

BrainVision is the name of a file format commonly used for storing electrophysiology data. Originally, it was put forward by the company Brain Products, however the simplicity of the format has allowed for a diversity of tools reading from and writing to the format.

The format consists of three separate files:

  1. A text header file (.vhdr) containing meta data

  2. A text marker file (.vmrk) containing information about events in the data

  3. A binary data file (.eeg) containing the voltage values of the EEG

Both text files are based on the Microsoft Windows INI format consisting of:

  • sections marked as [square brackets]

  • comments marked as ; comment

  • key-value pairs marked as key=value

The binary .eeg data file is written in little-endian format without a Byte Order Mark (BOM), in accordance with the specification by Brain Products. This ensures that the data file is uniformly written irrespective of the native system architecture.

A documentation for the BrainVision file format is provided by Brain Products. You can view the specification as hosted by Brain Products.

Installation

pybv runs on Python version 3.7 or higher.

pybv’s only dependency is numpy. However, we currently recommend that you install MNE-Python for reading BrainVision data. See their installation instructions.

After you have a working installation of MNE-Python (or only numpy if you do not want to read data and only write it), you can install pybv through the following:

  • pip install --upgrade pybv

or if you use conda:

  • conda install --channel conda-forge pybv

Contributing

The development of pybv is taking place on GitHub.

For more information, please see CONTRIBUTING.md

Usage

Writing BrainVision files

The primary functionality provided by pybv is the write_brainvision function. This writes a numpy array of data and provided metadata into a collection of BrainVision files on disk.

from pybv import write_brainvision

# for further parameters see our API documentation
write_brainvision(data=data, sfreq=sfreq, ch_names=ch_names,
                  fname_base=fname, folder_out=tmpdir,
                  events=events)

Reading BrainVision files

Currently, pybv recommends using MNE-Python for reading BrainVision files.

Here is an example of the MNE-Python code required to read BrainVision data:

import mne

# Import the BrainVision data into an MNE Raw object
raw = mne.io.read_raw_brainvision('tmp/test.vhdr', preload=True)

# Reconstruct the original events from our Raw object
events, event_ids = mne.events_from_annotations(raw)

Alternatives

The BrainVision data format is very popular and accordingly there are many software packages to read this format, or write to it. The following table is intended as a quick overview of packages similar to pybv. Please let us know if you know of additional packages that should be listed here.

Name of software

Language

Notes

BioSig Project

miscellaneous

Reading and writing capabilities depend on bindings used, see their overview

Brainstorm

MATLAB

Read and write, search for brainamp in their io functions

BrainVision Analyzer

n/a, GUI for Windows

Read and write, by Brain Products, requires commercial license

brainvisionloader.jl

Julia

Read

EEGLAB

MATLAB / Octave

Read and write via BVA-IO

FieldTrip

MATLAB

Read and write, search for brainvision in their fileio functions

MNE-Python

Python

Read (writing via pybv)

Acknowledgements

This package was originally adapted from the Philistine package by palday. It copies much of the BrainVision exporting code, but removes the dependence on MNE. Several features have been added, such as support for individual units for each channel.

API Documentation

Here we list the Application Programming Interface (API) for pybv.

pybv

write_brainvision(*, data, sfreq, ch_names)

Write raw data to the BrainVision format [R40c166337b24-1].

Authors

People who contributed to this software across releases (in alphabetical order):

Changelog

Here we list a changelog of pybv.

0.7.5 (2022-10-24)

Bug

  • Fix in private pybv._export module: handle annotations that do not contain an entry "ch_names", by Felix Klotzsche (#100)

  • Fix issue with variable reference when the first event was not of type "Stimulus"" or "Response" , by Stefan Appelhoff: (#102)

0.7.4 (2022-07-07)

Changelog

0.7.3 (2022-06-04)

Bug

  • Fix in private pybv._export module: durations of 1 sample length are fine even if they are at the last data sample, by Stefan Appelhoff (#92)

0.7.2 (2022-06-01)

Bug

  • Fixed that raw.annotations must take raw.first_time into account in private pybv._export module for export to BrainVision from MNE-Python, by Stefan Appelhoff (#91)

0.7.1 (2022-05-28)

Bug

  • Fixed a bug in private pybv._export module for export to BrainVision from MNE-Python, by Stefan Appelhoff: (#90)

0.7.0 (2022-05-28)

Changelog

0.6.0 (2021-09-29)

Changelog
API
Bug

0.5.0 (2021-01-03)

Changelog
API

0.4.0 (2020-11-08)

Changelog

  • Passing a “greek small letter mu” to the unit parameter in pybv.write_brainvision() instead of a “micro sign” is now permitted, because the former will be automatically convert to the latter, by Stefan Appelhoff (#47)

Bug
API

0.3.0 (2020-04-02)

Changelog

  • Add unit parameter for exporting signals in a specific unit (V, mV, µV or uV, nV), by Clemens Brunner (#39)

API

0.2.0 (2019-08-26)

Changelog

  • Add option to disable writing a meas_date event (which is also the new default), by Clemens Brunner (#32)

  • Support event durations by passing an (N, 3) array to the events parameter (the third column contains the event durations), by Clemens Brunner (#33)

0.1.0 (2019-06-23)

Changelog
Bug

  • fix bug with events indexing. VMRK events are now correctly written with 1-based indexing, by Stefan Appelhoff (#29)

  • fix bug with events that only have integer codes of length less than 3, by Stefan Appelhoff (#26)

0.0.2 (2019-04-28)

Changelog

0.0.1 (2018-12-10)

Changelog