{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Importing data from EEG devices\n\nMNE includes various functions and utilities for reading EEG data and electrode\nlocations.\n\n\n## BrainVision (.vhdr, .vmrk, .eeg)\n\nThe BrainVision file 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 [INI format](https://en.wikipedia.org/wiki/INI_file)\nconsisting of\n\n* sections marked as ``[square brackets]``,\n* comments marked as ``; comment``,\n* and key-value pairs marked as ``key=value``.\n\nBrain Products provides documentation for their core BrainVision file format.\nThe format specification is hosted on the\n[Brain Products website](https://www.brainproducts.com/support-resources/brainvision-core-data-format-1-0/).\n\nBrainVision EEG files can be read using :func:`mne.io.read_raw_brainvision`,\npassing the ``.vhdr`` header file as the argument.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>Renaming BrainVision files can be problematic due to their\n             multi-file structure. See this\n             [example](https://mne.tools/mne-bids/stable/auto_examples/rename_brainvision_files.html#sphx-glr-auto-examples-rename-brainvision-files-py)\n             for instructions.</p></div>\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>For *writing* BrainVision files, take a look at the :mod:`mne.export`\n          module, which used the [pybv](https://pypi.org/project/pybv/) Python\n          package.</p></div>\n\n\n\n## European data format (.edf)\n\n[EDF](http://www.edfplus.info/specs/edf.html) and\n[EDF+](http://www.edfplus.info/specs/edfplus.html) files can be read using\n:func:`mne.io.read_raw_edf`. Both variants are 16-bit formats.\n\nEDF+ files may contain annotation channels which can be used to store trigger\nand event information. These annotations are available in ``raw.annotations``.\n\nWriting EDF files is not supported natively yet. [This gist](https://gist.github.com/skjerns/bc660ef59dca0dbd53f00ed38c42f6be)_ or\n[MNELAB](https://github.com/cbrnr/mnelab) (both of which use\n[pyedflib](https://github.com/holgern/pyedflib) under the hood) can be used\nto export any :class:`mne.io.Raw` object to EDF/EDF+/BDF/BDF+.\n\n\n\n## BioSemi data format (.bdf)\n\nThe [BDF format](http://www.biosemi.com/faq/file_format.htm) is a 24-bit\nvariant of the EDF format used by EEG systems manufactured by BioSemi. It can\nbe imported with :func:`mne.io.read_raw_bdf`.\n\nBioSemi amplifiers do not perform \"common mode noise rejection\" automatically.\nThe signals in the EEG file are the voltages between each electrode and the CMS\nactive electrode, which still contain some CM noise (50 Hz, ADC reference\nnoise, etc.). The [BioSemi FAQ](https://www.biosemi.com/faq/cms&drl.htm)_\nprovides more details on this topic.\nTherefore, it is advisable to choose a reference (e.g., a single channel like Cz,\naverage of linked mastoids, average of all electrodes, etc.) after importing\nBioSemi data to avoid losing signal information. The data can be re-referenced\nlater after cleaning if desired.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>Data samples in a BDF file are represented in a 3-byte\n             (24-bit) format. Since 3-byte raw data buffers are not presently\n             supported in the FIF format, these data will be changed to 4-byte\n             integers in the conversion.</p></div>\n\n\n\n## General data format (.gdf)\n\nGDF files can be read using :func:`mne.io.read_raw_gdf`.\n\n[GDF (General Data Format)](https://arxiv.org/abs/cs/0608052) is a flexible\nformat for biomedical signals that overcomes some of the limitations of the\nEDF format. The original specification (GDF v1) includes a binary header\nand uses an event table. An updated specification (GDF v2) was released in\n2011 and adds fields for additional subject-specific information (gender,\nage, etc.) and allows storing several physical units and other properties.\nBoth specifications are supported by MNE.\n\n\n\n## Neuroscan CNT (.cnt)\n\nCNT files can be read using :func:`mne.io.read_raw_cnt`.\nChannel locations can be read from a montage or the file header. If read\nfrom the header, the data channels (channels that are not assigned to EOG, ECG,\nEMG or MISC) are fit to a sphere and assigned a z-value accordingly. If a\nnon-data channel does not fit to the sphere, it is assigned a z-value of 0.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>Reading channel locations from the file header may be dangerous, as the\n    x_coord and y_coord in the ELECTLOC section of the header do not necessarily\n    translate to absolute locations. Furthermore, EEG electrode locations that\n    do not fit to a sphere will distort the layout when computing the z-values.\n    If you are not sure about the channel locations in the header, using a\n    montage is encouraged.</p></div>\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>ANT Neuro also uses a file format with the ``.cnt`` extension, but it is different\n    from the Neuroscan CNT format. The ANT Neuro format is supported by the function\n    :func:`mne.io.read_raw_ant`.</p></div>\n\n\n\n## ANT Neuro CNT (.cnt)\n\nCNT files from the eego software of ANT Neuro can be read using\n:func:`mne.io.read_raw_ant`. The channels can be automatically recognized as auxiliary\n``'misc'`` channels if the regular expression in the argument ``misc`` correctly\ncaptures the channel names. Same for EOG channels with the regular expression in the\nargument ``eog``. Note that if a montage with specific bipolar channels is applied on\nexport, they can be loaded as EEG bipolar channel pairs by providing the argument\n``bipolars``. All other EEG channels will be loaded as regular EEG channels referenced\nto the same electrode.\n\n<div class=\"alert alert-danger\"><h4>Warning</h4><p>Neuroscan also uses a file format with the ``.cnt`` extension, but it is different\n    from the eego CNT format. The Neuroscan CNT format is supported by the function\n    :func:`mne.io.read_raw_cnt`.</p></div>\n\n\n## EGI simple binary (.egi)\n\nEGI simple binary files can be read using :func:`mne.io.read_raw_egi`.\nEGI raw files are simple binary files with a header and can be exported by the\nEGI Netstation acquisition software.\n\n\n\n## EGI MFF (.mff)\n\nEGI MFF files can be read with :func:`mne.io.read_raw_egi`.\n\n\n\n## EEGLAB files (.set, .fdt)\n\nEEGLAB .set files (which sometimes come with a separate .fdt file) can be read\nusing :func:`mne.io.read_raw_eeglab` and :func:`mne.read_epochs_eeglab`.\n\n\n\n## Nicolet (.data)\n\nThese files can be read with :func:`mne.io.read_raw_nicolet`.\n\n\n\n## eXimia EEG data (.nxe)\n\nEEG data from the Nexstim eXimia system can be read with\n:func:`mne.io.read_raw_eximia`.\n\n\n\n## Persyst EEG data (.lay, .dat)\n\nEEG data from the Persyst system can be read with\n:func:`mne.io.read_raw_persyst`.\n\nNote that subject metadata may not be properly imported because Persyst\nsometimes changes its specification from version to version. Please let us know\nif you encounter a problem.\n\n\n## Nihon Kohden EEG data (.eeg, .21e, .pnt, .log)\n\nEEG data from the Nihon Kohden (NK) system can be read using the\n:func:`mne.io.read_raw_nihon` function.\n\nFiles with the following extensions will be read:\n\n- The ``.eeg`` file contains the actual raw EEG data.\n- The ``.pnt`` file contains metadata related to the recording such as the\n  measurement date.\n- The ``.log`` file contains annotations for the recording.\n- The ``.21e`` file contains channel and electrode information.\n\nReading ``.11d``, ``.cmt``, ``.cn2``, and ``.edf`` files is currently not\nsupported.\n\nNote that not all subject metadata may be properly read because NK changes the\nspecification sometimes from version to version. Please let us know if you\nencounter a problem.\n\n\n## XDF data (.xdf, .xdfz)\n\nMNE-Python does not support loading\n[XDF](https://github.com/sccn/xdf/wiki/Specifications) files out of the box,\nbecause the inherent flexibility of the XDF format makes it difficult to\nprovide a one-size-fits-all function. For example, XDF supports signals from\nvarious modalities recorded with different sampling rates. However, it is\nrelatively straightforward to import only a specific stream (such as EEG\nsignals) using the [pyxdf](https://github.com/xdf-modules/pyxdf) package.\nSee `ex-read-xdf` for a simple example.\n\nA more sophisticated version, which supports selection of specific streams as\nwell as converting marker streams into annotations, is available in\n[MNELAB](https://github.com/cbrnr/mnelab). If you want to use this\nfunctionality in a script, MNELAB records its history (View - History), which\ncontains all commands required to load an XDF file after successfully loading\nthat file with the graphical user interface.\n\n\n## Setting EEG references\n\nThe preferred method for applying an EEG reference in MNE is\n:func:`mne.set_eeg_reference`, or equivalent instance methods like\n:meth:`raw.set_eeg_reference() <mne.io.Raw.set_eeg_reference>`. By default,\nthe data are assumed to already be properly referenced. See\n`tut-set-eeg-ref` for more information.\n\n\n## Reading electrode locations and head shapes for EEG recordings\n\nSome EEG formats (e.g., EGI, EDF/EDF+, BDF) contain neither electrode locations\nnor head shape digitization information. Therefore, this information has to be\nprovided separately. For that purpose, all raw instances have a\n:meth:`mne.io.Raw.set_montage` method to set electrode locations.\n\nWhen using locations of fiducial points, the digitization data are converted to\nthe MEG head coordinate system employed in the MNE software, see\n`coordinate_systems`.\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.12.2"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}