From 03ace5dc39c545e21163de9ad5d0052f56d4024e Mon Sep 17 00:00:00 2001 From: Robert Luke Date: Fri, 21 May 2021 12:54:07 +1000 Subject: [PATCH 1/2] drammock tutorial improvements --- tutorials/io/30_reading_fnirs_data.py | 30 ++++++++++++--------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index 7661ba454ac..4f7cfd0d689 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -6,23 +6,19 @@ Importing data from fNIRS devices ================================= -MNE includes various functions and utilities for reading fNIRS -data and optode locations. Regardless of the manufacturer and file format, -MNE stores both the measurement data and metadata in a consistent manner. - -fNIRS devices consist of light sources and light detectors, -often also termed emitter/transmitter and receiver respectively. -A channel is formed by source-detector pairs, and MNE represents the -channel location as the midpoint between source and detector. -MNE stores the location of the channels, sources, and -detectors. -There are a variety of fNIRS data types which can be represented in MNE. -For continuous wave fNIRS data this includes amplitude, optical density, -oxyhaemoglobin, and deoxyhemoglobin. -And for frequency domain fNIRS this additionally includes -AC amplitude and phase. -Different vendors save the data as different data types, and MNE will load -the data as the appropriate type. +fNIRS devices consist of two kinds of optodes: light sources (AKA "emitters" or +"transmitters") and light detectors (AKA "receivers"). Channels are defined as +source-detector pairs, and channel locations are defined as the midpoint +between source and detector. + +MNE-Python provides functions for reading fNIRS data and optode locations from +several file formats. Regardless of the device manufacturer or file format, +MNE-Python's fNIRS functions will internally store the measurement data and its +metadata in the same way (e.g., data values are always converted into SI +units). Supported measurement types include amplitude, optical density, +oxyhaemoglobin concentration, and deoxyhemoglobin concentration (for continuous +wave fNIRS), and additionally AC amplitude and phase (for +frequency domain fNIRS). .. warning:: MNE stores metadata internally with a specific structure, and internal functions expect specific naming conventions. From ae5800c2001f362d4768457e686026748e2466e5 Mon Sep 17 00:00:00 2001 From: Robert Luke Date: Sat, 22 May 2021 20:19:23 +1000 Subject: [PATCH 2/2] MNE -> MNE-Python --- tutorials/io/30_reading_fnirs_data.py | 63 ++++++++++++++------------- 1 file changed, 33 insertions(+), 30 deletions(-) diff --git a/tutorials/io/30_reading_fnirs_data.py b/tutorials/io/30_reading_fnirs_data.py index 4f7cfd0d689..fd9ac07462c 100644 --- a/tutorials/io/30_reading_fnirs_data.py +++ b/tutorials/io/30_reading_fnirs_data.py @@ -20,7 +20,7 @@ wave fNIRS), and additionally AC amplitude and phase (for frequency domain fNIRS). -.. warning:: MNE stores metadata internally with a specific structure, +.. warning:: MNE-Python stores metadata internally with a specific structure, and internal functions expect specific naming conventions. Manual modification of channel names and metadata is not recommended. @@ -40,13 +40,13 @@ is designed by the fNIRS community in an effort to facilitate sharing and analysis of fNIRS data. And is the official format of the Society for functional near-infrared spectroscopy (SfNIRS). -SNIRF is the preferred format for reading data in to MNE. +SNIRF is the preferred format for reading data in to MNE-Python. Data stored in the SNIRF format can be read in using :func:`mne.io.read_raw_snirf`. .. note:: The SNIRF format has provisions for many different types of fNIRS - recordings. MNE currently only supports reading continuous wave data - stored in the .snirf format. + recordings. MNE-Python currently only supports reading continuous + wave data stored in the .snirf format. *********************** @@ -62,9 +62,10 @@ NIRx produce continuous wave fNIRS devices. NIRx recordings can be read in using :func:`mne.io.read_raw_nirx`. The NIRx device stores data directly to a directory with multiple file types, -MNE extracts the appropriate information from each file. -MNE only supports NIRx files recorded with NIRStar version 15.0 and above. -MNE supports reading data from NIRScout and NIRSport 1 devices. +MNE-Python extracts the appropriate information from each file. +MNE-Python only supports NIRx files recorded with NIRStar +version 15.0 and above. +MNE-Python supports reading data from NIRScout and NIRSport 1 devices. .. _import-hitachi: @@ -90,7 +91,7 @@ BOXY recordings can be read in using :func:`mne.io.read_raw_boxy`. The BOXY software and ISS Imagent I and II devices are frequency domain systems that store data in a single ``.txt`` file containing what they call -(with MNE's name for that type of data in parens): +(with MNE-Python's name for that type of data in parens): - DC All light collected by the detector (``fnirs_cw_amplitude``) @@ -106,9 +107,10 @@ These raw data files can be saved by the acquisition devices as parsed or unparsed ``.txt`` files, which affects how the data in the file is organised. -MNE will read either file type and extract the raw DC, AC, and Phase data. -If triggers are sent using the ``digaux`` port of the recording hardware, MNE -will also read the ``digaux`` data and create annotations for any triggers. +MNE-Python will read either file type and extract the raw DC, AC, +and Phase data. If triggers are sent using the ``digaux`` port of the +recording hardware, MNE-Python will also read the ``digaux`` data and +create annotations for any triggers. ****************** @@ -124,10 +126,11 @@ provided by the Society for functional Near-Infrared Spectroscopy, and then load it using :func:`mne.io.read_raw_snirf`. -fNIRS measurements can have a non-standardised format that is not supported by -MNE and cannot be converted easily into SNIRF. This legacy data is often in CSV -or TSV format, we show here a way to load it even though it is not officially -supported by MNE due to the lack of standardisation of the file format (the +fNIRS measurements may be stored in a non-standardised format that is not +supported by MNE-Python and cannot be converted easily into SNIRF. +This legacy data is often in CSV or TSV format, +we show here a way to load it even though it is not officially supported by +MNE-Python due to the lack of standardisation of the file format (the naming and ordering of channels, the type and scaling of data, and specification of sensor positions varies between each vendor). You will likely have to adapt this depending on the system from which your CSV originated. @@ -140,10 +143,10 @@ # sphinx_gallery_thumbnail_number = 2 ############################################################################### -# First, we generate an example CSV file which will then be loaded in to MNE. -# This step would be skipped if you have actual data you wish to load. -# We simulate 16 channels with 100 samples of data and save this to a file -# called fnirs.csv. +# First, we generate an example CSV file which will then be loaded in to +# MNE-Python. This step would be skipped if you have actual data you wish to +# load. We simulate 16 channels with 100 samples of data and save this to a +# file called fnirs.csv. pd.DataFrame(np.random.normal(size=(16, 100))).to_csv("fnirs.csv") @@ -169,7 +172,7 @@ # Then, the metadata must be specified manually as the CSV file does not # contain information about channel names, types, sample rate etc. # -# .. warning:: In MNE the naming of channels MUST follow the structure of +# .. warning:: In MNE-Python the naming of channels MUST follow the structure # ``S#_D# type`` where # is replaced by the appropriate source and # detector numbers and type is either ``hbo``, ``hbr`` or the # wavelength. @@ -186,14 +189,14 @@ ############################################################################### -# Finally, the data can be converted in to an MNE data structure. +# Finally, the data can be converted in to an MNE-Python data structure. # The metadata above is used to create an :class:`mne.Info` data structure, -# and this is combined with the data to create an MNE :class:`~mne.io.Raw` -# object. For more details on the info structure see :ref:`tut-info-class`, and -# for additional details on how continuous data is stored in MNE see -# :ref:`tut-raw-class`. -# For a more extensive description of how to create MNE data structures from -# raw array data see :ref:`tut_creating_data_structures`. +# and this is combined with the data to create an MNE-Python +# :class:`~mne.io.Raw` object. For more details on the info structure +# see :ref:`tut-info-class`, and for additional details on how continuous data +# is stored in MNE-Python see :ref:`tut-raw-class`. +# For a more extensive description of how to create MNE-Python data structures +# from raw array data see :ref:`tut_creating_data_structures`. info = mne.create_info(ch_names=ch_names, ch_types=ch_types, sfreq=sfreq) raw = mne.io.RawArray(data, info, verbose=True) @@ -208,10 +211,10 @@ # etc), this is may be particularly important for fNIRS as information about # the optode locations is required to convert the optical density data in to an # estimate of the haemoglobin concentrations. -# MNE provides methods to load standard sensor configurations (montages) from -# some vendors, and this is demonstrated below. +# MNE-Python provides methods to load standard sensor configurations +# (montages) from some vendors, and this is demonstrated below. # Some handy tutorials for understanding sensor locations, coordinate systems, -# and how to store and view this information in MNE are: +# and how to store and view this information in MNE-Python are: # :ref:`tut-sensor-locations`, :ref:`plot_source_alignment`, and # :ref:`ex-eeg-on-scalp`. #