Mne-python: Add Interface(s) to/from FieldTrip

[thht]

As requested by @agramfort, here is the todo list:

• [X] Include pymatreader in mne-python to read any kind of mat file (old version and hdf5 based) in a consistent way
• [X] Read MEG data originating from the Neuromag Triux System at Salzburg
  
  
  
  • [X] Raw data
  
  
  • [X] Epoched data
  
  
  • [X] Averaged Timelocked data
  
  
  • [X] Write Unittests to verify above functionality
  
  
  • [X] Import channel descriptions (i.e., type, location, orientation etc)
  
  
  • [X] Verify this is done correctly.
    
    
    
    
    
    • [X] Mostly done and tested. Only problem is that FieldTrip always stores channel locations in head coordinates. The reader functions store the data in head coordinates. But for testing, I would need to find out how to transform the device coords of the mne read FIFF file object to head coords.
    
    
    
    • [X] Create mat files with that testing data
    
    
    
  
  
• [X] Read EEG, EOG, ECG and misc channels. Done and tested for Neuromag Sytsmes
• [X] Read event data from FieldTrip raw data structure
• [X] Make sure this all works with data from other systems. Just reading the MEG/EEG data should not be problematic at all. The metadata might be.
• [ ] Read Power and other spectra
• [ ] Read Time-Frequency data
• [ ] Read Source Space data

The corresponding PR is #5141

I leave the original issue here for reference:

I think, it would be great if it was possible to go back and forth between FieldTrip and mne-python.

We have a motivated and skilled student who will be supervised by me. Our group is very interested in this feature, so we are willing to contribute significant work.

I would suggest that we try to go for a solution that is as universal as possible from the beginning:

1. Read and write all available data structures:
   1.1. Raw Data
   1.2. Epoched Data
   1.3. Averaged Timelocked Data
   1.4. Power and other spectra (i.e. frequency resolved data), averaged and single trial
   1.5. Time-Frequency Data (averaged and single trial)
   1.6. Source Space Data
2. Use .mat files at least for the import, possibly also for the export.
   2.1. Be agnostic to the version of the .mat file (old version vs. the hdf5 based one). This would require writing some sort of abstraction on top of the scipy.io and h5py or pytables

One of the main questions that comes to mind is where this would fit into the structure of mne-python. One obvious place would of course be mne.io. However, we are not only dealing with raw data here, for which that package would be the logical spot.

So, for the moment, I see two possibilities:

1. Write one read_fieldtrip function that automatically detects what kind of data is in the .mat file and then returns the appropriate object.
2. Write individual functions for every "kind" of data.

I am looking forward to your input!

Best,
Thomas

[agramfort]

Hi Thomas,

this question was raised in the past and previously we went the other way
around
which is to have reader and writer for mne fif files in fieldtrip.

it was working with raw, epochs and evoked.

for the rest I am not sure what it involves. When it deals with source space
as fieldtrip does not require freesurfer that might be tricky to keep things
simple on mne side

Alex

[dengemann]

On the other hand the io support for MNE is broken / incomplete in FT and
it seems no one takes care of it.
Reading FT epochs is a frequent maintenance request and since we have
eeglab and brainstorm readers why not a basic API that can encourage
newcomers to try MNE.

My 3 cents.
On Thu 14 Dec 2017 at 17:52, Alexandre Gramfort [e-mail]
wrote:

Hi Thomas,

this question was raised in the past and previously we went the other way
around
which is to have reader and writer for mne fif files in fieldtrip.

it was working with raw, epochs and evoked.

for the rest I am not sure what it involves. When it deals with source
space
as fieldtrip does not require freesurfer that might be tricky to keep
things
simple on mne side

Alex

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/mne-tools/mne-python/issues/4833#issuecomment-351769535,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AB0fiqm1fZGX9ia1L87C9LpJEkgRSI3Wks5tAVJegaJpZM4RCKqk
.

[agramfort]

we don't have brainstorm readers but yes you are right. It would be a
valuable
addition to mne.

Thomas if you have the man power to do this it is great.

[thht]

Hi Alex and Denis,

thanks for your support. I also think that it might make more sense to integrate the API in mne instead of FieldTrip because the data structures are more complex in mne (my current impression), being classes instead of Matlab structures. Conversion should thus be easier in python/mne...

We will do some prototyping in the coming days and come back to you as soon as we have something to show.

