From 7be4c855d25ae95bd1b7880a93cc70c129f9ea00 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Mon, 7 Feb 2022 13:49:41 -0500
Subject: [PATCH 1/8] RF: move .bids into .bids/ subpackage and move tests
 along

This would open for a better structuring of BIDS support code etc.

All bids.utils are imported within bids/__init__.py so there should be
no effect on imports from heudiconv.bids
---
 heudiconv/bids/__init__.py                                | 1 +
 heudiconv/bids/tests/__init__.py                          | 0
 .../{tests/test_bids.py => bids/tests/test_utils.py}      | 4 ++--
 heudiconv/{bids.py => bids/utils.py}                      | 8 ++++----
 4 files changed, 7 insertions(+), 6 deletions(-)
 create mode 100644 heudiconv/bids/__init__.py
 create mode 100644 heudiconv/bids/tests/__init__.py
 rename heudiconv/{tests/test_bids.py => bids/tests/test_utils.py} (99%)
 rename heudiconv/{bids.py => bids/utils.py} (99%)

diff --git a/heudiconv/bids/__init__.py b/heudiconv/bids/__init__.py
new file mode 100644
index 00000000..16281fe0
--- /dev/null
+++ b/heudiconv/bids/__init__.py
@@ -0,0 +1 @@
+from .utils import *
diff --git a/heudiconv/bids/tests/__init__.py b/heudiconv/bids/tests/__init__.py
new file mode 100644
index 00000000..e69de29b
diff --git a/heudiconv/tests/test_bids.py b/heudiconv/bids/tests/test_utils.py
similarity index 99%
rename from heudiconv/tests/test_bids.py
rename to heudiconv/bids/tests/test_utils.py
index 8716bb59..4e70e7b6 100644
--- a/heudiconv/tests/test_bids.py
+++ b/heudiconv/bids/tests/test_utils.py
@@ -28,7 +28,7 @@
     remove_suffix,
 )
 
