[MISC] split intro, commons, mr, and meg into directory from specification.md

[teonbrooks]

closes #4
WIP: MR is currently a composite mr.md. Needs to be sectioned off.

[chrisgorgo]

Thanks for submitting this. We just had a brainstorming session with @franklin-feingold and @JesseyWright about this and came up with the following splitting

• 1 Introduction (01_introduction.md)
  • 1.1 Motivation
  • 3.2 Definitions
  • 3.3 Compulsory, optional, and additional data and metadata
  • 3.4 Source vs. raw vs. derived data
  • 3.6 Extensions
  • 3.7 Citing BIDS
• 2 Common principles (02_common_principles.md)
  • 2.1 The Inheritance Principle
  • 2.2 File Format specification
    • 2.2.1 Imaging files
    • 2.2.2 Tabular files
  • 2.3 Key/value files (dictionaries)
  • 2.4 Participant names and other labels
  • 2.5 Units
  • 2.6 Directory structure
    • 2.6.1 Single session example
    • 2.6.2 Code
• 3 Modality-agnostic files (03_modality_agnostic_files.md)
  • 3.1 Dataset description
    • 3.1.1 dataset_description.json
    • 3.1.2 README
    • 3.1.3 CHANGES
  • 3.2 Participants file
  • 3.3 Scans file
• 4 Modality-specific files (04_modality_specific_files/)
  • 4.1 Magnetic Resonance Imaging data (04_modality_specific_files/01_magnetic_resonance_imaging_data.md)
    • 4.1.1 Common metadata fields
    • 4.1.2 Anatomy imaging data
    • 4.1.3 Task (including resting state) imaging data
    • 4.1.4 Diffusion imaging data
    • 4.1.5 Fieldmap data
      • 4.1.5.1 Case 1: Phase difference image and at least one magnitude image
      • 4.1.5.2 Case 2: Two phase images and two magnitude images
      • 4.1.5.3 Case 3: A single, real fieldmap image (showing the field inhomogeneity in each voxel)
      • 4.1.5.4 Case 4: Multiple phase encoded directions (“pepolar”)
  • 4.2 Magnetoencephalography (04_modality_specific_files/02_magnetoencephalography.md)
    • 4.2.1 MEG recording data
      • 4.2.1.1 Sidecar JSON document (*_meg.json)
    • 4.2.2 Channels description table (*_channels.tsv)
    • 4.2.3 Coordinate System JSON document (*_coordsystem.json)
    • 4.2.4 Photos of the anatomical landmarks and/or head localization coils (*_photo.jpg)
    • 4.2.5 3-D head point /electrode locations file (*_headshape.<manufacturer_specific_format>)
    • 4.2.6 Empty-room files (sub-emptyroom)
  • 4.3 Task events (04_modality_specific_files/03_task_events.md)
  • 4.4 Physiological and other continuous recordings (04_modality_specific_files/04_physiological_and_other_continous_recordings.md)
  • 4.5 Behavioral experiments (with no MRI) (04_modality_specific_files/05_behavioural_experiments.md)
• 5 Longitudinal and multi-site studies (05_longitudinal_and_multi_site_studies.md
  • 5.1 Longitudinal studies with multiple sessions (visits)
  • 5.1.1 Sessions file
  • 5.2 Multi-site or multi-center studies
    • 5.2.1 Option 1: Treat each site/center as a separate dataset.
    • 5.2.2 Option 2: Combining sites/centers into one dataset
• Appendices (99_appendices/)
  • Appendix I: Contributors (99_appendices/01_contributors.md)
  • Appendix II: Licenses (99_appendices/02_licenses.md)
  • Appendix III: Hierarchical Event Descriptor (HED) Tags (99_appendices/03_hed.md)
  • Appendix IV: Entity table (99_appendices/04_centity_table.md)
  • Appendix V: Units (99_appendices/05_units.md)
  • Appendix VI: MEG file formats (99_appendices/06_meg_file_formats.md)
    • CTF
    • Elekta/Neuromag
    • 4D neuroimaging/BTi
    • KIT/Yokogawa
    • KRISS
    • ITAB
    • Aalto/MEG–MRI
  • Appendix VII: preferred names of MEG systems (99_appendices/07_MEG_systems.md)
  • Appendix VIII: preferred names of Coordinate systems (99_appendices/08_coordinate_systems.md)
    • MEG specific Coordinate Systems
    • EEG specific Coordinate Systems
    • Template based Coordinate Systems

Please note that numbering has changed and some sections were moved around. Would love to hear what you think.

[teonbrooks]

yeah, that makes sense, fewer files overall and still compartmentalized.

I guess one thing would be to use native md section, subsection nomenclature internally. that way there won't be any conflicting section numbers. we can then implement anchor tags to refer to sections internally

[chrisgorgo]

I guess one thing would be to use native md section, subsection nomenclature internally. that way there won't be any conflicting section numbers. we can then implement anchor tags to refer to sections internally

That's the idea - with each md file (independent of where it is in the hierarchy) starting with # and going down via ## and so on.

As for section numbers. Do you think we should remove them completely and trust they will be handled by whatever rendering engine we will use? They seem to be handy when talking about different parts of the spec (although anchors will help with that a lot).

[teonbrooks]

As for section numbers. Do you think we should remove them completely and trust they will be handled by whatever rendering engine we will use? They seem to be handy when talking about different parts of the spec (although anchors will help with that a lot).

i guess it depends on whether there could be hierarchical changes to the doc. If it is stable from here on then it would be fine to include. It would be a matter of having the rendering engine turn off auto-gen section headers then. also, i think if we ever wanted to include something at the folder level, e.g. in the case of modality specific files, I read that the README is rendered at the top of the folder section. just fyi.

[satra]

would it be worth considering markdown with sphinx? as of recent versions, sphinx supports markdown. this means readthedocs will be able to automatically generate the documentation.

this should also allow sectioning, and contributions to specific files, possibly making the aggregation easier.

[chrisgorgo]

I don't see clear benefits (or disadvantages), but lets discuss at #18. This PR concerns splitting the markdown document

[teonbrooks]

@satra cool, just linked your comment to #18

[chrisgorgo]

This section has a number, but some others don't. I would either remove all of them or add them everywhere.

[satra]

@chrisfilo - i think splitting is always cleaner, more atomic the better for maintenance/updates/review, but then stitching becomes the issue. if stitching exists, then different forms of splitting becomes easier. that's the only reason i brought up the stitcher in the context of the splitter.

[chrisgorgo]

I believe there is no disagreement that the markdown will be rendered into a more palatable form (although probably not just stitched into a single large file). There is the only discussion on which framework to use to do the rendering. All of them can work with the file/folder structure in this repo so I think we are good to merge. Thank you @teonbrooks!

[teonbrooks]

@chrisfilo I saved the deletion the monolithic file for you ;)