braph-software / braph-2

BRAPH 2.0 is a comprehensive software package for the analysis and visualization of brain connectivity data, offering flexible customization, rich visualization capabilities, and a platform for collaboration in neuroscience research.

BRAPH 2.0 — Multimodal and AI-powered Brain Connectivity Analysis

BRAPH 2.0 is an open-source MATLAB-based software that provides advanced capabilities for brain connectivity analysis. It offers a comprehensive range of features, including conventional graph theory, multilayer graphs, and deep learning techniques. With its user-friendly interface and extensive analysis pipelines, researchers can explore the complex organization of the human brain using multimodal neuroimaging data, going beyond the limitations of traditional approaches.

Advances in brain connectivity analysis. Brain connectivity analysis is rapidly evolving thanks to the widespread availability of increasing computational power and large-scale, high-resolution, multimodal neuroimaging datasets. BRAPH 2.0 provides a complete set of tools to analyze these data with conventional graph theory (single-layer graphs), multiplex and multilayer graphs, and deep learning (from dense neural networks to graph convolutional neural networks), as well as a flexible, easily expandable software architecture. BRAPH 2.0 uses parallel computing to allow users to run scripts on servers or clusters with both central processing units (CPUs) and graphical processing units (GPUs).

Welcome to BRAPH 2.0

BRAPH 2.0 is designed to facilitate the analysis of brain connectivity using various neuroimaging modalities and cutting-edge techniques. It enables researchers to assess brain organization with multimodal data and advanced tools such as deep learning. BRAPH 2.0 provides an extensive set of analysis pipelines accessible through a graphical user interface (GUI) and sample scripts, allowing users to perform ready-to-use analyses or develop customized pipelines for their specific needs.

Installation

To install BRAPH 2.0, follow these steps:

1. Ensure that you have MATLAB R2022a or a later version installed on your system. BRAPH 2.0 is compatible with the versions of MATLAB for Microsoft Windows, macOS, and Linux operating systems.

2. Make sure you have the following toolboxes installed in MATLAB:

   • Statistics and Machine Learning Toolbox (required)
   • Parallel Computing Toolbox (optional)
   • Deep Learning Toolbox (optional, for deep learning analysis)

3. Download the latest stable version of BRAPH 2.0 from BRAPH 2.0 Releases.

4. Unzip the downloaded file into the desired directory on your system.

5. Launch MATLAB.

6. Navigate to the braph2 folder located in the directory where you unzipped BRAPH 2.0.

7. Run the script braph2. This will launch the graphical user interface (GUI) from which you can choose an analysis pipeline.

8. Explore the BRAPH 2.0 Tutorials.

Compatibility with MatLab Releases and Operative Systems

A ✓ indicates that we have unit-tested the current release BRAPH 2.0 on the indicated Matlab release and operative system.

Matlab Version	Mac	Win	Linux
R2022a	?	?	?
R2022b	?	?	?
R2023a	?	?	?
R2023b	?	?	?

Use Cases & Analysis Pipelines

BRAPH 2.0 provides a wide range of analysis pipelines that can be used for various use cases in brain connectivity analysis. For detailed information about these analysis pipelines, including their functionalities and step-by-step instructions, refer to the BRAPH 2.0 Pipeline Tutorials. Here are some possible use cases of BRAPH 2.0:

1. Conventional Single-Layer Analyses: BRAPH 2.0 offers pipelines to analyze single-layer graphs derived from different kinds of neuroimaging data. These pipelines involve loading the brain atlas, loading the subject data, constructing the graph, calculating graph measures of interest, and comparing groups. Single-layer analyses can be performed on connectivity data, functional data, and structural data.

2. Multilayer Analyses: BRAPH 2.0 supports the analysis of multilayer graphs, which capture the connectivity patterns across multiple layers or modalities. The multilayer analysis pipelines involve similar steps as single-layer analyses but operate on multilayer graphs. This allows researchers to explore the relationships between different layers or modalities of brain connectivity.

3. Deep Learning Analyses: BRAPH 2.0 enables the analysis of brain connectivity data using deep learning techniques. The deep learning pipelines involve loading the brain atlas, loading the subject data, constructing the input for deep learning models, splitting the dataset, training the models, and evaluating the model performance. Deep learning analyses can be applied to connectivity data, functional data, and structural data and graphs.

For Developers

BRAPH 2.0 is designed to be an open community-driven project, and the code is freely available on this GitHub repository at BRAPH 2.0 Releases. Developers can contribute to BRAPH 2.0 at various levels of complexity, ranging from editing existing pipelines and adapting example scripts to implementing entirely new features. For the details on how to do this, refer to the BRAPH 2.0 Developer Tutorials.

Contribute to BRAPH 2.0

