Finalize draft of BEP017 - Relationship matrices

[PeerHerholz]

Hello @bids-standard/maintainers, @bids-standard/steering & everyone,

I hope you're doing fine.

As part of the BIDS Connectivity Extensions Project, we (@eduff, @jdkent, @dorahermes, @francopestilli, @dlevitas, @poldrack, @CPernet, @dmoracze, @sina-mansour, @MaxvandenBoom and others) worked on BEP017 - Relationship matrices. We would like to finalize Step 9 of the BEP development process: Incorporate the feedback and strive for consensus. . Thus, I thought about creating a dedicated issue within which we can track what is still needed in order to do so.

If y'all could have a look at the draft again and share your thoughts re the current status and if something/what definitely still needs to be addressed, that would be great! I'll start a list below and will keep editing it based on your comments.

Needs to be addressed

• NodeIndicesFile has to be added to support use cases besides "standard atlas", e.g. electrode positions, using multiple atlases, etc.
• address time/frequency and directed use cases & add examples
• clear definition and examples of matrix types
• tsv files and their headers: follow existing BIDS specification or not?

Would be cool to address but not necessary

Thanks so much again for all your help and effort, we highly appreciated it.

[PeerHerholz]

Adding @robertoostenveld and @arnodelorme to this.

[PeerHerholz]

Hi folks,

I think a lot of comments/feedback are/is concerned with the definition and examples of different matrix types (as just pointed out by @guiomar). Thus, I thought it might be a good idea to collect these terms here and create the respective definitions. I think we have some sort of conundrum including weighted, directed, symmetric, etc. . Additionally, there is a dependency between those terms, per se and based on the modality at hand (I think), ie "if the matrix is .... it can't be ....".

[guiomar]

As a first approach I would say there are 3 main categories:

Direction:

• Symmetric / undirected / funtional connectivity: a_ij = a_ji (you can take just the upper triangle)
  The relationship between two nodes is symmetric. A<->B
• Asymmetric / directed / effective connectivity: a_ij != a_ji
  The relationship between two nodes is different depending on the direction: A ->B != B->A

Weight:

• Binary: a_ij = 0,±1
  The relationship matrix just indicates if there is relationship between two nodes or not
• Weighted: a_ij = x ∈ C
  The relationship matrix indicates the specific value of the relationship between two nodes

Shape:

• Square: NxN
  Evaluates the relationship of all nodes with all nodes
• Rectangular: N1xN2
  Evaluates the relationship of just a few nodes with few or many others

There can be all possible combinations between the 3 categories, i.e. 6 combinations.
e.g. symetric, binary, squared and so on.

[guiomar]

Sorry, I didn't know when you said "here" if it was here on GH or on the bep doc? :)

[PeerHerholz]

Thx so much @guiomar, this is great. Sorry, I meant here as the discussions in the doc became rather hard to track.

[sina-mansour]

Weight:

• Binary: a_ij = 0,±1
  The relationship matrix just indicates if there is relationship between two nodes or not
• Weighted: a_ij = x ∈ C
  The relationship matrix indicates the specific value of the relationship between two nodes

I really like these 3 main categories. I think regarding the weight category, we could potentially add another detail to indicate if negative weights are allowed. That is, a weighted matrix could be "non-negative" where all elements are equal or greater than zero. This distinction can be included as an optional flag that can only exist in combination with a weighted flag. This would be an informative flag as some graph algorithms are only suited to non-negative matrices.

I think it would be better to replace Rectangular with non-square to be more specific. It is also noteworthy that the symmetric/asymmetric category only concerns square matrices as for symmetry to be defined [A=transpose(A)] the matrix should be square.

Here are some additional useful matrix types that may not fall into these main categories:

Matrix type: There are various graph theoretical terms that describe a very particular tabular structure (this is in cases related to the shape category). Here are some examples that I can think of:

• Adjacency matrix: The matrix describes pairwise nodal connections. Here's a formal definition:
  • An adjacency matrix is a square matrix used to represent a finite graph. For a simple graph with vertex set U = {u1, …, un}, the adjacency matrix is a square n × n matrix A such that its element Aij describes the connectivity from vertex ui to vertex uj.
  • By definition; an adjacency matrix is a square matrix.
  • Adjacency matrix can have any weight types (binary/weighted/nonnegative-weighted)
  • Adjacency matrix can be symmetric or asymmetric.
• Incidence matrix: This is a class of matrices that can be used to describe two sets of objects (e.g. nodes and connections). Here are some features of incidence matrices:
  • Incidence matrices are non-square in most cases (can be square if the two sets of objects happen to be the same number though).
  • They can have any weight types.
  • Symmetry is not usually described for these matrices (refer to the earlier note on nonsquare matrices).
• There are also other matrix types that are commonly used in neuroimaging: Stochastic matrices, similarity matrices, etc.

Storage type: There are different ways in which the same matrix could be stored:

