From 593b4ddbc4d6ce45abbbcd40b4eb7b7b85d4044c Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 15 Oct 2024 16:32:11 -0500 Subject: [PATCH 1/5] remove numbers from all example titles --- examples/anonymize_dataset.py | 6 +++--- examples/bidspath.py | 6 +++--- examples/convert_eeg_to_bids.py | 6 +++--- examples/convert_empty_room.py | 6 +++--- examples/convert_group_studies.py | 6 +++--- examples/convert_ieeg_to_bids.py | 6 +++--- examples/convert_mne_sample.py | 6 +++--- examples/convert_mri_and_trans.py | 6 +++--- examples/convert_nirs_to_bids.py | 6 +++--- examples/create_bids_folder.py | 6 +++--- examples/mark_bad_channels.py | 6 +++--- examples/read_bids_datasets.py | 6 +++--- examples/rename_brainvision_files.py | 6 +++--- examples/update_bids_datasets.py | 6 +++--- 14 files changed, 42 insertions(+), 42 deletions(-) diff --git a/examples/anonymize_dataset.py b/examples/anonymize_dataset.py index 132e515db..2c0e9987a 100644 --- a/examples/anonymize_dataset.py +++ b/examples/anonymize_dataset.py @@ -1,7 +1,7 @@ """ -============================== -13. Anonymizing a BIDS dataset -============================== +========================== +Anonymizing a BIDS dataset +========================== Consider the following scenario: diff --git a/examples/bidspath.py b/examples/bidspath.py index 0430e4c72..ce6f87782 100644 --- a/examples/bidspath.py +++ b/examples/bidspath.py @@ -1,9 +1,9 @@ """ .. _bidspath-example: -=============================== -10. An introduction to BIDSPath -=============================== +=========================== +An introduction to BIDSPath +=========================== BIDSPath is MNE-BIDS's working horse when it comes to file and folder operations. Learn here how to use it. diff --git a/examples/convert_eeg_to_bids.py b/examples/convert_eeg_to_bids.py index 1ad26448f..dbf0acdd7 100644 --- a/examples/convert_eeg_to_bids.py +++ b/examples/convert_eeg_to_bids.py @@ -1,7 +1,7 @@ """ -=================================== -04. Convert EEG data to BIDS format -=================================== +=============================== +Convert EEG data to BIDS format +=============================== In this example, we use MNE-BIDS to create a BIDS-compatible directory of EEG data. Specifically, we will follow these steps: diff --git a/examples/convert_empty_room.py b/examples/convert_empty_room.py index 09c496bad..477689e04 100644 --- a/examples/convert_empty_room.py +++ b/examples/convert_empty_room.py @@ -1,9 +1,9 @@ """ .. _ex-convert-empty-room: -==================================== -09. Manually storing empty room data -==================================== +================================ +Manually storing empty room data +================================ This example demonstrates how to store empty room data "manually" in the BIDS format and how to retrieve them. diff --git a/examples/convert_group_studies.py b/examples/convert_group_studies.py index 1b40010fc..24dc4cee8 100644 --- a/examples/convert_group_studies.py +++ b/examples/convert_group_studies.py @@ -1,7 +1,7 @@ """ -===================================== -05. BIDS conversion for group studies -===================================== +================================= +BIDS conversion for group studies +================================= Here, we show how to do BIDS conversion for group studies. We will use the diff --git a/examples/convert_ieeg_to_bids.py b/examples/convert_ieeg_to_bids.py index 74812f627..50cd2eb6f 100644 --- a/examples/convert_ieeg_to_bids.py +++ b/examples/convert_ieeg_to_bids.py @@ -3,9 +3,9 @@ .. currentmodule:: mne_bids -==================================== -08. Convert iEEG data to BIDS format -==================================== +================================ +Convert iEEG data to BIDS format +================================ In this example, we use MNE-BIDS to create a BIDS-compatible directory of iEEG data. Specifically, we will follow these steps: diff --git a/examples/convert_mne_sample.py b/examples/convert_mne_sample.py index 32be750a3..8a3e3ac6a 100644 --- a/examples/convert_mne_sample.py +++ b/examples/convert_mne_sample.py @@ -3,9 +3,9 @@ .. _ex-convert-mne-sample: -========================================== -02. Convert MNE sample data to BIDS format -========================================== +====================================== +Convert MNE sample data to BIDS format +====================================== In this example we will use MNE-BIDS to organize the MNE sample data according to the BIDS standard. diff --git a/examples/convert_mri_and_trans.py b/examples/convert_mri_and_trans.py index 807974d82..07cb6c901 100644 --- a/examples/convert_mri_and_trans.py +++ b/examples/convert_mri_and_trans.py @@ -1,7 +1,7 @@ """ -============================================================================== -07. Save and load T1-weighted MRI scan along with anatomical landmarks in BIDS -============================================================================== +========================================================================== +Save and load T1-weighted MRI scan along with anatomical landmarks in BIDS +========================================================================== When working with MEEG data in the domain of source localization, we usually have to deal with aligning several coordinate systems, such as the coordinate diff --git a/examples/convert_nirs_to_bids.py b/examples/convert_nirs_to_bids.py index 1400169ee..5452b6ada 100644 --- a/examples/convert_nirs_to_bids.py +++ b/examples/convert_nirs_to_bids.py @@ -1,7 +1,7 @@ """ -==================================== -13. Convert NIRS data to BIDS format -==================================== +================================ +Convert NIRS data to BIDS format +================================ In this example, we use MNE-BIDS to create a BIDS-compatible directory of NIRS data. Specifically, we will follow these steps: diff --git a/examples/create_bids_folder.py b/examples/create_bids_folder.py index cdca659f0..b99053de3 100644 --- a/examples/create_bids_folder.py +++ b/examples/create_bids_folder.py @@ -1,7 +1,7 @@ """ -======================================================= -11. Creating BIDS-compatible folder names and filenames -======================================================= +=================================================== +Creating BIDS-compatible folder names and filenames +=================================================== The Brain Imaging Data Structure (BIDS) has standard conventions for file names and folder hierarchy. MNE-BIDS comes with convenience functions if you diff --git a/examples/mark_bad_channels.py b/examples/mark_bad_channels.py index ecc5a7256..39ffee7fe 100644 --- a/examples/mark_bad_channels.py +++ b/examples/mark_bad_channels.py @@ -1,7 +1,7 @@ """ -========================================================= -03. Interactive data inspection and bad channel selection -========================================================= +===================================================== +Interactive data inspection and bad channel selection +===================================================== You can use MNE-BIDS interactively inspect your MEG or (i)EEG data. Problematic channels can be marked as "bad", for example if the connected diff --git a/examples/read_bids_datasets.py b/examples/read_bids_datasets.py index 995c8c661..029ccd816 100644 --- a/examples/read_bids_datasets.py +++ b/examples/read_bids_datasets.py @@ -1,9 +1,9 @@ """ .. _read_bids_datasets-example: -====================== -01. Read BIDS datasets -====================== +================== +Read BIDS datasets +================== When working with electrophysiological data in the BIDS format, an important resource is the `OpenNeuro `_ database. OpenNeuro diff --git a/examples/rename_brainvision_files.py b/examples/rename_brainvision_files.py index a38bd46e2..c86d8682b 100644 --- a/examples/rename_brainvision_files.py +++ b/examples/rename_brainvision_files.py @@ -1,7 +1,7 @@ """ -===================================== -06. Rename BrainVision EEG data files -===================================== +================================= +Rename BrainVision EEG data files +================================= According to the EEG extension to BIDS [1]_, the `BrainVision data format`_ is one of the recommended formats to store EEG data within a BIDS dataset. diff --git a/examples/update_bids_datasets.py b/examples/update_bids_datasets.py index 8a8aed2c5..304fdb4e2 100644 --- a/examples/update_bids_datasets.py +++ b/examples/update_bids_datasets.py @@ -1,7 +1,7 @@ """ -========================== -12. Updating BIDS datasets -========================== +====================== +Updating BIDS datasets +====================== When working with electrophysiological data in the BIDS format, we usually do not have all the metadata stored in the ``Raw`` mne-python object. From 19cb88659e61beed8d8222dbf593841e996d1719 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 15 Oct 2024 16:33:26 -0500 Subject: [PATCH 2/5] sort examples via JSON file, not title --- doc/conf.py | 2 +- doc/example_order.json | 16 ++++++++++++++++ mne_bids/utils.py | 19 +++++++++++++++++++ 3 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 doc/example_order.json diff --git a/doc/conf.py b/doc/conf.py index b16ccd6bf..d5b69a9c6 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -182,7 +182,7 @@ }, "backreferences_dir": "generated", "examples_dirs": "../examples", - "within_subsection_order": "ExampleTitleSortKey", + "within_subsection_order": "mne_bids.utils._example_sorter", "gallery_dirs": "auto_examples", "filename_pattern": "^((?!sgskip).)*$", } diff --git a/doc/example_order.json b/doc/example_order.json new file mode 100644 index 000000000..84e2a9cc8 --- /dev/null +++ b/doc/example_order.json @@ -0,0 +1,16 @@ +[ + "read_bids_datasets.py", + "convert_mne_sample.py", + "mark_bad_channels.py", + "convert_eeg_to_bids.py", + "convert_group_studies.py", + "rename_brainvision_files.py", + "convert_mri_and_trans.py", + "convert_ieeg_to_bids.py", + "convert_nirs_to_bids.py", + "convert_empty_room.py", + "bidspath.py", + "create_bids_folder.py", + "update_bids_datasets.py", + "anonymize_dataset.py" +] diff --git a/mne_bids/utils.py b/mne_bids/utils.py index fe3ad5738..2fbcec20d 100644 --- a/mne_bids/utils.py +++ b/mne_bids/utils.py @@ -8,6 +8,7 @@ import re from datetime import date, datetime, timedelta, timezone from os import path as op +from pathlib import Path import numpy as np from mne import pick_types @@ -518,6 +519,24 @@ def _import_nibabel(why="work with MRI data"): return nibabel +# better example sorting, without relying on numbers in example titles +with open(Path(__file__).parents[1] / "doc" / "example_order.json") as fid: + EXAMPLE_ORDER = json.load(fid) + + +def _example_sorter(filename): + """Sort for MNE-BIDS example filenames in a custom order. + + Examples not explicitly listed in `EXAMPLE_ORDER` above will be sorted at the end. + This is here (instead of in `conf.py`) because it needs to be *importable* for it + to work correctly in Sphinx Gallery / maintain serializability of the sphinx gallery + config dict in `conf.py`. + """ + if filename not in EXAMPLE_ORDER: + EXAMPLE_ORDER.append(filename) + return EXAMPLE_ORDER.index(filename) + + def warn( message, category=RuntimeWarning, From c4928a6f4e8fbfbb41185e0d20ba4042c00d15cf Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 15 Oct 2024 16:48:39 -0500 Subject: [PATCH 3/5] nest JSON loading so it isn't attempted on import --- mne_bids/utils.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/mne_bids/utils.py b/mne_bids/utils.py index 2fbcec20d..ee4a655c1 100644 --- a/mne_bids/utils.py +++ b/mne_bids/utils.py @@ -520,10 +520,6 @@ def _import_nibabel(why="work with MRI data"): # better example sorting, without relying on numbers in example titles -with open(Path(__file__).parents[1] / "doc" / "example_order.json") as fid: - EXAMPLE_ORDER = json.load(fid) - - def _example_sorter(filename): """Sort for MNE-BIDS example filenames in a custom order. @@ -532,6 +528,9 @@ def _example_sorter(filename): to work correctly in Sphinx Gallery / maintain serializability of the sphinx gallery config dict in `conf.py`. """ + with open(Path(__file__).parents[1] / "doc" / "example_order.json") as fid: + EXAMPLE_ORDER = json.load(fid) + if filename not in EXAMPLE_ORDER: EXAMPLE_ORDER.append(filename) return EXAMPLE_ORDER.index(filename) From 26299ff267cb6d3d4ade23f6eab08e628834f9df Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Tue, 15 Oct 2024 16:49:25 -0500 Subject: [PATCH 4/5] clearer docstring --- mne_bids/utils.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/mne_bids/utils.py b/mne_bids/utils.py index ee4a655c1..769725909 100644 --- a/mne_bids/utils.py +++ b/mne_bids/utils.py @@ -521,12 +521,11 @@ def _import_nibabel(why="work with MRI data"): # better example sorting, without relying on numbers in example titles def _example_sorter(filename): - """Sort for MNE-BIDS example filenames in a custom order. + """Sort MNE-BIDS example filenames in a custom order. - Examples not explicitly listed in `EXAMPLE_ORDER` above will be sorted at the end. - This is here (instead of in `conf.py`) because it needs to be *importable* for it - to work correctly in Sphinx Gallery / maintain serializability of the sphinx gallery - config dict in `conf.py`. + Examples not explicitly listed in `EXAMPLE_ORDER` will be sorted at the end. This + function is defined here (instead of in `conf.py`) because it must be *importable* + in order for the sphinx gallery config dict in `conf.py` to remain serializable. """ with open(Path(__file__).parents[1] / "doc" / "example_order.json") as fid: EXAMPLE_ORDER = json.load(fid) From f4af93a76691377508b542e6c16d423d29435a72 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Mon, 11 Nov 2024 10:07:30 +0100 Subject: [PATCH 5/5] use sphinx-gallery master --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 437c29c2b..17f60c4fa 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,7 +64,7 @@ test = ["mne_bids[full]", "pytest >= 8", "pytest-cov", "pytest-sugar", "ruff"] doc = [ "nilearn", "sphinx>=7.4.7", - "sphinx_gallery", + "https://github.com/sphinx-gallery/sphinx-gallery/archive/refs/heads/master.zip", "sphinx-copybutton", "pydata-sphinx-theme", "numpydoc",