GUIfMRICohort is a graphical user interface that allows the user to create an fMRI cohort by adding individual subjects or by importing groups of subjects from data files in xls, mat, or xlm format. The user can also edit the data and anagraphic details of the subjects, as well as create groups of subjects. Furthermore, GUIfMRICohort provides numerous options to visualize the data relative to individual subjects and groups. The fMRI cohort can be saved in a file *.fc for future use within BRAPH; it also can be exported in xml format for use within other programs.
The layout of GUIfMRICohort is shown in figure 1. It is composed of five main work areas:
- Menu permits one to access the basic functionalities of GUIfMRICohort, including loading, saving,editing, and visualizing an fMRI cohort, as well as creating a new fMRI graph analysis.
- Toolbar gives direct access to some of the most commonly employed functionalities, in particular loading and saving an fMRI cohort.
- Brain atlas panel permits one to select a brain atlas for the fMRI 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 two tabs: Groups & Demographics to visualize the group data; and Subject Data to edit the subjects’ data.
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 GUIfMRICohort, we will proceed to import the Dosenbach brain atlas from the file dosenbach_atlas.atlas. Then, we will proceed to import two groups of subjects from the folders gr1_fMRI_mat and gr2_fMRI_mat (the subjects’ data is imported from a series of MatLab files). Finally, we will save the fMRI cohort in a *.fc 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 mat … to add a group of subjects from a series of MatLab files. Locate and choose the folder gr1_fMRI_mat which contains the subjects’ files. After the folder 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 folder gr2_fMRI_mat to import also this group of subjects. The main panel shows all subjects in the fMRI cohort. If you select a group in the group panel, the main panel will show only the subject data corresponding to that group.
- Select File Save to save the fMRI cohort as a *.fc file; alternatively you can also use the shortcut Ctrl+S or the Save icon on the toolbar.
- Select File Open to open an fMRI cohort previously saved with GUIfMRICohort; 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 fMRI 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). A group of subjects can be imported from a folder containing multiple files with the data of each subject as Excel (*.xls or *.xlsx), MatLab (*.mat), or xml (*.xml) files, only if these files are in the correct format. For examples, see the files subject1.mat, subject1.xlsx and gr1_fMRI.xml.
In order to be imported correctly a MatLab file must contain a single matrix whose columns represent brain regions; the values in a column are the values measured for a specific brain region as a function of time.
The format for the Excel file is essentially the same (see subject1.xlsx).
The xml format is slightly more complex. It can be easily inferred from the sample file gr1_fMRI.xml.
The user can enter the repetition time for the fMRI measurement in the edit box below the name for the fMRI cohort. The repetition time designates the time that passes between the subsequent excitation pulses (measured in seconds). It is the factor that determines the time at which the fMRI images are obtained.
The main panel permits one to explore the data of the subjects. There are two 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 4). 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 41 in figure 4), 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 (figure 5) features a list on the left showing all the subjects. When a subject is selected, the corresponding data are shown in the table on the right. By default, all the subjects in the cohort are added to the list. If a group is selected in the group panel, only the subjects belonging to the selected group are listed. The header of the table shows the brain region labels. Each of the following rows contains the numerical information for each brain region of the corresponding subject at a given time. The numerical data can be edited by clicking on the desired field. Subject IDs and brain region names are not editable. A new row with all zeros can be added to the data by pushing Add row.
File provides various options for importing and saving an fMRI cohort:
- File Open (Ctrl+O) opens a popup window to load a cohort saved in *.fc format.
- File Close (Ctrl+C) closes the GUIfMRICohort.
- File Save (Ctrl+S) saves the current cohort in *.fc format.
- File Save as opens a popup window to save the current cohort in *.fc format possibly in a different file.
- File Import (xml) imports an fMRI cohort from an xml file.
- File Export (xml) exports the current fMRI 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 mat … loads subject group from mat.
- 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 the group data and the profiles of the subjects.
- View Subject Data shows the data for each subject in the cohort.
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 fMRI graph analysis launches GUIfMRIGraphAnalysis, a graph analysis manager program using the current cohort.
About About provides information about the current version of GUIfMRICohort and BRAPH.
The toolbar provides the options to open and save the fMRI cohort. It is shown in figure 6.
Open and save commands
These commands allow the user to open and save an fMRI cohort in *.fc format. These are equivalent to the open and save menu options in the File menu.
opens a popup window to load an fMRI cohort in *.fc format.
saves the current fMRI cohort in *.fc format.
Footnotes and references