bids-standard / bids-starter-kit

Collection of tutorials, wikis, and templates to get you started with creating BIDS compliant datasets

The BIDS starter-kit

https://bids-standard.github.io/bids-starter-kit/

Contributing

There are many ways to get in touch with us! Please see our Contact Page for all the details.

To find out more about all the different ways to contribute to the BIDS Starter Kit, check out our contributing guidelines. They'll tell help you figure out how to contribute via GitHub, how to make a change using issues (you can also check out GitHub's help on issues) and a pull request.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Dora Hermes 💻 🖋 🤔 👀 🚧 📖	Chris Gorgolewski 👀 🚧 🐛	Chris Holdgraf 👀 🖋 🚧	Chris Gahnström 💻 🖋 🤔	Elizabeth DuPre 👀 🚧 🤔 🖋 📖	Utmost Happiness 💻 🖋 🤔	Kirstie Whitaker 👀 🤔 🚧 🖋 📖 🐛
Patrick Park 🤔 🖋 👀	Peer Herholz 💻	Cyril Pernet 💻	Stefan Appelhoff 👀 💻 🖋 🤔	Ilkay Isik 🐛	Teon L Brooks 🐛	ayab 🖋
Remi Gau 🖋	Jaap van der Aar 💻 🖋 🤔	Giulio Castegnaro 💻 🖋 🤔	Franklin Feingold 🐛 👀	Thomas Nichols 👀	Pieter Vandemaele 🐛	Guillaume Flandin 👀 🤔
Robert Oostenveld 🐛 👀 🤔	Happy 🖋	Tal Pal Attia 💻	Kay Robbins 🤔 🖋	Eduard Klapwijk 🤔	Dorien Huijser 🤔	Arshitha Basavaraj 🤔
Lennart Wittkuhn 🤔	Anthony Galassi 🤔 💻	Athanasia Monika Mowinckel 🤔 💻	Yoni Ashar 🤔	dkp 🐛	James Kent 🤔	Chris Benjamin 📖
Isla 📖	Chris Markiewicz 📖	Ankit Gupta 📖	Alex von Lautz 📖	Alexandre Hutton 📖	Abrren Chen 🚧	Gabriel Silveira 🐛 💻
nathan liang 🐛

This project follows the all-contributors specification. Contributions of any kind welcome!

bids-starter-kit's Issues

[philosophy/repo organisation] What is the point of the code samples in this repo

Hey @choldgraf & @dorahermes (and anyone else who wants to chime in!)

@Park-Patrick and I are working together and we're looking through the repo and trying to make it super clear for new arrivals.

One question we have is "why do we want to share all these code snippets to help make json files" (in the matlabCode and pythonCode folders).

My guess on why they're there is to help people make json files from scratch.....but I wonder if either of you have some clearer answers.

Another question is where is best to add in this explanation. I'm guessing that a page on the wiki makes sense? With maybe a link from the README?

R information to the meta-data wiki

As requested by @chrisfilo , I'm doing this as an issue as I can't contribute to the wiki. Here's some markdown regarding writing and reading .json and .tsv files from R.

R

There are several packages for reading and writing JSON files from R. In this example we will be using jsonlite. Remember to install and call a package before using it.

https://github.com/jeroen/jsonlite

Installing required package

install.packages('jsonlite')

Reading a .json file

library(jsonlite)
data = fromJSON('myfile.json', pretty=TRUE)

Writing a .json file

library(jsonlite)
data = {'field1': 'value1', 'field2': 3, 'field3': 'field3'}
writeLines(toJSON(data, pretty=TRUE), file="myData.json")

R

Reading and writing tab separated files comes natively in R, no need for extra packages.

Reading a .tsv file

In this example, we assume the .tsv includes column names (headers), and explicitly set column separator (delimitor) to tab ('\t')

data = read.table('myFile.tsv', header=TRUE, sep='\t')

Writing a .tsv file

When writing files, colum and row names are always saved, we remove row names, and quotes from the outpur explicitly by setting them to FALSE.

data = cbind.data.frame(
  participant_id = c('sub-01', 'sub-02'),
  age = c(20,30),
  sex = c('m','f'))

write.table(data, file='myData.tsv',sep='\t',
  row.names = FALSE, quote = FALSE)

Add link to BIDS conversion tutorial written by Franklin

http://reproducibility.stanford.edu/bids-tutorial-series-part-1a/

Link to other BIDS-related repositories/tutorials

I started documenting some of the BIDS-related functionalities from SPM here:

• https://en.wikibooks.org/wiki/SPM/BIDS

