Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
tutorial:nirs_singlechannel [2018/07/12 14:48]
sophie [Define epochs of interest]
tutorial:nirs_singlechannel [2018/09/19 10:31] (current)
robert [Remove artifacts]
Line 5: Line 5:
 =====Introduction===== =====Introduction=====
  
-This tutorial demonstrates how to analyse a functional near-infrared spectroscopy (fNIRS) dataset ​that consists of a single channel.+This tutorial demonstrates how to analyse a functional near-infrared spectroscopy (fNIRS) dataset ​focussing on one single channel.
 The goal is to introduce the basic fNIRS analysis features of FieldTrip on Artinis NIRS data. The goal is to introduce the basic fNIRS analysis features of FieldTrip on Artinis NIRS data.
 You can find details on the Artinis recording and analysis software ​ [[http://​www.fieldtriptoolbox.org/​getting_started/​artinis|here]]. You can find details on the Artinis recording and analysis software ​ [[http://​www.fieldtriptoolbox.org/​getting_started/​artinis|here]].
Line 17: Line 17:
 =====Background===== =====Background=====
  
-FIXME +NIRS is an abbreviation of Near-InfraRed Spectroscopy,​ which is a method ​to measure ​the level of oxygenation in the blood flowing through the tissue on which the sensors are placed. It relies on the fact that oxygenated hemoglobin has a different light absorption spectrum than de-oxygenated hemoglobin and hence it has a different colour so you will. Most NIRS systems emit light of 2 wavelengths,​ typically around 700 and 850 nm, at every source optode and some systems use three wavelengths.  
-*this section should contain info about fNIRS as a method ​rather than about the content ​of the tutorial+ 
-*for example: What is special about fNIRShow is it different ​from other recording ​modalities? What signal is measuredalluding ​to why density has to be transformed ​to concentrationsWhat artifacts ​are commonly expected etc.+The detector optode ​is placed a few centimeters away from the source optode. Togetherthe source and detector optode make up a channel, but keep in mind that the system will always have 2 spatial locations for that one channel (most of us assume the recorded activity comes from a location mainly in the middle of the source and the detector) and 2 light wavelengths. The idea is that the light is scattered through the tissue and a small portion of the light will be detectable at the surface of the tissue by means of light detectors. The intensities of the light detected at the skin fluctuate systematically with changes in the oxygenated and de-oxygenated hemoglobin concentrations present in the tissue that lies between the source and detector optode. Due to the (more or less random) scatter, most light that arrives at the detector has only traveled through the surface of the tissue and only some small portion has traveled through an area a bit deeper below the surface. Typically, ​it is assumed that the light detected at the skin has traveled through a tissue volume that has a banana shape when depicted ​from a side-view. If the source and the detector are placed further apart, the light detected can potentially have traveled deeper through the tissue. Practically,​ there are limitations,​ because the portion of light that arrives at the detector falls off dramatically with increasing source-detector separations. When measuring changes in hemoglobin in the brain, the skull functions as an important barrier, as much light is absorbed by the bone. For that reason, scanning deeper in the brain is only feasible in young infants who still have a thin skull. 
 + 
 +The concentration of oxy- and deoxygenated hemoglobin can not be assessed in absolute terms, which means that all measures will reflect relative changes. Hence, like EEG and MEG, a baseline period is required. This can either be time-locked to the events that are provided to the participant (trial-by-trial baselines) which implies functional NIRS (fNIRS) or measured in a somewhat longer period prior or after the recording ​of interest (NIRS).  
 + 
 +The recorded and later processed fNIRS signal is comparable to fMRI in that sense that a hemodynamic response function (HRF) can be obtained, but with a higher temporal resolution. It is therefore, at least in theorypossible ​to measure the initial dip in the curve. In contrast ​to fMRI, the spatial resolution however is much poorer, and typically, we mainly record from the surface of the brain. As a result, plotting will often resemble EEG. The temporal resolution of EEG is of course much higher, but, the positive side of fNIRS is that the measured signal can only stem from the region in-between the source and detector, which need not be the case in EEG due to smearingAs such, fNIRS is a promising method for measuring brain activity in populations that cannot be tested in an fMRI scanner (think of young infants or people with cochlear implants who would otherwise display larger ​artifacts ​in regions that might be of critical interest), and/or for tasks that require more movements than the scanner would allow. Do keep in mind though that blood pressure can change with your task and thereby affects the measured signal as well.
 ===== The dataset used in this tutorial ===== ===== The dataset used in this tutorial =====
  
-In this dataset the motorcortex ​was probed using an Oxymon MK III system of Artinis Medical Systems. The system was placed over the motorcortex, and subsequently the subject was asked to perform finger tapping. ​The start of this motortask ​was reported by creating an event "A" and the end of the motortask was reported by creating an event "B". This motortask ​was repeated for a total of 12 times and all data was saved in an *.oxy3 file.+In this dataset the motor cortex ​was probed using an Oxymon MK III system of Artinis Medical Systems. The system was placed over the motor cortex, and subsequently the subject was asked to perform finger tapping. ​Alongside the recordings from the brain, we recorded when the participant ​was doing what in a so-called ​event channel. In that channel, an 'A' was recorded at the moment ​the participant started with the motor task, and a 'B' was recorded whenever the participant stopped tapping. This motor task was repeated for a total of 12 times and all data was saved, including the event channel, ​in an *.oxy3 file.
    
 The data used in this tutorial is available from our FTP server; please download [[ftp://​ftp.fieldtriptoolbox.org/​pub/​fieldtrip/​tutorial/​nirs_singlechannel/​motor_cortex.oxy3|motor_cortex.oxy3]] and [[ftp://​ftp.fieldtriptoolbox.org/​pub/​fieldtrip/​tutorial/​nirs_singlechannel/​optodetemplates.xml|optodetemplates.xml]]. For the XML file please right-click and save-as. The data used in this tutorial is available from our FTP server; please download [[ftp://​ftp.fieldtriptoolbox.org/​pub/​fieldtrip/​tutorial/​nirs_singlechannel/​motor_cortex.oxy3|motor_cortex.oxy3]] and [[ftp://​ftp.fieldtriptoolbox.org/​pub/​fieldtrip/​tutorial/​nirs_singlechannel/​optodetemplates.xml|optodetemplates.xml]]. For the XML file please right-click and save-as.
Line 83: Line 87:
   [data] = ft_preprocessing(cfg);​   [data] = ft_preprocessing(cfg);​
  
-When working with .oxy3-files,​ the optode template needs to be loaded. ​**[[reference:​ft_preprocessing|ft_preprocessing]]** opens a user interface dialogue to specify ​the template ​file. By default this file is located in C:\Program Files (x86)\Artinis Medical Systems BV\Oxysoft 3.0.103. The file to select is “optodetemplates.xml”. However, given that Fieldtrip ​often will search for this function, it is best to copy this function to the same folder as where your Matlab analysis script and/or your fNIRS are data stored.+When working with .oxy3-files,​ the optode template ​containing the layout of the optodes ​needs to be loaded. ​If MATLAB cannot find the template file on your path, it will pop up graphical ​user interface dialogue ​asking you to locate ​the xml file. By default this file is located in C:\Program Files (x86)\Artinis Medical Systems BV\Oxysoft 3.0.103. The file to select is “optodetemplates.xml”. However, given that FieldTrip ​often will search for this function, it is best to copy this function to the same folder as where your Matlab analysis script and/or your fNIRS are data stored. For information on how to choose the optimal template for your experiments,​ please see https://​www.artinis.com/​blogpost-all/​2017/​6/​27/​how-do-i-choose-the-correct-fibers-and-template-for-my-oxymon.
  
 FieldTrip is finished when you see something like this on the screen: FieldTrip is finished when you see something like this on the screen:
Line 106: Line 110:
            cfg: [1×1 struct]            cfg: [1×1 struct]
                        
-Let us go through these one-by-one. The field '​hdr'​ contain all top-level information about your data, like for example the original sample rate, the number of channels etc. So all information that was potentially available at the  time you read in the dataset. The field '​label'​ lists the name of all channels that you decided to read in. Note that you have told **[[reference:​ft_preprocessing|ft_preprocessing]]** to just read-in a subset ​of channelsHerehowever, we decided to read in both channels, and as each channel consists of measurements ​of 2 wavelengths, ​we end up with four of them. You also read in a set of ADC-channels,​ these will be ignored for now (these contain the triggers of the oxymon file, hence, this is NIRS acquisition hardware specific). The next field is called '​time'​ and represents the time axis of the dataset. The field '​trial'​ contains the data of all your channels. It is called '​trial'​ because usually, data is separated into different trials. To start off, we however have now read in all available data. The field '​fsample'​ describes the current sample rate of the data in the '​trial'​-field. The field '​sampleinfo'​ describes the sample numbers of each trial with respect to the original measurement. The field '​opto'​ contains all high-level information about the composition of the channels and optodes, such as what wavelengths were used, the position of the optodes, what optodes formed which channels, etc. Finally, the field '​cfg'​ is the same cfg that we have just used, extended by some default values. This way, we can always trace back what has actually happened to our data. But more about that later.+Let us go through these one-by-one. The field '​hdr'​ contain all top-level information about your data, like for example the original sample rate, the number of channels etc. So all information that was potentially available at the  time you read in the dataset. The field '​label'​ lists the name of all channels that you decided to read in. Note that you have told **[[reference:​ft_preprocessing|ft_preprocessing]]** to just read-in, by default, all channels as you haven'​t specified ​a subset. ​As you can seethere are 48 labels, and as the measurement consisted ​of 2 wavelengths ​per channelthis represents 24 channels. You also read in a set of ADC-channels,​ these will be ignored for now (these contain the triggers of the oxymon file, hence, this is NIRS acquisition hardware specific). The next field is called '​time'​ and represents the time axis of the dataset. The field '​trial'​ contains the data of all your channels. It is called '​trial'​ because usually, data is separated into different trials. To start off, we however have now read in all available data. The field '​fsample'​ describes the current sample rate of the data in the '​trial'​-field. The field '​sampleinfo'​ describes the sample numbers of each trial with respect to the original measurement. The field '​opto'​ contains all high-level information about the composition of the channels and optodes, such as what wavelengths were used, the position of the optodes, what optodes formed which channels, etc. Finally, the field '​cfg'​ is the same cfg that we have just used, extended by some default values. This way, we can always trace back what has actually happened to our data. But more about that later.
  
-Let us dive deeper into our data for now. For having a quick look at our data, we can use the function **[[reference:​ft_databrowser|ft_databrowser]]** . The databrowser is much more than a simple 'data browser',​ but we will utilize this functionality for our purpose at the moment. Of course, we could have a look at how to call the databrowser (help **[[reference:​ft_databrowser|ft_databrowser]]**),​ but a good guess is always to use fieldtrip ​functions as ft_functionname(cfg,​ data). We can keep the cfg empty to start with, and then see if this works:+Let us dive deeper into our data for now. For having a quick look at our data, we can use the function **[[reference:​ft_databrowser|ft_databrowser]]** . The databrowser is much more than a simple 'data browser',​ but we will utilize this functionality for our purpose at the moment. Of course, we could have a look at how to call the databrowser (help **[[reference:​ft_databrowser|ft_databrowser]]**),​ but a good guess is always to use FieldTrip ​functions as ft_functionname(cfg,​ data). We can keep the cfg empty to start with, and then see if this works. We add 'ylim = '​maxmin''​ to the configuration to adjust the y-axis such that the lowest values in the graph are determining the lowest point on the y-axis, and the largest values in the graph determine the highest point on the y-axis.
  
   cfg = [];   cfg = [];
 +  cfg.ylim = '​maxmin' ​
   ft_databrowser(cfg,​ data);   ft_databrowser(cfg,​ data);
  
Line 117: Line 122:
 **//Figure 2; Databrowser read-in.//​** **//Figure 2; Databrowser read-in.//​**
  
-=== Exercise 1 === 
- 
-<note exercise>​ 
-Take a moment to familiarize yourself with the user-interface. Change the horizontal and vertical scales until you can see the heartbeat signal in all of the channels. Tip: A time slice of something between 10 to 20 seconds is optimal. 
-</​note>​ 
  
 Using **[[reference:​ft_databrowser|ft_databrowser]]**,​ you can also cut out pieces of your data that you do not need. For instance, if you have started the recording while putting the optodes in place, you will probably have a chunk of data at the start of the recording that you don’t need and which contains very high (not brain-related) values that rapidly fluctuate. It is useful to cut these pieces out (trimming). In the tutorial dataset, this is not needed, but see here for an [[tutorial:​visual_artifact_rejection#​use_ft_databrowser_to_mark_the_artifacts_manually|illustration of how trimming works within ft_databrowser]]. Using **[[reference:​ft_databrowser|ft_databrowser]]**,​ you can also cut out pieces of your data that you do not need. For instance, if you have started the recording while putting the optodes in place, you will probably have a chunk of data at the start of the recording that you don’t need and which contains very high (not brain-related) values that rapidly fluctuate. It is useful to cut these pieces out (trimming). In the tutorial dataset, this is not needed, but see here for an [[tutorial:​visual_artifact_rejection#​use_ft_databrowser_to_mark_the_artifacts_manually|illustration of how trimming works within ft_databrowser]].
Line 128: Line 128:
 <​code>​ <​code>​
 cfg = []; cfg = [];
 +cfg.ylim = '​maxmin' ​
 cfg.channel = {'​Rx4b-Tx5 [860nm]',​ '​Rx4b-Tx5 [764nm]'​};​ cfg.channel = {'​Rx4b-Tx5 [860nm]',​ '​Rx4b-Tx5 [764nm]'​};​
 ft_databrowser(cfg,​ data); ft_databrowser(cfg,​ data);
 </​code>​ </​code>​
  
-{{tutorial:nirs_tut1_fig2_databrowser.png?400}}+{{tutorial:nirs_tut1_fig3_databrowser_one_chan.png?400}}
  
 **//Figure 3; Databrowser with one channel selected.//​** **//Figure 3; Databrowser with one channel selected.//​**
  
-<​note ​note+=== Exercise 1 === 
-Picking up the heartbeat in the NIRS measurement is a sign of good data quality, if the heartbeat cannot be detected in the data, contact with the skin must have been poor.+ 
 +<​note ​exercise
 +Take a moment to familiarize yourself with the user-interface. Change the horizontal and vertical scales until you can see the heartbeat signal in the selected channels. Tip: A time slice of something between 10 to 20 seconds is optimal. ​Picking up the heartbeat in the NIRS measurement is a sign of good data quality, if the heartbeat cannot be detected in the data, contact with the skin must have been poor.
 </​note>​ </​note>​
  
-FIXME  +
-* For the two channel databrowser,​ show picture with optimal scaling, so that heartbeat is visible+
  
 ==== Remove artifacts ==== ==== Remove artifacts ====
Line 147: Line 149:
 There are several ways to remove aspects of the data that are not of interest. That is, fNIRS data not only represents changes in oxyhemoglobin and deoxyhemoglobin concentrations,​ but contains, amongst others, also other physiological signals, random noise and variations stemming from the measurement environment. One prominent issue is motion artifacts, which are produced by temporary changes in the contact between optode and skin, often caused by movements of the head. Typically, one finds these motion artifacts in all channels simultaneously,​ but it could also be that just one channel or a few channels were affected, for instance if the participant moves the mouth. Short, unexpected peaks in the data are considered to stem from motion. You can detect and remove these artifacts for instance through **[[reference:​ft_artifact_zvalue|ft_artifact_zvalue]]**:​ There are several ways to remove aspects of the data that are not of interest. That is, fNIRS data not only represents changes in oxyhemoglobin and deoxyhemoglobin concentrations,​ but contains, amongst others, also other physiological signals, random noise and variations stemming from the measurement environment. One prominent issue is motion artifacts, which are produced by temporary changes in the contact between optode and skin, often caused by movements of the head. Typically, one finds these motion artifacts in all channels simultaneously,​ but it could also be that just one channel or a few channels were affected, for instance if the participant moves the mouth. Short, unexpected peaks in the data are considered to stem from motion. You can detect and remove these artifacts for instance through **[[reference:​ft_artifact_zvalue|ft_artifact_zvalue]]**:​
  
 +You can specify a z-value cut-off like this:
 +
 +  cfg = [];
   cfg.channel = {'​Rx4b-Tx5 [860nm]',​ '​Rx4b-Tx5 [764nm]'​};​   cfg.channel = {'​Rx4b-Tx5 [860nm]',​ '​Rx4b-Tx5 [764nm]'​};​
   cfg.artfctdef.zvalue.channel = {'​Rx4b-Tx5 [860nm]',​ '​Rx4b-Tx5 [764nm]'​};​   cfg.artfctdef.zvalue.channel = {'​Rx4b-Tx5 [860nm]',​ '​Rx4b-Tx5 [764nm]'​};​
- 
-You can specify a z-value cut-off below: 
- 
   cfg.artfctdef.zvalue.cutoff = 3.5;   cfg.artfctdef.zvalue.cutoff = 3.5;
   [cfg, artifact] = ft_artifact_zvalue(cfg,​ data);   [cfg, artifact] = ft_artifact_zvalue(cfg,​ data);
  
-You will see that Fieldtrip removed ​8 artifacts through this procedure.+You will see that FieldTrip identified ​8 artifacts through this procedure. ​These are not yet removed, you would call **[[:​reference:​ft_rejectartifact]]**. 
 === Exercise 2 === === Exercise 2 ===
 <note exercise> ​ <note exercise> ​
-Play around with the cut-off z-value ​and check how the data looks prior to artifact ​removal and after using **[[reference:​ft_databrowser|ft_databrowser]]**.+Play around with the cut-off z-value. You can do this by running ​the artifact ​rejection in interactive mode by adding cfg.artfctdef.zvalue.interactive = '​yes';​ before you run [cfg, artifact= ft_artifact_zvalue(cfg,​ data);. 
 +In the interactive mode, you can change the threshold to see which parts of the data would be rejected, the rejected bits are marked in red.
  
 What is the optimal threshold to get rid off short lived peaks? What is the optimal threshold to get rid off short lived peaks?
Line 300: Line 304:
  
 Here is the other documentation on this wiki that relates to fNIRS: Here is the other documentation on this wiki that relates to fNIRS:
-{{topic>​nirs ​+tutorial ​&​list}} +{{topic>​nirs &​list}} 
-{{topic>​nirs +faq &​list}} +
-{{topic>​nirs +example &list}}+