Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New appendix page: spherical harmonics #104

Open
wants to merge 2 commits into
base: bep-016
Choose a base branch
from
Open

New appendix page: spherical harmonics #104

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
277723a
New appendix page: spherical harmonics
Lestropie May 16, 2024
30f7c6b
Appendix: SH: Fix LaTeX equations
Lestropie May 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,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-standard.github.io/bids-starter-kit/
Expand Down
106 changes: 106 additions & 0 deletions src/appendices/spherical-harmonics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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+1)}{4\pi}\frac{(l-m)!}{(l+m)!}}&space;P_l^m(\cos&space;\theta)&space;e^{im\phi}")
Lestropie marked this conversation as resolved.
Show resolved Hide resolved

for integer *order* *l*, *phase* *m*, associated Legendre polynomials *P*.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider "phase factor" instead of "phase"? See dipy/dipy#3086 (comment) and preceding discussing there.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lately I've tried to consistently use "degree" rather than "order" for l. Wikipedia uses "degree" and "order". "Phase factor" is at risk of erroneous conflation with specifically the Condon-Shortley phase factor. So I wonder if adopting "degree" and "order" here would be better?
(I'd likely modify the MRtrix3 online documentation accordingly)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would really prefer to use "order" here (rather than "degree") for the reasons mentioned in that PR discussion in DIPY (i.e., to be consistent with the dMRI literature). But I agree that "phase" is fine, even though it implies something continuous, it is easy to understand what it means.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jdtournier any strong opinions? I have some limited sense that we've tried to transition to "degree" for l, but our own SH docs page conflicts, other docs self-conflict, and I'm not able to find any discussions online.

PS. This terminology is not just for the appendix, there's also a metadata field specifying maximal l. Could call it "SphericalHarmonicLmax" or the like if there's too much contention.


## 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)")
Lestropie marked this conversation as resolved.
Show resolved Hide resolved

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 represented using a spherical harmonics based are assumed to be antipodally symmetric.
This implies that all basis functions with odd degree 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})
Lestropie marked this conversation as resolved.
Show resolved Hide resolved

### `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})
Lestropie marked this conversation as resolved.
Show resolved Hide resolved

