BrainVoyager Python Developer Guide 0.9

General Application Commands

The following commands are exposed by the general object "BrainVoyager" that is made available to any Python script. Additional commands to create anatomical, functional and diffusion-weighted documents are described in subsequent topics.

methods() → tuple

Description: Returns a tuple with the methods supported by the BrainVoyager object.

describe_method(str method_name) → str

Description: Returns a string with documentation for the specified method the BrainVoyager object. The returned string should be printed to properly convert newline characters (e.g. > print(describe_method('name')). The printed output contains the same information displayed in the BV Notebook API Help Output pane when hovering over a BV method name or when tab-completing a method name. Note: At present help is not available for all commands.
method_name (str): String containing the name of the method.

close_all()

Description: Closes all open documents in the multi-document workspace. This might be useful to ensure that all previously (interactively or programmatically) opened documents have been closed.

open_document(str file_path) → DocPyBV

Description: Opens a document from a stored representation, adds it to the document list and shows it in the multi-document workspace area of the main window. This function opens both BrainVoyager standard formats (e.g. VMR, FMR, DMR) as well as NIfTI files; the respective file type is inferred from the file extension (e.g. ".vmr" for VMR files, "nii.gz" or "nii" for NIfTI files). The function returns a DocPyBV object that can be used to call document-specific functions.
file_path (str): String specifying the path of the file on disk to be opened. If the provided file name does not include a full path, make sure that the current directory is set appropriately. If file_path is a contains a relative path and if the code is evaluated from a notebook, the path is interpreted relative to the path of the notebook.

open(str file_path, bool close_current_doc=False, bool remove_current_doc=False) → DocPyBV

Description: Opens a document from a stored representation in the same way as desribed for the 'open_document' command above. The two optional parameters can be used to close the current document (if any) and to remove its file representation from disk before opening the new document, which might be useful when creating analysis pipelines.
file_path (str): String specifying the path of the file on disk to be opened. If the provided file name does not include a full path, make sure that the current directory is set appropriately. If file_path is a contains a relative path and if the code is evaluated from a notebook, the path is interpreted relative to the path of the notebook.
close_current_doc (bool): Optional; boolean specifying whether the currently active document should be closed before opening the new document from disk.
remove_current_doc (bool): Optional; boolean specifying whther the file(s) representing the currently active document should be removed from disk.

rename_dicoms(str directory)

Description: Renames DICOM files to a standard format that is easier to process by functions reading raw data files to create documents. Only files that are identified as DICOM are processed; from these files, the series number (0020,0011), acquisition (volume) number (0020,0012) and instance (image) number (0020,0013) as well as the patient's name (0010,0010) are extracted to form new names according to the pattern:
"PatientsName-SeriesNumber-VolumeNumber-ImageNumber.dcm"
The numbers are filled with zeros at the left side so that the series and volume number contain 4 digits, and the image number contains 5 digits (e.g. "Name-0003-0021-00001.dcm"). If a volume (acquisition) number is not found, it is set to "0001". If the DICOM files should be annonymized, use the "AnonymizeDicomFilesInDirectory" command.
directory (str): String specifying the folder containing the files to process. If a relative path is provided, make sure that the current directory is set appropriately.

anonymize_dicoms(str directory, str anonymized_patient_name)

Description: This function renames DICOM files to a standard format that is easier to process by functions reading raw data files operating in the same way as the "RenameDicomFilesInDirectory" command (see above). The patient's name is replaced by the provided new patient's name to anonymize the file resulting file names. The provided new name is also used to replace the value of the patient's name entry in the DICOM file (0010,0010) providing basic anonymization (other patient data such as date of birth is not changed). Note that all DICOM files found in the specified folder receive the same new patient's name, i.e. all files in the directory should be from the same participant.
directory (str): String specifying the folder containing the files to process. If a relative path is provided, make sure that the current directory is set appropriately.
anonymized_patient_name (str): String specifying the new patient name replacing the original name found in the DICOM file (0010,0010). The name is only replaced if the existing size of the text entry is large enough to hold the new patient's name, i.e. the length field of the tag is not adjusted at present and in that case a message is written to the Log pane; it is thus advised to use short names, such as "P24".

deface_anat_dicoms(str input_directory, str output_directory) → bool

Description: Defaces the DICOM images of a 3D anatomical (VMR) dataset. At present, the voxel size of the DICOM data must be 1.0mm in all 3 dimensions. The DICOM files in the provided input_directory are read and a VMR document is temporarily created. The VMR is then normalized into MNI space to obtain a MNI affine transformation matrix, which is applied backwards to locate the MNI defacing mask (bundled with BrainVoyager) in native space. After the mask is applied in native space, the defaced image data is stored back into the DICOM files that remain identical to the original ones except that voxels in and anterior to the face region are removed (retained voxels are not changed). The original DICOMs are not replaced, i.e. the defaced DICOMs are stored with a leading "defaced_" substring in the provided output_directory.
input_directory (str): String specifying the folder containing the DICOM files to process. While the directory can have other (e.g. functional) datasets next to anatomical datasets, only the first encountered 3D dataset is processed with this command, i.e. there should only be 1 3D dataset in the directory. If a relative path is provided, make sure that the current directory is set appropriately. In case the command is run from a notebook, the path can also be defined relative to the location of the notebook.
output_directory (str): String specifying the directory where the defaced DICOM files will be stored. While this can be the same as the input directory, it might be useful to store the defaced data in a separate folder. This is also necessary in case that the input directory is readable but not writable.

show_log_pane()

Description: Shows the Log pane, usually at the bottom of the main window. The Log pane can also be undocked to become a separate windos that can be resized and moved freely, and it can be docked in the lower and upper dock area.

hide_log_pane()

Description: Hides the Log pane.

print_to_log(str text)

Description: Prints the provided text to the Log pane. Usually the message is a short one-line plain text message but simple HTML formatting can also be used (e.g. bold, italics for sub-strings).
text (str): String specifying the text to be printed in the Log pane.

exit()

Description: Quits BrainVoyager. This should be called (if required) only at the end of a script in order to avoid interrupting ongoing processes.

Signatures of other general commands:

    show_message_box( str message );
    bool show_timeout_message_box( str message, int duration );

    move_window(int new_x, int new_y);
    resize_window(int new_width, int new_height);

    str choose_directory( str instruction );
    str choose_file( str instruction, str filter );

    tuple get_vtcs_of_mdm(str mdm_file);