BrainVoyager Python Developer Guide 0.9

FMR Document Commands

FMR documents use commands related to (pre-)processing functional data in original slice-based (STC) data sets. A common scripting application is to automatize important preprocessing steps. Note that some commands described below for FMR-STC documents can also be used for VMR documents in case that the VMR coument contains a link to a volume time course (VTC) data set.

link_protocol(str protocol_file) → bool

Description: Links the provided protocol file to the calling FMR document. If the file can not be linked, the command returns False, otherwise True. To keep the link permanently, the FMR file needs to be saved to disk (e.g. using the document object's Save command). Also applicable for VMR-VTC documents.
protocol_file (str): String specifying the name of the protocol that will be linked to the calling FMR docuemt. In case that not a full file path (folder plus file name) is provIded, the document is stored in the current directory.

link_amr(str amr_file) → bool

Description: Links the provided AMR file to the calling FMR document. The AMR will be used as background to show the slices and map overlays and should thus be in the same space than the original FMR slices; the slice dimensions can be higher than the original FMR slices (the pseudo-AMR is, for example, an upsampled version of original FMR slices from T1 saturated (extra) images, if available). If the file can not be linked, the command returns False, otherwise True. To keep the link permanently, the FMR file needs to be saved to disk (e.g. using the document object's Save command)
AMRFileName (str): String specifying the name of the AMR file that will be linked to the calling FMR docuemt. In case that not a full file path (folder plus file name) is provIded, the document is stored in the current directory.

correct_slicetiming(int slice_order_scheme, int interpolation_method, int multiband_factor) → bool

Description: Resamples the attached slice time course (STC) data of the calling FMR document in order to adjust time differences between individually scanned slices. The boolean return value indicates whether the operation could be run successfully.
slice_order_scheme (int): Integer specifying the order in which slices were scanned (0 -> ascending, 1 -> ascending-interleaved, 2 -> ascending-Interleaved, 10 -> descending, 11 -> descending-interleaved, 12 -> descending-interleaved2).
interpolation_method (int): Integer specifying the method used for interpolation of voxel time courses. A value of 0 selects linear interpolation, a value of 1 (recommended) selects cubic spline interpolation and a value of 2 selects sinc interpolation.
multiband_factor (int): Integer specifying how many slices were simultaneously excited as a "band" at the same time. Value 1 (or smaller) indicates that now simultaneous multi-slice sequence has been used.

correct_slicetiming_using_timingtable(int interpolation_method) → bool

Description: Resamples the attached slice time course (STC) data of the calling FMR document iin order to adjust time differences between individually scanned slices. The boolean return value indicates whether the operation could be run successfully. This command is preferred over the standard "CorrectSliceTiming" function (see above) since it handles single and multi-band data without the need to specify slice order information, but it only works in case that a slice time table could be retrieved from the raw data, which is currently only supported for recent Siemens DICOM mosaic files. To test whether this command can be applied, use the "HasSliceTimeTable" document property.
interpolation_method (int): Integer specifying the method used for interpolation of voxel time courses. A value of 0 selects linear interpolation, a value of 1 (recommended) selects cubic spline interpolation and a value of 2 selects sinc interpolation.

correct_slicetiming_using_sliceorder(str slice_list, int interpolation_method, int multiband_factor) → bool

Description: Resamples the attached slice time course (STC) data of the calling FMR document in order to adjust time differences between individually scanned slices. The boolean return value indicates whether the operation could be run successfully.
slice_list (str): String specifying a blank separated list of slices in the order as they were scanned If the "multiband_factor" parameter "nm" has a value larger 1, packets of nm slices are assumed to be scanned at the same time; slice numbers are 1-based, e.g. the string "1 2 3.." would indicate an ascending slice order.
interpolation_method (int): Integer specifying the method used for interpolation of voxel time courses. A value of 0 selects linear interpolation, a value of 1 (recommended) selects cubic spline interpolation and a value of 2 selects sinc interpolation.
multiband_factor (int): Integer specifying how many slices were simultaneously excited as a "band" at the same time. Value 1 (or smaller) indicates that now simultaneous multi-slice sequence has been used.

correct_motion() → bool

Description: Performs 3D motion correction of the attached slice time course (STC) data of the calling FMR document. The boolean return value indicates whether the operation could be run successfully. The volumes of the data set are aligned to the first volume of the run dataset. The command uses recommended default settings such as "trilinear sinc" for the interpolation method; for other options see other motion correction commands below.

correct_motion_to_vol(int target_vol_idx) → bool

Description: Performs 3D motion correction of the attached slice time course (STC) data of the calling FMR document. The boolean return value indicates whether the operation could be run successfully. The volumes of the data set are aligned to the specified target volume. The command uses recommended default settings such as "trilinear sinc" for the interpolation method; for other options see "correct_motion_ext" below.
target_vol_idx (int): Integer specifying the target volume in the range 0 - (number-of-volumes - 1). The specified target volume is not modified by this procedure.

correct_motion_ext(int target_vol_idx, int interpolation_method, bool full_dataset, int max_iterations, bool create_movie, bool extended_log_file) → bool

Description: Performs 3D motion correction of the attached slice time course (STC) data of the calling FMR document. The boolean return value indicates whether the operation could be run successfully. The volumes of the data set are aligned to the specified target volume. The command uses default settings for the interpolation method (full sinc).
target_vol_idx (int): Integer specifying the target volume in the range 0 - (number-of-volumes - 1). The specified target volume is not modified by this procedure.
interpolation_method (int): Integer specifying the method used for spatial interpolation when resampling source volumes to align them with the target volume. If value 1 is provided, trilinear interpolation will be used for motion detection and final volume transformation; if value 2 is provided (recommended), trilinear interpolation will be used for motion detechtion while sinc interpolation will be used for the final volume transformation; if value 3 is provided, sinc interpolation will be used during motion detection and final volume transformation.
full_dataset (bool): Specifies whether all voxels (True, recommended) or only a subset of voxels (False -> faster processing) will be used for motion detection.
max_iterations (int): Integer specifying the maximum number of iterations used during iterative motion detection. Usually about 5-10 iterations are needed to detect motion parameters and a value of 100 is recommended.
create_movie (bool): Boolean specifying whether a movie will be created (value True) or not (value False). The movie helps to assess the effectiveness of motion correction by dynamically showing a difference image between the first and last volume of the STC data volumes before and after motion correction.
extended_log_file (bool): Boolean specifying whether an extended log file (value True) should be written to disk or not (value False). The extended log file stores information not only about the volume-by-volume motion parameters but also about details of the iterartive motion detection step.

correct_motion_to_run(str target_fmr_file, int target_vol_idx) → bool

Description: Performs 3D motion correction of the attached slice time course (STC) data of the calling FMR document using as the target a volume in another FMR data set. This is useful if one wants to align several runs of the same scanning session. The boolean return value indicates whether the operation could be run successfully. The command uses recommended default settings for other options, e.g. "trilinear sinc" for the interpolation method.
target_fmr_file (str): String specifying the FMR file of another run. The referred file name (with or without path) need to be available on disk and the dimensions of the data must be the same as for the data of the calling FMR document, i.e. the data of the other run must be from the same session with the same slice positioning parameters and with the same dimensions.
target_vol_idx (int): Integer specifying the target volume in the range 0 - (number-of-volumes - 1). The specified target volume is not modified by this procedure.

correct_motion_to_run_ext(str target_fmr_file, int target_vol_idx, int interpolation_method, bool full_dataset, int max_iterations, bool create_movie, bool extended_log_file) → bool

Description: Performs 3D motion correction of the attached slice time course (STC) data of the calling FMR document. The boolean return value indicates whether the operation could be run successfully. The volumes of the data set are aligned to the specified target volume. The command uses default settings for the interpolation method (full sinc).
target_fmr_file (str): String specifying the FMR file of another run. The referred file name (with or without path) need to be available on disk and the dimensions of the data must be the same as for the data of the calling FMR document, i.e. the data of the other run must be from the same session with the same slice positioning parameters and with the same dimensions.
target_vol_idx (int): Integer specifying the target volume in the range 0 - (number-of-volumes - 1). The specified target volume is not modified by this procedure.
interpolation_method (int): Integer specifying the method used for spatial interpolation when resampling source volumes to align them with the target volume. If value 1 is provided, trilinear interpolation will be used for motion detection and final volume transformation; if value 2 is provided (recommended), trilinear interpolation will be used for motion detechtion while sinc interpolation will be used for the final volume transformation; if value 3 is provided, sinc interpolation will be used during motion detection and final volume transformation.
full_dataset (bool): Specifies whether all voxels (True, recommended) or only a subset of voxels (False -> faster processing) will be used for motion detection.
max_iterations (int): Integer specifying the maximum number of iterations used during iterative motion detection. Usually about 5-10 iterations are needed to detect motion parameters and a value of 100 is recommended.
create_movie (bool): Boolean specifying whether a movie will be created (value True) or not (value False). The movie helps to assess the effectiveness of motion correction by dynamically showing a difference image between the first and last volume of the STC data volumes before and after motion correction.
extended_log_file (bool): Boolean specifying whether an extended log file (value True) should be written to disk or not (value False). The extended log file stores information not only about the volume-by-volume motion parameters but also about details of the iterartive motion detection step.

smooth_spatial(float gauss_fwhm, str fwhm_unit) → bool

Description: Performs 3D Gaussian smoothing of the attached slice time course (STC) data of a calling FMR document or the attached volume time course (VTC) data of a calling VMR document. The boolean return value indicates whether the operation could be run successfully. The smoothing kernel is applied in the space domain.
gauss_fwhm (float): Float value specifying the width of the Gaussian smoothing kernel as a full width at half maximum (FWHM) value (default: 4 millimeter).
fwhm_unit (str): String specifying the unit of the FWHM parameter, usually "mm", which will be converted with respect to voxel size (FWHM in millimeter / voxel size). If the unit is not specified as millimeter (e.g. "vx" or "px"), the FWHM parameter is directly interpreted as voxels.

filter_temporal_highpass_glm_fourier(int n_cycles) → bool

Description: Removes low-frequency drifts from the voxel time courses of the attached STC data of the calling FMR document or the attached VTC data of the calling VMR; the high-pass filter is performed using a GLM with a design matrix containng sine/cosine predictors as well as a linear (and a constant) predictor. The boolean return value indicates whether the operation could be run successfully.
n_cycles (int): The number of cycles (default: 3) that will be removed from the voxel time courses, i.e. the number of sine/cosine pairs of predictors (basis functions) in the design matrix. A cycle means that one discretized sine (cosine) wave runs across the number of time points of the fMRI data (lowest frequency), a cycle value of 2 means that two sine/cosine waves fill the extent of the data, and so on.

filter_temporal_highpass_glm_dct(int n_basis_functions) → bool

Description: Removes low-frequency drifts from the voxel time courses of the attached STC data of the calling FMR document using a GLM with a design matrix containng discrete cosine predictors (plus a constant predictor). The boolean return value indicates whether the operation could be run successfully. Also applicable for VMR-VTC documents.
n_basis_functions (int): The number of basis functions (default: 2) that will be removed from the voxel time courses, i.e. the number of discrete cosine predictors (basis functions) in the design matrix. The first cosine predictor will stretch half a cycle over the time course, the second preditor one cycle, the third predictor one and a half and so on.

filter_temporal_highpass_fft(float highpass, str highpass_unit) → bool

Description: Removes low-frequency drifts from the voxel time courses of the attached STC data of the calling FMR document using Fourier analysis. The boolean return value indicates whether the operation could be run successfully. Also applicable for VMR-VTC documents.
highpass (float): The number of basis functions (default: 2) that will be removed from the voxel time courses, i.e. the number of discrete cosine predictors (basis functions) in the design matrix. The first cosine predictor will stretch half a cycle over the time course, the second preditor one cycle, the third predictor one and a half and so on.
highpass_unit (str): The number of basis functions (default: 2) that will be removed from the voxel time courses, i.e. the number of discrete cosine predictors (basis functions) in the design matrix. The first cosine predictor will stretch half a cycle over the time course, the second preditor one cycle, the third predictor one and a half and so on.

smooth_temporal(float gauss_fwhm, str fwhm_unit) → bool

Description: Performs temporal smoothing of the voxel time courses of the attached STC data of the calling FMR document or the linked VTC data of the calling VMR document. The boolean return value indicates whether the operation could be run successfully. The smoothing kernel is applied in the time domain.
gauss_fwhm (float): Float value specifying the width of the Gaussian smoothing kernel as a full width at half maximum (FWHM) value (default: 2 data points).
fwhm_unit (str): String specifying the unit of the FWHM parameter. If the value is "secs", the FWHM parameter is intepreted as number of seconds and the value will be converted in data points (FWHM [seconds] / volume-TR [milliseconds] * 1000). If the unit is not "secs" (e.g. "dp" or "timepoints"), the FWHM parameter is directly interpreted as time points.

adjust_mean_intensity() → bool

Description: Adjusts the mean value of intensities of each volume to the same value by multiplying each voxel of a volume with a correction (scale) factor. The boolean return value indicates whether the operation could be run successfully. This opearation may be useful to adjust for overall fluctuations from time point to time point (e.g. signal drops). If large mean intensities are observed from volume to volume, this may indicate issues with the scanner. If on the other hand the scanner works fine producing rather stationary mean time courses, the mean intensity adjustment procedure is not recommended since it might adjust small mean volume intensity differences that are due to functional activity.