bids-standard · Lestropie · Aug 1, 2019 · Sep 18, 2019 · Sep 18, 2019 · Jul 4, 2019
diff --git a/.github/workflows/changelog_generator.yml b/.github/workflows/changelog_generator.yml
@@ -13,7 +13,7 @@ jobs:
     github_changelog_generator:
         runs-on: ubuntu-latest
         steps:
-        - uses: actions/checkout@v5
+        - uses: actions/checkout@v6
         - name: Set up Ruby
           uses: ruby/setup-ruby@v1
           with:
@@ -52,7 +52,7 @@ jobs:
           run: |
             cat ~/changelog_build/CHANGES.md
         - name: Archive changelog
-          uses: actions/upload-artifact@v4
+          uses: actions/upload-artifact@v5
           with:
             name: changelog_pre_lint
             path: |
@@ -62,14 +62,14 @@ jobs:
         needs: github_changelog_generator
         runs-on: ubuntu-latest
         steps:
-        - uses: actions/checkout@v5
+        - uses: actions/checkout@v6
         - name: Download previously build changelog
-          uses: actions/download-artifact@v5
+          uses: actions/download-artifact@v6
           with:
             name: changelog_pre_lint
             path: ~/changelog_build
         - name: Set up Node
-          uses: actions/setup-node@v4
+          uses: actions/setup-node@v6
           with:
             node-version: 20
         - name: Install remark and extensions
@@ -93,7 +93,7 @@ jobs:
             head -n 25 ~/changelog_build/CHANGES.md
             npx remark ~/changelog_build/CHANGES.md --rc-path ${{ github.workspace }}/.remarkrc --frail --quiet --no-stdout
         - name: Archive linted changelog
-          uses: actions/upload-artifact@v4
+          uses: actions/upload-artifact@v5
           with:
             name: changelog_post_lint
             path: |
@@ -108,9 +108,9 @@ jobs:
         if: contains(github.event.head_commit.message, '[build changelog]')
         runs-on: ubuntu-latest
         steps:
-        - uses: actions/checkout@v5
+        - uses: actions/checkout@v6
         - name: Download previously build changelog
-          uses: actions/download-artifact@v5
+          uses: actions/download-artifact@v6
           with:
             name: changelog_post_lint
             path: ~/changelog_build
@@ -123,7 +123,7 @@ jobs:
             git add ${{ github.workspace }}/src/CHANGES.md
             git commit -m "[DOC] Auto-generated changelog entry"
         - name: Create Pull Request
-          uses: peter-evans/create-pull-request@v7
+          uses: peter-evans/create-pull-request@v8
           with:
             token: ${{ secrets.GITHUB_TOKEN }}
             branch: changelog_generator_update

diff --git a/.github/workflows/publish_schema.yml b/.github/workflows/publish_schema.yml
@@ -28,11 +28,11 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
           filter: "blob:none"
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: 3
       - run: env

diff --git a/.github/workflows/schemacode_ci.yml b/.github/workflows/schemacode_ci.yml
@@ -29,11 +29,11 @@ jobs:
       attestations: write
       id-token: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
       - name: Install the latest version of uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         if: ${{ startsWith(github.ref, 'refs/tags/schema-') }}
       - name: "Build archive on tag"
         run: |
@@ -62,10 +62,10 @@ jobs:
             python-version: 3.13
     name: ${{ matrix.os }} with Python ${{ matrix.python-version }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }} (uv)
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
           activate-environment: true
@@ -74,7 +74,7 @@ jobs:
         run: python -c "import sys; print(sys.version)"
 
       - name: "Fetch packages"
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v6
         with:
           name: Packages
           path: dist
@@ -95,7 +95,7 @@ jobs:
         working-directory: tools/schemacode
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: unit_${{ matrix.os }}_${{ matrix.python-version }}
           path: tools/schemacode/coverage.xml
