[MRG] Simplify raw_to_bids

doc/api.rst

@@ -13,7 +13,17 @@ MNE BIDS (:py:mod:`mne_bids.mne_bids`):
 .. autosummary::
    :toctree: generated/
 
-   raw_to_bids
+   write_raw_bids
+   make_bids_filename
+
+IO (:py:mod:`mne_bids.io`):
+
+.. current_module:: mne_bids.io
+
+.. autosummary::
+   :toctree: generated/
+
+   read_raw
 
 Utils (:py:mod:`mne_bids.utils`):
 
@@ -24,7 +34,6 @@ Utils (:py:mod:`mne_bids.utils`):
 
    print_dir_tree
    make_bids_folders
-   make_bids_filename
    make_dataset_description
    copyfile_brainvision
 

doc/index.rst

@@ -13,21 +13,36 @@ Installation
 
 We recommend the `Anaconda Python distribution <https://www.continuum.io/downloads>`_. To install ``mne_bids``, you first need to install its dependencies::
 
-	$ pip install pandas mne
+    $ pip install pandas mne
 
 Then install mne_bids::
 
-	$ pip install git+https://github.com/mne-tools/mne-bids.git#egg=mne-bids
+    $ pip install git+https://github.com/mne-tools/mne-bids.git#egg=mne-bids
 
 If you do not have admin privileges on the computer, use the ``--user`` flag
 with `pip`. To upgrade, use the ``--upgrade`` flag provided by `pip`.
 
 To check if everything worked fine, you can do::
 
-	$ python -c 'import mne_bids'
+    $ python -c 'import mne_bids'
 
 and it should not give any error messages.
 
+Quickstart
+==========
+
+Currently, we support writing of BIDS datasets for MEG and EEG. Support for
+iEEG is experimental at the moment.
+
+.. code:: python
+
+    >>> from mne_bids import read_raw, write_raw_bids
+    >>> raw = read_raw('my_old_file.fif')
+    >>> write_raw_bids(raw, 'sub-01_ses-01_run-05_meg.fif',
+                       output_path='./bids_dataset')
+
+Reading of BIDS data will also be supported in the next version.
+
 Bug reports
 ===========
 

examples/convert_eeg_to_bids.py

@@ -26,7 +26,7 @@
 from mne.datasets import eegbci
 from mne.io import read_raw_edf
 
-from mne_bids import raw_to_bids
+from mne_bids import write_raw_bids, make_bids_filename
 from mne_bids.utils import print_dir_tree
 
 ###############################################################################
@@ -104,7 +104,7 @@
 # * output_path
 #
 # ... as you can see in the docstring:
-print(raw_to_bids.__doc__)
+print(write_raw_bids.__doc__)
 
 ###############################################################################
 # We loaded 'S001R02.edf', which corresponds to subject 1 in the second task.
@@ -117,18 +117,15 @@
 ###############################################################################
 # Now we just need to specify a few more EEG details to get something sensible:
 
-# First, tell `MNE-BIDS` that it is working with EEG data:
-kind = 'eeg'
-
 # Brief description of the event markers present in the data. This will become
 # the `trial_type` column in our BIDS `events.tsv`. We know about the event
 # meaning from the documentation on PhysioBank
 trial_type = {'rest': 0, 'imagine left fist': 1, 'imagine right fist': 2}
 
 # Now convert our data to be in a new BIDS dataset.
-raw_to_bids(subject_id=subject_id, task=task, raw_file=raw_file,
-            output_path=output_path, kind=kind, event_id=trial_type,
-            overwrite=False)
+bids_fname = make_bids_filename(subject=subject_id, task=task,
+                                suffix='eeg.edf')
+write_raw_bids(raw_file, bids_fname, output_path, event_id=trial_type)
 
 ###############################################################################
 # What does our fresh BIDS directory look like?
@@ -159,17 +156,11 @@
                                 'S{:03}'.format(subj_idx),
                                 'S{:03}R{:02}.edf'.format(subj_idx, task_idx))
         raw = read_raw_edf(edf_path, preload=True)
