Merge remote-tracking branch 'upstream/master' into enh/954

readthedocs.yml

@@ -1,20 +1,36 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
-  apt_packages:
-    - jq
+  os: ubuntu-lts-latest
   tools:
-    python: "3.11"
+    python: latest
   jobs:
+    # The *_create_environment and post_install steps replace RTD's virtual environment
+    # steps with uv, a much faster alternative to virtualenv+pip.
+    pre_create_environment:
+      # Install jq and uv
+      - asdf plugin add jq https://github.com/lsanwick/asdf-jq.git
+      - asdf plugin add uv https://github.com/asdf-community/asdf-uv.git
+      - asdf install jq latest
+      - asdf install uv latest
+      - asdf global jq latest
+      - asdf global uv latest
+      # Turn `python -m virtualenv` into `python -c pass`
+      - truncate --size 0 $( dirname $( uv python find ) )/../lib/python3*/site-packages/virtualenv/__main__.py
+    post_create_environment:
+      - uv venv $READTHEDOCS_VIRTUALENV_PATH
+      # Turn `python -m pip` into `python -c pass`
+      - truncate --size 0 $( ls -d $READTHEDOCS_VIRTUALENV_PATH/lib/python3* )/site-packages/pip.py
+    # post_install replaces the top-level {python: {install: [{requirements: requirements.txt}]}}
+    post_install:
+      # Use a cache dir in the same mount to halve the install time
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH uv pip install --cache-dir $READTHEDOCS_VIRTUALENV_PATH/../../uv_cache -r requirements.txt
+    # Normal pre-build step to inject schema.json into the source directory
+    # so schema.json is hosted alongside the specification documents
     pre_build:
       - bst -v export --output src/schema.json
       - tools/no-bad-schema-paths.sh src/schema.json  # README.md might need fixing
 
 mkdocs:
   configuration: mkdocs.yml
   fail_on_warning: true
-
-python:
-  install:
-    - requirements: requirements.txt

src/derivatives/imaging.md

@@ -229,7 +229,7 @@ vertices) or a combined volume/surface space.
 
 If the segmentation can be generated in different ways,
 for example, following an atlas segmentation,
