Standardize structure of entity tables

[tsalo]

On a recent call with the NIDM-Terms group, it became clear that the entity tables are somewhat confusingly organized. Namely, auxiliary datatypes flip the conventional pattern without making it clear that the pattern was flipped.

In the current stable version (v1.4.0), there are four patterns:

1. data type (suffix1 suffix2 etc.): Used in most cases.
2. suffix (data type1/data type 2/etc.): Used for what we currently call "auxiliary data types" in the schema (e.g., channels files).
3. data type: Used in cases where the data type and suffix are the same (e.g., meg, eeg, ieeg). This pattern was removed when we schemafied the entity table, primarily for consistency.
4. data type (extension1 extension2): Only used for DWI with bvec and bval files. I assume this was a typo rather than a design choice, so this pattern was removed when we schemafied the entity table.

In the current latest version (v1.4.1-dev), only the first two patterns remain, but they are still confusing.

I propose that we eliminate the second pattern above (suffix (data type)) and reformat it to match the main pattern (i.e., data type (suffix)). This will increase the number of rows in the tables (especially the Encephalography table), but I don't think that's a major problem now that there are multiple tables.

I also propose that we include the pattern in either the table itself or in the text for the Entity table page.

Solution 1: Reflect the item in the pattern

We can append / to each data type to make it clear it refers to a folder and prepend _ to each suffix to make it clear it's a suffix.

Entity	Subject	Session	Task	Acquisition	Run	Recording
Format	sub-<label>	ses-<label>	task-<label>	acq-<label>	run-<index>	recording-<label>
beh/ (_stim _physio)	REQUIRED	OPTIONAL	REQUIRED	OPTIONAL	OPTIONAL	OPTIONAL
beh/ (_events _beh)	REQUIRED	OPTIONAL	REQUIRED	OPTIONAL	OPTIONAL

Solution 2: Explicit column header

Entity	Subject	Session	Task	Acquisition	Run	Recording
Modality (Suffixes)	sub-<label>	ses-<label>	task-<label>	acq-<label>	run-<index>	recording-<label>
beh (stim physio)	REQUIRED	OPTIONAL	REQUIRED	OPTIONAL	OPTIONAL	OPTIONAL
beh (events beh)	REQUIRED	OPTIONAL	REQUIRED	OPTIONAL	OPTIONAL

Solution 3: Describe the pattern in the text

Currently, we have:

This section compiles the entities (key-value pairs) described throughout this specification, and establishes a common order within a filename.
For example, if a file has an acquisition and reconstruction label, the acquisition entity must precede the reconstruction entity.
REQUIRED and OPTIONAL entities for a given file type are denoted.
Entity formats indicate whether the value is alphanumeric (<label>) or numeric (<index>).

A general introduction to entities is given in the section on file name structure.

We could have:

This section compiles the entities (key-value pairs) described throughout this specification, and establishes a common order within a filename.
For example, if a file has an acquisition and reconstruction label, the acquisition entity must precede the reconstruction entity.
REQUIRED and OPTIONAL entities for a given file type are denoted.
Entity formats indicate whether the value is alphanumeric (<label>) or numeric (<index>).
Cells in the first column identify the modality and associated suffixes for which each pattern of entities applies.

A general introduction to entities is given in the section on file name structure.