BrainVoyager Python Developer Guide 0.9
Creation of Functional Documents
The following commands are exposed by the BrainVoyager object to enable the creation of functional documents from original (scanner) MRI files.
create_fmr_dicom(str file_of_series, str fmr_stc_filename, str target_folder, str protocol_file='') → DocPyBV
- Description
- Creates a FMR document from specified DICOM source, i.e. files containing a series of functional volumes, including Siemens mosaic files. To read the DICOM data, the command only needs as input ('file_of_series')) a path to one DICOM file of the respective series representing the (mosaic) functional scan; all other parameters to create the document will be extracted from the DICOM header. The created FMR, STC and associated files are stored to disk. The returned document object can be used subsequently to call commands for e.g. preprocessing and statistics.
- file_of_series (str):
- A string specifying the file path to one file of the respective DICOM series.
- fmr_stc_filename (str):
- Name (without extension) of the created FMR (header) and STC (data) file; note that the FMR file itself contains only meta information and references the actual data STC file (and other auxiliary files).
- target_folder (str):
- Specifies the directory where the created FMR project and associated files (e.g. .stc, .amr files) will be stored.
- protocol_file (str):
- Optional; if provided and found on disk, the protocol file is linked to the created FMR document persistently (stored in FMR file).
create_fmr_dicom_nifti_bids(str file_of_series, int subj_id, int ses_id, int run_id, str task_name, str project_folder, str protocol_file='') → str
- Description
- Creates a NIfTI file from raw (image space) DICOM MRI file(s) of a functional scan. For reading in the data, the command only needs as input a path to one DICOM file of the respective series ('file_of_series') representing the 4D functional scan. The parameters 'subj_id', 'ses_id', 'run_id' and 'task_name' are used to create a BIDS conform file name and to put the file (plus a sidecar JSON file) in the BIDS conform subfolder inside a project referenced with the 'project_folder' parameter; in case the referenced project does not yet exist in the default projects directory, the project folder is created and the nifti file saved in the subject and session specific sub-folder. On success, the file path of the created NIfTI file is returned, otherwise an empty string.
- file_of_series (str):
- A string specifying the file path to one file of the respective series.
- subj_id (int):
- Integer value identifying the subject; note that the provided integer is used to build a "sub-{subj_id}" string, e.g. "sub-07" in case of value 7.
- ses_id (int):
- integer value identifying the session to which the scan belongs; note that the provided integer is used to build a "ses-{ses_id}" string, e.g. "ses-01" in case of value 1.
- run_id (int):
- Integer value identifying the run to which the functional scan belongs; note that the provided integer is used to build a "run-{run_id}" string, e.g. "run-03" in case of value 3. The created string will be part of the NIfTI file name.
- task_name (str):
- String specifying the task that was performed in this functional scan; the provided name will be used to build a "task-{task_name}" string as part of the NIfTI file name.
- project_folder (str):
- A string specifying the name of the project to which the created NIfTI file should be added. If the project does not exist, a new folder with the provided name is created in the projects path (default: "[user]/Documents/BrainVoyager/Projects"). If project_folder contains a full path, the NIfTI data is stored at the indicated location instead of the standard projects path.
- protocol_file (str):
- Optional; if provided and found on disk, the BrainVoyager protocol file will be converted into a BIDS confrom "events" TSV protocol file and stored next to the NIfTI file.
create_fmr(str scanner_file_type, str first_file, int n_volumes, int skip_n_volumes, bool first_volume_amr, int n_slices, str fmr_stc_filename, bool big_endian, int slice_rows, int slice_cols, int bytes_per_pixel, str targetFolder) → PyDoc
- Description
- Creates a FMR document from specified data source, i.e. files containing a series of functional volumes. The returned document object can be used subsequently to call commands for e.g. preprocessing and statistics. Note that for Siemens mosaic files, the "create_fmr_dicom" or "create_mosaic_fmr" command should be used.
- scanner_file_type (str):
- Specifies the type of the raw data, including "DICOM" (default), "ANALYZE", "PHILIPS_REC" and various GE types.
- first_file (str):
- Specifies the first file to use for project creation; in case that a document should be created from multiple files (usual case for Dicom files), this file is only the first of a sequence and subsequent files are found on disk by incrementing a corresponding file number. For Dicom files it is recommended to run the "rename_dicoms" command in a data source folder so that the file numbers are interpretable by BrainVoyager. If the provided filename does not include a full path, make sure that the current directory is set appropriately.
- n_volumes (int):
- Specifies the number of functional volumes to read (usually the full number of volumes scanned in the respective scanning run).
- skip_n_volumes (int):
- Specifies the number of volumes at the begin of the data that will not be included (usually 0); the number of functional volumes in the created FMR file will be: nrOfVolumes - nrOfVolumesToSkip.
- first_volume_amr (bool):
- Specifies whether a AMR file should be created from the first functional volume (true) or not (false). The created AMR file will be used as the default display of slices when a created (or loaded) FMR document is shown. This is especially useful in case that first volumes have been scanned with T1 saturation providing better grey/white matter contrast. These T1 saturated volumes are usually skipped using the nrOfSkipVolumes parameter. Note that in recent years, scanners remove T1 saturated volumes during preparation of functional scanning so first volumes are usually not T1 saturated and no initial volumes need to be skipped.
- n_slices (int):
- Specifies the expected number of slices comprising each functional volume.
- fmr_stc_filename (str):
- Name (without extension) of the created FMR (header) and STC (data) file; note that the FMR file itself contains only meta information and references the actual data STC file (and other auxiliary files).
- big_endian (bool):
- Specifies whether the imported data has little endian byte order (false, recommended as default) or big endian byte order (true). In case that imported images look like salt and pepper noise, try switching this flag. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- slice_rows (int):
- Specifies the number of rows of a single slice. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- slice_cols (int):
- Specifies the number of columns of a single slice. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- bytes_per_pixel (int):
- Specifies how many bytes represent the intensity value of a pixel (usually 2). If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- target_folder (str):
- Specifies the directory where the created FMR project and associated files (e.g. .stc, .amr files) will be stored.
create_mosaic_fmr(str first_file, int n_volumes, int skip_n_volumes, bool first_volume_amr, int n_slices, str fmr_stc_filename, bool big_endian, int mosaic_rows, int mosaic_cols, int slice_rows, int slice_cols, int bytes_per_pixel, str target_folder) → PyDoc
- Description
- Creates a FMR document from a series of Siemens mosaic files, each containing usually one functional volume. This special Siemens format "pretends" each file to be a single image allowing to store all slices of a functional volume in a single "big" DICOM file instead of a set of standard DICOM files; the mosaic arrangement of the individual slices leads to a correct display if displayed as an image, which can be checked in BrainVoyager by creating an AMR document from a mosaic file or by creating a "single slice per file" FMR project (see above). For further processing, the mosaic images need to be decomposed into separate slice images, which is performed by this special FMR document creation function. The returned document object can be used subsequently to call commands for e.g. preprocessing and statistics. Note that the new 'create_fmr_dicom' (and "create_fmr_dicom_nifti_bids") command also supports Siemens mosaic DICOM files and should be considered since most values specified here are automatically filled-in from the DICOM header in that function.
- first_file (str):
- Specifies the first file to use for project creation; the specified file is usually only the first of a series and subsequent files are found on disk by incrementing a corresponding volume number. It is recommended to run the "rename_dicoms" command in a data source folder so that the file numbers are interpretable by BrainVoyager. If the provided filename does not include a full path, make sure that the current directory is set appropriately.
- n_volumes (int):
- Specifies the number of functional volumes to read (usually the full number of volumes scanned in the respective scanning run).
- skip_n_volumes (int):
- Specifies the number of volumes at the begin of the data that will not be included (usually 0); the number of functional volumes in the created FMR file will be: n_volumes - skip_n_volumes .
- first_volume_amr (bool):
- Specifies whether a AMR file should be created from the first functional volume (true) or not (false). The created AMR file will be used as the default display of slices when a created (or loaded) FMR document is shown. This is especially useful in case that first volumes have been scanned with T1 saturation providing better grey/white matter contrast. These T1 saturated volumes are usually skipped using the nrOfSkipVolumes parameter. Note that in recent years, scanners remove T1 saturated volumes during preparation of functional scanning so first volumes are usually not T1 saturated and no initial volumes need to be skipped.
- n_slices (int):
- Specifies the expected number of slices comprising each functional volume.
- fmr_stc_filename (str):
- Name of the prefix used for the stored .stc file (e.g. "myexp_run1") containing the image data; note that the FMR file itself contains only meta information referring to the .stc file (and other auxiliary files).
- big_endian (bool):
- Specifies whether the imported data has little endian byte order (false, recommended as default) or big endian byte order (true). In case that imported images look like salt and pepper noise, try switching this flag. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- mosaic_rows (int):
- Specifies the number of rows of a mosaic image, which is a multiple of the rows of a single slice. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- mosaic_cols (int):
- Specifies the number of columns of a mosaic image, which is a multiple of the columns of a single slice. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- slice_rows (int):
- Specifies the number of rows of a single slice inside the mosaic file. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- slice_cols (int):
- Specifies the number of columns of a single slice inside the mosaic file. If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- bytes_per_pixel (int):
- Specifies how many bytes represent the intensity value of a pixel (usually 2). If this value can be retrieved from the file header (e.g. for DICOM data), the provided value will be ignored.
- target_folder (str):
- Specifies the directory where the created FMR project and associated files (e.g. .stc, .amr files) will be stored.
The following command is no longer recommended (deprecated):
create_fmr_slices_time_looping(QString scanner_file_type, QString first_file, int n_volumes, int skip_n_volumes, bool first_volume_amr, int n_slices, QString fmr_stc_filename, bool big_endian, int slice_rows, int slice_cols, int bytes_per_pixel, QString target_folder) -> DocPyBV
Copyright © 2020 Rainer Goebel. All rights reserved.