[REF] refactor institution and task tables

[Remi-Gau]

• extracts institution, task and hardware metadata in separate tables
• closes metadata table refactoring #1389

Also adds comments for several macros in the nirs page.

[codecov]

Codecov Report

Patch coverage has no change and project coverage change: +1.82 🎉

Comparison is base (88b4574) 87.88% compared to head (c387331) 89.70%.

❗ Current head c387331 differs from pull request most recent head 0e1f487. Consider uploading reports for the commit 0e1f487 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1397      +/-   ##
==========================================
+ Coverage   87.88%   89.70%   +1.82%     
==========================================
  Files          14       12       -2     
  Lines        1279     1185      -94     
==========================================
- Hits         1124     1063      -61     
+ Misses        155      122      -33     

see 6 files with indirect coverage changes

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report in Codecov by Sentry.
📢 Do you have feedback about the report comment? Let us know in this issue.

[Remi-Gau]

MEG before

https://bids-specification.readthedocs.io/en/latest/modality-specific-files/magnetoencephalography.html#sidecar-json-_megjson

MEG after

https://bids-specification--1397.org.readthedocs.build/en/1397/modality-specific-files/magnetoencephalography.html#sidecar-json-_megjson

[Remi-Gau]

EEG before

https://bids-specification.readthedocs.io/en/latest/modality-specific-files/electroencephalography.html#sidecar-json-_eegjson

EEG after

https://bids-specification--1397.org.readthedocs.build/en/1397/modality-specific-files/electroencephalography.html#sidecar-json-_eegjson

[Remi-Gau]

iEEG before

https://bids-specification.readthedocs.io/en/latest/modality-specific-files/intracranial-electroencephalography.html#sidecar-json-_ieegjson

iEEG after

https://bids-specification--1397.org.readthedocs.build/en/1397/modality-specific-files/intracranial-electroencephalography.html#sidecar-json-_ieegjson

[Remi-Gau]

behavioral before

https://bids-specification.readthedocs.io/en/latest/modality-specific-files/behavioral-experiments.html#recommended-metadata

behavioral after

https://bids-specification--1397.org.readthedocs.build/en/1397/modality-specific-files/behavioral-experiments.html#recommended-metadata

[Remi-Gau]

microscopy before

https://bids-specification.readthedocs.io/en/latest/modality-specific-files/microscopy.html#microscopy-metadata-sidecar-json

Microscopy after

https://bids-specification--1397.org.readthedocs.build/en/1397/modality-specific-files/microscopy.html#microscopy-metadata-sidecar-json

[Remi-Gau]

NIRS before

https://bids-specification.readthedocs.io/en/latest/modality-specific-files/near-infrared-spectroscopy.html#sidecar-json-_nirsjson

NIRS after

https://bids-specification--1397.org.readthedocs.build/en/1397/modality-specific-files/near-infrared-spectroscopy.html#institution-information

[Remi-Gau]

@effigies here too added links and screenshots to point to the "most obvious" changes.

[sappelhoff]

I find it a bit weird that after the specific sections (that contain REQUIRED, RECOMMENDED, OPTIONAL fields), there are additional sections for REQUIRED, ... fields 🤔 it might lead to confusion, what do you think?

[Remi-Gau]

I find it a bit weird that after the specific sections (that contain REQUIRED, RECOMMENDED, OPTIONAL fields), there are additional sections for REQUIRED, ... fields thinking it might lead to confusion, what do you think?

Maybe a better way to organize things ⬇️ ?

### Sidecar json

- put metadata specific to that datatype but with no headings

- table for required metadata, 
- table for recommended metadata,  
- table for optional metadata 

#### Hardware information

#### Institution information

#### Task information

[Remi-Gau]

FYI: I am breaking things into separate tables because currently macros do not sort items by their requirement level (AFAIK).

[Remi-Gau]

I find it a bit weird that after the specific sections (that contain REQUIRED, RECOMMENDED, OPTIONAL fields), there are additional sections for REQUIRED, ... fields thinking it might lead to confusion, what do you think?

Maybe a better way to organize things arrow_down ?

### Sidecar json

- put metadata specific to that datatype but with no headings

- table for required metadata, 
- table for recommended metadata,  
- table for optional metadata 

#### Hardware information

#### Institution information

#### Task information

@sappelhoff I have reorganized things as described above. Let me know what you think.

@effigies @tsalo if you have time for a quick look.

[Remi-Gau]

Actually looking at the new microscopy page, I have question:

Do we agree that, within a metadata table, requirement level takes precedence over alphabetical order for sorting items?

So REQUIRED items appear higher in the tables than RECOMMENDED, but all REQUIRED items must be sorted alphabetically?

If so I should probably reorganize some of the microscopy tables? See the sample one, for example:
https://bids-specification--1397.org.readthedocs.build/en/1397/modality-specific-files/microscopy.html#sample

Alternatively I could also create a table for required items and one for recommended as this a pattern we have in many other datatypes.

Preferences? Suggestions?

[sappelhoff]

I like it now and I think it's an improvement! Thanks Remi

So REQUIRED items appear higher in the tables than RECOMMENDED, but all REQUIRED items must be sorted alphabetically?

+1

[tsalo]

Given the scope of the PR I'll need to take a closer look before giving an approving review, but I really like the general change.

[Remi-Gau]

@bids-standard/maintainers if one of you has time to give this another review so it can go in