https://github.com/bids-standard/pybv
A lightweight I/O utility for the BrainVision data format, written in Python.
https://github.com/bids-standard/pybv
brain brainproducts brainvision data eeg ieeg products vhdr vision vmrk
Last synced: 4 months ago
JSON representation
A lightweight I/O utility for the BrainVision data format, written in Python.
- Host: GitHub
- URL: https://github.com/bids-standard/pybv
- Owner: bids-standard
- License: bsd-3-clause
- Created: 2018-11-13T19:30:16.000Z (about 7 years ago)
- Default Branch: main
- Last Pushed: 2025-08-18T07:48:15.000Z (6 months ago)
- Last Synced: 2025-09-04T23:44:13.914Z (5 months ago)
- Topics: brain, brainproducts, brainvision, data, eeg, ieeg, products, vhdr, vision, vmrk
- Language: Python
- Homepage: https://pybv.readthedocs.io/
- Size: 606 KB
- Stars: 22
- Watchers: 5
- Forks: 13
- Open Issues: 6
-
Metadata Files:
- Readme: README.rst
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
.. image:: https://github.com/bids-standard/pybv/workflows/Python%20build/badge.svg
:target: https://github.com/bids-standard/pybv/actions?query=workflow%3A%22Python+build%22
:alt: Python build
.. image:: https://github.com/bids-standard/pybv/workflows/Python%20tests/badge.svg
:target: https://github.com/bids-standard/pybv/actions?query=workflow%3A%22Python+tests%22
:alt: Python tests
.. image:: https://codecov.io/gh/bids-standard/pybv/branch/main/graph/badge.svg
:target: https://codecov.io/gh/bids-standard/pybv
:alt: Test coverage
.. image:: https://readthedocs.org/projects/pybv/badge/?version=stable
:target: https://pybv.readthedocs.io/en/stable/?badge=stable
:alt: Documentation Status
.. image:: https://badge.fury.io/py/pybv.svg
:target: https://badge.fury.io/py/pybv
:alt: PyPi version
.. image:: https://img.shields.io/conda/vn/conda-forge/pybv.svg
:target: https://anaconda.org/conda-forge/pybv
:alt: Conda version
.. image:: https://zenodo.org/badge/157434681.svg
:target: https://zenodo.org/badge/latestdoi/157434681
:alt: Zenodo archive
====
pybv
====
For documentation, see the:
- `stable documentation `_
- `latest (development) documentation `_
.. docs_readme_include_label
``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 `_.
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.9 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:
.. code-block:: Text
python -m pip install --upgrade pybv
or if you use `conda `_:
.. code-block:: Text
conda install --channel conda-forge pybv
For installing the **latest (development)** version of ``pyprep``, call:
.. code-block:: Text
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
=====
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.
.. code-block:: python
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:
.. code-block:: python
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 `ft_read_data and ft_write_data 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.