REL: v0.8

mne-tools · Jul 15, 2021 · b7abcee · b7abcee
1 parent 0db039f
commit b7abcee
Show file tree

Hide file tree

Showing 20 changed files with 115 additions and 119 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -55,7 +55,7 @@ jobs:
   docs-deploy:
     # will only be run on main branch
     docker:
-      - image: node:8
+      - image: cimg/node:lts
     steps:
       - checkout
 
@@ -64,8 +64,10 @@ jobs:
 
       - run:
           name: Install and configure dependencies
+          # do not update gh-pages above 3.0.0
+          # see: https://github.com/tschaub/gh-pages/issues/354
           command: |
-            npm install --global gh-pages@3.0
+            npm install gh-pages@3.0.0
             git config --global user.email "circle@mne.com"
             git config --global user.name "Circle Ci"
 
@@ -76,7 +78,7 @@ jobs:
       - run:
           # push built docs into the `dev` directory on the `gh-pages` branch
           name: Deploy docs to gh-pages branch
-          command: gh-pages --dotfiles --message "doc updates [skip ci]" --dist doc/_build/html --dest ./dev
+          command: node_modules/gh-pages/bin/gh-pages.js --dotfiles --message "doc updates [skip ci]" --dist doc/_build/html --dest ./dev
 
 
   link-check:

diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml
@@ -45,7 +45,7 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest]
-        python-version: [3.6, 3.7, 3.8, 3.9]
+        python-version: [3.7, 3.8, 3.9]
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python ${{ matrix.python-version }}

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -12,12 +12,14 @@ installation as shown below.
 ## Running tests
 
 ### (Optional) Install development version of MNE-Python
+
 If you want to run the tests with a development version of MNE-Python,
 you can install it by running
 
     $ pip install -U https://github.com/mne-tools/mne-python/archive/main.zip
 
 ### Install development version of MNE-BIDS
+
 First, you should [fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) the `mne-bids` repository. Then, clone the fork and install it in
 "editable" mode.
 