BRAPH 2.0 is an open-source project, and contributions from the community are highly encouraged. Whether you want to report a bug, suggest a new feature, or contribute code improvements, your contributions are valuable and help make BRAPH 2.0 even better.

Bug Reports and Feature Requests

If you encounter any issues or have ideas for new features, please submit detailed information for bug reports using the Bug Report template and clear descriptions for feature requests using the Feature Request template. Your contributions help us improve BRAPH 2.0 and make it even better.

Code Contributions

If you're interested in contributing with code, follow these steps:

1. Fork the BRAPH 2.0 repository on GitHub.

2. Create a new branch for your changes.

3. Make your modifications and commit them.

4. Push your branch to your forked repository.

5. Open a pull request against the develop branch of the main repository.

The core team of BRAPH 2.0 developers will then revise this proposal and possibly merge it or come back to you with questions and comments.

Documentation Contributions

Improvements to the documentation are welcome. Submit a pull request as indicated above with your proposed changes for errors, outdated information, or suggestions for improvement.

Community Support

Join discussions on the BRAPH 2.0 Discussion Forum to provide support, answer questions, and share your expertise.

By contributing to BRAPH 2.0, you play a crucial role in its growth and improvement. Your contributions shape the future development of the software and advance brain connectivity analysis.

We appreciate your support and look forward to your contributions!

Cite BRAPH 2.0

If you use BRAPH 2.0 in your research work, please cite the following publication:

Mite Mijalkov, Ehsan Kakaei, Joana B Pereira, Eric Westman & Giovanni Volpe (2017).
BRAPH: A graph theory software for the analysis of brain connectivity.
PLOS ONE 12, e0178798.
https://doi.org/10.1371/journal.pone.0178798

We appreciate your acknowledgment of BRAPH 2.0 in your research!

braph-2's Issues

Add .getCompatibleMeasureList() to children of Graph

Test Degrees and Strengths

Write test scripts:

• Degree
• DegreeAv
• InDegree
• InDegreeAv
• OutDegree
• OutDegreeAv
• Strength
• StrengthAv
• InStrength
• InStrengthAv
• OutStrength
• OutStrengthAv

Doc subclasses.m

Calculate Global efficiency

Based on the distance matrix, calculate the global efficiency of the nodes (for BD and WD graphs, In and Out Global efficiencies).

Calculate Betweeness centrality

Calculate the Betweeness centrality of a node.

The code in Braph 1 currently uses Kintali algorithm (same as BCT). Try to check if there is something else available, if not, the same algorithm can be implemented.

test_symmetrize

test that a matrix get symmetric, also with each of the rules

Update remove_diagonal with varargin

Update remove_diagonal so that it works with varargin, e.g., remove_diagonal(A, 'RemoveDiagonalValue', value)

• update code
• update doc

Calculate Degree Assortativity coefficient

Implement the degree assortativity coefficient.

Code DegreeAv, InDegreeAv, OutDegreeAv

These are the global measures,
see http://braph.org/manual/graph-measures/

Clustering coefficient BU graph

Calculate clustering coefficient for Binary Undirected graphs.

Distance measured in edges

• Measure corresponding to matrix B in the distance for W matrices

• test function

• check if revision of Distance is needed

Test Graph.subgraph()

Calculate Path length - Global

Calculate the path length of a graph (BU, WU graphs). Calculate the In and Out - path length of the graph in the case of BD and WD graphs.

The path length is simply the average of the nodal path lengths for all nodes in the graph. The average can be performed in three ways:

1. Simple average
2. within connected subgraphs
3. Harmonic mean

Once these are implemented, we can discuss about additional ways to perform the averaging procedure. Also, if a graph is disconnected, path length calculated as 1) returns NaN. Based on what we need, we can have additional ways to deal with it (return 0, output warning, etc..).

Create classes GraphBD and GraphBU

Comment Measure.m

Code Strength, InStrength, OutStrength

Check here for definitions:
http://braph.org/manual/graph-measures/

test_Triangles with all rules

@mitemijalkov @annacanal

Triangles should be tested for all rules in the directed graphs.

Calculate radius and diameter of a graph

Calculate the radius and diameter of a graph. These measures are very closely related to eccentricity.

Bug with the creation of BU/BD graphs

I was not sure where to submit this so I submit this bug as an issue.

When the BU/BD graphs are created, the matrix A associated with the graph is turned into logical matrix (accessed by the getA() method). This creates a problem with the performance of matrix multiplication in the measures (gives the following error: Error using *
Both logical arguments must be scalar. Use TIMES (.*) for elementwise multiplication.)
I double checked, and I think the problem is in the implementation of the function binarize.

What do you think? Should this be changed?

Test Measure.copy()

Deep copy

Calculate Local efficiency

After implementing the Global efficiency measure, implement local efficiency (which is defined as the global efficiency on the subgraph of node neighbors - nodal measure).