which, I thought, could be linked to from the wiki here if you agree.

More generally, I came across these MATLAB functions:

• https://github.com/lorenzomagazzini/mat-meg-bids

and these in Python:

• https://github.com/robertoostenveld/bids
• https://github.com/spinoza-rec/bidsify
• https://github.com/nejaz1/bidsify
• https://github.com/jmtyszka/bidskit
• https://github.com/cbedetti/Dcm2Bids

it seems like BIDS Starter Kit would be the right place to list them all.

Make Kirstie an admin on this repo

I'm very happy to mentor the BIDS starter kit development - specifically as relates to the GSoC project - but I'm not an admin on this repo. Could anyone make that happen? @dorahermes @choldgraf?

Create glossary for BIDS jargon

Some feedback from new users at the BrainHack Western tutorial was that there are too many unfamiliar technical terms associated with BIDS.
While these terms are needed for accurate communication and consistency, we also see the need for layperson's definitions that are easily understandable.

We imagine this to have two parts:
a) a text (markdown) document on this repo

• i.e. a searchable reference like a traditional glossary
• This document can be continuously growing

b) an easy-to-absorb graphic/video/interactive flashcards

• something visually appealing to cover the important terms

Clarify repo name

Here we call it bids-starter-kit. But another repo is called BIDS-examples. Is it bids or BIDS? I'm happy w/ either but we should be consistent :-)

Update the README to point very clearly to the wiki

At the moment the README contains lots of great information and it does technically link to the wiki, but I don't think it is very clear that there is LOTS more information in the wiki!

