[FIX] Correct entity names in YAML files

[tsalo]

This corrects a problem with the CI identified in #719. In #610 we switched to using the entity names, rather than keys, in the datatype YAML files, while in #714 we changed those names for a couple of entities. As such, the old names are referenced in the datatype YAML files, which causes a conflict with the rendering code.

[sappelhoff]

Thanks @tsalo

[marcelzwiers]

Can I ask, why did you switch from keys to entity names? I am asking because for me the old way was much better, as I was reading the schema files to check bidskeys. Do you know, how can I now translate the entity names back to keys?

[tsalo]

From what I can recall, the main reasons are (1) the schema files are tool-centric, so it made sense to use the tool-centric variable names, and (2) we wanted the more explanatory names, but couldn't figure out a good name for the field. Using those names as the keys meant we didn't have to come up with a term for them.

In terms of translating the names back to keys, in our current code we just reference the "entity" field as we search through available entities, rather than using the keys. It makes the code slightly more complicated, but I think it's still solid.

[marcelzwiers]

I am not sure I can fully follow what you are saying but what I meant is that I used the datatype files to check that e.g. the required inv key-value pair is missing in sub-001_flip-<index>_MP2RAGE.nii. Now I need to translate inversion back to inv before I can check whether it is present in the filename

[marcelzwiers]

Is there a mapping somewhere that maps entity names to keys? To me using the key names to define whether the key is required or not seems the most logical thing to do.

[marcelzwiers]

What the entities are is already (much better) described in entities.yaml?

[marcelzwiers]

Besides, there you don't use the entity name. See e.g. this snippet where the old inv is used instead of the new inversion:

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.
  format: index

[marcelzwiers]

Ah wait, now I see that the entityname is used in the top level of the entities.yaml file, right? So that is my mapping?

[effigies]

Yes, so the entities.yaml contains entity definitions that are indexed by a concept name. The entity field in this definition corresponds to the entity in the filename. So if you load entities.yaml into a python dict, you would say:

entities["inversion"]["entity"] == "inv"

[marcelzwiers]

Thanks! Not really important, but wouldn't it then be better to use key instead of entity to avoid confusion about what an entity is? E.g. like this

inversion:
  name: Inversion Time
  key: inv
  description: |
    [..]

and

entities["inversion"]["key"] == "inv"