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

[Remi-Gau]

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]

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

[agramfort]

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]

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]

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

• mne-bids
• the BIDS papers of the datatypes that were used

see the code:

mne-bids/mne_bids/write.py

Lines 280 to 315 in 18999ca

	def _readme(datatype, fname, overwrite=False):
	"""Create a README file and save it.
	This will write a README file containing an MNE-BIDS citation.
	If a README already exists, the behavior depends on the
	`overwrite` parameter, as described below.
	Parameters
	----------
	datatype : string
	The type of data contained in the raw file ('meg', 'eeg', 'ieeg')
	fname : str | mne_bids.BIDSPath
	Filename to save the README to.
	overwrite : bool
	Whether to overwrite the existing file (defaults to False).
	If overwrite is True, create a new README containing an
	MNE-BIDS citation. If overwrite is False, append an
	MNE-BIDS citation to the existing README, unless it
	already contains that citation.
	"""
	if os.path.isfile(fname) and not overwrite:
	with open(fname, 'r', encoding='utf-8-sig') as fid:
	orig_data = fid.read()
	mne_bids_ref = REFERENCES['mne-bids'] in orig_data
	datatype_ref = REFERENCES[datatype] in orig_data
	if mne_bids_ref and datatype_ref:
	return
	text = '{}References\n----------\n{}{}'.format(
	orig_data + '\n\n',
	'' if mne_bids_ref else REFERENCES['mne-bids'] + '\n\n',
	'' if datatype_ref else REFERENCES[datatype] + '\n')
	else:
	text = 'References\n----------\n{}{}'.format(
	REFERENCES['mne-bids'] + '\n\n', REFERENCES[datatype] + '\n')
	_write_text(fname, text, overwrite=True)

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