- Name: Kambham Deepthi Reddy
- Organisation: INCF
- Project: Development of JupyterLab Widgets for TVB
- Mentors: Lia Domide, Teodora Misan, Paula Popa
The Virtual Brain (TVB) provides an open-source simulation framework for whole-brain network modeling. Unlike the traditional approach of modeling neurons at the micro-scale level, TVB takes into account brain regions and their interactivity. This project aims to enhance The Virtual Brain (TVB) ecosystem by developing additional JupyterLab widgets that improve the exploration and analysis of brain connectivity data. By providing rich visualizations and dynamic interfaces, the project will help users better understand connectivity patterns across brain regions. It aligns strongly with TVB’s mission to make large-scale brain network modeling more accessible, interactive, and insightful, ultimately supporting researchers and clinicians in gaining a deeper understanding of brain function and neurological disorders.
-
Develop a new set of graphical JupyterLab widgets within the
tvb-widgetsecosystem. -
Enable interactive exploration of TVB brain connectivity data, including connectivity matrices, nodes, and edges.
-
Improve the usability and performance of existing widget functionality by exploring better visualization approaches, improved interfaces, and more efficient implementations.
-
Provide JupyterLab notebooks demonstrating the developed widgets.
-
Explore integration of the developed widgets with the
tvb-ext-xircuitsJupyterLab extension.
A new BCT Metrics Projection Widget was developed to compute and visualize Brain Connectivity Toolbox (BCT) metrics on TVB Connectivity data directly within JupyterLab. The widget supports both connectivity weights and tract-length matrices, provides analyzer selection, and integrates matrix editing before running an analysis.
The widget also validates the input connectivity and presents the analysis results using suitable visualizations, including metric cards, 3D head views, histograms, bar charts, and heatmaps depending on the type of result returned.
Connectivity and Matrix Selection
The widget supports both connectivity weights and tract-length matrices, allowing the appropriate matrix to be selected based on the analysis being performed.
Connectivity Matrix Editing
An interactive connectivity matrix editor is integrated into the workflow, allowing users to review and modify connectivity values before running an analyzer.
Analyzer Grouping and Selection
Available BCT analyzers are organized into groups, allowing users to select the required analysis and view its description before execution.
Input Validation
The widget validates connectivity matrices for conditions such as self-loops, negative weights, and directed/undirected compatibility before executing an analyzer.
BCT Metric Execution
Selected BCT metrics are executed directly on the TVB Connectivity datatype, with the widget handling the returned results and displaying the analysis status.
Result Classification
Analysis outputs are automatically classified as scalars, per-node values, network vectors, matrices, or tensors so that an appropriate visualization can be selected for each result type.
3D Head Visualization
Per-node metric results can be projected onto a 3D connectivity head, allowing users to visually identify how metric values vary across brain regions.
Histogram Visualization
Node-level results are also presented as interactive histograms, with brain regions sorted according to their metric values for easier comparison.
Network Vector and Matrix Visualization
Network vectors are displayed using interactive bar charts, while matrix-based results are represented using interactive heatmaps with brain-region labels.
A Unified Head Widget was developed to combine multiple TVB visualization and connectivity interaction components into a single interface. It integrates a 3D head view, space-time visualization, and connectivity matrix editing, allowing users to explore and modify brain connectivity data within one workflow.
Integrated Head and Space-Time Views
The widget provides separate Head View and Space Time tabs within the same interface. The space-time visualization is automatically rebuilt when connectivity data is edited.
Node Selection and Edge Highlighting
Users can select individual brain regions and highlight their incoming or outgoing connections directly on the 3D head visualization, making connectivity relationships easier to explore.
Interactive Connectivity Matrix Editing
The widget integrates the existing ConnectivityMatrixEditor, allowing users to inspect and modify connectivity matrices directly within the unified interface.
Edge Operations
Users can perform operations such as Set, Add, Subtract, Multiply, and Divide on selected groups of edges. Operations can be applied to different combinations of incoming and outgoing node groups.
Custom Node Selections
Users can select brain regions through checkboxes, create custom named selections, and reuse those selections for further connectivity operations.
Reset Functionality
A reset option restores the original connectivity values and clears node selections and visual modifications, allowing users to return to the initial state.
The existing Connectivity React Widget was reworked to address rendering and performance issues caused by handling thousands of connectivity edges as individual SVG elements. The rendering architecture was redesigned using a hybrid Canvas + SVG approach, where Canvas handles large-scale edge rendering while SVG manages the interactive brain-region labels.
Hybrid Canvas + SVG Rendering
Connectivity edges are rendered on a single Canvas instead of creating thousands of individual SVG paths, while SVG is retained for the interactive region labels. This reduces DOM overhead while preserving node-level interactivity.
Fixed Edge Duplication
The existing edge collection logic was corrected to prevent the same connectivity edge from being collected multiple times, reducing unnecessary edge rendering and improving performance.
Optimized Hover Interaction
The previous approach required updates across thousands of DOM elements during interaction. This was replaced with React state and Canvas redraws, allowing incoming and outgoing connections to be highlighted more efficiently.
Optimized Weight/Tract Switching
Instead of destroying and rebuilding the complete visualization when switching between weights and tract lengths, the layout calculation is cached and only the edge layer is redrawn. This avoids unnecessary layout calculations and DOM reconstruction.
Tract-Length Range Filtering
A range-based filter was introduced for tract lengths, allowing users to specify minimum and maximum tract-length values and display only the connections within the selected range.
Interactive Connection Highlighting
Selecting a node highlights its outgoing and incoming connections separately, making the directionality of the connectivity network easier to understand.
JupyterLab notebooks were provided for each of the developed widgets, demonstrating their implementation and functionality within the TVB environment. These notebooks accompany the widgets and provide examples of their usage with the corresponding TVB data.
- BCT Metrics Projection Widget PR(the-virtual-brain/tvb-widgets#103)
- Connectivity React Widget PR(the-virtual-brain/tvb-widgets#101)
- Unified Widget PR(the-virtual-brain/tvb-widgets#106)
A potential future direction is to integrate the developed TVB widgets with the tvb-ext-xircuits JupyterLab extension.
My GSoC experience with The Virtual Brain was a valuable opportunity to work on a real-world open-source project and understand how software development works in a collaborative environment. During the project, I gained hands-on experience with Python, JupyterLab, IPyWidgets, React, visualization libraries, and the TVB codebase. I learned how to understand an unfamiliar codebase, investigate existing implementations, identify performance issues, and design practical solutions. Working closely with my mentors helped me improve not only technically but also in communicating ideas, receiving feedback, and iterating on my work. I also became more comfortable with Git, GitHub, pull requests, code reviews, and contributing to an open-source community. One of the most valuable parts of the experience was seeing my ideas evolve through multiple iterations based on mentor and user feedback. Overall, GSoC gave me the confidence to work independently on complex problems while also understanding the importance of collaboration and continuous learning. I truly enjoyed the experience and hope to continue contributing to TVB and the open-source community beyond GSoC.
Thank you for your great work @deeptive !