pybv 0.7.5

Description:

pybv 0.7.5

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:

for the stable release
for the latest (development) version


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:

A text header file (.vhdr) containing meta data
A text marker file (.vmrk) containing information about events in the
data
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.