Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 4 commits into from
Oct 3, 2018

Conversation

teonbrooks
Copy link
Collaborator

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

WIP: MR is currently a composite mr.md. Needs to be sectioned off.
@chrisgorgo
Copy link
Contributor

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
Copy link
Collaborator Author

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
Copy link
Contributor

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
Copy link
Collaborator Author

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.

@teonbrooks teonbrooks changed the title split intro, commons, mr, and meg into folder from specification.md [MRG] split intro, commons, mr, and meg into folder from specification.md Oct 3, 2018
@satra
Copy link
Collaborator

satra commented Oct 3, 2018

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.

This was referenced Oct 3, 2018
@chrisgorgo
Copy link
Contributor

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

@teonbrooks
Copy link
Collaborator Author

@satra cool, just linked your comment to #18

Directory structure
-------------------

### 1 Single session example
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@satra
Copy link
Collaborator

satra commented Oct 3, 2018

@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
Copy link
Contributor

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!

@chrisgorgo chrisgorgo merged commit 45985e3 into bids-standard:master Oct 3, 2018
@teonbrooks teonbrooks deleted the filesplit branch October 3, 2018 22:33
@teonbrooks
Copy link
Collaborator Author

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

@chrisgorgo chrisgorgo mentioned this pull request Oct 3, 2018
sappelhoff pushed a commit that referenced this pull request Aug 21, 2019
@sappelhoff sappelhoff changed the title [MRG] split intro, commons, mr, and meg into folder from specification.md [MISC] split intro, commons, mr, and meg into folder from specification.md Sep 8, 2020
@tsalo tsalo mentioned this pull request Oct 2, 2020
15 tasks
@sappelhoff sappelhoff changed the title [MISC] split intro, commons, mr, and meg into folder from specification.md [MISC] split intro, commons, mr, and meg into directory from specification.md Mar 29, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Split into multiple documents
3 participants