automatic methods section

[jasmainak]

It would be helpful if one could use mne-bids to write out a basic methods section paragraph based on the sidecars and an editable template. Something along the lines of:

>>> template = """
Data was acquired using a {{system}} system ({{manufacturer}}) consisting 
of {{n_grad}} gradiometer channels and {{n_mag}} magnetometer channels. 
Blah, blah ... We had {{n_subjects}} subjects amongst whom there were 
{{n_males}} males and {{n_females}} females.
"""

>>> from mne_bids.report import create_methods_paragraph
>>> para = create_methods_paragraph(bids_root, template)
>>> print(para)

It could be inspired by whatever COBIDAS recommends. Pybids has something similar in their report module but I haven't looked very closely. In any case, something that is MEG/EEG specific would be needed and it would help people avoid mistakes in the methods section.

[adam2392]

Potentially this would have to be split up among modality-agnostic and modality-specific functions?

[jasmainak]

yes perhaps!

[adam2392]

@jasmainak

I need to write a summary of my dataset for a paper soon, so I might be willing to tackle this.

A few questions though for discussion:

1. Should we just print it out? If so, is there a way to render it pretty? Not sure here.

2. Should we save/append the output to the README file of the bids_root? Makes sense to me cuz then ppl can c/p it.

3. For the template you suggested: I think we can go one step further and provide the mean/std of the distribution of gender, age, handedness (at the minimum) since those are included in the participants file. In addition, we can summarizee the number of 'n/a's.

[jasmainak]

let's try to get some more opinions, cc @agramfort @alexrockhill @hoechenberger @sappelhoff

some specific responses below:

For the template you suggested: I think we can go one step further and provide the mean/std of the distribution of gender, age, handedness (at the minimum) since those are included in the participants file.

perhaps we should first focus on attributes that are MUST rather than RECOMMENDED. Is handedness always present in a participants file?

Should we just print it out? If so, is there a way to render it pretty? Not sure here.

I would just try a simple print first and then iterate

Should we save/append the output to the README file of the bids_root? Makes sense to me cuz then ppl can c/p it.

not sure about this. Maybe look at some "human READMEs" and see what information occurs frequently.

[hoechenberger]

3. provide the mean/std of the distribution of gender

I like the idea of a mean gender 😅 Once we can put this into a neuroscientific paper (and get it published), the world will certainly be a more liberal place ☺️

[alexrockhill]

+1 @jasmainak focusing on methods musts with maybe a verbose that adds recommended (maybe in a later iteration). I would maybe look at many existing published MEG/EEG methods sections that are as diverse as possible and try to cull from them a minimum acceptable methods paragraph and optionally a more detailed verbose=True section. I think step one is to compile these methods sections from different countries and with MEG, EEG and iEEG to replace the blah blah blah with a bit more exact idea of what's supposed to go in that paragraph ;)

Also PS w/r/t @hoechenberger 's comment: I believe the current default is still biological sex for the participants.tsv file and not gender identity. We often ask for both but usually only report gender unless it's relevant to the science as sex is more likely to be information that may be preferred to be private and usually not relevant to disclosing on a paper about frequency modulations in some task but that's just my opinion.

[sappelhoff]

perhaps we should first focus on attributes that are MUST rather than RECOMMENDED.

+1

is handedness always present in a participants file?

no

I would maybe look at many existing published MEG/EEG methods sections that are as diverse as possible and try to cull from them a minimum acceptable methods paragraph

this sounds good to me as well :+1:

[sappelhoff]

another note: perhaps we can also use this somehow to remind users that they can (please) cite MNE-BIDS as well. --> because even for willing users it's easy to forget as @ezemikulan and I recently noticed :wink:

what I found in this regard: https://github.com/duecredit/duecredit --> seems interesting, pybids is using it: https://github.com/bids-standard/pybids/blob/master/bids/due.py

I am not saying that we should use it though. Just a FYI.

[jasmainak]

in the README of the dataset that we write, don't we say somewhere that it's created by MNE-BIDS?