One question before we start:

Do you already use some kind of hdf5 library in mne? We need one in order to read v7.3 mat files. The most abstract one I found so far is hdf5storage, although it seems to have problems with structures (as does scipy.io).

Best,
Thomas

[jasmainak]

For hdf5, take a look here: https://github.com/mne-tools/mne-python/tree/de256c8c314e3e158371e0fb90242f86af9a4753/mne/externals/h5io

[larsoner]

h5io won't handle MATLAB files, you'll need to use h5py directly

[dengemann]

I'd at least start with sensor space data, raw, epochs, evoked.
Then for source space we would need a joint FT-MNE hackathon I fear ...
things really depart art that level.

On Fri, Dec 15, 2017 at 12:46 PM Eric Larson [e-mail]
wrote:

h5io won't handle MATLAB files, you'll need to use h5py directly

—
You are receiving this because you commented.

Reply to this email directly, view it on GitHub
https://github.com/mne-tools/mne-python/issues/4833#issuecomment-351986575,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AB0fiu1zdGGLwYnv5-JdD6pV2hE3euYeks5tAlwKgaJpZM4RCKqk
.

[thht]

ok. so we will use h5py and possibly also hdf5storage (which is another layer of abstraction on top of h5py) for reading mat files.

and yes, we will start with sensor space data.

[britta-wstnr]

Hi @thht - for the source space bit, I recently wrote some scripts plus examples on how to get MNE-Python source space data to Fieldtrip for plotting etc. The scripts take care of all the transformation matrix issues associated with that - but are not heavily tested yet ;-)

You can find them here:
https://github.com/meeg-cfin/nemolab/tree/master/mne_ft_conversions

[thht]

hi,
so, we have decided for now to develop this feature outside of mne-python. we have so far developed a package to unify reading mat-files (i.e. both <=7 and 7.3). you can find it here: https://gitlab.com/obob/pymatreader . we also developed a package called fieldtrip2mne (https://gitlab.com/obob/fieldtrip2mne) that can for now read raw, epoch and evoked data.

both packages can be found on pypi and conda.

i think it would be a good idea to keep the mat-file reader independent from mne-python as it is useful as well for other use-cases.

considering the fieldtrip2mne package: i would leave it up to you guys whether you want to include it directly into mne-python or keep it separate.

in any case, i would like to invite anybody interested in trying out the packages and give us some feedback.

[agramfort]

thanks @thht !

this should be documented in this file: https://github.com/mne-tools/mne-python/blob/master/doc/manual/io.rst
as well as on the fieldtrip wiki. cc @robertoostenveld

@smgutstein can you see if pymatreader can be an easier alternative to what you wrote to support hdf5 eeglab files?

now a problem is that you used GPLv3 for your license which we don't want in MNE-Python which is BSD licensed like most of the scientific python world. Is it a conscious decision @thht ?

[thht]

thanks for the appreciation!

considering the license issue: the GPLv3 is my default license for code that i publish because i like the fact that if someone uses my work and modifies it, it needs to stay open source. so yes, it is a conscious decision.

but if you decide that you want to include the code directly in mne-python, i would be open to change the license to the BSD one.

would that be necessary for both fieldtrip2mne and pymatreader?

[dengemann]

Yes for any code to be included in MNE Python.
On Mon 9 Apr 2018 at 09:45, Thomas Hartmann [e-mail]
wrote:

thanks for the appreciation!

considering the license issue: the GPLv3 is my default license for code
that i publish because i like the fact that if someone uses my work and
modifies it, it needs to stay open source. so yes, it is a conscious
decision.

but if you decide that you want to include the code directly in
mne-python, i would be open to change the license to the BSD one.

would that be necessary for both fieldtrip2mne and pymatreader?

—
You are receiving this because you commented.

Reply to this email directly, view it on GitHub
https://github.com/mne-tools/mne-python/issues/4833#issuecomment-379664231,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AB0fiqLqRgit0U-tJ0QUUSErtnV46dV-ks5tmxGugaJpZM4RCKqk
.

[agramfort]

yes it's necessary.

Good reads on this:

see http://ivory.idyll.org/blog/2015-on-licensing-in-bioinformatics.html
http://www.astrobetter.com/blog/2014/03/10/the-whys-and-hows-of-licensing-scientific-code/

[thht]

ok, thanks for the clarification. is it correct that this also holds for code that is not included directly into mne-python but merely a dependency?

