GUIMRICohort is a graphical user interface that allows the user to create an MRI cohort by adding individual subjects or by importing groups of subjects from data files in xls, txt, or xlm format. The user can also edit the data and anagraphic details of the subjects, as well as create groups of subjects. Furthermore, GUIMRICohort provides numerous options to visualize the data relative to individual subjects, groups, and comparisons between groups. The MRI cohort can be saved in a file *.mc for future use within BRAPH; it also can be exported in xml format for use within other programs.
The layout of GUIMRICohort is shown in figure 1. It is composed of five main work areas:
- Menu permits one to access the basic functionalities of GUIMRICohort, including loading, saving, editing, and visualizing an MRI cohort, as well as creating a new MRI graph analysis.
- Toolbar gives direct access to some of the most commonly employed functionalities, in particular loading and saving an MRI cohort, as well as visualizing the data corresponding to individual subjects, to groups, and to comparisons between groups.
- Brain atlas panel permits one to select a brain atlas for the MRI cohort or, if a brain atlas has already been selected, to view the brain atlas properties in GUIBrainAtlas.
- Group panel shows the subject groups and their properties in a table. Permits one to select, add, remove, move, and edit the existing groups, and to create new groups from the existing ones.
- Main panel consists of four tabs: Groups & Demographics to visualize the group data; Subject Data to edit the subjects’ data; Group Averages to calculate the averages and standard deviations of the group data; and Brain View to visualize the data on a brain surface (this brain image can be exported as a MatLab figure).
Example data and a tutorial video can be found on http://braph.org/videos/fmri/fmri-cohort/Getting Started
As a first example of the use of GUIMRICohort, we will proceed to import the brain atlas my_atlas.atlas. Then, we will proceed to import two groups of subjects from the Excel files gr1_MRI.xlsx and gr2_MRI.xlsx, and to calculate a comparison between the data. Finally, we will save the MRI cohort in a *.mc file.
- Push Select Atlas to select a brain atlas as shown in figure 2. The atlas must be in *.atlas format. After you select the file, the brain atlas panel is updated to show the properties of the atlas. The select button is changed to View Atlas; pushing this button opens the uploaded atlas in GUIBrainAtlas with restricted access (i.e. no further changes to the atlas are allowed).
- Push Load subject group from xls … to add a group from an xls file. Locate and choose the file gr1_MRI.xlsx. After the file is selected, the group panel is updated to show to group’s properties: the group name (editable), the number of subjects, and the notes (editable). The main panel is updated to show the subject data tab, as shown in figure 3.
A series of options are available to create new groups from the existing ones. They are accessible both through the buttons at the bottom of the group panel and through the menu. These are:
- Add adds new group at the bottom of the list.
- Remove removes the selected group.
- Move up moves the selected group up by one place.
- Move down moves the selected group down by one place.
- Invert creates a new group from the subjects not belonging to the group selected in the neighboring popup menu.
- Merge creates a new group by merging the subjects participating to the two groups currently selected in the neighboring popup menus.
- Intersect creates a new group by selecting the subjects participating to both groups selected in the neighboring popup menus.
- Repeat step 2 selecting the file gr2_MRI.xlsx to import also this group of subjects. The main panel shows all subjects in the MRI cohort. If you select a group in the group panel, the main panel will show only the subject data corresponding to that group.
- Push Group Averages in the main panel to visualize the average and standard deviation of the data corresponding to each brain region for each group. Choose two groups from the popup menus at the bottom of the main view and compare their data by pushing Comparison next to the popup menus. This performs a permutation test (the number of permutations can be entered in the neighboring edit box; the default number is 1000) that provides the significance of the difference by calculating single-tailed and double-tailed p-values. Figure 4 shows these values for the comparison between the groups gr1_MRI and gr2_MRI.
- Select File Save to save the MRI cohort as a *.mc file; alternatively you can also use the shortcut Ctrl+S or the Save icon on the toolbar.
- Select File Open to open an MRI cohort previously saved with GUIMRICohort; alternatively you can also use the shortcut Ctrl+O or the Open icon on the toolbar.
File formats that can be imported
To create an MRI cohort, you need a brain atlas and the data corresponding to the groups of subjects. A brain atlas can be imported only if previously saved as a *.atlas file (e.g. by using GUIBrainAtlas). Groups of subjects can be imported from Excel (*.xls or *.xlsx), text (*.txt), or xml (*.xml) files only if these files are in the correct format. For examples, see the files gr1_MRI.xlsx, gr1_MRI.txt, and gr1_MRI.xml.
In order to be imported correctly the Excel file should have the format shown in figure 5. It must include only one sheet. The first row must include the names of the brain regions consistent with the uploaded brain atlas starting from cell B1. Each of the following rows (e.g. row 2) must contain the IDs of a subject in the first cell (e.g. A2) and the numerical information for each brain region in the subsequent cells (e.g. B2, C2, D2, …).
The format for the text file is essentially the same, including a first column with the subjects’ ID codes, first row with the names of the brain regions, and the following rows with the corresponding data about the brain regions (see gr1_MRI.txt).
The xml format is slightly more complex, but can be easily inferred from the sample file gr1_MRI.xml.
The main panel permits one to explore the data of the subjects. There is a series of four console buttons at the top that can be used to switch between various tabs. The following information can be displayed:
- Groups & Demographics shows the profiles of the subjects (see figure 6). It is possible to change the age, gender, and notes of the subjects. The composition of the groups can be altered by checking the appropriate checkboxes corresponding to each group. The buttons at the bottom allow various options for the user to manipulate, remove, and add subjects:
– Select all selects all the subjects.
– Clear selection clears the current selection.
– Add subject adds a subject at the end of the table.
– Add above adds subjects above the selected ones.
– Add below adds subjects below the selected ones.
– Remove removes the selected subjects.
– Move up moves the selected subjects up by one place.
– Move down moves the selected subjects down by one place.
– Move to top moves the selected subjects to the top of the table.
– Move to bottom moves the selected subjects to the bottom of the table.
– New group from selection creates a new group from the selected subjects. Subjects can be selected by clicking the checkboxes next to them on the left side.
When a new subject is added (see, e.g., subject 101 in figure 6), it is assigned some default code (‘subject code’), age (‘1′), gender (`not assigned’), and notes (`…’), it is not included in any group, and its data is set to zero for all brain regions. The subject properties can be edited by clicking on them in the table and subjects can be assigned to groups by clicking on the corresponding checkboxes. This new subject has been added at the end of the table; to add it at a different position in the table, select a subject and push Add below or Add above.
Subject Data shows the data for each subject in the cohort for each brain region in the brain atlas (figure 7). By default, the data are shown for all the subjects in the cohort. If a group is selected in the group panel, the data are shown only for the subjects belonging to the selected group. The header of the table shows the brain region labels, while the first column shows the subject codes. Each of the following rows contains the numerical information for each brain region of the corresponding subject. The numerical data can be edited by clicking on the desired field. Subject IDs and brain region names are not editable. The subjects and their data can be exported as a *.txt file by pushing Save subjects as txt … .
- Group Averages shows the average and the standard deviation of all brain regions’ data for each group (figure 8). A comparison can be performed between any two groups specified by the popup menus at the bottom by pushing Comparison. The significance of the differences between values are calculated by permutation test; the number of permutations can be entered as the parameter (by default ). After the calculation, the table is updated to show the differences between the values of the two groups as well as single-tailed and double-tailed p-values.
- Brain View visualizes the data on a brain surface (figures 9,10 and 11). The user can visualize subject data, group data, or group comparisons on a brain surface by pushing one of the three buttons at the bottom. Each opens an interface that allows the user to specify the parameters to plot the data:
– View subjects visualizes the data for each brain region at the level of single subjects. This opens a new interface shown in figure 9. The list on the left shows all the subjects in the cohort. The user can offset and rescale the data by entering the desired values in the corresponding field. Alternatively, the offset and rescale can be computed automatically to scale the data between 0 and 1 pushing Automatic rescaling. The negative data are substituted with their absolute values if the absolute value check box is checked, otherwise all negative values are set to zero.
The value of the data can be plotted with various graphical conventions:
* Symbol size.
* Symbol color.
* Sphere radius.
* Sphere color.
* Sphere transparency.
* Label size.
* Label color.
– View group visualizes the data for each brain region at the group level. This opens the new interface shown in figure 10. The list on the left shows all the groups in the cohort. The average and standard deviation of each group can be visualized according to the graphical conventions selected on the left and right columns, respectively. The graphical conventions and rescaling parameters can be chosen analogously to the ones detailed in the view subjects section.
– View comparison visualizes a comparison between two groups. The interface in this case is shown in figure 11. The groups are selected from the lists on the left. The user can choose to view the difference between the average values and standard deviations of the two groups as well as the single-tailed or double-tailed p-values calculated by the permutation test. The graphical conventions and rescaling parameters can be chosen analogously to the ones detailed in the view subjects section.
By right-clicking on the brain surface, one has access to four popup menus where the parameters for visualization of the brain regions can be set:
– Brain settings (figure 12) permits one to set the parameters of the brain surface, including the edge color, face color, and transparency.
– Brain region symbol settings (figure 13) allows one to change the type, size, edge, and face color of the symbols representing the brain regions. Furthermore, brain regions can be set visible or hidden. The regions on which to apply the changes can be selected from the list that appears on the left-hand side of the menu.
– Brain region sphere settings (figure 14) allows one to change the radius, edge color, face color, and transparency of the spheres representing the brain regions. Also, brain regions can be set visible or hidden. The regions on which to apply the changes can be selected from the table at the left.
– Brain region label settings (figure 15) allows one to change the font, color, and interpreter for the labels representing the brain regions. Also, brain regions can be set visible or hidden. The regions on which to apply the changes can be selected from the table at the left.
File provides various options for importing and saving an MRI cohort:
– File Open (Ctrl+O) opens a popup window to load an MRI cohort saved in *.mc format.
– File Close (Ctrl+C) closes the GUIMRICohort.
– File Save (Ctrl+S) saves the current MRI cohort in *.mc format.
– File Save as opens a popup window to save the current MRI cohort in *.mc format possibly in a different file.
– File Import (xml) imports an MRI cohort from an xml file.
– File Export (xml) exports the current MRI cohort to an xml file.
Groups provides various options to edit subject groups:
– Groups Load subject group from xls … loads subject group from xls.
– Groups Load subject group from txt … loads subject group from txt.
– Groups Load subject group from xlm … loads subject group from xlm.
– Groups Add adds a group at the end of the table.
– Groups Remove removes the selected group.
– Groups Move up moves the selected group up by one place.
– Groups Move down moves the selected group down by one place.
Subjects provides various options to edit subjects:
– Subjects Select all selects all the subjects.
– Subjects Clear selection clears the current selection.
– Subjects Add subject adds a subject at the end of the table.
– Subjects Add above adds subjects above the selected ones.
– Subjects Add below adds subjects below the selected ones.
– Subjects Remove removes the selected subjects.
– Subjects Move up moves selected subjects up by one place.
– Subjects Move down moves selected subjects down by one place.
– Subjects Move to top moves selected subjects to the top of the table.
– Subjects Move to bottom moves selected subjects to the bottom of the table.
View switches the main view to display various types of information:
– View Groups & Demographics shows group data and the profiles of the subjects.
– View Subject Data shows the data for each subject in the cohort.
– View Group Averages shows the average and the standard deviation for each group.
– View Brain View visualizes the data on a brain surface.
Brain View Generate figure (Ctrl+F) generates a figure that can be customized using the standard MatLab plotting tools. The figure can then be exported in several standard graphic formats.
Graph Analysis New MRI graph analysis launches GUIMRIGraphAnalysis,
a graph analysis manager program, using the current cohort.
About About provides information about the current version of GUIMRICohort and BRAPH.
The toolbar provides different options to open and save the MRI cohort and visualize the brain surface. It is shown in figure 16.
Open and save commands
These commands allow the user to open and save an MRI cohort in the *.mc format. These are equivalent to the open and save menu options in the File menu.
opens a popup window to load an MRI cohort in *.mc format.
saves the current MRI cohort in *.mc format.
These commands allow the user to control the visualization of the brain view.
zooms in brain view.
zooms out brain view.
drags brain view.
rotates brain view
shows/hides data cursor.
standard 3D view.
sagittal left view.
sagittal right view.
axial dorsal view.
axial ventral view.
coronal anterior view.
coronal posterior view.
switches brain surface on/off.
switches axis on/off.
switches grid on/off.
switches brain region symbols on/off.
switches brain regions spheres on/off.
switches brain region labels on/off.
Footnotes and references
- ^ The data corresponding to the brain region can be edited as explained below when discussing the subject data tab.
- ^ They are editable in the groups & demographics tab.
- ^ The order of the groups is that specified by the popup menus. Thus, the comparison between the groups gr1_MRI and gr2_MRI is not equivalent to comparison between gr2_MRI and gr1_MRI.