Data Analysis Manager for Reproducible Processing Pipelines and Reports
The data analysis management tools (introduced first in version 20) enable a systematic way in BrainVoyager to handle and work with (large) datasets: Instead of isolated documents, data is entered and managed in a hierarchically organized format describing projects, subjects, sessions as well as workflows or pipelines producing data. The information and relationships between these entities are persistently stored in the BrainVoyager database (see figure below). The explicit specification of parameters in preprocessing and data analysis workflows provides transparency and reprroducibility. Since BrainVoyager 21, the generated organization of the data on disk follows the Brain Imaging Data Structure (BIDS) recommendation supporting collaboration and data sharing. At the top level, projects are created containing flexible and extensible information about the project, included subjects, workflows and analyzed data of a research experiment or clinical study.
Note. The Data Analysis Manager will be integrated with the new BrainVoyager Notebooks; the currently produced reports will then be replaced by one notebook documenting performed analysis steps as auto-generated Python code.
Each project is identified by a unique name as well as optional information including the preferred way to organize the data on disk as well as a descriptive text describing the study. Under each specified project, subjects (participants of a study) as well as workflows can be added. Subjects added to a project are identified by a code (label) and optionally additional information. Workflows define pipelines that process input data of multiple subjects in a consistent way to create derived (intermediate or final) reproducible output data. When workflows are executed, produced data sets will be automatically named in a consistent way and added to appropriate BIDS-compatible data folders. The BrainVoyager database stores all information about defined projects, specified subjects, sessions and workflows, and what data sets have been produced and stored on disk. Note that the actual data files are not stored inside the database but are referenced and displayed to the user in tables that hide unnecessary details about the underlying folder structure. From the displayed data tables, documents can be directly opened in BrainVoyager's standard multi-document area.
Data sets created by workflows can itself serve as input for other workflows creating powerful processing pipelines. Since workflows process data in the same way for all available subjects, they implement a batch processing mechanism without the need to write scripts. Furthermore, workfows create detailed reports in HTML and PDF format as a basis for quality assurance and for detailed documentation of performed analysis steps. At present, the available workflows support project creation, anatomical and functional preprocersssing, alignment of functional and anatomical data, normalization into MNI or Talairach space and statistical (GLM) analysis at the level of single subjects and groups. Pipelines for other computational routines (e.g. machine learning, cortex-based alignment) are planned for a later release. Since all entered information is stored in a central database (see below), the information from all defined projects is persistently available and presented in tables. Furthermore the data can be easily moved to other locations, for example, to relocate experiments to another computer or to share the data with colleagues.
The datasets created by the Data Analysis Manager (see below) for each project are as default (since version 21) organised according to BIDS. Note, however, that BIDS currently standardizes the folder structure and file naming only for raw data. In order to be compatible with the evolving recommendation for derived (preprocessed, analyzed) data, the Data Analysis Manger saves derived data from preprocessing and analysis workflows in the “derivatives” folder under the top-level project folder. Note that for sharing raw data in BIDS format, one can simply copy (or upload) the respective project folder. The derivatives folder should, however, NOT be included when sharing a project's raw data.
While the raw data files are stored in NIfTI format with sidecar files as required by BIDS, the generated (intermediate) data files are stored at present in conventional BrainVoyager file formats (FMR-STC, VMR-VTC., ..). For future versions it is planned to also store the derived data in NIfTI files together with JSON sidecar files.
The Data Analysis Manager
The Data Analysis Manager window (see snapshot below) provides access to the project, subjects, workflow, report and database functionality. The window is initially configured to appear automatically at program start. To turn this off, the Start At Launch option in the right lower section of the window can be unchecked. The Data Analysis Manager window can be invoked at any time using the Data Analysis Manager icon at the left side of the toolbar of the main BrainVoyager window or with the keyboard shortcut CTRL-D (CMD-D on Mac). Note that using the data management tools is optional, i.e. BrainVoyager can be used in the same way as in previous versions, and it is also possible (recommended) to mix workflow and conventional (single-document) tools, e.g. by performing basic analysis pipelines with data manager workflows and to continue with more specific tools afterwards.
The Projects pane on the left upper side contains a list of all defined projects. In case that projects are avaialbe, the program automatically selects the last inspected project in the Projects pane. Any available project can be selected by clicking its name. When a project is selected in the Projects pane its associated information is accessed from the BrainVoyager database and shown in the Subjects pane (left lower section), in the Workflows and Data tabs (in the main middle section) and in the Reports pane that is shown floated or docked to the right side of the main data analysis manager window. If a specific subject is selected, the data of this subject is shown in the subject-level data table in the Data tab (filled with "green" entries in the screenshot above). The entries in the data tables not only show references to data that is already available on disk but also data entries that are not yet stored as files but expected to become available when running a corresponding workflow that has been defined but not yet executed. The different entries are distinguished by different colors. If referenced data is available on disk, its entry in the data table is colored green; a data entry (created by a workflow) without a link to existing data on disk is colored red and the Linked File column will be empty.
The following topics describe the most important functions offered by the Data Analysis Manager:
- Create new projects
- Add subjects to a project
- Define and run Create Document workflows or Import NIfTI Document workflows
- Define and run Preprocessing workflows creating derived data
- Define and run Group-GLM Statistics workflows
- Optional: Use the Add Document workflow to integrate existing data
The BrainVoyager Database
The BrainVoyager database is a standard SQLite database that can be assessed also outside of BrainVoyager. While it might be interesting to see the stored tables in full detail (as compared to the simplified user-oriented display in the Data Analysis Manager window), it is recommended to not change the stored information in order to keep the consistency of the database. The BrainVoyager database is stored at the following default location within the user's home directory:
- Windows: C:\Users\[user]\AppData\Local\Brain Innovation\BrainVoyager\brainvoyager.db
- Mac OS X: ~/Library/Application Support/Brain Innovation/brainvoyager.db
- Linux: ~/Documents/Brain Innovation/brainvoyager.db
Note that the BrainVoyager database does not store the actual data files but only references to the data in the project root directory. The default data root path for projects is located in the user's "Documents/BrainVoyager/Projects" folder (since BV v22.0) or "Documents/BrainVoyagerData" folder but it can be changed by using the Browse button next to the Default projects root path field at the bottom of the Data Analysis Manager window. Note, however, that changing the default root path will only suggest the new path when creating new projects. Topic Moving Projects to a New Location describes how to handle the case when moving individual projects or the whole projects directory to a new location or computer.
Copyright © 2020 Rainer Goebel. All rights reserved.