Move entity definitions to separate page(s)

[tsalo]

Currently, entities are defined in one section where they're used with a heading (which helps find the definition in the search bar), and are then referenced in all other sections where they're used. The problem is that this spreads those entity definitions out across various sections, with no interlinking between them, and with variable text at each location.

For example, the run entity is defined under "Anatomy imaging data" with the following:

If several scans of the same modality are acquired they MUST be indexed with a key-value pair: _run-1, _run-2, _run-3 etc. (only integers are allowed as run labels). When there is only one scan of a given type the run key MAY be omitted. Please note that diffusion imaging data is stored elsewhere (see below).

However, in the MEG and EEG sections, at least, the run entity is not defined. It is just used in the filename templates. I should note, though, that in most cases where a definition is included, it's the same as the main definition with the heading. This is good for the specification, but it requires good maintenance instead of being automated as it could be.

I propose that we move the "canonical" definitions to either one page for all of them or one page for each, and then include links to the entity definitions in specification text. This will (1) standardize the definitions and (2) prepare us for when entities must be defined only once, in a canonical manner, as in #540.

Alternatives to consider

• Link to entity definitions in the filename templates instead of, or in addition to, the specification text. Personally, I think this would be beautiful, but I don't think hyperlinks can be placed in code snippets.
• Use mdinclude or something similar to simply include the full definitions in all of the relevant sections of the specification text. I don't know how this would interact with pandoc or the search-bar, but it would be more readable.

[satra]

pinging @dbkeator. @tsalo - this is exactly what dave's grant is supposed to help with, so just making sure he is notified.

[satra]

also pinging @nqueder

[sappelhoff]

yes, good idea ... this came up in the past as well (e.g., here: #200 (comment))

[VisLab]

I'd like to see a separate definitions page. I did not think about looking for definitions in common principles until I did a search in the PDF. As someone not as familiar with the spec as most people, it wasn't the first place I thought to look.

[tsalo]

I've drafted up an extremely rough attempt at what I'm proposing in #568. The real deal would build off of some of the early schema work we've done in #475, but this first attempt should at least allow folks to judge how the changes would render in the specification.

Also, thanks @satra for pinging potentially interested folks!

[dbkeator]

Hi Folks,

As @satra mentioned, we have mined all the BIDS specification PDF documents and extracted terms used in BIDS into JSON-LD documents: https://github.com/NIDM-Terms/terms/tree/master/terms/BIDS_Terms. These are searchable and we have implemented a little tool at OHBM Brainhack (which needs some additional functionality) that let's you search through these terms and add them with selected properties to export a Markdown table for inclusion in your BIDS specifications: https://github.com/nqueder/bids_terms_to_markdown_table. This code also let's you add a new BIDS term, checks whether its label collides with another BIDS term and writes out a new JSON-LD document for the term (it doesn't currently issue a pull request to the main NIDM-Terms repo which is something we'd like to finish up so one can contribute new proposed BIDS terms to the group).

Further we have loaded the BIDS specification terms into InterLex and are working on a process where InterLex updates its list of terms by pulling from the terms repo above: https://neuinfo.org/interlex/search?q=BIDS.

We are currently working on parsing the YAML schema files that @tsalo has been working on to verify we have all the BIDS terms and would like to work with you on coordinating our activities of managing terms used in BIDS.

Cheers,
Dave

[tsalo]

Thanks @dbkeator! I think that the best course of action in synchronizing BIDS_Terms with the BIDS schema developments is a meeting (as discussed in #540). I don't think the current form of the YAML files will survive many releases- hopefully we'll adopt a more general standard (or set of standards) over time.

For this issue, my goal is mostly to start reorganizing the specification so that it's compatible with the full schema conversion once that transition happens. That reorganization will involve identifying what text can be truly modularized/sectioned off into schema files, and what text is necessary as section-specific "glue". In this case, entity definitions should be consistent across modalities, so they can be easily separated out without a lot of effort.