[MRG] Simplify raw_to_bids

.circleci/config.yml

@@ -20,7 +20,7 @@ jobs:
                   source activate testenv
                   conda install --yes --quiet numpy=1.13.1 scipy=0.19.1 matplotlib pandas=0.20.3
                   pip install sphinx numpydoc sphinx-gallery sphinx_bootstrap_theme pillow
-                  pip install mne
+                  pip install -U https://api.github.com/repos/mne-tools/mne-python/zipball/master
                   python setup.py develop
             - run:
                 name: Build the documentation

.travis.yml

@@ -18,7 +18,7 @@ install:
     - conda install --yes --quiet numpy=1.13.1 scipy=0.19.1 matplotlib pandas=0.20.3
     - pip install flake8 pytest pytest-sugar pytest-faulthandler
     - |
-      git clone --depth 1 https://github.com/mne-tools/mne-python.git --branch maint/0.16
+      git clone --depth 1 https://github.com/mne-tools/mne-python.git
       cd mne-python
       pip install --no-deps -e .
       cd ../

README.md

@@ -18,7 +18,8 @@ Next to `numpy`, `scipy`, and `matplotlib` that are included in the standard
 anaconda distribution, you will need to install the following dependencies
 to be able to use `mne_bids`:
 
-    $ pip install pandas mne
+    $ pip install pandas
+    $ pip install -U https://api.github.com/repos/mne-tools/mne-python/zipball/master
 
 Then install `mne_bids`:
 

appveyor.yml

@@ -19,7 +19,7 @@ install:
   - "pip uninstall -yq mne"
   - |-
     cd ..
-    git clone --depth 1 https://github.com/mne-tools/mne-python.git --branch maint/0.16
+    git clone --depth 1 https://github.com/mne-tools/mne-python.git
     cd mne-python
     python setup.py develop
     cd ..

doc/api.rst

@@ -13,7 +13,9 @@ MNE BIDS (:py:mod:`mne_bids.mne_bids`):
 .. autosummary::
    :toctree: generated/
 
-   raw_to_bids
+   write_raw_bids
+   make_bids_basename
+   make_bids_folders
 
 Utils (:py:mod:`mne_bids.utils`):
 
@@ -23,10 +25,9 @@ Utils (:py:mod:`mne_bids.utils`):
    :toctree: generated/
 
    print_dir_tree
-   make_bids_folders
-   make_bids_filename
    make_dataset_description
    copyfile_brainvision
+   copyfile_eeglab
 
 Datasets (:py:mod:`mne_bids.datasets`):
 

doc/index.rst

@@ -13,21 +13,37 @@ 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
+    $ pip install -U https://api.github.com/repos/mne-tools/mne-python/zipball/master
 
 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 import io
+    >>> from mne_bids import write_raw_bids
+    >>> raw = io.read_raw_fif('my_old_file.fif')
+    >>> write_raw_bids(raw, 'sub-01_ses-01_run-05', output_path='./bids_dataset')
+
+Reading of BIDS data will also be supported in the next version.
+
 Bug reports
 ===========
 

examples/convert_eeg_to_bids.py

@@ -23,10 +23,11 @@
 import os
 import shutil as sh
 
+import mne
 from mne.datasets import eegbci
-from mne.io import read_raw_edf
+from mne.io.edf.edf import read_annotations_edf
 
-from mne_bids import raw_to_bids
+from mne_bids import write_raw_bids, make_bids_basename
 from mne_bids.utils import print_dir_tree
 
 ###############################################################################
@@ -84,27 +85,35 @@
 # --------------------------
 #
 # Let's start by formatting a single subject. We are reading the data using
-# MNE-Python's io module and the `read_raw_edf` function.
-data_dir = os.path.join(data_dir, 'physiobank', 'database', 'eegmmidb')
-edf_path = os.path.join(data_dir, 'S001', 'S001R02.edf')
-raw = read_raw_edf(edf_path, preload=True)
+# MNE-Python's io module and the `read_raw_edf` function. Note that we must
+# use `preload=False`, the default in MNE-Python. It prevents the data from
+# being loaded and modified when converting to BIDS.
+edf_path = eegbci.load_data(subject=1, runs=2)[0]
+raw = mne.io.read_raw_edf(edf_path, preload=False, stim_channel=None)
+
+###############################################################################
+# The annotations stored in the file must be read in separately and converted
+# into a 2D numpy array of events that is compatible with MNE.
+annot = read_annotations_edf(edf_path)
+raw.set_annotations(annot)
+events, event_id = mne.events_from_annotations(raw)
+
 print(raw)
 
 ###############################################################################
-# With this simple step we have everything to start a new BIDS directory using
-# our data. To do that, we can use the high level function `raw_to_bids`, which
-# is the core of MNE-BIDS. Generally, `raw_to_bids` tries to extract as much
+# With this step, we have everything to start a new BIDS directory using
+# our data. To do that, we can use the function `write_raw_bids`
+# Generally, `write_raw_bids` tries to extract as much
 # meta data as possible from the raw data and then formats it in a BIDS
