for a future issue to be created on bids-specs: creation of an overview file on tasks: *_tasks.tsv

[SylvainTakerkart]

This issue is to log one of @JuliaSprenger 's proposition that was initially made in BEP032, to create an overview text file that quickly describes all the tasks that were used / performed... With @JuliaSprenger , we decided that the discussion of introducing such a file is out of the scope of BEP032 and should be raised as an issue on the bids-specs repo sometimes in the future... Below is a copy of the content of the section that describes what was proposed and what we removed this day from the BEP032 document...

---

3.6 Task information (*_tasks.tsv & *_tasks.json)

The task label is RECOMMENDED for ephys datasets, in particular for in-vivo extra-cellular electrophysiology experiments. If no classic behavioral task was used, a suitable placeholder, e.g. ‘rest’, ‘anesthesia’ or ‘sleep’ can be used. If the task entity was used in the dataset the different task values are REQUIRED to be summarized in a tasks.tsv file with an OPTIONAL tasks.json providing more detailed description of the individual tasks. If necessary, a file can be added to document the events specifically for each task, as described in the task events BIDS specifications. For full usage of the BIDS also the task events BIDS specification can be used to document the task events consistently with functional data.

The _tasks.tsv file has to contain the column task_name with one entry for each task occurring in the dataset. The entries have to start with the task- prefix as used in the folder name. Additional custom column names REQUIRE to be described in the corresponding json sidecar file (_tasks.json)
Optional: Yes

Example of * _tasks.tsv:
task_name config_file force_level comment
task-hold ../tasks/hold.cfg 1 standard task
task-pull ../tasks/pull.cfg 2 modified hold, negative length
task-push ../tasks/push.cfg 1 modified hold, positive length
task-rest ../tasks/rest.cfg n no movement required

It is RECOMMENDED to provide supplementary task information using a tasks.json file. This file can contain additional information regarding the columns in the tasks.tsv file as specified in the BIDS tabular files specification but also custom supplementary information in a custom hierarchical structure within the json file.

Example *_tasks.json:
{
"TaskName": {
"LongName": "Abbreviated task name",
"Description": "Human-readable abbreviated task name”,
}
}
“ConfigFile”: {
“LongName”: “Location of the configuration file”,
“Description”: “Relative or absolute path to the configuration file”,
}
“ForceLevel”: {
“LongName”: “Relative amount of force required for the task”,
“Description”: “Subjective amount of force required for the task”
“Levels”: {
“0”: “participant requires no significant force”,
“1”: “participant requires some force for task completion”,
“2”: “participant requires significant force for task completion“,
“3”: “participant barely manages to apply force for task completion”
}
}
“Comment”: {
“LongName”: “General comments”,
“Description”: “General comments by the experimenter on the typ of the task”
}
“TaskDefinitions”: {
“Hold”: “The hold task consists of the participant initiating the trial [...]”,
“Pull”: “The pull task consists of the participant initiating the trial [...]”
“Push”: “The push task consists of the participant initiating the trial [...]”,
“Rest”: “The rest task consists of the participant initiating the trial [...]”,
}
}

[VisLab]

This would be a useful addition to BIDS. I have a few questions about format.

1. Since task is currently an entity in BIDS, should be a task_descriptions.json at the top level and have each task be a entry keyed by entity name? The current proposal is half-way in between task as an entity (like participants) and task as a suffix (like events).
2. There is a confusion as to the "task" and the components of the task such as Hold, Pull, Push, etc. Is the task going to be the larger task or the individual subactions?
3. We would ask that HED tags be allowed to be included both in the .json and the .tsv file.
   @smakeig, @dorahermes @sappelhoff