Formalize specification of shape(s) (AKA contour(s))

[yarikoptic]

Problem space

It came up in the scope of working on https://bids.neuroimaging.io/bep032 , which is currently being transferred from google doc into

• [ENH] microelectrode electrophysiology specification (BEP032) #1705

in the need to describe the "contours" of the

• probes
• shanks (if multiple)
• electrodes (individual sensors on a shank)

Per our discussion with @bids-standard/bep032 folks involved in other BEPs (such as @robertoostenveld ) we saw relation to e.g.

• specification of contours/shapes for EEG electrodes or MEG sensors (attn @bids-standard/raw-electrophys-meg @bids-standard/raw-electrophys-eeg )
  • for MEG there is a https://github.com/mne-tools/mne-python/blob/main/mne/data/coil_def.dat re-shared/re-used centralized definition for shapes/orientations
• electrodes for BEP032 discussed in BEP042 surface electromyography (HDsEMG/EMG) #1371 (attn @bids-standard/bep042)

Definitions space

I see many definitions of 3D shapes could be generalized into

• planar (2D) contour + depth/extrusion
• arbitrary mesh

And in turn planar (2D) contours could be generalized into

• basic shape (circle, square, rectangle) + shape specification (diameter, width, width+height) + orientation
• arbitrary contour -- problematic as could contain arbitrary number of points to describe

Existing structures/definitions in BIDS

• _headshape.pos -- a shape/contour of the head. (interestingly it is for MEG, but for _acq-EEG and EEG section does not define any shapes, only fiducial points and individual xyz of electrodes).
• ???

Potential solutions

shape entity + complimentary shapes/ folder

• Define shape entity so there could be shape_id = shape_<label>.
• Any {probe,shank,electrode}s.{tsv,json} could have shape_id column to associate any particular instance with a specific shape
  • we already have _electrodes.{tsv,json} suffix/sidecar files! so it is just a matter of the fact that any {entity_plural}.{tsv,json} becomes a suffix if within another entity (left comment in Remove the suffix and exclusively use entities in the filename. bids-2-devel#58 (comment))
• shapes.{tsv,json} could potentially provide description of "simple" shapes right there as e.g. with pre-specified columns such as planar_geometry (circle, square), and properties for those (width, radius) as applicable, with value "custom" pointing to the next:
• In a spirit of Make it possible to specify folders layout to be other than sub-{label}/[ses-{label}/] bids-2-devel#54 define top level, shapes/ folder with shape-<label>_shape.pos files to describe shapes for any given probe shape in the .pos format (whatever it is) or adopt some other appropriate formats e.g. for mesh definitions or contours etc. This way there could also form some "reusable" shapes/ collection.

Data structure within sidecar .json

In BEP032 PR # 1705 we suggested to use sidecar json field ProbeContours:

"ProbeContours": {
   "probe_infoid": {
      "<my_probe_id>": {
         "Contour": <list of contour points>,
         "Unit": "<my spatial unit>"
      }
   }
}

Benefits: simple, and immediately would benefit from inheritance principle allowing to define all contours in a single (hopefully, since ATM still would need some entity IIRC, thus might need to be duplicated... needs clarification) ephys.json file on top.

[robertoostenveld]

The definition of probes, shanks (aka legs, the elements within a probe) and electrodes (the elements along a shank) would benefit from some examples to ensure that everyone shares the same terminology. For example, https://doi.org/10.1088/1741-2560/6/3/036003 describes a flexible probe (aka grid) that is designed to cover most of the left hemisphere, that consists of 14 shanks (aka legs), and per shank/leg (or finger, as we call it there) there are 8 to 28 electrodes, leading to 252 electrodes in total.

Do you have published examples of stiff probes with multiple shanks?

[robertoostenveld]

To provide some background considering differences and similarities with EEG and iEEG: for those the electrode array is flexible, hence we try to record individual electrode positions and don't care too much about the shape and outline of the cap/grid/strip itself, unless for plotting a 2-D projection of the data on screen/paper.

For conventional SQUID-based MEG systems, the sensors are fixed in a rigid array and there is only a coregistration of the array as a whole to the head to worry about by the researcher. The original MEG datafile contains the detailed locations and calibration values (related to the shape) of the sensors, as those might differ a bit from one to the next machine even when they are from the same manufacturer and type. Again, the outline of the array is only used for plotting data as a 2-D projection of the data on screen/paper.

The 2D plotting is explained here https://www.fieldtriptoolbox.org/tutorial/plotting/#multiplot-functions and down, for which the 2D layouts are explained here https://www.fieldtriptoolbox.org/tutorial/layout. All EEG/MEG software packages do this similarly, and each package has its own template layouts like mne python, fieldtrip and eeglab (where those for EEGLAB are 34D locations that are projected to a 2D representation on the fly).

[yarikoptic]

Do you have published examples of stiff probes with multiple shanks?

yes, we should include some illustrative figures in each modality on what is meant by each term. Here is a potential paper/figures but I was hoping to find or draw more specific: https://www.nature.com/articles/s41467-019-11628-5/figures/1 .

NB I will now also add to original description pointer to our initial approach within BEP032 via ProbeContours within .json .