New datasets for demonstrating / validating the Inheritance principle

ip112badmetapathe1/README.txt

@@ -0,0 +1,36 @@
+The following exerpt is duplicated from version 1.1.2
+of the Brain Imaging Data Structure (BIDS) specification:
+
+    Files for a particular participant can exist only at participant level directory,
+    i.e /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 eg: task-sist_bold.json must be placed under /dataset/task-sist_bold.json.
+
+Notes:
+
+-   There are two potential issues with the issue as described:
+
+    -   The T1-weighted image is not placed inside the "anat/" modality directory
+        as would be conventionally expected / is most common,
+        and the file name fails to account for the potential presence of the "ses" entity.
+        The example path would more suitably have been:
+        /dataset/sub-*[/ses-*]/anat/sub-*[_ses-*]_T1w.json.
+
+    -   The description fails to clarify that such files can be placed
+        only within *one of* potentially *multiple* "participant-level directories".
+        As exemplified by other Inheritance Principle examples,
+        it is permissible for metadata files to exist at a filesystem location
+        other than the lowest level modality directory.
+        The description fails to convey the fact that the example filesystem path presented
+        is only one of multiple possible parent directories for such a file;
+        for instance, location /dataset/sub-*[/ses-*]/sub-*[_ses-*]_T1w.json
+        is technically permissible also.
+
+-   This particular dataset exemplifies violation of the first criterion.
+    Violation of the second criterion is exemplified
+    in sister datasets "ip112badmetapathe2v1" and "ip112badmetapathe2v2".
+
+-   There are intentionally two T1w runs for sub-01
+    so that the dataset does not trigger a warning
+    regarding an exclusively-matched non-sidecar data-metadata file pair.

ip112badmetapathe1/dataset_description.json

@@ -0,0 +1,9 @@
+{
+    "Authors": [
+        "Robert E. Smith <[email protected]>"
+    ],
+    "BIDSVersion": "1.1.2",
+    "DatasetType": "raw",
+    "Name": "Inheritance Principle validation; specification version 1.1.2; bad metadata path; example 1"
+}
+

ip112badmetapathe1/sourcedata/ip_graph.json

@@ -0,0 +1,18 @@
+{
+    "sub-01_T1w.json": [
+        "sub-01/anat/sub-01_run-1_T1w.nii.gz",
+        "sub-01/anat/sub-01_run-2_T1w.nii.gz"
+    ],
+    "sub-01/anat/sub-01_run-1_T1w.nii.gz": {
+        ".json": [
+            "sub-01_T1w.json"
+        ]
+    },
+    "sub-01/anat/sub-01_run-2_T1w.nii.gz": {
+        ".json": [
+            "sub-01_T1w.json"
+        ]
+    },
+    "sub-02/anat/sub-02_T1w.nii.gz": {
+    }
+}

ip112badmetapathe1/sourcedata/ip_metadata.json

@@ -0,0 +1,14 @@
+{
+    "sub-01/anat/sub-01_run-1_T1w.nii.gz": {
+        ".json": {
+            "Sub01T1w": true
+        }
+    },
+    "sub-01/anat/sub-01_run-2_T1w.nii.gz": {
+        ".json": {
+            "Sub01T1w": true
+        }
+    },
+    "sub-02/anat/sub-02_T1w.nii.gz": {
+    }
+}

ip112badmetapathe1/sub-01_T1w.json

@@ -0,0 +1,3 @@
+{
+    "Sub01T1w": true
+}

ip112badmetapathe2v1/README.txt

@@ -0,0 +1,23 @@
+The following exerpt is duplicated from version 1.1.2
+of the Brain Imaging Data Structure (BIDS) specification:
+
+    Files for a particular participant can exist only at participant level directory,
+    i.e /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 eg: task-sist_bold.json must be placed under /dataset/task-sist_bold.json.
+
+Notes:
+
+-   This particular dataset exemplifies violation of the second criterion.
+    Violation of the first criterion is exemplified in sister dataset "ip112badmetapathe1".
+
+-   In this first version of the example,
+    the derivative Inheritance Principle criterion
+    defined in version 1.7.0 of the specification
+    *is* also violated,
+    as the erroneous placement of the participant-agnosticcally-named metadata file
+    is violated by the presence of another participant to which the metadata file name matches.
+    A modified version of this example,
+    where that corresponding 1.7.0 version criterion is *not* violated,
+    is presented in sister dataset "ip112badmetapathe1v2".

ip112badmetapathe2v1/dataset_description.json

@@ -0,0 +1,9 @@
+{
+    "Authors": [
+        "Robert E. Smith <[email protected]>"
+    ],
+    "BIDSVersion": "1.1.2",
+    "DatasetType": "raw",
+    "Name": "Inheritance Principle validation; specification version 1.1.2; bad metadata path; example 1; version 1"
+}
+

ip112badmetapathe2v1/sourcedata/ip_graph.json

