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 :)