BrainVoyager Python Developer Guide 0.9

VMR-VTC Commands

VMR document objects expose specific commands to handle e.g. preprocessing and spatial transformations. Here commands related to the creation and access of volume time course (VTC) files are described.

link_vtc(str vtc_file) → bool

Description: Links the specified volume time course (VTC) file to the hosting VMR (DocPyBV) document object. The boolean value indicates whether the VTC file could be linked successfully or not.
vtc_file (str): String specifying the name of the input volume time course (VTC) file, which will be linked to the VMR document object. The string should contain the full path file name.

save_vtc(str vtc_file) → bool

Description: Saves the current VTC data associated with the VMR (DocPyBV) document object to disk using the specified file name.
vtc_file (str): String specifying the name of the input volume time course (VTC) file, which will be linked to the VMR document object. Besides a full path file name, relative paths with respect to the hosting VMR location (or notebook location if used inside a BV notebook) can be used.

coregister_fmr_to_vmr(str fmr_file, bool iihc_func=False, int use_attached_amr=False) → bool

Description: Calculates transformation matrices to coregister the specified FMR with the 3D anatomical data of the calling VMR document object. The procedure uses alignment information from the headers of (DICOM) images as well as an iterative intensity gradient-based matching procedure. The boolean return value indicates whether the command could be executed successfully. As default, the command uses the first functional volume of the FMR dataset (recommended) but also a volume in an attached AMR file can be used (see use_attached_amr parameter). The functional volume is aligned to the volume data of the hosting VMR to calculate two transformation matrices, a header-based initial alignment (IA) TRF file and a matching-based fine-tuning adjustment (FA) TRF file. The two generated files can be used subsequently to actually transform all volumes of the FMR-STC data in the space of the hosting VMR; the calculation of coregistration files is separated from the actuall application since it is usually desired to transform the FMR-STC data into a normalized space beyond the space of the hosting VMR (see VTC creation commands below). In case that the optional iihc_func parameter is 'True', the functional volume is corrected for intensity inhomogeneities before calculation the iterative (fine-tuning) alignment matrix.
fmr_file (str): String specifying the name of the input functional FMR file, which will be coregistered to the hosting 3D anatomical VMR document. The string may contain the full path file name or a path relative to the hosting VMR (or notebook location if used inside a BV notebook). Besides using the (first) functional volume (default, use_attached_amr: False), a AMR volume attached to the FMR can be used the FMR that will be used to calculate the IA and FA coregistration matrices is determined by the useAttachedAMR parameter.
iihc_func (bool): Optional. Boolean parameter specifying whether the functional volume used for calculating the fine-tuning alignment transformation matrix is corrected for spatial intensity inhomogeneities (True) or not (False, default). This parameter should be set to True if the functional dataset exhibits intensity inhomogeneities (such as ithe functional data of the experiment described in BV's Getting Started Guide).
use_attached_amr (int): Optional. Boolean specifying whether the original FMR volume should be used (value: 0) or whether the volume in an attached AMR should be used as input (value: 1, recommended). If requested but no AMR is available, the first FMR volume will be used instead. The linked AMR is usually only a resampled (higher resolution) version of the first volume of the original functional data (thus also called a "pseudo" AMR). Using the linked (pseduo) AMR is recommended since this volume will not be modified by FMR preprocessing operations such as spatial smoothing (it will also be properly modified in case of across-run motion correction). In case that the linked AMR is a true T1 weighted anatomical coplanar set of slices from an extra scan, a value of 2 should be used for this parameter, which will not invert voxel intensiities, which is otherwise performed to match the functional data volume to the anatomical VMR data volume.

coregister_fmr_to_vmr_using_bbr(str fmr_file) → bool

Description: Calculates transformation matrices to coregister the specified FMR with the 3D anatomical data of the calling VMR document object. The procedure uses alignment information from the headers of (DICOM) images as well as an iterative boundary-based registration (BBR) matching procedure. The Boolean return value indicates whether the command could be executed successfully. This BBR-based version of the FMR-VMR coregistration command takes more calculation time than the "coregister_fmr_to_vmr" command (see above) since several intermediate calculations have to be performed, including a whilte-grey matter segmentation, reconstruction and smoothing of a white-grey matter mesh; if the mesh for the VMR document is already available (from a previous run), the segmentation and mesh processing steps are skipped and only the BBR algorithm is performed. The command uses the first volume of the FMR data, which is aligned to the volume data of the hosting VMR to calculate two transformation matrices, a header-based initial alignment (IA) TRF file and a BBR-based fine-tuning adjustment (BBR_FA) TRF file. The two generated files can be used subsequently to actually transform all volumes of the FMR-STC data in the space of the hosting VMR; the calculation of coregistration files is separated from the actuall application since it is usually desired to transform the FMR-STC data into a normalized space beyond the space of the hosting VMR (see VTC creation commands below).
fmr_file (str): String specifying the name of the input FMR file, which will be coregistered to the hosting VMR. Besides using a full path file name, a path relative to the hosting VMR document's location on disk can be used.

create_vtc_in_native_space(str fmr_file, str coreg_ia_trf_file, str coreg_fa_trf_file, str vtc_file, int res_to_anat, int interpolation_method, int bounding_box_intensity_threshold=100, int data_type=2) → bool

Description: Transforms the specified FMR-STC data into the space of the calling VMR document producing a VTC file as output. The boolean return value indicates whether the command could be executed successfully. The calling VMR document object should be the same that was used for coregistration of the source FMR file with the calling VMR document object. The IA and FA transformation files will be combined into one transformation matrix. The resulting resolution will be determined by the spatial resolution (millimeters) of the calling VMR document object but it can be reduced by an integral value using the resolution parameter. The bounding box of the resulting VTC data is determined by the intensity threshold parameter but can also be set explicity to desired values using the "TargetVTCBoundingBoxXYZStartEnd" property values.
fmr_file (str): String specifying the name of the source FMR file; the voxel time course data in the STC file that is referenced by the FMR file will be used as input of the VTC creation process.
coreg_ia_trf_file (str): String specifying the name of the initial alignment (IA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
coreg_fa_trf_file (str): String specifying the name of the fine-tuning adjustment (FA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
vtc_file (str): String specifying the name of the resulting volume time course (VTC) file in the space of the hosting VMR document. Specification of a full path file name is recommended and required if the resulting file should be stored in another directory than the one of the FMR input file.
res_to_anat (int): Integer in the range [1, 3] specifying the spatial resolution of the voxels of the resulting VTC data relative to the resolution of the calling VMR document object. A value of "1" indicates that the resolution of the VTC data will be the same as the resolution of the hosting VMR, value "2" indicates that 1 VTC voxel will correspond to 2 * 2 * 2 (8) VMR voxels and value "3" indicates that 1 VTC voxel will correspond to 3 * 3 * 3 (27) VMR voxels.
interpolation_method (int): Integer in the range [0, 2] specifying the interpolation method used for resampling the STC input data. Providing value "0" will select nearest neighbor interpolation, value "1" trilinear interpolation and value "2" will select sinc interpolation. Sinc interpolation will be very slow if no GPU is available and enabled for sinc interpolation.
bounding_box_intensity_threshold (int): Optional. A value that is used to separate background voxels (low intensity) from brain voxels (high intensity); voxels passing the threshold will determine the bounding box used to store the resulting VTC data. If not changed, the default value of "100" is used (recommended), which is usually appropriate in case that the FMR-STC input data reflect originally scaned MRI data after standard preprocessing. If the data has been processed in some non-standard way (e.g. z normalized), the intensity threshold value should be set to 0, which will however lead to a large VTC bounding box (if not restricted).
data_ype (int): Optional. Integer in the range [1, 2] specifying the data type for the values in the resulting VTC output file; value "1" will produce integer values (2 byte), value "2" (default, recommended) will produce float32 (4 byte float) values.

create_vtc_in_acpc_space(str fmr_file, str coreg_ia_trf_file, str coreg_fa_trf_file, str acpc_trf_file, str vtc_file, int res_to_anat, int interpolation_method, int bounding_box_intensity_threshold=100, int data_type=2) → bool

Description: Transforms the specified FMR-STC data into ACPC space producing a VTC file as output. The boolean return value indicates whether the command could be executed successfully. The calling VMR document object should be the same that was used for coregistration of the source FMR file with the calling VMR document object and the ACPC transformation file should be the one resulting from transforming the hosting VMR into ACPC space. The IA, FA and ACPC transformation files will be combined into one transformation matrix. The resulting resolution will be determined by the spatial resolution (millimeters) of the calling VMR document object but it can be reduced by an integral value using the resolution parameter. The bounding box of the resulting VTC data is determined by the intensity threshold parameter but can also be set explicity to desired values using the "TargetVTCBoundingBoxXYZStartEnd" property values.
fmr_file (str): String specifying the name of the source FMR file; the voxel time course data in the STC file that is referenced by the FMR file will be used as input of the VTC creation process.
coreg_ia_trf_file (str): String specifying the name of the initial alignment (IA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
coreg_fa_trf_file (str): String specifying the name of the fine-tuning adjustment (FA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
acpc_trf_file (str): String specifying the name of the ACPC transformation (TRF) file resulting from previously transforming the hosting VMR document into ACPC space.
vtc_file (str): String specifying the name of the resulting volume time course (VTC) file in ACPC space. Specification of a full path file name is recommended and required if the resulting file should be stored in another directory than the one of the FMR input file.
res_to_anat (int): Integer in the range [1, 3] specifying the spatial resolution of the voxels of the resulting VTC data relative to the resolution of the calling VMR document object. A value of "1" indicates that the resolution of the VTC data will be the same as the resolution of the hosting VMR, value "2" indicates that 1 VTC voxel will correspond to 2 * 2 * 2 (8) VMR voxels and value "3" indicates that 1 VTC voxel will correspond to 3 * 3 * 3 (27) VMR voxels.
interpolation_method (int): Integer in the range [0, 2] specifying the interpolation method used for resampling the STC input data. Providing value "0" will select nearest neighbor interpolation, value "1" trilinear interpolation and value "2" will select sinc interpolation. Sinc interpolation will be very slow if no GPU is available and enabled for sinc interpolation.
bounding_box_intensity_threshold (int): Optional. A value that is used to separate background voxels (low intensity) from brain voxels (high intensity); voxels passing the threshold will determine the bounding box used to store the resulting VTC data. If not changed, the default value of "100" is used (recommended), which is usually appropriate in case that the FMR-STC input data reflect originally scaned MRI data after standard preprocessing. If the data has been processed in some non-standard way (e.g. z normalized), the intensity threshold value should be set to 0, which will however lead to a large VTC bounding box (if not restricted).
data_ype (int): Optional. Integer in the range [1, 2] specifying the data type for the values in the resulting VTC output file; value "1" will produce integer values (2 byte), value "2" (default, recommended) will produce float32 (4 byte float) values.

create_vtc_in_tal_space(str fmr_file, str coreg_ia_trf_file, str coreg_fa_trf_file, str acpc_trf_file, str tal_file, str vtc_file, int res_to_anat, int interpolation_method, int bounding_box_intensity_threshold=100, int data_type=2) → bool

Description: Transforms the specified FMR-STC data into ACPC space producing a VTC file as output. The boolean return value indicates whether the command could be executed successfully. The calling VMR document object should be the same that was used for coregistration of the source FMR file with the calling VMR document object and the ACPC transformation file should be the one resulting from transforming the hosting VMR into ACPC space. The IA, FA and ACPC transformation files will be combined into one transformation matrix. The resulting resolution will be determined by the spatial resolution (millimeters) of the calling VMR document object but it can be reduced by an integral value using the resolution parameter.
fmr_file (str): String specifying the name of the source FMR file; the voxel time course data in the STC file that is referenced by the FMR file will be used as input of the VTC creation process.
coreg_ia_trf_file (str): String specifying the name of the initial alignment (IA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
coreg_fa_trf_file (str): String specifying the name of the fine-tuning adjustment (FA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
acpc_trf_file (str): String specifying the name of the ACPC transformation (TRF) file resulting from previously transforming the hosting VMR document into ACPC space.
tal_file (str): String specifying the name of the TAL file (with AC, PC and cerebrum fiducials) resulting from previously transforming the hosting VMR document into Talairach space.
vtc_file (str): String specifying the name of the resulting volume time course (VTC) file in ACPC space. Specification of a full path file name is recommended and required if the resulting file should be stored in another directory than the one of the FMR input file.
res_to_anat (int): Integer in the range [1, 3] specifying the spatial resolution of the voxels of the resulting VTC data relative to the resolution of the calling VMR document object. A value of "1" indicates that the resolution of the VTC data will be the same as the resolution of the hosting VMR, value "2" indicates that 1 VTC voxel will correspond to 2 * 2 * 2 (8) VMR voxels and value "3" indicates that 1 VTC voxel will correspond to 3 * 3 * 3 (27) VMR voxels.
interpolation_method (int): Integer in the range [0, 2] specifying the interpolation method used for resampling the STC input data. Providing value "0" will select nearest neighbor interpolation, value "1" trilinear interpolation and value "2" will select sinc interpolation. Sinc interpolation will be very slow if no GPU is available and enabled for sinc interpolation.
bounding_box_intensity_threshold (int): Optional. A value that is used to separate background voxels (low intensity) from brain voxels (high intensity); voxels passing the threshold will determine the bounding box used to store the resulting VTC data. If not changed, the default value of "100" is used (recommended), which is usually appropriate in case that the FMR-STC input data reflect originally scaned MRI data after standard preprocessing. If the data has been processed in some non-standard way (e.g. z normalized), the intensity threshold value should be set to 0, which will however lead to a large VTC bounding box (if not restricted).
data_ype (int): Optional. Integer in the range [1, 2] specifying the data type for the values in the resulting VTC output file; value "1" will produce integer values (2 byte), value "2" (default, recommended) will produce float32 (4 byte float) values.

create_vtc_in_mni_space(str fmr_file, str coreg_ia_trf_file, str coreg_fa_trf_file, str mni_trf_file, str vtc_file, int res_to_anat, int interpolation_method, int bounding_box_intensity_threshold=100, int data_type=2) → bool

Description: Transforms the FMR-STC data specified by the fmr_file parameter into MNI space producing a VTC file as output. The boolean return value indicates whether the command could be executed successfully. The calling VMR document object should be the same that was used for coregistration of the source FMR file with the calling VMR document object and the MNI transformation file should be the one resulting from transforming the hosting VMR into MNI space. The IA, FA and MNI transformation files will be combined into one transformation matrix. The resulting resolution will be usually 1 mm iso-voxel in MNI space but it can be reduced by an integral value using the res_to_anat parameter (typically set to 2 or 3).
fmr_file (str): String specifying the name of the source FMR file; the voxel time course data in the STC file that is referenced by the FMR file will be used as input of the VTC creation process.
coreg_ia_trf_file (str): String specifying the name of the initial alignment (IA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
coreg_fa_trf_file (str): String specifying the name of the fine-tuning adjustment (FA) transformation (TRF) file resulting from the preparatory FMR-VMR alignment step. Specification of a full path file name is recommended and required if the TRF file is not located in the same directory as the FMR input file.
mni_trf_file (str): String specifying the name of the ACPC transformation (TRF) file resulting from previously transforming the hosting VMR document into ACPC space.
vtc_file (str): String specifying the name of the resulting volume time course (VTC) file in MNI space. Specification of a full path file name is recommended and required if the resulting file should be stored in another directory than the one of the FMR input file.
res_to_anat (int): Integer in the range [1, 3] specifying the spatial resolution of the voxels of the resulting VTC data relative to the resolution of the resulting MNI space (usually 1 mm). A value of "1" indicates that the resolution of the VTC data will be the same as the target VMR resolution, value "2" indicates that 1 VTC voxel will correspond to 2 * 2 * 2 (8) VMR voxels and value "3" indicates that 1 VTC voxel will correspond to 3 * 3 * 3 (27) VMR voxels.
interpolation_method (int): Integer in the range [0, 2] specifying the interpolation method used for resampling the STC input data. Providing value "0" will select nearest neighbor interpolation, value "1" trilinear interpolation and value "2" will select sinc interpolation. Sinc interpolation will be very slow if no GPU is available and enabled for sinc interpolation.
bounding_box_intensity_threshold (int): Optional. A value that is used to separate background voxels (low intensity) from brain voxels (high intensity); voxels passing the threshold will determine the bounding box used to store the resulting VTC data. If not changed, the default value of "100" is used (recommended), which is usually appropriate in case that the FMR-STC input data reflect originally scaned MRI data after standard preprocessing. If the data has been processed in some non-standard way (e.g. z normalized), the intensity threshold value should be set to 0, which will however lead to a large VTC bounding box (if not restricted).
data_ype (int): Optional. Integer in the range [1, 2] specifying the data type for the values in the resulting VTC output file; value "1" will produce integer values (2 byte), value "2" (default, recommended) will produce float32 (4 byte float) values.