From 81d8afd2f727e0779f42e034f54d3e05bf861979 Mon Sep 17 00:00:00 2001 From: Daniel McCloy Date: Mon, 11 Nov 2024 13:50:53 -0600 Subject: [PATCH] Control example order via explicit list, not via sorting titles (#1321) * remove numbers from all example titles * sort examples via JSON file, not title * nest JSON loading so it isn't attempted on import * clearer docstring * use sphinx-gallery master --------- Co-authored-by: Stefan Appelhoff --- doc/conf.py | 2 +- doc/example_order.json | 16 ++++++++++++++++ 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 +++--- mne_bids/utils.py | 17 +++++++++++++++++ pyproject.toml | 2 +- 18 files changed, 77 insertions(+), 44 deletions(-) create mode 100644 doc/example_order.json diff --git a/doc/conf.py b/doc/conf.py index 84fd53226..e61a693d7 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -185,7 +185,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/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 8d6714799..f6aed26f8 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 b2f71c12b..ebe4c73b1 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. diff --git a/mne_bids/utils.py b/mne_bids/utils.py index 05aac7523..e59777107 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 @@ -519,6 +520,22 @@ def _import_nibabel(why="work with MRI data"): return nibabel +# better example sorting, without relying on numbers in example titles +def _example_sorter(filename): + """Sort MNE-BIDS example filenames in a custom order. + + 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) + + if filename not in EXAMPLE_ORDER: + EXAMPLE_ORDER.append(filename) + return EXAMPLE_ORDER.index(filename) + + def warn( message, category=RuntimeWarning, diff --git a/pyproject.toml b/pyproject.toml index ba6a183d5..c7c01d579 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,7 +57,7 @@ doc = [ "seaborn", "sphinx-copybutton", "sphinx>=7.4.7", - "sphinx_gallery", + "sphinx_gallery @ https://github.com/sphinx-gallery/sphinx-gallery/archive/refs/heads/master.zip", ] # Dependencies for using all mne_bids features full = [