@@ -112,7 +112,7 @@ jobs:
 
     steps:
       - name: Download packages built by build-and-inspect-python-package
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v6
         with:
           name: Packages
           path: dist
@@ -131,10 +131,10 @@ jobs:
     runs-on: ubuntu-latest
     name: Validate schema
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: Set Up Python environment
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -150,7 +150,7 @@ jobs:
         working-directory: tools/schemacode
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v5
         with:
           name: schema_validation
           path: tools/schemacode/coverage.xml
@@ -162,10 +162,10 @@ jobs:
     needs: [test, validate_schema]
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
 
       - name: Download artifacts
-        uses: actions/download-artifact@v5
+        uses: actions/download-artifact@v6
 
       - name: Upload to CodeCov
         uses: codecov/codecov-action@v5

diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml
@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
       - name: Install dependencies
         run: |
           sudo apt update && sudo apt install -y shellcheck

diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml
@@ -16,15 +16,15 @@ jobs:
   codespell:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - uses: codespell-project/actions-codespell@master
 
   # Markdown formatting
   remark:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: actions/setup-node@v4
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
         with:
           node-version: 22
       - name: Install dependencies
@@ -36,35 +36,35 @@ jobs:
   yamllint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
       - name: Lint yml files in src/schema
         run: uvx yamllint -f standard src/schema/ -c .yamllint.yml
 
   # Python best practices
   python-style:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
       - run: uvx ruff format --diff
       - run: uvx ruff check
 
   # Avoid Latin phrases to improve readability
   latin-phrases:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
       - name: Check for Latin phrases
         run: uv run tools/no-bad-latin.py
 
   # Validate CITATION.cff
   validate_cff:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
       - name: Validate CITATION.cff
         run: uvx cffconvert --validate
       - name: Check for Zenodo compatibility

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -46,6 +46,7 @@ nav:
           - Quantitative MRI: appendices/qmri.md
           - Arterial Spin Labeling: appendices/arterial-spin-labeling.md
           - Cross modality correspondence: appendices/cross-modality-correspondence.md
+          - Spherical Harmonics: appendices/spherical-harmonics.md
       - Changelog: CHANGES.md
   - The BIDS Starter Kit:
       - Website: https://bids.neuroimaging.io/getting_started/

