BrainVoyager 22.2 Release Notes

New Features

 

Project and Workflow Programming InterfaceThis version introduces a powerful Python programming interface for the management of projects, workflows, datasets and reports. With a few lines of code, one can create and manage projects, define and run workflows, inspect notebook reports, and open and use produced (derived) datasets. Since workflows run in the same way across all subjects, the written Python code serves as an executable document for reproducible data analysis. The Python interface uses the BIDS folder structure to discover the structure of projects, data and workflows without the need of a separate database. Additional meta-information about subjects, analysis parameters and data flow connections are stored in human readable JSON files at appropriate locations in the BIDS directory tree. Furthermore, rich editable quality assurance reports are generated as self-contained BrainVoyager notebook files. For further details of the programming interface, see the "Python Developer Guide".
New Data Analysis ManagerThe new Python interface (see above) serves also as the basis of BrainVoyager's new Data Analysis Manager. The predictable BIDS folder structure and supporting JSON files no longer require a separate (MySQL) database as used in the old Data Analysis Manager. Building the programming as well as user interface project management tools on a common interface has the advantage that changes in Python are automatically reflected in the "Data Analysis Manager" window allowing to freely mix the two approaches to project management. This approach makes it also possible to use other (BrainVoyager or other software) tools to process datasets without getting out of synch with the informaton stored in a separate database as could happen in previous versions. Note that the old Data Analysis Manager is still available but marked as deprecated and it will be removed in a future release. It is possible to switch between the old and new Data Analysis Manager in the "GUI" tab of the "Settings" ("Preferences" on macOS) dialog. For details, see chapter "Data Analysis Management" in the updated User's Guide.
Inter-Subject Correlation AnalysisThis release adds Inter-Subject Correlation (ISC) analysis. While there was a very old ISC tool available based on multiple regression in past releases, it was rather limited in scope. The new implementation adds the possibility to run pairwise correlations of a provided list of 4D time course (VTC) files [as well as a version calculating the correlation of each 4D dataset with the mean of all other datasets serving as the target. Furthermore, ISC can be computed for a set of provided regions-of-interests (VOIs) producing correlation matrices for mean regional volume time courses. The ISC analysis tool is available in the newly added "FuncConn" menu. For more details, see topic "Inter-Subject Correlation (ISC) Analysis" in the "Functional Connectivity Analysis" chapter of the User's Guide.
Interactive GLM VisualizerThe new Interactive GLM Visualizer, developed originally for the BV EDU version, provides a tool to inspect how a time series is fitted by the weighted sum of predictor time courses. The data time course and scaled predictor time courses are shown in vertical time-aligned plots with associated beta values. Individual predictors can be turned off to study their impact on the overall fitted time course. For didactic purposes, beta values can also be changed, which can be used, e.g. as an exercise, to manually fit a time course. The GLM visualizer can be invoked easily from the context menu of a Time Course Plot window, which will automatically create a design matrix from a linked protocol. For options to define and load custom defined design matrices, the tool can also be called via the "GLM Builder and Visualizer" item in the "Analysis" menu.

 

Enhancements

 

Improved MNI NormalizationThe MNI normalization function has been improved to provide more robust results in cases of source (native space) brains that are rotated away substantially from the AC-PC plane. The improvement uses a new iterative rigid rotation step bringing the brain in a near-ACPC (nACPC) space before the full (12-affine) normalization. A second improvement addresses the issue that some brains were not exactly fitting in the MNI bounding box after template matching. This is now addressed by a step (enabled as default) that uses a global non-linear adjustment by scaling 6 sub-cuboids into the MNI bounding box. Furthermore, a template with more details is now used as default. For more details, see the updated "MNI Normalization" topic in the "Transformation to Normalized Space" chapter of the User's Guide.
VMR-Specific VOIsIn previous versions only a single set of volumes-of-interest (VOIs) could be loaded and displayed. In this release, each VMR document keeps its own set of VOIs, which makes it possible to display different VOIs for different anatomical documents in the multi-document workspace.
More than 254 VOI LabelsWhile a VOI file could have an unlimited number of VOIs, only the first 254 VOIs could be visually displayed. This limitation has been lifted to 65534 VOI displays (1 entry of 65535 values is reserved for a "no label" tag) by switching internally from a single-byte (8 bit) to a two-bytes (16 bit) data structure. This is also useful when importing atlas data (e.g. stored in NIfTI files) where each label is marked by a different intensity value. In previous versions a maximum of 254 labels could be processed but now also larger label counts are supported. Note that when importing a (int or float) NIfTI atlas file, the labels are stored in the V16 file generated next to the VMR file (8 bit) itself since the VMR document alone can not show all labels if exceeding 254 values. It is, thus, important to convert the V16 data into VOIs by using the "Conert VMR/V16 Label Values to VOIs " function available in the "Volumes" menu to obtain VOIs for all labels stored in the V16 data set.
Support for 4D NIfTI in Normalized SpaceNIfTI files containig 4D time courses were supported already in previous versions but only if they were in native (scanner) space; these 4D NIfTI files are converted into FMR-STC files. It is now possible to save normalized (MNI / TAL) VTC documents as 4D NIfTI files from the 'VTC Properties' dialog. Furthermore 4D NIfTI files in normalized space (sform code of 3 (Talairach) or 4 (MNI)) can now be read and will be saved as VMR-VTC documents. At present, only normalized NIfTI files with a transformation matrix that does not contain rotations (and shears) are supported, i.e. the data must have been stored after normalization in the file. If the transformation matrix contains non-integral scales, the data will be scaled to the next better integral VTC resolution (e.g. a voxel size of 2.4 or 2.7 will be rescaled to a resolution of 2.0); in case of integral scales (e.g. 2.0 or 3.0) the data will not be resampled when creating the VTC document.
Python and Notebook EnhancementsBesides the new Project and Workflow API, Python support has been enhanced. The "Select Python On Disk" dialog now supports multiple different Python versions - in this release both Python 3.6 and Python 3.8 are supported. For better support of TensorFlow, it is recommended to use Python 3.8 and TensorFlow version 2.2, for details see the updated "Installing and Enabling Python" topic in the "General Information" chapter of the User's Guide. The BV Notebook window now auto-saves edited notebooks and asks whether one wants to use them (if available) when restarting after a crash. In addition, the auto-generating Python code functionality has been further extended sending now also commands related to mesh creation and morphing to a receiving BV notebook (support for auto-generating CBA code is planned for the next release). For details, see the updated "Auto-Coding GSG Analysis" notebook and updated topic "From User Interface Actions to Python Code" in the "BV Notebooks" chapter of the User's Guide.
Derivative PredictorsIt is now possible to add time derivative predictors next to each main predictor of a single-run design matrix by enabling the "Add time derivative" option in the "Single Factor Design" tab of the "Single Study GLM Options" dialog. The effect of the derivatives can be, for example, inspected using the interactive GLM visualizer by modifying the value of derivative predictor's beta value.
Adjusting Exclusion of First PredictorWhen defining main predictors using the "Define Pres" button in the "Single Study GLM" dialog (or the corresponding button in the "Options" dialog), the program uses the global setting to exclude or include a predictor for the first condition. Excluding the first condition is useful in case it is a "Rest" or "Baseline" condition. However some protocols might not define an extra predictor for the first condition, which may lead to the exclusion of a condition predictor. This potential issue could go unnoticed by users. This has been improved by now always displaying all defined predictors as default after using the "Define Preds" function. More importantly, the program now guesses from the name of the first condition whether it is a baseline condition and warns the user in case that the "Exclude first condition" setting does not match to the current protocol. Furthermore, the program pops-up a message offering to adjust the setting automatically - if accepted, the setting is changed and the predictors are redefined accordingly.
Ideal Time Courses in Event-Related Averaging PlotsEvent-related averaging plots may now show ideal (noise-free) time courses as predicted by the generic HRF function. This may be useful to assess how good empirical event-related averages match in time and extent with ideal predictions. The ideal time courses can be enabled by turning on (default) the new "Ideal" option in "ROI Signal Time Course" plots. The ideal averaging time courses are only available if a ".dat" file with the same base name as a ".avg" file is available. This file is now created automatically when generating "AVG" files in the "Event-Related Averaging Specification" dialog by saving the time courses displayed in the "Expected response plot" section.
Removing Sections from 4D Time Course DatasetsFMR-STC time courses can now be edited to remove problematic sections (e.g. corrupted by motion) from a time course. In case that a protocol is linked to the FMR-STC data, it will be adjusted accordingly. The hemodynamic delay should be considered, however, when editing time course datasets and it is advised to only remove sections within baseline periods if possible.
Integrated Access to Functional Connectivity Toolsa new "FuncConn" menu has been added in the main menu bar to simplify access of available functional and effective connectivity tools in BrainVoyager, including ICA, GCM, ISC and graph-theoretical connectivity analysis..
Matrix Color Displays with NumbersWhen presenting data in image-like matrices (e.g. correlation matrices or dissimilarity matrices), the program now shows teh (e.g. correlation) values in cells in case there is enough space for text available.
Custom Cross SettingsWhen changing settings of the cross displayed in VMR windows, they were reset to defaults in later sessions. The new 'Save As Default' button in the '3D Coords' tab of the '3D Volume Tools' dialog can now be used to store custom settings permanently. If one wants to go back to the system default cross parameters, one can use the 'Reset' button beneath the 'Save As Default' button.
Show VTC VolumeThe 'Show VTC Vol' function in the 'Spatial Transf' tab of the '3D Volume Tools' dialog now creates a 16-bit representation instead of 8-bit. This allows to adjust the contrast and brightness of the visualized functional VMR volume. The 'Contrast And Brightness' dialog is automatically invoked in case the new 'Adjust contrast dialog' option is turned on.
Ultra-High Resolution Sphere for CBAWhile the high resolution standard spheres for cortex-based alignment (CBA) have a high enough resolution for most cases (# vertices: 163,842, # triangles: 327,680), a "ultra-high" resolution option has been added with more than a million triangles (# vertices: 655,362, # triangles: 1,310,720) that might be useful for meshes created from sub-millimeter anatomical datasets. The new option is available in the "Resolution" section of the "Curvature" tab of the "Cortex-Based Alignment" dialog. Note that the resolution of standard sphere meshes needs to be selected at the begin of CBA, especially before the standard sphere maps the original folded cortex of hemispheres that have been inflated to a sphere. The ultra-high resolution option has been added experimentally in this release and will need currently some custom fine-tuning of morphing parameters despite provided adjustments of default parameters.
Movie StudioAnimations created with Movie Studio can now be exported as lossless WebP animations, which can be further converted to .mp4 (or similar) movie formats externally using custom quality / file size adjustments. Furthermore, mesh visibility is now stored at each state, which is useful to show/hide meshes in multi-mesh scenes. Also the alpha value of a mesh is now stored at each state making it possible to animate mesh transparency.

 

Bug Fixes

 

VMP SmoothingWhen spatially smoothing VMP maps by using the "Smooth" button in the "Map Options" tab of the "Volume Maps" dialog, the result was shown as expected but the smoothed map was not saved for further use, i.e. it was not available for saving or for sampling from surface meshes. This issue has been fixed.
Granger Causality MappingThe 'RFX GCM Plugin' did not work for MNI datasets and also did not produce group VMP maps that can be used as input for an RFX analysis. These issues as well as some minor ones in the (RFX) GCM plugins have been fixed in this release. Note that these plugins can now be called from the new 'FuncConn' menu.
Predictor z-TransformationIn rare cases, the z normalization option for predictor time courses in the 'General General Linear Model' dialog did not work because of unprecise rounding of float data. This issue has been fixed by replacing float with double precision values for the calculation.
Contrast Brightness DialogThe contrast and brighntess dialog now applies to the secondary VMR if selected using the 'Show secondary VMR' option in the 'Spatial Transf' tab of the '3D Volume Tools' dialog. In previous versions it applied always to the primary VMR even if this was not shown.