-the [`seg` entity](../appendices/entities.md#segmentation) MAY be used to
+the [`seg` entity](../appendices/entities.md#seg) MAY be used to
 distinguish the name of the segmentation used.
 
 The following section describes discrete and probabilistic segmentations of
@@ -293,7 +293,7 @@ In this case, the mask suffix MUST be used,
 the [`label` entity](../appendices/entities.md#label) SHOULD be used
 to specify the masked structure
 (see [Common image-derived labels](#common-image-derived-labels)),
-and the [`seg` entity](../appendices/entities.md#segmentation) SHOULD be defined.
+and the [`seg` entity](../appendices/entities.md#seg) SHOULD be defined.
 
 For example:
 

src/modality-specific-files/behavioral-experiments.md

@@ -44,7 +44,7 @@ and a guide for using macros can be found at
 
 In addition to the metadata that is either:
 
--   RECOMMENDED for sidecar JSON files for [tabular data](../common-principles.md#tabular-data), or
+-   RECOMMENDED for sidecar JSON files for [tabular data](../common-principles.md#tabular-files), or
 
 -   REQUIRED for some data that can be found in the `beh` directory
     (for example `SamplingFrequency` and `StartTime` for `*_<physio|stim>.tsv.gz` files),

src/modality-specific-files/electroencephalography.md

@@ -272,7 +272,7 @@ Examples of free-form text for field `description`
 
 ### Example `*_channels.tsv`
 
-See also the corresponding [`electrodes.tsv` example](#example-electrodestsv).
+See also the corresponding [`electrodes.tsv` example](#example-_electrodestsv).
 
 ```Text
 name     type  units  description                     reference     status  status_description
@@ -316,7 +316,7 @@ If electrodes are repositioned, it is RECOMMENDED to use multiple sessions to in
 
 ### Example `*_electrodes.tsv`
 
-See also the corresponding [`electrodes.tsv` example](#example-channelstsv).
+See also the corresponding [`channels.tsv` example](#example-_channelstsv).
 
 ```Text
 name   x        y	       z        type     material

src/modality-specific-files/magnetic-resonance-imaging-data.md

@@ -11,7 +11,7 @@ MRI acquisition parameters are divided into several categories based on
 When adding additional metadata please use the CamelCase version of
 [DICOM ontology terms](https://dicom.nema.org/medical/dicom/current/output/chtml/part16/chapter_d.html)
 whenever possible. See also
-[recommendations on JSON files](../common-principles.md#keyvalue-files-dictionaries).
+[recommendations on JSON files](../common-principles.md#key-value-files-dictionaries).
 
 ### Hardware information
 
@@ -78,7 +78,7 @@ A guide for using macros can be found at
 
 <sup>2</sup>Conveniently, for Siemens data, this value is easily obtained as
 `1 / (BWPPPE * ReconMatrixPE)`, where BWPPPE is the
-"BandwidthPerPixelPhaseEncode" in DICOM Tag 0019, 1028 and ReconMatrixPE is
+"BandwidthPerPixelPhaseEncode" in [DICOM Tag 0019, 1028](https://dicomlookup.com/dicomtags/(0019,1028)) and ReconMatrixPE is
 the size of the actual reconstructed data in the phase direction (which is NOT
 reflected in a single DICOM Tag for all possible aforementioned scan
 manipulations). See
@@ -944,7 +944,7 @@ accompanied by two ancillary files: `*_asl.json` and `*_aslcontext.tsv`.
 
 The `*_aslcontext.tsv` table consists of a single column of labels identifying the
 `volume_type` of each volume in the corresponding `*_asl.nii[.gz]` file.
-Volume types are defined in the following table, based on DICOM Tag 0018, 9257 `ASL Context`.
+Volume types are defined in the following table, based on [DICOM Tag 0018, 9257](https://dicomlookup.com/dicomtags/(0018,9257)) `ASL Context`.
 Note that the volume_types `control` and  `label` within BIDS only serve
 to specify the magnetization state of the blood and thus the ASL subtraction order.
 See the [ASL Appendix](../appendices/arterial-spin-labeling.md#which-image-is-control-and-which-is-label)
@@ -1354,6 +1354,6 @@ See [Using `IntendedFor` metadata](#using-intendedfor-metadata)
 for details on the `IntendedFor` field.
 
 As for other EPI sequences, these field mapping sequences may have any of the
-[in-plane spatial encoding](#in-plane-spatial-encoding) metadata keys.
+[in-plane spatial encoding](#in-and-out-of-plane-spatial-encoding) metadata keys.
 However, please note that `PhaseEncodingDirection` and `TotalReadoutTime` keys
 are REQUIRED for these field mapping sequences.

src/modality-specific-files/magnetoencephalography.md

@@ -187,7 +187,7 @@ A guide for using macros can be found at
 
 #### Specific EEG fields
 
-If recorded with MEG, see [Recording EEG simultaneously with MEG](#recording-eeg-simultaneously-with-meg)
+If recorded with MEG, see [Recording EEG simultaneously with MEG](#recording-ieeg-simultaneously-with-meg)
 SHOULD be present:
 
 <!-- This block generates a metadata table.

src/schema/objects/entities.yaml

@@ -275,7 +275,7 @@ run:
     (only nonnegative integers are allowed as run indices).
 
     If different entities apply,
-    such as a different session indicated by [`ses-<label>`][SPEC_ROOT/appendices/entities.md#ses),
+    such as a different session indicated by [`ses-<label>`](SPEC_ROOT/appendices/entities.md#ses),
     or different acquisition parameters indicated by
     [`acq-<label>`](SPEC_ROOT/appendices/entities.md#acq),
     then `run` is not needed to distinguish the scans and MAY be omitted.