BrainVoyager 23.2 |
|---|
| This minor release focuses on important improvements and bug fixes. |
New Features |
|---|
| Reading 4D Normalized Func NIfTI Files | If 4D functional NIfTI files are in 'Scanner' space, they are imported as FMR/STC documents without applying the spatial transformation. Normalized 4D NIfTI files were only accepted in some cases in previous versions when the spatial transformation (sform code) did not contain rotations and only integral scales. This excluded import of many 4D nifti files that were preprocessed with pipelines such as fmriprep, which often contain non-integral and/or non-iso scales. The new functions in this release read all 4D func nifti files by applying the full transform saving the result as a VTC file with the first functional volume as the visible ('hosting') VMR file. Since nearest neighbor interpolation is used for files with no rotations and only integral scales, the final VTC contains a unmodified copy of the original nifti data in normalized space (placed in a standard bounding box) while in case of rotations or non-integral non-iso scales, the data is interpolated using CPU-parallelized interpolation. The interpolation method (default Lanczos) can be chosen in the 'Reading normalized space 4D NIfTI as VTC' field in the 'NIfTI' tab of the 'Settings' dialog. In all cases, scales are analyzed and used to set the 'func-to-anat' integral scale value (1, 2 or 3) for the transformation; for non-integral scales the nearest (over-sampled) integer value is used, e.g., for a scale of '2.5', a 'func-to-anat' scale of '2' would be used, which can be inspected also after reading the NifTI file in the 'VTC Properties' dialog. Details of how a 4D nifti is processed are written to the 'Log' tab. For more details, consult the 'Functional 4D NIfTI Files' topic in the 'NIfTI Files' chapter of the updated User's Guide. |
| Cluster-Thresholding GUI Plugin | The cluster-thresholding plugin is available for many years and provides an important additional means to test statistical results for significance by finding an appropriate cluster threshold given an uncorrected single-voxel threshold of p = 0.001 (or smaller). The plugin has, however, not a proper user interface, and its use with a sequence of dialogs asking questions is somewhat inconvenient. While the 'classical' plugin remains available, the new Cluster-Thresholding GUI plugin provides a dialog that allows entering and checking all important information in a single place before committing to the compute-intensive calculation to find a cluster-level statistical threshold. The new GUI version can not only be called from the 'Plugins' menu but is integrated directly in the 'Volume Maps' dialog with a new 'Correct' button in the 'Cluster threshold' field of the 'Statistics' tab. Furthermore, the GUI version can also be called from the 'Analysis' menu. An important improvement of both the 'classical' and GUI cluster-thresholding plugin is that it can be applied more generally since its application is no longer restricted to hosting VMRs with dimensions of 256 voxels. |
Enhancements |
|---|
| Writing Normalized NIfTI Files | The writing of 4D normalized VTCs and VMPs as NIfTI files has been improved using default MNI / TAL bounding box ranges for consistency across data from multiple runs and subjects. Furthermore, when saving a normalized VTC as a NIfTI file, a linked protocol is now exported as a TSV file in the same way as when writing FMR / STC documents as NIftI files in 'Scanner' space. |
| Open (Pure) VTC Functions | The usual way to load a VTC (4D functional time series) file requires first loading a 'hosting' VMR file from which the VTC file is then linked. This has the advantage that one can select different VMRs (from a participant or a template brain) for visualization of VTC derived data such as calculated statistical maps. If one is interested in opening a VTC quickly, one can now use the new 'Open VTC' function in the 'File' menu. Instead of a chosen VMR, this function will display the first functional volume of the VTC as the 'hosting' VMR. A related function, 'Ope Pure VTC' is also provided in the 'Files' menu. The difference is that the 'Open VTC' function places the visualized VTC volume in the position of the respective normalized space (e.g. MNI) in the hosting VMR (usually with dimensions of 256 voxels) using the VTC's bounding box definition (in the same way as when linking the VTC), while the 'Open Pure VTC' version ignores the location in a normalized space and shows the VTC 'as is'. In most cases, the 'Open VTC' variant is appropriate but the 'Open Pure VTC' function might be useful in some cases when inspection of the 'pure' VTC data is sufficient. |
| VMR View Tooltip With V16 Intensity | The VMR View Tooltip overlay shows the intensity of the underlying VMR when hovering over the orthographic (SAG, TRA, COR) slices. In case that a (16 bit intensities) V16 volume is attached to the (8 bit intensities) VMR, it might be useful to inspect the V16 intensity values next to the 8 bit intensity values. The tooltip now shows the V16 intensity of the voxel below the mouse cursor on the right side of the VMR intensity value. To quickly load the V16 with the same name of the VMR, one can, for example, call the 'Contrast / Brightness' dialog. |
| Adjusting Intensities To Match Default WM / GM | The 'Contrast / Brightness' dialog contains the 'Set to standard GM WM' button that aims to adjust the VMR/V16 intensities in a way that the mean values of white and grey matter match defaul intensity values, usually GM (grey matter) = 100, WM (white matter) = 150. This function has been substantially improved in this release. It is intended to be used after brain extraction and spatial intensity inhomogeneity correction, i.e. after running the standard IIHC functionality using the '16 Bit 3D Tools' dialog. Setting the WM and GM values using this function prepares the dataset optimally for subsequent segmentation functions, including segmentation for boundary-based registration (BBR) or when using the 'Advanced Segmentation' dialog. The default parameters for GM and WM can be adjusted temporarily in the Contrast / Brightness dialog. If one wants to make permanent changes, one can change the default values in the 'Analysis' tab of the 'Settings' dialog. It is not advised to change the default value of GM (100) since this value is expected by several functions, but changing the WM value to a different value (e.g. 170 or 180) might be useful if one wants to visualize white matter in more white instead of grey color. |
| Center Cross Function In VMR View Menu | To make it possible to quickly access the 'Center cross' function that can be called using the 'Center' button in the 'Coregister' tab of the '3D Volume Tools' dialog, this functino has been added to the VMR View context menu that can be invoked by right-clicking inside the VMR window. |
| Show First VTC Volume Function In VMR View Menu | To make it possible to quickly access the 'Show First VTC Volume' function that can be called using the 'Show VTC Vol' button in the 'Spatial Transf' tab of the '3D Volume Tools' dialog, this functino has been added to the VMR View context menu that can be invoked by right-clicking inside the VMR window. |
| JS Script Commands | For GUI scripts and GUI plugins, new functions have been added to the 'bv' ('BrainVoyager') script object that allow to set the minimum and maximum size of a GUI dialog: 'SetMinimumSizeOfPluginWindow(int widht, int height)', 'SetMaximumSizeOfPluginWindow(int widht, int height)', 'SetMinimumSizeOfGUIScriptWindow(int width, int height)' and 'SetMaximumSizeOfGUIScriptWindow(int width, int height)'. While it is usually not necessary to restrict the maximum size of a dialog window, it is useful to set a minimum size to prevent that a window can be made so small that user interface elements are hidden from view. It is advised to call these functions in the 'Component.onCompleted' function of the dialog (see provided examples in the 'Scripts' and 'Plugins' folders for detail). Furthermore, the 'MessageBox()' function obtained an optional second parameter for a 'detailed message' string (next to the main message string provided in the first parameter). Also the possibility to provide a 'Yes / No' dialog has been added with the new 'YesNoMessageBox()' function, which accepts the same parameters as the message box and shows a 'Yes' and a 'No' button. If the user presses the 'Yes' button, the function returns 'true', otherwise 'false'. The 'document' object obtained the new commands 'ShowVOIsDialog()' and 'HideVOIsDialog()' as well as the 'GetBetaTValueOfROIGLM()' and 'GetBetaPValueOfROIGLM()' functions accepting the index of a fitted beta value as input (these functiosn are defined for the Pyhton interface but were missing for JS scripts). |
Bug Fixes |
|---|
| Iso-Voxelation on macOS | Iso-voxelation using Metal shaders on devices with Apple Silicon and Intel chips did not work in the previous release (had been fixed for Apple Silicon in patch release 23.0.9). This issue has been fixed. |
| Average VTC Volumes | The option 'Average VTC Over Time And Convert To VMR' in the 'Options' menu can be used to average all volumes of a VTC to create a VMR (and V16) file. This function resulted in empty files in version 22.4 and 23.0.8. This issue has been fixed. |
| Create VTC On Apple Using 'Metal' Compute | Sometimes a crash happened when running the 'create_vtc' Python or 'CreateVTC' JS script function (but also when using the user interface) for large datasets. This has been solved by optimising Metal compute shader code, which now reuses once allocated Metal volume buffers for each volume of a sequence. The improvement has been also applied to FMR motion correction to ensure fast and robust performance. |
| VOI RFX GLM | When running RFX GLMs for volume regions of interest (VOIs) with (dummy-coded) runs containing predictors with only 0 values in the design matrix, the program crashed. This issue has been fixed. |
| Automatic Cortex Segmentation For BBR | When running the 'Automatic Cortex Segmentation for BBR' function via script or the user interface, the function sometimes returned without running the cortex (WM) segmentation and cortex mesh reconstruction. This issue was caused by a sub-optimal contrast / brightness setting. This issue is now solved by internally calling the 'Set to standard GM/WM' function described above under 'Enhancements'. |
| Coregistration Using BBR Script Function | When calling the Python script function 'coregister_fmr_to_vmr_using_bbr' (or the equivalent JS function), the .VOI with the GM boundary before and after the alignment was not created and saved as in the GUI version. This issue has been fixed. |
| Automatic Creation of Project Folders | In some cases the automatic creation of a 'rawdata' folder did not work correctly (there could be a nested chain of 'rawdata' and 'sourcedata' folders). This issue has been fixed. |
| LoadVOIFile Script Function | The 'LoadVOIFile()' JS script function did not work in previous 23.x versions. This issue has been fixed. |
| Windows - No Fibers Visualized in Line Mode | When visualizing fiber tracts and tensor lines, nothing was shown on Windows in previous 23.x veresions. Only if 'tube' rendering mode was used, fiber tracts could be visualized. This issue with visualizing lines on Windows has been fixed in this release. |
| Interactive Fiber Tracking | Interactive fiber tracking did not work in previous versions. In the current version 'CTRL-click' on a brain slice does still not work but it is now possible via the context menu of the VMR View. After invoking the context menu (usually via right-clicking) at a voxel of a VMR slice, one can select the "Track fibers from cross position" option to launch fiber tracking from the selected voxel. One can then switch to the associated 'Brain Viewer' window to se the tracked slices. It is recommended to 'tile' the VMR and Brain Viewer window next to each other to see both the slice(s) and the tract fibers. |
| Open Pure VTC - TR Value | When using the 'Open Pure VTC' function from the 'File' menu, invoked time course plots die not show a linked protocol correctly since the VTC TR value was not provided correctly to the 'Time Course Plot' window. This issue has been fixed. |
| Saving FMR Files | When saving FMR files, a small change had been introduced in 23.0, namely to use the strings 'NrOfColumns' and 'NrOfRows' instead of 'ResolutionX' and 'ResolutionY'. This led, however, to issues in some programs that read FMR files, and this change has been reverted. It is planned to introduce the renaming with the next version update of FMR files. |
New Features |
|---|
| Reading 4D Normalized Func NIfTI Files | If 4D functional NIfTI files are in 'Scanner' space, they are imported as FMR/STC documents without applying the spatial transformation. Normalized 4D NIfTI files were only accepted in some cases in previous versions when the spatial transformation (sform code) did not contain rotations and only integral scales. This excluded import of many 4D nifti files that were preprocessed with pipelines such as fmriprep, which often contain non-integral and/or non-iso scales. The new functions in this release read all 4D func nifti files by applying the full transform saving the result as a VTC file with the first functional volume as the visible ('hosting') VMR file. Since nearest neighbor interpolation is used for files with no rotations and only integral scales, the final VTC contains a unmodified copy of the original nifti data in normalized space (placed in a standard bounding box) while in case of rotations or non-integral non-iso scales, the data is interpolated using CPU-parallelized interpolation. The interpolation method (default Lanczos) can be chosen in the 'Reading normalized space 4D NIfTI as VTC' field in the 'NIfTI' tab of the 'Settings' dialog. In all cases, scales are analyzed and used to set the 'func-to-anat' integral scale value (1, 2 or 3) for the transformation; for non-integral scales the nearest (over-sampled) integer value is used, e.g., for a scale of '2.5', a 'func-to-anat' scale of '2' would be used, which can be inspected also after reading the NifTI file in the 'VTC Properties' dialog. Details of how a 4D nifti is processed are written to the 'Log' tab. For more details, consult the 'Functional 4D NIfTI Files' topic in the 'NIfTI Files' chapter of the updated User's Guide. |
| Cluster-Thresholding GUI Plugin | The cluster-thresholding plugin is available for many years and provides an important additional means to test statistical results for significance by finding an appropriate cluster threshold given an uncorrected single-voxel threshold of p = 0.001 (or smaller). The plugin has, however, not a proper user interface, and its use with a sequence of dialogs asking questions is somewhat inconvenient. While the 'classical' plugin remains available, the new Cluster-Thresholding GUI plugin provides a dialog that allows entering and checking all important information in a single place before committing to the compute-intensive calculation to find a cluster-level statistical threshold. The new GUI version can not only be called from the 'Plugins' menu but is integrated directly in the 'Volume Maps' dialog with a new 'Correct' button in the 'Cluster threshold' field of the 'Statistics' tab. Furthermore, the GUI version can also be called from the 'Analysis' menu. An important improvement of both the 'classical' and GUI cluster-thresholding plugin is that it can be applied more generally since its application is no longer restricted to hosting VMRs with dimensions of 256 voxels. |
Enhancements |
|---|
| Writing Normalized NIfTI Files | The writing of 4D normalized VTCs and VMPs as NIfTI files has been improved using default MNI / TAL bounding box ranges for consistency across data from multiple runs and subjects. Furthermore, when saving a normalized VTC as a NIfTI file, a linked protocol is now exported as a TSV file in the same way as when writing FMR / STC documents as NIftI files in 'Scanner' space. |
| Open (Pure) VTC Functions | The usual way to load a VTC (4D functional time series) file requires first loading a 'hosting' VMR file from which the VTC file is then linked. This has the advantage that one can select different VMRs (from a participant or a template brain) for visualization of VTC derived data such as calculated statistical maps. If one is interested in opening a VTC quickly, one can now use the new 'Open VTC' function in the 'File' menu. Instead of a chosen VMR, this function will display the first functional volume of the VTC as the 'hosting' VMR. A related function, 'Ope Pure VTC' is also provided in the 'Files' menu. The difference is that the 'Open VTC' function places the visualized VTC volume in the position of the respective normalized space (e.g. MNI) in the hosting VMR (usually with dimensions of 256 voxels) using the VTC's bounding box definition (in the same way as when linking the VTC), while the 'Open Pure VTC' version ignores the location in a normalized space and shows the VTC 'as is'. In most cases, the 'Open VTC' variant is appropriate but the 'Open Pure VTC' function might be useful in some cases when inspection of the 'pure' VTC data is sufficient. |
| VMR View Tooltip With V16 Intensity | The VMR View Tooltip overlay shows the intensity of the underlying VMR when hovering over the orthographic (SAG, TRA, COR) slices. In case that a (16 bit intensities) V16 volume is attached to the (8 bit intensities) VMR, it might be useful to inspect the V16 intensity values next to the 8 bit intensity values. The tooltip now shows the V16 intensity of the voxel below the mouse cursor on the right side of the VMR intensity value. To quickly load the V16 with the same name of the VMR, one can, for example, call the 'Contrast / Brightness' dialog. |
| Adjusting Intensities To Match Default WM / GM | The 'Contrast / Brightness' dialog contains the 'Set to standard GM WM' button that aims to adjust the VMR/V16 intensities in a way that the mean values of white and grey matter match defaul intensity values, usually GM (grey matter) = 100, WM (white matter) = 150. This function has been substantially improved in this release. It is intended to be used after brain extraction and spatial intensity inhomogeneity correction, i.e. after running the standard IIHC functionality using the '16 Bit 3D Tools' dialog. Setting the WM and GM values using this function prepares the dataset optimally for subsequent segmentation functions, including segmentation for boundary-based registration (BBR) or when using the 'Advanced Segmentation' dialog. The default parameters for GM and WM can be adjusted temporarily in the Contrast / Brightness dialog. If one wants to make permanent changes, one can change the default values in the 'Analysis' tab of the 'Settings' dialog. It is not advised to change the default value of GM (100) since this value is expected by several functions, but changing the WM value to a different value (e.g. 170 or 180) might be useful if one wants to visualize white matter in more white instead of grey color. |
| Center Cross Function In VMR View Menu | To make it possible to quickly access the 'Center cross' function that can be called using the 'Center' button in the 'Coregister' tab of the '3D Volume Tools' dialog, this functino has been added to the VMR View context menu that can be invoked by right-clicking inside the VMR window. |
| Show First VTC Volume Function In VMR View Menu | To make it possible to quickly access the 'Show First VTC Volume' function that can be called using the 'Show VTC Vol' button in the 'Spatial Transf' tab of the '3D Volume Tools' dialog, this functino has been added to the VMR View context menu that can be invoked by right-clicking inside the VMR window. |
| JS Script Commands | For GUI scripts and GUI plugins, new functions have been added to the 'bv' ('BrainVoyager') script object that allow to set the minimum and maximum size of a GUI dialog: 'SetMinimumSizeOfPluginWindow(int widht, int height)', 'SetMaximumSizeOfPluginWindow(int widht, int height)', 'SetMinimumSizeOfGUIScriptWindow(int width, int height)' and 'SetMaximumSizeOfGUIScriptWindow(int width, int height)'. While it is usually not necessary to restrict the maximum size of a dialog window, it is useful to set a minimum size to prevent that a window can be made so small that user interface elements are hidden from view. It is advised to call these functions in the 'Component.onCompleted' function of the dialog (see provided examples in the 'Scripts' and 'Plugins' folders for detail). Furthermore, the 'MessageBox()' function obtained an optional second parameter for a 'detailed message' string (next to the main message string provided in the first parameter). Also the possibility to provide a 'Yes / No' dialog has been added with the new 'YesNoMessageBox()' function, which accepts the same parameters as the message box and shows a 'Yes' and a 'No' button. If the user presses the 'Yes' button, the function returns 'true', otherwise 'false'. The 'document' object obtained the new commands 'ShowVOIsDialog()' and 'HideVOIsDialog()' as well as the 'GetBetaTValueOfROIGLM()' and 'GetBetaPValueOfROIGLM()' functions accepting the index of a fitted beta value as input (these functiosn are defined for the Pyhton interface but were missing for JS scripts). |
Bug Fixes |
|---|
| Iso-Voxelation on macOS | Iso-voxelation using Metal shaders on devices with Apple Silicon and Intel chips did not work in the previous release (had been fixed for Apple Silicon in patch release 23.0.9). This issue has been fixed. |
| Average VTC Volumes | The option 'Average VTC Over Time And Convert To VMR' in the 'Options' menu can be used to average all volumes of a VTC to create a VMR (and V16) file. This function resulted in empty files in version 22.4 and 23.0.8. This issue has been fixed. |
| Create VTC On Apple Using 'Metal' Compute | Sometimes a crash happened when running the 'create_vtc' Python or 'CreateVTC' JS script function (but also when using the user interface) for large datasets. This has been solved by optimising Metal compute shader code, which now reuses once allocated Metal volume buffers for each volume of a sequence. The improvement has been also applied to FMR motion correction to ensure fast and robust performance. |
| VOI RFX GLM | When running RFX GLMs for volume regions of interest (VOIs) with (dummy-coded) runs containing predictors with only 0 values in the design matrix, the program crashed. This issue has been fixed. |
| Automatic Cortex Segmentation For BBR | When running the 'Automatic Cortex Segmentation for BBR' function via script or the user interface, the function sometimes returned without running the cortex (WM) segmentation and cortex mesh reconstruction. This issue was caused by a sub-optimal contrast / brightness setting. This issue is now solved by internally calling the 'Set to standard GM/WM' function described above under 'Enhancements'. |
| Coregistration Using BBR Script Function | When calling the Python script function 'coregister_fmr_to_vmr_using_bbr' (or the equivalent JS function), the .VOI with the GM boundary before and after the alignment was not created and saved as in the GUI version. This issue has been fixed. |
| Automatic Creation of Project Folders | In some cases the automatic creation of a 'rawdata' folder did not work correctly (there could be a nested chain of 'rawdata' and 'sourcedata' folders). This issue has been fixed. |
| LoadVOIFile Script Function | The 'LoadVOIFile()' JS script function did not work in previous 23.x versions. This issue has been fixed. |
| Windows - No Fibers Visualized in Line Mode | When visualizing fiber tracts and tensor lines, nothing was shown on Windows in previous 23.x veresions. Only if 'tube' rendering mode was used, fiber tracts could be visualized. This issue with visualizing lines on Windows has been fixed in this release. |
| Interactive Fiber Tracking | Interactive fiber tracking did not work in previous versions. In the current version 'CTRL-click' on a brain slice does still not work but it is now possible via the context menu of the VMR View. After invoking the context menu (usually via right-clicking) at a voxel of a VMR slice, one can select the "Track fibers from cross position" option to launch fiber tracking from the selected voxel. One can then switch to the associated 'Brain Viewer' window to se the tracked slices. It is recommended to 'tile' the VMR and Brain Viewer window next to each other to see both the slice(s) and the tract fibers. |
| Open Pure VTC - TR Value | When using the 'Open Pure VTC' function from the 'File' menu, invoked time course plots die not show a linked protocol correctly since the VTC TR value was not provided correctly to the 'Time Course Plot' window. This issue has been fixed. |
| Saving FMR Files | When saving FMR files, a small change had been introduced in 23.0, namely to use the strings 'NrOfColumns' and 'NrOfRows' instead of 'ResolutionX' and 'ResolutionY'. This led, however, to issues in some programs that read FMR files, and this change has been reverted. It is planned to introduce the renaming with the next version update of FMR files. |