| Integrated EPI Distortion Correctiont | EPI distortions can be corrected in BrainVoyager using the opposite phase encoding approach by using the COPE plugin. This method is especially useful when using 7T+ datasets. EPI distortion correction using opposite phase encoding was, however, not integrated in the 'Preprocessing' dialog and it was not part of the scripting API. This release integrates EPI distortion correction using opposite phase necoding directly in the user interface and provides commands for scripting (see below). In the user interface, the new dialog 'Estimate EPI Distortions' has been added, which allows to calculate voxel displacement maps (VDMs) from two provided functional runs with opposite phase encoding. One run is usually the experimental run and the other one is recorded explicity for the purpose of EPI distortion correction and, thus, usually contains only a few volumes. The calculated VDM map file for the experimental run can then be selected in the enhanced 'FMR Preprocessing' dialog when preprocessing the respective run. For details, see topic 'EPI Distortion Correction' in chapter 'Preprocessing of Functional Data' in the Users Guide, and also the new "Layer fMRI Tutorial". Note also that the COPE plugin remains available providing additional capabilities such as batch processing. Also note that for field map based correction of geometric distortions, the 'anatabacus' plugin can be used. |
| Masking FMRs | It is now possible to apply a spatial mask to restrict motion correction to a subset of voxels specified by a region-of-interest (.roi) file.A ROI (mask) file can be created especially easily from SLICES-space VOI files (see below). The ROI masking possibility is available for both the new across-run motion preparation step as well as for running motion correction for within-run volumes in the 'Preprocessing' dialog. More generally, voxels outside an ROI mask file can now be set to 0.0 (removing those voxels from most processing steps) by using the 'Apply ROI-Mask to FMR-STC Time Series' item in the 'Options' menu. |
| Python Support | The Python API has been updated. For the new across-run motion correction approach, the command prepare_across_run_moco(session_runs, ref_vol=0) of the BrainVoyager object ('bv.') can be used with one required parameter containing a list of ordered run files (first one: target run) and an optional parameter specifying a reference volume (default: '0'). The command produces .SDM files containig the motion parameters that bring the reference volume of a run (e.g. run-04) to the reference volume of the target run (e.g. run-01). When preprocessing individual runs (usually as part of a preprocessing pipeline), the document command correct_motion_to_run_trf(ref_vol, to_run_trf_sdm_file) can be used to perform the actual motion correction for all volumes of the respective functional document; the command has two parameters, the first indicates the reference volume (e.g. '0') and the second the relevant spatial transformation (.SDM) file produced by the 'prepare_across_run_moco()' command. The integrated COPE distortion correction can be scripted via two commands. The first, estimate_epi_distortion(ap_file, pa_file) estimates the EPI distortion for two runs with opposite phase encoding. Additional optional parameters can be provided; the 'phase_enc_lr' parameter (default: False) specifies whether phase encoding is in the left-right axis instead of the anterior-posterior axis; the 'ap_use_vol' (default: 0) and 'pa_use_vol' (default: 0) parameters specify the volume in the two provided files that should be used for distortion correction; the string parameters 'out_ap_vdm_file'(default: "") and 'out_pa_vdm_file' (default: "") can be used to provide explicit names for the produced voxel displacement map files - in case the output file names are not provided (default), they are generated automatically. During preprocessing, an experimental run can be distortion corrected using the document command correct_epi_distortion(vdm_file) with one parameter specifying the generated voxel displacement map for that run. For details of the new commands, see the Python developer guide and the BV notebook "Layer-fMRI-Imagery-Tutorial.bvnb". |
| JavaScript Support | The new commands described for the Python API (see above) have also been added to the JavaScript API. Across-run motion preparation can be launched by the BrainVoyager object function PrepareAcrossRunMoco(SsessionRuns, RrefVol). The actual motion correction of a source run to a target run can be performed using the document method CorrectMotionToRunTrf(RefVol, ToRunTrfSDMFile). For the estimation of EPI distortions for two runs with opposite phase encoding, the method EstimateEpiDistortion(APFile, PAFile) is available with the optional parameters 'PhaseEncLR' (default: false), 'APUseVol' (default: 0), 'PAUseVol' (default: 0), 'OutAPVDMFile'(default: "") and 'OutPAVDMFile' (default: ""). During preprocessing, an experimental run can be distortion corrected using the document method CorrectEpiDistortion(VDMFile) with one parameter specifying the generated voxel displacement map for that run. |
| DNN Segmentaion Postprocessing | Following DNN-based segmentation, the tissue labels are further processed using a postprocessing pipeline that is available using the 'DNN Segmentation Postprocessing' dialog. The pipeline has been improved in various ways producing high-quality output that can be directly used for mesoscale data analysis. First, it is now assured that VOI labels are exclusively defined so that they can be used for Label drawing (see above), i.e. tissue labels that overlapped (e.g. original and processed labels) are no longer botth kept in the VOI list. Also the order of tissue labels is kept constant throughout the processing steps. There is also a new step 'Fill Holes' that fills voxels of small unlabelled regions with tissue labels from the voxel neighborhood. For more details, see topic 'Postprocessing of DNN Segmentation Results' in the sub-chapter 'Deep Neural Network Segmentation' inside the 'Brain and Cortex Segmentation' chapter of the User's Guide. |
| Create Func from 3D NIfTI | BrainVoyager only creates FMR or VTC files when loading a 4D NIfTI file. Sometimes a single functional volume is stored as a 3D NIfTI file (e.g., an 'SBref' volume. To enable loading such files as functional data with a single volume, the new '' item in the 'File' menu can be used. |
| Create Sub-Meshes from POIs | It is now possible to create a sub-mesh of a mesh for the subset of vertices defined by a POI. This function is useful to divide a mesh in sub-parts or to remove mesh parts. The function can be inovked by clicking the 'Create' button in the new 'POIs - Meshes' field in the 'POI Functions' tab of the 'POI Analysis Options' dialog. |
| Enhanced VMR and VMP TRF Dialogs | Updated dialogs. The VMR dialog to scale the voxel resolution has been improved, also renamed from "Iso-Voxelation" to "Scale" in '3D Volume Tools' dialog. Also general TRF dialog improvements.. Easier to apply spatial TRFs, including scales, to VMPs... target dims calculated, no longer restricted to 'framing cube dimensions'. For details see User's Guide and "Layer-fMRI Analysis Tutorial". |
| SLICES Space VOIs to ROIs | The functionality to convert VOIs into ROIs (used in FMR and DMR documents) has been extended to VOIs in 'SLICES' space. This function can be useful to convert masks defined in a volume (VMR) into FMR space, e.g., to be used for masked motion correction or general FMR/DMR masking (see above). |
| Saving, Loading, Deleting DICOM POS Info | The 'Scan Positioning Information' dialog (available via the 'POS Info' button in the 'VMR Properties' dialog) now provides the possibility to save or load DICOM-based position information. This can be useful to copy such information from one VMR to another one, which might not have that information. It is also possible to remove DICOM position information, which is recommended when exporting VMRs as NIfTI files for further (segmentation) editing (see next point). |
| Native-Space VMR To NIfTI | Saving native-space VMRs containing scanner-space DICOM information was not allowed in previous versions in case that additional spatial transformations had been performed after creating the volume from DICOM files. It is now possible to save any native space VMR to NIfTI. In case that no DICOM / NIfTI scanner space information is available in the VMR header or if additional spatial transformations (except scales) have been performed, the program now saves the NIfTI file with a simple orthographic orientation matrix to disk. While this matrix does not contain original scanner information, the saved NIfTI files can be used for exchange with other software such as ITK-Snap that will recognize the provided orientation information. The contents of those NIfTI files can then be modified and saved by external software and then loaded back into BrainVoyager. For exchange with external software, it is recommended to remove the DICOM position information (see point above). For further details, see the 'Label Drawing' topic in the 'Brain and Cortex Segmentation' chapter of the User's Guide. |
| Save VOIs as Label Volume | The 'Volumes-Of-Interest' dialog now has a 'Save Vol' button that saves visualized (selected) VOIs in a NIfTI (or VMR/V16) 'label volume'. The first (top most) VOI in the 'VOIs list' will get label (intensity value) '1' in the saved volume, the second VOI will get label '2' and so on. Note that if VOIs overlap, the VOIs appearing further down in the list have precedence, i.e. VOIs are drawin into the volume from top to bottom. The appearing 'Save File' dialog provides a file type selection option to save the VOI volume either as a NIfTI file (default) or as a VMR/V16 file. The stored NIfTI file can be used as segmentation overlays for further editing in other software such as 'ITK-Snap'. Note that a similar function was (and is) available in the 'VOI - VMR values' field of the 'VOI Functions' tab of the 'VOI Analysis Options' dialog, but the new 'Save Vol' button allows access to this functionality more quickly and directly, especially if one wants to save the volume as a NIfTI file. Furthermore, it removes any DICOM information from the VMR file if available (see also point above). For more details, see the 'Label Drawing' topic in the 'Brain and Cortex Segmentation' chapter of the User's Guide. |
| Import Label Volume into VOIs | The 'Volumes-Of-Interest' dialog now has a 'Import Vol' button that imports a label volume - edited outside BV - back into the original VOIs from either as a NIfTI file (default) or as a VMR/V16 file. Note that the import function for label volumes does not change the label names and colors already defined for the loaded VOIs in BrainVoyager. The import routine only updates the list of voxels belonging to the existing VOIs from the imported label volume. Note that there is also a more general approach available to convert a label volume into VOIs via the 'Convert VMR / V16 Label Values to VOIs' dialg that can be invoked from the 'Volumes' menu. For more details, see the 'Label Drawing' topic in the 'Brain and Cortex Segmentation' chapter of the User's Guide. |
| Improved VMR Editing | When using the 'old' approach drawing directly 'in' a VMR using the 'Zoom View', the current volume is automatically loaded into the 3rd VMR buffer as a backup. Besides drawing in a specified color and deleting to 'black' (intensity '0'), the new key combination Shift + CMD (macOS) / Shift + CTRL (Windows, Linux) will draw using the voxel intensities in the backup buffer when clicking on voxels with the mouse. This drawing mode can be used, for example, to recover voxel intensities that have been erroneously drawn with the current pen color. This provides a useful means to directly correct edits without the need to go through the "Undo" buffer. This possibility is also available when directly drawing in the VMR View (not the 'Zoom View') but when using the VMR View directly for drawing, the current volume needs to be manually loaded in the 3rd VMR buffer by using the 'Load Tertiary VMR' item in the sub-menu 'Secondary, Tertiary VMR' of the 'File' menu. For details about this 'backbuffer' drawing functionality, see topic 'Direct Volume Drawing' in the 'Brain and Cortex Segmentation' chapter of the User's Guide. |
| Rescale Voxel Time Series | The new 'Scale Time Series Values' dialog can be used to rescale the time series of functional (FMR) documents. It can be invoked using the 'Rescale FMR-STC Time Series' item in the 'Options' menu. This functionality is useful in case the range of functional files needs to be changed. Using the scale value '-1.0', it can also be used to flip positive and negative values which may be helpful for calculated VASO time course data. |
| Create-VTC Target Voxel Size | When creating VTC files using the 'Create VTC' dialog, the resolution of the target anatomy is assumed to be the one of the hosting VMR. The new 'Resolution of target anatomy' input field in the 'Create VTC Options' dialog allows to adjust the voxel size of the target VMR if needed, e.g., when going to a target space using a TRF matrix that combines several transformations, e.g. first a voxel rescale operation followed by a MNI transformation. Such a combined TRF matrix can be added by selecting a (pseudo) 'To ACPC' transformaton and then selecting the respective TRF file in the 'ACPC' input field. |
| Plotting Map Values Across VOIs | Using the new 'Plot' button in the 'VOIs with Map Values' dialog one can now create plots of map values across VOIs. The table in the dialog shows VOIs in rows and different maps in columns for each of which a different plot line will be shown (if filled with data). This quick plot functionality is, for example, useful in the context of layer-fMRI analysis to plot effect sizes (e.g. t values) across VOIs representing different layer compartments. The dialog can be invoked by clicking the 'Table' button in the 'VOIs with map values' field in the 'VOI Functions' tab of the 'VOI Analysis Options' dialog. For details, see the 'xx' tutorial. |
| Display FMRs/MAPs Y-Flipped | The 'Layout and Display Options' dialog (available via the 'Layout and Display Options' item in the 'Options' menu) has a new 'Flip y axis (display only)' option that flips the y axis of FMR / DMR documents upside down, as well as any overlaid maps and time course regions-of-interest. This functionality might be useful when displaying FMR files that appear flipped such as when loading some externally converted NIfTI files (FMR / DMR files draw slices as found in the NIfTI file without applying a spatial transformation). The y-axis flip is only a display option, i.e. the data is not modified when using this option. |
| DNN Segmentation Input Voxel Size | When the voxel size of a MP(2)RAGE anatomical dataset was not exactly 0.7, the program proceeded only when rescaling it to 0.7 iso-voxels. This has been slightly relaxed, i.e. if the input resolution deviates from 0.7 within a range of 0.05 mm, the program now presents a new dialog that suggests to keep the current resolution - but also offers the possibility to rescale the voxel size to 0.7 mm. |
| Voxel Beta Plot in Light Theme | The 'Voxel Beta Plot' now supports also light mode with a white background and automatically adjusted colors for other items in the dialog. The light mode can be turned on by checking the 'White background' option in the 'Chart Options' dialog, which can be invoked by clciking inside the 'Voxel Beta Plot'. In the same way one can turn on the 'Dark background' option. Since the colors of betas might change when switching the appearance mode the first time, it is currently advised to close the 'Voxel Beta Plot' and reopen it after switching theme appearance mode. |
| VOI from VMR Drawing via Context Menu | When drawing in a VMR (with a 'blue' color (value: 240) as default), one can convert the drawing into a VOI directly from the context menu without the need to go via the '3D Volume Tools' dialog. With the introduced 'Label drawing' in this release, a better way is to directly draw in a (created) VOI label. |
| Labels in FFT Plots | As default FFT Plots show text labels for the top-5 frequencies with the highest magnitude values. While this option is useful, it might sometimes clutter the plot. The labels can now be turned on or off using the 'Show' option in the 'Labels for top freqs in FFT plots' field in the 'Options' tab of the 'Settings' dialog. For more informatoin, consult topic 'Finding Optimal High-Pass Filter Values' in the 'Preprocessing of Functional Data' chapter of the User's Guide. |