Skip to content

Commit

Permalink
Merge branch 'master' into bep020
Browse files Browse the repository at this point in the history
  • Loading branch information
Remi-Gau authored Sep 5, 2024
2 parents 26c463a + 7c93b9c commit a6a1c9d
Show file tree
Hide file tree
Showing 76 changed files with 2,400 additions and 755 deletions.
89 changes: 89 additions & 0 deletions .github/workflows/publish_schema.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
name: "Publish schema"

on:
push:
branches:
- "master"

concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

defaults:
run:
shell: bash

env:
GIT_AUTHOR_NAME: BIDS CI
GIT_AUTHOR_EMAIL: [email protected]
GIT_COMMITTER_NAME: BIDS CI
GIT_COMMITTER_EMAIL: [email protected]

permissions:
contents: write
id-token: write

jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
filter: "blob:none"
- uses: actions/setup-python@v5
with:
python-version: 3
- name: Install bidsschematools
run: |
pip install --upgrade tools/schemacode
git clean -fxd tools/schemacode
- name: Checkout jsr-dist
run: |
git checkout -t origin/jsr-dist
- name: Regenerate schema
run: bst export > schema.json
- name: Regenerate context types
run: |
jq .meta.context schema.json \
| npx quicktype --src-lang schema --lang ts -t Context --just-types \
> context.ts
- name: Regenerate metaschema types
run: |
# Name the file schema so the type will be named Schema
bst export-metaschema > /tmp/schema.json
npx --package=json-schema-to-typescript json2ts --unknownAny /tmp/schema.json > metaschema.ts
- name: Determine next version
run: |
BASE=$( jq -r .schema_version schema.json )
if [[ "$BASE" =~ ^[0-9]*.[0-9]*.[0-9]*$ ]]; then
# Release, so unconditionally update version
VERSION=$BASE
jq ".version = \"$VERSION\"" jsr.json > tmp.json && mv tmp.json jsr.json
else
DENOVER=$( jq -r .version jsr.json )
# Get the reference of the latest commit to touch the schema directory
HASH=$( git log -n 1 --pretty=%h $REF -- src/schema )
if [[ $DENOVER =~ ^"$BASE".[0-9] ]]; then
PREFIX=${DENOVER%+*}
let SERIAL=1+${PREFIX#$BASE.}
else
SERIAL=1
fi
VERSION="$BASE.$SERIAL+$HASH"
fi
echo VERSION=$VERSION | tee -a $GITHUB_ENV
env:
REF: ${{ github.ref }}
- name: Check for changes, set version and commit
run: |
if ! git diff -s --exit-code; then
jq ".version = \"$VERSION\"" jsr.json > tmp.json && mv tmp.json jsr.json
git add jsr.json schema.json context.ts metaschema.ts
git commit -m "Update schema JSR distribution"
git push
fi
- name: Publish to JSR
if: success()
run: |
npx jsr publish
2 changes: 1 addition & 1 deletion .github/workflows/schemacode_ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ jobs:
- name: "Install build dependencies"
run: pip install --upgrade build twine
- name: "Install test dependencies on tag"
run: pip install --upgrade tools/schemacode[test]
run: pip install --upgrade tools/schemacode[all]
if: ${{ startsWith(github.ref, 'refs/tags/schema-') }}
- name: "Build archive on tag"
run: pytest tools/schemacode/bidsschematools -k make_archive
Expand Down
8 changes: 4 additions & 4 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ repos:
- id: check-added-large-files
- id: check-case-conflict
- repo: https://github.com/python-jsonschema/check-jsonschema
rev: 0.29.0
rev: 0.29.2
hooks:
- id: check-dependabot
- id: check-github-workflows
Expand All @@ -25,7 +25,7 @@ repos:
- id: check-readthedocs
files: readthedocs.yml
- repo: https://github.com/psf/black
rev: 24.4.2
rev: 24.8.0
hooks:
- id: black
files: ^tools/(?!schemacode)
Expand All @@ -45,7 +45,7 @@ repos:
files: tools/schemacode
args: ["--settings-file", "tools/schemacode/pyproject.toml"]
- repo: https://github.com/pyCQA/flake8
rev: 7.1.0
rev: 7.1.1
hooks:
- id: flake8
args: [--config=tools/schemacode/setup.cfg]
Expand All @@ -67,7 +67,7 @@ repos:
- id: codespell
args: ["--config=.codespellrc", "--dictionary=-", "--dictionary=.codespell_dict"]
- repo: https://github.com/pre-commit/mirrors-mypy
rev: v1.11.0
rev: v1.11.2
hooks:
- id: mypy
# Sync with project.optional-dependencies.typing
Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ BIDS currently supports the following data modalities with more to come in the f
- microscopy
- NIRS
- motion
- MRS

# Formatting your data with BIDS

Expand Down
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ nav:
- Microscopy: modality-specific-files/microscopy.md
- Near-Infrared Spectroscopy: modality-specific-files/near-infrared-spectroscopy.md
- Motion: modality-specific-files/motion.md
- Magnetic Resonance Spectroscopy: modality-specific-files/magnetic-resonance-spectroscopy.md
- Derivatives:
- BIDS Derivatives: derivatives/introduction.md
- Common data types and metadata: derivatives/common-data-types.md
Expand Down
2 changes: 1 addition & 1 deletion src/appendices/arterial-spin-labeling.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ For (P)CASL, specifying the `LabelingDuration` and the `PostLabelingDelay` is re
The `LabelingDuration` is defined as the total duration of the labeling pulse train in seconds.
`PostLabelingDelay` is the time in seconds after the end of the labeling until the middle of the excitation pulse applied
to the imaging slab (for 3D acquisition) or first slice (for 2D acquisition).
Additionally, the `BackgroundSuppressionPulseTime`'s is required in case `BackgroundSuppression` was applied.
Additionally, the `BackgroundSuppressionPulseTime` is RECOMMENDED if `BackgroundSuppression` was applied.
This an array of numbers containing the timing in seconds of the background suppression pulses
with respect to the start of the labeling.
In the case of `PCASL`, the recommended `PCASLType` field defines the type of the gradient pulses
Expand Down
1 change: 1 addition & 0 deletions src/appendices/contributors.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,6 +55,7 @@ If you contributed to the BIDS ecosystem and your name is not listed, please add
| Alexander Jones | 💻🐛 |
| Alexander L. Cohen | 🐛💻📖💬 |
| Alexander von Lautz | 📖 |
| Alexandre D'Astous | 📖 |
| Alexandre Gramfort | 📖💡 |
| Alexandre Hutton | 📖 |
| Alexandre Routier | 📖 |
Expand Down
7 changes: 7 additions & 0 deletions src/appendices/cross-modality-correspondence.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,10 @@ The reason for this is that the MRI needs to be corrected for nonlinear gradient
in order to fit the accompanying PET scans for co-registration
(Knudsen et al. 2020, [doi:10.1177/0271678X20905433](https://doi.org/10.1177/0271678X20905433);
Norgaard et al. 2019, [doi:10.1016/j.neuroimage.2019.05.055](https://doi.org/10.1016/j.neuroimage.2019.05.055)).

## MRS-MRI correspondence

It is typical to acquire high-resolution 3D anatomical MR images alongside MRS data for
voxel/slab placement, co-registration, and partial-volume tissue correction of metabolite concentrations.
To avoid incorrectly matching an MRS dataset with a corresponding anatomical MR image,
it is RECOMMENDED that the field `AnatomicalImage` be included in the MRS sidecar JSON files.
84 changes: 54 additions & 30 deletions src/appendices/qmri.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,10 +133,13 @@ A guide for using macros can be found at

Please visit the [file collections appendix](./file-collections.md#magnetic-resonance-imaging) to see the list of currently supported qMRI applications.

### Quantitative maps are derivatives
### Outputs are quantitative maps

Regardless of how they are obtained (pre- or post-generated), qMRI maps are stored in the `derivatives` directory.
For example a `T1map` can be generated from an `MP2RAGE` file collection using either options.
qMRI maps are stored differently depending on the process that generated them.
Pre-generated qMRI maps MAY be stored as part of a raw BIDS dataset,
whereas they MUST be stored in a derivative BIDS dataset if they were post-generated.

See the example below of a `T1map` generated from an `MP2RAGE` file collection using either option.

If the map is post-generated:

Expand All @@ -151,15 +154,25 @@ A guide for using macros can be found at
"qMRI-software-name": {
"sub-01": {
"anat": {
"sub-01_T1map.nii.gz": "",
"sub-01_T1map.nii.gz": " # --> T1 map in a derivative dataset",
"sub-01_T1map.json": "",
"sub-01_UNIT1.nii.gz": "",
"sub-01_UNIT1.nii.gz": " # --> UNI T1 in a derivative dataset",
"sub-01_UNIT1.json": "",
},
},
},
},
},
"sub-01": {
"anat": {
"sub-01_inv-1_part-mag_MP2RAGE.nii.gz":"",
"sub-01_inv-1_part-phase_MP2RAGE.nii.gz":"",
"sub-01_inv-1_MP2RAGE.json":"",
"sub-01_inv-2_part-mag_MP2RAGE.nii.gz":"",
"sub-01_inv-2_part-phase_MP2RAGE.nii.gz":"",
"sub-01_inv-2_MP2RAGE.json":"",
},
},
},
}
) }}