## 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 | ... |
99 changes: 15 additions & 84 deletions src/derivatives/05-diffusion-derivatives.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,9 +187,8 @@ see [parameter metadata](#parameter-metadata).
a continuous function spanning the 2-sphere
using coefficients within a spherical harmonics basis.

Number of image volumes depends on the spherical harmonic basis employed,
and the maximal spherical harmonic degree *l<sub>max</sub>*
(see [spherical harmonics bases](#spherical-harmonics-bases)).
Number of image volumes depends on the maximal spherical harmonic degree *l<sub>max</sub>*
(see [spherical harmonics serialization](../../appendices/spherical-harmonics.md#sh-serialization-and-deserialization)).

1. <a name="encoding-amp">*Amplitudes*</a>:

Expand Down Expand Up @@ -256,12 +255,12 @@ The following table defines reserved fields within the `"Model"` sub-dictionary.

Dictionary `"Model["Parameters"]"` has the following reserved keywords that may be applicable to a broad range of models:

| **Key name** | **Description** |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Key name** | **Description** |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FitMethod | OPTIONAL. String. The optimization procedure used to fit the intrinsic model parameters to the empirical diffusion-weighted signal. Reserved values are: "`ols`" (Ordinary Least Squares); "`wls`" (Weighted Least Squares); "`iwls`" (Iterative Weighted Least Squares); "`nlls`" (Non-Linear Least Squares). |
| Iterations | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter. |
| OutlierRejectionMethod | OPTIONAL. String. Text describing any form of rejection of outlier values that was performed during fitting of the model. |
| Samples | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (such as mean, standard deviation) of those parameters were computed. |
| Iterations | OPTIONAL. Integer. The number of iterations used for any form of model fitting procedure where the number of iterations is a fixed input parameter. |
| OutlierRejectionMethod | OPTIONAL. String. Text describing any form of rejection of outlier values that was performed during fitting of the model. |
| Samples | OPTIONAL. Integer. The number of realisations of a diffusion model from which statistical summaries (such as mean, standard deviation) of those parameters were computed. |

#### Parameter metadata

Expand Down Expand Up @@ -293,8 +292,8 @@ Dictionary `"OrientationEncoding"` has the following reserved keywords:
| EncodingAxis | All except [scalar](#encoding-scalar) | REQUIRED. Integer. Indicates the image axis (indexed from zero) along which image intensities should be interpreted as corresponding to orientation encoding. |
| FillValue | [Scalar](#encoding-scalar), [spherical coordinates](#encoding-spherical), [3-vectors](#encoding-3vector) | OPTIONAL. Float; allowed values: { 0.0, NaN }. Value stored in image when the number of discrete orientations in a given voxel is fewer than the maximal number for that image. |
| Reference | All except [scalar](#encoding-scalar) | REQUIRED. String; allowed values: { `ijk`, `xyz` }. Indicates whether the NIfTI image axes, or scanner-space axes, are used as reference axes for orientation information. |
| SphericalHarmonicBasis | [Spherical harmonics](#encoding-sh) | REQUIRED for `"Type": "sh"`; MUST NOT be specified otherwise. String. Options are: { `mrtrix3`, `descoteaux` }. Details are provided in the [spherical harmonics bases](#spherical-harmonics-bases) section. |
| SphericalHarmonicDegree | [Spherical harmonics](#encoding-sh) | OPTIONAL for `"Type": "sh"`; MUST NOT be specified otherwise. Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in [spherical harmonics bases](#spherical-harmonics-bases) section. |
| SphericalHarmonicBasis | [Spherical harmonics](#encoding-sh) | REQUIRED for `"Type": "sh"`; MUST NOT be specified otherwise. String. Options are: { `mrtrix3`, `descoteaux` }. Details are provided in the [appendix on Spherical Harmonics](../../appendices/spherical-harmonics.md#bases). |
| SphericalHarmonicDegree | [Spherical harmonics](#encoding-sh) | OPTIONAL for `"Type": "sh"`; MUST NOT be specified otherwise. Integer. The maximal spherical harmonic order *l<sub>max</sub>*; the number of volumes in the associated NIfTI image must correspond to this value as per the relationship described in the [appendix on Spherical Harmonics](../../appendices/spherical-harmonics.md#sh-serialization-and-deserialization). |
| TensorRank | [Tensor](#encoding-tensor) | REQUIRED for `"Type": "tensor"; MUST NOT be specified otherwise. Integer. Rank of tensor reporesentation. Specification currently only supports a value of 2. |
| Type | Any | REQUIRED. String. Specifies the type of orientation information (if any) encoded in the NIfTI image. Permitted values: { `scalar`, `dec`, `unitspherical`, `spherical`, `unit3vector`, `3vector`, `tensor`, `sh`, `amplitudes` }. |

Expand All @@ -314,13 +313,16 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
then the values provided can be one of the following:

- List of floating-point values.
Values correspond to the response function coefficient for each consecutive even zonal spherical harmonic degree starting from zero.
Values correspond to [serialized zonal spherical harmonic coefficients](../../appendices/spherical-harmonics.md#zsh-serialization-and-deserialization)
in the nominated spherical harmonics basis.

- List of lists of floating-point values.
One list per unique *b*-value.
Each individual list contains a coefficient per even zonal spherical harmonic degree starting from zero.
Each individual list contains [serialized zonal spherical harmonic coefficients](../../appendices/spherical-harmonics.md#zsh-serialization-and-deserialization).
in the nominated spherical harmonics basis.
If the response function utilized has a different number of non-zero zonal spherical harmonic coefficients for different *b*-values,
these must be padded with zeroes such that all lists contain the same number of floating-point values.
these must be padded with zeroes such that all lists contain the same number of floating-point values
(that is, a regular matrix is formed).

### Demonstrative examples

Expand Down Expand Up @@ -838,74 +840,3 @@ Dictionary `"ResponseFunction"` has the following reserved keywords:
given that in the more general case there may be multiple scalar parameters
individually attributed to each component.

### Appendix

#### Spherical Harmonics

- Concepts shared across all spherical harmonics bases:

- Basis functions:

![SH basis 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>*.

- Functions assumed to be real: conjugate symmetry is assumed, that is,
*Y*(*l*,-*m*) = *Y*(*l*,*m*)\*, where \* denotes the complex
conjugate.

- Antipodally symmetric: all basis functions with odd degree are
assumed zero; `AntipodalSymmetry` MUST NOT be set to `False`.

- Utilized basis functions:

- `mrtrix3`

![MRtrix3 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{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})

- Mapping between image volume *V* and spherical harmonic basis
function coefficient *Y<sub>l,m</sub>*:

*V<sub>l,m</sub>* = (*l*(*l*+1) / 2) + *m*

| ***V*** | **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 number of image volumes *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 | ... |

- Relationship between maximal degree of *zonal* spherical harmonic
function (spherical harmonics function where all *m* != 0 terms are
assumed to be zero; used for response function definition and similar) and
number of coefficients *N*:

*N* = 1 + (*l<sub>max</sub>* / 2)

| ***l<sub>max</sub>*** | 0 | 2 | 4 | 6 | 8 | 10 | ... |
| --------------------- |--:|--:|--:|--:|--:|--: | :--: |
| ***N*** | 1 | 2 | 3 | 4 | 5 | 6 | ... |
Loading