This needs to implemented with care, because the current algorithm in Braph is a bit slow, making the local efficiency generally a limiting factor for these calculations.

Implement also the In and Out Local efficiency (nodal measures).

Implement the global counterparts of these 3 measures.

test_remove_negative_weights

Test Graph.copy()

Write test code for Graph.copy()
It should check that it does a deep copy of the graph, including all measures and references to the graph in the measures.

Community Structure of a Graph

Calculate a community structure of a graph. Also write the corresponding test function.

For the calculation, two parameters need to be passed: algorithm that will be used in calculation (Louvain and Newman) and gamma parameters (that defines the resolution of the community).

Issues to decide:

1. How the community will be implemented for a graph. It is not nodal or global measure in the traditional sense, but the output is indeed a number for each node (number of community to which it participates).
2. Whether to use the optimization procedure described in other toolboxes. The procedure entails calculating the community structure few times (typically 10 or 100) and use the structure that produces maximum modularity.

Graph.subgraph(), nodeattack(), edgeattack() not working

Normalization

• add function normalize(A, 'NormalizeRule', RULE) to graph
  RULE can be 'rescale' (A/max(A)) or 'one'|1 (A<0 = 0 and A>1 = 1).

• Comment function

• Check this i the constructors of GraphWD (and therefore WU)

• Explain this in the getDescription() of GraphWD and GraphWU

• create test_normalize

Add .getCompatibleGraphNumber() to children of Measure

Add list of measures

Mite, please:

• check and add all measures (as separated) issues from
  https://sites.google.com/site/bctnet/measures/list
  Start with those already implemented in the Braph 1.0

• check that all measure can be either nodal (vector) or global (scalar) -- maybe we need to introduce new kinds of datatypes, in which case we need to discuss

Restructure settings + deep copy

Restructure settings in Graph and Measure, and make deep copy

Calculate Transitivity

Calculate Transitivity for a graph.

Transitivity can be calculated for BD, BU, WD and WU graphs. It is a global measure.

Write the associated test functions.

Code StrengthAv, InStrengthAv, OutStrenghtAv

These are the global measures,
see
http://braph.org/manual/graph-measures/

distance

• Add distance() to Graph as abstract method

Implement it in all kinds of graphs:

• GraphBU

• GraphBD

• GraphWU

• GraphWD

• add concrete method to Graph getDistance()

• add test

Calculate Path Length

Using the distance function, calculate path length of each node.

Path length can be calculated for BU and WU graph. For BD and WD graphs, calculate In and Out - path length for all nodes.

For binary graphs, path length is based on the number of edges needing to reach one node starting from the other. For weighted graphs, the calculation is based on the weights of the edges (Dijkstra's algorithm). Since we have distance based on the number of edges, maybe this variant can be implemented for weighted graphs also.

Code Degree, InDegree, OutDegree

Code Degree as child of Measure for BU and WU (same obj.)

Code InDegree and OutDegree as child of Measure for BD and WD (two obj.)

Restructure auxiliary functions Graph

• remove_diagonal -> dediagonalize

• remove_negative_weights -> semipositivize

create/check test functions:

• test_dediagonalize

• test_symmetrize

• test_semipositivize

Test Graph + children

Write test scripts:

• test_Graph
• test_GraphBD
• test_GraphBU
• test_GraphWD
• test_GraphWU

Bug deep copy of Measure

missing Measure.copyElement()

Graph is_measure_calculated(g, measure_class) not working

Measure constructor is ussing a deleted function is_compatible_with_graph(m,g)

Cant create new derived class from Measures.

Test Graph.nodeattack() & Graph.edgeattack()

Add to test_Graph the tests for:

• Graph.nodeattack()
• Graph.edgeattack()

Implement Measure.tostring() and Measure.disp()

Implement

• Measure.tostring()
• Measure.disp()

Implement remove_negative_weights()

The possible rules are

• 'zero', '0', 'null' (default)
• 'abs', 'absolute', 'modulus'

Calculate Global Efficiency - Global

Calculate the global efficiency of the network, by averaging the nodal global efficiencies of each nodes.

Test Triangles

Write test_triangles

We are using this:
https://www.mathworks.com/help/matlab/script-based-unit-tests.html

Calculate Eccentricity and related measures

Calculate the eccentricity of each node. Calculate the eccentricity of the graph.

Distance as a Measure

Rewrite Distance as a Measure class.

• Add Distance

• add Distance test

Add .getCompatibleGraphNumber() to children of Graph

Comments for remove_diagonal, remove_negative_weights, symmetrize

Add comments for remove_diagonal, remove_negative_weights, symmetrize

Follow style from Braph 1.0

Bugs: InDegree and OutDegree

Add .getName() and .getDescription() to InDegree and OutDegree

Triangle BU

Implement TriangleBU