-
-        # `kind` and `trial_type` were already defined above
-        raw_to_bids(subject_id='{:03}'.format(subj_idx),
-                    task=task_names[task_idx],
-                    run=run_mapping[task_idx],
-                    raw_file=raw,
-                    output_path=output_path,
-                    kind=kind,
-                    event_id=trial_type,
-                    overwrite=True
-                    )
+        bids_fname = make_bids_filename(
+            subject='{:03}'.format(subj_idx), task=task_names[task_idx],
+            run=run_mapping[task_idx], suffix='eeg.edf')
+        write_raw_bids(raw, bids_fname, output_path, event_id=trial_type,
+                       overwrite=True)
 
 ###############################################################################
 # Step 3: Check and compare with standard
@@ -183,8 +174,9 @@
 # initial `dataset_description` on top!
 #
 # Now it's time to manually check the BIDS directory and the meta files to add
-# all the information that MNE-BIDS could not infer. These places are marked
-# with "n/a".
+# all the information that MNE-BIDS could not infer. For instance, you must
+# describe EEGReference and EEGGround yourself. It's easy to find these by
+# searching for "n/a" in the sidecar files.
 #
 # Remember that there is a convenient javascript tool to validate all your BIDS
 # directories called the "BIDS-validator", available as a web version and a

examples/convert_group_studies.py

@@ -24,7 +24,9 @@
 # Let us import ``mne_bids``
 
 import os.path as op
-from mne_bids import raw_to_bids
+
+from mne_bids import write_raw_bids, make_bids_filename
+from mne_bids.io import read_raw
 from mne_bids.datasets import fetch_faces_data
 from mne_bids.utils import print_dir_tree
 
@@ -63,13 +65,15 @@
 for subject_id in subject_ids:
     subject = 'sub%03d' % subject_id
     for run in runs:
-        raw_file = op.join(data_path, repo, subject, 'MEG',
-                           'run_%02d_raw.fif' % run)
-
-        # Make it BIDS compatible
-        raw_to_bids(subject_id='%02d' % subject_id, session_id='01', run=run,
-                    task='VisualFaces', raw_file=raw_file, event_id=event_id,
-                    output_path=output_path, overwrite=True)
+        raw_fname = op.join(data_path, repo, subject, 'MEG',
+                            'run_%02d_raw.fif' % run)
+
+        raw = read_raw(raw_fname)
+        bids_fname = make_bids_filename(subject='%02d' % subject_id, run=run,
+                                        session='01', task='VisualFaces',
+                                        suffix='meg.fif')
+        write_raw_bids(raw, bids_fname, output_path, event_id=event_id,
+                       overwrite=True)
 
 ###############################################################################
 # Now let's see the structure of the BIDS folder we created.

examples/convert_mne_sample.py

@@ -18,7 +18,8 @@
 
 import os.path as op
 from mne.datasets import sample
-from mne_bids import raw_to_bids
+from mne_bids import write_raw_bids, make_bids_filename
+from mne_bids.io import read_raw
 from mne_bids.utils import print_dir_tree
 
 ###############################################################################
@@ -28,17 +29,18 @@
 event_id = {'Auditory/Left': 1, 'Auditory/Right': 2, 'Visual/Left': 3,
             'Visual/Right': 4, 'Smiley': 5, 'Button': 32}
 
-raw_file = op.join(data_path, 'MEG', 'sample', 'sample_audvis_raw.fif')
+raw_fname = op.join(data_path, 'MEG', 'sample', 'sample_audvis_raw.fif')
 events_data = op.join(data_path, 'MEG', 'sample', 'sample_audvis_raw-eve.fif')
 output_path = op.join(data_path, '..', 'MNE-sample-data-bids')
 
 ###############################################################################
 # Finally, we specify the raw_file and events_data
 
-raw_to_bids(subject_id='01', run='01', session_id='01', task='audiovisual',
-            raw_file=raw_file, events_data=events_data,
-            output_path=output_path, event_id=event_id,
-            overwrite=False)
+raw = read_raw(raw_fname)
+bids_fname = make_bids_filename(subject='01', run='01', session='01',
+                                task='audiovisual', suffix='meg.fif')
+write_raw_bids(raw, bids_fname, output_path, events_data=events_data,
+               event_id=event_id, overwrite=True)
 
 ###############################################################################
 # Now let's see the structure of the BIDS folder we created.

