From c23030159b1071ce3b580b4238628eef063bbbaf Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Mon, 6 Dec 2021 10:38:48 +1100 Subject: [PATCH 01/16] [FIX] Rewrite inheritance principle --- src/02-common-principles.md | 145 +++++++++++++++++++++--------------- 1 file changed, 83 insertions(+), 62 deletions(-) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index e29d0b96ed..90ed991ea9 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -400,108 +400,129 @@ datasets and non-compliant derivatives. ## The Inheritance Principle -Any metadata file (such as `.json`, `.bvec` or `.tsv`) may be defined at any -directory level, but no more than one applicable file may be defined at a given -level (Example 1). The values from the top level are inherited by all lower -levels unless they are overridden by a file at the lower level. For example, -`sub-*_task-rest_bold.json` may be specified at the participant level, setting -TR to a specific value. If one of the runs has a different TR than the one -specified in that file, another `sub-*_task-rest_bold.json` file can be placed -within that specific series directory specifying the TR for that specific run. -There is no notion of "unsetting" a key/value pair. -Once a key/value pair is set in a given level in the dataset, lower down in -the hierarchy that key/value pair will always have some assigned value. -Files for a particular participant can exist only at participant level directory, -that is, `/dataset/sub-*[/ses-*]/sub-*_T1w.json`. Similarly, any file that is not -specific to a participant is to be declared only at top level of dataset for example: -`task-sist_bold.json` must be placed under `/dataset/task-sist_bold.json` - -Example 1: Two JSON files that are erroneously at the same level +Any metadata file (such as `.json`, `.bvec` or `.tsv`) MAY be defined at any +directory level. For any given data file, any metadata file at that directory +level or higher that does not include any entities absent from the name of the +data file and possesses the same suffix are applicable to that data file. Such +files are loaded from the top of the directory hierarchy downwards, such that +values from the top level are inherited by all data files at lower levels to +which it is applicable unless overridden by a value for the same key present +in another metadata file at a lower level (though it is RECOMMENDED to minimise +the extent of such overrides). There is no notion of "unsetting" a +key/value pair. + +Example 1: Demonstration of inheritance principle + +{{ MACROS___make_filetree_example( + { + "sub-01": { + "func": { + "sub-01_task-rest_acq-default_bold.nii.gz": "", + "sub-01_task-rest_acq-longtr_bold.nii.gz": "", + "sub-01_task-rest_acq-longtr_bold.json": "", + } + } + } + "task-rest_bold.json": "", +) }} + +Contents of file "task-rest_bold.json": + +{{ MACROS___make_metadata_table( + { + "EchoTime": 40.0, + "RepetitionTime", 1000.0 + } +) }} + +Contents of file "sub-01/func/sub-01_task-rest_acq-longtr_bold.json": + +{{ MACROS___make_metadata_table( + { + "RepetitionTime", 3000.0 + } +) }} + +When reading image `sub-01/func/sub-01_task-rest_acq-default_bold.nii.gz`, only +metadata file `task-rest_bold.json` is read; file +`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` is inapplicable as it contains +entity "`acq-longtr`" that is absent from the image path. When reading image +`sub-01/func/sub-01_task-rest_acq-longtr_bold.nii.gz`, metadata file +`task-rest_bold.json` at the top level is read first, followed by file +`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` at the bottom level; the value +for field "`RepetitionTime`" is therefore overridden to the value 3000.0. The value +for field "`EchoTime`" remains applicable to that image, and is not unset by its +absence in the metadata file at the lower level. + +Metadata files applicable only to a specific participant / session MUST be defined +in or below the directory corresponding to that participant / session. Similarly, +a metadata file that is applicable to multiple participants / sessions MUST NOT be +placed within a directory corresponding to only one such participant / session. + +There MUST NOT be multiple metadata files applicable to a data file at one level +of the directory hierarchy. + +Example 2: Impermissible use of multiple metadata files at one directory level {{ MACROS___make_filetree_example( { "sub-01": { "ses-test":{ - "sub-01_ses-test_task-overtverbgeneration_bold.json": "", - "sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": "", "anat": { "sub-01_ses-test_T1w.nii.gz": "", }, "func": { "sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": "", "sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": "", + "sub-01_ses-test_task-overtverbgeneration_bold.json": "", + "sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": "", } } } } ) }} -In the above example, two JSON files are listed under `sub-01/ses-test/`, which -are each applicable to -`sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz`, violating the -constraint that no more than one file may be defined at a given level of the -directory structure. Instead `sub-01_ses-test_task-overtverbgeneration_run-2_bold.json` -should have been under `sub-01/ses-test/func/`. - -Example 2: Multiple `run`s and `rec`s with same acquisition (`acq`) parameters +Example 3: Modification of filesystem structure from Example 2 to satisfy inheritance +principle requirements {{ MACROS___make_filetree_example( { "sub-01": { - "anat": {}, - "func": { - "sub-01_task-xyz_acq-test1_run-1_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_run-2_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_rec-recon1_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_rec-recon2_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_bold.json": "", + "ses-test":{ + "sub-01_ses-test_task-overtverbgeneration_bold.json": "", + "anat": { + "sub-01_ses-test_T1w.nii.gz": "", + }, + "func": { + "sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": "", + "sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": "", + "sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": "", + } } } } ) }} -For the above example, all NIfTI files are acquired with same scanning -parameters (`acq-test1`). Hence a JSON file describing the acq parameters will -apply to different runs and rec files. Also if the JSON file -(`task-xyz_acq-test1_bold.json`) is defined at dataset top level directory, it -will be applicable to all task runs with `test1` acquisition parameter. +It is permissible for a single metadata file to be applicable to multiple data +files at that level of the hierarchy. Where such metadata content is consistent +across multiple data files, it is RECOMMENDED to store metadata in this +way, rather than duplicating that metadata content across multiple metadata files. -Example 3: Multiple JSON files at different levels for same task and acquisition parameters +Example 4: Single metadata file applying to multiple data files {{ MACROS___make_filetree_example( { - "task-xyz_acq-test1_bold.json": "", "sub-01": { "anat": {}, "func": { "sub-01_task-xyz_acq-test1_run-1_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_rec-recon1_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_rec-recon2_bold.nii.gz": "", + "sub-01_task-xyz_acq-test1_run-2_bold.nii.gz": "", "sub-01_task-xyz_acq-test1_bold.json": "", } } } ) }} -In the above example, the fields from the `task-xyz_acq-test1_bold.json` file -at the top directory will apply to all bold runs. However, if there is a key -with different value in the -`sub-01/func/sub-01_task-xyz_acq-test1_bold.json` file defined at a -deeper level, that value will be applicable for that particular run/task NIfTI -file/s. In other words, the `.json` file at the deeper level overrides values -that are potentially also defined in the `.json` at a more shallow level. If the -`.json` file at the more shallow level contains key-value-pairs that are not -present in the `.json` file at the deeper level, these key-value-pairs are -inherited by the `.json` file at the deeper level (but NOT vice versa!). - -### Good practice recommendations - -**Try to avoid excessive amount of overrides.** Do not specify a field -value in the upper levels if lower levels have more or less even -distribution of multiple possible values. For example, if a field `X` has one -value for all `ses-01/` and another for all `ses-02/` it better not to be -defined at all in the `.json` at the upper level. - ## File Formation specification ### Imaging files From 2202697e71c0aac6ad64ee7761c993709d224f33 Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Mon, 6 Dec 2021 11:18:32 +1100 Subject: [PATCH 02/16] [FIX] Fix trailing space src/02_common_principles.md #946 --- src/02-common-principles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 90ed991ea9..bb446a7b91 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -444,7 +444,7 @@ Contents of file "sub-01/func/sub-01_task-rest_acq-longtr_bold.json": ) }} When reading image `sub-01/func/sub-01_task-rest_acq-default_bold.nii.gz`, only -metadata file `task-rest_bold.json` is read; file +metadata file `task-rest_bold.json` is read; file `sub-01/func/sub-01_task-rest_acq-longtr_bold.json` is inapplicable as it contains entity "`acq-longtr`" that is absent from the image path. When reading image `sub-01/func/sub-01_task-rest_acq-longtr_bold.nii.gz`, metadata file From 0abc9300a9a92b48e53d75dc8a1479b70fbe85cf Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Mon, 13 Dec 2021 10:11:15 +1100 Subject: [PATCH 03/16] Inheritance principle: Use bullet points Co-authored-by: Remi Gau --- src/02-common-principles.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index bb446a7b91..22cdfdb263 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -400,16 +400,17 @@ datasets and non-compliant derivatives. ## The Inheritance Principle -Any metadata file (such as `.json`, `.bvec` or `.tsv`) MAY be defined at any -directory level. For any given data file, any metadata file at that directory -level or higher that does not include any entities absent from the name of the -data file and possesses the same suffix are applicable to that data file. Such -files are loaded from the top of the directory hierarchy downwards, such that -values from the top level are inherited by all data files at lower levels to -which it is applicable unless overridden by a value for the same key present -in another metadata file at a lower level (though it is RECOMMENDED to minimise -the extent of such overrides). There is no notion of "unsetting" a -key/value pair. +- Any metadata file (such as `.json`, `.bvec` or `.tsv`) MAY be defined at any directory level. +- For a given data file, any metadata file at that directory level or higher +is applicable to that data file if: + - the metadata and the data filenames possess the same suffix, + - the metadata filename does not include any entity absent from the data filename. +- Such files are loaded from the top of the directory hierarchy downwards, +such that values from the top level are inherited by all data files +at lower levels to which it is applicable unless overridden +by a value for the same key present in another metadata file at a lower level +(though it is RECOMMENDED to minimise the extent of such overrides). +- There is no notion of "unsetting" a key/value pair. Example 1: Demonstration of inheritance principle From 1bcf1b52a750d8bfa3f6121e893a2af6ffd861e1 Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Mon, 13 Dec 2021 10:51:42 +1100 Subject: [PATCH 04/16] Inheritance principle: Multiple changes - Change primary rules from dot points to enumerations, and reference rules by number where applicable. - Move from subsequent text into this list rules relating to improper placement of metadata files within the directory structure, and not permitting multiple applicable files at one level of the hierarchy. - Add "corollaries" section incorporating text relating to interpretation and consequences of the rules, separating them from subsequent examples. --- src/02-common-principles.md | 71 +++++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 31 deletions(-) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 22cdfdb263..3ef4406c49 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -400,17 +400,39 @@ datasets and non-compliant derivatives. ## The Inheritance Principle -- Any metadata file (such as `.json`, `.bvec` or `.tsv`) MAY be defined at any directory level. -- For a given data file, any metadata file at that directory level or higher -is applicable to that data file if: - - the metadata and the data filenames possess the same suffix, - - the metadata filename does not include any entity absent from the data filename. -- Such files are loaded from the top of the directory hierarchy downwards, -such that values from the top level are inherited by all data files -at lower levels to which it is applicable unless overridden -by a value for the same key present in another metadata file at a lower level -(though it is RECOMMENDED to minimise the extent of such overrides). -- There is no notion of "unsetting" a key/value pair. +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: + 1. It is stored at the same directory level or higher; + 1. The metadata and the data filenames possess the same suffix; + 1. The metadata filename does not include any entity absent from the data filename. +1. A metadata file MUST NOT have a file name that would be otherwise applicable + to some data file based on rules 2.2 and 2.3 but is made inapplicable based on its + location in the directory structure as per rule 2.1. +1. There MUST NOT be multiple metadata files applicable to a data file at one level + of the directory hierarchy. +1. If multiple metadata files are applicable to a given data file: + 1. For [tabular files](#tabular-files) and other simple metadata files + (e.g. [`bvec` / `bval` files for diffusion MRI](#04-modality-specific-files/01-magnetic-resonance-imaging#required-gradient-orientation-information), + only the file lowest in the filesystem hierarchy SHALL be treated as being + associated with that data file. + 1. For [JSON files](#key-value-files-dictionaries): + 1. Files are loaded from the top of the directory hierarchy downwards, + such that values from the top level are inherited by all data files + at lower levels to which it is applicable unless overridden + by a value for the same key present in another metadata file at a lower level + (though it is RECOMMENDED to minimise the extent of such overrides). + 1. There is no notion of "unsetting" a key/value pair. + +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; + similarly, a metadata file that is applicable to multiple participants / sessions + MUST NOT be placed within a directory corresponding to only one such participant / session. +1. It is permissible for a single metadata file to be applicable to multiple data + files at that level of the hierarchy. Where such metadata content is consistent + across multiple data files, it is RECOMMENDED to store metadata in this + way, rather than duplicating that metadata content across multiple metadata files. Example 1: Demonstration of inheritance principle @@ -447,23 +469,15 @@ Contents of file "sub-01/func/sub-01_task-rest_acq-longtr_bold.json": When reading image `sub-01/func/sub-01_task-rest_acq-default_bold.nii.gz`, only metadata file `task-rest_bold.json` is read; file `sub-01/func/sub-01_task-rest_acq-longtr_bold.json` is inapplicable as it contains -entity "`acq-longtr`" that is absent from the image path. When reading image +entity "`acq-longtr`" that is absent from the image path (rule 2.3). When reading image `sub-01/func/sub-01_task-rest_acq-longtr_bold.nii.gz`, metadata file `task-rest_bold.json` at the top level is read first, followed by file -`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` at the bottom level; the value -for field "`RepetitionTime`" is therefore overridden to the value 3000.0. The value -for field "`EchoTime`" remains applicable to that image, and is not unset by its -absence in the metadata file at the lower level. +`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` at the bottom level (rule 5.2.1); +the value for field "`RepetitionTime`" is therefore overridden to the value 3000.0. +The value for field "`EchoTime`" remains applicable to that image, and is not unset by its +absence in the metadata file at the lower level (rule 5.2.2). -Metadata files applicable only to a specific participant / session MUST be defined -in or below the directory corresponding to that participant / session. Similarly, -a metadata file that is applicable to multiple participants / sessions MUST NOT be -placed within a directory corresponding to only one such participant / session. - -There MUST NOT be multiple metadata files applicable to a data file at one level -of the directory hierarchy. - -Example 2: Impermissible use of multiple metadata files at one directory level +Example 2: Impermissible use of multiple metadata files at one directory level (rule 4) {{ MACROS___make_filetree_example( { @@ -504,12 +518,7 @@ principle requirements } ) }} -It is permissible for a single metadata file to be applicable to multiple data -files at that level of the hierarchy. Where such metadata content is consistent -across multiple data files, it is RECOMMENDED to store metadata in this -way, rather than duplicating that metadata content across multiple metadata files. - -Example 4: Single metadata file applying to multiple data files +Example 4: Single metadata file applying to multiple data files (corollary 2) {{ MACROS___make_filetree_example( { From 7f52984578ddc94eb263ba100f834cf25ca961a3 Mon Sep 17 00:00:00 2001 From: Robert Smith Date: Mon, 13 Dec 2021 10:53:40 +1100 Subject: [PATCH 05/16] Inheritance principle: Move to follow "file formation specification" As the inheritance principle makes reference to tabular files and JSON key-value dictionaries, but there are no such references in the opposite direction, these files should be defined prior to introduction of the Inheritance Principle. --- src/02-common-principles.md | 270 ++++++++++++++++++------------------ 1 file changed, 135 insertions(+), 135 deletions(-) diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 3ef4406c49..7c35a2a29d 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -398,141 +398,6 @@ In particular, if a BIDS dataset contains a `derivatives/` sub-directory, the contents of that directory may be a heterogeneous mix of BIDS Derivatives datasets and non-compliant derivatives. -## The Inheritance Principle - -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: - 1. It is stored at the same directory level or higher; - 1. The metadata and the data filenames possess the same suffix; - 1. The metadata filename does not include any entity absent from the data filename. -1. A metadata file MUST NOT have a file name that would be otherwise applicable - to some data file based on rules 2.2 and 2.3 but is made inapplicable based on its - location in the directory structure as per rule 2.1. -1. There MUST NOT be multiple metadata files applicable to a data file at one level - of the directory hierarchy. -1. If multiple metadata files are applicable to a given data file: - 1. For [tabular files](#tabular-files) and other simple metadata files - (e.g. [`bvec` / `bval` files for diffusion MRI](#04-modality-specific-files/01-magnetic-resonance-imaging#required-gradient-orientation-information), - only the file lowest in the filesystem hierarchy SHALL be treated as being - associated with that data file. - 1. For [JSON files](#key-value-files-dictionaries): - 1. Files are loaded from the top of the directory hierarchy downwards, - such that values from the top level are inherited by all data files - at lower levels to which it is applicable unless overridden - by a value for the same key present in another metadata file at a lower level - (though it is RECOMMENDED to minimise the extent of such overrides). - 1. There is no notion of "unsetting" a key/value pair. - -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; - similarly, a metadata file that is applicable to multiple participants / sessions - MUST NOT be placed within a directory corresponding to only one such participant / session. -1. It is permissible for a single metadata file to be applicable to multiple data - files at that level of the hierarchy. Where such metadata content is consistent - across multiple data files, it is RECOMMENDED to store metadata in this - way, rather than duplicating that metadata content across multiple metadata files. - -Example 1: Demonstration of inheritance principle - -{{ MACROS___make_filetree_example( - { - "sub-01": { - "func": { - "sub-01_task-rest_acq-default_bold.nii.gz": "", - "sub-01_task-rest_acq-longtr_bold.nii.gz": "", - "sub-01_task-rest_acq-longtr_bold.json": "", - } - } - } - "task-rest_bold.json": "", -) }} - -Contents of file "task-rest_bold.json": - -{{ MACROS___make_metadata_table( - { - "EchoTime": 40.0, - "RepetitionTime", 1000.0 - } -) }} - -Contents of file "sub-01/func/sub-01_task-rest_acq-longtr_bold.json": - -{{ MACROS___make_metadata_table( - { - "RepetitionTime", 3000.0 - } -) }} - -When reading image `sub-01/func/sub-01_task-rest_acq-default_bold.nii.gz`, only -metadata file `task-rest_bold.json` is read; file -`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` is inapplicable as it contains -entity "`acq-longtr`" that is absent from the image path (rule 2.3). When reading image -`sub-01/func/sub-01_task-rest_acq-longtr_bold.nii.gz`, metadata file -`task-rest_bold.json` at the top level is read first, followed by file -`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` at the bottom level (rule 5.2.1); -the value for field "`RepetitionTime`" is therefore overridden to the value 3000.0. -The value for field "`EchoTime`" remains applicable to that image, and is not unset by its -absence in the metadata file at the lower level (rule 5.2.2). - -Example 2: Impermissible use of multiple metadata files at one directory level (rule 4) - -{{ MACROS___make_filetree_example( - { - "sub-01": { - "ses-test":{ - "anat": { - "sub-01_ses-test_T1w.nii.gz": "", - }, - "func": { - "sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": "", - "sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": "", - "sub-01_ses-test_task-overtverbgeneration_bold.json": "", - "sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": "", - } - } - } - } -) }} - -Example 3: Modification of filesystem structure from Example 2 to satisfy inheritance -principle requirements - -{{ MACROS___make_filetree_example( - { - "sub-01": { - "ses-test":{ - "sub-01_ses-test_task-overtverbgeneration_bold.json": "", - "anat": { - "sub-01_ses-test_T1w.nii.gz": "", - }, - "func": { - "sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": "", - "sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": "", - "sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": "", - } - } - } - } -) }} - -Example 4: Single metadata file applying to multiple data files (corollary 2) - -{{ MACROS___make_filetree_example( - { - "sub-01": { - "anat": {}, - "func": { - "sub-01_task-xyz_acq-test1_run-1_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_run-2_bold.nii.gz": "", - "sub-01_task-xyz_acq-test1_bold.json": "", - } - } - } -) }} - ## File Formation specification ### Imaging files @@ -675,6 +540,141 @@ for more information. } ``` +## The Inheritance Principle + +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: + 1. It is stored at the same directory level or higher; + 1. The metadata and the data filenames possess the same suffix; + 1. The metadata filename does not include any entity absent from the data filename. +1. A metadata file MUST NOT have a file name that would be otherwise applicable + to some data file based on rules 2.2 and 2.3 but is made inapplicable based on its + location in the directory structure as per rule 2.1. +1. There MUST NOT be multiple metadata files applicable to a data file at one level + of the directory hierarchy. +1. If multiple metadata files are applicable to a given data file: + 1. For [tabular files](#tabular-files) and other simple metadata files + (e.g. [`bvec` / `bval` files for diffusion MRI](#04-modality-specific-files/01-magnetic-resonance-imaging#required-gradient-orientation-information), + only the file lowest in the filesystem hierarchy SHALL be treated as being + associated with that data file. + 1. For [JSON files](#key-value-files-dictionaries): + 1. Files are loaded from the top of the directory hierarchy downwards, + such that values from the top level are inherited by all data files + at lower levels to which it is applicable unless overridden + by a value for the same key present in another metadata file at a lower level + (though it is RECOMMENDED to minimise the extent of such overrides). + 1. There is no notion of "unsetting" a key/value pair. + +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; + similarly, a metadata file that is applicable to multiple participants / sessions + MUST NOT be placed within a directory corresponding to only one such participant / session. +1. It is permissible for a single metadata file to be applicable to multiple data + files at that level of the hierarchy. Where such metadata content is consistent + across multiple data files, it is RECOMMENDED to store metadata in this + way, rather than duplicating that metadata content across multiple metadata files. + +Example 1: Demonstration of inheritance principle + +{{ MACROS___make_filetree_example( + { + "sub-01": { + "func": { + "sub-01_task-rest_acq-default_bold.nii.gz": "", + "sub-01_task-rest_acq-longtr_bold.nii.gz": "", + "sub-01_task-rest_acq-longtr_bold.json": "", + } + } + } + "task-rest_bold.json": "", +) }} + +Contents of file "task-rest_bold.json": + +{{ MACROS___make_metadata_table( + { + "EchoTime": 40.0, + "RepetitionTime", 1000.0 + } +) }} + +Contents of file "sub-01/func/sub-01_task-rest_acq-longtr_bold.json": + +{{ MACROS___make_metadata_table( + { + "RepetitionTime", 3000.0 + } +) }} + +When reading image `sub-01/func/sub-01_task-rest_acq-default_bold.nii.gz`, only +metadata file `task-rest_bold.json` is read; file +`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` is inapplicable as it contains +entity "`acq-longtr`" that is absent from the image path (rule 2.3). When reading image +`sub-01/func/sub-01_task-rest_acq-longtr_bold.nii.gz`, metadata file +`task-rest_bold.json` at the top level is read first, followed by file +`sub-01/func/sub-01_task-rest_acq-longtr_bold.json` at the bottom level (rule 5.2.1); +the value for field "`RepetitionTime`" is therefore overridden to the value 3000.0. +The value for field "`EchoTime`" remains applicable to that image, and is not unset by its +absence in the metadata file at the lower level (rule 5.2.2). + +Example 2: Impermissible use of multiple metadata files at one directory level (rule 4) + +{{ MACROS___make_filetree_example( + { + "sub-01": { + "ses-test":{ + "anat": { + "sub-01_ses-test_T1w.nii.gz": "", + }, + "func": { + "sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": "", + "sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": "", + "sub-01_ses-test_task-overtverbgeneration_bold.json": "", + "sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": "", + } + } + } + } +) }} + +Example 3: Modification of filesystem structure from Example 2 to satisfy inheritance +principle requirements + +{{ MACROS___make_filetree_example( + { + "sub-01": { + "ses-test":{ + "sub-01_ses-test_task-overtverbgeneration_bold.json": "", + "anat": { + "sub-01_ses-test_T1w.nii.gz": "", + }, + "func": { + "sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": "", + "sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": "", + "sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": "", + } + } + } + } +) }} + +Example 4: Single metadata file applying to multiple data files (corollary 2) + +{{ MACROS___make_filetree_example( + { + "sub-01": { + "anat": {}, + "func": { + "sub-01_task-xyz_acq-test1_run-1_bold.nii.gz": "", + "sub-01_task-xyz_acq-test1_run-2_bold.nii.gz": "", + "sub-01_task-xyz_acq-test1_bold.json": "", + } + } + } +) }} + ## Participant names and other labels BIDS allows for custom user-defined `