= Tutorial: Import and visualize functional NIRS data =
||<40%> || ~+'''This tutorial is under construction'''+~ ||
''Authors: Thomas Vincent''
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.
== Download ==
The dataset used in this tutorial is available online.
* Go to the [[http://neuroimage.usc.edu/bst/download.php|Download]] 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 run of 12''' '''minutes acquired with a sampling rate of 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 "TutorialNIRSTapping":
* Got to File -> New Protocol
* Use the following setting :
* '''Default anatomy''': Use individual anatomy.
* '''Default channel file''': Use one channel file per acquisition run (MEG).
In term of sensor configuration, NIRS is similar to EEG and the placement of optodes may change from subject to the other. Also, the channel definition will change during data processing, that's why you should always use one channel file per acquisition even if the optode placement does not change.
Create a subject called "Subject01" (Go to File -> New subject), with the default options.
== Import anatomy ==
=== Import MRI and meshes ===
Make sure you are in the anatomy view of the protocol. Right-click on "Subject01 -> Import anatomy folder". Select anatomy folder from the nirs_sample data folder. Reply "yes" when asked to apply the transformation. Leave the number of vertices for the head mesh to the default value. 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]]). Note that the PC, AC and IH points are already defined.
{{attachment:NIRSTORM_tut_nirs_tapping_MRI_edit.gif||height="400"}}
Here are the MRI coordinates ([x y z] in mm) of the fiducials used to produce the above figure:
* NAS: 95 213 114
* LPA: 31 126 88
* RPA: 164 128 89
* AC: 96 137 132
* PC: 97 112 132
* IH: 95 103 180
To define NAS, LPA and RPA, you can right click on the anatomy view, select "Edit fiducial points" and enter the coordinates above.
When finished, click on "Save".
The head and white segmentations provided in the NIRS sample data were computed with Brainvisa and should automatically be imported and processed. 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_tut_nirs_tapping_new_MRI_meshes.gif||height="300"}}
== Import NIRS functional data ==
The functional data used in this tutorial was produced by the Brainsight acquisition software and is available in the data subfolder of the nirs sample folder. It contains the following files:
* '''fiducials.txt''': the coordinates of the fudicials (nasion, left ear, right ear).<
>The positions of the Nasion, LPA and RPA 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 results.
* '''optodes.txt''': the coordinates of the optodes (sources and detectors), in the same referential as in fiducials.txt. 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'''.<
>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 -> Review raw file"
* Select file type "NIRS: Brainsight (.nirs)"
* Load the file "S01_Block_FO_LH_Run01.nirs" in the NIRS sample folder.<
>Note: the importation process assumes that the files optodes.txt and fiducials.txt are in the same folder<
>as the .nirs data file.
== 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.
* 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 (here Brainsight). The position of these points are saved in the NIRS datasets (see fiducials.txt).
* When the NIRS recordings are loaded into the Brainstorm database, they are aligned on the MRI using these fiducial points: the NAS/LPA/RPA points digitized with Brainsight are matched with the ones we placed in the MRI Viewer.
To review this registration, right-click on "NIRS-BRS sensors (104) -> Display sensors -> NIRS" To show the fiducials, which were stored as additional digitized head points: right-click on "NIRS-BRS sensors (104) -> Display sensors -> NIRS labels". To also show the fiducials, right-click on the plot window and select "Figure -> View head points"
{{attachment:NIRSTORM_tut_nirs_tapping_display_sensors_fiducials.png||height="300"}}
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_tut_nirs_tapping_brainsight_head_mesh_fiducials_1.gif||height="280"}} {{attachment:NIRSTORM_tut_nirs_tapping_brainsight_head_mesh_fiducials_2.gif||height="280"}} {{attachment:NIRSTORM_tut_nirs_tapping_brainsight_head_mesh_fiducials_3.gif||height="280"}}
== Review Channel information ==
The resulting data organization should be:
{{attachment:NIRSTORM_tut_nirs_tapping_func_organization.png}}
This indicates that the data comes from the Brainsight system (BRS) and comprises 104 channels (96 NIRS channels + 8 auxiliary signals).
To review the content of channels, right-click on "BS channels -> Edit channel file".
{{attachment:NIRSTORM_tut_nirs_tapping_channel_table.png||height="350"}}
* Channels whose name is in the form SXDYWLZZZ represent NIRS measurements. For a given NIRS channel, its name is composed of the pair Source X, Detector Y and the wavelength value ZZZ. Column Loc(1) contains the coordinates of the source, Loc(2) the coordinates of the associated detector.
* Each NIRS channel is here assigned to the group "WL690" or "WL830" to specified its wavelength.
* Channels AUXY of type NIRS_AUX are data read from the nirs.aux structure of the input NIRS data file. It usually contains acquisition triggers (AUX1 here) and stimulation events (AUX2 here).
== Visualize NIRS signals ==
Select "Subject01/S01_Block_FO_LH_Run01/Link to raw file -> NIRS -> Display time series" It will open a new figure with superimposed channels
{{attachment:NIRSTORM_tut_nirs_tapping_time_series_stacked.png||height="400"}}
Which can also be viewed in butterfly mode
{{attachment:NIRSTORM_tut_nirs_tapping_time_series_butterfly.png||height="400"}}
To view the auxiliary data, select "Subject01/S01_Block_FO_LH_Run01/Link to raw file -> NIRS_AUX -> Display time series"
{{attachment:NIRSTORM_tut_nirs_tapping_time_series_AUX_stacked.gif||height="300"}}
We refer to the tutorial for navigating in these views [[Tutorials/ReviewRaw|"Review continuous recordings"]]
=== Montage selection ===
/!\ TODO add dynamic montages
/!\ Add screenshot
== Extract stimulation events ==
During the experiment, the stimulation paradigm was run under matlab and sent triggers through the parallel port to the acquisition device. These stimulation events are then stored as a box signal in channel AUX2: values above a certain threshold indicate a stimulation block.
To transform this signal into Brainstorm events, drag and drop the NIRS data "S01_Block_FO_LH_Run01" in the Brainstorm process window. Click on "Run" and select Process "Events -> Read from channel".
{{attachment:NIRSTORM_tut_nirs_tapping_detect_events.gif||width="300"}}
Use the following parameters:
* set "Event channels" to "NIRS_AUX"
* select "TTL: detect peaks ...". This is the method to extract events from the AUX signal.
Run the process.
Then right-click on "Link to raw file" under "S01_Block_FO_LH_Run01" then "NIRS -> Display time series". There should be an event group called "AUX1". Rename it to "MOTOR" using "Events -> Rename Group".
{{attachment:NIRSTORM_tut_nirs_tapping_nirs_time_series_motor_events.gif||height="300"}}
The "MOTOR" event group has 10 events which are shown in green on the top of the plot.
== Bad channel tagging ==
NIRS measurement are heterogeneous (long distance measurements, movements, occlusion by hair) and the signal in several channels might not be properly analysed. A first pre-processing step hence consists in removing those channels.
The following criterions may be applied to reject channels:
* some values are negative
* signal is flat (variance close to 0)
* signal has too many flat segments
Drag and drop the NIRS data "S01_Block_FO_LH_Run01" in the Brainstorm process window. Click on "Run" and select Process "NIRSTORM -> Tag bad channels".
{{attachment:NIRSTORM_tut2_nirs_remove_bad_channels.png||width="300"}}
* Remove negative channels: tag a channel as bad if it has a least one negative value. This is important for the quantification of delta [Hb] which cannot be applied if there are negative values.
* Maximum proportion of saturating point: a saturating point has a value equals to the maximum of the signal. The default is at 1: remove only flat signals. If one wants to also keep flat channels, set the value to at least 1.01.
This process is performed "in place": the channel flags of the given data are modified. To view the result, right-click on "S01_Block_FO_LH_Run01 > Link to raw file" then "Good/Bad Channels > View all bad channels" or "Edit good/bad channels".
== Compute [Hb] variations - Modified Beer-Lambert Law ==
This process computes variations of concentration of oxy-hemoglobin (HbO), deoxy-hemoglobin (HbR) and total hemoglobin (HbT) from the measured light intensity time courses at different wavelengths.
Note that the channel definition will differ from the raw data. Previously there was one channel per wavelength, now there will be one channel per Hb type (HbO, HbR or HbT). The total number of channels may change.
For a given pair, the formula used is:
. delta_hb = d^-1^ * eps^-1^ * -log(I / I_ref) / ppf
where:
* '''delta_hb''' is the 3 x nb_samples matrix of delta [Hb],
* '''d''' is the distance between the pair optodes,
* '''eps''' is the 3 x nb_wavelengths matrix of Hb extinction coefficients,
* '''I''' is the input light intensity,
* '''I_ref''' is a reference light intensity,
* '''ppf''' is the partial light path correction factor.
{{attachment:NIRSTORM_tut2_MBLL.png||width="300"}}
Process parameters:
* Age: age of the subject, used to correct for partial light path length
* Baseline method: mean or median. Method to compute the reference intensity ('''I_ref''') against which to compute variations.
* Light path length correction: flag to actually correct for light scattering. If unchecked, then '''ppf'''=1
* Register Hb channel montages: register one montage per paired channel group. This will create a list of montage to help visualizing the different Hb time-courses together. /!\ make ref to visu
This process creates a new condition, here "Hb_S01_Block_FO_LH_Run01", because the montage is redefined.
Double-click on "Hb_S01_Block_FO_LH_Run01 |- [Hb]" to browse the delta [Hb] time-series.
{{attachment:NIRSTORM_tut2_view_hb.png||width="600"}}
As shown on the left part, all recorded optode pairs are available as montages to enable the display of overlapping HbO, HbR and HbT.
== Linear detrend ==
This filter process removes any linear trend in the signal.
Clear the process window and drag and drop the item named "[Hb]" into it. Select "Run -> NIRSTORM -> Linear Detrend"
{{attachment:NIRSTORM_tut2_detrend_parameters.png||width="300"}}
Parameters:
* Sensor types: channel types on which to apply detrending
* Overwrite input files: if unchecked, then create a new file with the detrended signal.
This process creates an item called "[Hb] | detrended"
== Infinite Impulse Response filtering ==
So far, the signal still contains a lot of physiological components of non-interest: heart beats, breathing and Mayer waves. As the evoked signal of interest should be distinct from those components in terms of frequency bands, we can get rid of them by filtering.
{{attachment:NIRSTORM_tut2_iir_filter_parameters.png||width="300"}}
Parameters:
* Filter type: lowpass, highpass, bandpass or bandstop.
* Low cut-off (Hz.): lower bound cut-off frequency for highpass, bandpass and bandstop filters.
* High cut-off (Hz.): higher bound cut-off frequency for lowpass, bandpass and bandstop filters.
* Sensor types: channel types on which to apply filtering
* Overwrite input files: if unchecked, then create a new file with the detrended signal.
This process creates an item called "[Hb] | detrended | IIR filtered"
== Window averaging ==
the goal is to get the response elicited by the motor paradigm. For this, we perform window-averaging time-locked on each motor onset while correcting for baseline differences across trials.
The first step is to split the data into chunks corresponding to the window over which we want to average. The average window is wider than the stimulation events: we'd like to see the return to baseline / undershoot after stimulation. If we directly use the ''extended'' MOTOR events to split data, the window will be constrain to the event durations.
To avoid this, define new "simple" events from the existing ones: Double-click on "[Hb] | detrended | IIR filtered", then in the right panel select the MOTOR event type, click on "Events -> convert to simple events" and select "start". Then click on "File -> Save modifications". This defines the temporal origin point of the peri-stimulus averaging window.
Right-click on "[Hb] | detrended | IIR filtered -> Import in database"
{{attachment:NIRSTORM_tut2_import_data_chunks.png||width="550"}}
Ensure that "Use events" is checked and that the MOTOR events are selected. The epoch time should be: -5000 to 45000 ms. This means that there will be 5 seconds prior to the stimulation event to check if the signal is steady. There will also be 15 seconds after the stimulation to check the return to baseline / undershoot. In the "Pre-processing" panel, check "Remove DC offset" and use a Time range of -5000 to -100 ms. This will set a reference window prior over which to remove chunk offsets. All signals will be zero-centered according to this window. Finally, ensure that the option "Create a separate folder for each event type" is checked".
After clicking on "import", we end up with 10 "MOTOR" data chuncks.
The last step is to actually compute the average of these chunks. Clear the process panel then drag and drop the item "MOTOR (10 files)" into it. Click on "run" and select the process "Average -> Average files".
{{attachment:NIRSTORM_tut2_average_files_process.png||width="300"}}
Use '''Group files''': Everything and '''Function''': Arithmetic average + Standard deviation.
To see the results, double click on the created item "AvgStd: MOTOR (10)". You can again browse by measurement pair by using the different montages in the record panel.
{{attachment:NIRSTORM_tut2_averaged_response.png||width="300"}}