• Dense storage: This is the most common storage type where any NxM matrix is stored as a dense matrix in a tabulated structure (eg. tsv/csv).
• Triangular serialization: For symmetric square matrices, nearly half of the elements in a dense structure are duplicates (excluding the diagonal). As such it is possible to serialize and store only upper/lower triangular section of the dence matrix.
• Sparse storage: For larger matrices (describing billions of interactions over thousands of regions) storing the dense structure can be cumbersome. In many cases such matrices are either sparse-by-nature, or can be sparsified, such that the majority of matrix elements are zeros. These matrices can be stored in a sparse format to save storage requirements. There are different formats for sparse storage (e.g. CSC, CSR, DOK, LIL, etc.) but all can fall under the same sparse storage umbrella category.

Both sparse and dense storage formats can be used to store any combination of other matrix types described earlier (unlike triangular storage which can only be used for symmetric square matrices)

[PeerHerholz]

Thx @sina-mansour for your feedback and comments!

I'll let the others add thoughts concerning the matrix types but regarding storage types I think this could go into the .json metadata. IIRC, you already something along those lines there, right?

[PeerHerholz]

Hi everyone,

@guiomar WDYT about the matrix types outlined by @sina-mansour? Could we integrate them into your specifications?

[PeerHerholz]

Hello everyone,

given the current state of the BEP it's seems about time for a meeting to discuss the latest set of comments to then move on to the next stage, ie moving the BEP to GitHub. Concerning this, I would like to ask if you maybe have time within the first or third week of February and created a respective survey which you can find here.

It would be great of some of you (@eduff, @dorahermes, @francopestilli, @dlevitas, @CPernet, @dmoracze, @sina-mansour, @MaxvandenBoom, @guiomar, @robertoostenveld, @arnodelorme) could make it.

Please let me know if you have any questions and feel free to bring up discussions here.

Cheers, Peer

[sina-mansour]

Hi Peer, Unfortunately, I will be on leave during the first week of Feb, but I have filled in my availability for the third week of Feb. In case that gets to be the favorable option, I'd be more than happy to join the discussion. Cheers, Sina <https://sina-mansour.github.io/> Sina Mansour L. Research Fellow <https://sina-mansour.github.io/> National University of Singapore Computational Brain Imaging Group <https://scholar.google.com/citations?user=GVoC568AAAAJ&hl=en> <https://twitter.com/Sina_Mansour_L> <https://github.com/sina-mansour> <https://gitlab.com/sina_mansour> <https://orcid.org/0000-0002-5695-5696>

…

On Fri, 26 Jan 2024 at 16:14, Peer Herholz ***@***.***> wrote: Hello everyone, given the current state of the BEP it's seems about time for a meeting to discuss the latest set of comments to then move on to the next stage, ie moving the BEP to GitHub. Concerning this, I would like to ask if you maybe have time within the first or third week of February and created a respective survey which you can find here <https://www.when2meet.com/?23349893-SYNix>. It would be great of some of you ***@***.*** <https://github.com/eduff>, @dorahermes <https://github.com/dorahermes>, @francopestilli <https://github.com/francopestilli>, @dlevitas <https://github.com/dlevitas>, @CPernet <https://github.com/CPernet>, @dmoracze <https://github.com/dmoracze>, @sina-mansour <https://github.com/sina-mansour>, @MaxvandenBoom <https://github.com/MaxvandenBoom>, @guiomar <https://github.com/guiomar>, @robertoostenveld <https://github.com/robertoostenveld>, @arnodelorme <https://github.com/arnodelorme>) could make it. Please let me know if you have any questions and feel free to bring up discussions here. Cheers, Peer — Reply to this email directly, view it on GitHub <#1604 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AD235MXEPVZWAYA7CY3KDOLYQNQXRAVCNFSM6AAAAAA4ES64DWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSMJRGY2DMNJZHA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[PeerHerholz]

Hi everyone,

sorry for the late reply, I was afk for a bit.

@sina-mansour, @dorahermes and @dmoracze: Would this Wednesday, 21/02, 3 PM CET/9 AM EST still work for you?
Otherwise, I would send another survey to find a suitable date and time.

Thanks so much again for taking the time and sorry for the late reply.

Cheers, Peer

[dmoracze]

Hi Peer,

Sure, that time still works for me. Thanks!

[guiomar]

It works for me as well! Sorry I have missed this thread.
For sure, we can integrate Sina's matrix proposal, if not already done. I'll have a look :)

[sina-mansour]

Hi Peer,

The time slot works for me too. Thanks for organizing and looking forward to catching up.

Cheers,
Sina

[PeerHerholz]

Hi everyone,

thanks for replying. I'll set a video call and agenda and then share both here.

Cheers, Peer

[PeerHerholz]

Hi again everyone,

