BrainVoyager 24.0 |
|---|
| This major release provides new features, important improvements and bug fixes. |
New Features |
|---|
| Single Trial Estimation with 'GLMsingle' | 'GLMsingle' is a powerful tool to estimate single trial responses, especially for fMRI experiments with a large number of conditions and a low number of condition repetitions (Prince et al., 2022). While one can use the Python version of the original GLMsingle implementation from inside or outside of BrainVoyager, this release provides a C++ implementation of GLMsingle to allow BV users to run single trial estimation directly and conveniently independent of any Python setup. The code is available as open source in case other software developers prefer C++ for implementing GLMsingle. The tool can be launched from the 'GLMsingle' dialog by clicking on 'GLMsingle - Single Trial Estimation' in the 'Analysis' menu. In this version only the TYPE-A (On-Off) and TYPE-B (optimized HRF) models are supported. Fitting the TYPE-B model produces the same output as the original Python implementation. Support for TYPE-C (denoising) and TYPE-D (ridge regression) models is planned for the next minor release (BV 24.2). For more details on the BV C++ implementation of GLMsingle, please consult the 'GLMsingle' sub-chapter in the 'Statistical Data Analysis' chapter of the User's Guide. |
| Atlases Support | While atlas data can be loaded and used in BrainVoyager, this release provides specific tools to support volume and surface atlases. This is visible already by a new 'Atlases' menu in the main menu bar. The new 'Atlases' menu (which can also be displayed as a sub-menu of the 'Files' menu, see below) is now also the location where one can quickly load standard anatomical MNI and Talairach files to host e.g., functional data in normalized space. The main atlases provided in this release are the 'Glasser' atlas and the 'Rosenke' (volume space) visual atlas. While these atlases could be loaded in previous versions after some processing of the original files, this release provides VOIs and POIs with all atlas area labels for MNI space as well as for inflated and flattened surface (cortex) space. Further support to quickly show custom sets of regions is provided by the new 'VOI Lists' and 'POI Lists' tools in the standard 'Volumes-Of-Interest' and 'Patches-Of-Interest' dialogs, respectively. Lists of VOIs / POIs can be defined (e.g., 'all areas in high-level visual cortex') and subsequently shown all together by using the list 'Show' button. The new atlases come with several computational and visualization tools. A major new tool is the possibility to identify active clusters of a map using the parcels of a loaded atlas. After loading and selecting a desired volume map, a click on the 'Identify Map Clusters Using Atlas Parcels' item in the 'Atlases' menu will calculate and present a table with clusters sorted by their size. Furthermore, a list of all atlas parcels overlapping with a cluster is shown sorted by the amount of cluster coverage of those parcels. For more informaiton about the new atlas tools, consult the 'Atlases' chapter of the User's Guide. |
| Event-Related Averarging Maps | Event-related averaging plots are very useful to explore time courses of voxels or regions and is supported by BrainVoyager since its beginning. It entails defining an event-related averaging '.AVG' file first, which can then be used in 'ROI Signal Time Course Plot' windows to show event-related averages over data from single runs up to large studies with many subjects. When using many files for averaging, the recalculation for newly selected time courses shown in the 'ROI Signal Time Course Plot' window may take quite some time limiting fast data exploration. To support fast real-time exploration of event-related averaging data in all cases, event-related averaging maps have been introduced. Event-related averaging maps can be created using the 'Event-Related Averaging Map' dialog, which can be launched using the 'Event-Related Averaging Map..' item in the 'Analysis' menu. In the dialog one can load a created .AVG file to pre-calculate event-related averaging results for all voxels across all included functional files, which are stored in an event-related map'(.EMP) file. When an .EMP file is linked to a VMR, a new 'Voxel AVG Plot' dialog is available that shows the AVG result 'under the mouse' when hovering over the VMR View in the same way as the 'Voxel Beta Plot'. Furthermore, with EMP data one can now also plot AVG results for regions-of-interest by using the new 'Er-AVG' button in the 'Volumes-Of-Interest' dialog. Established links from VMRs to EMPs are also stored in BrainVoyager's scene (.BVSCN) files so that they are reloaded automatically when the last scene is re-established when starting a new BrainVoyager session allowing direct inspection of event-related averaging. For more details, please consult topic 'Event-Related Averaging Maps' in the 'Event-Related Averaging' chapter of the User's Guide. |
| GLM Builder Tools | The 'GLM Builder and Visualizer' has been extended with important tools that are useful for modelling GLM data and design matrices. The new tools are available in the 'GLM Builder Tools' dialog, which can be invoked by clicking the 'Tools' button in the 'GLM Builder and Visualizer' main window. The new tools allow, for example, to create and manipulate design matrices from sratch or after loading .SDM files. The tools also provide the possibility to add confound (polynomial) predictors to a design matrix; the confounds can also directly be applied to the data vector as well as the design matrix performing a temporal high-pass filter. It is also possible to create design matrices from scratch that can be used to analyze loaded or simulated data. Any generated or modified design matrix can be saved to disk using the new 'Save SDM' button in the 'GLM Builder and Visualizer' dialog and subsequently used in the standard GLM dialogs. More information about the new powerful GLM Builder tools will be available soon. |
Enhancements |
|---|
| Finding Optimal Filters Using FFT | It is useful to inspect the frequency domain representation of time courses. This is beneficial to learn about the (stimulus) frequencies that can be useful when specifying filtering options. To support this, FFT and inverse FFT functions are now available for time courses shown in the standard 'ROI Time Course Plot' dialog (context menu), the 'Single-Study GLM' dialog as well as in the new 'GLM Builder Tools'. The frequency domain representation of the time course will be computed using the FFT algorithm and shown in a 'FFT Plot' window. The plot will also highlight the top-5 frequencies with the highest magnitude including a text label indicating both the frequency value and the corresponding duration (period) in the time domain. Furthermore, when clicking inside the window, the time course can be filtered using low- and/or high-pass cut-off values. The filtered result (inverse FFT) is shown directly in the 'ROI Time Course Plot' dialog or in a separate window when used in other dialogs. The 'FFT Plot' window will also be updated showing the frequencies that have set their magnitude to zero to implement the filter. Details of the new options are described in the topic 'Finding optimal high-pass filter values' of the 'Data Preprocessing | Preprocessing of Functional Data' chapter of the User's Guide. |
| High-Pass Filter Using Polynomials | A new option to high-pass filter functional data using polynomials of a specified degree (as used in GLMsingle) has been added to the 'FMR Data Preprocessing' and 'VTC Data Preprocessing'dialogs. To select polynomial high-pass filtering, select 'GLM with Polynomials' in the 'High-Pass Filter Options' dialog and specify the highest degree of the set of polynomials (default: 4). The (GLM-based) Fourier high-pass filtering options are recommded as default. |
| Python Support | BV 24.0 supports Python 3.10 and 3.12. The 'documentsbv_path' property has been added to enable easy access to the '[user]/Documents/BrainVoyager' folder where most BrainVoyager-related data is stored including the sub-folders 'Atlases' and 'GLMsingle' that have been added in this release. Note that 'documentsbv_path' as well as all properties of the 'bv' (or 'brainvoyager') object that retrieve a BrainVoyager-related path (e.g., 'sampledata_path', 'projects_path', 'notebook_path', 'pythonscripts_path') do now return a path without a trailing '/' delimiter (except in special cases) while they did in previous versions since this is more consistent with Python behavior. There are also new functions to load numpy arrays and to save them in BV's new .arr file format. This can be used to import numpy arrays directly that were saved in Python, for example, volume data sets and design matrices. Important note: Due to changes in how numpy 2.x and recent versions of TensorFlow handle data precision, the DNN segmentation tool might produce sub-optimal results. To avoid this, please consult the 'Installing and Enabling Python' topic in the 'General Information' chapter of the User's Guide. |
| Active Document Actions Panel | To support quick access to frequently used functions, BrainVoyager now shows a panel with a list of the most common actions for the currently active document type (VMR, FMR, DMR, SRF). The floating panel is shown initially on the right side of the screen but can be moved to another location that will be saved and restored in future sessions. Note that the same action list is also always available as a context menu when right-clicking the title bar of a document window. The new panel can be enabled or disabled using the 'Show panel with actions of active document' check box in the 'Workspace' section of the 'Layout' tab of the 'Settings' dialog. For more information, see topic 'Active Document Actions Panel' in the 'Getting Started' chapter of the User's Guide. |
| Transparent Map Thresholding with Contours | For a more complete picture of a map it is useful to use transparent thresholding instead of 'hard' thresholding to see locations in the map that missed the threshold. BrainVoyager offers this possibility since many years in the 'Visualization Options' dialog that is available in the 'Statistics' tab of the 'Volume Maps' dialog. When turning on the 'Transparency scales with significance' option in the 'Visualization Options' dialog, one can also check the new 'Add contour of hard threshoded map' option (default: on). This will create a contour that follows the borders of clusters of the original thresholded map (set via FDR or manually). The contour is overlaid as a VOI on the transpartly thresholded map, which is useful for comparison. As default, the contour is colored white but can be set to any other color (e.g. black) in the 'Volumes-Of-Interest' dialog. The minimum and maximum thresholds are set to 0.0 and to the original threshold plus 1.0 as default but can be changed in the 'Volume Maps' dialog. Furthermore, the transparencey of the overlaid contour can be changed in the 'VOI transparency' field in the 'VOI Functions' tab of the 'VOI Analysis Options' dialog, which is set to 0.8 as default. |
| Time Course Movie for VTC Files | Showing the slices of functional FMR documents is a useful feature to check image quality and head motion over time. This feature with the same 'Time Course Movie' dialog is now also available for VTC files. Independent whether VTC files are directly loaded with the 'Open VTC' menu item (or simply via the 'Open' tollbar icon, see below) or linked to a (normalized) VMR anatomy, the VTC file will always be shown in its own coordinate space, i.e. it covers the entire VMR view space. To see the effect of head motion, it is useful to convert a non-motion corrected FMR file to the corresponding '[name]_SLICES.vtc' file using the 'Convert FMR to Identical VTC' item in the 'Options' menu. |
| VTC Files | VTC files can now not only be opened using the 'Open VTC' or 'Open Pure VTC' menu items but they are now also included in the standard file types when using the generic 'Open' toolbar icon. VTC (and VDW) files are becoming the standard format also for non-normalized functional (diffusion) data replacing FMR (DMR) files in the next versions. In this context, the 'Convert FMR (DMR) to Identical VTC (VDW)' function available in the 'Options' menu has been further enhanced and will be used automatically when creating FMR / DMR documents in the future. To indicate more clearly that these "identical" VTCs are in the same non-spatially transformed original space of MRI slices as the corresponding FMR files, they are now identified as type 'SLICES' in the 'VTC/VDW/VMR Properties' dialogs; furthermore, there file names end with '[name]_SLICES.vtc' to indicate this. |
| Min / Max of VMPs | Two processing options 'Min VMPs' and 'Max VMPs' have been added in the 'Combine VMPs' dialog. The 'Min VMPs' function calculates at each voxel the minimum value of all selected VMPs while the 'Max VMPs' function calculates the maximum value. The 'Min VMP' function can be, for example, used to calculate a conjunction map such as a minimum t map. In case that the sign of values at a voxel across map values differ, the value 0.0 will be set in the resulting map. The calculated values per voxel are stored in a newly created map that is appended to the list of loaded maps. The same functionality has also been added to the 'Combine SMPs' dialog. |
| Translating VOIs | Sometimes it may be useful to slightly adjust VOIs, for example, after importing region labeling files. Using the buttons in the 'Manually translate VOIs' field in the 'Transformations' tab of the 'VOI Analysis Options' dialog, it is now possible to shift all VOIs in steps of 1 voxel along all three cardinal axes. Since the result of each translation step is visualized directly, the effect will be immediately visible of displayed VOIs in the VMR view. |
| GUI Simplification Options | This version introduces new options to simplify the GUI of BrainVoyager. This is particularly useful for beginners but comes also handy for experts that do not need certain features or that work on small (laptop) screens. One new option is to (temporarily) hide menus that are (temporarily) not of interest to a user. The 'Remove the following menus from the main menu bar' section in the 'Layout' tab of the 'Settings' dialog can be used to hide the top-level menus 'Atlases', 'EEG-MEG', 'DWI/DTI', 'FuncConn', 'Python' and 'Notebooks'. Note that essential main menus are not disappearing completely but are only moved as sub-menus to other main menus. When the 'Atlases' menu is (temporarily) hidden, it will still be available at the top of the 'Files' menu. Similarly when the 'FuncConn' menu is hidden, it will appear in the 'Analysis' menu under the name 'Functional Connectivity Tools'. In case the 'Python' and 'Notebooks' menus are hidden, the main tools are still available via the (non-hidden) 'Python' and 'Notebook' icons in the main toolbar. In addition to the menu, also the main toolbar can be adjusted. The icon of the data analysis manager can be hidden by checking the 'Hide Analysis Manager icon' option in the 'Main toolbar' section of the 'Layout' tab of the 'Settings' dialog. Instead of two "New Document" icons, now only one is present in the main toolbar corresponding to the 'New Document Wizard' option. The older 'New Document Dialog' option is still available in the 'File' menu. Note also that the new floating 'Active Document Actions Panel' (see above) also belongs to the new GUI simplification options - while adding a window, relevant tools can be found more quickly than using the rather long lists in the main menu bar. |
| Send Time Course To GLM Builder | When plotting time courses in 'ROI Signal Time Course' windows, one can click the item 'Interactive GLM' in the local context menu (e.g. by clicking with the right mouse on the time course) to show the time course as well as a standard design matrix (if a protocol is attached to the functional data) in the 'GLM Visualizer' window. A related new item 'Transfer to GLM Builder' has been added to the local context menu that sends the time course to the 'GLM Builder and Visualizer'. This allows to inspect the data numerically and to apply various tools (see 'GLM Builder Tools' above) before running and visualizing the GLM. |
| Map Spread On Click | The new 'Set Map Spread on Click' option in the context menu of the VMR view provides a quick way to change the maximum amount of spread along the 3 axes of a volume map. This is, for example, useful if one wants to change the maximum spread to 1 voxel to allow inspection of single voxel time courses instead of selecting a activation cluster. This functionality is still also available in the '3D Volume Tools' dialog that additionally allows to set different values for the maximum spread along the 3 cardinal axes. |
| Windows 11 Thene | When using an operating GUI theme instead of the generic (cross-platform) theme, a moderb Windows 11 theme is now used on Windows. |
s
Bug Fixes |
|---|
| RFX GLM Memory Calculation | While running a multi-subject RFX-GLM divides calculation into smaller pieces (separate GLM per run), the calculated betas will be accumulated for each subject in a GLM memory structure of 4-byte float values roughly containing 'subjects x betas x voxels * 4' bytes. In case that this product was larger than ca. 2 GB, the program calculated a wrong value for the requested memory reporting wrongly a 'Insufficient memory to calculate GLM map file' error. This issue has been fixed and large RFX-GLM data structures are now supported (as long as enough memory is available). |
| Reading Very Large MNI NIfTI Files | When reading MNI-space NIfTI files, they are converted from a series of volumes to a BV VTC file requiring re-arrangement of the data (time as inner loop for optimized access to time courses). This conversion might lead to much larger output files than the original (un-gzippe'd) NIfTI file in case that the functional data does not have an integral value of the spatial resolution (e.g. 1.8 x 1.8 x 2.1 vs 2 x 2 x 2), BrainVoyager performs a full resampling to 1 x 1 x 1 at present, which can cause large output VTC files. If the output VTC file was larget than 2 GB, an error occurred in previous releases. This error has been fixed in this release. The exact file size values can be inspected in the BV Log pane. |
| Event-Related Averaging | When using more than 200 files for event-related averaging, the program crashed. This error has been fixed by removing any limits (besides working memory) in the implementation of event-related averaging supporting now very large numbers of datasets. |
| Export Enhanced DICOM | The 'Export DICOM' function in the 'Spatial Transf' tab of the '3D Volume Tools' dialog allows to export (usually anatomical) 3D datasets with functional map (and VOI) overlays using the original header information. The functional overlays will be drawn with a high intensity value inside the original slices appearing as white overlays when the exported DICOM files are imported in other software (or BrainVoyager). This feature is used for special cases, especially when only DICOM files are supported in target software. This function did, however, only work with standard (one slice per file) DICOMs. With this release, also the more recently supported enhanced multi-frame DICOM format can be used with the 'Export DICOM' function. |
| Python GUI | When running Python code that launches modal (blocking) GUI dialogs (as in the 'messagebox.py' and 'gui_example.py' sample files), interactions with the user interface elements inside the dialog were not possible. This issue has been fixed. |
| Python Console | When running a Python script it could happen that new output in the Python console was written inside existing text; this happened when the position of the cursor was moved inside console text, for example, when selecting and copying some output. This issue has been fixed by moving the cursor in the Python console to the end of its text when launching a script. |
| Volume Renderer VOI Overlays | Showing VOIs with more thn 255 regions (parcels) in the Volume Renderer was not supported correctly in previous versions. This issue has been fixed by supporting 16-bit index values for overlays supporting now up to 65535 parcels. |
| Single-Slice VTCs | When a single-slice VTC was used, clicking on the slice to show time course plots did not work. This issue has been fixed. |
| VMP To SMP Sampling | When using the 'Create SMP' button in the 'Surface Maps' dialog to sample VMPs overlaid on the associated VMR, the option 'Only positive values' was ignored when nearest neighbor interpolation was used (it worked fine when using trilinear interpolation). This issue has been fixed. |
| Grid Sampling in VOIs | When sampling high-resolution depth grids (layers) in the context of laminar MRI analysis, the option to restrict the sampling to a specified region via VOIs had been ignored in the 23.x releases. This issue has been fixed. |
| Batch DICOM to NIfTI Conversion | When using the batch DICOM to NIfTI conversion tool of the Data Analysis Manager, the values in the 'sub-ID' fields were restricted to a maximum of 99. This restriction has been lifted and it is now possible to use values up to 9999. |
| Batch DICOM to NIfTI Conversion: DWI | When using the batch DICOM to NIfTI conversion tool of the Data Analysis Manager, it was not possible to select a 'Directions' file when adding diffusion-weighted data. Normally direction and b-value information can be extracted from DICOM files but in case that this is not possible, a 'GRB' file can now be provided. |
| Importing Interpolated DICOM Data | When importing interpolated (upsampled by factor of 2) DICOM data, the program could crash since the interpolation was not always detected. This issue has been fixed. |
| MNI Coords for Non-1mm VMRs | In case a datset in MNI space had non-1mm (e.g., sub-millimeter) spatial resolution, clicking the coordinates spin boxes in the 'MNI Coords' field of the '3D Volume Tools' dialog did not work correctly. This issue has been fixed. |
| DICOM Files with Implicit VR Coding | Some DICOM files with implicit VR (value representation) coding could not be read and renamed. The reason was that some sequence (SQ) elements that need to be known for parsing were missing. More SQ elements have been added so that nearly all MR DICOM files with implict VR coding should be readable. |