diff --git a/CODEOWNERS b/CODEOWNERS index 39a7964049..befef1c2e4 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -5,10 +5,11 @@ # Request for Review) please add your GitHub username next to the file you want to # monitor below. -# Add your github name below to get notified about proposed releases -/src/CHANGES.md @chrisfilo @sappelhoff @CPernet +# Add your GitHub name below to get notified about proposed releases +/src/CHANGES.md @chrisgorgo @sappelhoff @CPernet # Individual sections -/src/01-common-principles.md @chrisfilo -/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @chrisfilo -/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff +/src/01-common-principles.md @chrisgorgo @DimitriPapadopoulos +/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @chrisgorgo +/src/04-modality-specific-files/03-electroencephalography.md @sappelhoff @ezemikulan +/src/04-modality-specific-files/04-intracranial-electroencephalography.md @ezemikulan diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1869a5e8d6..07ebbc74dd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,9 +44,9 @@ The specification documents follow the [Markdown Style Guide](http://www.cirosan You can validate your changes against the guide using [remark](https://github.com/remarkjs/remark-lint) which works as a [standalone command line tool](https://github.com/remarkjs/remark/tree/master/packages/remark-cli) as well as [a plugin for various text editors](https://github.com/remarkjs/remark-lint#editor-integrations). Remark preserves consistent markdown styling across the contributions. Please ensure before submitting a contribution that you do not have any linter errors in your text editor. -You can also use [prettier](https://github.com/prettier/prettier) to automatically correct some of the style issuse that might be found in the proposed changes. +You can also use [prettier](https://github.com/prettier/prettier) to automatically correct some of the style issues that might be found in the proposed changes. -We have deployed a continous integrator ([circle CI](https://circleci.com/)) to further allow for integrating changes continously. The CI is testing that the changes are inline with our standard styling. +We have deployed a continuous integrator ([circle CI](https://circleci.com/)) to further allow for integrating changes continuously. The CI is testing that the changes are inline with our standard styling. GitHub has a helpful page on [getting started with writing and formatting on GitHub](https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github). @@ -95,9 +95,25 @@ Try to keep the changes focused. If you submit a large amount of work in all in #### 4. Submit a [pull request](https://help.github.com/articles/about-pull-requests/) +Please keep the title of your pull request short but informative - it will +appear in the [changelog](src/CHANGES.md). + +Use one of the following prefixes in the title of your pull request: + - `[ENH]` - enhancement of the specification that adds a new feature or + support for a new data type + - `[FIX]` - fix of a typo or language clarification + - `[INFRA]` - changes to the infrastructure automating the specification + release (for example building HTML docs etc.) + - `[MISC]` - everything else including changes to the file listing + contributors + +If you are opening a pull request to obtain early feedback, but the changes +are not ready to be merged (a.k.a. Work in Progress pull request) please +use a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/). + A member of the BIDS Specification team will review your changes to confirm that they can be merged into the main codebase. -A [review](https://help.github.com/articles/about-pull-request-reviews/) will probably consist of a few questions to help clarify the work you've done. Keep an eye on your github notifications and be prepared to join in that conversation. +A [review](https://help.github.com/articles/about-pull-request-reviews/) will probably consist of a few questions to help clarify the work you've done. Keep an eye on your GitHub notifications and be prepared to join in that conversation. You can update your [fork](https://help.github.com/articles/about-forks/) of the BIDS Specification and the pull request will automatically update with those commits. You don't need to submit a new pull request when you make a change in response to a review. diff --git a/DECISION-MAKING.md b/DECISION-MAKING.md index 51aebda63c..32c9d064a7 100644 --- a/DECISION-MAKING.md +++ b/DECISION-MAKING.md @@ -25,6 +25,15 @@ community decides on the content of this file using the same process as any other change to the Repository (see below) allowing the meaning of "Contributor" to evolve independently of the Decision-making rules. +**Maintainer** - a Contributor responsible for the long term health of the +project and the community. Maintainers have additional rights (see Rules) +helping them to resolve conflicts and increase the pace of the development +when necessary. Current Maintainers: + +| Name | Time commitment | +|-----------------------------------------------------------------|-----------------| +| Stefan Appelhoff ([@sappelhoff](https://github.com/sappelhoff)) | 5h/week | + ## Rules 1. Every modification of the specification (including a correction of a typo, @@ -45,6 +54,11 @@ to evolve independently of the Decision-making rules. 1. Does not feature any [Reviews that Request changes](https://help.github.com/articles/about-required-reviews-for-pull-requests/). 1. Does not feature "WIP" in the title (Work in Progress). 1. Passes all automated tests. + 1. Is not proposing a new release or has been approved by at least one + Maintainer (i.e., PRs proposing new releases need to be approved by at + least one Maintainer). +1. A Maintainer can merge any PR - even if it's not eligible to merge according + to Rule 4. 1. Any Contributor can Review a PR and Request changes. If a Contributor Request changes they need to provide an explanation what changes should be added and justification of their importance. Reviews requesting @@ -54,7 +68,7 @@ to evolve independently of the Decision-making rules. 1. If the author of a PR and Contributor who provided Review that Requests changes cannot find a solution that would lead to the Contributor dismissing their review or accepting the changes the Review can be Dismissed with a - vote. Rules governing voting: + vote or by a Maintainer. Rules governing voting: 1. A Vote can be triggered by any Contributor, but only after 5 working days from the time a Review Requesting Changes has been raised and in case a Vote has been triggered previously no sooner than 15 working days since @@ -70,13 +84,16 @@ to evolve independently of the Decision-making rules. ## Comments +1. Researchers preparing academic manuscripts describing work that has been + merged into this repository are strongly encouraged to invite all + Maintainers as co-authors as a form of appreciation for their work. 1. There are no restrictions on how the content of the PR is prepared. For example it is perfectly fine for a PR to consist of content developed by a group of experts over an extended period of time via in person meetings and online collaborations using a Google Document. -1. To facilitate triaging of incoming PR you can subscribe to +1. To facilitate triage of incoming PR you can subscribe to notifications for new PRs proposing changes to specific files. To do this - add your Github name next to the file you want to subscribe to in the + add your GitHub name next to the file you want to subscribe to in the [CODEOWNERS](CODEOWNERS). This way you will be ask to review each relevant PR. Please mind that lack of your review will not prevent the PR from being merged so if you think the PR needs your attention, please review it diff --git a/Release_Protocol.md b/Release_Protocol.md index 519be65c63..3ff0608a0e 100644 --- a/Release_Protocol.md +++ b/Release_Protocol.md @@ -19,7 +19,7 @@ Important note: The pull request title **needs** to follow this protocol. REL: v ### This will open a period of discussion for 5 business days regarding if we are ready to release. This will also freeze all pull request merging. -If we determine we are ready to release, please have the PR submitter add an additional commit with the date in year-month-date format in parentheses after the version of the date of merging (not opening) (i.e. it should read v1.1.2 (2018-12-28)) and merge this PR. This will mark a new release. On the same day, please also do a github release. To do this please see below. +If we determine we are ready to release, please have the PR submitter add an additional commit with the date in year-month-date format in parentheses after the version of the date of merging (not opening) (i.e. it should read v1.1.2 (2018-12-28)) and merge this PR. This will mark a new release. On the same day, please also do a GitHub release. To do this please see below. ![GH-release-1](release_images/GH-release_1.png "GH-release-1") diff --git a/mkdocs.yml b/mkdocs.yml index 39322ae87c..cc1194b1a6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -15,7 +15,7 @@ nav: - Electroencephalography: 04-modality-specific-files/03-electroencephalography.md - intracranial Electroencephalography: 04-modality-specific-files/04-intracranial-electroencephalography.md - Task events: 04-modality-specific-files/05-task-events.md - - Physiological and other continous recordings: 04-modality-specific-files/06-physiological-and-other-continous-recordings.md + - Physiological and other continuous recordings: 04-modality-specific-files/06-physiological-and-other-continuous-recordings.md - Behavioral experiments (with no MRI): 04-modality-specific-files/07-behavioral-experiments.md - Longitudinal and multi-site studies: 05-longitudinal-and-multi-site-studies.md - Extending the BIDS specification: 06-extensions.md diff --git a/pull_request_template.md b/pull_request_template.md new file mode 100644 index 0000000000..7f01ddbc69 --- /dev/null +++ b/pull_request_template.md @@ -0,0 +1,17 @@ +--- PLEASE READ AND DELETE THE TEXT BELOW BEFORE OPENING THE PULL REQUEST --- + +- Please keep the title of your pull request short but informative - it will + appear in the changelog +- Use one of the following prefixes in the title of your pull request: + - `[ENH]` - enhancement of the specification that adds a new feature or + support for a new data type + - `[FIX]` - fix of a typo or language clarification + - `[INFRA]` - changes to the infrastructure automating the specification + release (for example building HTML docs etc.) + - `[MISC]` - everything else including changes to the file listing + contributors +- If you are opening a pull request to obtain early feedback, but the changes + are not ready to be merged (a.k.a. Work in Progress pull request) please + use a [draft pull request](https://github.blog/2019-02-14-introducing-draft-pull-requests/) + +--- PLEASE READ AND DELETE THE TEXT ABOVE BEFORE OPENING THE PULL REQUEST --- diff --git a/src/01-introduction.md b/src/01-introduction.md index e077e6cbb9..fe0f66b676 100644 --- a/src/01-introduction.md +++ b/src/01-introduction.md @@ -45,7 +45,7 @@ different backgrounds. ## Extensions The BIDS specification can be extended in a backwards compatible way and will -evolve over time. This is accomplished through community-driven BIDS Extention +evolve over time. This is accomplished through community-driven BIDS Extension Proposals (BEPs). For more information about the BEP process, and list of current BEP proposals, see [Extending the BIDS specification](06-extensions.md). diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 2138fe03b6..3dfc31a501 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -109,6 +109,29 @@ these data are to be included: 1. We RECOMMEND including the PDF print-out with the actual sequence parameters generated by the scanner in the `sourcedata` folder. +Alternatively one can organize their data in the following way + +```Text +my_dataset/ + sourcedata/ + ... + rawdata/ + dataset_description.json + participants.tsv + sub-01/ + sub-02/ + ... + derivatives/ + ... +``` + +In this example **only the `rawdata` subfolder needs to be BIDS compliant** +dataset. This specification does not prescribe anything about the contents of +`sourcedata` and `derivatives` folders in the above example - nor does it +prescribe the `sourcedata`, `derivatives`, or `rawdata` folder names. The above +example is just a convention that can be useful for organizing raw, source, and +derived data while maintaining BIDS compliancy of the raw data folder. + ## The Inheritance Principle Any metadata file (`.json`, `.bvec`, `.tsv`, etc.) may be defined at any @@ -206,7 +229,7 @@ possible. Since the NIfTI standard offers limited support for the various image acquisition parameters available in DICOM files, we RECOMMEND that users provide additional meta information extracted from DICOM files in a sidecar JSON file (with the same filename as the `.nii[.gz]` file, but with a `.json` extension). -Extraction of BIDS compatible metadata can be performed using [dcm2nii](https://www.nitrc.org/projects/dcm2nii/) +Extraction of BIDS compatible metadata can be performed using [dcm2niix](https://github.com/rordenlab/dcm2niix) and [dicm2nii](http://www.mathworks.com/matlabcentral/fileexchange/42997-dicom-to-nifti-converter/content/dicm2nii.m) DICOM to NIfTI converters. A provided [validator](https://github.com/bids-standard/bids-validator) diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md index 905586e8b8..341602fd4b 100644 --- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md +++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @@ -20,7 +20,7 @@ by Ben Inglis: | HardcopyDeviceSoftwareVersion | (Deprecated) Manufacturer’s designation of the software of the device that created this Hardcopy Image (the printer). Corresponds to DICOM Tag 0018, 101A `Hardcopy Device Software Version` | | MagneticFieldStrength | RECOMMENDED. Nominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018,0087 `Magnetic Field Strength` | | ReceiveCoilName | RECOMMENDED. Information describing the receiver coil. Corresponds to DICOM Tag 0018, 1250 `Receive Coil Name`, although not all vendors populate that DICOM Tag, in which case this field can be derived from an appropriate private DICOM field | -| ReceiveCoilActiveElements | RECOMMENDED. Information describing the active/selected elements of the receiver coil. This doesn’t correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. As an example, for Siemens, coil channels are typically not activated/selected individually, but rather in pre-defined selectable "groups" of individual channels, and the list of the "groups" of elements that are active/selected in any given scan populates the `Coil String` entry in Siemen’s private DICOM fields (e.g., `HEA;HEP` for the Siemens standard 32 ch coil when both the anterior and posterior groups are activated). This is a flexible field that can be used as most appropriate for a given vendor and coil to define the "active" coil elements. Since individual scans can sometimes not have the intended coil elements selected, it is preferable for this field to be populated directly from the DICOM for each individual scan, so that it can be used as a mechanism for checking that a given scan was collected with the intended coil elements selected | +| ReceiveCoilActiveElements | RECOMMENDED. Information describing the active/selected elements of the receiver coil. This doesn’t correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. As an example, for Siemens, coil channels are typically not activated/selected individually, but rather in pre-defined selectable "groups" of individual channels, and the list of the "groups" of elements that are active/selected in any given scan populates the `Coil String` entry in Siemens’ private DICOM fields (e.g., `HEA;HEP` for the Siemens standard 32 ch coil when both the anterior and posterior groups are activated). This is a flexible field that can be used as most appropriate for a given vendor and coil to define the "active" coil elements. Since individual scans can sometimes not have the intended coil elements selected, it is preferable for this field to be populated directly from the DICOM for each individual scan, so that it can be used as a mechanism for checking that a given scan was collected with the intended coil elements selected | | GradientSetType | RECOMMENDED. It should be possible to infer the gradient coil from the scanner model. If not, e.g. because of a custom upgrade or use of a gradient insert set, then the specifications of the actual gradient coil should be reported independently | | MRTransmitCoilSequence | RECOMMENDED. This is a relevant field if a non-standard transmit coil is used. Corresponds to DICOM Tag 0018, 9049 `MR Transmit Coil Sequence` | | MatrixCoilMode | RECOMMENDED. (If used) A method for reducing the number of independent channels by combining in analog the signals from multiple coil elements. There are typically different default modes when using un-accelerated or accelerated (e.g. GRAPPA, SENSE) imaging | diff --git a/src/04-modality-specific-files/02-magnetoencephalography.md b/src/04-modality-specific-files/02-magnetoencephalography.md index 88d67ed680..96ccf2d10c 100644 --- a/src/04-modality-specific-files/02-magnetoencephalography.md +++ b/src/04-modality-specific-files/02-magnetoencephalography.md @@ -352,7 +352,7 @@ For more information on typical coordinate systems for MEG-MRI coregistration: or: [http://neuroimage.usc.edu/brainstorm/CoordinateSystems](http://neuroimage.usc.edu/brainstorm/CoordinateSystems) -### Landmark photos (`*_photo.jpg`) +## Landmark photos (`*_photo.jpg`) Photos of the anatomical landmarks and/or head localization coils (`*_photo.jpg`) @@ -378,7 +378,7 @@ actual anatomical nasion: `sub-0001_ses-001_acq-NAS_photo.jpg` ![placement of NAS fiducial](images/sub-0001_ses-001_acq-NAS_photo.jpg "placement of NAS fiducial") -### 3-D head point /electrode locations +## Head shape and electrode description (`*_headshape.`) Template: @@ -391,12 +391,12 @@ sub-