= Tutorial: Import and visualize functional NIRS data =
||<40%> || <!> ~+'''This tutorial is under construction'''+~ <!> ||


''Authors: Thomas Vincent, Zhengchen Cai''

The current tutorial assumes that the tutorials 1 to 6 have been performed. Even if they focus on MEG data, they introduce Brainstorm features that are required for this tutorial.

List of prerequisites:

 * [[http://neuroimage.usc.edu/brainstorm/Tutorials/CreateProtocol|Create a new protocol]]
 * [[http://neuroimage.usc.edu/brainstorm/Tutorials/ImportAnatomy|Import the subject anatomy]]
 * [[http://neuroimage.usc.edu/brainstorm/Tutorials/ExploreAnatomy|Display the anatomy]]
 * [[http://neuroimage.usc.edu/brainstorm/Tutorials/ChannelFile|Channel file / MEG-MRI coregistration]]
 * [[http://neuroimage.usc.edu/brainstorm/Tutorials/ReviewRaw|Review continuous recordings]]

== Download ==
The dataset used in this tutorial is available online.

 * Go to the Download /!\ '''link''' page of this website, and download the file: nirs_sample.zip
 * Unzip it in a folder that is not in any of the Brainstorm folders

== Presentation of the experiment ==
 * Finger tapping task: 10 stimulation blocks of 30 seconds each, with rest periods of 30 seconds
 * One subject, one NIRS acquisition run of 12''' '''minutes at 10Hz
 * 4 sources and 12 detectors (+ 4 proximity channels) placed above the right motor region
 * Two wavelengths: 690nm and 830nm
 * MRI anatomy 3T from /!\ ''' scanner type '''

== Create the data structure ==
Create a protocol called "TutorialNIRSTORM":

 * Got to File -> New Protocol
 * Use the following setting :
  * '''Default anatomy''': Use individual anatomy.
  * '''Default channel file''': Use one channel file per subject (EEG).

In term of sensor configuration, NIRS is very similar to EEG and the placement of optodes may change from subject to the other.

(!) Should we add (EEG '''or NIRS''') in the interface?

Create a subject called "Subject01" (Go to File -> New subject), with the default options

== Import anatomy ==
=== Import MRI ===
Make sure you are in the anatomy view of the protocol.

Right-click on "Subject01 -> Import MRI". Select T1_MRI.nii from the NIRS_sample data folder.

This will open the MRI review panel where you have to set the fudicial points (See [[http://neuroimage.usc.edu/brainstorm/Tutorials/ImportAnatomy|Import the subject anatomy]]).

{{attachment:NIRSTORM_tut1_MRI_edit.gif||height="335",width="355"}}

=== Import Meshes ===
The head and white segmentations provided in the NIRS sample data were computed with Brainvisa.

Right-click on "Subject01 -> Import surfaces". From the NIRS sample data folder, select files: head_10000V.mesh, hemi_8003V.mesh and white_8003V.mesh.

You can check the registration between the MRI and the loaded meshes by right-clicking on each mesh element and going to "MRI registration -> Check MRI/Surface registration".

{{attachment:NIRSTORM_tut1_new_MRI_meshes.gif||height="335",width="355"}}

== Import NIRS functional data ==
The functional data used in this tutorial was produced by the Brainsight acquisition software and is available in the NIRS sample folder in S01_Block_FO_LH_Run01.bs. This folder contains the following files:

 * '''fiducials.txt''': the coordinates of the fudicials (nasion, left ear, right ear).<<BR>>These positions should have been digitized at the same location as the fiducials previously marked on the anatomical MRI. These points will be used by Brainstorm for the registration, hence the consistency between the digitized and marked fiducials is essential for good
 * '''optodes.txt''': the coordinates of the optodes (sources and detectors), in the same referential as for the fiducials. Note: the actual referential is not relevant here, as the registration will be performed by Brainstorm afterwards.
 * '''S01_Block_FO_LH_Run01.nirs''': the NIRS data in a HOMer-based format /!\ '''document format'''.<<BR>>Note: The fields ''SrcPos'' and ''DetPos'' will be overwritten to match the given coordinates in "optodes.txt"

To import this data set in Brainstorm:

 * Go to the "functional data" view of the protocol.
 * Right-click on "Subject01 -> Import MEG/EEG'''/NIRS'''"
  * Select file type "NIRS: BS (.bs)"

  * Load the folder "S01_Block_FO_LH_Run01.bs" in the NIRS sample folder.
 * Refine registration now? '''YES'''<<BR>>This operation is detailed in the next section

== Registration ==
In the same way as in the tutorial "[[http://neuroimage.usc.edu/brainstorm/Tutorials/ChannelFile|Channel file / MEG-MRI coregistration]]", the registration between the MRI and the NIRS is first  based on three reference points Nasion, Left and Right ears. It can then be refined with the either the full head shape of the subject or with manual adjustment.

=== Step 1: Fiducials ===
 * The initial registration is based on the three fiducial point that define the Subject Coordinate System (SCS): nasion, left ear, right ear. You have marked these three points in the MRI viewer in the [[http://neuroimage.usc.edu/brainstorm/Tutorials/NIRSDataImport#Import_MRI|previous part]].
 * These same three points have also been marked before the acquisition of the NIRS recordings. The person who recorded this subject digitized their positions with a tracking device (such as a Polhemus FastTrak or Patriot). The position of these points are saved in the NIRS datasets (see NIRS_sample/fiducials.txt). * When we bring the NIRS recordings into the Brainstorm database, we align them on the MRI using these fiducial points: we match the NAS/LPA/RPA points digitized with Brainsight with the ones we placed in the MRI Viewer.
 * This registration method gives approximate results. It can be good enough in some cases, but not always because of the imprecision of the measures. The tracking system is not always very precise, the points are not always easy to identify on the MRI slides, and the very definition of these points does not offer a millimeter precision. All this combined, it is easy to end with an registration error of 1cm or more.
 * The quality of the source analysis we will perform later is highly dependent on the quality of the registration between the sensors and the anatomy. If we start with a 1cm error, this error will be propagated everywhere in the analysis.

=== Step 2: Head shape ===
/!\ We don't have digitized head points for this data set. We should skip this

=== Step 3: manual adjustment ===
If the registration you get with automatic alignment techniques described previously, or if there was an issue when you digitized the position of the fiducials or the head shape, you may have to realign manually the optodes on the head. Right-click on the channel file > MRI Registration:

 * '''Check''': Show all the possible information that may help to verify the registration.
 * '''Edit''': Opens a window where you can move manually the MEG helmet relative to the head.<<BR>>  Read the tooltips of the buttons in the toolbar to see what is available, select an operation and then right-click+move up/down to apply it. From a scientific point of view this is not exactly a rigorous operation, but sometimes it is much better than using wrong default positions.<<BR>> IMPORTANT: this refinement can only be used to better align the headshape with the digitized points - it cannot be used to correct for a subject who is poorly positioned in the helmet (i.e. you cannot move the helmet closer to the subjects head if they were not seated that way to begin with!)

/!\ '''Add screenshots'''

As reference, the following figures show the position of fiducials [blue] (inion and nose tip are extra positions), sources [orange] and detectors [green] as they were digitized by Brainsight:

{{attachment:NIRSTORM_tut1_brainsight_head_mesh_fiducials_1.gif||height="280"}}  {{attachment:NIRSTORM_tut1_brainsight_head_mesh_fiducials_2.gif||height="280"}}  {{attachment:NIRSTORM_tut1_brainsight_head_mesh_fiducials_3.gif||height="280"}}

== Review Channel information ==
The resulting data organization should be:

{{attachment:func_data_loading_result.gif}}

This indicates that the data comes from the Brainsight system (BS) and comprises 97 channels.

To review the content of channels, right-click on "BS channels -> Edit channel file".
|| ||'''Name''' ||'''Type''' ||'''Group''' ||'''Comment''' ||'''Loc(1)''' ||'''Loc(2)''' ||'''Loc(3)''' ||... ||
||1 ||TAPPING ||Stim || || ||N/A ||N/A ||N/A || ||
||2 ||WLs ||NIRS_WL_DEF || || ||N/A ||N/A ||N/A || ||
||3 ||S1D1WL1 ||NIRS ||NIRS_WL1 || ||coords S1 ||coords D1 ||coords middle [S1-D1] || ||
||4 ||S1D1WL2 ||NIRS ||NIRS_WL2 || ||coords S1 ||coords D1 ||coords middle [S1-D1] || ||
||5 ||S1D2WL1 ||NIRS ||NIRS_WL1 || ||coords S1 ||coords D2 ||coords middle [S1-D2] || ||
||6 ||S1D2WL2 ||NIRS ||NIRS_WL2 || ||coords S1 ||coords D2 ||coords middle [S1-D2] || ||
||7 ||S1P1WL1 ||NIRS ||NIRS_WL1 ||(NIRS_PROX) ||coords S1 ||coords D2 ||coords middle [S1-D2] || ||
||8 ||S1P1WL2 ||NIRS ||NIRS_WL2 ||(NIRS_PROX) ||coords S1 ||coords D2 ||coords middle [S1-D2] || ||




 * The channel named "TAPPING" encodes the stimulation paradigm
 * The channel named "WLs" defines the set of wavelengths
 * Other channels contain the NIRS time-series measurements. For a given NIRS channel, its name is composed of the pair Source / Detector and the wavelength index.  Column Loc(1) contains the coordinates of the source,  Loc(2) the coordinates of the associated detector and  Loc(3) the coordinates of the middle point between the source and the detector.
 * Each NIRS channel is assigned to either "NIRS_WL1" and "NIRS_WL2" so specified its wavelength. "NIRS_WL1" will correspond to the 1st value of the channel "WLs", and "NIRS_WL2" to the 2nd value.
 * The comment "NIRS_PROX" indicates that the channel is a close-source measurement.

== Visualize NIRS signals ==
Right-clicking on the raw file shows the list of channel types:

 * NIRS: 96 NIRS channels (2 wavelenghts x 48 Source-Detector pairs)
 * STIM: 1 sequence stimulation blocks
 * NIRS_WL_DEF: 1 sequence of two values defining the wavelengths (690nm and 830nm)
 * NIRS_PROXY: 4 NIRS close-distance channels

Select -> NIRS -> Display time series

It will open a new figure with superimposed channels

/!\ '''add screenshot'''

Which can also be viewed in butterfly mode

/!\ '''add screenshot'''

We refer to the tutorial for navigating in these views [[Tutorials/ReviewRaw|"Review continuous recordings"]]

=== Montage selection ===
Within the NIRS channel type, the following channel groups are available:

 * '''All channels: '''gathers all NIRS channels
 * '''WL1''': contains only the channels corresponding to the 1st wavelength (690 nm here)
 * '''WL2''': contains only the channels corresponding to the 2nd wavelength (890 nm here)

/!\ Add screenshot