@@ -0,0 +1,18 @@
+{
+    "sub-01/task-sist_bold.json": [
+        "sub-01/func/sub-01_task-sist_run-1_bold.nii.gz",
+        "sub-01/func/sub-01_task-sist_run-2_bold.nii.gz"
+    ],
+    "sub-01/func/sub-01_task-sist_run-1_bold.nii.gz": {
+        ".json": [
+            "sub-01/task-sist_bold.json"
+        ]
+    },
+    "sub-01/func/sub-01_task-sist_run-2_bold.nii.gz": {
+        ".json": [
+            "sub-01/task-sist_bold.json"
+        ]
+    },
+    "sub-02/func/sub-02_task-sist_bold.nii.gz": {
+    }
+}

ip112badmetapathe2v1/sourcedata/ip_metadata.json

@@ -0,0 +1,16 @@
+{
+    "sub-01/func/sub-01_task-sist_run-1_bold.nii.gz": {
+        ".json": {
+            "RepetitionTime": 1.0,
+            "TaskName": "SIST"
+        }
+    },
+    "sub-01/func/sub-01_task-sist_run-2_bold.nii.gz": {
+        ".json": {
+            "RepetitionTime": 1.0,
+            "TaskName": "SIST"
+        }
+    },
+    "sub-02/func/sub-02_task-sist_bold.nii.gz": {
+    }
+}

ip112badmetapathe2v1/sub-01/task-sist_bold.json

@@ -0,0 +1,4 @@
+{
+    "RepetitionTime": 1.0,
+    "TaskName": "SIST"
+}

ip112badmetapathe2v2/README.txt

@@ -0,0 +1,24 @@
+The following exerpt is duplicated from version 1.1.2
+of the Brain Imaging Data Structure (BIDS) specification:
+
+    Files for a particular participant can exist only at participant level directory,
+    i.e /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 eg: task-sist_bold.json must be placed under /dataset/task-sist_bold.json.
+
+Notes:
+
+-   This particular dataset exemplifies violation of the second criterion.
+    Violation of the first criterion is exemplified in sister dataset "ip112badmetapathe1".
+
+-   In this second version of the example,
+    the derivative Inheritance Principle criterion
+    defined in version 1.7.0 of the specification
+    *is not* violated:
+    the erroneous placement of the participant-agnosticcally-named metadata file
+    nevertheless does not actually cause any data - metadata associations
+    that violate the corresponding criterion as written.
+    Another version of this example,
+    where that corresponding 1.7.0 version criterion *is* violated,
+    is presented in sister dataset "ip112badmetapathe1v1".

ip112badmetapathe2v2/dataset_description.json

@@ -0,0 +1,9 @@
+{
+    "Authors": [
+        "Robert E. Smith <[email protected]>"
+    ],
+    "BIDSVersion": "1.1.2",
+    "DatasetType": "raw",
+    "Name": "Inheritance Principle validation; specification version 1.1.2; bad metadata path; example 1; version 2"
+}
+

ip112badmetapathe2v2/sourcedata/ip_graph.json

@@ -0,0 +1,16 @@
+{
+    "sub-01/task-sist_bold.json": [
+        "sub-01/func/sub-01_task-sist_run-1_bold.nii.gz",
+        "sub-01/func/sub-01_task-sist_run-2_bold.nii.gz"
+    ],
+    "sub-01/func/sub-01_task-sist_run-1_bold.nii.gz": {
+        ".json": [
+            "sub-01/task-sist_bold.json"
+        ]
+    },
+    "sub-01/func/sub-01_task-sist_run-2_bold.nii.gz": {
+        ".json": [
+            "sub-01/task-sist_bold.json"
+        ]
+    }
+}

ip112badmetapathe2v2/sourcedata/ip_metadata.json

@@ -0,0 +1,14 @@
+{
+    "sub-01/func/sub-01_task-sist_run-1_bold.nii.gz": {
+        ".json": {
+            "RepetitionTime": 1.0,
+            "TaskName": "SIST"
+        }
+    },
+    "sub-01/func/sub-01_task-sist_run-2_bold.nii.gz": {
+        ".json": {
+            "RepetitionTime": 1.0,
+            "TaskName": "SIST"
+        }
+    }
+}

ip112badmetapathe2v2/sub-01/task-sist_bold.json

@@ -0,0 +1,4 @@
+{
+    "RepetitionTime": 1.0,
+    "TaskName": "SIST"
+}

ip112e1bad/README.txt