mne_bids/__init__.py

@@ -3,6 +3,6 @@
 __version__ = '0.1.dev0'
 
 
-from .mne_bids import raw_to_bids  # noqa
+from .mne_bids import write_raw_bids  # noqa
 from .utils import make_bids_folders, make_bids_filename  # noqa
 from .config import BIDS_VERSION  # noqa

mne_bids/commands/mne_bids_raw_to_bids.py

@@ -4,11 +4,12 @@
 """Command line interface for mne_bids.
 
 example usage:  $ mne_bids raw_to_bids --subject_id sub01 --task rest
---raw_file data.edf --output_path new_path
+--raw_fname data.edf --output_path new_path
 
 """
-
-from mne_bids import raw_to_bids
+import os
+from mne_bids import write_raw_bids, make_bids_filename
+from mne_bids.io import read_raw
 
 
 def run():
@@ -24,7 +25,7 @@ def run():
     parser.add_option('--task', dest='task',
                       help='Name of the task the data is based on.',
                       metavar='t')
-    parser.add_option('--raw_file', dest='raw_file',
+    parser.add_option('--raw_fname', dest='raw_fname',
                       help='The path to the raw MEG file.', metavar='r')
     parser.add_option('--output_path', dest='output_path',
                       help='The path of the BIDS compatible folder.',
@@ -35,6 +36,9 @@ def run():
     parser.add_option('--run', dest='run',
                       help='The run number for this dataset.',
                       metavar='run')
+    parser.add_option('--acq', dest='acq',
+                      help='The acquisition parameter.',
+                      metavar='acq')
     parser.add_option('--kind', dest='kind',
                       help='The kind of data being converted.',
                       metavar='k')
@@ -58,13 +62,15 @@ def run():
 
     opt, args = parser.parse_args()
 
-    raw_to_bids(subject_id=opt.subject_id, task=opt.task,
-                raw_file=opt.raw_file, output_path=opt.output_path,
-                session_id=opt.session_id, run=opt.run, kind=opt.kind,
-                events_data=opt.events_data, event_id=opt.event_id,
-                hpi=opt.hpi, electrode=opt.electrode, hsp=opt.hsp,
-                config=opt.config, overwrite=opt.overwrite,
-                verbose=True)
+    suffix = '%s%s' % (opt.kind, os.path.splitext(opt.raw_fname)[1])
+    bids_fname = make_bids_filename(
+        subject=opt.subject_id, session=opt.session_id, run=opt.run,
+        acquisition=opt.acq, task=opt.task, suffix=suffix)
+    raw = read_raw(opt.raw_fname, hpi=opt.hpi, electrode=opt.electrode,
+                   hsp=opt.hsp, config=opt.config)
+    write_raw_bids(raw, bids_fname, opt.output_path, event_id=opt.event_id,
+                   events_data=opt.events_data, overwrite=opt.overwrite,
+                   verbose=True)
 
 
 is_main = (__name__ == '__main__')

mne_bids/io.py

@@ -32,15 +32,19 @@ def _parse_ext(raw_fname, verbose=False):
     return fname, ext
 
 
-def _read_raw(raw_fname, electrode=None, hsp=None, hpi=None, config=None,
-              montage=None, verbose=None):
+def read_raw(raw_fname, electrode=None, hsp=None, hpi=None, config=None,
+             montage=None, verbose=None):
     """Read a raw file into MNE, making inferences based on extension."""
     fname, ext = _parse_ext(raw_fname)
 
     # MEG File Types
     # --------------
     # KIT systems
     if ext in ['.con', '.sqd']:
+        if isinstance(hpi, list):
+            # No currently accepted way to name multiple marker files. See:
+            # https://github.com/bids-standard/bids-specification/issues/45
+            raise ValueError('Only single marker coils supported currently')
         raw = io.read_raw_kit(raw_fname, elp=electrode, hsp=hsp,
                               mrk=hpi, preload=False)