-from heudiconv.bids import (
+from .. import (
     maybe_na,
     treat_age,
     find_fmap_groups,
@@ -44,7 +44,7 @@
     BIDSFile,
 )
 
-from .utils import (
+from heudiconv.tests.utils import (
     TESTS_DATA_PATH,
 )
 
diff --git a/heudiconv/bids.py b/heudiconv/bids/utils.py
similarity index 99%
rename from heudiconv/bids.py
rename to heudiconv/bids/utils.py
index 40deb1e5..66a2b2ff 100644
--- a/heudiconv/bids.py
+++ b/heudiconv/bids/utils.py
@@ -13,10 +13,10 @@
 from glob import glob
 import errno
 
-from .external.pydicom import dcm
+from ..external.pydicom import dcm
 
-from .parser import find_files
-from .utils import (
+from ..parser import find_files
+from ..utils import (
     load_json,
     save_json,
     create_file_if_missing,
@@ -28,7 +28,7 @@
     remove_suffix,
     remove_prefix,
 )
-from . import __version__
+from .. import __version__
 
 lgr = logging.getLogger(__name__)
 

From 2ff3b98e1be94335ef994033697f73155d1c3e37 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Mon, 7 Feb 2022 13:53:33 -0500
Subject: [PATCH 2/8] Add entities objects+rules from bids v1.7.0

ATM we will need only these two files to establish consistent
order of the entities in the filenames.  Later we might want to
carry a more complete copy of the schema, or may be eventually some
proper  bidsschema  python package would appear to provide desired
functionality anyways
---
 .../bids/data/schema/objects/entities.yaml    | 356 ++++++++++++++++++
 .../bids/data/schema/rules/entities.yaml      |  30 ++
 setup.py                                      |   3 +
 3 files changed, 389 insertions(+)
 create mode 100644 heudiconv/bids/data/schema/objects/entities.yaml
 create mode 100644 heudiconv/bids/data/schema/rules/entities.yaml

diff --git a/heudiconv/bids/data/schema/objects/entities.yaml b/heudiconv/bids/data/schema/objects/entities.yaml
new file mode 100644
index 00000000..3df87f7e
--- /dev/null
+++ b/heudiconv/bids/data/schema/objects/entities.yaml
@@ -0,0 +1,356 @@
+---
+# This file describes entities present in BIDS filenames.
+# WARNING: The entities are presented here in alphabetical order!
+# The appropriate order of entities in filenames is defined in `rules/entities.yaml`,
+# rather than this file (`objects/entities.yaml`).
+acquisition:
+  name: Acquisition
+  entity: acq
+  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 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
+    (for example, `RARE` and `FLASH` for T1w)
+    this field can also be used to make that distinction.
+    At what level of detail to make the distinction (for example,
+    just between `RARE` and `FLASH`, or between `RARE`, `FLASH`, and `FLASHsubsampled`)
+    remains at the discretion of the researcher.
+  type: string
+  format: label
+ceagent:
+  name: Contrast Enhancing Agent
+  entity: ce
+  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 also be added in the JSON file,
+    with the same label.
+  type: string
+  format: label
+chunk:
+  name: Chunk
+  entity: chunk
+  description: |
+    The `chunk-<index>` key/value pair is used to distinguish between different
+    regions, 2D images or 3D volumes files, of the same physical sample with
+    different fields of view acquired in the same imaging experiment.
+  type: string
+  format: index
+density:
+  name: Density
+  entity: den
+  description: |
+    Density of non-parametric surfaces.
+    MUST have a corresponding `Density` metadata field to provide
+    interpretation.
+
+    This entity is only applicable to derivative data.
+  type: string
+  format: label
+description:
+  name: Description
+  entity: desc
+  description: |
+    When necessary to distinguish two files that do not otherwise have a
+    distinguishing entity, the `_desc-<label>` keyword-value SHOULD be used.
+
+    This entity is only applicable to derivative data.
+  type: string
+  format: label
+direction:
+  name: Phase-Encoding Direction
+  entity: dir
+  description: |
+    The `dir-<label>` key/value can be set to an arbitrary alphanumeric label
+    (for example, `dir-LR` or `dir-AP`) to distinguish different phase-encoding
+    directions.
+  type: string
+  format: label
+echo:
+  name: Echo
+  entity: echo
+  description: |
+    If files belonging to an entity-linked file collection are acquired at different
+    echo times, the `_echo-<index>` key/value pair MUST be used to distinguish
+    individual files.
+    This entity represents the `"EchoTime"` metadata field. Please note that the `<index>`
+    denotes the number/index (in the form of a nonnegative integer), not the
+    `"EchoTime"` value which needs to be stored in the field `"EchoTime"` of the separate
+    JSON file.
+  type: string
+  format: index
+flip:
+  name: Flip Angle
+  entity: flip
+  description: |
+    If files belonging to an entity-linked file collection are acquired at different
+    flip angles, the `_flip-<index>` key/value pair MUST be used to distinguish
+    individual files.
+    This entity represents the `"FlipAngle"` metadata field. Please note that the `<index>`
+    denotes the number/index (in the form of a nonnegative integer), not the `"FlipAngle"`
+    value which needs to be stored in the field `"FlipAngle"` of the separate JSON file.
+  type: string
+  format: index
+hemisphere:
+  name: Hemisphere
+  entity: hemi
+  description: |
+    The `hemi-<label>` entity indicates which hemibrain is described by the file.
+    Allowed label values for this entity are `L` and `R`, for the left and right
+    hemibrains, respectively.
+  type: string
+  format: label
+  enum:
+  - "L"
+  - "R"
+inversion:
+  name: Inversion Time
+  entity: inv
+  description: |
+    If files belonging to an entity-linked file collection are acquired at different
+    inversion times, the `_inv-<index>` key/value pair MUST be used to distinguish
+    individual files.
+    This entity represents the `"InversionTime` metadata field. Please note that the `<index>`
+    denotes the number/index (in the form of a nonnegative integer), not the `"InversionTime"`
+    value which needs to be stored in the field `"InversionTime"` of the separate JSON file.
+  type: string
+  format: index
+label:
+  name: Label
+  entity: label
+  description: |
+    Tissue-type label, following a prescribed vocabulary.
+    Applies to binary masks and probabilistic/partial volume segmentations
+    that describe a single tissue type.
+
+    This entity is only applicable to derivative data.
+  type: string
+  format: label
+modality:
+  name: Corresponding Modality
+  entity: mod
+  description: |
+    The `mod-<label>` key/value pair corresponds to modality label for defacing
+    masks, for example, T1w, inplaneT1, referenced by a defacemask image.
+    For example, `sub-01_mod-T1w_defacemask.nii.gz`.
+  type: string
+  format: label
+mtransfer:
+  name: Magnetization Transfer
+  entity: mt
+  description: |
+    If files belonging to an entity-linked file collection are acquired at different
+    magnetization transfer (MT) states, the `_mt-<label>` key/value pair MUST be used to
+    distinguish individual files.
+    This entity represents the `"MTState"` metadata field. Allowed label values for this
+    entity are `on` and `off`, for images acquired in presence and absence of an MT pulse,
+    respectively.
+  type: string
+  enum:
+  - "on"
+  - "off"
+part:
+  name: Part
+  entity: part
+  description: |
+    This entity is used to indicate which component of the complex
+    representation of the MRI signal is represented in voxel data.
+    The `part-<label>` key/value pair is associated with the DICOM Tag
+    `0008, 9208`.
+    Allowed label values for this entity are `phase`, `mag`, `real` and `imag`,
+    which are typically used in `part-mag`/`part-phase` or
+    `part-real`/`part-imag` pairs of files.
+
+    Phase images MAY be in radians or in arbitrary units.
+    The sidecar JSON file MUST include the units of the `phase` image.
+    The possible options are `"rad"` or `"arbitrary"`.
+
+    When there is only a magnitude image of a given type, the `part` key MAY be
+    omitted.
+  type: string
+  enum:
+  - mag
+  - phase
+  - real
+  - imag
+processing:
+  name: Processed (on device)
+  entity: proc
+  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
+    (for example, `sss`, `tsss`, `trans`, `quat` or `mc`),
+    which some installations impose to be run on raw data because of active
+    shielding software corrections before the MEG data can actually be
+    exploited.
+  type: string
+  format: label
+reconstruction:
+  name: Reconstruction
+  entity: rec
+  description: |
+    The `rec-<label>` key/value can be used to distinguish
+    different reconstruction algorithms (for example `MoCo` for the ones using motion
+    correction).
+  type: string
+  format: label
+recording:
+  name: Recording
+  entity: 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`.
+  type: string
+  format: label
+resolution:
+  name: Resolution
+  entity: res
+  description: |
+    Resolution of regularly sampled N-dimensional data.
+    MUST have a corresponding `"Resolution"` metadata field to provide
+    interpretation.
+
+    This entity is only applicable to derivative data.
+  type: string
+  format: label
+run:
+  name: Run
+  entity: run
+  description: |
+    If several scans with the same acquisition parameters are acquired in the same session,
+    they MUST be indexed with the [`run-<index>`](../99-appendices/09-entities.md#run) entity:
+    `_run-1`, `_run-2`, `_run-3`, and so on (only nonnegative integers are allowed as
+    run labels).
+
+    If different entities apply,
+    such as a different session indicated by [`ses-<label>`](../99-appendices/09-entities.md#ses),
+    or different acquisition parameters indicated by
+    [`acq-<label>`](../99-appendices/09-entities.md#acq),
+    then `run` is not needed to distinguish the scans and MAY be omitted.
+  type: string
+  format: index
+sample:
+  name: Sample
+  entity: sample
+  description: |
+    A sample pertaining to a subject such as tissue, primary cell
+    or cell-free sample.
+    The `sample-<label>` key/value pair is used to distinguish between different
+    samples from the same subject.
+    The label MUST be unique per subject and is RECOMMENDED to be unique
+    throughout the dataset.
+  type: string
+  format: label
+session:
+  name: Session
+  entity: ses
+  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
+    (for example, training).
+  type: string
+  format: label
+space:
+  name: Space
+  entity: space
+  description: |
+    The space entity can be used to indicate
+    the way in which electrode positions are interpreted
+    (for EEG/MEG/iEEG data) or
+    the spatial reference to which a file has been aligned (for MRI data).
+    The space `<label>` MUST be taken from one of the modality specific lists in
+    [Appendix VIII](../99-appendices/08-coordinate-systems.md).
+    For example for iEEG data, the restricted keywords listed under
+    [iEEG Specific Coordinate Systems](../99-appendices/08-coordinate-systems.md#ieeg-specific-coordinate-systems)
+    are acceptable for `<label>`.
+
+    For EEG/MEG/iEEG data, this entity can be applied to raw data, but
+    for other data types, it is restricted to derivative data.
+  type: string
+  format: label
+split:
+  name: Split
+  entity: 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-Python](https://mne.tools/),
+    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.
+    If there are multiple parts of a recording and the optional `scans.tsv` is provided,
+    remember to list all files separately in `scans.tsv` and that the entries for the
+    `acq_time` column in `scans.tsv` MUST all be identical, as described in
+    [Scans file](../03-modality-agnostic-files.md#scans-file).
+  type: string
+  format: index
+stain:
+  name: Stain
+  entity: stain
+  description: |
+    The `stain-<label>` key/pair values can be used to distinguish image files
+    from the same sample using different stains or antibodies for contrast enhancement.
+    Stains SHOULD be indicated in the `"SampleStaining"` key in the sidecar JSON file,
+    although the label may be different.
+    Description of antibodies SHOULD also be indicated in `"SamplePrimaryAntibodies"`
+    and/or `"SampleSecondaryAntobodies"` as appropriate.
+  type: string
+  format: label
+subject:
+  name: Subject
+  entity: sub
+  description: |
+    A person or animal participating in the study.
+  type: string
+  format: label
+task:
+  name: Task
+  entity: task
+  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.
+  type: string
+  format: label
+tracer:
+  name: Tracer
+  entity: trc
+  description: |
+    The `trc-<label>` key/value can be used to distinguish
+    sequences using different tracers.
+    The key `"TracerName"` MUST also be included in the associated JSON file,
+    although the label may be different.
+  type: string
+  format: label
diff --git a/heudiconv/bids/data/schema/rules/entities.yaml b/heudiconv/bids/data/schema/rules/entities.yaml
new file mode 100644
index 00000000..3590bea8
--- /dev/null
+++ b/heudiconv/bids/data/schema/rules/entities.yaml
@@ -0,0 +1,30 @@
+---
+# This file simply defines the order in which entities should appear within filenames.
+# Entity definitions appear in the `objects/entities.yaml` file.
+- subject
+- session
+- sample
+- task
+- acquisition
+- ceagent
+- tracer
+- stain
+- reconstruction
+- direction
+- run
+- modality
+- echo
+- flip
+- inversion
+- mtransfer
+- part
+- processing
+- hemisphere
+- space
+- split
+- recording
+- chunk
+- resolution
+- density
+- label
+- description
diff --git a/setup.py b/setup.py
index 686d71d9..1515ee8d 100755
--- a/setup.py
+++ b/setup.py
@@ -59,6 +59,9 @@ def findsome(subdir, extensions):
                         op.join('data', '*.dcm'),
                         op.join('data', '*', '*.dcm')
             ],
+            'heudiconv.bids.data.schema': [
+                '*/*.yaml'
+            ],
         }
     )
 

From 8d9c48df58fb4505282d876366e2854709833b4c Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Tue, 29 Mar 2022 14:08:46 -0400
Subject: [PATCH 3/8] RF: boost the BIDS version we list to 1.7.0 since that is
 what schema will be from

---
 heudiconv/bids/utils.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/heudiconv/bids/utils.py b/heudiconv/bids/utils.py
index 66a2b2ff..72efe750 100644
--- a/heudiconv/bids/utils.py
+++ b/heudiconv/bids/utils.py
@@ -54,7 +54,7 @@ class BIDSError(Exception):
     pass
 
 
-BIDS_VERSION = "1.4.1"
+BIDS_VERSION = "1.7.0"
 
 # List defining allowed parameter matching for fmap assignment:
 SHIM_KEY = 'ShimSetting'

From 7f9d585a4fa65deb4607c8fd06fac4a7189783ee Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Mon, 7 Feb 2022 14:16:23 -0500
Subject: [PATCH 4/8] ENH: added populating order of entities from bids schema
 copy

---
 heudiconv/bids/schema.py | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)
 create mode 100644 heudiconv/bids/schema.py

diff --git a/heudiconv/bids/schema.py b/heudiconv/bids/schema.py
new file mode 100644
index 00000000..3c271b98
--- /dev/null
+++ b/heudiconv/bids/schema.py
@@ -0,0 +1,30 @@
+from pathlib import Path
+import yaml
+
+
+def _load_entities_order():
+    # we carry the copy of the schema
+    schema_p = Path(__file__).parent / "data" / "schema"
+    with (schema_p / "objects" / "entities.yaml").open() as f:
+        entities = yaml.load(f)
+
+    with (schema_p / "rules" / "entities.yaml").open() as f:
+        entities_full_order = yaml.load(f)
+
+    # map from full name to short "entity"
+    return [entities[e]["entity"] for e in entities_full_order]
+
+
+class BIDSFile:
+    """ as defined in https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html
+    which might soon become machine readable
+    order matters
+    """
+
+    _known_entities = _load_entities_order()
+
+
+# TEMP: just for now, could be moved/removed
+def test_BIDSFile():
+    assert BIDSFile._known_entities[:2] == ['sub', 'ses']
+    print(BIDSFile._known_entities)
\ No newline at end of file

From 08390bdd621aa3de6be1016f20eb048fdb557c89 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Tue, 29 Mar 2022 14:22:08 -0400
Subject: [PATCH 5/8] RF: move BIDSFile into bids.schema and make it load
 ordered entities from schema

---
 heudiconv/bids/schema.py            | 93 ++++++++++++++++++++++++++--
 heudiconv/bids/tests/test_schema.py | 76 +++++++++++++++++++++++
 heudiconv/bids/tests/test_utils.py  | 68 +--------------------
 heudiconv/bids/utils.py             | 94 +----------------------------
 4 files changed, 167 insertions(+), 164 deletions(-)
 create mode 100644 heudiconv/bids/tests/test_schema.py

diff --git a/heudiconv/bids/schema.py b/heudiconv/bids/schema.py
index 3c271b98..5d127b96 100644
--- a/heudiconv/bids/schema.py
+++ b/heudiconv/bids/schema.py
@@ -1,15 +1,22 @@
 from pathlib import Path
+import re
 import yaml
 
+from heudiconv.utils import remove_prefix
+
+import logging
+
+lgr = logging.getLogger(__name__)
+
 
 def _load_entities_order():
     # we carry the copy of the schema
     schema_p = Path(__file__).parent / "data" / "schema"
     with (schema_p / "objects" / "entities.yaml").open() as f:
-        entities = yaml.load(f)
+        entities = yaml.load(f, yaml.SafeLoader)
 
     with (schema_p / "rules" / "entities.yaml").open() as f:
-        entities_full_order = yaml.load(f)
+        entities_full_order = yaml.load(f, yaml.SafeLoader)
 
     # map from full name to short "entity"
     return [entities[e]["entity"] for e in entities_full_order]
@@ -23,8 +30,82 @@ class BIDSFile:
 
     _known_entities = _load_entities_order()
 
+    def __init__(self, entities, suffix, extension):
+        self._entities = entities
+        self._suffix = suffix
+        self._extension = extension
+
+    def __eq__(self, other):
+        if not isinstance(other, self.__class__):
+            return False
+        if (
+            all([other[k] == v for k, v in self._entities.items()])
+            and self.extension == other.extension
+            and self.suffix == other.suffix
+        ):
+            return True
+        else:
+            return False
+
+    @classmethod
+    def parse(cls, filename):
+        """ Parse the filename for BIDS entities, suffix and extension """
+        # use re.findall to find all lower-case-letters + '-' + alphanumeric + '_' pairs:
+        entities_list = re.findall('([a-z]+)-([a-zA-Z0-9]+)[_]*', filename)
+        # keep only those in the _known_entities list:
+        entities = {k: v for k, v in entities_list if k in BIDSFile._known_entities}
+        # get whatever comes after the last key-value pair, and remove any '_' that
+        # might come in front:
+        ending = filename.split('-'.join(entities_list[-1]))[-1]
+        ending = remove_prefix(ending, '_')
+        # the first dot ('.') separates the suffix from the extension:
+        if '.' in ending:
+            suffix, extension = ending.split('.', 1)
+        else:
+            suffix, extension = ending, None
+        return BIDSFile(entities, suffix, extension)
+
+    def __str__(self):
+        """ reconstitute in a legit BIDS filename using the order from entity table """
+        if 'sub' not in self._entities:
+            raise ValueError('The \'sub-\' entity is mandatory')
+        # reconstitute the ending for the filename:
+        suffix = '_' + self.suffix if self.suffix else ''
+        extension = '.' + self.extension if self.extension else ''
+        return '_'.join(
+            ['-'.join([e, self._entities[e]]) for e in self._known_entities if e in self._entities]
+        ) + suffix + extension
+
+    def __getitem__(self, entity):
+        return self._entities[entity] if entity in self._entities else None
+
+    def __setitem__(self, entity, value):  # would puke with some exception if already known
+        return self.set(entity, value, overwrite=False)
+
+    def set(self, entity, value, overwrite=True):
+        if entity not in self._entities:
+            # just set it; no complains here
+            self._entities[entity] = value
+        elif overwrite:
+            lgr.warning("Overwriting the entity %s from %s to %s for file %s",
+                        str(entity),
+                        str(self[entity]),
+                        str(value),
+                        self.__str__()
+                        )
+            self._entities[entity] = value
+        else:
+            # if it already exists, and overwrite is false:
+            lgr.warning("Setting the entity %s to %s for file %s failed",
+                        str(entity),
+                        str(value),
+                        self.__str__()
+                        )
+
+    @property  # as needed make them RW
+    def suffix(self):
+        return self._suffix
 
-# TEMP: just for now, could be moved/removed
-def test_BIDSFile():
-    assert BIDSFile._known_entities[:2] == ['sub', 'ses']
-    print(BIDSFile._known_entities)
\ No newline at end of file
+    @property
+    def extension(self):
+        return self._extension
diff --git a/heudiconv/bids/tests/test_schema.py b/heudiconv/bids/tests/test_schema.py
new file mode 100644
index 00000000..2aac1968
--- /dev/null
+++ b/heudiconv/bids/tests/test_schema.py
@@ -0,0 +1,76 @@
+from collections import OrderedDict
+from random import shuffle
+
+import pytest
+
+from heudiconv.bids import BIDSFile
+
+
+def test_BIDSFile_known_entries():
+    assert BIDSFile._known_entities[:2] == ['sub', 'ses']
+    assert len(BIDSFile._known_entities) > 10  # we do have many
+    assert 'run' in BIDSFile._known_entities
+
+
+def test_BIDSFile():
+    """ Tests for the BIDSFile class """
+
+    # define entities in the correct order:
+    sorted_entities = [
+        ('sub', 'Jason'),
+        ('acq', 'Treadstone'),
+        ('run', '2'),
+        ('echo', '1'),
+    ]
+    # 'sub-Jason_acq-Treadstone_run-2_echo-1':
+    expected_sorted_str = '_'.join(['-'.join(e) for e in sorted_entities])
+    # expected BIDSFile:
+    suffix = 'T1w'
+    extension = 'nii.gz'
+    expected_bids_file = BIDSFile(OrderedDict(sorted_entities), suffix, extension)
+
+    # entities in random order:
+    idcs = list(range(len(sorted_entities)))
+    shuffle(idcs)
+    shuffled_entities = [sorted_entities[i] for i in idcs]
+    shuffled_str = '_'.join(['-'.join(e) for e in shuffled_entities])
+
+    # Test __eq__ method.
+    # It should consider equal BIDSFiles with the same entities even in different order:
+    assert BIDSFile(OrderedDict(shuffled_entities), suffix, extension) == expected_bids_file
+
+    # Test __getitem__:
+    assert all([expected_bids_file[k] == v for k, v in shuffled_entities])
+
+    # Test filename parser and  __str__ method:
+    # Note: the __str__ method should return entities in the correct order
+    ending = '_T1w.nii.gz'            # suffix + extension
+    my_bids_file = BIDSFile.parse(shuffled_str + ending)
+    assert my_bids_file == expected_bids_file
+    assert str(my_bids_file) == expected_sorted_str + ending
+
+    ending = '.json'                  # just extension
+    my_bids_file = BIDSFile.parse(shuffled_str + ending)
+    assert my_bids_file.suffix == ''
+    assert str(my_bids_file) == expected_sorted_str + ending
+
+    ending = '_T1w'                   # just suffix
+    my_bids_file = BIDSFile.parse(shuffled_str + ending)
+    assert my_bids_file.extension is None
+    assert str(my_bids_file) == expected_sorted_str + ending
+
+    # Complain if entity 'sub' is not set:
+    with pytest.raises(ValueError) as e_info:
+        assert str(BIDSFile.parse('dir-reversed.json'))
+        assert 'sub-' in e_info.value
+
+    # Test set method:
+    # -for a new entity, just set it without a complaint:
+    my_bids_file['dir'] = 'AP'
+    assert my_bids_file['dir'] == 'AP'
+    # -for an existing entity, don't change it by default:
+    my_bids_file['echo'] = '2'
+    assert my_bids_file['echo'] == expected_bids_file['echo']  # still the original value
+    # -for an existing entity, you can overwrite it with "set":
+    my_bids_file.set('echo', '2')
+    assert my_bids_file['echo'] == '2'
\ No newline at end of file
diff --git a/heudiconv/bids/tests/test_utils.py b/heudiconv/bids/tests/test_utils.py
index 4e70e7b6..964b404c 100644
--- a/heudiconv/bids/tests/test_utils.py
+++ b/heudiconv/bids/tests/test_utils.py
@@ -1,4 +1,4 @@
-"""Test functions in heudiconv.bids module.
+"""Test functions of heudiconv.bids.utils module.
 """
 
 import re
@@ -6,7 +6,6 @@
 import os.path as op
 from pathlib import Path
 from random import (random,
-                    shuffle,
                     choice,
                     seed
                     )
@@ -41,7 +40,6 @@
     SHIM_KEY,
     AllowedCriteriaForFmapAssignment,
     KeyInfoForForce,
-    BIDSFile,
 )
 
 from heudiconv.tests.utils import (
@@ -1052,67 +1050,3 @@ def test_populate_intended_for(
                 assert '{p}_acq-unmatched_bold.nii.gz'.format(p=run_prefix) not in data['IntendedFor']
             else:
                 assert 'IntendedFor' not in data.keys()
-
-
-def test_BIDSFile():
-    """ Tests for the BIDSFile class """
-
-    # define entities in the correct order:
-    sorted_entities = [
-        ('sub', 'Jason'),
-        ('acq', 'Treadstone'),
-        ('run', '2'),
-        ('echo', '1'),
-    ]
-    # 'sub-Jason_acq-Treadstone_run-2_echo-1':
-    expected_sorted_str = '_'.join(['-'.join(e) for e in sorted_entities])
-    # expected BIDSFile:
-    suffix = 'T1w'
-    extension = 'nii.gz'
-    expected_bids_file = BIDSFile(OrderedDict(sorted_entities), suffix, extension)
-
-    # entities in random order:
-    idcs = list(range(len(sorted_entities)))
-    shuffle(idcs)
-    shuffled_entities = [sorted_entities[i] for i in idcs]
-    shuffled_str = '_'.join(['-'.join(e) for e in shuffled_entities])
-
-    # Test __eq__ method.
-    # It should consider equal BIDSFiles with the same entities even in different order:
-    assert BIDSFile(OrderedDict(shuffled_entities), suffix, extension) == expected_bids_file
-
-    # Test __getitem__:
-    assert all([expected_bids_file[k] == v for k, v in shuffled_entities])
-
-    # Test filename parser and  __str__ method:
-    # Note: the __str__ method should return entities in the correct order
-    ending = '_T1w.nii.gz'            # suffix + extension
-    my_bids_file = BIDSFile.parse(shuffled_str + ending)
-    assert my_bids_file == expected_bids_file
-    assert str(my_bids_file) == expected_sorted_str + ending
-
-    ending = '.json'                  # just extension
-    my_bids_file = BIDSFile.parse(shuffled_str + ending)
-    assert my_bids_file.suffix == ''
-    assert str(my_bids_file) == expected_sorted_str + ending
-
-    ending = '_T1w'                   # just suffix
-    my_bids_file = BIDSFile.parse(shuffled_str + ending)
-    assert my_bids_file.extension is None
-    assert str(my_bids_file) == expected_sorted_str + ending
-
-    # Complain if entity 'sub' is not set:
-    with pytest.raises(ValueError) as e_info:
-        assert str(BIDSFile.parse('dir-reversed.json'))
-        assert 'sub-' in e_info.value
-
-    # Test set method:
-    # -for a new entity, just set it without a complaint:
-    my_bids_file['dir'] = 'AP'
-    assert my_bids_file['dir'] == 'AP'
-    # -for an existing entity, don't change it by default:
-    my_bids_file['echo'] = '2'
-    assert my_bids_file['echo'] == expected_bids_file['echo']  # still the original value
-    # -for an existing entity, you can overwrite it with "set":
-    my_bids_file.set('echo', '2')
-    assert my_bids_file['echo'] == '2'
diff --git a/heudiconv/bids/utils.py b/heudiconv/bids/utils.py
index 72efe750..951fffad 100644
--- a/heudiconv/bids/utils.py
+++ b/heudiconv/bids/utils.py
@@ -30,6 +30,9 @@
 )
 from .. import __version__
 
+from .schema import BIDSFile
+
+
 lgr = logging.getLogger(__name__)
 
 # Fields to be populated in _scans files. Order matters
@@ -933,94 +936,3 @@ def populate_intended_for(path_to_bids_session, matching_parameters, criterion):
             # Add this intended_for to all fmap files in the fmap_group:
             for fm_json in unique_fmap_groups[fmap_group]:
                 update_json(fm_json, {"IntendedFor": intended_for}, pretty=True)
-
-
-class BIDSFile(object):
-    """ as defined in https://bids-specification.readthedocs.io/en/stable/99-appendices/04-entity-table.html
-    which might soon become machine readable
-    order matters
-    """
-
-    _known_entities = ['sub', 'ses', 'task', 'acq', 'ce', 'rec', 'dir', 'run', 'mod',
-                       'echo', 'flip', 'inv', 'mt', 'part', 'recording',
-                       ]
-
-    def __init__(self, entities, suffix, extension):
-        self._entities = entities
-        self._suffix = suffix
-        self._extension = extension
-
-    def __eq__(self, other):
-        if not isinstance(other, self.__class__):
-            return False
-        if (
-            all([other[k] == v for k, v in self._entities.items()])
-            and self.extension == other.extension
-            and self.suffix == other.suffix
-        ):
-            return True
-        else:
-            return False
-
-    @classmethod
-    def parse(cls, filename):
-        """ Parse the filename for BIDS entities, suffix and extension """
-        # use re.findall to find all lower-case-letters + '-' + alphanumeric + '_' pairs:
-        entities_list = re.findall('([a-z]+)-([a-zA-Z0-9]+)[_]*', filename)
-        # keep only those in the _known_entities list:
-        entities = {k: v for k, v in entities_list if k in BIDSFile._known_entities}
-        # get whatever comes after the last key-value pair, and remove any '_' that
-        # might come in front:
-        ending = filename.split('-'.join(entities_list[-1]))[-1]
-        ending = remove_prefix(ending, '_')
-        # the first dot ('.') separates the suffix from the extension:
-        if '.' in ending:
-            suffix, extension = ending.split('.', 1)
-        else:
-            suffix, extension = ending, None
-        return BIDSFile(entities, suffix, extension)
-
-    def __str__(self):
-        """ reconstitute in a legit BIDS filename using the order from entity table """
-        if 'sub' not in self._entities:
-            raise ValueError('The \'sub-\' entity is mandatory')
-        # reconstitute the ending for the filename:
-        suffix = '_' + self.suffix if self.suffix else ''
-        extension = '.' + self.extension if self.extension else ''
-        return '_'.join(
-            ['-'.join([e, self._entities[e]]) for e in self._known_entities if e in self._entities]
-        ) + suffix + extension
-
-    def __getitem__(self, entity):
-        return self._entities[entity] if entity in self._entities else None
-
-    def __setitem__(self, entity, value):  # would puke with some exception if already known
-        return self.set(entity, value, overwrite=False)
-
-    def set(self, entity, value, overwrite=True):
-        if entity not in self._entities:
-            # just set it; no complains here
-            self._entities[entity] = value
-        elif overwrite:
-            lgr.warning("Overwriting the entity %s from %s to %s for file %s",
-                        str(entity),
-                        str(self[entity]),
-                        str(value),
-                        self.__str__()
-                        )
-            self._entities[entity] = value
-        else:
-            # if it already exists, and overwrite is false:
-            lgr.warning("Setting the entity %s to %s for file %s failed",
-                        str(entity),
-                        str(value),
-                        self.__str__()
-                        )
-
-    @property  # as needed make them RW
-    def suffix(self):
-        return self._suffix
-
-    @property
-    def extension(self):
-        return self._extension

From de6087ce7afdaf1bdd4c4d285cc8dea04bcbdbc3 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Tue, 29 Mar 2022 14:24:47 -0400
Subject: [PATCH 6/8] [DATALAD RUNCMD] isort the gitrepo we modified

=== Do not change lines below ===
{
 "chain": [],
 "cmd": "python3 -m isort -m3 --fgw 2 --tc {outputs}",
 "exit": 0,
 "extra_inputs": [],
 "inputs": [],
 "outputs": [
  "heudiconv/bids/*py",
  "heudiconv/bids/tests/*py"
 ],
 "pwd": "."
}
^^^ Do not change lines above ^^^
---
 heudiconv/bids/schema.py           |  6 ++--
 heudiconv/bids/tests/test_utils.py | 54 ++++++++++++++----------------
 heudiconv/bids/utils.py            | 30 ++++++++---------
 3 files changed, 43 insertions(+), 47 deletions(-)

diff --git a/heudiconv/bids/schema.py b/heudiconv/bids/schema.py
index 5d127b96..e7a68486 100644
--- a/heudiconv/bids/schema.py
+++ b/heudiconv/bids/schema.py
@@ -1,11 +1,11 @@
-from pathlib import Path
+import logging
 import re
+from pathlib import Path
+
 import yaml
 
 from heudiconv.utils import remove_prefix
 
-import logging
-
 lgr = logging.getLogger(__name__)
 
 
diff --git a/heudiconv/bids/tests/test_utils.py b/heudiconv/bids/tests/test_utils.py
index 964b404c..581bb29d 100644
--- a/heudiconv/bids/tests/test_utils.py
+++ b/heudiconv/bids/tests/test_utils.py
@@ -1,52 +1,50 @@
 """Test functions of heudiconv.bids.utils module.
 """
 
-import re
 import os
 import os.path as op
-from pathlib import Path
-from random import (random,
-                    choice,
-                    seed
-                    )
-from datetime import (datetime,
-                      timedelta,
-                      )
-from collections import (OrderedDict,
-                         )
+import re
+import string
+from collections import OrderedDict
+from datetime import (
+    datetime,
+    timedelta,
+)
 from glob import glob
+from pathlib import Path
+from random import (
+    choice,
+    random,
+    seed,
+)
 
 import nibabel
-import string
+import pytest
 from numpy import testing as np_testing
 
+from heudiconv.tests.utils import TESTS_DATA_PATH
 from heudiconv.utils import (
-    load_json,
-    save_json,
     create_tree,
+    load_json,
     remove_suffix,
+    save_json,
 )
 
 from .. import (
-    maybe_na,
-    treat_age,
-    find_fmap_groups,
-    populate_intended_for,
-    get_shim_setting,
-    get_key_info_for_fmap_assignment,
-    find_compatible_fmaps_for_run,
-    find_compatible_fmaps_for_session,
-    select_fmap_from_compatible_groups,
     SHIM_KEY,
     AllowedCriteriaForFmapAssignment,
     KeyInfoForForce,
+    find_compatible_fmaps_for_run,
+    find_compatible_fmaps_for_session,
+    find_fmap_groups,
+    get_key_info_for_fmap_assignment,
+    get_shim_setting,
+    maybe_na,
+    populate_intended_for,
+    select_fmap_from_compatible_groups,
+    treat_age,
 )
 
-from heudiconv.tests.utils import (
-    TESTS_DATA_PATH,
-)
-
-import pytest
 
 def gen_rand_label(label_size, label_seed, seed_stdout=True):
     seed(label_seed)
diff --git a/heudiconv/bids/utils.py b/heudiconv/bids/utils.py
index 951fffad..3fba827f 100644
--- a/heudiconv/bids/utils.py
+++ b/heudiconv/bids/utils.py
@@ -1,38 +1,36 @@
 """Handle BIDS specific operations"""
 
+import csv
+import errno
 import hashlib
+import logging
 import os
 import os.path as op
-import logging
-import numpy as np
 import re
 from collections import OrderedDict
 from datetime import datetime
-import csv
-from random import sample
 from glob import glob
-import errno
+from random import sample
 
-from ..external.pydicom import dcm
+import numpy as np
 
+from .. import __version__
+from ..external.pydicom import dcm
 from ..parser import find_files
 from ..utils import (
-    load_json,
-    save_json,
     create_file_if_missing,
-    json_dumps,
-    update_json,
-    set_readonly,
-    is_readonly,
     get_datetime,
-    remove_suffix,
+    is_readonly,
+    json_dumps,
+    load_json,
     remove_prefix,
+    remove_suffix,
+    save_json,
+    set_readonly,
+    update_json,
 )
-from .. import __version__
-
 from .schema import BIDSFile
 
-
 lgr = logging.getLogger(__name__)
 
 # Fields to be populated in _scans files. Order matters

From 40aeffc22137ae50403e73508c05b329ffc77f07 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Tue, 29 Mar 2022 14:32:48 -0400
Subject: [PATCH 7/8] ENH: a little pythonisation + ensure no bad entities
 provided

---
 heudiconv/bids/consts.py            | 31 +++++++++++++++++++++++++++++
 heudiconv/bids/schema.py            | 12 ++++++-----
 heudiconv/bids/tests/test_schema.py |  4 ++++
 heudiconv/bids/utils.py             |  4 +---
 heudiconv/convert.py                |  2 +-
 5 files changed, 44 insertions(+), 9 deletions(-)
 create mode 100644 heudiconv/bids/consts.py

diff --git a/heudiconv/bids/consts.py b/heudiconv/bids/consts.py
new file mode 100644
index 00000000..a509908c
--- /dev/null
+++ b/heudiconv/bids/consts.py
@@ -0,0 +1,31 @@
+#emacs: -*- mode: python-mode; py-indent-offset: 4; tab-width: 4; indent-tabs-mode: nil -*- 
+#ex: set sts=4 ts=4 sw=4 noet:
+"""
+
+ COPYRIGHT: Yaroslav Halchenko 2014
+
+ LICENSE: MIT
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+  copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in
+  all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+  THE SOFTWARE.
+"""
+
+__author__ = 'yoh'
+__license__ = 'MIT'
+
+BIDS_VERSION = "1.7.0"
\ No newline at end of file
diff --git a/heudiconv/bids/schema.py b/heudiconv/bids/schema.py
index e7a68486..a338ff7e 100644
--- a/heudiconv/bids/schema.py
+++ b/heudiconv/bids/schema.py
@@ -6,6 +6,8 @@
 
 from heudiconv.utils import remove_prefix
 
+from .consts import BIDS_VERSION
+
 lgr = logging.getLogger(__name__)
 
 
@@ -31,6 +33,9 @@ class BIDSFile:
     _known_entities = _load_entities_order()
 
     def __init__(self, entities, suffix, extension):
+        unknown_entities = set(entities).difference(self._known_entities)
+        if unknown_entities:
+            raise ValueError(f"Unknown to BIDS {BIDS_VERSION} entities provided: {', '.join(unknown_entities)}")
         self._entities = entities
         self._suffix = suffix
         self._extension = extension
@@ -38,14 +43,11 @@ def __init__(self, entities, suffix, extension):
     def __eq__(self, other):
         if not isinstance(other, self.__class__):
             return False
-        if (
+        return (
             all([other[k] == v for k, v in self._entities.items()])
             and self.extension == other.extension
             and self.suffix == other.suffix
-        ):
-            return True
-        else:
-            return False
+        )
 
     @classmethod
     def parse(cls, filename):
diff --git a/heudiconv/bids/tests/test_schema.py b/heudiconv/bids/tests/test_schema.py
index 2aac1968..2ab9bb89 100644
--- a/heudiconv/bids/tests/test_schema.py
+++ b/heudiconv/bids/tests/test_schema.py
@@ -11,6 +11,10 @@ def test_BIDSFile_known_entries():
     assert len(BIDSFile._known_entities) > 10  # we do have many
     assert 'run' in BIDSFile._known_entities
 
+    good_entities = dict(sub='me')
+    BIDSFile(good_entities, None, None)  # just to ensure we are good
+    with pytest.raises(ValueError):
+        BIDSFile(dict(good_entities, badentity="good"), None, None)
 
 def test_BIDSFile():
     """ Tests for the BIDSFile class """
diff --git a/heudiconv/bids/utils.py b/heudiconv/bids/utils.py
index 3fba827f..4c63139d 100644
--- a/heudiconv/bids/utils.py
+++ b/heudiconv/bids/utils.py
@@ -10,10 +10,10 @@
 from collections import OrderedDict
 from datetime import datetime
 from glob import glob
-from random import sample
 
 import numpy as np
 
+from .consts import BIDS_VERSION
 from .. import __version__
 from ..external.pydicom import dcm
 from ..parser import find_files
@@ -55,8 +55,6 @@ class BIDSError(Exception):
     pass
 
 
-BIDS_VERSION = "1.7.0"
-
 # List defining allowed parameter matching for fmap assignment:
 SHIM_KEY = 'ShimSetting'
 AllowedFmapParameterMatching = [
diff --git a/heudiconv/convert.py b/heudiconv/convert.py
index bf9e6def..1df30796 100644
--- a/heudiconv/convert.py
+++ b/heudiconv/convert.py
@@ -31,8 +31,8 @@
     tuneup_bids_json_files,
     add_participant_record,
     BIDSError,
-    BIDS_VERSION,
 )
+from .bids.consts import BIDS_VERSION
 from .dicoms import (
     group_dicoms_into_seqinfos,
     embed_metadata_from_dicoms,

From 6ce5422685812918b783e2346fa62719895cbc89 Mon Sep 17 00:00:00 2001
From: Yaroslav Halchenko <debian@onerussian.com>
Date: Tue, 29 Mar 2022 17:44:21 -0400
Subject: [PATCH 8/8] BF+ENH: add pyyaml to depends and sort all depends

---
 heudiconv/info.py | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

diff --git a/heudiconv/info.py b/heudiconv/info.py
index 4de9453a..6236d384 100644
--- a/heudiconv/info.py
+++ b/heudiconv/info.py
@@ -22,29 +22,30 @@
 PYTHON_REQUIRES = ">=3.6"
 
 REQUIRES = [
-    'nibabel',
-    'pydicom',
-    'nipype >=1.2.3',
     'dcmstack>=0.8',
     'etelemetry',
     'filelock>=3.0.12',
+    'nibabel',
+    'nipype >=1.2.3',
+    'pydicom',
+    'pyyaml',
 ]
 
 TESTS_REQUIRES = [
-    'six',
-    'pytest',
+    'inotify',
     'mock',
+    'pytest',
+    'six',
     'tinydb',
-    'inotify',
 ]
 
 MIN_DATALAD_VERSION = '0.13.0'
 EXTRA_REQUIRES = {
-    'tests': TESTS_REQUIRES,
+    'datalad': ['datalad >=%s' % MIN_DATALAD_VERSION],
     'extras': [
         'duecredit',  # optional dependency
     ],  # Requires patched version ATM ['dcmstack'],
-    'datalad': ['datalad >=%s' % MIN_DATALAD_VERSION]
+    'tests': TESTS_REQUIRES,
 }
 
 # Flatten the lists