So somewhere in the README we need to have a section on (something like) "how do I find information" that highlights the wiki (and potentially contains the answer to #57 ✨

Integrate already existing resources for learning about BIDS

This issue is an easy place to comment if you have made (or know of) useful resources to learn more about BIDS! Please add any and all links - Thank you!! ✨

Tidy up contents page for the wiki

At the moment there's a home page that doesn't say very much and then BIDS wiki page that seems to be more of an intro.

As we're making progress on the CONTRIBUTING guidelines (#63) I think it would be great to also make the landing pages of the wiki (along with the contents sidebar etc) really clear about where information can be found.

@Park-Patrick - please can you have a bit of a think about this? Please ping me if you're not sure though, I'm happy to find some time to give feedback etc. Might be something that's easy to do via slack?

Edit contents of wiki sidebar

At the moment, the _Sidebar file in the wiki lists the various pages, but this is redundant with the Pages tab. Mostly this creates some issues when a new page is added / deleted because two different table of contents have to be updated separately.

We can brainstorm about what info would be useful there (i.e. whatever would be good to have displayed on the side of every wiki page) or leave it minimal for now

Creation of dependencies file list

Hi everyone!

The first thing that our users of the tutorials/scripts will need are the necessary software dependencies.

Some of them, like MATLAB, may already be familiar while others like Python libraries may require some more details (+ links to helpful installation sites).

Additionally, we will also require a requirements.txt file for eventual integration with Jupyter Notebooks and Binder.

@dorahermes @emdupre @KirstieJane , what are your thoughts?

I'd imagine this will be a growing list, but I am happy to start on it!

Google Summer of Code Applicants.

This issue is intended to comment our interest and share advice during the application process for the 2018 GSoC.

Add template for the _meg.json file

Would be great to have code and templates for the MEG specification

Document process / compile FAQ for creating BIDS Apps

Working together with Daniele, Asier and Madhur to document the process of creating a BIDS app.
This will most likely be a page on the wiki!

Create python file to generate dataset description template

A python file required to generate dataset description json file.

Online templates

As suggested by Trey Smith https://docs.google.com/document/d/1HFUkAEE-pB-angVcYe6pf_-fVf4sCpOHKesUvfb8Grc/edit?disco=AAAABBoxE28

Here's something that would help JSON novices: for each type of JSON object you describe in your specification, provide a URL to a template document in jsoneditoronline.org. The template document would have proper example values for the keys of interest, and it would also be schema-aware (define a schema for the relevant object type, and link the template document to that schema).

Look at https://www.jsoneditoronline.org/doc/index.html - JSON schema validation. Super cool feature.

Add contributing guidelines

Possibly inspired by this one from Brain Networks in Python?

https://github.com/WhitakerLab/BrainNetworksInPython/blob/master/CONTRIBUTING.md

Incorporate the bids validator into the wiki

I'm not sure if it should be a new page (my gut instinct) or a page that has a few other bits of information, but I think it's useful to include a description of the validator: http://incf.github.io/bids-validator.

• What it does
• Why its useful
• What it doesn't do (upload data!)
• How it works? (maybe not too necessary)
• Some example outputs (most importantly 🌟)

Choice of headings on useful links page on wiki

I'm not sure that the tools under Python in the Useful links wiki page are in best linked to as "Python" tools.

I think maybe they're there because they're written in python? I feel like they're better collected as "converting to BIDS" tools.

For me I'd expect the "python" tools to be specific to people who want to run their analyses in python.

[To @Park-Patrick and to anyone else who's stopping by] What do you think? Very happy to be "out voted" on this - it may just be a personal reaction from me!

Add CONTRIBUTING.md

Describe how one can contribute to this repository

https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution
https://github.com/emdupre/me-ica/blob/py3/CONTRIBUTING.md

We need to add extra lines about the wiki

Incorporate Patrick's GSoC proposal into this repository

There are lots of lovely paragraphs explaining why we are building the BIDS Starter Kit in your proposal @Park-Patrick! When you have time I think they'd fit really well into the README 😺

Add R Code for templates

Hey
We currently don't have a RCodes folder. Some users will be looking for R files to generate different templates.
I set up R environment for the same and I think it would be great to have ReadMe in RCode Folder where links to setting up R environment for different distributions will be given. Also, the README will be linked to the repo's wiki (Metadata file formats ) for the ease of our users.
I would like to create the requisite R files for template generation.

Regards
Anushka

MINC / BIDS mapping

Hi everyone,

During some discussions that came up at the CONP (Canadian Open Neuroscience Platform) Hackathon in June, we discovered that there were was a lack of mapping between MINC and BIDS.

My understanding was that the main issue was differences in names for metadata tags? (i.e. something like "scan date" would have two different phrases that refer to the same thing.) But maybe someone more familiar with the MINC format could offer more insight into what the problem is.

Is this something that's preventing the adoption of BIDS in the MINC community?

@emdupre @jbpoline do you know anything about this?

[idea] create a datacamp course about BIDSs

DataCamp is an online training platform that includes web based data related courses with game like features. More info at https://www.datacamp.com/teach/

Stats on the wiki

It would be great if the wiki could include statistics about who's making contributions so that we can say "thanks" to members of the community that participate. I found out that you can git-clone the wiki with the following incantation:

git clone https://github.com/incf/bids-starter-kit.wiki.git

We can use whatever git-analytics approach we like to pull out user stats from this. Alternatively we could create a new dummy repository within INCF called something like wiki-stats and the only thing we'd do is occasionally update that repository with the git repo for the wiki. Then I think GitHub's pre-existing repo stats dashboarding would work.

Here's the process, from how I see it:

General overview

The Wiki for the bids starter kit is stored in its own git repository, this lives at:

https://github.com/incf/bids-starter-kit.wiki.git

However we don't have access to the typical GitHub statistics because GH doesn't expose this UI for wikis. So, how can we get "GitHub repository statistics plots for a wiki?"

Solution

Use a "traditional" GitHub repository to mirror all of the changes that happen in the wiki. Since GitHub thinks it's just a "regular" github repository, it'll expose all of the plots for user activity.

Steps

1. Set up a repository that will mirror the start kit wiki (e.g. INCF/bids-starter-kit-wiki)

2. Git clone the repository to your computer

3. Add the wiki repository as a "remote" in git

   git remote add wiki https://github.com/incf/bids-starter-kit.wiki.git
   

4. Now pull in the latest changes to the wiki into your local "wiki mirror" repository

   git pull wiki master
   

5. Finally, push the local repository back to the "wiki mirror" repository on github:

   git push
   

Thoughts? cc @KirstieJane

Full example vs Short example json template differences

Hi @dorahermes @emdupre @KirstieJane

I just noticed that the template json file for the full example and short example are identical.

File paths:
bids-starter-kit/templates/sub-01/ses-01/func/sub-01_ses-01_task-FullExample_run-01_bold.json
bids-starter-kit/templates/sub-01/ses-01/func/sub-01_ses-01_task-ShortExample_run-01_bold.json

Is this something we would like to work on / clarify?

Happy to be the person to do so if we decide to!

Patrick

Harmonise code samples across languages

[caveat] This might be a bit of a big task (I think @Park-Patrick can do it for matlab and python, but we might want to recruit a new contributor to translate into R or any other language).

Before we get started it would be great to be all on the same page about what we're trying to achieve: (see #57 - what is the point of the code samples in this repo).

Once #57 is closed out, the next step is to make sure that what's inside the folders (matlabCode, pythonCode etc) are the same.

I think this means making sure that:

• Each folder has a README file that contains basically the same information, explaining how you can use the scripts and why you'd want to
• The files are all the same. At the moment the pythonCode folder only has createBIDS_dataset_description_json.py while the matlabCode has a lot of different files. It would be great if these were harmonised.

Once these steps are complete, we could get back to #35 and add in an RCode folder ✨

Improvements to this repo before SfN?

I'd like to add a link to this wiki on the SfN poster, and to point people here more generally that want to get started w/ the spec. What other information are we missing? Anything important? I have a few cycles of time to work on this in the next week or two, so wanna make sure it's being spent effectively!

Google summer of code application through INCF

From the GSoC website:

Google Summer of Code is a global program focused on bringing more student developers into open source software development. Students work with an open source organization on a 3 month programming project during their break from school.

The BIDS parent organisation INCF are participating again as a host GSoC organisation. More information can be found at https://www.incf.org/collaborate/tool-development/google-summer-of-code.

If we want to have a great student working on a project for the bids-starter-kit in the summer we need to submit an application to INCF by January 15th 4pm CET.

Here's a list of the current draft proposals to give us an idea of what a proposal looks like! https://www.incf.org/collaborate/tool-development/google-summer-of-code/gsoc-2017-project-ideas

Below I've outlined an idea for how a GSoC student could support the development of the bids-starter-kit. Please share any comments, suggestions & additions!

---

Vision

To build up a set of tutorials for BIDS that are housed in jupyter notebooks (which don’t have to be written in python) and enable mybinder integration so they are fun and interactive ways to learn about BIDS. We're particularly inspired by the Nipype tutorials built by @miykael.

The student would also be integral in building up a community of BIDS users - in particular supporting new and and code nervous folk who just want to do their studies and don’t really care about how they name their files…but who want to do good reproducible science at the same time :)

Timeline

Three stages: 1) collecting together knowledge from current users and developers, 2) turning this information into interactive notebooks, and 3) soliciting feedback from potential users as to what else they want to see. (You could also imagine iterating around 2 and 3 a few times in a best case scenario!)

