WIP: Added tutorial for fNIRS data by mcaffini · Pull Request #4257 · mne-tools/mne-python

mcaffini · 2017-05-10T11:19:37Z

I started a tutorial to process fNIRS data. It's super basic so this is definitely WIP, but we can work it out together to align this to the other tutorials and to add features of potential interest.

For now, the numpy file with test data can be found here, but we could make use of a public dataset as @agramfort previously suggested.

codecov-io · 2017-05-10T12:10:20Z

Codecov Report

Merging #4257 into master will decrease coverage by 0.1%.
The diff coverage is n/a.

@@            Coverage Diff            @@
##           master   #4257      +/-   ##
=========================================
- Coverage    86.2%   86.1%   -0.11%     
=========================================
  Files         346     346              
  Lines       64639   64639              
  Branches     9907    9907              
=========================================
- Hits        55725   55660      -65     
- Misses       6197    6266      +69     
+ Partials     2717    2713       -4

larsoner

Looks like a good start, thanks for working on this

larsoner · 2017-05-10T14:00:04Z

tutorials/Working_with_fNIRS_data.py

+
+import mne
+
+raw_ndarray = np.load('/home/matteo/raw_ndarray.npy')


Can you make a PR to add this to mne.datasets.misc here? It will be necessary for CircleCI to run, and for anybody to run your tutorial.

@mcaffini what did you have to do to get this file? there is no real file format? what would an MNE user have to do to get such a file?

Yes, @Eric89GXL that would be an option. If @agramfort still prefers a public dataset, I'll stick with him and adapt the tutorial.
BTW, the real file format is a csv file with fluences data, I manually crunched it to get HbO and HbR concentrations and then saved it in numpy format.

It might be worth going from the raw CSV data, then.

larsoner · 2017-05-10T14:00:47Z

tutorials/Working_with_fNIRS_data.py

+# Usually in fNIRS one looks for brain responses to external sensorial
+# stimulations (visual, acoustic, etc.). In order to do so, block design
+# studies are usually employed and data are later epoched to get evoked
+# responses.


This would be good to put in the triple-quoted section above.

larsoner · 2017-05-10T14:01:39Z

tutorials/Working_with_fNIRS_data.py

+# fNIRS raw data come in various formats and the best way to dive into MNE is
+# to deal with your own format first and fit your data into a 2D numpy array
+# [channels x samples]. Once you prepared your time series for HbO and HbR
+# concentrations, you can create a RawArray instance from the data array using


see other tutorials -- you can/should do

:class:`mne.io.RawArray`

and the like to make nice links for people. And then you don't even need the tail end of the sentence here "using mne.io.RawArray"

larsoner · 2017-05-10T14:02:18Z

tutorials/Working_with_fNIRS_data.py

+# 
+# In this tutorial, I don't preprocess the data. If your fNIRS device outputs
+# data in the form of photon fluences at detectors, you can compute HbO and HbR
+# concentrations using the modified Lambert-Beer model.


Can you provide some link either to a paper (in References section) or e.g. Wikipedia?

larsoner · 2017-05-10T14:02:33Z

tutorials/Working_with_fNIRS_data.py

+# concentrations using the modified Lambert-Beer model.
+# 
+# In the following example we have data from 20 channels plus one events
+# channel and we end up # with 20 HbO time series, 20 HbR time series and one


larsoner · 2017-05-10T14:07:27Z

tutorials/Working_with_fNIRS_data.py

+raw_data.filter(l_freq, h_freq)
+
+###############################################################################
+# In order to have a general glimpse of the dataset, I start by plotting all


use first-person plural "we" or second-person "you"

larsoner · 2017-05-10T14:08:05Z

tutorials/Working_with_fNIRS_data.py

+scalings = dict(hbo=10e-6, hbr=10e-6, stim=1)
+fig_title = 'fNIRS Raw Bandpass filtered [' + str(l_freq) + ' Hz, '
+    + str(h_freq) + ' Hz]'
+plot_colors = dict(hbo='r', hbr='b', stim='k')


Maybe we should just change the default colors in raw.plot. Are these standard colors for fNIRS?

Yes, red for HbO and blue for HbR are accepted standards.

Okay we should change the defaults in raw.plot, then.

larsoner · 2017-05-10T14:08:21Z

tutorials/Working_with_fNIRS_data.py

+# events data using red, blue and black respectively. I also mark color-coded
+# events positions, using the same colors previously used in
+# mne.viz.plot_events.
+scalings = dict(hbo=10e-6, hbr=10e-6, stim=1)


Again about standardization -- are these standard for fNIRS?

