[SCHEMA] Reorganize schema

src/schema/entities.yaml

@@ -1,138 +1,16 @@
 ---
-sub:
-  name: Subject
-  description: |
-    A person or animal participating in the study.
-  format: label
-ses:
-  name: Session
-  description: |
-    A logical grouping of neuroimaging and behavioral data consistent across
-    subjects.
-    Session can (but doesn't have to) be synonymous to a visit in a
-    longitudinal study.
-    In general, subjects will stay in the scanner during one session.
-    However, for example, if a subject has to leave the scanner room and then
-    be re-positioned on the scanner bed, the set of MRI acquisitions will still
-    be considered as a session and match sessions acquired in other subjects.
-    Similarly, in situations where different data types are obtained over
-    several visits (for example fMRI on one day followed by DWI the day after)
-    those can be grouped in one session.
-    Defining multiple sessions is appropriate when several identical or similar
-    data acquisitions are planned and performed on all -or most- subjects,
-    often in the case of some intervention between sessions (e.g., training).
-  format: label
-task:
-  name: Task
-  format: label
-  description: |
-    Each task has a unique label that MUST only consist of letters and/or
-    numbers (other characters, including spaces and underscores, are not
-    allowed).
-    Those labels MUST be consistent across subjects and sessions.
-acq:
-  name: Acquisition
-  description: |
-    The `acq-<label>` key/value pair corresponds to a custom label the
-    user MAY use to distinguish a different set of parameters used for
-    acquiring the same modality.
-    For example this should be used when a study includes two T1w images - one
-    full brain low resolution and and one restricted field of view but high
-    resolution.
-    In such case two files could have the following names:
-    `sub-01_acq-highres_T1w.nii.gz` and `sub-01_acq-lowres_T1w.nii.gz`, however
-    the user is free to choose any other label than highres and lowres as long
-    as they are consistent across subjects and sessions.
-    In case different sequences are used to record the same modality (e.g. RARE
-    and FLASH for T1w) this field can also be used to make that distinction.
-    At what level of detail to make the distinction (e.g. just between RARE and
-    FLASH, or between RARE, FLASH, and FLASHsubsampled) remains at the
-    discretion of the researcher.
-  format: label
-ce:
-  name: Contrast Enhancing Agent
-  description: |
-    The `ce-<label>` key/value can be used to distinguish
-    sequences using different contrast enhanced images.
-    The label is the name of the contrast agent.
-    The key `ContrastBolusIngredient` MAY be also be added in the JSON file,
-    with the same label.
-  format: label
-rec:
-  name: Reconstruction
-  description: |
-    The `rec-<label>` key/value can be used to distinguish
-    different reconstruction algorithms (for example ones using motion
-    correction).
-  format: label
-dir:
-  name: Phase-Encoding Direction
-  description: |
-    The `dir-<label>` key/value can be used to distinguish
-    different phase-encoding directions.
-  format: label
-run:
-  name: Run
-  description: |
-    If several scans of the same modality are acquired they MUST be indexed
-    with a key-value pair: `_run-1`, `_run-2`, ..., `_run-<index>`
-    (only nonnegative integers are allowed for the `<index>`).
-    When there is only one scan of a given type the run key MAY be omitted.
-  format: index
-mod:
-  name: Corresponding Modality
-  description: |
-    The `mod-<label>` key/value pair corresponds to modality label for defacing
-    masks, e.g., T1w, inplaneT1, referenced by a defacemask image.
-    E.g., `sub-01_mod-T1w_defacemask.nii.gz`.
-  format: label
-echo:
-  name: Echo
-  description: |
-    Multi-echo data MUST be split into one file per echo.
-    Each file shares the same name with the exception of the `_echo-<index>`
-    key/value.
-    Please note that the `<index>` denotes the number/index (in the form of a
-    nonnegative integer) of the echo not the echo time value which needs to be
-    stored in the field `EchoTime` of the separate JSON file.
-  format: index
-recording:
-  name: Recording
-  description: |
-    More than one continuous recording file can be included (with different
-    sampling frequencies).
-    In such case use different labels.
-    For example: `_recording-contrast`, `_recording-saturation`.
-  format: label
-proc:
-  name: Processed (on device)
-  description: |
-    The proc label is analogous to rec for MR and denotes a variant of a file
-    that was a result of particular processing performed on the device.
-    This is useful for files produced in particular by Elekta’s MaxFilter
-    (e.g. sss, tsss, trans, quat, mc, etc.), which some installations impose to
-    be run on raw data because of active shielding software corrections before
-    the MEG data can actually be exploited.
-  format: label
-space:
-  name: Space
-  description: |
-    The space label (`*[_space-<label>]_electrodes.tsv`) can be used
-    to indicate the way in which electrode positions are interpreted.
-    The space label needs to be taken from the list in Appendix VIII.
-  format: label
-split:
-  name: Split
-  description: |
-    In the case of long data recordings that exceed a file size of 2Gb, the
-    .fif files are conventionally split into multiple parts.
-    Each of these files has an internal pointer to the next file.
-    This is important when renaming these split recordings to the BIDS
-    convention.
-
-    Instead of a simple renaming, files should be read in and saved under their
-    new names with dedicated tools like MNE, which will ensure that not only
-    the file names, but also the internal file pointers will be updated.
-    It is RECOMMENDED that .fif files with multiple parts use the
-    `split-<index>` entity to indicate each part.
-  format: index
+# This file determines the order of entities in filenames.
+- sub
+- ses
+- task
+- acq
+- ce
+- rec
+- dir
+- run
+- mod
+- echo
+- recording
+- proc
+- space
+- split

src/schema/items/T1w.yaml

@@ -0,0 +1,17 @@
+---
+name: T1-weighted
+class: suffix
+description: |
+  T1-weighted MRI scan.
+# Suffix-specific fields
+extensions:
+  - .nii.gz
+  - .nii
+  - .json
+entities:
+  sub: required
+  ses: optional
+  run: optional
+  acq: optional
+  ce: optional
+  rec: optional

src/schema/items/acq.yaml

@@ -0,0 +1,21 @@
+---
+name: Acquisition
+class: entity
+description: |
+  The `acq-<label>` key/value pair corresponds to a custom label the
+  user MAY use to distinguish a different set of parameters used for
+  acquiring the same modality.
+  For example this should be used when a study includes two T1w images - one
+  full brain low resolution and and one restricted field of view but high
+  resolution.
+  In such case two files could have the following names:
+  `sub-01_acq-highres_T1w.nii.gz` and `sub-01_acq-lowres_T1w.nii.gz`, however
+  the user is free to choose any other label than highres and lowres as long
+  as they are consistent across subjects and sessions.
+  In case different sequences are used to record the same modality (e.g. RARE
+  and FLASH for T1w) this field can also be used to make that distinction.
+  At what level of detail to make the distinction (e.g. just between RARE and
+  FLASH, or between RARE, FLASH, and FLASHsubsampled) remains at the
+  discretion of the researcher.
+# Entity-specific fields
+format: label

src/schema/items/ce.yaml

@@ -0,0 +1,11 @@
+---
+name: Contrast Enhancing Agent
+class: entity
+description: |
+  The `ce-<label>` key/value can be used to distinguish
+  sequences using different contrast enhanced images.
+  The label is the name of the contrast agent.
+  The key `ContrastBolusIngredient` MAY be also be added in the JSON file,
+  with the same label.
+# Entity-specific fields
+format: label

src/schema/items/dir.yaml

@@ -0,0 +1,8 @@
+---
+name: Phase-Encoding Direction
+class: entity
+description: |
+  The `dir-<label>` key/value can be used to distinguish
+  different phase-encoding directions.
+# Entity-specific fields
+format: label

src/schema/items/echo.yaml

@@ -0,0 +1,12 @@
+---
+name: Echo
+class: entity
+description: |
+  Multi-echo data MUST be split into one file per echo.
+  Each file shares the same name with the exception of the `_echo-<index>`
+  key/value.
+  Please note that the `<index>` denotes the number/index (in the form of a
+  nonnegative integer) of the echo not the echo time value which needs to be
+  stored in the field `EchoTime` of the separate JSON file.
+# Entity-specific fields
+format: index

src/schema/items/mod.yaml

@@ -0,0 +1,9 @@
+---
+name: Corresponding Modality
+class: entity
+description: |
+  The `mod-<label>` key/value pair corresponds to modality label for defacing
+  masks, e.g., T1w, inplaneT1, referenced by a defacemask image.
+  E.g., `sub-01_mod-T1w_defacemask.nii.gz`.
+# Entity-specific fields
+format: label

src/schema/items/proc.yaml

@@ -0,0 +1,12 @@
+---
+name: Processed (on device)
+class: entity
+description: |
+  The proc label is analogous to rec for MR and denotes a variant of a file
+  that was a result of particular processing performed on the device.
+  This is useful for files produced in particular by Elekta’s MaxFilter
+  (e.g. sss, tsss, trans, quat, mc, etc.), which some installations impose to
+  be run on raw data because of active shielding software corrections before
+  the MEG data can actually be exploited.
+# Entity-specific fields
+format: label

src/schema/items/rec.yaml

@@ -0,0 +1,9 @@
+---
+name: Reconstruction
+class: entity
+description: |
+  The `rec-<label>` key/value can be used to distinguish
+  different reconstruction algorithms (for example ones using motion
+  correction).
+# Entity-specific fields
+format: label

src/schema/items/recording.yaml

@@ -0,0 +1,10 @@
+---
+name: Recording
+class: entity
+description: |
+  More than one continuous recording file can be included (with different
+  sampling frequencies).
+  In such case use different labels.
+  For example: `_recording-contrast`, `_recording-saturation`.
+# Entity-specific fields
+format: label

src/schema/items/run.yaml

@@ -0,0 +1,10 @@
+---
+name: Run
+class: entity
+description: |
+  If several scans of the same modality are acquired they MUST be indexed
+  with a key-value pair: `_run-1`, `_run-2`, ..., `_run-<index>`
+  (only nonnegative integers are allowed for the `<index>`).
+  When there is only one scan of a given type the run key MAY be omitted.
+# Entity-specific fields
+format: index

src/schema/items/ses.yaml

@@ -0,0 +1,20 @@
+---
+name: Session
+class: entity
+description: |
+  A logical grouping of neuroimaging and behavioral data consistent across
+  subjects.
+  Session can (but doesn't have to) be synonymous to a visit in a
+  longitudinal study.
+  In general, subjects will stay in the scanner during one session.
+  However, for example, if a subject has to leave the scanner room and then
+  be re-positioned on the scanner bed, the set of MRI acquisitions will still
+  be considered as a session and match sessions acquired in other subjects.
+  Similarly, in situations where different data types are obtained over
+  several visits (for example fMRI on one day followed by DWI the day after)
+  those can be grouped in one session.
+  Defining multiple sessions is appropriate when several identical or similar
+  data acquisitions are planned and performed on all -or most- subjects,
+  often in the case of some intervention between sessions (e.g., training).
+# Entity-specific fields
+format: label

src/schema/items/space.yaml

@@ -0,0 +1,9 @@
+---
+name: Space
+class: entity
+description: |
+  The space label (`*[_space-<label>]_electrodes.tsv`) can be used
+  to indicate the way in which electrode positions are interpreted.
+  The space label needs to be taken from the list in Appendix VIII.
+# Entity-specific fields
+format: label

src/schema/items/split.yaml

@@ -0,0 +1,17 @@
+---
+name: Split
+class: entity
+description: |
+  In the case of long data recordings that exceed a file size of 2Gb, the
+  .fif files are conventionally split into multiple parts.
+  Each of these files has an internal pointer to the next file.
+  This is important when renaming these split recordings to the BIDS
+  convention.
+
+  Instead of a simple renaming, files should be read in and saved under their
+  new names with dedicated tools like MNE, which will ensure that not only
+  the file names, but also the internal file pointers will be updated.
+  It is RECOMMENDED that .fif files with multiple parts use the
+  `split-<index>` entity to indicate each part.
+# Entity-specific fields
+format: index

src/schema/items/sub.yaml

@@ -0,0 +1,7 @@
+---
+name: Subject
+class: entity
+description: |
+  A person or animal participating in the study.
+# Entity-specific fields
+format: label

src/schema/items/task.yaml

@@ -0,0 +1,10 @@
+---
+name: Task
+class: entity
+description: |
+  Each task has a unique label that MUST only consist of letters and/or
+  numbers (other characters, including spaces and underscores, are not
+  allowed).
+  Those labels MUST be consistent across subjects and sessions.
+# Entity-specific fields
+format: label