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/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. diff --git a/mne_bids/utils.py b/mne_bids/utils.py index fe3ad5738..769725909 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,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,