Not exactly standard, but reasonable. Signal dynamics may be affected by for many factors such as stimuli type, skull thickness, superficial artifacts, ...

larsoner · 2017-05-10T14:08:39Z

tutorials/Working_with_fNIRS_data.py

+###############################################################################
+# I can later dive into the dataset and look at the raw time series more
+# closely. Same color-codes through the plots is usually a good idea.
+scalings = dict(hbo=10e-6, hbr=10e-6, stim=1)


no need to redefine

larsoner · 2017-05-10T14:09:12Z

tutorials/Working_with_fNIRS_data.py

+# I can later dive into the dataset and look at the raw time series more
+# closely. Same color-codes through the plots is usually a good idea.
+scalings = dict(hbo=10e-6, hbr=10e-6, stim=1)
+fig_title = 'fNIRS Raw Bandpass filtered [' + str(l_freq) + ' Hz, '


we usually use % pattern like 'fNIRS raw bandpass filtered %s Hz - %s Hz' % (l_freq, h_freq)

agramfort · 2017-05-11T07:54:01Z

tutorials/Working_with_fNIRS_data.py

+#'hbo' or 'hbr' channel type to your channel.
+nChannels = 20 # number of physical channels
+sampling_frequency = 15.625
+channel_names_fnirs = ['HbO '+"%.2d" % i for i in range(1,nChannels+1)] +


"HbO %.2d" % i

is enough

agramfort · 2017-05-11T14:23:28Z

It might be worth going from the raw CSV data, then.

+1

agramfort · 2017-05-11T14:40:58Z

yes

mcaffini · 2017-05-11T16:02:47Z

I integrated most of the comments, I still have to work on the raw file load-parse-crunch part.

agramfort · 2017-05-11T19:30:14Z

tutorials/Working_with_fNIRS_data.py

+# :func:`mne.viz.plot_events`.
+scalings = dict(hbo=10e-6, hbr=10e-6, stim=1)
+fig_title = 'fNIRS Raw Bandpass filtered [' + str(l_freq) + ' Hz, ' +
+            str(h_freq) + ' Hz]'


use %s and not str +

like just below

ops sorry fixing this now

larsoner · 2017-05-12T13:57:53Z

tutorials/Working_with_fNIRS_data.py

+# We can later dive into the dataset and look at the raw time series more
+# closely. Same color-codes through the plots is usually a good idea.
+fig_title = 'fNIRS raw bandpass filtered %s Hz - %s Hz' % (l_freq, h_freq)
+plot_colors = dict(hbo='r', hbr='b', stim='k')


Please update these (and possibly the scalings) here:

https://github.com/mne-tools/mne-python/blob/master/mne/defaults.py#L13

We should probably explicitly pick some aesthetically nice red/blue from here instead of using 'r' and 'b' (which change from 1.+ -> 2.+ of mpl):

https://cloud.githubusercontent.com/assets/11820627/19903655/9ec8a21e-a02c-11e6-8778-80c2f2c068fb.png

larsoner · 2017-05-12T13:58:28Z

tutorials/Working_with_fNIRS_data.py

+# events data using red, blue and black respectively. We also add color-coded
+# events positions, using the same colors previously used in
+# :func:`mne.viz.plot_events`.
+scalings = dict(hbo=10e-6, hbr=10e-6, stim=1)


And assuming you're using what can be considered a standard processing setup with standard signals, let's fix the scalings in the same file. We can add it to whats_new.rst as a bugfix.

larsoner · 2017-05-12T14:00:36Z

tutorials/Working_with_fNIRS_data.py

+Use MNE with fNIRS data
+=======================
+
+MNE Python was implemented with EEG and MEG in mind, but can be useful to


originally implemented

(nowadays we try to implement things with a broader scope)

larsoner · 2017-05-12T14:00:42Z

tutorials/Working_with_fNIRS_data.py

+=======================
+
+MNE Python was implemented with EEG and MEG in mind, but can be useful to
+process fNIRS data as #well. A common fNIRS data set (similarly to EEG and


larsoner · 2017-05-12T14:01:25Z

tutorials/Working_with_fNIRS_data.py