[alexrockhill]

I think we don't write a README at all, but mne-bids is added as an author in dataset_description.json

[adam2392]

another note: perhaps we can also use this somehow to remind users that they can (please) cite MNE-BIDS as well. --> because even for willing users it's easy to forget as @ezemikulan and I recently noticed 😉

what I found in this regard: https://github.com/duecredit/duecredit --> seems interesting, pybids is using it: https://github.com/bids-standard/pybids/blob/master/bids/due.py

I am not saying that we should use it though. Just a FYI.

Why not just import pybids to setup the prelim report? And we can append?

In addition, the more I look at this, the more I wonder if there is a way to make essentially a tree-like data structure for easy parsing at every level of the bids root? / Can this be user-facing as well? To get to the template that @jasmainak suggested seems hard w/o doing a tree-like query to get every sidecar and summarize the set of sidecars for a modality.

[jasmainak]

Why not just import pybids to setup the prelim report? And we can append?

can you see what their report gives for an example dataset? Such as ds000117

In addition, the more I look at this, the more I wonder if there is a way to make essentially a tree-like data structure for easy parsing at every level of the bids root? / Can this be user-facing as well? To get to the template that @jasmainak suggested seems hard w/o doing a tree-like query to get every sidecar and summarize the set of sidecars for a modality.

@adam2392 could you not just grep for all the files with a .json extension?

[adam2392]

@adam2392 could you not just grep for all the files with a .json extension?

I feel like this would get unwieldy as you need to match by certain BIDS entities?

[jasmainak]

maybe, but I would start with a simple solution and iteratively add complexity if needed

[adam2392]

For iEEG formed from the 'convert_ieeg_to_bids' example

import mne
    # get MNE directory w/ example data
    mne_data_dir = mne.get_config('MNE_DATASETS_MISC_PATH')

    # There is the root directory for where we will write our data.
    bids_root = os.path.join(mne_data_dir, 'ieegmmidb_bids')

    layout = bids.BIDSLayout(bids_root, validate=False)

    report = BIDSReport(layout)

    counter = report.generate()
    print(layout)
    print(counter)
    main_report = counter.most_common()[0][0]
    print(main_report)

>

Traceback (most recent call last):
  File "/Users/adam2392/Documents/mne-bids/mne_bids/report.py", line 123, in <module>
    counter = report.generate()
  File "/Users/adam2392/miniconda3/envs/mne/lib/python3.6/site-packages/bids/reports/report.py", line 92, in generate
    descriptions.append(self._report_subject(subject=sid, **kwargs))
  File "/Users/adam2392/miniconda3/envs/mne/lib/python3.6/site-packages/bids/reports/report.py", line 141, in _report_subject
    raise Exception('No niftis for subject {0}'.format(subject))
Exception: No niftis for subject 001

For the ds00017 dataset, if you substitute that for bids_root:

Traceback (most recent call last):
  File "/Users/adam2392/Documents/mne-bids/mne_bids/report.py", line 127, in <module>
    main_report = counter.most_common()[0][0]
IndexError: list index out of range
Number of patterns detected: 0
Remember to double-check everything and to replace <deg> with a degree symbol.
BIDS Layout: ...392/mne_data/mne_bids_examples | Subjects: 0 | Sessions: 0 | Runs: 0
Counter()

[jasmainak]

I don't know what's going one :-) make a PR with what you have, we'll comment ;-)

[adam2392]

I don't know what's going one :-) make a PR with what you have, we'll comment ;-)

Oh sorry, basically saying that pybids doesn't work because 1) ds0017 dataset isn't formatted correctly (I think) and 2) non-nifti type datasets aren't supported (i.e ieeg), or idk how to make it work...

[jasmainak]

yes, exactly so we need a report that specific to electrophysiology.

what's going on with ds000117? Does it pass the validator?

[sappelhoff]

yes, ieeg is not supported in pybids yet, I think: https://github.com/bids-standard/pybids/issues/583

[hoechenberger]

We have that now, of course it still needs some work but I think this issue has been resolved.