I just sent everyone who replied to the survey an invite, including a link to the video call and the agenda. (@dmoracze, I unfortunately don't have your Email, would you mind sending it via discord or so?)
However, you can also find the agenda here and if you want to join the meeting, please respond here and I'll share the link.

Thanks again and see you later, Peer

[MaxvandenBoom]

Hi Peer, sorry couldn't make it, but I see Dora attended.

[eduff]

Apologies I've missed the meeting and recent discussion being on paternity leave. I'm interested to see outcomes from the call. While it is ok if map-based storage of connectivity data uses different suffixes, I believe there are useful standards defined in this bep that can pertain to connectivity data in any format, so this would ideally be made clear imo, unless I'm mistaken.

…

On Sat, 24 Feb 2024, 17:08 Max, ***@***.***> wrote: Hi Peer, sorry couldn't make it, but I see Dora attended. — Reply to this email directly, view it on GitHub <#1604 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAG4KVCFEJNLQONJZM32GODYVINAVAVCNFSM6AAAAAA4ES64DWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMYTSNRSGQZDIOJVGA> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[PeerHerholz]

Hi @MaxvandenBoom and @eduff,

thank you very much for your reply and no worries!
Please feel free to check the agenda if you're interested.

@eduff, yes you're totally right and this was the idea. I adapted things in the latest version of the BEP to outline things respectively, ie that map-based data will use the _<modality>map extension and be accompanied by the meta-data proposed for all relationship data (except matrix-specific information). However, if that's not clearly enough stated in the current version of the BEP, I can of course adapt things respectively.

Please note, that we also talked about changing _meas- to _stat- to avoid introducing a new term while we could use an existing one.

@dmoracze, @dorahermes and @sina-mansour, I implemented the changes we talked about. Would you mind having a look if you have time?

Thanks again.

Cheers, Peer

[PeerHerholz]

Hi team (@eduff, @dorahermes, @MaxvandenBoom, @sina-mansour, @dmoracze, @arnodelorme, @robertoostenveld, @guiomar and of course: everyone else):

I hope you're doing well. As it's been a while and @arnodelorme and I had the chance to meet and talk about different matrix types/formats, I thought it might be great if y'all (if you have time and availabilities), could have another look at the BEP.
Specifically, with regard to the aim of finalizing our draft in the GoogleDoc and moving things to GitHub. Thus, please note down all problems that, in your opinion, need to be addressed before we move forward.

I think all initial points outlined in the beginning (ie here) have been addressed and we additionally made great progress on the different matrix types/formats (e.g. sparse and dense).

Furthermore, I'll reach out to organize a meeting concerning this soon (most likely around mid/late May).

As always: thanks so much for all your help and effort within this project, we highly appreciate it.

Best, Peer

[PeerHerholz]

Hi team (@eduff, @dorahermes, @MaxvandenBoom, @sina-mansour, @dmoracze, @arnodelorme, @robertoostenveld, @guiomar and of course: everyone else):

as @eduff and I had another read-through of the draft, we would like to organize a meeting to prepare the transition to GitHub which will most likely happen during the OHBM Brainhack (please find the respective project submission/issue here).

We set up a little survey to hopefully find a time in the week of June 10th. Thus, if you want/have time, please indicate your availabilities here by the end of next week.

@bids-standard/maintainers if you would also like to join, that would be awesome!

If you have any questions, please don't hesitate to post them here.

Cheers, Peer

[CPernet]

Where does it take place? @snu? I'll be at the stat workshop but could pop in

[PeerHerholz]

Hi @CPernet,

do you mean the BEP017 meeting or the BrainHack?

Best, Peer

[CPernet]

The stat workshop is on Thursday and Friday on the SNU campus, but would escape to meet the team and work on this for a few hours -- depends place and time.

[PeerHerholz]

Hi @CPernet,

the Brainhack is happening here until Saturday. So there would be one day without overlap.

Best, Peer

[PeerHerholz]

Hi @bids-standard/maintainers,

after talking with @effigies during the Brainhack, I wanted to ask if it be possible to have a somewhat formal review/assessment of the current state of the GoogleDoc draft, so that we can then hopefully move things over to GitHub?

It would be cool to hear from you.
Thanks.

Best, Peer

[PeerHerholz]

Hi everyone,

here's a quick summary based on the meeting with the @bids-standard/maintainers:

• overall, the BEP seems to be in a good shape
• we can start moving from the GoogleDoc to GitHub, following the BEP development process
• we will start with:
  • creating different examples
  • draft rules for the validator/schema
• after that, we will start updating the spec respectively

[PeerHerholz]

Hi @bids-standard/maintainers (especially @rwblair),

concerning the rules for the validator/schema: how would you like to discuss those?
Should we propose something here, in the schema repository or elsewhere?

Best, Peer

[effigies]

I would either discuss here or in the validator, mostly depending on whose eyes you want on it. The actual checks will go in https://github.com/bids-standard/bids-specification/tree/master/src/schema, with some accommodation in the validator. If you want broader feedback on what the rules should be, the spec seems the more appropriate place. If you want targeted feedback on how to write rules, the validator will get a narrower audience.

[rwblair]

@PeerHerholz I'll open a PR against the specification, I had started implementing some of the changes needed during our call the other day.
#1902 - an incomplete starting point for the schema changes. Long todo, sprinkled with questions I couldn't answer myself.

[PeerHerholz]

Thanks @rwblair, I'll have a look at it asap!