@@ -0,0 +1,34 @@
+The following exerpt is duplicated from version 1.1.2
+of the Brain Imaging Data Structure (BIDS) specification:
+
+    Example 1: Two JSON files at same level that are applicable for NIfTI file.
+
+    sub-01/
+        ses-test/
+            sub-test_task-overtverbgeneration_bold.json
+            sub-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
+
+    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 task-overtverbgeneration_run-2_bold.json should have been under sub-01/ses-test/func/.
+
+Notes:
+
+-   There is an error in the filesystem structure shown.
+    Files "sub-test_task-overtverbgeneration_*bold.json" erroneously combine
+    entities "sub-01" and "ses-test" implied by the directory structure
+    into entity "ses-test" in these file names.
+    This error is rectified in the realised dataset,
+    as it is not the aspect of specification non-conformity that is of interest.
+
+-   This dataset is *intended to be non-conformant*.
+    Its evaluation under the ruleset of the Inheritance Principle
+    corresponding to this version of the specification
+    should therefore fail.
+
+-   The "Instead ... " proposal as to how this exemplar dataset
+    should be modified in order to become conformant
+    is realised in sister dataset "ip112e1good".

ip112e1bad/dataset_description.json

@@ -0,0 +1,9 @@
+{
+    "Authors": [
+        "Robert E. Smith <[email protected]>"
+    ],
+    "BIDSVersion": "1.1.2",
+    "DatasetType": "raw",
+    "Name": "Inheritance Principle validation; BIDS version 1.1.2; example 1; non-compliant version"
+}
+

ip112e1bad/sourcedata/ip_graph.json

@@ -0,0 +1,22 @@
+{
+    "sub-01/ses-test/sub-01_ses-test_task-overtverbgeneration_bold.json": [
+        "sub-01/ses-test/func/sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz",
+        "sub-01/ses-test/func/sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz"
+    ],
+    "sub-01/ses-test/sub-01_ses-test_task-overtverbgeneration_run-2_bold.json": [
+        "sub-01/ses-test/func/sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz"
+    ],
+    "sub-01/ses-test/anat/sub-01_ses-test_T1w.nii.gz": {
+    },
+    "sub-01/ses-test/func/sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": {
+        ".json": [
+            "sub-01/ses-test/sub-01_ses-test_task-overtverbgeneration_bold.json"
+        ]
+    },
+    "sub-01/ses-test/func/sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": {
+        ".json": [
+            "sub-01/ses-test/sub-01_ses-test_task-overtverbgeneration_bold.json",
+            "sub-01/ses-test/sub-01_ses-test_task-overtverbgeneration_run-2_bold.json"
+        ]
+    }
+}

ip112e1bad/sourcedata/ip_metadata.json

@@ -0,0 +1,16 @@
+{
+    "sub-01/ses-test/anat/sub-01_ses-test_T1w.nii.gz": {
+    },
+    "sub-01/ses-test/func/sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz": {
+        ".json": {
+            "RepetitionTime": 1.0,
+            "TaskName": "OvertVerbGeneration"
+        }
+    },
+    "sub-01/ses-test/func/sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz": {
+        ".json": {
+            "RepetitionTime": 1.0,
+            "TaskName": "OvertVerbGeneration"
+        }
+    }
+}

ip112e1bad/sub-01/ses-test/sub-01_ses-test_task-overtverbgeneration_bold.json

@@ -0,0 +1,5 @@
+{
+    "RepetitionTime": 1.0,
+    "TaskName": "OvertVerbGeneration"
+}
+

ip112e1bad/sub-01/ses-test/sub-01_ses-test_task-overtverbgeneration_run-2_bold.json

@@ -0,0 +1,3 @@
+{
+}
+

ip112e1good/README.txt

@@ -0,0 +1,44 @@
+From the relevant section of version 1.1.2
+of the Brain Imaging Data Structure (BIDS) specification:
+
+    Example 1: Two JSON files at same level that are applicable for NIfTI file.
+
+    sub-01/
+        ses-test/
+            sub-test_task-overtverbgeneration_bold.json
+            sub-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
+    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 task-overtverbgeneration_run-2_bold.json should have been under sub-01/ses-test/func/.
+
+Notes:
+
+-   The filesystem layout described in the specification is erroneous.
+    Files "sub-test_task-overtverbgeneration*_bold.json" erroneously combine entities
+    "sub-01" and "ses-test" implied by the directory structure
+    into entity "sub-test" in the file names.
+    This error is corrected in this realised dataset.
+
+-   This dataset *incorporates* the suggestion made at the end of this section
+    of how to modify the filesystem layout in order to make the dataset conformant.
+
+    The actual layout of this dataset is therefore:
+
+    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.json
+                sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz
+
+    As such, this dataset is expected to be determined conformant.
+
+-   The (fixed) dataset as originally described in the specification,
+    absent the rectification described above to conform specifically to the Inheritance Principle,
+    is realised in sister dataset "ip112e1bad".

ip112e1good/dataset_description.json

@@ -0,0 +1,9 @@
+{
+    "Authors": [
+        "Robert E. Smith <[email protected]>"
+    ],
+    "BIDSVersion": "1.1.2",
+    "DatasetType": "raw",
+    "Name": "Inheritance Principle validation; BIDS version 1.1.2; example 1; compliant version"
+}
+