Mentors

I (Kirstie Whitaker) am happy to be the point person for this - but also very happy for anyone else to take the lead.

I have no opinions on whether it's good to name more than one mentor, but importantly there will certainly be LOTS of opportunities for everyone in the current BIDS community to support the student and build the project together!

---

To do list

• Find out the deadline for submissions to INCF
  • Done by CG on Christmas eve 🎄 and reply recieved on Christmas day 🎅
  • January 15 4pm Swedish time
• Email Malin at INCF to see what the requirements are for GSoC submissions within INCF
  • Done by KW on 5th Jan (late on Friday) - reply received on 6 Jan
• Find a great picture to go with the application (because everyone likes pictures)
  • Added image from Sci Data paper, no porgs, but probably more informative...
• Write the draft - started by @emdupre - available at: https://docs.google.com/document/d/1xkZhCWv-y3QAigzq-vDYJzzMUkQygxBXy8f1s2UoBao/edit?usp=sharing
• Send information to Malin

Add code of conduct

Possibly inspired by the OHBM demo calls code of conduct?

https://github.com/ohbm/OpenScienceDemoCalls/blob/master/Code_of_Conduct.md

Repo Format

Branching off of #7, is there an opinion on moving the repo format to a series of ipython/binder notebooks? I'm thinking something similar to what nipype has for their tutorials.

It seems as though this would be a good fit, as right now code snippets in [R/matlab/python] are being included in the wiki and could be instead executed in the notebooks. This might make it easier for new adopters to play around with the code themselves.

Fix _events.tsv file

@anushkab
Sorry, there is still a pumps_demean in the _events.tsv and it is still called balloon risk. Merged to soon and only saw the matlab code corrections.

Chat communications

We seem to be very happily using GitHub issues for our discussions, but I wonder if we could also supplement these with either a gitter chat room or a slack channel in the brainhack workspace?

Gitter batch in readme?

Should a link to the Gitter batch be added in the readme? I can't see it right now. @chrisfilo @KirstieJane

Upload some non-BIDSified data to the BIDS Examples repo or document where to find some

In his tutorials, Franklin uses data from the NKI Rockland sample to show an example of not-yet-bidsified data.

I think these resources would be super useful to document in the starter kit. Any ideas?

Add information about the BIDS extensions to the wiki

These aren't well documented yet and I think it would be super useful to start sharing experiences!

@chrisfilo has a nice little figure in his neurohackademy talk with a flow chart that is super useful 🙌

Make a page in the wiki with publications related to BIDS