@@ -0,0 +1,123 @@
+"""


change filename to plot_fnirs_data.py, and add it to the documentation.rst somewhere.

larsoner · 2017-08-11T01:34:56Z

@mcaffini how are we doing here? Any chance you can work on this in the next week or so? We're working on pushing out a release soon and it would be great to have this tutorial

mcaffini · 2017-09-05T11:58:34Z

Hi @larsoner and sorry for the late reply, I was off work for a long time. Yes, let's finish this in the next days.

agramfort · 2018-04-04T11:38:39Z

@mcaffini do you still plan to complete this?

mcaffini · 2018-06-29T09:30:44Z

Oops I've seen this just now, sorry.

agramfort · 2018-06-29T10:25:16Z

never too late :)

larsoner · 2019-03-27T17:54:25Z

@mcaffini any time for this in the near future? If not, I know another fNIRS person who might be able to take over

mcaffini · 2019-03-28T10:02:07Z

@larsoner I can't make it in the near future and I'd be happy if someone takes over :-)

larsoner · 2019-03-28T14:50:52Z

@mcaffini do you have the original raw data (light intensity measurements) that were used to generate the chroma concentrations (HBo / HBr)? It would be best if we could also add code to do this processing step, and having the original data + knowing what you did to convert it would help.

mcaffini · 2019-03-29T08:28:27Z

@larsoner that specific dataset was exported from our fNIRS device in the form of HbO and HbR concentrations. The conversion from raw intensity to concentration depends on the type of instrument, for CW (continuous-wave) it can be a simple modified Lambert-Beer model, but for FD (frequency-domain) and TD (time-domain) it may be more complicated.
If you think the intensity2concentration step is of interest for MNE Python, my suggestion is to discuss it independently. Eventually all type of intensity data will be converted into concentrations and, after that step, they can benefit from what is discussed here.

cbrnr · 2019-03-29T09:38:57Z

IMO it is sufficient to start from HbO/HbR signals because this is what most devices spit out.

larsoner · 2019-03-29T13:53:02Z

Thoughts @rob-luke ?

rob-luke · 2019-04-01T22:44:35Z

I agree with @mcaffini that the complexity of converting from intensity to concentration is dependent on the type of instrument. And its interesting to hear from @cbrnr that the majority of devices directly export HbO/HbR, are you in an engineering heavy field? or is this in general?

My experience is predominantly in the auditory domain. All the devices I have used are CW and export raw intensity. The devices I have interacted with are NIRX (Macquarie Uni, Bionics Institute, U California), TechEn (NIJT), and Hitachi (UCL). I also attended the last sfNIRS conference and most of the research I saw had to deal with this conversion to concentration. Perhaps the reason I have seen lots of intensity exporting machines is that I am working in less engineering heavy domains, and these CW machines may be cheaper.

I think if you want MNE fNIRS analysis to be available to as many users as possible starting with a CW intensity to concentration conversion step sounds like a good plan. @mcaffini suggestion to split this discussion to a different issue makes sense to me.

cbrnr · 2019-04-02T06:15:44Z

I've worked with fNIRS signals in the BCI field occasionally, but I'm by no means an expert. Maybe the signals I received were even preprocessed, I'm not sure. It sounds like a conversion step is definitely necessary.

rob-luke · 2019-04-05T02:15:12Z

As a first step to getting HbO/HbR I will raise a PR to read NIRX files. Then we can worry about the conversion steps. We can move this discussion when I open the PR.

larsoner · 2019-04-05T12:00:19Z

Sounds good to me.

larsoner · 2019-09-11T18:46:37Z

Closing in favor of #6674

ENH: Added tutorial for fNIRS data

b112047

larsoner reviewed May 10, 2017

View reviewed changes

agramfort reviewed May 11, 2017

View reviewed changes

integrate syntax comments

e480fe8

agramfort reviewed May 11, 2017

View reviewed changes

mini fix syntax

fcae1c5

larsoner reviewed May 12, 2017

View reviewed changes

mcaffini added 2 commits May 15, 2017 15:42

fix filename and syntax

938181e

fix filename and syntax 2

c265848

rob-luke mentioned this pull request Aug 19, 2019

MRG: Add nirx file reader #6674

Merged

10 tasks

larsoner closed this Sep 11, 2019


		import mne

		raw_ndarray = np.load('/home/matteo/raw_ndarray.npy')

Uh oh!

Conversation

mcaffini commented May 10, 2017

Uh oh!

codecov-io commented May 10, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mcaffini May 11, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agramfort commented May 11, 2017 via email

Uh oh!

agramfort commented May 11, 2017 via email

Uh oh!

mcaffini commented May 11, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

larsoner commented Aug 11, 2017

Uh oh!

mcaffini commented Sep 5, 2017

Uh oh!

agramfort commented Apr 4, 2018

Uh oh!

mcaffini commented Jun 29, 2018

Uh oh!

agramfort commented Jun 29, 2018 via email

codecov-io commented May 10, 2017 •

edited

Loading

mcaffini May 11, 2017 •

edited

Loading

rob-luke commented Apr 1, 2019 •

edited

Loading