[ENH] microelectrode electrophysiology specification (BEP032)

[yarikoptic]

Replaces #1352 submitted from a fork outside of bids-specification.

Add specification for microelectrode electrohpysiology datasets based on the BEP032 proposal

Note

We meet regularly and everyone is welcome

Next meeting: insert date on URL to join

Communication channel: https://framalistes.org/sympa/info/neuroscience-data-structure

Tip

HTML preview of this BEP

---

• To use this WiP schema on sample datasets, see https://deno.land/x/[email protected]#modifying-and-building-a-new-schema on how to use "stock" bids-validator with a custom schema. (attn @TheChymera)

TODOs

• Add (at least one) .md with the section for the added new modality/datatype
• [js] Update all npm dependencies (2023-09-10) legacy-validator#1800
• Please ensure your name is credited on our Contributors appendix.
  To add your name, please edit our Contributors wiki and add your name with the type of contribution.
  For assistance, please tag @bids-standard/maintainers.
• After opening the PR, our continuous integration services will automatically check your contribution for formatting errors and render a preview of the BIDS specification with your changes.
  To see the checks and preview, scroll down and click on the show all checks link.
  From the list, select the Details link of the ci/circleci: build_docs artifact check to see the preview of the BIDS specification.
• Add instructions here on how to run new bids-validator using schema in this PR
  • Currently there is ongoing effort in Add "master-deno" flavor of validator to use as well bids-examples#435 to assess the state of deno based validator against examples, then chore(deps): bump bids-validator/tests/data/bids-examples from c557d1f to 1c30c6e legacy-validator#1798 is the first one trying it on whitelisted set of packages, and I think we should create a helper action for that : https://github.com/bids-standard/bids-validator/issues/1931
• Populate schema with specifications from the google doc ...
  • The majority of changes: [ENH] Schema changes related to BEP032 #1826
• Further markdown description: @Peyman-N is working on a PR
• Define enums of coord spaces to be added -- some image based, some ad-hoc
• Add CI action (likely github) to run bids-validator on sample datasets and this modified schema (@yarikoptic)

Issues this PR would likely to address

• Fixes run node tests in github actions legacy-validator#1375

Issues to see being addressed while working on this BEP (likely to move above) or not (moved below):

• bump min node version to 14 legacy-validator#1634
• Add summary generation to schema-prototype legacy-validator#1481

Other issues which relate but not in scope here and provided for reference/backreference

• Bundle CLI entrypoint with main() call legacy-validator#1669
• Bump date-and-time from 0.14.1 to 0.14.2 in /bids-validator legacy-validator#1133
• CLI --config flag does not find relative paths? legacy-validator#1165
• spit out more informative/meaningful msg whenever some file is not actually accessible legacy-validator#197
• Make it possible to specify folders layout to be other than sub-{label}/[ses-{label}/] bids-2-devel#54

[TheChymera]

I'd really recommend renaming the rotation axes to yaw, roll, and pitch (that would be the analogous angle order). There was no consensus either way on the google docs discussion. Someone said both are confusing, which I guess might be expected, but alpha, beta, gamma, are just more confusing...

[yarikoptic]

I agree -- very adhoc. Let's discuss in google doc

[TheChymera]

https://docs.google.com/document/d/1oG-C8T-dWPqfVzL2W8HO3elWK8NIh2cOCPssRGv23n0/edit?disco=AAAA4fkI4eY

Could you chime in? I think the other guy commenting might be amenable to accepting this as well.

[robertoostenveld]

I agree that both are confusing, but at least alpha, beta and gamma are SO confusing that everyone realizes that additional specification is needed to define them properly. With roll, yaw and pitch it seems at first that all is clear, until you have a number of different people go through different use cases. See the more challenging examples that I posted on the google doc under https://docs.google.com/document/d/1oG-C8T-dWPqfVzL2W8HO3elWK8NIh2cOCPssRGv23n0/edit?disco=AAAA4fkI4eY

[TheChymera]

@robertoostenveld sorry, I only now saw the update, reply there. I don't think confusion on purpose is good in this case, because the documentation is very eclectic so we might be sending people down rabbit holes. Wiki, where people will invariably go first, does a particularly poor job explaining both euler and TB angles for the casual non-mathematics-versed user. The only thing that wiki has going for it here are the aircraft animations on the TB page. Yaw, Pitch, Roll, will be intuited correctly as long as we specify the starting postion. That we can do (1) as (I think, it's pretty vague) is currently proposed, aligning the implant with the world coordinate system (meaning most implants will be at yaw 0 pitch -90 roll 0) or (2) relative to the implantation stereotax normal (meaning most implants will be at 0 0 0).

For comparison, Euler commonly has the normal pointing up so most implants will be.... 0 -180 0 🤔

[lzehl]

in the last BEP032 meeting we discussed further and wanted to follow this approach now (based on the Allen Inst. standard and IBL standard):

Assumption: x,y,z is posterior, ventral, right (unit needs to be specified).

Translational origin (0,0,0) needs to be defined (typically Bregma for rodents).

Rotational origin (0,0,0) is the probe facing up with the tip facing forward. Rotations are all clockwise in degrees and around the tip. For multi-shank probes, the “tip” of the probe is defined as the end of the left shank if you are looking at the electrodes.

• yaw: clockwise when looking down
• pitch: In the direction of the electrode face
• roll: clockwise when looking down at the probe

The depth (unit needs to be specified) is a translation in the direction that the tip is pointing.

We need to add a “probe_model”, which references probeinterface_library

• versioning of probe library files (raised here)
• annotation of “tip” position (raised here)

NOTE: We need to change the electrode x,y,z.
X,y,z in BIDS refers to location in brain, not on probe.

[TheChymera]

The “reference atlas” if you visually verify the area is basically the atlas you looked at before you nod and said “eh, good enough”. This seems at once an overly detailed (does this really matter? the coordinates are commonly given with sub-mm precision) and underdetermined (what coordinates did you look at in the atlas?). I think it's best just to drop this.

[TheChymera]

Also relevant if you'd like to comment. → https://docs.google.com/document/d/1oG-C8T-dWPqfVzL2W8HO3elWK8NIh2cOCPssRGv23n0/edit?disco=AAABIzHGpUU

[TheChymera]

Also I forgot to link to this when I wrote it → https://docs.google.com/document/d/1oG-C8T-dWPqfVzL2W8HO3elWK8NIh2cOCPssRGv23n0/edit?disco=AAABIGPAMOw

[Remi-Gau]

Random suggestion: maybe having a markdown file in the source tree and the mkdoc config so you can at least use a macro to render the filename template.

The HTML version of this could then be reviewed by people still working on the google doc: may help if you don't read BIDS schema yaml fluently.

[Remi-Gau]

Did a few minor fix to pacify pre-commit and make sure the HTML page rendered.

Also check the top message of this PR:
#1705 (comment)

I added some github admonitions that need tweaking so people know where this BEP is discussed.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 87.92%. Comparing base (1cb92eb) to head (73012b3).
Report is 36 commits behind head on master.

❗ Current head 73012b3 differs from pull request most recent head a46e439

Please upload reports for the commit a46e439 to get more accurate results.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    bids-standard/legacy-validator#1705      +/-   ##
==========================================
+ Coverage   87.79%   87.92%   +0.13%     
==========================================
  Files          16       16              
  Lines        1360     1375      +15     
==========================================
+ Hits         1194     1209      +15     
  Misses        166      166              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.