[ENH] BEP020 examples

.github/workflows/validate_datasets.yml

@@ -74,7 +74,7 @@ jobs:
     - name: Install BIDS validator (dev)
       if: matrix.bids-validator == 'dev'
       run: |
-        git clone -b dev https://github.com/bids-standard/bids-validator/ ../bids-validator
+        git clone -b bep020 https://github.com/bids-standard/bids-validator/ ../bids-validator
         cd ../bids-validator
         deno compile -A -o $HOME/.deno/bin/bids-validator src/bids-validator.ts
 
@@ -107,7 +107,7 @@ jobs:
         fi
 
     - name: Skip legacy validation for post-legacy datasets
-      run: for DS in mrs_* dwi_deriv pet006 pheno004 volume_timing; do touch $DS/.SKIP_VALIDATION; done
+      run: for DS in mrs_* dwi_deriv pet006 pheno004 volume_timing eyetracking_*; do touch $DS/.SKIP_VALIDATION; done
       if: matrix.bids-validator == 'legacy'
 
     - name: Skip stable validation for datasets with unreleased validator features
@@ -119,7 +119,7 @@ jobs:
     - name: Skip main validation for datasets with unreleased spec features
       # Replace ${EMPTY} with dataset patterns, when this is needed
       # Reset to "for DS in ${EMPTY}; ..." after a spec release
-      run: for DS in dwi_deriv pheno004; do touch $DS/.SKIP_VALIDATION; done
+      run: for DS in eyetracking_*; do touch $DS/.SKIP_VALIDATION; done
       if: matrix.bids-validator != 'dev'
 
     - name: Set BIDS_SCHEMA variable for dev version
@@ -128,7 +128,7 @@ jobs:
       # Update this URL to the schema.json from PRs to the spec, when needed.
       # If this variable is unset, dev will generally track the latest development
       # release of https://jsr.io/@bids/schema
-      run: echo BIDS_SCHEMA=https://bids-specification.readthedocs.io/en/latest/schema.json >> $GITHUB_ENV
+      run: echo BIDS_SCHEMA=https://bids-specification--1128.org.readthedocs.build/en/1128/schema.json >> $GITHUB_ENV
 
     - name: Validate all BIDS datasets using bids-validator
       run: |

eyetracking_binocular/README.md