The MEG-BIDS paper was just published this month, but there are more. I think it makes sense to have a page that showcases those papers. They'll be useful to read for anyone getting started, but I think they also lend a little additional oompf as they're peer reviewed and "traditional" publications.

• https://www.nature.com/articles/sdata201644
• https://www.nature.com/articles/sdata2018110

Link other relevant resources

@choldgraf pointed out that mne-tools would be a good resource to keep in mind as we're developing this starter kit. In #10, we also discussed the structuring these resource to resemble nipype tutorials format.

It would be great to update the README (or the wiki) to link out to these resources and any others that might be helpful ! Is there a preference on which, @dorahermes ?

Describe how to create a TSV and a json file in python

@chrisfilo offered to do this

Add template for _events.tsv file in the func data

We do not have a template yet for the _events.tsv file. The best place is probably to add this for the func dataset.

Broken link in community resource

I don't know what type of file the Graphical Representation of BIDS (Brainhack NYC 2018, NY USA - N Markowitz (2018)) should be. (It's part of the community resources in the wiki). When I download the file it doesn't have a suffix and I don't know what programme to open it in!

Wiki does not support contributions from users without push access

Unlike contents of the repository GitHub wiki does not support pull requests. Workarounds exist, but seem to be cumbersome. This has negative impact on new people wanting to contribute.

Any ideas what to do instead? Series of Markdown documents? @dorahermes @KirstieJane @emdupre

Code and Template of anat acquisition type

Collect together people interested in GSoC applications

I'm going to start work on a markdown table that allows people to register their interest and share their work in progress applications.

Utilize templates for our scripts

Right now we have scripts that use python/matlab to generate various BIDS structures, e..g.:

Python: https://github.com/choldgraf/bids-starter-kit/blob/master/pythonCode/createBIDS_dataset_description_json.py

Matlab: https://github.com/INCF/bids-starter-kit/blob/master/matlabCode/createBIDS_dataset_description_json.m

Whereas we also have a nicely-detailed template that's language-agnostic and in the "final" BIDS format:
https://github.com/INCF/bids-starter-kit/blob/master/templates/dataset_description.json

I propose that, wherever we have a pre-defined template such as this, instead of re-creating the same structure with raw matlab/python, we provide code to read in the template and show how to update the fields. This would make things much easier to maintain, and separates out the data structure from the scripting code itself.

What do folks think? If y'all are +1, I think this would be a great new contributor issue as well

Update BIDS website (http://bids.neuroimaging.io) with information from Starter Kit README

The main landing page for anyone searching for information about BIDS is http://bids.neuroimaging.io.

@Park-Patrick has done great work updating the BIDS Starter Kit README with lots of useful information about the background and motivations for BIDS, and this information could also be brought over to the main website (http://bids.neuroimaging.io) (as suggested by @chrisfilo in our discussions in #70).

The pull request would have to go to https://github.com/INCF/BIDS rather than to this repository, but I thought having the discussion of what to transfer over might make sense.

Any thoughts on what should be included on the main website?

Two small fixes to the func json template

The example template file for the bold json file below has a few syntax errors:

https://github.com/INCF/bids-starter-kit/blob/master/templates/sub-01/ses-01/func/sub-01_ses-01_task-ShortExample_run-01_bold.json

Please help us fix them!

Hints

The last line of a json file should not have a comma at the end
The RepetitionFile field must have a numerical value (which doesn't require quotes)
This website can give you helpful feedback about validating your json: https://jsonlint.com/

Link to the BIDS-examples repo

I'm not sure I know exactly what the BIDS-examples repository is for - I think it's mostly for testing software?

What do you all think about whether we need to link to this repository for the starter kit? Is is distracting? On the other hand it might be good to clarify why it exists 😸

Reformat BIDS publications in wiki to include full reference

We have a page of BIDS publications in the wiki and I think it would make sense to include the full reference to the paper, eg in APA style.

So for example:

MEG-BIDS, the brain imaging data structure extended to magnetoencephalography

G Niso et al (2018)

could be formatted as:

Niso, G., Gorgolewski, K. J., Bock, E., Brooks, T. L., Flandin, G., Gramfort, A., … Baillet, S. (2018). MEG-BIDS, the brain imaging data structure extended to magnetoencephalography. Scientific Data, 5, 180110. 10.1038/sdata.2018.110

I'd be open to other ways of formatting the publications though to make that page most useful.

This is a good-first-issue which means it's particularly appropriate for someone looking to make their first contribution. Please don't pick this issue if you're already comfortable contributing to github (please DO choose another way to add what you know about BIDS though!)