Expand All @@ -172,25 +185,30 @@ A guide for using macros can be found at
{{ MACROS___make_filetree_example(
{
"ds-example": {
"derivatives": {
"Siemens": {
"sub-01": {
"anat": {
"sub-01_T1map.nii.gz": "",
"sub-01_T1map.json": "",
"sub-01_UNIT1.nii.gz": "",
"sub-01_UNIT1.json": "",
},
},
},
"sub-01": {
"anat": {
"sub-01_inv-1_part-mag_MP2RAGE.nii.gz":"",
"sub-01_inv-1_part-phase_MP2RAGE.nii.gz":"",
"sub-01_inv-1_MP2RAGE.json":"",
"sub-01_inv-2_part-mag_MP2RAGE.nii.gz":"",
"sub-01_inv-2_part-phase_MP2RAGE.nii.gz":"",
"sub-01_inv-2_MP2RAGE.json":"",
"sub-01_T1map.nii.gz": " # --> T1 map in a raw dataset",
"sub-01_T1map.json": "",
"sub-01_UNIT1.nii.gz": " # --> UNI T1 in a raw dataset",
"sub-01_UNIT1.json": "",
},
},
}
}
) }}

Note: Even though the process from which pre-generated qMRI maps are obtained (vendor pipelines) is not known,
vendors generally allow exporting of the corresponding input data.
It is RECOMMENDED to share them along with the vendor outputs, whenever possible for a qMRI method supported by BIDS.
!!! note "Sharing of vendor outputs"

Even though the process from which pre-generated qMRI maps are obtained (vendor pipelines) is not known,
vendors generally allow exporting of the corresponding input data.
It is RECOMMENDED to share them along with the vendor outputs,
whenever possible for a qMRI method supported by BIDS.

### Example datasets

Expand Down Expand Up @@ -326,7 +344,7 @@ A guide for using macros can be found at

`dataset_description.json`:

```text
```json
{
"Name": "qMRLab Outputs",
"BIDSVersion": "1.5.0",
Expand Down Expand Up @@ -526,12 +544,13 @@ as an input to offline calculation of a `T1map` using a dictionary lookup approa
provided by the stock sequence. Instead, the `magnitude` and `phase` images are exported. Please
see the relevant discussion at [qMRLab issue #255](https://github.com/qMRLab/qMRLab/issues/255).

Therefore, the `UNIT1` image provided by the scanner is RECOMMENDED to be stored under the `anat`
raw dataset directory along with the `MP2RAGE` file collection and to be used as the primary input
for quantifying a `T1map`.
Therefore, the `UNIT1` image provided by the scanner
SHOULD be stored under the `anat` in a raw BIDS dataset
along with the `MP2RAGE` file collection
and to be used as the primary input for quantifying a `T1map`.

If an additional `UNIT1` image is calculated offline, then the output is to be stored in the
`derivatives` directory with necessary provenance information.
If an additional `UNIT1` image is calculated offline,
then the output MUST be stored in a derivative BIDS dataset with necessary provenance information.

##### `NumberShots` metadata field

Expand Down Expand Up @@ -607,10 +626,15 @@ The nominal FA value of the SE pulse is twice this value.
Note that the following metadata fields MUST be defined in the accompanying JSON
files:

| **Field name** | **Definition** |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `TotalReadoutTime` | The effective readout length defined as `EffectiveEchoSpacing * PEReconMatrix`, with `EffectiveEchoSpacing = TrueEchoSpacing / PEacceleration` |
| `MixingTime` | Time interval between the SE and STE pulses |
<!-- This block generates a metadata table.
These tables are defined in
src/schema/rules/sidecars
The definitions of the fields specified in these tables may be found in
src/schema/objects/metadata.yaml
A guide for using macros can be found at
https://github.com/bids-standard/bids-specification/blob/master/macros_doc.md
-->
{{ MACROS___make_sidecar_table("fmap.TB1EPI") }}

To properly identify constituents of this particular method, values of the `echo`
entity MUST index the images as follows:
Expand Down
69 changes: 45 additions & 24 deletions src/appendices/units.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,30 +83,51 @@ Examples for CMIXF-12 (including the five unicode symbols mentioned above):

### Multiples

| **Prefix name** | **Prefix symbol** | **Factor** |
| ------------------------------------------- | ----------------- | --------------- |
| [deca](https://www.wikiwand.com/en/Deca-) | da | 10<sup>1</sup> |
| [hecto](https://www.wikiwand.com/en/Hecto-) | h | 10<sup>2</sup> |
| [kilo](https://www.wikiwand.com/en/Kilo-) | k | 10<sup>3</sup> |
| [mega](https://www.wikiwand.com/en/Mega-) | M | 10<sup>6</sup> |
| [giga](https://www.wikiwand.com/en/Giga-) | G | 10<sup>9</sup> |
| [tera](https://www.wikiwand.com/en/Tera-) | T | 10<sup>12</sup> |
| [peta](https://www.wikiwand.com/en/Peta-) | P | 10<sup>15</sup> |
| [exa](https://www.wikiwand.com/en/Exa-) | E | 10<sup>18</sup> |
| [zetta](https://www.wikiwand.com/en/Zetta-) | Z | 10<sup>21</sup> |
| [yotta](https://www.wikiwand.com/en/Yotta-) | Y | 10<sup>24</sup> |
| **Prefix name** | **Prefix symbol** | **Factor** |
| --------------- | ----------------- | --------------- |
| [deca][] | da | 10<sup>1</sup> |
| [hecto][] | h | 10<sup>2</sup> |
| [kilo][] | k | 10<sup>3</sup> |
| [mega][] | M | 10<sup>6</sup> |
| [giga][] | G | 10<sup>9</sup> |
| [tera][] | T | 10<sup>12</sup> |
| [peta][] | P | 10<sup>15</sup> |
| [exa][] | E | 10<sup>18</sup> |
| [zetta][] | Z | 10<sup>21</sup> |
| [yotta][] | Y | 10<sup>24</sup> |

### Submultiples

| **Prefix name** | **Prefix symbol** | **Factor** |
| ------------------------------------------- | ----------------- | ---------------- |
| [deci](https://www.wikiwand.com/en/Deci-) | d | 10<sup>-1</sup> |
| [centi](https://www.wikiwand.com/en/Centi-) | c | 10<sup>-2</sup> |
| [milli](https://www.wikiwand.com/en/Milli-) | m | 10<sup>-3</sup> |
| [micro](https://www.wikiwand.com/en/Micro-) | u | 10<sup>-6</sup> |
| [nano](https://www.wikiwand.com/en/Nano-) | n | 10<sup>-9</sup> |
| [pico](https://www.wikiwand.com/en/Pico-) | p | 10<sup>-12</sup> |
| [femto](https://www.wikiwand.com/en/Femto-) | f | 10<sup>-15</sup> |
| [atto](https://www.wikiwand.com/en/Atto-) | a | 10<sup>-18</sup> |
| [zepto](https://www.wikiwand.com/en/Zepto-) | z | 10<sup>-21</sup> |
| [yocto](https://www.wikiwand.com/en/Yocto-) | y | 10<sup>-24</sup> |
| **Prefix name** | **Prefix symbol** | **Factor** |
| --------------- | ----------------- | ---------------- |
| [deci][] | d | 10<sup>-1</sup> |
| [centi][] | c | 10<sup>-2</sup> |
| [milli][] | m | 10<sup>-3</sup> |
| [micro][] | u | 10<sup>-6</sup> |
| [nano][] | n | 10<sup>-9</sup> |
| [pico][] | p | 10<sup>-12</sup> |
| [femto][] | f | 10<sup>-15</sup> |
| [atto][] | a | 10<sup>-18</sup> |
| [zepto][] | z | 10<sup>-21</sup> |
| [yocto][] | y | 10<sup>-24</sup> |

[deca]: https://en.wikipedia.org/wiki/Deca-
[hecto]: https://en.wikipedia.org/wiki/Hecto-
[kilo]: https://en.wikipedia.org/wiki/Kilo-
[mega]: https://en.wikipedia.org/wiki/Mega-
[giga]: https://en.wikipedia.org/wiki/Giga-
[tera]: https://en.wikipedia.org/wiki/Tera-
[peta]: https://en.wikipedia.org/wiki/Peta-
[exa]: https://en.wikipedia.org/wiki/Exa-
[zetta]: https://en.wikipedia.org/wiki/Zetta-
[yotta]: https://en.wikipedia.org/wiki/Yotta-
[deci]: https://en.wikipedia.org/wiki/Deci-
[centi]: https://en.wikipedia.org/wiki/Centi-
[milli]: https://en.wikipedia.org/wiki/Milli-
[micro]: https://en.wikipedia.org/wiki/Micro-
[nano]: https://en.wikipedia.org/wiki/Nano-
[pico]: https://en.wikipedia.org/wiki/Pico-
[femto]: https://en.wikipedia.org/wiki/Femto-
[atto]: https://en.wikipedia.org/wiki/Atto-
[zepto]: https://en.wikipedia.org/wiki/Zepto-
[yocto]: https://en.wikipedia.org/wiki/Yocto-
Loading

0 comments on commit a6a1c9d

Please sign in to comment.