Using Delay-Duration combiation to annotate HBN two-sgate visula stimulus

[neuromechanist]

The Surround Suppression Task of the Healthy Brain Network Project (HBN) includes a stimulus consisting of 1- a starting 400ms gray background with a small dot at the center of the screen, accompanied by 2- four added circles to the foreground peripheral view. The second part may also modify the background (having stripes). The foreground circles can also have stripes with certain contrast and spatial relation to the background. The start and stop of the stimulus are annotated under the value column of the _events.tsv as STIM-ON and STIM_OFF. The modifiers have their respective columns: background, foreground_contrast, and stimulus_cond.

My first annotation was like this:

"value": {
  "Description": "The event marker value (type).",
  "Levels": {
      "surroundSuppB1_start": "Start of surround suppression block (run) 1",
      "surroundSuppB2_start": "Start of surround suppression block (run) 2",
      "stim_ON": "Stimulation turned on",
      "stim_OFF": "Stimulation off",
  },
  "HED": {
    "surroundSuppB1_start": "(Def/surroundSup-start, Onset)",
    "surroundSuppB2_start": "(Def/surroundSup-start, Onset)",
    "stim_ON": "(Def/stim, Onset)",
    "stim_OFF": "(Def/stim, Offset)"
  },
},
"hed_defs":{
  "Description": "Metadata dictionary for defining the stimulus",
  "HED":{
    "surroundSup-start_def": "(Definition/surroundSup-start,(Visual-presentation, (Background-view, Gray), (Foreground-view, (Dots, Item-count/1, White, (Center-of, Computer-screen)))), Recording)",
    "stim_def": "(Definition/stim, (Visual-presentation, (Background-view, Gray), (Foreground-view, (Dots, Item-count/1, White, (Center-of, Computer-screen)))),(Delay/400 ms, ((Background-view, label/{background}), (Foreground-view, (Peripheral-view,     (Circle, Item-count/4, (Radius, Angle/2 degree))), (Luminance-contrast, Fraction/{forground_contrast}), (Spatial-relation, Label/{stimulue_cond})))))"
    }
}

However, as discussed during HWG on 3/7/2024, this annotation has two main issues with the current HED 8.2:

1. Curly braces ({}) are not allowed in the Definitions because Definitions should be validated independent of the column values.
2. Delay is not currently allowed to be grouped with Onset and Offset.

A solution to avoid additional rows in the _events.tsv is to move the Delay part outside the Definition and use the Duration tag with Delay:

"value": {
  "Description": "The event marker value (type).",
  "Levels": {
      "surroundSuppB1_start": "Start of surround suppression block (run) 1",
      "surroundSuppB2_start": "Start of surround suppression block (run) 2",
      "stim_ON": "Stimulation turned on",
      "stim_OFF": "Stimulation off",
  },
  "HED": {
    "surroundSuppB1_start": "(Def/surroundSup-start, Onset)",
    "surroundSuppB2_start": "(Def/surroundSup-start, Onset)",
    "stim_ON": "(Def/stim, Onset), (Delay/400 ms, {duration}, (Visual-presentation, (Background-view, label/{background}), (Foreground-view, (Peripheral-view, (Circle, Item-count/4, (Radius, Angle/2 degree))), (Luminance-contrast, Fraction/{forground_contrast}), (Spatial-relation, Label/{stimulue_cond})))",
    "stim_OFF": "(Def/stim, Offset)"
  },
},
"hed_defs":{
  "Description": "Metadata dictionary for defining the stimulus",
  "HED":{
    "surroundSup-start_def": "(Definition/surroundSup-start,(Visual-presentation, (Background-view, Gray), (Foreground-view, (Dots, Item-count/1, White, (Center-of, Computer-screen)))), Recording)",
    "stim_def": "(Definition/stim, (Visual-presentation, (Background-view, Gray), (Foreground-view, (Dots, Item-count/1, White, (Center-of, Computer-screen)))))"
  }
}

[VisLab]

This example was discussed at length in the HWG. It can be solved by using the Duration column for expressing the second event process at that event marker (e.g., the visual presentation that is delayed 400 ms). However it was decided that given the prevalence of trial-encoding strategies where multiple event processes are encoded in a single line (e.g., psychoPy, BIDS), that we should support using the Delay tag with Onset, Offset, and Inset as well as Duration. A new attribute will be introduced in schema version 8.3.0 to handle this. @IanCa @happy5214

[happy5214]

What would this attribute be called, and what would its semantics be? How would it be better than just declaring Delay as reserved and special-casing it in the validators?

[VisLab]

Delay and Duration support in Python not quite in Javascript yet.