From 999b897055994e84915f7e83dc825144efd6a1eb Mon Sep 17 00:00:00 2001 From: Park-Patrick Date: Thu, 11 Oct 2018 12:21:59 -0400 Subject: [PATCH 01/23] pull of common elements from starter kit + some edits --- CONTRIBUTING.md | 105 ++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 93 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a53de5c22e..0469fd4aaa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,95 @@ # Contributors guide -## Markdown style - -The specification documents follow the -[Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). 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). -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. +# Contributing to the BIDS Specification + +:tada::balloon::cake: **Welcome to the BIDS Specification repository!** :cake::balloon::tada: + +:dizzy::hatched_chick::sunny: *We're so excited you're here and want to contribute.* :sunny::hatched_chick::dizzy: + +We hope that these guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know through one of the many ways to [get in touch](#get-in-touch). + +## Table of contents + +Been here before? Already know what you're looking for in this guide? Jump to the following sections: + +* [Joining the BIDS community](#joining-the-community) +* [Get in touch](#get-in-touch) +* [Contributing through GitHub](#contributing-through-github) +* [Make a change with a pull request](#making-a-change-with-a-pull-request) + * [Example pull request](#example-pull-request) +* [Recognizing contributions](#recognizing-contributions) + +## Joining the community + +BIDS - the [Brain Imaging Data Structure][bids] - is a growing community of neuroimaging enthusiasts, and we want to make our resources accessible to and engaging for as many researchers as possible. + +We therefore require that all contributions **adhere to our [Code of Conduct](CODE_OF_CONDUCT.md)**. + +How do you know that you're a member of the BIDS community? You're here! You know that BIDS exists! You're officially a member of the community. It's THAT easy! Welcome! :joy::raised_hands: + +## Get in touch + +## Contributing through GitHub + +[git][git] is a really useful tool for version control. [GitHub][github] sits on top of git and supports collaborative and distributed working. + +We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the BIDS Specification maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! :heart: + +In order to contribute via GitHub you'll need to set up a free account and sign in. Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account/) to help you get going. Remember that you can ask us any questions you need to along the way. + +## Writing in markdown + +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). + +Most of the writing that you'll do will be in [Markdown][markdown]. You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting. For example you could write words as bold (`**bold**`), or in italics (`*italics*`), or as a [link][rick-roll] (`[link](https://https://youtu.be/dQw4w9WgXcQ)`) to another webpage. + +## Making a change with a pull request + +We appreciate all contributions to the BIDS Starter Kit. **THANK YOU** for helping us build this useful resource. :sparkles::star2::dizzy: + +:point_right: Remember that if you're adding information to the [wiki](#wiki) you ***don't need to submit a pull request***. You can just log into GitHub, navigate to the [wiki][bids-starterkit-wiki] and click the **edit** button. + +If you're updating the [code](#code) or the [templates](#templates), the following steps are a guide to help you contribute in a way that will be easy for everyone to review and accept with ease :sunglasses:. + +#### 1. Comment on an existing issue or open a new issue referencing your addition + +This allows other members of the BIDS Starter Kit team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out. + +[This blog][dont-push-pull-request] is a nice explanation of why putting this work in up front is so useful to everyone involved. + +#### 2. [Fork][github-fork] the [BIDS Starter Kit repository][bids-starterkit-repo] to your profile + +This is now your own unique copy of the BIDS Starter Kit. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code! + +Make sure to [keep your fork up to date][github-syncfork] with the master repository, otherwise you can end up with lots of dreaded [merge conflicts][github-mergeconflicts]. + +#### 3. Make the changes you've discussed + +Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. [Help them help you][jerry-maguire] :wink: + +If you feel tempted to "branch out" then please make a [new branch][github-branches] and a [new issue][bids-starterkit-issues] to go with it. + +#### 4. Submit a [pull request][github-pullrequest] + +A member of the BIDS Starter Kit team will review your changes to confirm that they can be merged into the main codebase. + +A [review][github-review] 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][github-fork] of the BIDS Starter Kit [repository][bids-starterkit-repo] and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review. + +GitHub has a [nice introduction][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions :balloon:. + +## Example pull request +Example-Contribution + +
+ +
+ +## Recognizing contributions + +BIDS follows the [all-contributors][all-contributors] specification, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the [BIDS specification][bids-specification]. + +## Thank you! + +You're awesome. :wave::smiley: From 6c8c0737e0c10e414a42819e1966c0e5af184a3d Mon Sep 17 00:00:00 2001 From: Park-Patrick Date: Fri, 12 Oct 2018 04:00:31 -0400 Subject: [PATCH 02/23] Update CONTRIBUTING.md --- CONTRIBUTING.md | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0469fd4aaa..bc7e80cbb1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,9 +2,9 @@ # Contributing to the BIDS Specification -:tada::balloon::cake: **Welcome to the BIDS Specification repository!** :cake::balloon::tada: +**Welcome to the BIDS Specification repository!** -:dizzy::hatched_chick::sunny: *We're so excited you're here and want to contribute.* :sunny::hatched_chick::dizzy: +*We're so excited you're here and want to contribute.* We hope that these guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know through one of the many ways to [get in touch](#get-in-touch). @@ -15,6 +15,7 @@ Been here before? Already know what you're looking for in this guide? Jump to th * [Joining the BIDS community](#joining-the-community) * [Get in touch](#get-in-touch) * [Contributing through GitHub](#contributing-through-github) +* [Writing in markdown](#writing-in-markdown) * [Make a change with a pull request](#making-a-change-with-a-pull-request) * [Example pull request](#example-pull-request) * [Recognizing contributions](#recognizing-contributions) @@ -39,23 +40,27 @@ In order to contribute via GitHub you'll need to set up a free account and sign ## Writing in markdown -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). +The specification documents follow the +[Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). 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). +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. -Most of the writing that you'll do will be in [Markdown][markdown]. You can think of Markdown as a few little symbols around your text that will allow GitHub to render the text with a little bit of formatting. For example you could write words as bold (`**bold**`), or in italics (`*italics*`), or as a [link][rick-roll] (`[link](https://https://youtu.be/dQw4w9WgXcQ)`) to another webpage. +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). ## Making a change with a pull request -We appreciate all contributions to the BIDS Starter Kit. **THANK YOU** for helping us build this useful resource. :sparkles::star2::dizzy: - -:point_right: Remember that if you're adding information to the [wiki](#wiki) you ***don't need to submit a pull request***. You can just log into GitHub, navigate to the [wiki][bids-starterkit-wiki] and click the **edit** button. - -If you're updating the [code](#code) or the [templates](#templates), the following steps are a guide to help you contribute in a way that will be easy for everyone to review and accept with ease :sunglasses:. +We appreciate all contributions to the BIDS Specification. **THANK YOU** for helping us build this useful resource. #### 1. Comment on an existing issue or open a new issue referencing your addition -This allows other members of the BIDS Starter Kit team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out. +This allows other members of the BIDS Specification team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out. -[This blog][dont-push-pull-request] is a nice explanation of why putting this work in up front is so useful to everyone involved. #### 2. [Fork][github-fork] the [BIDS Starter Kit repository][bids-starterkit-repo] to your profile @@ -65,17 +70,15 @@ Make sure to [keep your fork up to date][github-syncfork] with the master reposi #### 3. Make the changes you've discussed -Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. [Help them help you][jerry-maguire] :wink: - -If you feel tempted to "branch out" then please make a [new branch][github-branches] and a [new issue][bids-starterkit-issues] to go with it. +Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. #### 4. Submit a [pull request][github-pullrequest] -A member of the BIDS Starter Kit team will review your changes to confirm that they can be merged into the main codebase. +A member of the BIDS Specification team will review your changes to confirm that they can be merged into the main codebase. A [review][github-review] 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][github-fork] of the BIDS Starter Kit [repository][bids-starterkit-repo] and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review. +You can update your [fork][github-fork] of the BIDS Specification and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review. GitHub has a [nice introduction][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions :balloon:. From 3bdca0c74ea94585ec74815eb2b013ffcc626ad8 Mon Sep 17 00:00:00 2001 From: Park-Patrick Date: Fri, 12 Oct 2018 04:03:24 -0400 Subject: [PATCH 03/23] Update CONTRIBUTING.md --- CONTRIBUTING.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bc7e80cbb1..04fe368621 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,3 @@ -# Contributors guide # Contributing to the BIDS Specification @@ -26,7 +25,7 @@ BIDS - the [Brain Imaging Data Structure][bids] - is a growing community of neur We therefore require that all contributions **adhere to our [Code of Conduct](CODE_OF_CONDUCT.md)**. -How do you know that you're a member of the BIDS community? You're here! You know that BIDS exists! You're officially a member of the community. It's THAT easy! Welcome! :joy::raised_hands: +How do you know that you're a member of the BIDS community? You're here! You know that BIDS exists! You're officially a member of the community. It's THAT easy! Welcome! ## Get in touch @@ -34,7 +33,7 @@ How do you know that you're a member of the BIDS community? You're here! You kno [git][git] is a really useful tool for version control. [GitHub][github] sits on top of git and supports collaborative and distributed working. -We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the BIDS Specification maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! :heart: +We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the BIDS Specification maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! In order to contribute via GitHub you'll need to set up a free account and sign in. Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account/) to help you get going. Remember that you can ask us any questions you need to along the way. @@ -80,7 +79,7 @@ A [review][github-review] will probably consist of a few questions to help clari You can update your [fork][github-fork] of the BIDS Specification and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review. -GitHub has a [nice introduction][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions :balloon:. +GitHub has a [nice introduction][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions. ## Example pull request Example-Contribution From 0a5654f78e37b5b73c1b1ef5f6b3e226758dac5a Mon Sep 17 00:00:00 2001 From: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com> Date: Fri, 12 Oct 2018 11:40:29 -0700 Subject: [PATCH 04/23] Update CONTRIBUTING.md --- CONTRIBUTING.md | 109 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 95 insertions(+), 14 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a53de5c22e..ce92e5a78e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,95 @@ -# Contributors guide - -## Markdown style - -The specification documents follow the -[Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). 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). -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. + +# Contributing to the BIDS Specification + +**Welcome to the BIDS Specification repository!** + +*We're so excited you're here and want to contribute.* + +We hope that these guidelines are designed to make it as easy as possible to get involved. If you have any questions that aren't discussed below, please let us know through one of the many ways to [get in touch](#get-in-touch). + +## Table of contents + +Been here before? Already know what you're looking for in this guide? Jump to the following sections: + +* [Joining the BIDS community](#joining-the-community) +* [Get in touch](#get-in-touch) +* [Contributing through GitHub](#contributing-through-github) +* [Writing in markdown](#writing-in-markdown) +* [Make a change with a pull request](#making-a-change-with-a-pull-request) +* [Example pull request](#example-pull-request) +* [Recognizing contributions](#recognizing-contributions) + +## Joining the community + +BIDS - the [Brain Imaging Data Structure](http://bids.neuroimaging.io/) - is a growing community of neuroimaging enthusiasts, and we want to make our resources accessible to and engaging for as many researchers as possible. + +We therefore require that all contributions **adhere to our [Code of Conduct](CODE_OF_CONDUCT.md)**. + +How do you know that you're a member of the BIDS community? You're here! You know that BIDS exists! You're officially a member of the community. It's THAT easy! Welcome! + +## Get in touch + +## Contributing through GitHub + +[Git](https://git-scm.com/) is a really useful tool for version control. [GitHub](https://github.com/) sits on top of git and supports collaborative and distributed working. + +We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the BIDS Specification maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! + +In order to contribute via GitHub you'll need to set up a free account and sign in. Here are some [instructions](https://help.github.com/articles/signing-up-for-a-new-github-account/) to help you get going. Remember that you can ask us any questions you need to along the way. + +## Writing in markdown + +The specification documents follow the [Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). + +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. + +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. + +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). + +## Making a change with a pull request + +We appreciate all contributions to the BIDS Specification. **THANK YOU** for helping us build this useful resource. + +#### 1. Comment on an existing issue or open a new issue referencing your addition + +This allows other members of the BIDS Specification team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out. + + +#### 2. [Fork](https://help.github.com/articles/fork-a-repo/) [this repository](https://github.com/bids-standard/bids-specification) to your profile + +This is now your own unique copy of the BIDS Specification. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the specification! + +Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork/) with the master repository, otherwise you can end up with lots of dreaded [merge conflicts](https://help.github.com/articles/about-merge-conflicts/). + +#### 3. Make the changes you've discussed + +Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. Please detail the changes you are attempting to make. + +#### 4. Submit a [pull request](https://help.github.com/articles/about-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. + +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. + +GitHub has a [nice introduction](https://help.github.com/articles/github-flow/) to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions. + +## Example pull request +Example-Contribution + +
+ +
+ +## Recognizing contributions + +BIDS follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the [BIDS specification](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md). + +## Thank you! + +You're awesome. From 63c245a54787dbb3faadf7e56578ab567c9bbf01 Mon Sep 17 00:00:00 2001 From: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com> Date: Wed, 24 Oct 2018 23:29:37 +0000 Subject: [PATCH 05/23] Add files via upload --- CONTRIBUTING.md | 93 +++++++++++++++++++++++++++---------------------- 1 file changed, 52 insertions(+), 41 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 409e2d787e..2b5e72d9fc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,19 +11,17 @@ We hope that these guidelines are designed to make it as easy as possible to get Been here before? Already know what you're looking for in this guide? Jump to the following sections: - -======= -* [Joining the BIDS community](#joining-the-community) -* [Get in touch](#get-in-touch) -* [Contributing through GitHub](#contributing-through-github) -* [Writing in markdown](#writing-in-markdown) -* [Make a change with a pull request](#making-a-change-with-a-pull-request) - * [Example pull request](#example-pull-request) -* [Recognizing contributions](#recognizing-contributions) +* [Joining the BIDS community](#joining-the-community) +* [Get in touch](#get-in-touch) +* [Contributing through GitHub](#contributing-through-github) +* [Writing in markdown](#writing-in-markdown) +* [Make a change with a pull request](#making-a-change-with-a-pull-request) +* [Example pull request](#example-pull-request) +* [Recognizing contributions](#recognizing-contributions) ## Joining the community -BIDS - the [Brain Imaging Data Structure][bids] - is a growing community of neuroimaging enthusiasts, and we want to make our resources accessible to and engaging for as many researchers as possible. +BIDS - the [Brain Imaging Data Structure](http://bids.neuroimaging.io/) - is a growing community of neuroimaging enthusiasts, and we want to make our resources accessible to and engaging for as many researchers as possible. We therefore require that all contributions **adhere to our [Code of Conduct](CODE_OF_CONDUCT.md)**. @@ -33,9 +31,7 @@ How do you know that you're a member of the BIDS community? You're here! You kno ## Contributing through GitHub - -======= -[git][git] is a really useful tool for version control. [GitHub][github] sits on top of git and supports collaborative and distributed working. +[Git](https://git-scm.com/) is a really useful tool for version control. [GitHub](https://github.com/) sits on top of git and supports collaborative and distributed working. We know that it can be daunting to start using git and GitHub if you haven't worked with them in the past, but the BIDS Specification maintainers are here to help you figure out any of the jargon or confusing instructions you encounter! @@ -43,52 +39,69 @@ In order to contribute via GitHub you'll need to set up a free account and sign ## Writing in markdown -======= -The specification documents follow the -[Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). 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). -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. +The specification documents follow the [Markdown Style Guide](http://www.cirosantilli.com/markdown-style-guide/). + +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. + +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. 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). -## Making a change with a pull request +## Building the specification using mkdocs + +We are using mkdocs to render our specification. Please follow these instructions if you would like to build the specification locally. + +#### 1. Install mkdocs + +To begin please follow [this link](https://www.mkdocs.org/#installation) to install mkdocs locally. + +#### 2. Download the BIDS specification [repository](https://github.com/bids-standard/bids-specification/tree/master) onto your computer + +This can be done by clicking the green button the right titled "Clone or download" +#### 3. Install our theme -======= -We appreciate all contributions to the BIDS Specification. **THANK YOU** for helping us build this useful resource. +Please go [here](https://squidfunk.github.io/mkdocs-material/) and install our theme - material. The command is `pip install mkdocs-material` + +#### 4. In the terminal (command line) navigate to your local version of the specification + +This location will have the same files you see on our [main specification page](https://github.com/bids-standard/bids-specification) + +#### 5. Ready to build! + +Using the terminal (command line) please enter `mkdocs serve`. This will allow you to see a local version of the specification. The local address will be `http://127.0.0.1:8000`. You may enter that into your browser and this will bring up the specification! + +## Making a change with a pull request + +We appreciate all contributions to the BIDS Specification. **THANK YOU** for helping us build this useful resource. #### 1. Comment on an existing issue or open a new issue referencing your addition This allows other members of the BIDS Specification team to confirm that you aren't overlapping with work that's currently underway and that everyone is on the same page with the goal of the work you're going to carry out. +#### 2. [Fork](https://help.github.com/articles/fork-a-repo/) [this repository](https://github.com/bids-standard/bids-specification) to your profile -======= -#### 2. [Fork][github-fork] the [BIDS Starter Kit repository][bids-starterkit-repo] to your profile +This is now your own unique copy of the BIDS Specification. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the specification! -This is now your own unique copy of the BIDS Starter Kit. Changes here won't affect anyone else's work, so it's a safe space to explore edits to the code! - -Make sure to [keep your fork up to date][github-syncfork] with the master repository, otherwise you can end up with lots of dreaded [merge conflicts][github-mergeconflicts]. +Make sure to [keep your fork up to date](https://help.github.com/articles/syncing-a-fork/) with the master repository, otherwise you can end up with lots of dreaded [merge conflicts](https://help.github.com/articles/about-merge-conflicts/). #### 3. Make the changes you've discussed -Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. +Try to keep the changes focused. If you submit a large amount of work in all in one go it will be much more work for whomever is reviewing your pull request. Please detail the changes you are attempting to make. -#### 4. Submit a [pull request][github-pullrequest] +#### 4. Submit a [pull request](https://help.github.com/articles/about-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][github-review] 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][github-fork] of the BIDS Specification and the pull request will automatically update with those changes. You don't need to submit a new pull request when you make a change in response to a review. +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. -GitHub has a [nice introduction][github-flow] to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions. +GitHub has a [nice introduction](https://help.github.com/articles/github-flow/) to the pull request workflow, but please [get in touch](#get-in-touch) if you have any questions. ## Example pull request Example-Contribution @@ -99,10 +112,8 @@ GitHub has a [nice introduction][github-flow] to the pull request workflow, but ## Recognizing contributions - -======= -BIDS follows the [all-contributors][all-contributors] specification, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the [BIDS specification][bids-specification]. +BIDS follows the [all-contributors](https://github.com/kentcdodds/all-contributors) specification, so we welcome and recognize all contributions from documentation to testing to code development. You can see a list of current contributors in the [BIDS specification](https://github.com/bids-standard/bids-specification/blob/master/src/99-appendices/01-contributors.md). ## Thank you! -You're awesome. :wave::smiley: +You're awesome. From 184b86880689f9477ae3a1c134fcdc564d1a8cca Mon Sep 17 00:00:00 2001 From: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com> Date: Wed, 24 Oct 2018 16:52:32 -0700 Subject: [PATCH 06/23] Small edit --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2b5e72d9fc..037846fedc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -60,7 +60,7 @@ To begin please follow [this link](https://www.mkdocs.org/#installation) to inst #### 2. Download the BIDS specification [repository](https://github.com/bids-standard/bids-specification/tree/master) onto your computer -This can be done by clicking the green button the right titled "Clone or download" +This can be done by clicking the green button on the right titled "Clone or download" #### 3. Install our theme @@ -68,7 +68,7 @@ Please go [here](https://squidfunk.github.io/mkdocs-material/) and install our t #### 4. In the terminal (command line) navigate to your local version of the specification -This location will have the same files you see on our [main specification page](https://github.com/bids-standard/bids-specification) +This location will have the same files you see on our [main specification page](https://github.com/bids-standard/bids-specification). Note: A finder window may not show the hidden files (those that start with a period i.e. .remarkrc) #### 5. Ready to build! From 98cd12720d6f0e18d48f0e1b8c354eb6963479b4 Mon Sep 17 00:00:00 2001 From: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com> Date: Wed, 24 Oct 2018 16:53:51 -0700 Subject: [PATCH 07/23] Small edit --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 037846fedc..314170e2fa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,7 +64,7 @@ This can be done by clicking the green button on the right titled "Clone or down #### 3. Install our theme -Please go [here](https://squidfunk.github.io/mkdocs-material/) and install our theme - material. The command is `pip install mkdocs-material` +Please go [here](https://squidfunk.github.io/mkdocs-material/) and install our theme - material. The terminal command is `pip install mkdocs-material` #### 4. In the terminal (command line) navigate to your local version of the specification From c3a65301fbfb26813a2413a42f4273105471df3c Mon Sep 17 00:00:00 2001 From: Franklin Feingold <35307458+franklin-feingold@users.noreply.github.com> Date: Tue, 30 Oct 2018 01:21:17 +0000 Subject: [PATCH 08/23] Edits and Additions of Appendix into mkdocs - Added Appendix into the mkdocs.yml - Added most internal links --- 02-common-principles.md | 375 +++++++++++++++++++++++++++++ 02-magnetoencephalography.md | 434 ++++++++++++++++++++++++++++++++++ 03-modality-agnostic-files.md | 200 ++++++++++++++++ 03-task-events.md | 94 ++++++++ CHANGES.md | 110 ++++++--- mkdocs.yml | 9 + 6 files changed, 1190 insertions(+), 32 deletions(-) create mode 100644 02-common-principles.md create mode 100644 02-magnetoencephalography.md create mode 100644 03-modality-agnostic-files.md create mode 100644 03-task-events.md diff --git a/02-common-principles.md b/02-common-principles.md new file mode 100644 index 0000000000..4b4f558bcb --- /dev/null +++ b/02-common-principles.md @@ -0,0 +1,375 @@ +# Common principles + +## Definitions + +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", +"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be +interpreted as described in [[RFC2119](https://www.ietf.org/rfc/rfc2119.txt)]. + +Throughout this protocol we use a list of terms. To avoid misunderstanding we +clarify them here. + +1. Dataset - a set of neuroimaging and behavioural data acquired for a purpose + of a particular study. A dataset consists of data acquired from one or more + subjects, possibly from multiple sessions. + +1. Subject - a person or animal participating in the study. + +1. Session - a logical grouping of neuroimaging and behavioural data consistent + across subjects. Session can (but doesn't have to) be synonymous to a visit + in a longitudinal study. In general, subjects will stay in the scanner + during one session. However, for example, if a subject has to leave the + scanner room and then be re-positioned on the scanner bed, the set of MRI + acquisitions will still be considered as a session and match sessions + acquired in other subjects. Similarly, in situations where different data + types are obtained over several visits (for example fMRI on one day followed + by DWI the day after) those can be grouped in one session. Defining multiple + sessions is appropriate when several identical or similar data acquisitions + are planned and performed on all -or most- subjects, often in the case of + some intervention between sessions (e.g., training). + +1. Data acquisition - a continuous uninterrupted block of time during which a + brain scanning instrument was acquiring data according to particular + scanning sequence/protocol. + +1. Data type - a functional group of different types of data. In BIDS we define + five data types: func (task based and resting state functional MRI), dwi + (diffusion weighted imaging), fmap (field inhomogeneity mapping data such as + field maps), anat (structural imaging such as T1, T2, etc.), meg + (magnetoencephalography). + +1. Task - a set of structured activities performed by the participant. Tasks + are usually accompanied by stimuli and responses, and can greatly vary in + complexity. For the purpose of this protocol we consider the so-called + “resting state” a task. In the context of brain scanning, a task is always + tied to one data acquisition. Therefore, even if during one acquisition the + subject performed multiple conceptually different behaviours (with different + sets of instructions) they will be considered one (combined) task. + +1. Event - a stimulus or subject response recorded during a task. Each event + has an onset time and duration. Note that not all tasks will have recorded + events (e.g., resting state). + +1. Run - an uninterrupted repetition of data acquisition that has the same + acquisition parameters and task (however events can change from run to run + due to different subject response or randomized nature of the stimuli). Run + is a synonym of a data acquisition. + +## Compulsory, optional, and additional data and metadata + +The following standard describes a way of arranging data and writing down +metadata for a subset of neuroimaging experiments. Some aspects of the standard +are compulsory. For example a particular file name format is required when +storing structural scans. Some aspects are regulated but optional. For example a +T2 volume does not need to be included, but when it is available it should be +saved under a particular file name specified in the standard. This standard +aspires to describe a majority of datasets, but acknowledges that there will be +cases that do not fit. In such cases one can include additional files and +subfolders to the existing folder structure following common sense. For example +one may want to include eye tracking data in a vendor specific format that is +not covered by this standard. The most sensible place to put it is next to the +continuous recording file with the same naming scheme but different extensions. +The solutions will change from case to case and publicly available datasets will +be reviewed to include common data types in the future releases of the BIDS +spec. + +## Source vs. raw vs. derived data + +BIDS in its current form is designed to harmonize and describe raw (unprocessed +or minimally processed due to file format conversion) data. During analysis such +data will be transformed and partial as well as final results will be saved. +Derivatives of the raw data (other than products of DICOM to NIfTI conversion) +MUST be kept separate from the raw data. This way one can protect the raw data +from accidental changes by file permissions. In addition it is easy to +distinguish partial results from the raw data and share the latter. Similar +rules apply to source data which is defined as data before harmonization and/or +file format conversion (for example E-Prime event logs or DICOM files). + +This specification currently does not go into details of recommending a +particular naming scheme for including different types of source data (raw event +logs, parameter files, etc. before conversion to BIDS) and data derivatives +(correlation maps, brain masks, contrasts maps, etc.). However, in the case that +these data are to be included: + +1. These data MUST be kept in separate `sourcedata` and `derivatives` folders + each with a similar folder structure as presented below for the BIDS-managed + data. For example: + `derivatives/fmriprep/sub-01/ses-pre/sub-01_ses-pre_mask.nii.gz` or + `sourcedata/sub-01/ses-pre/func/sub-01_ses-pre_task-rest_bold.dicom.tgz` or + `sourcedata/sub-01/ses-pre/func/MyEvent.sce`. + +1. A README file SHOULD be found at the root of the `sourcedata` or the + `derivatives` folder (or both). This file should describe the nature of the + raw data or the derived data. In the case of the existence of a + `derivatives` folder, we RECOMMEND including details about the software + stack and settings used to generate the results. Inclusion of non-imaging + objects that improve reproducibility are encouraged (scripts, settings + files, etc.). + +1. We RECOMMEND including the PDF print-out with the actual sequence parameters + generated by the scanner in the `sourcedata` folder. + +## The Inheritance Principle + +Any metadata file (`.json`, `.bvec`, `.tsv`, etc.) may be defined at any +directory level, but no more than one applicable file may be defined at a given +level (Example 1). The values from the top level are inherited by all lower +levels unless they are overridden by a file at the lower level. For example, +`sub-*_task-rest_bold.json` may be specified at the participant level, setting +TR to a specific value. If one of the runs has a different TR than the one +specified in that file, another `sub-*_task-rest_bold.json` file can be placed +within that specific series directory specifying the TR for that specific run. +There is no notion of "unsetting" a key/value pair. For example if there is a +JSON file corresponding to particular participant/run defining a key/value and +there is a JSON file on the root level of the dataset that does not define this +key/value it will not be "unset" for all subjects/runs. Files for a particular +participant can exist only at participant level directory, i.e +`/dataset/sub-*[/ses-*]/sub-*_T1w.json`. Similarly, any file that is not +specific to a participant is to be declared only at top level of dataset for eg: +`task-sist_bold.json` must be placed under `/dataset/task-sist_bold.json` + +Example 1: Two JSON files at same level that are applicable for NIfTI file. + +```Text +sub-01/ + ses-test/ + sub-test_task-overtverbgeneration_bold.json + sub-test_task-overtverbgeneration_run-2_bold.json + anat/ + sub-01_ses-test_T1w.nii.gz + func/ + sub-01_ses-test_task-overtverbgeneration_run-1_bold.nii.gz + sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz +``` + +In the above example, two JSON files are listed under `sub-01/ses-test/`, which +are each applicable to +`sub-01_ses-test_task-overtverbgeneration_run-2_bold.nii.gz`, violating the +constraint that no more than one file may be defined at a given level of the +directory structure. Instead `task-overtverbgeneration_run-2_bold.json` should +have been under `sub-01/ses-test/func/`. + +Example 2: Multiple run and rec with same acquisition (acq) parameters acq-test1 + +```Text +sub-01/ + anat/ + func/ + sub-01_task-xyz_acq-test1_run-1_bold.nii.gz + sub-01_task-xyz_acq-test1_run-2_bold.nii.gz + sub-01_task-xyz_acq-test1_rec-recon1_bold.nii.gz + sub-01_task-xyz_acq-test1_rec-recon2_bold.nii.gz + sub-01_task-xyz_acq-test1_bold.json +``` + +For the above example, all NIfTI files are acquired with same scanning +parameters (`acq-test1`). Hence a JSON file describing the acq parameters will +apply to different runs and rec files. Also if the JSON file +(`task-xyz_acq-test1_bold.json`) is defined at dataset top level directory, it +will be applicable to all task runs with `test1` acquisition parameter. + +Case 2: Multiple json files at different levels for same task and acquisition +parameters + +```Text +sub-01/ + sub-01_task-xyz_acq-test1_bold.json + anat/ + func/ + sub-01_task-xyz_acq-test1_run-1_bold.nii.gz + sub-01_task-xyz_acq-test1_rec-recon1_bold.nii.gz + sub-01_task-xyz_acq-test1_rec-recon2_bold.nii.gz +``` + +In the above example, the fields from `task-xyz_acq-test1_bold.json` file will +apply to all bold runs. However, if there is a key with different value in +`sub-01/func/sub-01_task-xyz_acq-test1_run-1_bold.json`, the new value will be +applicable for that particular run/task NIfTI file/s. + +## File Formation specification + +### Imaging files + +All imaging data MUST be stored using the NIfTI file format. We RECOMMEND using +compressed NIfTI files (.nii.gz), either version 1.0 or 2.0. Imaging data SHOULD +be converted to the NIfTI format using a tool that provides as much of the NIfTI +header information (such as orientation and slice timing information) as +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/](https://www.nitrc.org/projects/dcm2nii/) +and dicm2nii +[http://www.mathworks.com/matlabcentral/fileexchange/42997-dicom-to-nifti-converter/content/dicm2nii.m](http://www.mathworks.com/matlabcentral/fileexchange/42997-dicom-to-nifti-converter/content/dicm2nii.m) +DICOM to NIfTI converters. A provided +validator[https://github.com/INCF/bids-validator](https://github.com/INCF/bids-validator) +will check for conflicts between the JSON file and the data recorded in the +NIfTI header. + +### Tabular files + +Tabular data MUST be saved as tab delimited values (`.tsv`) files, i.e. csv +files where commas are replaced by tabs. Tabs MUST be true tab characters and +MUST NOT be a series of space characters. Each TSV file MUST start with a header +line listing the names of all columns (with the exception of physiological and +other continuous acquisition data - see below for details). Names MUST be +separated with tabs. String values containing tabs MUST be escaped using double +quotes. Missing and non-applicable values MUST be coded as `n/a`. + +Example: + +```Text +onset duration response_time correct stop_trial go_trial +200 200 0 n/a n/a n/a +``` + +Tabular files MAY be optionally accompanied by a simple data dictionary in a +JSON format (see below). The data dictionaries MUST have the same name as their +corresponding tabular files but with `.json` extensions. Each entry in the data +dictionary has a name corresponding to a column name and the following fields: + +| Field name | Definition | +| :---------- | :--------------------------------------------------------------------------------------------------------------------- | +| LongName | Long (unabbreviated) name of the column. | +| Description | Description of the column. | +| Levels | For categorical variables: a dictionary of possible values (keys) and their descriptions (values). | +| Units | Measurement units. `[] ` format following the SI standard is RECOMMENDED (see Appendix V). | +| TermURL | URL pointing to a formal definition of this type of data in an ontology available on the web. | + +Example: + +```JSON +{ + "test": { + "LongName": "Education level", + "Description": "Education level, self-rated by participant", + "Levels": { + "1": "Finished primary school", + "2": "Finished secondary school", + "3": "Student at university", + "4": "Has degree from university" + } + }, + "bmi": { + "LongName": "Body mass index", + "Units": "kilograms per squared meters", + "TermURL": "http://purl.bioontology.org/ontology/SNOMEDCT/60621009" + } +} +``` + +## Key/value files (dictionaries) + +JavaScript Object Notation (JSON) files MUST be used for storing key/value +pairs. Extensive documentation of the format can be found here: +[http://json.org/](http://json.org/). Several editors have built-in support for +JSON syntax highlighting that aids manual creation of such files. An online +editor for JSON with built-in validation is available at: +[http://jsoneditoronline.org](http://jsoneditoronline.org). JSON files MUST be +in UTF-8 encoding. + +Example: + +```JSON +{ + "RepetitionTime": 3, + "Instruction": "Lie still and keep your eyes open" +} +``` + +## Participant names and other labels + +BIDS uses custom user-defined labels in several situations (naming of +participants, sessions, acquisition schemes, etc.) Labels are strings and MUST +only consist of letters (lower or upper case) and/or numbers. If numbers are +used we RECOMMEND zero padding (e.g., `01` instead of `1` if you have more than +nine subjects) to make alphabetical sorting more intuitive. Please note that the +sub- prefix is not part of the subject label, but must be included in file names +(similarly to other key names). In contrast to other labels, run and echo labels +MUST be integers. Those labels MAY include zero padding, but this is NOT +RECOMMENDED to maintain their uniqueness. + +## Units + +All units SHOULD be specified as per International System of Units (abbreviated +as SI, from the French Système international (d'unités)) and can be SI units or +SI derived units. In case there are valid reasons to deviate from SI units or SI +derived units, the units MUST be specified in the sidecar JSON file. In case +data is expressed in SI units or SI derived units, the units MAY be specified in +the sidecar JSON file. In case prefixes are added to SI or non-SI units (e.g. +mm), the prefixed units MUST be specified in the JSON file (see [Appendix V](https://bids-specification.readthedocs.io/en/latest/99-appendices/05_units.html): +Units). In particular: + +- Elapsed time SHOULD be expressed in seconds. Please note that some DICOM + parameters have been traditionally expressed in milliseconds. Those need to + be converted to seconds. + +- Frequency SHOULD be expressed in Hertz. + +Describing dates and timestamps: + +- Date time information MUST be expressed in the following format + `YYYY-MM-DDThh:mm:ss` (one of the + [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) date-time formats). For + example: `2009-06-15T13:45:30` + +- Time stamp information MUST be expressed in the following format: `13:45:30` + +- Dates can be shifted by a random number of days for privacy protection + reasons. To distinguish real dates from shifted dates always use year 1900 + or earlier when including shifted years. For longitudinal studies please + remember to shift dates within one subject by the same number of days to + maintain the interval information. Example: `1867-06-15T13:45:30` + +- Age SHOULD be given as the number of years since birth at the time of + scanning (or first scan in case of multi session datasets). Using higher + accuracy (weeks) should in general be avoided due to privacy protection, + unless when appropriate given the study goals, e.g., when scanning babies. + +## Directory structure + +### Single session example + +This is an example of the folder and file structure. Because there is only one +session, the session level is not required by the format. For details on +individual files see descriptions in the next section: + +```Text +sub-control01/ + anat/ + sub-control01_T1w.nii.gz + sub-control01_T1w.json + sub-control01_T2w.nii.gz + sub-control01_T2w.json + func/ + sub-control01_task-nback_bold.nii.gz + sub-control01_task-nback_bold.json + sub-control01_task-nback_events.tsv + sub-control01_task-nback_physio.tsv.gz + sub-control01_task-nback_physio.json + sub-control01_task-nback_sbref.nii.gz + dwi/ + sub-control01_dwi.nii.gz + sub-control01_dwi.bval + sub-control01_dwi.bvec + fmap/ + sub-control01_phasediff.nii.gz + sub-control01_phasediff.json + sub-control01_magnitude1.nii.gz + sub-control01_scans.tsv + + code/ + deface.py + derivatives/ + README + participants.tsv + dataset_description.json + CHANGES +``` + +Additional files and folders containing raw data may be added as needed for +special cases. They should be named using all lowercase with a name that +reflects the nature of the scan (e.g., `calibration`). Naming of files within +the directory should follow the same scheme as above (e.g., +`sub-control01_calibration_Xcalibration.nii.gz`) diff --git a/02-magnetoencephalography.md b/02-magnetoencephalography.md new file mode 100644 index 0000000000..556cb929d0 --- /dev/null +++ b/02-magnetoencephalography.md @@ -0,0 +1,434 @@ +# Magnetoencephalography (MEG) + +Support for MEG was developed as a BIDS Extension Proposal. Please cite the +following paper when referring to this part of the standard in context of the +academic literature: + +> Niso Galan, J.G., Gorgolewski, K.J., Bock, E., Brooks, T.L., Flandin, G., +> Gramfort, A., Henson, R.N., Jas, M., Litvak, V., Moreau, J., Oostenveld, R., +> Schoffelen, J.-M., Tadel, F., Wexler, J., Baillet, S., 2018. +> [MEG-BIDS, the brain imaging data structure extended to magnetoencephalography](https://www.nature.com/articles/sdata2018110). +> Scientific Data volume 5, Article number: 180110 (2018) + +## MEG recording data + +Template: + +```Text +sub-/ + [ses-