diff --git a/README.md b/README.md index c61cb04..007c443 100644 --- a/README.md +++ b/README.md @@ -19,20 +19,105 @@ See also the [`DCCN project proposal slides`](protocol/Invisible-Flicker_aka_MEG # Table of contents 1. [About the Project](#about-the-project) -2. [Data Analysis](#data-analysis) +2. [Data Curration](#data-curration) + 1. [Philosophy](#philosophy) + 2. [Data Versions](#data-versions) + 3. [Converting Data](#converting-data) +3. [Data Analysis](#data-analysis) 1. [40 Hz Artefact Removal](#40-hz-artefact-removal) 2. [Sensor Level Analysis](#sensor-level-analysis) 3. [Source Level Analysis](#source-level-analysis) 4. [Behavioural Analysis](#behavioural-analysis) -3. [Experiment Management](#experiment-management) +4. [Experiment Management](#experiment-management) 1. [Dependencies](#dependencies) 2. [Quick-Start Guide](#quick-start-guide) 3. [Code Structure](#code-structure) 4. [Advanced Options](#advanced-options) -4. [Testing](#testing) +5. [Testing](#testing) -{DATA_MANAGEMENT} +## Data Curration + +### Philosophy + +For the purpose of transparency, interpretability, and reproducibility, +this project aims to conduct data analysis on BIDS-compliant data from the get-go. Thus, +the source data is converted to BIDS prior to data analysis. However, the conversion +takes place in two steps to incrementally enrich the data structure. + +Data analysis is conducted solely on the completely enriched data set (raw2 below). + +### Data Versions + +The project pilot-data exists in several versions that can all be accessed in the MEG-AHAT +project directory on the DCCN cluster under `/project/3031004.01/pilot-data`. These versions +include: + +1. Source data (`/source/`) contains the data files as they were obtained from their + respective recording devices and includes MEG scans, simultaneous eye-tracking + and presentation log-files, polhemous positional data, and MRI scans. +2. First iteration raw data (`/raw1/`) contains a BIDS-compliant version with minimal + changes. One implication of this is that events are not yet alligned, as the recorded + behavioural data is not set on a time axis at the point of recording. +2. Second iteration raw data (`/raw2/`) contains a BIDS-compliant version of the data + in which the behevioural data recorded along with MEG has been moved to the /meg + directory, and MEG, eyetrack, and behavioural events are enriched and aligned in time. + +### Converting Data + +Converting data between versions is non-trivial and requires both commonly used public +tools and custom scripts. This projects uses the FieldTrip tool [`data2bids`](https://github.com/fieldtrip/fieldtrip/blob/master/data2bids.m) +and custom matlab scripts. + +Source data is converted to raw1 using the +[`/data_curration/convert_source_to_raw1.m`](https://github.com/henneysq/meg-ahat/blob/main/data_curration/convert_source_to_raw1.m) script. + +Raw1 data is converted to raw2 using the +[`/data_curration/convert_raw1_to_raw2.m`](https://github.com/henneysq/meg-ahat/blob/main/data_curration/convert_raw1_to_raw2.m) script. + +#### Eyetrack data + +Currently, eyetracking data is not covered by BIDS, but is added with the [BIDS extension proposal BEP020](https://docs.google.com/document/d/1eggzTCzSHG3AEKhtnEDbcdk-2avXN6I94X8aUPEBVsw/edit#heading=h.9tphvz6ot0j1). + +With this change, eyetracker data is allocated to the `eyetrack/` scans directory and has the `_eyetrack` suffix. + +#### Directory Layout + +``` +pilot-data +|-- raw1 +| |-- dataset_description.json +| |-- participants.tsv +| `-- sub-099 +| |-- ses-001 +| | |-- anat +| | |-- beh +| | |-- eyetrack +| | |-- meg +| | `-- sub-099_ses-001_scans.tsv +| |-- ses-002 +| | |-- beh +| | |-- eyetrack +| | |-- meg +| | `-- sub-099_ses-002_scans.tsv +| `-- sub-099_sessions.tsv +`-- source + `-- sub-099 + |-- ses-001 + | |-- 099_1.ds + | |-- behaviour + | |-- pilot001_3031000.01_20231212_01.ds + | |-- sub-099.pos + | |-- sub-099_ses-001-eyetracking.asc + | |-- sub-099_ses-001-eyetracking.edf + | `-- sub-20231212T163000 + `-- ses-002 + |-- 099_2.ds + |-- behaviour + |-- pilot002_3031000.01_20231214_01.ds + |-- sub-099_ses-002-eyetracking.asc + `-- sub-099_ses-002-eyetracking.edf +``` ## Data Analysis @@ -69,6 +154,8 @@ graph TD; ### 40 Hz Artefact Removal +The 40 Hz cable noise is removed using [`artefact_rejection.m`](analysis/artefact_rejection.m). + ### Sensor Level Analysis ### Source Level Analysis