| Name | pybv JSON |
| Version |
0.7.6
JSON |
| download |
| home_page | None |
| Summary | pybv - a lightweight I/O utility for the BrainVision data format |
| upload_time | 2024-11-25 20:52:38 |
| maintainer | None |
| docs_url | None |
| author | pybv developers |
| requires_python | >=3.9 |
| license | BSD 3-Clause License Copyright (c) 2018, pybv developers All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
brain products
brainvision
eeg
vhdr
vmrk
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. 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 <https://pybv.rtfd.io/en/stable/>`_
- `latest (development) documentation <https://pybv.rtfd.io/en/latest/>`_
.. 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 <https://bids.neuroimaging.io>`_.
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 <https://www.brainproducts.com>`_,
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 <https://en.wikipedia.org/wiki/INI_file>`_
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 <https://www.brainproducts.com/support-resources/brainvision-core-data-format-1-0/>`_
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 <https://mne.tools/stable/install/index.html>`_.
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 <https://docs.conda.io/en/latest/miniconda.html>`_:
.. 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 <https://github.com/bids-standard/pybv>`_.
For more information, please see
`CONTRIBUTING.md <https://github.com/bids-standard/pybv/blob/main/.github/CONTRIBUTING.md>`_.
Citing
======
If you use this software in academic work, please cite it using the `Zenodo entry <https://zenodo.org/badge/latestdoi/157434681>`_.
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 <https://mne.tools>`_
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 <https://github.com/bids-standard/pybv>`_.
Please let us know if you know of additional packages that should be listed here.
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name of software | Language | Notes |
+=============================================================================+======================+=============================================================================================================================================================+
| `BioSig Project <http://biosig.sourceforge.net/index.html>`_ | miscellaneous | Reading and writing capabilities depend on bindings used, see their `overview <https://pub.ist.ac.at/~schloegl/biosig/TESTED>`_ |
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `Brainstorm <https://neuroimage.usc.edu/brainstorm/>`_ | MATLAB | Read and write, search for ``brainamp`` in their `io functions <https://github.com/brainstorm-tools/brainstorm3/tree/master/toolbox/io>`_ |
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `BrainVision Analyzer <https://www.brainproducts.com/downloads.php?kid=9>`_ | n/a, GUI for Windows | Read and write, by Brain Products, requires commercial license |
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `brainvisionloader.jl <https://github.com/agricolab/brainvisionloader.jl>`_ | Julia | Read |
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `EEGLAB <https://sccn.ucsd.edu/eeglab/index.php>`_ | MATLAB / Octave | Read and write via `BVA-IO <https://github.com/arnodelorme/bva-io>`_ |
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `FieldTrip <https://www.fieldtriptoolbox.org>`_ | MATLAB | Read and write, search for ``brainvision`` in their `ft_read_data and ft_write_data functions <https://github.com/fieldtrip/fieldtrip/tree/master/fileio>`_ |
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
| `MNE-Python <https://mne.tools>`_ | Python | Read (writing via ``pybv``) |
+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
Acknowledgements
================
This package was originally adapted from the
`Philistine package <https://gitlab.com/palday/philistine>`_ by
`palday <https://phillipalday.com/>`_.
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.
Raw data
{
"_id": null,
"home_page": null,
"name": "pybv",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "Stefan Appelhoff <stefan.appelhoff@mailbox.org>",
"keywords": "Brain Products, BrainVision, eeg, vhdr, vmrk",
"author": "pybv developers",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e7/35/6b61dcca1386b14d368b5f927e1babcf8f6c6171a04e4e21a344d159d857/pybv-0.7.6.tar.gz",
"platform": null,
"description": ".. image:: https://github.com/bids-standard/pybv/workflows/Python%20build/badge.svg\n :target: https://github.com/bids-standard/pybv/actions?query=workflow%3A%22Python+build%22\n :alt: Python build\n\n.. image:: https://github.com/bids-standard/pybv/workflows/Python%20tests/badge.svg\n :target: https://github.com/bids-standard/pybv/actions?query=workflow%3A%22Python+tests%22\n :alt: Python tests\n\n.. image:: https://codecov.io/gh/bids-standard/pybv/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/bids-standard/pybv\n :alt: Test coverage\n\n.. image:: https://readthedocs.org/projects/pybv/badge/?version=stable\n :target: https://pybv.readthedocs.io/en/stable/?badge=stable\n :alt: Documentation Status\n\n.. image:: https://badge.fury.io/py/pybv.svg\n :target: https://badge.fury.io/py/pybv\n :alt: PyPi version\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/pybv.svg\n :target: https://anaconda.org/conda-forge/pybv\n :alt: Conda version\n\n.. image:: https://zenodo.org/badge/157434681.svg\n :target: https://zenodo.org/badge/latestdoi/157434681\n :alt: Zenodo archive\n\n====\npybv\n====\n\nFor documentation, see the:\n\n- `stable documentation <https://pybv.rtfd.io/en/stable/>`_\n- `latest (development) documentation <https://pybv.rtfd.io/en/latest/>`_\n\n.. docs_readme_include_label\n\n``pybv`` is a lightweight I/O utility for the BrainVision data format.\n\nThe BrainVision data format is a recommended data format for use in the\n`Brain Imaging Data Structure <https://bids.neuroimaging.io>`_.\n\nAbout the BrainVision data format\n=================================\n\nBrainVision is the name of a file format commonly used for storing electrophysiology data.\nOriginally, it was put forward by the company `Brain Products <https://www.brainproducts.com>`_,\nhowever the simplicity of the format has allowed for a diversity of tools reading from and\nwriting to the format.\n\nThe format consists of three separate files:\n\n1. A text header file (``.vhdr``) containing meta data\n2. A text marker file (``.vmrk``) containing information about events in the\n data\n3. A binary data file (``.eeg``) containing the voltage values of the EEG\n\nBoth text files are based on the\n`Microsoft Windows INI format <https://en.wikipedia.org/wiki/INI_file>`_\nconsisting of:\n\n- sections marked as ``[square brackets]``\n- comments marked as ``; comment``\n- key-value pairs marked as ``key=value``\n\nThe binary ``.eeg`` data file is written in little-endian format without a Byte Order\nMark (BOM), in accordance with the specification by Brain Products.\nThis ensures that the data file is uniformly written irrespective of the\nnative system architecture.\n\nA documentation for the BrainVision file format is provided by Brain Products.\nYou can `view the specification <https://www.brainproducts.com/support-resources/brainvision-core-data-format-1-0/>`_\nas hosted by Brain Products.\n\nInstallation\n============\n\n``pybv`` runs on Python version 3.9 or higher.\n\n``pybv``'s only dependency is ``numpy``.\nHowever, we currently recommend that you install MNE-Python for reading BrainVision data.\nSee their `installation instructions <https://mne.tools/stable/install/index.html>`_.\n\nAfter you have a working installation of MNE-Python (or only ``numpy`` if you\ndo not want to read data and only write it), you can install ``pybv`` through\nthe following:\n\n.. code-block:: Text\n\n python -m pip install --upgrade pybv\n\nor if you use `conda <https://docs.conda.io/en/latest/miniconda.html>`_:\n\n.. code-block:: Text\n\n conda install --channel conda-forge pybv\n\nFor installing the **latest (development)** version of ``pyprep``, call:\n\n.. code-block:: Text\n\n python -m pip install --upgrade https://github.com/bids-standard/pybv/archive/refs/heads/main.zip\n\nBoth the *stable* and the *latest* installation will additionally install\nall required dependencies automatically.\nThe dependencies are defined in the ``pyproject.toml`` file under the\n``dependencies`` and ``project.optional-dependencies`` sections.\n\nContributing\n============\n\nThe development of ``pybv`` is taking place on\n`GitHub <https://github.com/bids-standard/pybv>`_.\n\nFor more information, please see\n`CONTRIBUTING.md <https://github.com/bids-standard/pybv/blob/main/.github/CONTRIBUTING.md>`_.\n\nCiting\n======\n\nIf you use this software in academic work, please cite it using the `Zenodo entry <https://zenodo.org/badge/latestdoi/157434681>`_.\nMetadata is encoded in the `CITATION.cff` file.\n\nUsage\n=====\n\nWriting BrainVision files\n-------------------------\n\nThe primary functionality provided by ``pybv`` is the ``write_brainvision``\nfunction. This writes a numpy array of data and provided metadata into a\ncollection of BrainVision files on disk.\n\n.. code-block:: python\n\n from pybv import write_brainvision\n\n # for further parameters see our API documentation\n write_brainvision(data=data, sfreq=sfreq, ch_names=ch_names,\n fname_base=fname, folder_out=tmpdir,\n events=events)\n\nReading BrainVision files\n-------------------------\n\nCurrently, ``pybv`` recommends using `MNE-Python <https://mne.tools>`_\nfor reading BrainVision files.\n\nHere is an example of the MNE-Python code required to read BrainVision data:\n\n.. code-block:: python\n\n import mne\n\n # Import the BrainVision data into an MNE Raw object\n raw = mne.io.read_raw_brainvision('tmp/test.vhdr', preload=True)\n\n # Reconstruct the original events from our Raw object\n events, event_ids = mne.events_from_annotations(raw)\n\nAlternatives\n============\n\nThe BrainVision data format is very popular and accordingly there are many\nsoftware packages to read this format, or write to it.\nThe following table is intended as a quick overview of packages similar to\n`pybv <https://github.com/bids-standard/pybv>`_.\nPlease let us know if you know of additional packages that should be listed here.\n\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| Name of software | Language | Notes |\n+=============================================================================+======================+=============================================================================================================================================================+\n| `BioSig Project <http://biosig.sourceforge.net/index.html>`_ | miscellaneous | Reading and writing capabilities depend on bindings used, see their `overview <https://pub.ist.ac.at/~schloegl/biosig/TESTED>`_ |\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `Brainstorm <https://neuroimage.usc.edu/brainstorm/>`_ | MATLAB | Read and write, search for ``brainamp`` in their `io functions <https://github.com/brainstorm-tools/brainstorm3/tree/master/toolbox/io>`_ |\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `BrainVision Analyzer <https://www.brainproducts.com/downloads.php?kid=9>`_ | n/a, GUI for Windows | Read and write, by Brain Products, requires commercial license |\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `brainvisionloader.jl <https://github.com/agricolab/brainvisionloader.jl>`_ | Julia | Read |\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `EEGLAB <https://sccn.ucsd.edu/eeglab/index.php>`_ | MATLAB / Octave | Read and write via `BVA-IO <https://github.com/arnodelorme/bva-io>`_ |\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `FieldTrip <https://www.fieldtriptoolbox.org>`_ | MATLAB | Read and write, search for ``brainvision`` in their `ft_read_data and ft_write_data functions <https://github.com/fieldtrip/fieldtrip/tree/master/fileio>`_ |\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n| `MNE-Python <https://mne.tools>`_ | Python | Read (writing via ``pybv``) |\n+-----------------------------------------------------------------------------+----------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+\n\nAcknowledgements\n================\n\nThis package was originally adapted from the\n`Philistine package <https://gitlab.com/palday/philistine>`_ by\n`palday <https://phillipalday.com/>`_.\nIt copies much of the BrainVision exporting code, but removes the dependence on MNE.\nSeveral features have been added, such as support for individual units for each channel.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2018, pybv developers All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "pybv - a lightweight I/O utility for the BrainVision data format",
"version": "0.7.6",
"project_urls": {
"Documentation": "https://pybv.readthedocs.io",
"Issues": "https://github.com/bids-standard/pybv/issues",
"Repository": "https://github.com/bids-standard/pybv"
},
"split_keywords": [
"brain products",
" brainvision",
" eeg",
" vhdr",
" vmrk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d7e0041e56e455d26d5fb644dde3976cffa135e658ac5572c2ca7ab40245af2",
"md5": "f06c338614257a150fb24c6eee04ba5c",
"sha256": "5b2816b3547035c8b806fcca7705c67f8be5c6ca5fee26486754bd492f180139"
},
"downloads": -1,
"filename": "pybv-0.7.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f06c338614257a150fb24c6eee04ba5c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 16211,
"upload_time": "2024-11-25T20:52:37",
"upload_time_iso_8601": "2024-11-25T20:52:37.684168Z",
"url": "https://files.pythonhosted.org/packages/7d/7e/0041e56e455d26d5fb644dde3976cffa135e658ac5572c2ca7ab40245af2/pybv-0.7.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e7356b61dcca1386b14d368b5f927e1babcf8f6c6171a04e4e21a344d159d857",
"md5": "1ac645f9aa474d288e20f4eadeca1049",
"sha256": "518dac9bf151601c45787bf0ddcc5e37afd61033058eb734067825f8ae46d51b"
},
"downloads": -1,
"filename": "pybv-0.7.6.tar.gz",
"has_sig": false,
"md5_digest": "1ac645f9aa474d288e20f4eadeca1049",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 16002,
"upload_time": "2024-11-25T20:52:38",
"upload_time_iso_8601": "2024-11-25T20:52:38.973583Z",
"url": "https://files.pythonhosted.org/packages/e7/35/6b61dcca1386b14d368b5f927e1babcf8f6c6171a04e4e21a344d159d857/pybv-0.7.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-25 20:52:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bids-standard",
"github_project": "pybv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pybv"
}