@@ -0,0 +1,24 @@
+# Example BIDS Physio-EyeTracking Dataset - Binocular Recordings
+
+## Data descriptor 
+
+Authors: Martin SZINTE, Guillaume Masson, Jason Samonds & Nicholas Priebe
+BIDS-Conversion: Julia-Katharina Pfarr, Rémi Gau
+BIDS-Example: Julia-Katharina Pfarr, Oscar Esteban
+Project: natImSac
+Version: 1.0
+
+## Data
+
+This example corresponds to the structure of the "natImSac" project, adapted to demonstrate BEP020.
+This example does not contain any eye-tracking data, it just shows the BIDS organization of an experiment with an eye-tracker.
+For the full example preserving the actual eye-tracker recordings, please access the DataLad dataset at https://github.com/julia-pfarr/natImSac_BIDSexample.git. 
+
+The original source data is found at https://github.com/mszinte/natImSac.
+The natImSac involved an experiment in which human participant free view natural images to determine saccade and fixation statistics.
+Full description of the project is found in the following [publication](https://doi.org/10.1523/ENEURO.0287-23.2023).
+Only the eye-tracking data of the original dataset and a subset of participants and runs thereof were kept for this example dataset. 
+
+## Methods (BIDS Conversion)
+
+Sourcedata was converted to raw data according to the BIDS Physio-EyeTracking specification using the [eye2bids](https://github.com/bids-standard/eye2bids) converter tool. 

eyetracking_binocular/dataset_description.json

@@ -0,0 +1,28 @@
+{
+    "Name": "natImSac",
+    "BIDSVersion": "1.10.0-dev",
+    "DatasetType": "raw",
+    "License": "CCBY4",
+    "Authors": [
+      "Martin Szinte",
+      "Guillaume Masson",
+      "Jason Samonds",
+      "Nicholas Priebe"
+    ],
+    "HowToAcknowledge": "Please cite this paper: https://doi.org/10.1523/ENEURO.0287-23.2023",
+    "Funding": [
+        "This research was funded by Agence Nationale de la Recherche ANR-20NEUC-0002 (G.S.M.) and National Institutes of Health NIH-R01NS120562 (N.J.P.), NIH-R01EY025102 (N.J.P.), and NIH-R01EY034092 (J.M.S.)."
+    ],
+    "GeneratedBy": [
+    {
+      "Name": "eye2bids",
+      "CodeURL": "https://github.com/bids-standard/eye2bids"
+    }
+  ],
+    "SourceDatasets": [
+      {
+        "URL": "https://github.com/mszinte/natImSac",
+        "Version": "October 2020"
+      }
+    ]
+  }

eyetracking_binocular/participants.json

@@ -0,0 +1,6 @@
+{
+    "participant_id": {
+		"LongName": "patient idnetification",
+		"Description": "anonymized, BIDS compatible identification"
+			  }
+}

eyetracking_binocular/participants.tsv

@@ -0,0 +1,2 @@
+participant_id	
+sub-01	

eyetracking_binocular/sub-01/beh/sub-01_task-FreeView_run-01_events.tsv

@@ -0,0 +1,10 @@
+onset	duration	run_number	trial_number	image_blank_size	image_blank_num
+1785.302201	32.0600146	1	1	2	77
+1817.506034	31.9947156	1	2	1	16
+1849.675358	32.0047486	1	3	1	50
+1881.846792	31.9950453	1	4	1	70
+1914.00865	32.0089389	1	5	1	33
+1946.145349	31.9961995	1	6	1	81
+1978.265709	31.9956032	1	7	2	57
+2010.394642	31.995466	1	8	2	26
+2042.549024	29.9995082	1	9	1	76

eyetracking_binocular/sub-01/beh/sub-01_task-FreeView_run-01_recording-eye1_physio.json

@@ -0,0 +1,9 @@
+{
+  "StartTime": 1648407,
+  "StopTime": 1993390,
+  "CalibrationCount": 1,
+  "CalibrationType": "HV13",
+  "RecordedEye": "left",
+  "AverageCalibrationError": 0.29,
+  "MaximalCalibrationError": 0.61
+}

eyetracking_binocular/sub-01/beh/sub-01_task-FreeView_run-01_recording-eye2_physio.json

@@ -0,0 +1,9 @@
+{
+  "StartTime": 1648407,
+  "StopTime": 1993390,
+  "CalibrationCount": 1,
+  "CalibrationType": "HV13",
+  "RecordedEye": "right",
+  "AverageCalibrationError": 0.3,
+  "MaximalCalibrationError": 0.65
+}

eyetracking_binocular/sub-01/beh/sub-01_task-FreeView_run-02_events.tsv

@@ -0,0 +1,10 @@
+onset	duration	run_number	trial_number	image_blank_size	image_blank_num
+2169.998589	32.008892	2	10	2	79
+2202.127506	31.9959166	2	11	2	68
+2234.231261	31.9961381	2	12	2	83
+2266.418559	31.9962044	2	13	1	32
+2298.574443	31.9991934	2	14	2	13
+2330.768193	31.9959178	2	15	1	51
+2362.913755	31.999576	2	16	2	1
+2395.109372	32.0043407	2	17	1	39
+2427.254733	29.9965816	2	18	1	30

eyetracking_binocular/sub-01/beh/sub-01_task-FreeView_run-02_recording-eye1_physio.json

@@ -0,0 +1,9 @@
+{
+  "StartTime": 2078643,
+  "StopTime": 2378110,
+  "CalibrationCount": 1,
+  "CalibrationType": "HV13",
+  "RecordedEye": "left",
+  "AverageCalibrationError": 0.51,
+  "MaximalCalibrationError": 2.54
+}

eyetracking_binocular/sub-01/beh/sub-01_task-FreeView_run-02_recording-eye2_physio.json

@@ -0,0 +1,9 @@
+{
+  "StartTime": 2078643,
+  "StopTime": 2378110,
+  "CalibrationCount": 1,
+  "CalibrationType": "HV13",
+  "RecordedEye": "right",
+  "AverageCalibrationError": 0.51,
+  "MaximalCalibrationError": 3.53
+}

eyetracking_binocular/task-FreeView_events.json

@@ -0,0 +1,48 @@
+{
+    "Columns": [
+        "onset",
+        "duration",
+        "run_number",
+        "trial_number",
+        "image_blank_size",
+        "image_blank_num"
+    ],
+    "Description": "Timing and other properties of events recorded during a run.",
+    "ForeignIndexColumn": "timestamp",
+    "onset": {
+        "Description": "Onset (in seconds) of the event, measured from the beginning of the acquisition of the first data point stored in the corresponding task data file."
+    },
+    "duration": {
+        "Description": "Duration of the event (measured from onset) in seconds."
+    },
+    "run_number": {
+        "Description": "Number of run according to run-<index> specification."
+    },
+    "trial_number": {
+        "Description": "Number of trial within one session."
+    },
+    "image_blank_size": {
+        "Description": "Size of the image displayed, where 1 = 583.7x465.83 pixel and 2 = 1204.87 x 950.44 pixel"
+    },
+    "image_blank_num": {
+        "Description": "Index number of the image displayed from https://github.com/mszinte/natImSac/tree/main/stim."
+    },
+    "TaskName": "FreeView",
+    "EnvironmentCoordinates": "top-left",
+    "InstitutionAddress": "27 Bd Jean Moulin, 13005 Marseille, France",
+    "InstitutionName": "Institut de Neurosciences de la Timone",
+    "StimulusPresentation": {
+        "ScreenDistance": 60,
+        "ScreenOrigin": ["top", "left"],
+        "ScreenRefreshRate": 120,
+        "ScreenSize": [
+            0.696,
+            0.391
+        ],
+        "ScreenResolution": [
+            1919,
+            1079
+        ],
+        "Code": "https://github.com/mszinte/natImSac/tree/main/trials"
+    }
+}

eyetracking_binocular/task-FreeView_physio.json

@@ -0,0 +1,36 @@
+{
+    "Manufacturer": "SR-Research",
+    "PhysioType": "eyetrack",
+    "Columns": [
+        "timestamp",
+        "x_coordinate",
+        "y_coordinate",
+        "pupil_size"
+    ],
+    "timestamp": {
+        "Description": "a continuously increasing identifier of the sampling time registered by the device",
+        "Units": "ms",
+        "Origin": "SystemStartup"
+
+    },
+    "x_coordinate": {
+        "LongName": "Gaze position (x)",
+        "Description": "Gaze position x-coordinate of the recorded eye, in the coordinate units specified in the corresponding metadata sidecar.",
+        "Units": "pixel"
+    },
+    "y_coordinate": {
+        "LongName": "Gaze position (y)",
+        "Description": "Gaze position y-coordinate of the recorded eye, in the coordinate units specified in the corresponding metadata sidecar.",
+        "Units": "pixel"
+    },
+    "pupil_size": {
+        "Description": "Pupil area of the recorded eye as calculated by the eye-tracker in arbitrary units (see EyeLink's documentation for conversion).",
+        "Units": "a.u."
+    },
+    "SampleCoordinateSystem": "gaze-on-screen",
+    "ManufacturersModelName": "EYELINK II CL v5.12 May 12 2017",
+    "DeviceSerialNumber": "CLG-BAF38",
+    "PupilFitMethod": "CENTROID",
+    "SamplingFrequency": 1000,
+    "EyeTrackingMethod": "P-CR"
+}

eyetracking_binocular/task-FreeView_physioevents.json

@@ -0,0 +1,28 @@
+{
+    "Columns": [
+        "onset",
+        "duration",
+        "trial_type",
+        "blink",
+        "message"
+    ],
+    "Description": "Messages logged by the measurement device",
+    "ForeignIndexColumn": "timestamp",
+    "blink": {
+        "Description": "Gives status of the eye.",
+        "Levels": {
+            "0": "Indicates if the eye was open.",
+            "1": "Indicates if the eye was closed."
+        }
+    },
+    "message": {
+        "Description": "String messages logged by the eye-tracker."
+    },
+    "trial_type": {
+        "Description": "Event type as identified by the eye-tracker's model.",
+        "Levels": {
+            "fixation": "Indicates a fixation.",
+            "saccade": "Indicates a saccade."
+        }
+    }
+}

eyetracking_fmri/CHANGES

@@ -0,0 +1,2 @@
+2.0.6 2025-05-09
+  - updated jsons according to new BEP020 updates

eyetracking_fmri/README

@@ -0,0 +1,21 @@
+Eye-tracking example for BEP020 from OpenNeuro's ds004158 REST_EYE
+
+Sourcedata by : Martin Szinte, Anna Montagnini & Guillaume Masson<br/>
+Sourcedata: https://openneuro.org/datasets/ds004158 
+
+Curated-by: Julia-Katharina Pfarr, Oscar Esteban
+
+## Methods (BIDS Conversion)
+
+Sourcedata was converted to raw data according to the BIDS Physio-EyeTracking specification using the [eye2bids](https://github.com/bids-standard/eye2bids) converter tool. 
+
+Please refer to the source dataset to learn more about the original
+experiment, or to access the full dataset.
+
+## Experiment description
+
+Participants where told to let their mind wonder while keeping fixation to a fixation dot at the screen 
+center.<br/>
+Participants where told to let their mind wonder while keeping fixation to a fixation dot at the screen 
+These data are here use to provide an example of BIDS eyetracking data together with fMRI.<br/>
+

eyetracking_fmri/dataset_description.json

@@ -0,0 +1,12 @@
+{
+    "Name": "rest_eye",
+    "BIDSVersion": "1.1.1",
+    "Authors": [
+        "Martin Szinte",
+        "Anna Montagnini",
+        "Guillaume Masson"
+    ],
+    "Note": "These data are part of a larger dataset and presented here only to provide an example to BIDS eyetracking modality",
+    "DatasetDOI": "doi:10.18112/openneuro.ds004158.v2.0.6",
+    "License": "CC0"
+}

eyetracking_fmri/participants.json

@@ -0,0 +1,24 @@
+{
+	"participant_id": {
+		"LongName": "patient idnetification",
+		"Description": "anonymized, BIDS compatible identification"
+			  },
+	"sex": {
+		"Levels": { 
+			"M" : "Male",
+			"F" : "Female"
+			  }
+		},
+	"age": {
+		"Description" : "Age of the subject at time of scan with 3 digits"
+		},
+    "GUID": {
+        "Description" : "Unique participant ID as set in the INT"
+    },
+    "eTIV": {
+    	"LongName": "EstimatedTotalIntraCranialVol",
+        "Description" : "Estimated total intracranial volume as measured with 'mri_segstats' function of Freesurfer (mri_segstats --subject subjid --etiv-only)",
+        "Units": "mm3"
+    }
+
+}

eyetracking_fmri/participants.tsv

@@ -0,0 +1,2 @@
+participant_id	sex	age	GUID	eTIV
+sub-01	M	35	19B10ABE8F9F	1775498