[agramfort]

yes. It has been our policy so far. No copy-left code in MNE.

[thht]

ok. i still need to speak to my colleague who has also contributed to the code. but i do not expect it to be a problem.

assuming we have re-licensed to BSD, would you like to include fieldtrip2mne directly into your code or do you want to keep it separate? and what about pymatreader?

as i said in one of my previous posts, i do not have any preferences concerning fieldtrip2mne. i would like to keep pymatreader separate, though.

what is your workflow here? what do you prefer? what can i do to help?

[thht]

ok, my colleague just told me that he is fine with the BSD license as well. i will update the respective information shortly.

[agramfort]

great

that will make everything easier.

[thht]

ok, pymatreader and fieldtrip2mne are now under the 2-clause BSD license.

[agramfort]

great !

could you add cross-refs to how docs?

[thht]

so you mean a link to here: http://fieldtrip2mne.readthedocs.io/en/latest/ ?

[agramfort]

thinking a bit more. I would suggest:

• keep pymatreader https://gitlab.com/obob/pymatreader as a separate
  package with proper release cycles. Put a copy in externals module.
• integrate fieldtrip2mne in mne/io/fieldtrip

wdyt?

[larsoner]

Sounds good to me

[thht]

i agree. i think this makes the fieldtrip2mne part available to a wide userbase. and i guess that it is the easiest solution to fir into the MNE release system.

[agramfort]

great

can you start a PR?

[thht]

yes, i will do. sorry for the delay...

i would organize the new files like this. please tell me if that is ok with you:

1. the fieldtrip2mne reader functions will be renamed to read_ft_raw, read_ft_epoched, read_ft_average. they will be placed as the module fieldtrip.py in the mne.io package
2. a copy of pymatreader will go to mne.externals.pymatreader as a package
3. unittests for fieldtrip2mne will go to the tests package in the mne.io package
4. necessary testdata (~14MB) will go the the respective data folder.

is that ok?

should i include the unittests for pymatreader as well? if yes, where should i put those (including testdata?)

[robertoostenveld]

in FT we don't have the epoched structure as such, so could you avoid using "epoched" for the FT structure? We have raw and timelock. Raw can be continuous or epoched (with trials that are not per see aligned) and timelock can be averaged or epoched (with trials that are per construct aligned in time). The difference between aligned and non-aligned epochs is relevant here, as is the difference between same length and different length segments. See http://www.fieldtriptoolbox.org/tutorial/sleep for an example of non-aligned 30-sec epochs (for sleep staging throughout the whole night).

[agramfort]

@thht please sounds good. Now if function returns an MNE Evoked object (resp Epochs) it should be called read_ft_evoked (resp Epochs).

thanks @robertoostenveld for pitching and sharing this great tutorial.

[agramfort]

@thht regarding tests for pymatreader don't add them if it means increasing the size of our repo with new mat files.

[larsoner]

the fieldtrip2mne reader functions will be renamed to read_ft_raw, read_ft_epoched, read_ft_average. they will be placed as the module fieldtrip.py in the mne.io package

mne.io.read_raw_ft, mne.read_epochs_ft and mne.read_evoked_ft would be consistent with our naming schemes

a copy of pymatreader will go to mne.externals.pymatreader as a package

Sure. This might be done in #4874, we'll have to see who gets there first :)

should i include the unittests for pymatreader as well?

No, these should be left in the upstream repository.

necessary testdata (~14MB) will go the the respective data folder.

This should be added to the mne-testing-data repo

[stfnrpplngr]

Hi, I added some lines to the ft_definetrial function (to import epoched data coming from mne into fieldtrip without losing event codes, fieldtrip/fieldtrip#755) and updated the documentation on the fieldtip page regarding mne-fieldtrip integration (http://www.fieldtriptoolbox.org/development/integrate_with_mne). Maybe good to know.

[agramfort]

thanks !

[agramfort]

@thht can you put tick boxes in issue description with things that already work and what is still todo?

[thht]

yes, will do. sorry for the inactivity. i just came back from paternity leave today and am catching up.

[thht]

@agramfort done

[thht]

the PR is merged. what is "missing" is importing source, freq and tfr data. but frankly, i do not have time to work on that in the near future. so i would like to close the issue.

@agramfort is that ok with you?

[larsoner]

Easier to ask forgiveness than permission :)