-# compatible way. `raw_to_bids` takes a bunch of inputs, most of which are
+# compatible way. `write_raw_bids` takes a bunch of inputs, most of which are
 # however optional. The required inputs are:
 #
-# * subject_id
-# * task
-# * raw_file
+# * raw
+# * bids_basename
 # * 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,19 +126,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_basename = make_bids_basename(subject=subject_id, task=task)
+write_raw_bids(raw_file, bids_basename, output_path, event_id=trial_type,
+               events_data=events, overwrite=True)
 ###############################################################################
 # What does our fresh BIDS directory look like?
 print_dir_tree(output_path)
@@ -155,21 +160,18 @@
 for subj_idx in [1, 2]:
     for task_idx in [2, 4, 12]:
         # Load the data
-        edf_path = os.path.join(data_dir,
-                                '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
-                    )
+        edf_path = eegbci.load_data(subject=subj_idx, runs=task_idx)[0]
+
+        raw = mne.io.read_raw_edf(edf_path, preload=False, stim_channel=None)
+        annot = read_annotations_edf(edf_path)
+        raw.set_annotations(annot)
+        events, event_id = mne.events_from_annotations(raw)
+
+        make_bids_basename(
+            subject='{:03}'.format(subj_idx), task=task_names[task_idx],
+            run=run_mapping[task_idx])
+        write_raw_bids(raw, bids_basename, output_path, event_id=trial_type,
+                       events_data=events, overwrite=True)
 
 ###############################################################################
 # Step 3: Check and compare with standard
@@ -183,8 +185,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
+
+import mne
+from mne_bids import write_raw_bids
 from mne_bids.datasets import fetch_faces_data
 from mne_bids.utils import print_dir_tree
 
@@ -63,13 +65,14 @@
 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 = mne.io.read_raw_fif(raw_fname)
+        bids_basename = ('sub-%02d_ses-01_task-VisualFaces_run-%d'
+                         % (subject_id, run))
+        write_raw_bids(raw, bids_basename, 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

@@ -17,8 +17,11 @@
 # Let us import mne_bids
 
 import os.path as op
+
+import mne
 from mne.datasets import sample
-from mne_bids import raw_to_bids
+
+from mne_bids import write_raw_bids
 from mne_bids.utils import print_dir_tree
 
 ###############################################################################
@@ -28,17 +31,17 @@
 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 = mne.io.read_raw_fif(raw_fname)
+bids_basename = 'sub-01_ses-01_task-audiovisual_run-01'
+write_raw_bids(raw, bids_basename, output_path, events_data=events_data,
+               event_id=event_id, overwrite=True)
 
 ###############################################################################
 # Now let's see the structure of the BIDS folder we created.

examples/create_bids_folder.py

@@ -9,8 +9,8 @@
 
 .. note::
 
-   You may automatically convert Raw files to a BIDS-compatible folder with
-   `raw_to_bids`. This example is for manually creating files/folders.
+   You may automatically convert Raw objects to BIDS-compatible files with
+   `write_raw_bids`. This example is for manually creating files/folders.
 """
 
 # Authors: Chris Holdgraf <choldgraf@berkeley.edu>
@@ -19,27 +19,27 @@
 ###############################################################################
 # We'll import the relevant functions from the utils module
 
-from mne_bids import make_bids_folders, make_bids_filename
+from mne_bids import make_bids_folders, make_bids_basename
 
 ###############################################################################
 # Creating file names for BIDS
 # ----------------------------
 #
 # BIDS requires a specific ordering and structure for metadata fields in
-# file paths, the function `filename_bids` allows you to specify many such
+# file paths, the function `make_bids_basename` allows you to specify many such
 # pieces of metadata, ensuring that they are in the correct order in the
 # final file path. Omitted keys will not be included in the file path.
 
-my_name = make_bids_filename(subject='test', session='two', task='mytask',
-                             suffix='data.csv')
-print(my_name)
+bids_basename = make_bids_basename(subject='test', session='two',
+                                   task='mytask', suffix='data.csv')
+print(bids_basename)
 
 ###############################################################################
 # You may also omit the suffix, which will result in *only* a prefix for a
 # file name. This could then prepended to many more files.
 
-my_name = make_bids_filename(subject='test', task='mytask')
-print(my_name)
+bids_basename = make_bids_basename(subject='test', task='mytask')
+print(bids_basename)
 
 ###############################################################################
 # Creating folders
@@ -48,7 +48,7 @@
 # You can also use MNE-BIDS to create folder hierarchies.
 
 path_folder = make_bids_folders('sub_01', session='mysession',
-                                kind='meg', root='path/to/project',
+                                kind='meg', output_path='path/to/project',
                                 make_dir=False)
 print(path_folder)
 

mne_bids/__init__.py

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