@@ -26,12 +28,14 @@ First, you should [fork](https://help.github.com/en/github/getting-started-with-
 
 
 ### Install Python packages required to run tests
-Install the following packages for testing purposes, plus all optonal MNE-BIDS
-dependencies to ensure you will be able to run all tests.
 
-    $ pip install flake8 pytest pytest-cov scikit-learn nibabel nilearn pybv
+You can install the testing requirements using the `test_requirements.txt` file
+from the root of the mne-bids repository.
+
+    $ pip install -r test_requirements.txt
 
 ### Install the BIDS validator
+
 Finally, it is necessary to install the
 [BIDS validator](https://github.com/bids-standard/bids-validator). The outputs
 of MNE-BIDS are run through the BIDS validator to check if the conversion
@@ -40,6 +44,7 @@ worked properly and produced datasets that conforms to the BIDS specifications.
 You will need the `command line version` of the validator.
 
 #### Global (system-wide) installation
+
 - First, install [Node.js](https://nodejs.org/en/).
 - For installing the **stable** version of `bids-validator`, please follow the
 instructions as detailed in the README of the bids-validator repository.
@@ -59,18 +64,18 @@ Then, retrieve the validator and install all its dependencies via `npm`.
 
     $ git clone git@github.com:bids-standard bids-validator.git
     $ cd bids-validator/bids-validator
-    $ npm i
+    $ npm install
 
 Test your installation by running:
 
     $ ./bin/bids-validator --version
 
 
 ### Invoke pytest
+
 Now you can finally run the tests by running `pytest` in the
 `mne-bids` directory.
 
-    $ cd mne-bids
     $ pytest
 
 If you have installed the `bids-validator`
@@ -80,18 +85,18 @@ on a per-user basis, set the environment variable `VALIDATOR_EXECUTABLE` to poin
 
 ## Building the documentation
 
-The documentation can be built using sphinx. For that, please additionally
-install the following:
+The documentation can be built using sphinx.
+You can install the documentation requirements using the `requirements.txt` file
+in the `doc/` directory of the mne-bids repository.
 
-    $ pip install matplotlib nilearn sphinx numpydoc sphinx-gallery pydata-sphinx-theme pillow
+    $ pip install -r doc/requirements.txt
 
 To build the documentation locally, one can run:
 
-    $ cd doc/
-    $ make html
+    $ make build-doc
 
-or
+or, if you don't want to run the examples to build the documentation:
 
-    $ make html-noplot
+    $ make -C doc/ html-noplot
 
-if you don't want to run the examples to build the documentation. This will result in a faster build but produce no plots in the examples.
+The latter command will result in a faster build but produce no plots in the examples.
diff --git a/doc/_templates/docs-navbar.html b/doc/_templates/docs-navbar.html
diff --git a/doc/_templates/docs-toc.html b/doc/_templates/docs-toc.html
diff --git a/doc/_templates/navbar.html b/doc/_templates/navbar.html
diff --git a/doc/_templates/version-switcher.html b/doc/_templates/version-switcher.html
@@ -0,0 +1,11 @@
+<div class="dropdown">
+    <button type="button" class="btn btn-{% if (build_dev_html|tobool) %}danger{% else %}primary{% endif %} btn-sm navbar-btn dropdown-toggle" id="dLabelMore" data-toggle="dropdown">
+        v{{ release }}
+        <span class="caret"></span>
+    </button>
+    <div class="dropdown-menu list-group-flush py-0" aria-labelledby="dLabelMore">
+        {%- for ver, txt in versions_dropdown.items() %}
+        <a class="list-group-item list-group-item-action py-1" href="https://mne.tools/mne-bids/{{ ver }}/index.html">{{ txt }}</a>
+        {%- endfor %}
+    </div>
+</div>
diff --git a/doc/authors.rst b/doc/authors.rst
@@ -24,4 +24,7 @@
 .. _Tom Donoghue: https://github.com/TomDonoghue
 .. _Richard Köhler: https://github.com/richardkoehler
 .. _Sin Kim: https://github.com/AKSoo
-.. _Jean-Rémi King: https://kingjr.github.io/
+.. _Jean-Rémi King: https://kingjr.github.io
+.. _Julia Guiomar Niso Galán: https://github.com/guiomar
+.. _Eric Larson: https://github.com/rob-luke
+.. _Clemens Brunner: https://github.com/cbrnr
diff --git a/doc/conf.py b/doc/conf.py
@@ -127,12 +127,14 @@
     'use_edit_page_button': False,
     'navigation_with_keys': False,
     'show_toc_level': 1,
+    'navbar_end': ['version-switcher', 'navbar-icon-links'],
 }
 
 html_context = {
     'versions_dropdown': {
-        'dev': 'v0.8 (devel)',
-        'stable': 'v0.7 (stable)',
+        'dev': 'v0.9 (devel)',
+        'stable': 'v0.8 (stable)',
+        'v0.7': 'v0.7',
         'v0.6': 'v0.6',
         'v0.5': 'v0.5',
         'v0.4': 'v0.4',

diff --git a/doc/install.rst b/doc/install.rst
@@ -7,15 +7,15 @@ Dependencies
 ------------
 
 * ``mne`` (>=0.21.2)
-* ``numpy`` (>=1.15.4)
-* ``scipy`` (>=1.1.0, or >=1.5.0 for certain operations with EEGLAB data)
+* ``numpy`` (>=1.16.0)
+* ``scipy`` (>=1.2.0, or >=1.5.0 for certain operations with EEGLAB data)
 * ``nibabel`` (>=2.2, optional, for processing MRI data)
 * ``pybv`` (>=0.5, optional, for writing BrainVision data)
-* ``pandas`` (>=0.23.4, optional, for generating event statistics)
-* ``matplotlib`` (optional, for using the interactive data inspector)
+* ``pandas`` (>=0.24.0, optional, for generating event statistics)
+* ``matplotlib`` (>=3.1.0, optional, for using the interactive data inspector)
 
 We recommend the `Anaconda <https://www.anaconda.com/download/>`_ Python
-distribution. We require that you use Python 3.6 or higher.
+distribution. We require that you use Python 3.7 or higher.
 You may choose to install ``mne-bids``
 `via pip <#Installation via pip>`_ or
 `via conda <#Installation via conda>`_.

diff --git a/doc/whats_new.rst b/doc/whats_new.rst
@@ -10,28 +10,51 @@ What's new?
 .. currentmodule:: mne_bids
 .. _changes_0_8:
 
-Version 0.8 (unreleased)
+Version 0.8 (2021-07-15)
 ------------------------
 
-...
+This release brings numerous improvements and fixes based on feedback from our
+users, including those working with very large datasets. MNE-BIDS now handles
+previously-overlooked edge cases, offers a much more efficient way to
+store data on macOS and Linux (using symbolic links), and lays the groundwork
+for supporting BIDS derivatives, i.e., storing modified data.
 
 Notable changes
 ~~~~~~~~~~~~~~~
 
-- ...
+- You can now write preloaded and potentially modified data with
+  :func:`mne_bids.write_raw_bids` by passing ``allow_preload=True``. This is
+  a first step towards supporting derivative files.
+- `mne_bids.BIDSPath` now has property getters and setters for all BIDS
+  entities. What this means is that you can now do things like
+  ``bids_path.subject = '01'`` instead of ``bids_path.update(subject='01')``.
+- We now support Deep Brain Stimulation (DBS) data.
+- The way we handle anatomical landmarks was greatly revamped to ensure we're
+  always using the correct coordinate systems. A new function,
+  `mne_bids.get_anat_landmarks`, helps with extracting fiducial points from
+  anatomical scans.
+- When creating a BIDS dataset from FIFF files on macOS and Linux, MNE-BIDS
+  can now optionally generate symbolic links to the original files instead of
+  copies. Simply pass ``symlink=True`` to
+  :func:`mne_bids.write_raw_bids`. This can massively reduce the storage space
+  requirements.
 
 Authors
 ~~~~~~~
 
-* `Alex Rockhill`_
-* `Richard Höchenberger`_
 * `Adam Li`_
+* `Alex Rockhill`_
+* `Alexandre Gramfort`_
+* `Clemens Brunner`_
 * `Eduard Ort`_
-* `Richard Köhler`_ (new contributor)
+* `Eric Larson`_
 * `Jean-Rémi King`_ (new contributor)
-* `Sin Kim`_ (new contributor)
-* `Alexandre Gramfort`_
+* `Julia Guiomar Niso Galán`_ (new contributor)
 * `Mainak Jas`_
+* `Richard Höchenberger`_
+* `Richard Köhler`_ (new contributor)
+* `Robert Luke`_ (new contributor)
+* `Sin Kim`_ (new contributor)
 * `Stefan Appelhoff`_
 
 Detailed list of changes
@@ -40,7 +63,7 @@ Detailed list of changes
 Enhancements
 ^^^^^^^^^^^^
 
-- The fields "DigitizedLandmarks" and "DigitizedHeadPoints" in the json sidecar of Neuromag data are now set to True/False depending on whether any landmarks (NAS, RPA, LPA) or extra points are found in raw.info['dig'], by `Eduard Ort`_ (:gh:`772`)
+- The fields "DigitizedLandmarks" and "DigitizedHeadPoints" in the json sidecar of Neuromag data are now set to ``true`` or ``false`` depending on whether any landmarks (NAS, RPA, LPA) or extra points are found in ``raw.info['dig']``, by `Eduard Ort`_ (:gh:`772`)
 - Updated the "Read BIDS datasets" example to use data from `OpenNeuro <https://openneuro.org>`_, by `Alex Rockhill`_ (:gh:`753`)
 - :func:`mne_bids.get_head_mri_trans` is now more lenient when looking for the fiducial points (LPA, RPA, and nasion) in the MRI JSON sidecar file, and accepts a larger variety of landmark names (upper- and lowercase letters; ``'nasion'`` instead of only ``'NAS'``), by `Richard Höchenberger`_ (:gh:`769`)
 - :func:`mne_bids.get_head_mri_trans` gained a new keyword argument ``t1_bids_path``, allowing for the MR scan to be stored in a different session or even in a different BIDS dataset than the electrophysiological recording, by `Richard Höchenberger`_ (:gh:`771`)
@@ -51,7 +74,7 @@ Enhancements
 - :func:`mne_bids.write_raw_bids` gained a new parameter ``empty_room`` that allows to specify an associated empty-room recording when writing an MEG data file. This information will be stored in the ``AssociatedEmptyRoom`` field of the MEG JSON sidecar file, by `Richard Höchenberger`_ (:gh:`795`)
 - Added support for the new channel type ``'dbs'`` (Deep Brain Stimulation), which was introduced in MNE-Python 0.23, by `Richard Köhler`_ (:gh:`800`)
 - :func:`mne_bids.read_raw_bids` now warns in many situations when it encounters a mismatch between the channels in ``*_channels.tsv`` and the raw data, by `Richard Höchenberger`_ (:gh:`823`)
-- MNE BIDS now accepts ".mrk" head digitization files used in the KIT/Yokogawa/Ricoh MEG system, by `Jean-Rémi King`_ and `Stefan Appelhoff`_ (:gh:`842`)
+- MNE BIDS now accepts ``.mrk`` head digitization files used in the KIT/Yokogawa/Ricoh MEG system, by `Jean-Rémi King`_ and `Stefan Appelhoff`_ (:gh:`842`)
 
 API and behavior changes
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -71,6 +94,7 @@ Requirements
 
 - For downloading `OpenNeuro <https://openneuro.org>`_ datasets, ``openneuro-py`` is now required to run the examples and build the documentation, by `Alex Rockhill`_ (:gh:`753`)
 - MNE-BIDS now depends on `setuptools <https://setuptools.readthedocs.io>`_. This package is normally installed by your Python distribution automatically, so we don't expect any users to be affected by this change, by `Richard Höchenberger`_ (:gh:`794`)
+- MNE-BIDS now requires Python 3.7 or higher, because Python 3.6 is soon reaching its end of life.
 
 Bug fixes
 ^^^^^^^^^
@@ -84,7 +108,7 @@ Bug fixes
 - :func:`mne_bids.read_raw_bids` crashed when the (optional) ``acq_time`` column was missing in ``*_scans.tsv``, by `Alexandre Gramfort`_ (:gh:`814`)
 - :func:`mne_bids.write_raw_bids` doesn't crash anymore if the designated output directory contains the string ``"tsv"``, by `Richard Höchenberger`_ (:gh:`833`)
 - :func:`mne_bids.get_head_mri_trans` gave incorrect results when the T1 image was not in LIA format, now all formats function properly, by `Alex Rockhill`_ and `Alexandre Gramfort`_ (:gh:`827`)
-- :func:`mne_bids.get_head_mri_trans` and :func:`mne_bids.write_anat` used a T1w image but depended specifically on the freesurfer T1w image. Now the freesurfer subject directory is used, by `Alex Rockhill`_ and `Alexandre Gramfort`_ (:gh:`827`)
+- :func:`mne_bids.get_head_mri_trans` and :func:`mne_bids.write_anat` used a T1w image but depended specifically on the freesurfer T1w image. Now the FreeSurfer subjects directory is used, by `Alex Rockhill`_ and `Alexandre Gramfort`_ (:gh:`827`)
 
 :doc:`Find out what was new in previous releases <whats_new_previous_releases>`