search

mne-tools / mne-bids

MNE-BIDS is a Python package that allows you to read and write BIDS-compatible datasets with the help of MNE-Python.
https://mne.tools/mne-bids/
BSD 3-Clause "New" or "Revised" License
132 stars 87 forks source link

Add more template-like suggestions to the README that mne-bids auto-writes #1042

Open Remi-Gau opened 2 years ago

Remi-Gau commented 2 years ago

hey

We (BIDS maintainers) are trying to see if we can improve the quality of the average README in BIDS dataset. Those tend to be pretty thin and are missing some information we would like to see there even if it cannot be formalized "yet" into the BIDS specification.

Hoping to leverage the bids converters to help to do.

So I am going around the different BIDS converters repo to see if we can start improving the default README they put in a the BIDS dataset.

There is template that is provided in the BIDS starter kit: https://github.com/bids-standard/bids-starter-kit/blob/main/templates/README.MD

Some possible options:

  1. use this template is
  2. use a subset of it
  3. add a link to the template README
  4. something else (a mix of 2 and 3?)

What do you think? I can try to open a PR if you want.

Also let us know if you think that the template README in the starter kit could / should be improved .

Feel free to disregard if you are already using some version of the template README.

welcome[bot] commented 2 years ago

Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴🏽‍♂️

agramfort commented 2 years ago

my first reaction is that some information would be redundant with DATASET_DESCRIPTION.JSON file.

I would say that maybe README could be generated from DATASET_DESCRIPTION.JSON to be more human readable?

Message ID: @.***>

Remi-Gau commented 2 years ago

my first reaction is that some information would be redundant with DATASET_DESCRIPTION.JSON file.

which one specifically? happy remove redundancy if that piece of info can be found somewhere else

I would say that maybe README could be generated from DATASET_DESCRIPTION.JSON to be more human readable?

Assuming that there is more than the bare minimum in the dataset_description this makes total sense.

Another thing I have done manually in some datasets is copy pasting the summary of the dataset content generated by the BIDS validator into the readme. Automating this could be nice.

sappelhoff commented 2 years ago

we currently have a very basic code for producing the README. In essence we only write two references to it:

see the code: https://github.com/mne-tools/mne-bids/blob/18999ca3d374b7f2338e60dd13658695649950d3/mne_bids/write.py#L280-L315

I would be fine with adding some more "suggestions" of what users could/should fill in manually into that README.