diff --git a/.circleci/config.yml b/.circleci/config.yml index ee82d5b0..63f1dd4c 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -93,112 +93,6 @@ jobs: - store_artifacts: path: bids-spec.pdf - # Automatically generate a changelog since migration from Google Docs to GitHub - github_changelog_generator: - docker: - - image: ferrarimarco/github-changelog-generator:1.14.3 - steps: - - setup_remote_docker: - version: 18.06.0-ce - # checkout code to default ~/project - - checkout - - run: - name: Build changelog - # $CHANGE_TOKEN is generated via the GitHub web UI, and then securely stored within CircleCI web UI - command: | - mkdir ~/changelog_build - git status - if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then - github_changelog_generator \ - --exclude-tags-regex "^(?!v).*?$" \ - --user bids-standard \ - --project bids-specification \ - --token ${CHANGE_TOKEN} \ - --output ~/changelog_build/CHANGES.md \ - --base ~/project/src/pregh-changes.md \ - --header-label "# Changelog" \ - --release-branch master \ - --no-issues \ - --no-filter-by-milestone \ - --no-compare-link \ - --pr-label "" \ - --enhancement-label "" \ - --bugs-label "" \ - --exclude-labels "exclude-from-changelog" - cat ~/changelog_build/CHANGES.md - else - echo "Commit or Release, do nothing" - fi - - persist_to_workspace: - # raw generated changelog in ~/changelog_build/CHANGES.md - root: ~/. - paths: - - changelog_build - - # Lint and fix the auto generated changes.md file - lint_generated_changelog: - docker: - - image: cimg/node:lts - steps: - # checkout code to default ~/project - - checkout - - attach_workspace: - # the freshly built CHANGES.md will be in ~/changelog_build/CHANGES.md - at: ~/. - - run: - name: install remark and extensions - command: npm install `cat npm-requirements.txt` - - run: - name: remark on autogenerated CHANGES.md - # format changelog, then use sed to change * to -, then lint changelog - command: | - git status - if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then - head -n 100 ~/changelog_build/CHANGES.md - npx remark-cli ~/changelog_build/CHANGES.md --rc-path ~/project/.remarkrc --output ~/changelog_build/CHANGES.md - head -n 100 ~/changelog_build/CHANGES.md - sed -i 's/* /- /' ~/changelog_build/CHANGES.md - head -n 100 ~/changelog_build/CHANGES.md - npx remark-cli ~/changelog_build/CHANGES.md --frail --rc-path ~/project/.remarkrc - else - echo "Commit or Release, do nothing" - fi - - persist_to_workspace: - # linted and fixed changelog in ~/changelog_build/CHANGES.md - root: ~/. - paths: - - changelog_build - - # Push built changelog to repo - commit_generated_changelog: - docker: - - image: cimg/base:stable - steps: - - setup_remote_docker: - version: 17.11.0-ce - # checkout code to default ~/project - - checkout - - attach_workspace: - # fixed+linted changelog in ~/changelog_build/CHANGES.md - at: ~/. - - run: - name: Changelog deployment - # $CHANGE_TOKEN is generated via the GitHub web UI, and then securely stored within CircleCI web UI - command: | - if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then - mv ~/changelog_build/CHANGES.md ~/project/src/CHANGES.md - merge_message=$(git log -1 | grep Merge | grep "pull") - PR_number=$(echo $merge_message | cut -d ' ' -f 4) - git config credential.helper 'cache --timeout=120' - git config user.email "bids.maintenance@gmail.com" - git config user.name "bids-maintenance" - git add ~/project/src/CHANGES.md - git commit -m "[DOC] Auto-generate changelog entry for PR ${PR_number}" - git push https://${CHANGE_TOKEN}@github.com/bids-standard/bids-specification.git master - else - echo "Commit or Release, do nothing" - fi - workflows: search_build: jobs: @@ -206,20 +100,4 @@ workflows: - check_links: requires: - build_docs - - github_changelog_generator: - filters: - branches: - only: master - - lint_generated_changelog: - requires: - - github_changelog_generator - filters: - branches: - only: master - - commit_generated_changelog: - requires: - - lint_generated_changelog - filters: - branches: - only: master - build_docs_pdf diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fa9d6566..b6be304f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -2,27 +2,52 @@ See the [CONTRIBUTING](https://github.com/bids-standard/bids-specification/blob/master/CONTRIBUTING.md) guide. Specifically: -- Please keep the title of your Pull Request (PR) short but informative - it will - appear in the changelog. +- Please keep the title of your Pull Request (PR) short but informative - it will appear in the changelog. - If you do **not** want a PR to appear in the changelog, it must receive the `exclude-from-changelog` label. -- Please ensure your name is credited on our [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/appendices/contributors.md). - To add your name, please edit our [Contributors wiki](https://github.com/bids-standard/bids-specification/wiki/Contributors) and add your name with the type of contribution. + +- Please ensure your name is credited + on our [Contributors appendix](https://github.com/bids-standard/bids-specification/blob/master/src/appendices/contributors.md). + To add your name, please edit our [Contributors wiki](https://github.com/bids-standard/bids-specification/wiki/Contributors) + and add your name with the type of contribution. For assistance, please tag @bids-standard/maintainers. + - Use one of the following prefixes in the title of your PR: - - `[ENH]` - enhancement of the specification that adds a new feature or - support for a new data type + - `[ENH]` - enhancement of the specification that adds a new feature or support for a new data type - `[FIX]` - fix of a typo or language clarification - - `[INFRA]` - changes to the infrastructure automating the specification - release (for example building HTML docs) + - `[INFRA]` - changes to the infrastructure automating the specification release (for example building HTML docs) - `[SCHEMA]` - changes to the BIDS schema and/or related code - - `[MISC]` - everything else including changes to the file listing - contributors -- If you are opening a PR to obtain early feedback, but the changes - are not ready to be merged (also known as a "Work in Progress" PR), please - use a [Draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/). -- After opening the PR, our continuous integration services will automatically check your contribution for formatting errors and render a preview of the BIDS specification with your changes. + - `[MISC]` - everything else including changes to the file listing contributors + +- If you are opening a PR to obtain early feedback, + but the changes are not ready to be merged (also known as a "Work in Progress" PR), + please use a [Draft PR](https://github.blog/2019-02-14-introducing-draft-pull-requests/). + +- After opening the PR, our continuous integration services will automatically check your contribution + for formatting errors and render a preview of the BIDS specification with your changes. To see the checks and preview, scroll down and click on the `show all checks` link. - From the list, select the `Details` link of the `ci/circleci: build_docs artifact` check to see the preview of the BIDS specification. -- If you are updating the schema *and* you need to subsequently make changes to the bidsschematools code (validation, tests, rendering), this means your PR probably introduces a compatibility breaking change and you should increment the minor version (the second number) in `bids-specification/src/schema/SCHEMA_VERSION`. + From the list: + - select the `Details` link of the `docs/readthedocs.org:bids-specification` check to see the HTML preview of the BIDS specification. + - select the `Details` link of the `Check the rendered PDF version here! ` check to see the PDF preview of the BIDS specification. + +- If you are updating the schema *and* you need to subsequently make changes to the bidsschematools code (validation, tests, rendering), + this means your PR probably introduces a compatibility breaking change + and you should increment the minor version (the second number) in `bids-specification/src/schema/SCHEMA_VERSION`. + +- If you are opening a PR for a BIDS extension proposal (BEP), + make sure that your top message contains the following notes + +> [!Note] +> +> **We meet regularly to discuss this BEP** +> +> Next meeting: **insert date** on **URL to join** +> +> Communication channel on github repo / matrix / slack / discord : **insert URL to join** +> + +> [!Tip] +> +> [**HTML preview of this BEP**](insert URL to HTML preview once available) +> --- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST --- diff --git a/.github/workflows/changelog_generator.yml b/.github/workflows/changelog_generator.yml new file mode 100644 index 00000000..45d9948d --- /dev/null +++ b/.github/workflows/changelog_generator.yml @@ -0,0 +1,130 @@ +--- +name: GitHub_Changelog_Generator + +on: + push: + branches: ["master"] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + github_changelog_generator: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: '3.2' + - name: Install dependencies + run: | + gem install github_changelog_generator + - name: Check version + run: | + github_changelog_generator --version + - name: Build changelog + run: | + mkdir ~/changelog_build + github_changelog_generator \ + --exclude-tags-regex "^(?!v).*?$" \ + --user bids-standard \ + --project bids-specification \ + --token ${{ secrets.GITHUB_TOKEN }} \ + --output ~/changelog_build/CHANGES.md \ + --header-label "# Changelog" \ + --release-branch master \ + --no-issues \ + --no-filter-by-milestone \ + --no-compare-link \ + --pr-label "" \ + --enhancement-label "" \ + --bugs-label "" \ + --exclude-labels "exclude-from-changelog" + - name: Append changelog from pre-GitHub times + run: | + cat ${{ github.workspace }}/src/pregh-changes.md >> ~/changelog_build/CHANGES.md + - name: Remove the inserted advert from the file + run: | + sed -i '/This Changelog was automatically generated by/d' ~/changelog_build/CHANGES.md + - name: Print out complete changelog + run: | + cat ~/changelog_build/CHANGES.md + - name: Archive changelog + uses: actions/upload-artifact@v4 + with: + name: changelog_pre_lint + path: | + ~/changelog_build/CHANGES.md + + lint_generated_changelog: + needs: github_changelog_generator + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Download previously build changelog + uses: actions/download-artifact@v4 + with: + name: changelog_pre_lint + path: ~/changelog_build + - name: Set up Node + uses: actions/setup-node@v4 + with: + node-version: 20 + - name: Install remark and extensions + run: | + npm install `cat npm-requirements.txt` + - name: Remark on autogenerated CHANGES.md + # first remove empty lines + # then run remark to re-organize + # replace remark's bullet list "*" with "-" + # final run of remark to check everything passes now + run: | + head -n 25 ~/changelog_build/CHANGES.md + sed -i '/^$/d' ~/changelog_build/CHANGES.md + echo $'\n------------------------------\n' + head -n 25 ~/changelog_build/CHANGES.md + npx remark ~/changelog_build/CHANGES.md --rc-path ${{ github.workspace }}/.remarkrc --output ~/changelog_build/CHANGES.md --quiet + echo $'\n------------------------------\n' + head -n 25 ~/changelog_build/CHANGES.md + sed -i 's/^* /- /' ~/changelog_build/CHANGES.md + echo $'\n------------------------------\n' + 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 + with: + name: changelog_post_lint + path: | + ~/changelog_build/CHANGES.md + + commit_generated_changelog: + permissions: + # Give the default GITHUB_TOKEN write permission to commit and push the + # added or changed files to the repository. + contents: write + needs: lint_generated_changelog + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Download previously build changelog + uses: actions/download-artifact@v4 + with: + name: changelog_post_lint + path: ~/changelog_build + - name: Changelog deployment + run: | + if (git log -1 --pretty=%s | grep Merge*) && (! git log -1 --pretty=%b | grep REL:) ; then + mv ~/changelog_build/CHANGES.md ${{ github.workspace }}/src/CHANGES.md + merge_message=$(git log -1 | grep Merge | grep "pull") + PR_number=$(echo $merge_message | cut -d ' ' -f 4) + git config credential.helper 'cache --timeout=120' + git config user.email "bids.maintenance@gmail.com" + git config user.name "bids-maintenance" + git add ${{ github.workspace }}/src/CHANGES.md + git commit -m "[DOC] Auto-generate changelog entry for PR ${PR_number}" + git push https://${{ secrets.GITHUB_TOKEN }}@github.com/bids-standard/bids-specification.git master + else + echo "Did not detect a "Merge commit" to master, or detected a Release ... doing nothing." + fi diff --git a/.github/workflows/schemacode_ci.yml b/.github/workflows/schemacode_ci.yml index 6cf4dbcd..14746534 100644 --- a/.github/workflows/schemacode_ci.yml +++ b/.github/workflows/schemacode_ci.yml @@ -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 pytest pyyaml pandas tabulate markdown-it-py pyparsing + run: pip install --upgrade tools/schemacode[test] if: ${{ startsWith(github.ref, 'refs/tags/schema-') }} - name: "Build archive on tag" run: pytest tools/schemacode/bidsschematools -k make_archive @@ -117,8 +117,8 @@ jobs: with: user: __token__ password: ${{ secrets.TEST_PYPI_API_TOKEN }} - repository_url: https://test.pypi.org/legacy/ - skip_existing: true + repository-url: https://test.pypi.org/legacy/ + skip-existing: true - name: "Upload to PyPI (on tags)" if: startsWith(github.ref, 'refs/tags/schema-') uses: pypa/gh-action-pypi-publish@release/v1 diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml new file mode 100644 index 00000000..c4e38c1d --- /dev/null +++ b/.github/workflows/shellcheck.yml @@ -0,0 +1,26 @@ +--- +name: Shellcheck + +on: + push: + branches: [master] + pull_request: + branches: [master] + +permissions: + contents: read + +jobs: + shellcheck: + name: Check shell scripts + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Install dependencies + run: | + sudo apt update && sudo apt install -y shellcheck + - name: shellcheck + run: | + git grep -l '^#\( *shellcheck \|!\(/bin/\|/usr/bin/env \)\(sh\|bash\|dash\|ksh\)\)' | xargs shellcheck diff --git a/.github/workflows/validation.yml b/.github/workflows/validation.yml index 5be42a5b..ee554f9f 100644 --- a/.github/workflows/validation.yml +++ b/.github/workflows/validation.yml @@ -26,7 +26,7 @@ jobs: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: - node-version: 14 + node-version: 22 - name: Install dependencies run: npm install `cat npm-requirements.txt` - name: Run style checks diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8d032c6a..d6b5c199 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,5 +1,7 @@ # See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks +ci: + skip: [shellcheck] exclude: 'tools/schemacode/bidsschematools/tests/data/broken_dataset_description.json' repos: - repo: https://github.com/pre-commit/pre-commit-hooks @@ -50,7 +52,7 @@ repos: args: [-f=standard, -c=.yamllint.yml] files: src/schema/.*/.*\.yaml - repo: https://github.com/codespell-project/codespell - rev: v2.2.6 + rev: v2.3.0 hooks: - id: codespell args: ["--config=.codespellrc", "--dictionary=-", "--dictionary=.codespell_dict"] @@ -71,3 +73,7 @@ repos: - types-jsonschema args: ["tools/schemacode/bidsschematools"] pass_filenames: false + - repo: https://github.com/koalaman/shellcheck-precommit + rev: v0.10.0 + hooks: + - id: shellcheck diff --git a/.remarkrc b/.remarkrc index 8d6c2648..5f10c62b 100644 --- a/.remarkrc +++ b/.remarkrc @@ -4,7 +4,7 @@ "preset-lint-recommended", "remark-gfm", ["lint-no-duplicate-headings", false], - ["lint-list-item-indent", "tab-size"], + ["lint-list-item-indent", "tab"], ["lint-emphasis-marker", "consistent"], ["lint-maximum-line-length", false], ["lint-maximum-heading-length", false], diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c34f9cb5..208d0bd4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -202,28 +202,28 @@ Don't do this: ```Markdown | **Key name** | **Description** | -|--------------|----------------------------------------------------------| +| ------------ | -------------------------------------------------------- | | Manufacturer | Manufacturer of the equipment, for example (`Siemens`) | ``` That would look like this: | **Key name** | **Description** | -|--------------|----------------------------------------------------------| +| ------------ | -------------------------------------------------------- | | Manufacturer | Manufacturer of the equipment, for example (`Siemens`) | But do this instead: ```Markdown | **Key name** | **Description** | -|--------------|----------------------------------------------------------| +| ------------ | -------------------------------------------------------- | | Manufacturer | Manufacturer of the equipment, for example (`"Siemens"`) | ``` That would look like this: | **Key name** | **Description** | -|--------------|----------------------------------------------------------| +| ------------ | -------------------------------------------------------- | | Manufacturer | Manufacturer of the equipment, for example (`"Siemens"`) | diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index a29b4b86..f31b2eac 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -20,30 +20,33 @@ Current and past members of the steering group can be found ### Maintainers Group | Name | Time commitment | Scope | Joined | -|---------------------------------------------------------------------------|-----------------|---------------------------------------|----------| -| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 5h/week | Lead Maintainer | Mar 2020 | +| ------------------------------------------------------------------------- | --------------- | ------------------------------------- | -------- | +| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 1h/week | | Mar 2020 | | Chris Markiewicz ([@effigies](https://github.com/effigies)) | 5h/week | | Mar 2020 | | Ross Blair ([@rwblair](https://github.com/rwblair)) | | Maintainer of the bids-validator | Mar 2020 | | Taylor Salo ([@tsalo](https://github.com/tsalo)) | 3h/week | MRI | Sep 2020 | | Remi Gau ([@Remi-Gau](https://github.com/Remi-Gau)) | 3h/week | Community development, MRI | Oct 2020 | | Anthony Galassi ([@bendhouseart](https://github.com/bendhouseart)) | 3h/week | PET, Community development | Sep 2021 | | Eric Earl ([@ericearl](https://github.com/ericearl)) | 2h/week | | Dec 2021 | -| Christine Rogers ([@christinerogers](https://github.com/christinerogers)) | 2h/mo | Interoperability, EEG and multi-modal | Apr 2023 | +| Christine Rogers ([@christinerogers](https://github.com/christinerogers)) | 2h/month | Interoperability, EEG and multi-modal | Apr 2023 | | Nell Hardcastle ([@nellh](https://github.com/nellh)) | 2h/week | | Jul 2023 | -| Kimberly Ray ([@KimberlyLRay](https://github.com/KimberlyLRay)) | 1h/week | | Nov 2022 | +| Kimberly Ray ([@KimberlyLRay](https://github.com/KimberlyLRay)) | 1h/week | | Nov 2022 | In addition to the [BIDS Governance](https://bids.neuroimaging.io/governance.html#bids-maintainers-group) classification of a maintainer, maintainers may declare a limited scope of responsibility. Such a scope can range from maintaining a modality supported in the specification to nurturing a welcoming BIDS community. -One or more scopes can be chosen by the maintainer and agreed upon by the Maintainers Group. +Any number of scopes can be chosen by the maintainer and agreed upon by the Maintainers Group. A maintainer is primarily responsible for issues within their chosen scope(s), although contributions elsewhere are welcome, as well. +The role of the "lead maintainer", that is, the BIDS maintainer currently representing the maintainers group, +is rotating among current maintainers. + #### Past maintainers group members | Name | Duration | -|--------------------------------------------------------------------------------|---------------------| +| ------------------------------------------------------------------------------ | ------------------- | | Franklin Feingold ([@franklin-feingold](https://github.com/franklin-feingold)) | Mar 2020 - Jul 2022 | ### BEP Leads Group diff --git a/npm-requirements.txt b/npm-requirements.txt index 7ef67d23..c2eaebe9 100644 --- a/npm-requirements.txt +++ b/npm-requirements.txt @@ -1,5 +1,5 @@ -remark-cli@9.0.0 -remark-gfm@1 -remark-preset-lint-recommended@5.0.0 -remark-preset-lint-markdown-style-guide@4.0.0 +remark-cli@12 +remark-gfm@4 +remark-preset-lint-recommended@7 +remark-preset-lint-markdown-style-guide@6 remark-lint-no-trailing-spaces@2 diff --git a/scripts/test_tag b/scripts/test_tag index f11ef697..64e0ddd2 100755 --- a/scripts/test_tag +++ b/scripts/test_tag @@ -9,7 +9,7 @@ EPOCH="$(date +%s)" GIT_DIR=$( git rev-parse --git-dir ) -REPO_ROOT=$( ls -d ${GIT_DIR%.git} ) +REPO_ROOT=$( ls -d "${GIT_DIR%.git}" ) VERSION_FILE="$REPO_ROOT/src/schema/SCHEMA_VERSION" diff --git a/src/appendices/file-collections.md b/src/appendices/file-collections.md index 93d8391c..1df4677c 100644 --- a/src/appendices/file-collections.md +++ b/src/appendices/file-collections.md @@ -47,7 +47,7 @@ and a guide for using macros can be found at }} | **Suffix** | **Linking entities** | **Application** | **Description** | -|------------|-----------------------|--------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| ---------- | --------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | VFA | flip | Variable flip angle | The VFA method involves at least two spoiled gradient echo (SPGR) of steady-state free precession (SSFP) images acquired at different flip angles. Depending on the provided metadata fields and the sequence type, data may be eligible for DESPOT1, DESPOT2 and their variants ([Deoni et al. 2005](https://doi.org/10.1002/mrm.20314)). | | IRT1 | inv, part | Inversion recovery T1 mapping | The IRT1 method involves multiple inversion recovery spin-echo images acquired at different inversion times ([Barral et al. 2010](https://doi.org/10.1002/mrm.22497)). | | MP2RAGE | flip, inv, echo, part | Magnetization prepared two gradient echoes | The MP2RAGE method is a special protocol that collects several images at different flip angles and inversion times to create a parametric T1map by combining the magnitude and phase images ([Marques et al. 2010](https://doi.org/10.1016/j.neuroimage.2009.10.002)). | @@ -81,7 +81,7 @@ and a guide for using macros can be found at }} | **Suffix** | **Meta-data relevant entity** | **Application** | **Description** | -|------------|--------------------------------------------------------|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ---------- | ------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TB1DAM | flip | Double-angle B1+ mapping | The double-angle B1+ method ([Insko and Bolinger 1993](https://doi.org/10.1006/jmra.1993.1133)) is based on the calculation of the actual angles from signal ratios, collected by two acquisitions at different nominal excitation flip angles. Common sequence types for this application include spin echo and echo planar imaging. | | TB1EPI | flip, echo | B1+ mapping with 3D EPI | This B1+ mapping method ([Jiru and Klose 2006](https://doi.org/10.1002/mrm.21083)) is based on two EPI readouts to acquire spin echo (SE) and stimulated echo (STE) images at multiple flip angles in one sequence, used in the calculation of deviations from the nominal flip angle. | | TB1AFI | Please see the [qMRI appendix](../appendices/qmri.md). | Actual Flip Angle Imaging (AFI) | This method ([Yarnykh 2007](https://doi.org/10.1002/mrm.21120)) calculates a B1+ map from two images acquired at interleaved (two) TRs with identical RF pulses using a steady-state sequence. | diff --git a/src/appendices/licenses.md b/src/appendices/licenses.md index 90cb6aa7..adc02c23 100644 --- a/src/appendices/licenses.md +++ b/src/appendices/licenses.md @@ -9,7 +9,7 @@ The terms of any license should be consistent with the informed consent obtained from participants and any institutional limitations on distribution. | **Identifier** | **License name** | **Description** | -| ---------------| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | +| -------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | PD | Public Domain | No license required for any purpose; the work is not subject to copyright in any jurisdiction. | | [PDDL][pddl] | Open Data Commons Public Domain Dedication and License | License to assign public domain like permissions without giving up the copyright. | | [CC0][cc0] | Creative Commons Zero 1.0 Universal. | Use this if you are a holder of copyright or database rights, and you wish to waive all your interests in your work worldwide. | diff --git a/src/appendices/meg-systems.md b/src/appendices/meg-systems.md index 189d0ead..9ae9fa30 100644 --- a/src/appendices/meg-systems.md +++ b/src/appendices/meg-systems.md @@ -14,7 +14,7 @@ Preferred names of MEG systems comprise restricted keywords for Manufacturer fie Restricted keywords for ManufacturersModelName field in the `*_meg.json` file: | **System Model Name** | **Manufacturer** | **Details** | -|-------------------------- | --------- ------------| -------------------------------------------------------------------------------------------- | +| ------------------------- | --------- ----------- | -------------------------------------------------------------------------------------------- | | CTF-64 | CTF | | | CTF-151 | CTF | [https://www.ctf.com/products](https://www.ctf.com/products) | | CTF-275 | CTF | CTF-275: OMEGA 2000 | diff --git a/src/appendices/qmri.md b/src/appendices/qmri.md index 31e3b3ef..8aad465f 100644 --- a/src/appendices/qmri.md +++ b/src/appendices/qmri.md @@ -208,7 +208,7 @@ but also by which metadata fields are provided in accompanying json files. #### Anatomy imaging data | **File collection** | **REQUIRED metadata** | **OPTIONAL metadata** | -|----------------------|------------------------------------------------------------------------------------------------------------------------------|----------------------------| +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------- | | VFA | `FlipAngle`, `PulseSequenceType`, `RepetitionTimeExcitation` | `SpoilingRFPhaseIncrement` | | IRT1 | `InversionTime` | | | MP2RAGE\* | `FlipAngle`, `InversionTime`, `RepetitionTimeExcitation`, `RepetitionTimePreparation`, `NumberShots`,`MagneticFieldStrength` | `EchoTime` | @@ -282,7 +282,7 @@ and a guide for using macros can be found at }} | **File collection** | **REQUIRED metadata** | -|----------------------|------------------------------------------------------------------------------------------------------| +| -------------------- | ---------------------------------------------------------------------------------------------------- | | TB1DAM | `FlipAngle` | | TB1EPI | `EchoTime`, `FlipAngle`, `TotalReadoutTime`, `MixingTime` | | TB1AFI | `RepetitionTime` | @@ -447,7 +447,7 @@ This approach aims at: - keeping an inheritance track of the qMRI methods described within the specification. | **File-collection suffix** | **If REQUIRED metadata == Value** | **OPTIONAL metadata (`entity`/`fixed`)** | **Derived application name (NOT a suffix)** | -|----------------------------|-----------------------------------|------------------------------------------|---------------------------------------------| +| -------------------------- | --------------------------------- | ---------------------------------------- | ------------------------------------------- | | VFA | `PulseSequenceType` == `SPGR` | | DESPOT1 | | VFA | `PulseSequenceType` == `SSFP` | `SpoilingRFPhaseIncrement` (`fixed`) | DESPOT2 | | MP2RAGE | | `EchoTime` (`echo`) | MP2RAGE-ME | diff --git a/src/appendices/units.md b/src/appendices/units.md index 0edf271b..4e435548 100644 --- a/src/appendices/units.md +++ b/src/appendices/units.md @@ -47,7 +47,7 @@ Examples for CMIXF-12 (including the five unicode symbols mentioned above): ## Unit table | **Unit name** | **Unit symbol** | **Quantity name** | -| ---------------| --------------- | ------------------------------------------ | +| -------------- | --------------- | ------------------------------------------ | | meter | m | length | | kilogram | kg | mass | | liter | L | volume | @@ -84,7 +84,7 @@ 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 | 101 | | [hecto](https://www.wikiwand.com/en/Hecto-) | h | 102 | | [kilo](https://www.wikiwand.com/en/Kilo-) | k | 103 | diff --git a/src/common-principles.md b/src/common-principles.md index 3d9bc233..08ef8e6a 100644 --- a/src/common-principles.md +++ b/src/common-principles.md @@ -658,6 +658,21 @@ for more information. ## The Inheritance Principle +In some circumstances, there can be multiple data files for which +all or a subset of the relevant metadata is precisely equivalent. +Where this occurs, +it may be preferable to define those metadata *only once*, +and be placed on the filesystem in such a way that those files +are deemed to be *applicable* to each relevant data file individually, +but *not* be erroneously associated with other data files +to which the metadata contained within are not applicable. +The Inheritance Principle defines a systematized set of rules +to determine which metadata files to associate with which data files. +Further, because multiple metadata files may apply to an individual data file, +the Principle defines the *order of precedence* of such metadata files contents. + +### Rules + 1. Any metadata file (such as `.json`, `.bvec` or `.tsv`) MAY be defined at any directory level. 1. For a given data file, any metadata file is applicable to that data file if: @@ -687,7 +702,7 @@ for more information. same key present in another metadata file at a lower level (though it is RECOMMENDED to minimize the extent of such overrides). -Corollaries: +### Corollaries 1. As per rule 3, metadata files applicable only to a specific participant / session MUST be defined in or below the directory corresponding to that participant / session; @@ -704,6 +719,8 @@ Corollaries: a key-value in a later file does not imply the "unsetting" of that field (indeed removal of existing fields is not possible). +### Examples + Example 1: Demonstration of inheritance principle -{{ MACROS___make_suffix_table( - [ - "dwi", - "sbref", - ] - ) -}} +{{ MACROS___make_suffix_table(["dwi", "sbref"]) }} + +Additionally, the following suffixes are used for scanner-generated images: + + +{{ MACROS___make_suffix_table(["ADC", "TRACE"]) }}