{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "\n\n# Importing data from MEG devices\n\nThis section describes how to read data for various MEG manufacturers.\n\n\n## MEGIN/Elekta Neuromag VectorView and TRIUX (.fif)\n\nNeuromag Raw FIF files can be loaded using :func:`mne.io.read_raw_fif`.\n\nIf the data were recorded with MaxShield on and have not been processed\nwith MaxFilter, they may need to be loaded with\n``mne.io.read_raw_fif(..., allow_maxshield=True)``.\n\n\n## FIL OPM (.bin)\nMEG data from the OPM system used by the FIL at UCL can be read with\n:func:`mne.io.read_raw_fil`. For related OPM processing methods, see\n`tut-opm-processing`.\n\n\n## Artemis123 (.bin)\nMEG data from the Artemis123 system can be read with\n:func:`mne.io.read_raw_artemis123`.\n\n\n\n## 4-D Neuroimaging / BTI data (dir)\n\nMNE-Python provides :func:`mne.io.read_raw_bti` to read and convert 4D / BTI\ndata. This reader function will by default replace the original channel names,\ntypically composed of the letter ``A`` and the channel number with Neuromag.\nTo import the data, the following input files are mandatory:\n\n- A data file (typically c,rfDC)\n  containing the recorded MEG time series.\n\n- A hs_file\n  containing the digitizer data.\n\n- A config file\n  containing acquisition information and metadata.\n\nBy default :func:`mne.io.read_raw_bti` assumes that these three files are located\nin the same folder.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>While reading the reference or compensation channels,\n          the compensation weights are currently not processed.\n          As a result, the :class:`mne.io.Raw` object and the corresponding fif\n          file does not include information about the compensation channels\n          and the weights to be applied to realize software gradient\n          compensation. If the data are saved in the Magnes system are already\n          compensated, there will be a small error in the forward calculations,\n          whose significance has not been evaluated carefully at this time.</p></div>\n\n\n\n## CTF data (dir)\n\nThe function :func:`mne.io.read_raw_ctf` can be used to read CTF data.\n\n### CTF Polhemus data\n\nThe function :func:`mne.channels.read_dig_polhemus_isotrak` can be used to read\nPolhemus data.\n\n### Applying software gradient compensation\n\nSince the software gradient compensation employed in CTF\nsystems is a reversible operation, it is possible to change the\ncompensation status of CTF data in the data files as desired. This\nsection contains information about the technical details of the\ncompensation procedure and a description of\n:func:`mne.io.Raw.apply_gradient_compensation`.\n\nThe raw instances returned by :func:`mne.io.read_raw_ctf` contain several\ncompensation matrices which are employed to suppress external disturbances\nwith help of the reference channel data. The reference sensors are\nlocated further away from the brain than the helmet sensors and\nare thus measuring mainly the external disturbances rather than magnetic\nfields originating in the brain. Most often, a compensation matrix\ncorresponding to a scheme nicknamed *Third-order gradient\ncompensation* is employed.\n\nLet us assume that the data contain $n_1$ MEG\nsensor channels, $n_2$ reference sensor\nchannels, and $n_3$ other channels.\nThe data from all channels can be concatenated into a single vector\n\n\\begin{align}x = [x_1^T x_2^T x_3^T]^T\\ ,\\end{align}\n\nwhere $x_1$, $x_2$,\nand $x_3$ are the data vectors corresponding\nto the MEG sensor channels, reference sensor channels, and other\nchannels, respectively. The data before and after compensation,\ndenoted here by $x_{(0)}$ and $x_{(k)}$, respectively,\nare related by\n\n\\begin{align}x_{(k)} = M_{(k)} x_{(0)}\\ ,\\end{align}\n\nwhere the composite compensation matrix is\n\n\\begin{align}M_{(k)} = \\begin{bmatrix}\n                I_{n_1} & C_{(k)} & 0 \\\\\n                0 & I_{n_2} & 0 \\\\\n                0 & 0 & I_{n_3}\n                \\end{bmatrix}\\ .\\end{align}\n\nIn the above, $C_{(k)}$ is a $n_1$ by $n_2$ compensation\ndata matrix corresponding to compensation \"grade\" $k$.\nIt is easy to see that\n\n\\begin{align}M_{(k)}^{-1} = \\begin{bmatrix}\n                I_{n_1} & -C_{(k)} & 0 \\\\\n                0 & I_{n_2} & 0 \\\\\n                0 & 0 & I_{n_3}\n                \\end{bmatrix}\\ .\\end{align}\n\nTo convert from compensation grade $k$ to $p$ one\ncan simply multiply the inverse of one compensate compensation matrix\nby another and apply the product to the data:\n\n\\begin{align}x_{(k)} = M_{(k)} M_{(p)}^{-1} x_{(p)}\\ .\\end{align}\n\nThis operation is performed by :meth:`mne.io.Raw.apply_gradient_compensation`.\n\n\n\n## Ricoh/KIT MEG system data (.con/.sqd)\n\nMNE-Python includes the :func:`mne.io.read_raw_kit` and\n:func:`mne.read_epochs_kit` to read and convert Ricoh/KIT MEG data.\n\n.. admonition:: Channel naming\n    :class: sidebar warning\n\n    In MNE 0.21 This reader function will by default replace the original channel names,\n    which typically with index starting with zero, with ones with an index starting\n    with one. In 0.22 it will use native names when possible. Use the\n    ``standardize_names`` argument to control this behavior.\n\nTo import continuous data, only the input .sqd or .con file is needed. For\nepochs, an Nx3 matrix containing the event number/corresponding trigger value\nin the third column is needed.\n\nThe following input files are optional:\n\n- A KIT marker file (mrk file) or an array-like containing the locations of\n  the HPI coils in the MEG device coordinate system.\n  These data are used together with the elp file to establish the coordinate\n  transformation between the head and device coordinate systems.\n\n- A Polhemus points file (elp file) or an array-like\n  containing the locations of the fiducials and the head-position\n  indicator (HPI) coils. These data are usually given in the Polhemus\n  head coordinate system.\n\n- A Polhemus head shape data file (hsp file) or an array-like\n  containing locations of additional points from the head surface.\n  These points must be given in the same coordinate system as that\n  used for the elp file.\n\nModern Ricoh systems may encode this information it the file itself, in which\ncase ``mrk``, ``elp``, and ``hsp`` can all be ``None`` and the data will be\nread from the file itself.\n\n<div class=\"alert alert-info\"><h4>Note</h4><p>The output fif file will use the Neuromag head coordinate system convention,\n   see `coordinate_systems`. A coordinate transformation between the\n   Polhemus head coordinates and the Neuromag head coordinates is included.</p></div>\n\nBy default, KIT-157 systems assume the first 157 channels are the MEG channels,\nthe next 3 channels are the reference compensation channels, and channels 160\nonwards are designated as miscellaneous input channels (MISC 001, MISC 002,\netc.).\nBy default, KIT-208 systems assume the first 208 channels are the MEG channels,\nthe next 16 channels are the reference compensation channels, and channels 224\nonwards are designated as miscellaneous input channels (MISC 001, MISC 002,\netc.).\n\nIn addition, it is possible to synthesize the digital trigger channel (STI 014)\nfrom available analog trigger channel data by specifying the following\nparameters:\n\n- A list of trigger channels (stim) or default triggers with order: '<' | '>'\n  Channel-value correspondence when converting KIT trigger channels to a\n  Neuromag-style stim channel. By default, we assume the first eight\n  miscellaneous channels are trigger channels. For '<', the largest values are\n  assigned to the first channel (little endian; default). For '>', the largest\n  values are assigned to the last channel (big endian). Can also be specified\n  as a list of trigger channel indexes.\n- The trigger channel slope (slope) : '+' | '-'\n  How to interpret values on KIT trigger channels when synthesizing a\n  Neuromag-style stim channel. With '+', a positive slope (low-to-high)\n  is interpreted as an event. With '-', a negative slope (high-to-low)\n  is interpreted as an event.\n- A stimulus threshold (stimthresh) : float\n  The threshold level for accepting voltage changes in KIT trigger\n  channels as a trigger event.\n\nThe synthesized trigger channel data value at sample $k$ will\nbe:\n\n\\begin{align}s(k) = \\sum_{p = 1}^n {t_p(k) 2^{p - 1}}\\ ,\\end{align}\n\nwhere $t_p(k)$ are the thresholded\nfrom the input channel data d_p(k):\n\n\\begin{align}t_p(k) = \\Bigg\\{ \\begin{array}{l}\n                 0 \\text{  if  } d_p(k) \\leq t\\\\\n                 1 \\text{  if  } d_p(k) > t\n             \\end{array}\\ .\\end{align}\n\nThe threshold value $t$ can\nbe adjusted with the ``stimthresh`` parameter.\n\n\n\n## FieldTrip MEG/EEG data (.mat)\n\nMNE-Python includes :func:`mne.io.read_raw_fieldtrip`, :func:`mne.read_epochs_fieldtrip` and :func:`mne.read_evoked_fieldtrip` to read data coming from FieldTrip.\n\nThe data is imported directly from a ``.mat`` file.\n\nThe ``info`` parameter can be explicitly set to ``None``. The import functions will still work but:\n\n#. All channel locations will be in head coordinates.\n#. Channel orientations cannot be guaranteed to be accurate.\n#. All channel types will be set to generic types.\n\nThis is probably fine for anything that does not need that information, but if you intent to do things like interpolation of missing channels, source analysis or look at the RMS pairs of planar gradiometers, you most likely run into problems.\n\nIt is **highly recommended** to provide the ``info`` parameter as well. The ``info`` dictionary can be extracted by loading the original raw data file with the corresponding MNE-Python functions::\n\n    original_data = mne.io.read_raw_fiff('original_data.fif', preload=False)\n    original_info = original_data.info\n    data_from_ft = mne.read_evoked_fieldtrip('evoked_data.mat', original_info)\n\nThe imported data can have less channels than the original data. Only the information for the present ones is extracted from the ``info`` dictionary.\n\nAs of version 0.17, importing FieldTrip data has been tested on a variety of systems with the following results:\n\n+----------+-------------------+-------------------+-------------------+\n| System   | Read Raw Data     | Read Epoched Data | Read Evoked Data  |\n+==========+===================+===================+===================+\n| BTI      | Works             | Untested          | Untested          |\n+----------+-------------------+-------------------+-------------------+\n| CNT      | Data imported as  | Data imported as  | Data imported as  |\n|          | microvolts.       | microvolts.       | microvolts.       |\n|          | Otherwise fine.   | Otherwise fine.   | Otherwise fine.   |\n+----------+-------------------+-------------------+-------------------+\n| CTF      | Works             | Works             | Works             |\n+----------+-------------------+-------------------+-------------------+\n| EGI      | Mostly Ok. Data   | Mostly Ok. Data   | Mostly Ok. Data   |\n|          | imported as       | imported as       | imported as       |\n|          | microvolts.       | microvolts.       | microvolts.       |\n|          | FieldTrip does    | FieldTrip does    | FieldTrip does    |\n|          | not apply         | not apply         | not apply         |\n|          | calibration.      | calibration.      | calibration.      |\n+----------+-------------------+-------------------+-------------------+\n| KIT      | Does not work.    | Does not work.    | Does not work.    |\n|          | Channel names are | Channel names are | Channel names are |\n|          | different in      | different in      | different in      |\n|          | MNE-Python and    | MNE-Python and    | MNE-Python and    |\n|          | FieldTrip.        | FieldTrip.        | FieldTrip.        |\n+----------+-------------------+-------------------+-------------------+\n| Neuromag | Works             | Works             | Works             |\n+----------+-------------------+-------------------+-------------------+\n| eximia   | Works             | Untested          | Untested          |\n+----------+-------------------+-------------------+-------------------+\n\n## Creating MNE data structures from arbitrary data (from memory)\n\nArbitrary (e.g., simulated or manually read in) raw data can be constructed\nfrom memory by making use of :class:`mne.io.RawArray`, :class:`mne.EpochsArray`\nor :class:`mne.EvokedArray` in combination with :func:`mne.create_info`.\n\nThis functionality is illustrated in `tut-creating-data-structures`.\nUsing 3rd party\nlibraries such as [NEO](https://github.com/NeuralEnsemble/python-neo)_ in\ncombination with these functions abundant electrophysiological file formats can\nbe easily loaded into MNE.\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
}