ENH: Support reading FIL-OPM-MEG data

[larsoner]

@neurofractal I want to try using your auditory evoked OPM dataset in MNE-Python. Is the .bin format you use there mature enough that it would make sense to make a proper data reader in MNE-Python?

If so, my plan was to look at your MATLAB code to figure out how raw data is actually being read, then ask whoever I need to ask permission to relicense under MNE-Python's BSD license (if required). Does this sound reasonable to you?

If so, do you have any tiny datasets (1-2 sec of data) from the system that we could add to mne-testing-data? I would just read it in Python and ensure the binary values match what I get using your MATLAB code for example, so no need for it to be useful neuroscience data, just something where we could at least check that binary data values and sensor locations are sensible for example.

[neurofractal]

Hey @larsoner - good to hear from you! Sounds cool - it would be great to get more OPM resources into MNE-Python.

Is the .bin format you use there mature enough that it would make sense to make a proper data reader in MNE-Python?

Yes - we will be using it at UCL for the foreseeable future. I'm unsure if up-and-coming OPM manufactures will adopt it though...

Does this sound reasonable to you?

Absolutely. I'll also point you in the direction of @georgeoneill from UCL who has been writing some add-ons to load our data into the MNE ecosystem: https://github.com/FIL-OPMEG/OPyM. Perhaps we could all contribute to a PR on this?

do you have any tiny datasets (1-2 sec of data)

Sure - I can send you this.

Some more general thoughts:

• The dataset on Zenodo features AEF data acquired during movement and will therefore be very noisy. As an alternative I have similar and much cleaner AEF data with the participant sitting still.
• The moving AEF might require Homogenous Field Correction (Tierney et al., 2021) to look sensible.

[georgeoneill]

Hello @larsoner

Happy to be of assistance with this!

[larsoner]

I'm unsure if up-and-coming OPM manufactures will adopt it though...

I don't think this matters so much as there actually being files in the wild that people (ideally from institutions) need to read. I count as one of those people so I think we're in the clear :)

I'll also point you in the direction of @georgeoneill from UCL who has been writing some add-ons to load our data into the MNE ecosystem: https://github.com/FIL-OPMEG/OPyM. Perhaps we could all contribute to a PR on this?

That would be great! Initial thoughts from a very quick glance at the README:

1. read_raw_ucl -- I guess in principle the read_raw_ucl could continue to exist in a separate, non mne module like OPyM if you want. It might make integration with mne-bids a tiny bit less straightforward because you can't just use mne.io.read_raw to read it. My preference would be to put it in MNE-Python for simplicity but I'm happy either way.
2. HFC -- we also plan to support that directly in MNE-Python (for all OPM manufacturers) so maybe MNE-Python is a better place for that so that we don't duplicate effort?
3. coreg -- we plan to support OPM coregistration, probably through the existing mne coreg GUI. I'm still coming to understand the details of how this stuff works so it's not easy for me to say the scope here, but I've worked with the 3D plotting stuff there so I could help add the parts we need (I assume the big part would be allowing you to supply a helmet mesh).

When I say "we plan to support" I mean we have some dedicated FTE (probably mine) for this through the MNE-Python NIH R01 because the TL;DR for the first aim was "support OPMs", so I think we could make quick progress if we work together on it.

The dataset on Zenodo features AEF data acquired during movement and will therefore be very noisy. As an alternative I have similar and much cleaner AEF data with the participant sitting still.

Ahh yes until we have HFC the "still" case would be a better place to start. So maybe:

1. A first PR adds some reading support (or uses OPyM for this), and in its tutorial, loads the "still" data, and show that we can see + localize some auditory activation
2. Subsequent PRs add HFC and the "moving" data, and show that HFC + movement info can be used to deal with movement to obtain equivalent auditory activation

@neurofractal for (1), could we upload the data to osf.io or openneuro, without the need to get individual permission to get the data (like I think is the case for the Zenodo "moving" dataset)? This is necessary for our CIs to build docs, and also for users to be able to readily run the tutorials, at least so far. It might not be a deal breaker if you do want to keep "approval required" access to the data, but it will mean some more work and thinking about our CI infrastructure.

[georgeoneill]

1. read_raw_ucl -- I guess in principle the read_raw_ucl could continue to exist in a separate, non mne module like OPyM if you want. It might make integration with mne-bids a tiny bit less straightforward because you can't just use mne.io.read_raw to read it. My preference would be to put it in MNE-Python for simplicity but I'm happy either way.

Personally, I am happy with read_raw_ucl being integrated into MNE-Python. OPyM's intention was to be a stopgap for the bits of functionality not yet integrated into MNE-Python, or for some of the groups more esoteric requirements. Yes I can see why mne.io.read_raw will not be able to disambiguate between our data and the artemis123 .bin format. But this is something which we might be able to trivially change going forward (i.e. swtich the file extention at the lab, .fil anybody?)

