[ENH] BEP 020 Eye Tracking

[mszinte]

Here is the specifications of the BEP 020 about eye tracking.

• it follows the main discussion initiated on a google document.
• it includes the different modification the group of maintainers suggested to us during our zoom meeting.
• it includes the macros as used in other modality specific extensions
• it includes links toward dataset examples.

Note

We meet regularly and everyone is welcome :
Next meeting August 1st 2024 2pm CET on zoom.
Note that if you consider joining but this time or day doesn't suits you, reach me (@mszinte) and I will arrange another appointment.

Notes of last meeting

Chat and discussions also happening on matrix

We are currently drafing a companion paper for this BEP, feel free to participate (GoogleDoc)

Tip

HTML preview of this BEP

Issues for:

• general todo list: To do list mszinte/bids-specification#1
• conversion discussion: Converter roadmap mszinte/bids-specification#4
• list datasets: eyetracking dataset examples mszinte/bids-specification#3

---

• implement macros
  • for filename templates ?
  • for examples ?
  • for metadata table
• add contributors to the wiki (so they can be added to the contributors page)
• end docmentation
• update examples
• update validator
• update list of contributors via the github wiki

[sappelhoff]

(NOTE: I'll cross-post this message across several BEP threads)

Hi there, just a quick notification that we have just merged #918 and it may be interesting to look at the implications for this BEP.

We are introducing "BIDS URIs", which unify the way we refer to and point to files in BIDS datasets (as opposed to "dataset-relative" or "subject-relative" or "file-relative" links).

If the diff and discussion in the PR is unclear, you can also read the rendered version: https://bids-specification.readthedocs.io/en/latest/02-common-principles.html#bids-uri

Perhaps there are things in the BEP that need adjusting now, but perhaps also not -- in any case it's good to be aware of this new feature!

Let me know if there are any questions, comments, or concerns.

[oesteban]

@Remi-Gau @mszinte I'm struggling with keeping _stim.<tsv.gz|json> within the physio section and not moving it here https://bids-specification--1128.org.readthedocs.build/en/1128/modality-specific-files/task-events.html#stimuli

_stim.<tsv.gz|json> looks like a highly organic growth embedded within physio for the only reason of tsv.gz files. Should I move the stuff about the columns to the tabular data in the common principles? EDIT: and then stim into the task-events section?

[oesteban]

Okay, have a look at #1749 and #1750.

I think defining tsv.gz here in physio is not a good idea, so #1749 would remove a great deal of weight from the BEP.

Then #1750 will just get stim out of the way, which is going to help make this proposal way more readable.

[oesteban]

I have resynced with master after #1749 and #1750 have been finalized and merged. I believe the proposal is now more readable (cc/ @mszinte, @julia-pfarr).

There are still some minimal wrinkles, but I think overall, it is looking good. I'll try to find time for the BIDS Validator before our meeting next week.

[oesteban]

@Remi-Gau one more question about the schema. I think it'd be ideal that the timestamp column was the first one (when present). However, it looks like required columns are always pushed first in the spec. What should we do here?

[Remi-Gau]

Pretty sure that there is a precedent for column order in the schema. Need to check.

[Remi-Gau]

this only describes pupil_size but the tsv content below has 4 columns, wouldn't it be better to have all 4 described?

I think that users can figure it out but I would prefer to avoid having users interprate the specification and be explicit about it.

[julia-pfarr]

I put all descriptions to be written in the json file by the converter...I thought this was just an example to show that all descriptions should be present

[yarikoptic]

AFAIK shouldn't be HTML here -- I can't read it... Use MACRO as below or demonstrate on a simple Text example?

[Remi-Gau]

Problem is that that matches is not in the glossary so we can't have macro yet.

Opened this so we can have it in the glossary and then after make it easier to MACRO the 💩 out of this.
#1781

[Remi-Gau]

See also: #1128 (comment)

[Remi-Gau]

and also... all PRs are rendered as HTML: https://bids-specification--1128.org.readthedocs.build/en/1128/modality-specific-files/physiological-recordings.html#physiology-events

😉

[oesteban]

AFAIK shouldn't be HTML here -- I can't read it... Use MACRO as below or demonstrate on a simple Text example?

Yes, we're using this to set some expectation for the macros to deal with this.

[yarikoptic]

shameless plug: this is the situation I would like to avoid in

• Uniformize .tsv and .tsv.gz: both to have header + both have "Columns" dictionary (!not list) in sidecar .json  bids-2-devel#71

where I guess such file would look like

{
    "Description": "Messages logged by the measurement device",
    "ForeignIndexColumn": "timestamp",
    "Columns": {
       "onset": { "Index": 1},
       "duration": {"Index": 2},
       "trial_type": {
           "Description": "Event type as identified by the eye-tracker's model (either 'n/a' if not applicabble, 'fixation', or 'saccade')."
           "Index": 3}, 
       "blink": {
         "Description": "One indicates if the eye was closed, zero if open."
         "Index" : 4},
       "message": {
         "Description": "String messages logged by the eye-tracker.",
         "Index": 5}
}

[oesteban]

I'm +1 on this and the solution.

However, I understand that can only be implemented in BIDS 2.0 because would introduce backward breaking changes, right?

If so, I think this is something we cannot resolve here :(

[effigies]

Sorry, I haven't been following this, but if adding a timestamp column is an issue, have you looked at blood for prior art, which has a time column in seconds from scan start?

[oesteban]

Sorry, I haven't been following this, but if adding a timestamp column is an issue, have you looked at blood for prior art, which has a time column in seconds from scan start?

It is not an issue (other than whether we are correctly configuring the schema #1128 (comment) and allowing an optional column to be placed first in the file when there are two mandatory columns after)

It seems that most of the ET devices do generate a timestamp/time column, so that would not be problematic at all.

[Remi-Gau]

As mentioned yesterday in the meeting: only for on-screen eyetracking.

Makes the validation of those a bit more complicated (one extra If).

I wonder if we should not have a similar warning in the eyetracking section, or at least a link to the task page.

[oesteban]

@rwblair can we get your input about allowing/validating optional columns to be present (when present) before mandatory columns?

[effigies]

@oesteban #1128 (comment):

Should be doable. Opened a validator issue for it. bids-standard/bids-validator#1948

[Remi-Gau]

assumes the same position for all calibrations / validations

[julia-pfarr]

Is this really the _events.json file or is it the _physioevents.json?

[oesteban]

This is correct, it annotates the events.tsv file, as opposed to the new _physioevents.json.

[julia-pfarr]

So basically in the _physioevents.json file I only have the column names plus their description? And do I need a _events.json file if I do not have an _events.tsv? Because Martins dataset on Open Neuro does not have it.

[oesteban]

Okay, gotcha -- you've actually hit an edge case we do not currently cover:

• We say that some metadata belonging in the _events.json file becomes mandatory if eye tracking is present
• However, BIDS allows task-rest to dismiss the events.tsv file. This BEP could make it mandatory for rest, even if the events.tsv file is just empty (only the header row).

WDYT @effigies @Remi-Gau ?

[oesteban]

(dataset: https://doi.org/10.18112/openneuro.ds004158.v2.0.2)

[julia-pfarr]

Or include it in the physioevents.json? (if this does not disturb too much other stuff) Because that would be easy to include in the converter as we are already asking users to put some metadata manually in themetadata.yml which is read in by our code. The current code actually does that because I understood it wrong, cf my initial question...

[oesteban]

Not sure that is a good idea. If I were to move the metadata from events.json, I would think it'd be better in the physio.json file rather than physioevents.json.

These metadata are about stimulus presentation, so they are likely relevant beyond eye tracking exclusively. Perhaps a reasonable alternative would be to update the specs so these metadata are encoded within stim.json files instead of the events.json files. Either way, they need to allow a json be defined without the corresponding .tsv[.gz] file, or allow empty tables (okay for .tsv but dangerous for .tsv.gz).

[julia-pfarr]

Ok, I'm of course fine with the solution that fits best to BIDS in general but I agree that we should keep this information somehow.

allow a json be defined without the corresponding .tsv[.gz] file

would probably the best solution for this particular BEP as we agreed on .tsv.gz

[julia-pfarr]

In the src/schema/objects/columns.yaml and src/schema/rules/tabular_data/physio.yaml it says "et_timestamp", here it says "timestamp", which is correct?

[oesteban]

Both are correct, these are two different things:

• src/schema/objects/columns.yaml, src/schema/rules/tabular_data/physio.yaml define a et_timestamp column name. This is so to allow the timestamp be different from the already existing timestamp column. This identifier is internal to the schema, so it does not propagate into actual column names.

• the line 672 you commented on is just the necessary specification of the "Columns" metadata, the column name is arbitrary, and in this case it is named "timestamp" but other names would be equally supported.