|
| 1 | +# README |
| 2 | + |
| 3 | +(template copied from the BIDS starter kit: |
| 4 | +https://github.com/bids-standard/bids-starter-kit) |
| 5 | + |
| 6 | +The README is usually the starting point for researchers using your data |
| 7 | +and serves as a guidepost for users of your data. A clear and informative |
| 8 | +README makes your data much more usable. |
| 9 | + |
| 10 | +In general you can include information in the README that is not captured by some other |
| 11 | +files in the BIDS dataset (dataset_description.json, events.tsv, ...). |
| 12 | + |
| 13 | +It can also be useful to also include information that might already be |
| 14 | +present in another file of the dataset but might be important for users to be aware of |
| 15 | +before preprocessing or analysing the data. |
| 16 | + |
| 17 | +If the README gets too long you have the possibility to create a `/doc` folder |
| 18 | +and add it to the `.bidsignore` file to make sure it is ignored by the BIDS validator. |
| 19 | + |
| 20 | +More info here: https://neurostars.org/t/where-in-a-bids-dataset-should-i-put-notes-about-individual-mri-acqusitions/17315/3 |
| 21 | + |
| 22 | +## Details related to access to the data |
| 23 | + |
| 24 | +- [ ] Data user agreement |
| 25 | + |
| 26 | +If the dataset requires a data user agreement, link to the relevant information. |
| 27 | + |
| 28 | +- [ ] Contact person |
| 29 | + |
| 30 | +Indicate the name and contact details (email and ORCID) of the person responsible for additional information. |
| 31 | + |
| 32 | +- [ ] Practical information to access the data |
| 33 | + |
| 34 | +If there is any special information related to access rights or |
| 35 | +how to download the data make sure to include it. |
| 36 | +For example, if the dataset was curated using datalad, |
| 37 | +make sure to include the relevant section from the datalad handbook: |
| 38 | +http://handbook.datalad.org/en/latest/basics/101-180-FAQ.html#how-can-i-help-others-get-started-with-a-shared-dataset |
| 39 | + |
| 40 | +## Overview |
| 41 | + |
| 42 | +- [ ] Project name (if relevant) |
| 43 | + |
| 44 | +- [ ] Year(s) that the project ran |
| 45 | + |
| 46 | +If no `scans.tsv` is included, this could at least cover when the data acquisition |
| 47 | +starter and ended. Local time of day is particularly relevant to subject state. |
| 48 | + |
| 49 | +- [ ] Brief overview of the tasks in the experiment |
| 50 | + |
| 51 | +A paragraph giving an overview of the experiment. This should include the |
| 52 | +goals or purpose and a discussion about how the experiment tries to achieve |
| 53 | +these goals. |
| 54 | + |
| 55 | +- [ ] Description of the contents of the dataset |
| 56 | + |
| 57 | +An easy thing to add is the output of the bids-validator that describes what type of |
| 58 | +data and the number of subject one can expect to find in the dataset. |
| 59 | + |
| 60 | +- [ ] Independent variables |
| 61 | + |
| 62 | +A brief discussion of condition variables (sometimes called contrasts |
| 63 | +or independent variables) that were varied across the experiment. |
| 64 | + |
| 65 | +- [ ] Dependent variables |
| 66 | + |
| 67 | +A brief discussion of the response variables (sometimes called the |
| 68 | +dependent variables) that were measured and or calculated to assess |
| 69 | +the effects of varying the condition variables. This might also include |
| 70 | +questionnaires administered to assess behavioral aspects of the experiment. |
| 71 | + |
| 72 | +- [ ] Control variables |
| 73 | + |
| 74 | +A brief discussion of the control variables --- that is what aspects |
| 75 | +were explicitly controlled in this experiment. The control variables might |
| 76 | +include subject pool, environmental conditions, set up, or other things |
| 77 | +that were explicitly controlled. |
| 78 | + |
| 79 | +- [ ] Quality assessment of the data |
| 80 | + |
| 81 | +Provide a short summary of the quality of the data ideally with descriptive statistics if relevant |
| 82 | +and with a link to more comprehensive description (like with MRIQC) if possible. |
| 83 | + |
| 84 | +## Methods |
| 85 | + |
| 86 | +### Subjects |
| 87 | + |
| 88 | +A brief sentence about the subject pool in this experiment. |
| 89 | + |
| 90 | +Remember that `Control` or `Patient` status should be defined in the `participants.tsv` |
| 91 | +using a group column. |
| 92 | + |
| 93 | +- [ ] Information about the recruitment procedure |
| 94 | +- [ ] Subject inclusion criteria (if relevant) |
| 95 | +- [ ] Subject exclusion criteria (if relevant) |
| 96 | + |
| 97 | +### Apparatus |
| 98 | + |
| 99 | +A summary of the equipment and environment setup for the |
| 100 | +experiment. For example, was the experiment performed in a shielded room |
| 101 | +with the subject seated in a fixed position. |
| 102 | + |
| 103 | +### Initial setup |
| 104 | + |
| 105 | +A summary of what setup was performed when a subject arrived. |
| 106 | + |
| 107 | +### Task organization |
| 108 | + |
| 109 | +How the tasks were organized for a session. |
| 110 | +This is particularly important because BIDS datasets usually have task data |
| 111 | +separated into different files.) |
| 112 | + |
| 113 | +- [ ] Was task order counter-balanced? |
| 114 | +- [ ] What other activities were interspersed between tasks? |
| 115 | + |
| 116 | +- [ ] In what order were the tasks and other activities performed? |
| 117 | + |
| 118 | +### Task details |
| 119 | + |
| 120 | +As much detail as possible about the task and the events that were recorded. |
| 121 | + |
| 122 | +### Additional data acquired |
| 123 | + |
| 124 | +A brief indication of data other than the |
| 125 | +imaging data that was acquired as part of this experiment. In addition |
| 126 | +to data from other modalities and behavioral data, this might include |
| 127 | +questionnaires and surveys, swabs, and clinical information. Indicate |
| 128 | +the availability of this data. |
| 129 | + |
| 130 | +This is especially relevant if the data are not included in a `phenotype` folder. |
| 131 | +https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#phenotypic-and-assessment-data |
| 132 | + |
| 133 | +### Experimental location |
| 134 | + |
| 135 | +This should include any additional information regarding the |
| 136 | +the geographical location and facility that cannot be included |
| 137 | +in the relevant json files. |
| 138 | + |
| 139 | +### Missing data |
| 140 | + |
| 141 | +Mention something if some participants are missing some aspects of the data. |
| 142 | +This can take the form of a processing log and/or abnormalities about the dataset. |
| 143 | + |
| 144 | +Some examples: |
| 145 | + |
| 146 | +- A brain lesion or defect only present in one participant |
| 147 | +- Some experimental conditions missing on a given run for a participant because |
| 148 | + of some technical issue. |
| 149 | +- Any noticeable feature of the data for certain participants |
| 150 | +- Differences (even slight) in protocol for certain participants. |
| 151 | + |
| 152 | +### Notes |
| 153 | + |
| 154 | +Any additional information or pointers to information that |
| 155 | +might be helpful to users of the dataset. Include qualitative information |
| 156 | +related to how the data acquisition went. |
| 157 | + |
0 commit comments