2. HFC -- we also plan to support that directly in MNE-Python (for all OPM manufacturers) so maybe MNE-Python is a better place for that so that we don't duplicate effort?

This is great news to hear! As you can see we've been doing some initial tests. I've been trying to work out whats the best approach for MNE-Python. We normally do a hard correction to the data (rather than having an online montage) and then update our 'compensation matrix' to update our forward modelling later. But I realise this is not in the nature of how the SSP filters work in MNE-Python (i.e. only activated when needed). This might need some thought. We also have been expeirmenting with higher harmonic orders (see Tierney et al. 2022, so we are starting to look more like a half-implemented MaxFilter.

3. coreg -- we plan to support OPM coregistration, probably through the existing mne coreg GUI. I'm still coming to understand the details of how this stuff works so it's not easy for me to say the scope here, but I've worked with the 3D plotting stuff there so I could help add the parts we need (I assume the big part would be allowing you to supply a helmet mesh).

We are still trying to understand where to go with this ourselves. Currently in our lab we all posess bespoke scannercasts derived from the anatomy of each participant, so the tranfrormation between the sensors to the anatomy is either identity or a translation (depending if the cRAS information of the anatomical was read correctly).

HOWEVER we've started to collect data from a site which they use generic helmets, so optical scans and point cloud/rigid body registrations are required, we'll have a better handle on this going forward. The rigid helmets will certainly be the case for the Cerca Magnetics systems going forward. The meshes for the Cerca helmets are provided in OPyM.

[neurofractal]

@neurofractal for (1), could we upload the data to osf.io or openneuro, without the need to get individual permission to get the data (like I think is the case for the Zenodo "moving" dataset)? This is necessary for our CIs to build docs, and also for users to be able to readily run the tutorials, at least so far. It might not be a deal breaker if you do want to keep "approval required" access to the data, but it will mean some more work and thinking about our CI infrastructure.

Sure - I have uploaded the "still" AEF data to OSF:

• Data: https://doi.org/10.17605/OSF.IO/VY5N6
• Code: https://github.com/FIL-OPMEG/tutorials_interference/blob/main/stationary_AEF.m

Let me know if you need anything else :)

[larsoner]

Personally, I am happy with read_raw_ucl being integrated into MNE-Python. OPyM's intention was to be a stopgap for the bits of functionality not yet integrated into MNE-Python, or for some of the groups more esoteric requirements. Yes I can see why mne.io.read_raw will not be able to disambiguate between our data and the artemis123 .bin format. But this is something which we might be able to trivially change going forward (i.e. swtich the file extention at the lab, .fil anybody?)

Filename-based parsing is bound to break at some point anyway. We can't ask manufacturers to get along with each other :) I think there is even an EEG format or two that already share the same filename :shrug:

I don't think it will be too hard to disambiguate in principle. For artemis, it looks like there is an obligatory accompanying .txt file with some metadata that we can look for and parse. I assume your file format similarly has some accompanying file, or some header bits in the first ~1k of binary that make it clear if it's a FIL-OPM file. If that's the case, a simple try/except or smarter triaging function could work.

To get the ball rolling, @georgeoneill would you be up for adding a 1-2 sec OPM file from your system to mne-testing-data, along with a .mat file with the MATLAB-read/parsed metadata (sensor locations, etc.) and binary sensor data? That way we can verify our reading in MNE-Python against the canoncial/known/trusted MATLAB version. And maybe it's almost as easy as copy-pasting your existing code into MNE-Python :crossed_fingers: The more of this you're willing to do, the better, but let me know if/where/when you'd like help!

Concurrently I can make a dataset downloader for the data that @neurofractal has already uploaded. I'll ping you in that PR to make sure I have the right citation information in it.

I'll open separate issues for other OPM-related stuff so we can keep the discussions straight (and keep this one about I/O).

[larsoner]

BTW @georgeoneill @neurofractal given that this, #10780, and #11276 might require a bit of discussion, feel free to join our discord https://discord.gg/rKfvxTuATa and we can set a time to chat if it's easier for you! Otherwise I'm happy to continue discussion on GitHub

[georgeoneill]

Hi @larsoner, apologies for the radio silence.

I'm putting some data onto mne-testing-data imminently. I'll include a .mat file with an output from FieldTrip-like importer with all the metadata. A PR for that will be sent soon.

I'm definitely happy to do some of the legwork on getting the initial import code working with MNE. Unsure how the unit-testing might pan out, but this is something we can continue to discuss here or on Discord (I've signed up).