Read haemoglobin data from SNIRF #9929

rob-luke · 2021-10-30T09:49:17Z

What does this implement/fix?

The SNIRF file format (https://github.com/fNIRS/snirf) supports a great variety of fNIRS data types. Currently MNE only supports reading continuous wave amplitude data from SNIRF files (referred to in SNIRF as type 1).

MNE-Python currently supports reading/processing continuous wave and frequency domain fNIRS signals (time-domain coming in the next few weeks hopefully!). The raw signals are then converted to haemoglobin concentration for analysis. This PR adds support for reading the processed oxy and deoxyhaemoglobin signals (HbO & HbR) from SNIRF files. (referred to in SNIRF as type 99999 processed with dataTypeLabel HbO and HbR).

Some devices export directly in HbO/HbR so this enables support for those devices. And also enables sharing of data that is preprocessed in other software.

Additional information

This begun in the #9661 PR. However, that PR was much larger and also wanted to add support for a completely new type of fNIRS (time domain fNIRS). This breaks out a more manageable sized PR. Then, once we have a more complete understanding we can tackle adding the TD-fNIRS types etc.

Currently no changelog as this won't make it in to 0.24, once 24 is released I will rebase and add to the new list and add @Zahra-M-Aghajan as co-author as much of the actual code is from her original PR.

FYI: @Zahra-M-Aghajan @julien-dubois-k

rob-luke · 2021-10-30T09:58:04Z

@sstucker @dboas does Homer export SNIRF files in 99999 hbo/hbr format? If so, is there a test file publicly available I can test our implementation against to ensure compatibility with Homer? If Homer does export SNIRF in HbO/HbR but no file is available, I can create one with Homer myself, but has the SNIRF export code stabilised? Or should I wait till the validator etc is completed?

rob-luke · 2021-10-31T02:08:04Z

Ok, the coordinate frame for Kernel data is 'mri'. ~~Is this correct @Zahra-M-Aghajan @julien-dubois-k ?~~ (I found the answer on the kernel community site)

I can not determine the coordinate frame correctly from the SNIRF file alone. So the user needs to load it with the optode_frame='mri' argument, which isn't a problem, but would be nice to make this automatically detected. @Zahra-M-Aghajan is there any way that we could get this information included within the SNIRF file in the future? I have opened an issue upstream in the SNIRF standard for a new optional field to specify this. fNIRS/snirf#89 Currently MNE uses its own custom field (which is explicitly allowed within SNIRF) to store the coordinate frame, but I would prefer this is included in the actual standard...

mne-python/mne/io/snirf/_snirf.py

Lines 271 to 272 in 47c0112

    
           elif 'MNE_coordFrame' in dat.get('nirs/metaDataTags/'): 
        
               coord_frame = int(dat.get('/nirs/metaDataTags/MNE_coordFrame')

Using the measurement file provided by @JohnGriffiths everything seems to be looking good so far...

kernel_hb = '/Volumes/MassStorage2TB/rluke/Repositories/' \
            'kernel-flow-tools/pitch_sub010_ft_ses01_1017-1706_kp-snf-hbm.snirf'

from mne.io import read_raw_snirf
import os.path as op
import mne

raw = read_raw_snirf(kernel_hb, optode_frame='mri', preload=True)

# Plot sources and detectors on head
subjects_dir = op.join(mne.datasets.sample.data_path(), 'subjects')
mne.datasets.fetch_fsaverage(subjects_dir=subjects_dir)
brain = mne.viz.Brain('fsaverage', subjects_dir=subjects_dir, alpha=0.5, cortex='low_contrast', background="white")
brain.add_head()
brain.add_sensors(raw.info, trans='fsaverage', fnirs=['sources', 'detectors'])
brain.enable_depth_peeling()
brain.show_view(azimuth=90, elevation=90, distance=500)

# Plot channels only
brain = mne.viz.Brain('fsaverage', subjects_dir=subjects_dir, alpha=0.5, cortex='low_contrast', background="white")
brain.add_sensors(raw.info, trans='fsaverage', fnirs=['channels'])
brain.enable_depth_peeling()
brain.show_view(azimuth=90, elevation=90, distance=500)

# Plot pairs only
brain = mne.viz.Brain('fsaverage', subjects_dir=subjects_dir, alpha=0.5, cortex='low_contrast', background="white")
brain.add_sensors(raw.copy().pick('hbo').info, trans='fsaverage', fnirs=['pairs'])
brain.enable_depth_peeling()
brain.show_view(azimuth=90, elevation=90, distance=500)

rob-luke · 2021-10-31T05:23:32Z

Ok, I have done some more playing around to ensure that downstream processing can handle so many channels. One thing I've noticed is that many channels have Nans in them. So this might be a useful snippet for end-users.

raw.info['bads'] = np.isnan(raw.get_data()).any(axis=1)
# and/or
raw.drop_channels(list(compress(raw.ch_names, raw.info['bads'])))

After running this on Johns data it still leaves almost 1000 source detector pairs.

rob-luke · 2021-10-31T05:33:39Z

And I have run my standard GLM analysis on the channel level data then used mne-nirs surface_projection (which just wraps MNE stc_near_sensors) to get this...

Red dots are sources. Black dots are detectors.

I don't know what is in the data or if its meaningful, but this demonstrates that the data is moving through the end-to-end processing without errors.

I think as the next steps we get the small test file and then let @JohnGriffiths see if the branch works for him. Then should be good for review.

rob-luke · 2021-10-31T05:38:02Z

tutorials/io/30_reading_fnirs_data.py

+NIRx     ICBM-152 MNI        mri
+Kernel   ICBM 2009b          mri


I have just taken the model names exactly as described by the vendors. I guess these might actually be the same thing?

I don't know the bottom line but I would be very concerned for my sanity if those two were meaningfully different MNI spaces.

haha agreed, I am pretty sure they are practically the same. Maybe I will just change them both to ICBM

they may be slightly different: there are several versions of the ICBM-152 MNI atlas (2009a, 2009b, 2009c; and within each, different flavors, symmetric vs. asymmetric). 152 refers to the number of individual subjects' scans that went into creating the atlas.

The 2009b is the highest resolution atlas (0.5mm isotropic) and thus the one we chose to run tissue segmentation and make meshes.

Calling them both ICBM-152 MNI is likely enough information.

Yes there are different template images, but the space = the co-ordinate frame, ie the target of the voxel-to-world transform in the header's affine matrix, should I think be same.

( Whether MRI template images in standard space used for registration should be called 'atlases' is debatable, but it's true that is a common terminology )

agreed on both points.

Thank you both for the information. I appreciate you sharing your knowledge here, I am learning lots as we go along here :)

Zahra-M-Aghajan · 2021-11-02T17:31:14Z

Ok, the coordinate frame for Kernel data is 'mri'. ~~Is this correct @Zahra-M-Aghajan @julien-dubois-k ?~~ (I found the answer on the kernel community site)

I can not determine the coordinate frame correctly from the SNIRF file alone. So the user needs to load it with the optode_frame='mri' argument, which isn't a problem, but would be nice to make this automatically detected. @Zahra-M-Aghajan is there any way that we could get this information included within the SNIRF file in the future? I have opened an issue upstream in the SNIRF standard for a new optional field to specify this. fNIRS/snirf#89 Currently MNE uses its own custom field (which is explicitly allowed within SNIRF) to store the coordinate frame, but I would prefer this is included in the actual standard...

mne-python/mne/io/snirf/_snirf.py

Lines 271 to 272 in 47c0112

elif 'MNE_coordFrame' in dat.get('nirs/metaDataTags/'):

coord_frame = int(dat.get('/nirs/metaDataTags/MNE_coordFrame')

Using the measurement file provided by @JohnGriffiths everything seems to be looking good so far...
kernel_hb = '/Volumes/MassStorage2TB/rluke/Repositories/' \
            'kernel-flow-tools/pitch_sub010_ft_ses01_1017-1706_kp-snf-hbm.snirf'

from mne.io import read_raw_snirf
import os.path as op
import mne

raw = read_raw_snirf(kernel_hb, optode_frame='mri', preload=True)

# Plot sources and detectors on head
subjects_dir = op.join(mne.datasets.sample.data_path(), 'subjects')
mne.datasets.fetch_fsaverage(subjects_dir=subjects_dir)
brain = mne.viz.Brain('fsaverage', subjects_dir=subjects_dir, alpha=0.5, cortex='low_contrast', background="white")
brain.add_head()
brain.add_sensors(raw.info, trans='fsaverage', fnirs=['sources', 'detectors'])
brain.enable_depth_peeling()
brain.show_view(azimuth=90, elevation=90, distance=500)

# Plot channels only
brain = mne.viz.Brain('fsaverage', subjects_dir=subjects_dir, alpha=0.5, cortex='low_contrast', background="white")
brain.add_sensors(raw.info, trans='fsaverage', fnirs=['channels'])
brain.enable_depth_peeling()
brain.show_view(azimuth=90, elevation=90, distance=500)

# Plot pairs only
brain = mne.viz.Brain('fsaverage', subjects_dir=subjects_dir, alpha=0.5, cortex='low_contrast', background="white")
brain.add_sensors(raw.copy().pick('hbo').info, trans='fsaverage', fnirs=['pairs'])
brain.enable_depth_peeling()
brain.show_view(azimuth=90, elevation=90, distance=500)

@rob-luke Thanks so much for doing this, everything is looking great!
We can easily add the extra field to metaDataTags.. should I wait till this is standardized (re your open issue on SNIRF specs)? I see that you are using the field MNE_coordFrame in the metaDataTags, which will be set to 'mri' in our case for now..

rob-luke · 2021-11-03T02:11:53Z

We can easily add the extra field to metaDataTags.. should I wait till this is standardized (re your open issue on SNIRF specs)? I see that you are using the field MNE_coordFrame in the metaDataTags, which will be set to 'mri' in our case for now..

Thanks @Zahra-M-Aghajan for being so open about this. Let's give the SNIRF developers another week to chime in. If they don't speak up in a week, it would be great to add the field MNE_coordFrame until a solution appears upstream. In this case, you would store the number 5 in the field, you can see the coding of coordinate frames in FIFF format below. This isn't essential, but I think would be easier for end users, rather than needing to specify the coord frame manually each time.

mne-python/mne/io/constants.py

Lines 241 to 253 in b97da43

    
           # 
        
           # Coordinate frames 
        
           # 
        
           FIFF.FIFFV_COORD_UNKNOWN        = 0 
        
           FIFF.FIFFV_COORD_DEVICE         = 1 
        
           FIFF.FIFFV_COORD_ISOTRAK        = 2 
        
           FIFF.FIFFV_COORD_HPI            = 3 
        
           FIFF.FIFFV_COORD_HEAD           = 4 
        
           FIFF.FIFFV_COORD_MRI            = 5 
        
           FIFF.FIFFV_COORD_MRI_SLICE      = 6 
        
           FIFF.FIFFV_COORD_MRI_DISPLAY    = 7 
        
           FIFF.FIFFV_COORD_DICOM_DEVICE   = 8 
        
           FIFF.FIFFV_COORD_IMAGING_DEVICE = 9

dboas · 2021-11-03T17:48:42Z

I don’t have specific comments on this as I am not expert in these coordinate transformations. MRI people are best at this and we should follow their standards. From: Robert Luke ***@***.***> Date: Tuesday, November 2, 2021 at 10:12 PM To: mne-tools/mne-python ***@***.***> Cc: Boas, David ***@***.***>, Mention ***@***.***> Subject: Re: [mne-tools/mne-python] Read haemoglobin data from SNIRF (PR #9929) We can easily add the extra field to metaDataTags.. should I wait till this is standardized (re your open issue on SNIRF specs)? I see that you are using the field MNE_coordFrame in the metaDataTags, which will be set to 'mri' in our case for now.. Thanks @Zahra-M-Aghajan<https://github.com/Zahra-M-Aghajan> for being so open about this. Let's give the SNIRF developers another week to chime in. If they don't speak up in a week, it would be great to add the field MNE_coordFrame until a solution appears upstream. In this case, you would store the number 5 in the field, you can see the coding of coordinate frames in FIFF format below. This isn't essential, but I think would be easier for end users, rather than needing to specify the coord frame manually each time. https://github.com/mne-tools/mne-python/blob/b97da4357f9ffb584eef5949c958187b3a7cc566/mne/io/constants.py#L241-L253 — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#9929 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AHFCP5GZP33DSAEQW2STXR3UKCK7LANCNFSM5HA4NNEA>. Triage notifications on the go with GitHub Mobile for iOS<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android<https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

rob-luke · 2021-11-19T22:52:44Z

Now using released testing data from mne-tools/mne-testing-data#90
I will update the tests, then this should be ready for review.

larsoner · 2021-11-19T22:53:24Z

Okay, ping for review once tests are updated and everything is green

rob-luke · 2021-11-20T00:56:22Z

All green! @larsoner @agramfort could you please review

larsoner

Other than a few minor things, LGTM

mne/io/snirf/_snirf.py

mne/io/snirf/tests/test_snirf.py

rob-luke · 2021-11-20T02:40:18Z

Thanks @larsoner

agramfort

@larsoner merge if happy

larsoner · 2021-11-22T18:01:37Z

Thanks @rob-luke !

larsoner · 2021-11-22T18:02:10Z

Argh just noticed there was no latest.inc, could you make a quick PR to add one @rob-luke ? Or if you have plans for some other PR soon, just add it there?

rob-luke · 2021-11-22T21:24:33Z

Thanks @larsoner

I'll make a small PR when at work today for the missing change log. Sorry

rob-luke added 3 commits October 30, 2021 20:36

Read haemoglobin data from SNIRF

1badf4b

Read haemoglobin data from SNIRF

d9988eb

Read haemoglobin data from SNIRF

3ebf0ad

rob-luke mentioned this pull request Oct 31, 2021

Add optional coordinate system field to probe fNIRS/snirf#89

Closed

Update tutorial

adccf4c

Update tutorial

536c8e9

rob-luke commented Oct 31, 2021

View reviewed changes

rob-luke added this to the 1.0 milestone Oct 31, 2021

rob-luke mentioned this pull request Nov 19, 2021

Kernel Flow50 haemoglobin SNIRF mne-tools/mne-testing-data#90

Merged

rob-luke added 2 commits November 20, 2021 09:47

Merge branch 'mne-tools:main' into snirfhb

0cce004

Use released testing data

17c86e4

rob-luke added 3 commits November 20, 2021 10:17

Add tests

22adfb9

Flake

0c3fa01

Final test

336af1f

rob-luke marked this pull request as ready for review November 20, 2021 00:20

larsoner reviewed Nov 20, 2021

View reviewed changes

mne/io/snirf/_snirf.py Outdated Show resolved Hide resolved

mne/io/snirf/_snirf.py Outdated Show resolved Hide resolved

mne/io/snirf/tests/test_snirf.py Outdated Show resolved Hide resolved

mne/io/snirf/tests/test_snirf.py Outdated Show resolved Hide resolved

Larsoner feedback

87f19c9

rob-luke marked this pull request as draft November 20, 2021 04:37

rob-luke marked this pull request as ready for review November 20, 2021 04:40

agramfort approved these changes Nov 20, 2021

View reviewed changes

larsoner merged commit f621302 into mne-tools:main Nov 22, 2021

rob-luke mentioned this pull request Nov 23, 2021

Add haemoglobin SNIRF support to changelog #10027

Merged

rob-luke mentioned this pull request Dec 5, 2021

Add coordinateSystem fields fNIRS/snirf#94

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Read haemoglobin data from SNIRF #9929

Read haemoglobin data from SNIRF #9929

rob-luke commented Oct 30, 2021 •

edited

Loading

rob-luke commented Oct 30, 2021 •

edited

Loading

rob-luke commented Oct 31, 2021 •

edited

Loading

rob-luke commented Oct 31, 2021

rob-luke commented Oct 31, 2021 •

edited

Loading

rob-luke Oct 31, 2021

JohnGriffiths Oct 31, 2021

rob-luke Oct 31, 2021

julien-dubois-k Nov 2, 2021 •

edited

Loading

JohnGriffiths Nov 2, 2021

julien-dubois-k Nov 2, 2021

rob-luke Nov 3, 2021

Zahra-M-Aghajan commented Nov 2, 2021

rob-luke commented Nov 3, 2021

dboas commented Nov 3, 2021 via email

rob-luke commented Nov 19, 2021

larsoner commented Nov 19, 2021

rob-luke commented Nov 20, 2021

larsoner left a comment

rob-luke commented Nov 20, 2021

agramfort left a comment

larsoner commented Nov 22, 2021

larsoner commented Nov 22, 2021

rob-luke commented Nov 22, 2021

Read haemoglobin data from SNIRF #9929

Read haemoglobin data from SNIRF #9929

Conversation

rob-luke commented Oct 30, 2021 • edited Loading

What does this implement/fix?

Additional information

rob-luke commented Oct 30, 2021 • edited Loading

rob-luke commented Oct 31, 2021 • edited Loading

rob-luke commented Oct 31, 2021

rob-luke commented Oct 31, 2021 • edited Loading

rob-luke Oct 31, 2021

Choose a reason for hiding this comment

JohnGriffiths Oct 31, 2021

Choose a reason for hiding this comment

rob-luke Oct 31, 2021

Choose a reason for hiding this comment

julien-dubois-k Nov 2, 2021 • edited Loading

Choose a reason for hiding this comment

JohnGriffiths Nov 2, 2021

Choose a reason for hiding this comment

julien-dubois-k Nov 2, 2021

Choose a reason for hiding this comment

rob-luke Nov 3, 2021

Choose a reason for hiding this comment

Zahra-M-Aghajan commented Nov 2, 2021

rob-luke commented Nov 3, 2021

dboas commented Nov 3, 2021 via email

rob-luke commented Nov 19, 2021

larsoner commented Nov 19, 2021

rob-luke commented Nov 20, 2021

larsoner left a comment

Choose a reason for hiding this comment

rob-luke commented Nov 20, 2021

agramfort left a comment

Choose a reason for hiding this comment

larsoner commented Nov 22, 2021

larsoner commented Nov 22, 2021

rob-luke commented Nov 22, 2021

rob-luke commented Oct 30, 2021 •

edited

Loading

rob-luke commented Oct 30, 2021 •

edited

Loading

rob-luke commented Oct 31, 2021 •

edited

Loading

rob-luke commented Oct 31, 2021 •

edited

Loading

julien-dubois-k Nov 2, 2021 •

edited

Loading