A graphical user interface for exploring and sharing a database of optogenetically-induced vascular responses in mouse somatosensory cortex in vivo measured by 2-photon microscopy is presented. It allows browsing the data, criteria-based selection, averaging, localization of measurements within a 3D volume of vasculature and exporting the data.
The importance of sharing experimental data in neuroscience grows with the amount and complexity of data acquired and various techniques used to obtain and process these data. However, the majority of experimental data, especially from individual studies of regular-sized laboratories never reach wider research community. A graphical user interface (GUI) engine called Neurovascular Network Explorer 2.0 (NNE 2.0) has been created as a tool for simple and low-cost sharing and exploring of vascular imaging data. NNE 2.0 interacts with a database containing optogenetically-evoked dilation/constriction time-courses of individual vessels measured in mice somatosensory cortex in vivo by 2-photon microscopy. NNE 2.0 enables selection and display of the time-courses based on different criteria (subject, branching order, cortical depth, vessel diameter, arteriolar tree) as well as simple mathematical manipulation (e.g. averaging, peak-normalization) and data export. It supports visualization of the vascular network in 3D and enables localization of the individual functional vessel diameter measurements within vascular trees.
NNE 2.0, its source code, and the corresponding database are freely downloadable from UCSD Neurovascular Imaging Laboratory website1. The source code can be utilized by the users to explore the associated database or as a template for databasing and sharing their own experimental results provided the appropriate format.
The brain is considered one of the most intricate organs and the desire to untangle its complex function is unflagging. It is being studied at different scales from the molecular to the behavioral level using a wide palette of tools2,3,4,5,6,7,8. The amount of non-homogeneous experimental data grows with unprecedented speed. The awareness of the need for experimental data sharing, organization and standardization grows with the amount of acquired data. It has become evident that neuroinformatics will play a critical role in integrating experimental data across scales into models of brain function and dysfunction9,10.
To this end some studies, especially larger-scale studies, were able to earmark resources to make their results available via extensive databases11,12,13,14,15. However, a vast amount of experimental data from individual studies and regular-sized laboratories never reached the wider research community. This is mainly for two reasons: first, more dedicated time is needed to build a database and create tools that would enable the user to interact with the database; and second, more money is needed to support these tasks. Motivated by these challenges, a MATLAB based graphical user interface (GUI) engine called the Neurovascular Network Explorer 2.0 (NNE 2.0)16 was developed as a simple and low-cost tool for databasing, sharing and exploring of vascular imaging data. This manuscript provides a manual for operation of NNE 2.0 and the associated database of experimental data.
NNE 2.0 is already a second-generation software engine. The first generation, called Neurovascular Network Explorer 1.0 (NNE 1.0)17 was built to interact with a database of sensory-evoked vasodilation in rat primary somatosensory cortex (SI) in vivo measured by 2-photon microscopy18. NNE 1.0, its source code as well as the associated database are freely downloadable as a zipped file called ‘NNE 1 Tian’ from UCSD Neurovascular Imaging Laboratory website1. More information about NNE 1.0 and the associated database can be found in17.
The second generation, the NNE 2.0, interacts with a database of optogenetically-evoked dilation of individual vessels in mice SI in vivo measured by 2-photon microscopy20. The user can browse, select and visualize data based on selection categories such as cortical depth, branching order, vessel diameter, animal subject or a particular arteriolar tree. The GUI further performs simple mathematical operations such as averaging and peak-normalization in selected categories. NNE 2.0 enables to view and browse through images capturing 3D volumes of vasculature as well as identify the location of the functional measurement within the vascular trees. This feature can be used to reconstruct vascular morphologies in 3D and populate them with real single-vessel vaso-motion measurements. These reconstructions can in turn be incorporated into computational models of brain function21,22. NNE 2.0, its source code and the associated database are freely downloadable as a zipped file called ‘NNE 2.0 HDbase v1.0’ from UCSD Neurovascular Imaging Laboratory website1.
NNE 2.0 works with a database called 'vdb.mat'. This database is a matrix containing temporal profiles (time-courses) of single vessel diameter changes evoked by an optogenetic stimulus and measured at different locations of arteriolar trees. Each time-course was computed using custom-written software. It calculates the relative change of a vessel diameter from expansion of a fluorescent intensity profile acquired by scanning across the vessel. The fluorescent contrast was presented by intravascular injection of fluorescein isothiocyanate (FITC)-labeled dextran. For more information about the data and analysis procedures, please see20,23. The database has 305 time-courses (i.e. database entries) in total. In addition to the diameter change, each entry to the database holds an array of additional metadata which (1) quantify the time-course (2) describe the measured vessel and (3) identify the measurement location within a 3D volume of cortical vasculature. The metadata include the onset time, peak amplitude, peak amplitude time, cortical depth, branching order, vessel diameter at baseline, path to original reference images and 3D image stacks for each measurement and low-magnification maps of brain surface vasculature. Please see all parameters in the metadata listed and described in detail previously in Table 116.
NNE 2.0 interacts with reference images that are X-Y scans of a plane where the diameter measurement occurred. Each database entry has one corresponding reference image with a reference name displayed in the GUI. Each database entry also has an associated stack of images (3D stack) capturing a 3D volume of the vascular tree within which the measurement occurred. The GUI enables to choose a particular database entry and display the corresponding reference image as well as the 3D stack. It also guides the user to find the matching reference image and frame in the 3D stack (the same features can be found in both images). All stack and reference images in their full resolution (1024 pix x 1024 pix) are included in folders hana_stk and hana_refs, respectively. Low-magnification maps of brain vasculature are included in folder 'maps'. All three folders as well as the database matrix ‘vdb.mat’ are downloaded in the zipped file ‘NNE 2.0 HDbase v1.0’ from the UCSD Neurovascular Imaging Laboratory website1 and saved to the root folder of NNE 2.0 during the installation process.
The GUI has been designed as a set of four panels (Panel 1 (Main Panel) – Panel 4) which open sequentially as the user explores the database and selects specific data based on selection categories. Each panel is divided into two main parts: (1) the right column provides the possibility to interact with the database by selecting parameters and categories of the data and displays important information from the metadata; (2) the left column displays the data in the form of time-courses (diameter change in time) and scatter-plots. There are four types of scatter plots displaying (1) dilation onset time (2) time of the dilation peak (3) maximum diameter change (peak amplitude) and (4) baseline diameter (diameter before stimulation) as function of cortical depth. The user has the possibility to display average time-courses and values for selected data grouped either by cortical depth or branching order. This is to highlight the feature of gradient diameter-change behavior with increasing depth and branching order20. NNE 2.0 allows the user to export the selected subset of data in the format of '.xls', '.csv' or '.mat'.
1. Installation of NNE 2.0
2. Running NNE 2.0
NNE 2.0 and the associate database serve to browse and view the data of the database, sort out the data based on selection criteria, download the selected data, and find the vascular measurements within the corresponding vascular tree.
Panel 1 features selection of data based on categories: 'Cortical Depth', 'Branching Order', 'Baseline Diameter' and 'Subjects' – Figure 1). Please note that in this study, there are no entries for surface arterioles ('Surface') in the 'Branching Order' selection category. If this option is selected, a warning dialog 'No records found – Search too restrictive' appears and prompts the user to select a different option. The same warning will appear if there are no measurements satisfying the selected criteria in Panel 1. In this case the user should close Panel 1 by pressing [x] and restart the program.
All diameter change time-courses fulfilling criteria chosen in Panel 1 can be viewed in Panel 2 (Figure 2). The user can explore all individual time-courses, time-courses group-averaged by cortical depth or branching order and the corresponding values of 'Onset time', 'Peak amplitude', 'Time-to-peak' and 'Baseline diameter' plotted as functions of depth. The user selects one time-course from the individual time-courses graph and explores the shape of the curve as well as the corresponding numerical characteristics in the scatter plots.
All data acquired in the same animal or arteriolar tree can be explored in Panel 3 (Figure 3). In the same manner as in Panel 2, the user selects one time-course from the individual time-courses graph and explores the shape of the curve as well as the corresponding numerical characteristics in the scatter plots. If desired, the user can export all the data from Panel 3 in the format of '.xls', 'csv' and '.mat'. These files are created or overwritten each time the 'Export' action is taken. Before overwriting the files, a warning dialog 'About to overwrite vdb_subset.xls' pops out prompting the user to rename previously exported results. The user should make sure none of the exported files are open during the 'Export' action. If one of the files is open, a warning dialog 'Error exporting Excel file: make sure vdb_subset.xls is not open' will appear. In this case, the user should close the exported file and restart NNE 2.0.
All data acquired within a single arteriolar tree can be explored in the context of 3D vasculature in Panel 4 (Figure 4). Selecting a time-course will automatically display the associated reference image and the 3D image stack which are loaded from folders 'hana_refs' and 'hana_stk', respectively. The measured vessel is highlighted in its reference image with a red semi-transparent rectangle in the middle of the image. The scanning path is marked as a red line crossing the measured vessel. If more vessels are scanned within one measurement (red line crossing multiple vessels – Figure 4), the user needs to take into account the branching order found in 'vdb.mat' or displayed in the GUI on top of the time-courses graph ('B. Order') to understand which scan belongs to the particular measurement. Branching order '0' labels diving trunks, '1' labels branches connected directly to diving trunks, '2' labels branches directly connected to 1st order branches, etc. To identify the appropriate arteriolar tree starting with a diving arteriole at the surface of the brain (seen in the top images of the 3D stack), the user should refer to a low-magnification map saved in the folder 'maps'. This map is unique for each animal subject and can be located using the corresponding subject ID (e.g. '022014.jpg'). This map is an image of the whole brain exposure with surface vasculature. The diving segments of measured arterioles are labeled with the tree identifiers ('Tree ID') (Figure 5). The user can export a single selected time-course along with the information about the corresponding reference image, 3D stack and position of the measurement within the stack into 'ref_stacks_trace.xls'. Similarly, as for 'Export' in Panel 3, 'ref_stacks_trace.xls' should be closed before the 'Export' action is taken. The same type of warning dialogs will appear before overwriting the exported file or when the file is open during the 'Export' action. Please note that if there is a missing reference image for the selected database entry (9 entries in total), a warning 'NO REFERENCE IMAGE FOUND: index = ' will be displayed instead of the reference image in Panel 4. No export is available for those entries and the user is prompted to choose a different time-course. If the user selects an entry for which the 3D stack does not exist or no reference image/stack frame was found (31 and 52 entries, respectively) a note *NO STACK MATCH* will be displayed on top of a blank image in the place of the 3D stack image in Panel 4.
Figure 1: Panel 1 (Main Panel) serves to select a subset of data based on selection categories. All data from 'vdb.mat' are displayed in six graphs in the left column. The right column allows the user to select a subset of this data by choosing Cortical Depth | Branching Order | Baseline Diameter | Subjects. Please click here to view a larger version of this figure.
Figure 2: Panel 2 allows examining the selected subset of data and further refining the selection. Right column offers to calculate average of the selected data based on depth categories or branching order (the actual choice is highlighted in green). Left column displays data fulfilling the criteria selection in Panel 1 and the average type selected in the right column. The user can select a time-course in the top left graph (cross cursor) which gets highlighted (magenta). The corresponding times of onset and peak, the peak amplitude and baseline diameter are circled in red and the entry identifiers are displayed in the right column at the bottom. Thick red points in the scatter plots mark the average values for the actual data subset. The selection of 'all data for tree' vs. 'all data for Subj' affects data in the following panels. Please click here to view a larger version of this figure.
Figure 3: Panel 3 allows exploring the final subset of data and exporting them. The user can select (cross cursor) a time-course in the graph on top of the left column. The selected trace gets highlighted (magenta) and the entry metadata is displayed on top of the graph. Simultaneously the corresponding onset and peak times as well as the peak amplitude and baseline diameters are displayed in the graphs below. The EXPORT SET button in the right column allows exporting all the time-courses from the top graph. The average time-course is plotted in thick black. Please click here to view a larger version of this figure.
Figure 4: Panel 4 allows localizing the diameter measurements within a reference image and within a 3D stack of vasculature. The time-courses plot on top of the left column is identical with the time-courses plot in Panel 3. The user can select individual time-courses from the top graph in the left column. The corresponding reference image is displayed at the bottom right along with the metadata information: 'Ref. Image' (reference image name), 'Depth' (cortical depth of the measurement) and 'Scale' (scale of the image in microns per pixel). The corresponding 3D stack is displayed at the bottom left along with the descriptive metadata information: 'Stack index' (actual image number in the stack), 'Delta' (vertical distance from the top image), 'Ref' (image number in the stack which corresponds to the reference image and captures the measurement location) and 'Scale' (scale of the image in microns per pixel). Please note that the 'Depth' on top of the reference image was entered manually during the experiment and is approximate. It does not match exactly the value of 'Delta' of the frame level in stack images due to the fact that the brain surface is tilted with regards to the imaging plane. Please click here to view a larger version of this figure.
Figure 5: Low-magnification map of the surface vasculature. The image captures the exposed brain region with surface vessels. The diving segments of measured arteriolar trees are labeled with the tree identifiers ('Tree ID'). These maps are saved in the folder 'maps' in the folder where NNE 2.0 is running from. Please click here to view a larger version of this figure.
NNE 2.0 was written in order to share the vascular imaging data of a specific study20 but with the intention of developing a simple tool for sharing and exploring data of similar kind by other users. Researchers interested in inspecting the associated database of vascular data may use the GUI to browse the data, select subsets of data, compare them to their own experimental results or process them further using their own computational procedures. Users familiar with MATLAB can utilize directly the database 'vdb.mat' while users employing a different type of programming language can export the data in one of the alternative formats ('.xls' or '.csv').
Researchers who are interested in sharing their own experimental data using NNE 2.0 need to structure the results into a matrix similarly to 'vdb.mat'. Principal entries to this database should be time-courses of any kind in the form of vectors and the corresponding time vectors. Parameters of the database can be modified or added to via modular structure of the GUI. All reference images, image stacks and brain exposure maps (if applicable) should be collected and deposited along with the database and the executable GUI on the internet (e.g. laboratory webpage or a third-party repository).
Researchers interested in using the vascular measurements along with the 3D vascular morphology in modelling studies of brain function can first explore the data using the GUI. After selecting a desired subset of data, they can use the metadata information exported to 'ref_stacks_trace.xls' along with variables in 'vdb.mat', 3D stack images saved in 'hana_stk' and brain exposure maps in 'maps' to reconstruct the vascular morphology in 3D.
The most critical step of the protocol is exporting the data. For correct export of selected data (from Panel 3 and 4) it is important to close all files into which the data should be exported to before the ‘Export’ action is taken. Only then the files will be correctly overwritten with the actual choice of data. Any modifications to the program or troubleshooting need to be performed to the source code.
NNE 2.0 has been developed to share temporal profiles computed from line-scans which were acquired by 2-photon microscopy. Data explored by NNE 2.0 are therefore not raw intensity scans but rather pre-processed time-courses of relative diameter changes. In this way the users are able to process their raw experimental data using their own standard procedures and software and use NNE 2.0 as a template to present and share their results with other researchers. Not only vascular diameter changes but basically any time-dependent signal measured using different measurement techniques can be shared this way. Such signals include fluorescence of calcium24, sodium25, voltage sensitive dyes26, genetically encoded indicators for metabolites27, partial pressure of oxygen (pO2)28, blood oxygenation (BOLD18, spectral imaging29), blood flow (speckle imaging29) or electrophysiology signals30. The prerequisite for using NNE 2.0 is a database in the format of a matrix '*.mat'. This could be achieved either by processing the data directly in MATLAB or using tools to build the matrix from other formats (e.g. 'xlsread(filename)' serves to read excel spread sheets into '.mat' formats). The use of NNE 2.0 without MATLAB is limited to exploring, downloading and further processing of data from the current database 'vdb.mat'.
NNE 2.0 has the potential to help spreading experimental data across the wide neuroscience research community to be explored and compared to other experimental data of similar kind facilitating the development of standards for data acquisition and processing31. NNE 2.0 can also help spreading the data across the neuroinformatics community where it can be used in models of non-invasive imaging signals such as functional magnetic resonance imaging (fMRI)21. While NNE 2.0 cannot compete with more complex databases5,32,33,34, it can provide a seamless and ready-to-use platform for databasing and sharing experimental data without the need of additional extensive investments.
The authors have nothing to disclose.
We gratefully acknowledge support from the NIH (NS057198, EB00790, MH111359, and S10RR029050) and the Ministry of Education, Youth and Sports of the Czech Republic (CEITEC 2020, LQ1601). KK was supported by postdoctoral fellowships from the International Headache Society in 2014 and The Scientific and Technological Research Council of Turkey in 2015. MT was supported by postdoctoral fellowship from the German Research Foundation (DFG TH 2031/1).