diff --git a/src/appendices/spherical-harmonics.md b/src/appendices/spherical-harmonics.md
@@ -0,0 +1,106 @@
+# Spherical Harmonics
+
+Spherical Harmonics (SH) are continuous functions defined on the surface of the sphere.
+They may be used to encode directionally dependent information;
+for instance, the distribution of white matter fibre orientations within an image voxel.
+This page provides the requisite information on the different basis sets that may be used,
+and how coefficients of such functions may be encoded within a data file.
+
+## SH functions
+
+![SH functions](https://latex.codecogs.com/gif.latex?Y_l^m(\theta,\phi)&space;=&space;\sqrt{\frac{(2l&plus;1)}{4\pi}\frac{(l-m)!}{(l&plus;m)!}}&space;P_l^m(\cos&space;\theta)&space;e^{im\phi})
+
+for integer *order* *l*, *phase* *m*, associated Legendre polynomials *P*.
+
+## Truncated basis coefficients
+
+![SH basis coefficients](https://latex.codecogs.com/gif.latex?f(\theta,\phi)&space;=&space;\sum_{l=0}^{l_\text{max}}&space;\sum_{m=-l}^{l}&space;c_l^m&space;Y_l^m(\theta,\phi))
+
+for *maximum* spherical harmonic order *l<sub>max</sub>*.
+
+## Real-valuedness
+
+All functions represented using a spherical harmonics basis are assumed to be real.
+This implies conjugate symmetry;
+that is: *Y*(*l*,-*m*) = *Y*(*l*,*m*)\*,
+where \* denotes the complex conjugate.
+
+## Antipodal symmetry
+
+All functions currently represented using a spherical harmonics based are assumed to be antipodally symmetric.
+This implies that all basis functions with odd order are zero.
+
+## Bases
+
+### `mrtrix3`
+
+![MRtrix3 SH basis](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Im}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Re}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
+
+### `descoteaux`
+
+![Descoteaux SH basis functions](https://latex.codecogs.com/gif.latex?Y_{lm}(\theta,\phi)=\begin{Bmatrix}&space;0&\text{if&space;}l\text{&space;is&space;odd},\\&space;\sqrt{2}\times\text{Re}\left[Y_l^{-m}(\theta,\phi)\right]&\text{if&space;}m<0,\\&space;Y_l^0(\theta,\phi)&\text{if&space;}m=0,\\&space;\sqrt{2}\times\text{Im}\left[Y_l^m(\theta,\phi)\right]&\text{if&space;}m>0\\&space;\end{Bmatrix})
+
+## Zonal Spherical Harmonics
+
+*Zonal* Spherical Harmonics (ZSH) refer to spherical harmonic functions for which all coefficients
+of non-zero order *m* are zero.
+These functions are therefore invariant under rotation about some zenith axis.
+
+![ZSH](https://latex.codecogs.com/gif.latex?Z_{l}(\theta,\phi)=Z_{l}(\theta)=Y_{l0})
+
+## Serialization and deserialization
+
+This is used to, for instance,
+store coefficients in a spherical harmonic basis within volumes of a 4D NIfTI image.
+
+### SH serialiszation and deserialization
+
+For coefficient index *n* and spherical harmonic basis function coefficient *Y<sub>l,m</sub>*:
+
+*n<sub>l,m</sub>* = (*l*(*l*+1) / 2) + *m*
+
+| ***n*** | **Coefficient**    |
+| ------- | ------------------ |
+| 0       | *Y<sub>0,0</sub>*  |
+| 1       | *Y<sub>2,-2</sub>* |
+| 2       | *Y<sub>2,-1</sub>* |
+| 3       | *Y<sub>2,0</sub>*  |
+| 4       | *Y<sub>2,1</sub>*  |
+| 5       | *Y<sub>2,2</sub>*  |
+| 6       | *Y<sub>4,-4</sub>* |
+| 7       | *Y<sub>4,-3</sub>* |
+| ...     | ...                |
+
+Relationship between maximal spherical harmonic degree *l<sub>max</sub>*
+and total number of coefficients *N*:
+
+*N* = ((*l<sub>max</sub>*+1) x (*l<sub>max</sub>*+2)) / 2
+
+| ***l<sub>max</sub>*** | 0 | 2 | 4  | 6  | 8  | 10 | ...  |
+| --------------------- |--:|--:|--: |--: |--: |--: | :--: |
+| ***N***               | 1 | 6 | 15 | 28 | 45 | 66 | ...  |
+
+### ZSH serialization and deserialization
+
+For coefficient index *n* and zonal spherical harmonic basis function coefficient *Z<sub>l</sub>*:
+
+*n<sub>l</sub>* = *l* / 2
+
+| ***n*** | **Coefficient**  |
+| ------- | ---------------- |
+| 0       | *Z<sub>0</sub>*  |
+| 1       | *Z<sub>2</sub>*  |
+| 2       | *Z<sub>4</sub>*  |
+| 3       | *Z<sub>6</sub>*  |
+| 4       | *Z<sub>8</sub>*  |
+| 5       | *Z<sub>10</sub>* |
+| ...     | ...              |
+
+Relationship between maximal zonal spherical harmonic degree *l<sub>max</sub>*
+and total number of coefficients *N*:
+
+*N* = 1 + *l*/2
+
+| ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | 10 | ...  |
+| --------------------- |--:|--:|--:|--:|--:|--: | :--: |
+| ***N***               | 1 | 2 | 3 | 4 | 5 | 6  | ...  |