pybv

A lightweight I/O utility for the BrainVision data format, written in Python.

https://github.com/bids-standard/pybv

Keywords

Keywords from Contributors

Repository

A lightweight I/O utility for the BrainVision data format, written in Python.

README.rst

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

Owner

Citation (CITATION.cff)

# YAML 1.2
---
# Metadata for citation of this software according to the CFF format (https://citation-file-format.github.io/)
cff-version: 1.2.0
title: "pybv -- A lightweight I/O utility for the BrainVision data format."
message: "If you use this software, please cite it using the metadata below."
authors:
- given-names: "Stefan"
  family-names: "Appelhoff"
  orcid: "https://orcid.org/0000-0001-8002-0877"
- given-names: "Clemens"
  family-names: "Brunner"
  orcid: "https://orcid.org/0000-0002-6030-2233"
- given-names: "Tristan"
  family-names: "Stenner"
  orcid: "https://orcid.org/0000-0002-2428-9051"
- given-names: "Chris R."
  family-names: "Holdgraf"
  orcid: "https://orcid.org/0000-0002-2391-0678"
- given-names: "Richard"
  family-names: "Höchenberger"
  orcid: "https://orcid.org/0000-0002-0380-4798"
- given-names: "Adam"
  family-names: "Li"
  orcid: "https://orcid.org/0000-0001-8421-365X"
- given-names: "Phillip"
  family-names: "Alday"
  orcid: "https://orcid.org/0000-0002-9984-5745"
- given-names: "Aniket"
  family-names: "Pradhan"
  orcid: https://orcid.org/0000-0002-6705-5116
- given-names: "Pierre"
  family-names: "Cutellic"
  orcid: "https://orcid.org/0000-0002-7224-9222"
- given-names: "Felix"
  family-names: "Klotzsche"
  orcid: "https://orcid.org/0000-0003-3985-2481"
- given-names: "Benjamin"
  family-names: "Beasley"
  orcid: "https://orcid.org/0009-0002-6936-5959"
- given-names: "Robert"
  family-names: "Oostenveld"
  orcid: "https://orcid.org/0000-0002-1974-1293"
type: software
repository-code: "https://github.com/bids-standard/pybv"
url: "https://pybv.readthedocs.io/"
license: BSD-3-Clause
identifiers:
  - description: "Code archive on Zenodo"
    type: doi
    value: 10.5281/zenodo.5539451
keywords:
  - data
  - eeg
  - vision
  - products
  - brain
  - ieeg
  - brainvision
  - brainproducts
  - vhdr
  - vmrk
...

GitHub Events

Committers

Last synced: almost 3 years ago

Issues and Pull Requests

Last synced: 6 months ago

Packages