pybv 0.8.1

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.10 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:

python -m pip install --upgrade pybv

or if you use conda:

conda install --channel conda-forge pybv

For installing the latest (development) version of pyprep, call:

python -m pip install --upgrade https://github.com/bids-standard/pybv/archive/refs/heads/main.zip

Both the stable and the latest installation will additionally install all required dependencies automatically. The dependencies are defined in the pyproject.toml file under the dependencies and project.optional-dependencies sections.

Contributing

The development of pybv is taking place on GitHub.

For more information, please see CONTRIBUTING.md.

Citing

If you use this software in academic work, please cite it using the Zenodo entry. Metadata is encoded in the CITATION.cff file.

Usage

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)

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.

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.