Configuration
All user parameters for QC report creation are collected in a single csv file, config.csv. Initial configuration file with default values can be created using the mrisnapshot_prep_data helper function, or can be copied from a configuration template.
Warning
config.csv consists of two columns, ParamName and ParamValue. Values in ParamName column should not be edited. Values in ParamValue column can be edited to customize the QC report.
Configuration file includes groups of variables that modify different aspects of QC report creation:
1. Image list parameters
ParamName |
Default Values |
Type |
Values |
Description |
|---|---|---|---|---|
id_col |
ScanID |
Text |
ScanID |
Name of the id column in image list |
ulay_col |
UnderlayImg |
Text |
Any |
Name of the underlay image column in image list |
mask_col |
MaskImg |
Text |
Any |
Name of the mask image column in image list |
olay_col |
OverlayImg |
Text |
Any |
Name of the overlay image column in image list |
olay_col2 |
OverlayImg2 |
Text |
Any |
Name of the second overlay image column in image list |
These parameters control the selection of input images. The report will display snapshots from either a single underlay image (required), or with one or two overlay masks (optional).
Note
Using a second overlay may be useful for comparing two different segmentations. For this use case, the first overlay will be shown with the red color, and the second overlay in green color.
If there are multiple labels in any of the two overlay images, the parameter for edge detection will be set to 1, to make sure that multiple labels from the same overlay can be displayed using a single color.
Users can input a mask image (optional). A mask is primarily used for slice selection, but it can also be used for cropping the selected snapshots (optional).
2. Slice selection parameters
ParamName |
Default Values |
Type |
Values |
Description |
|---|---|---|---|---|
view_plane |
A+S+C |
Char[+Char] |
{A, S, C, A+S, … , A+S+C} |
View plane to extract the snapshot |
sel_vals_olay |
Int[+Int] |
Any label value in overlay image |
Values to select from overlay image |
|
sel_vals_olay2 |
Int[+Int] |
Any label value in second overlay image |
Values to select from second overlay image |
|
min_vox |
1 |
Int |
Any positive value |
Minimum number of foreground voxels in a slice to be eligible for selection |
num_slice |
5 |
Int |
Any positive value |
Number of slices selected from each view |
step_size_slice |
Int |
Any positive value |
Step size between selected slices |
|
crop_to_mask |
0 |
Bool |
[0 or 1] |
Is the snapshot cropped to the mask? |
crop_to_olay |
0 |
Bool |
[0 or 1] |
Is the snapshot cropped to the overlay? |
padding_ratio |
0 |
Float |
[0 to 1] |
Ratio of additional padding if the snapshot is cropped |
An important task in QC report creation is the slice selection and extraction of final snapshots. We use a set of parameters to control this task for various use cases, such as:
QC of raw scans
QC of segmentations focusing on the whole image
QC of segmentations focusing only on the segmented structures
QC of selected labels in segmentations
Slice selection is done independently in each view plane. Users can select any combinations of 3 view planes, axial, sagittal and coronal (view_plane).
For slice selection, we first create a “foreground mask”. This mask is primarily derived from the mask image; from the overlay image(s) if no mask exists; and from the non-zero voxels of the underlay image if no mask and overlay images exist
Users can select a subset of labels from overlay images (sel_vals_olay, sel_vals_olay2). By default, all labels from an overlay image are used for slice selection and display. If a user selects specific labels, all other values are reset to 0, and the updated overlay image is used for slice selection and display.
Note
A typical use case scenario is the QC of specific regions of interest (ROI). For example, users may want to create QC snapshots that only show the hippocampus
With the example dataset, this can be tested using the _ROIMASK.nii.gz images as overlay, and setting “sel_vals_olay = 47+48”, the indices for the left hippocampus (47) and right hippocampus (48)
If a slice has less than min_vox foreground pixels, it will not be included in the foreground mask for the specific view plane.
Note
This parameter was introduced to allow discarding small structures during the QC of segmentations. For example, to discard slices with small lesions in the QC of WM lesion segmentation
From the foreground mask, a subset of slices are selected using either the num_slice parameter (fixed number of slices with a regular step size) or the step_size_slice (fixed step size with a variable number of slices)
Note
When the size of the overlay or mask image is predictable and not variable (e.g. brain mask), it may be suitable to set the num_slice parameter, in order to display a fixed number of equally spaced slices.
For segmentation labels with variable size (e.g WM lesions) users may prefer to set the step_size_slice parameter to display more or less slices depending on the segmented volumes
For this second case, the typical usage is not to input a mask image, so that the slice selection is limited to segmented structures on the overlay image (e.g. show only slices with lesions). However, the users may also provide a mask to select slices independent of the overlay images (e.g. showing slices within a brain mask with or without lesions)
Selected slices can be displayed in full size, cropped to the mask (bounding box of the foreground volume in the mask), or cropped to overlay images (bounding box of the foreground volume in the overlay images).
Users can also extend the cropping area by setting the padding_ratio. For example padding_ratio = 0.1 will increase the padding area by %10 of its initial size
3. Visualization parameters
ParamName |
Default Values |
Type |
Values |
Description |
|---|---|---|---|---|
bin_olay |
0 |
Bool |
[0 or 1] |
Binarize the overlay image? |
is_edge |
1 |
Bool |
[0 or 1] |
Detect edges on the overlay image? |
alpha_olay |
1 |
Float |
[0 to 1] |
Alpha (transparency) value of the overlay |
perc_low |
0 |
Int |
[0 to 49] |
Lower intensity value for scaling the contrast of the underlay image |
perc_high |
100 |
Int |
[51 to 100] |
Upper intensity value for scaling the contrast of the underlay image |
These parameters control few visual aspects of the display. Users can binarize the overlay images (bin_olay); extract the edges of the overlays (is_edge); change the transparency of the overlays (alpha_olay); and change the contrast of the underlay image by mapping the minimum and maximum image intensities to selected intensity percentile values calculated from the complete image (perc_low, perc_high)
4. Report parameters
ParamName |
Default Values |
Type |
Values |
Description |
|---|---|---|---|---|
is_out_single |
0 |
Bool |
[0 or 1] |
Create a single html QC report for all subjects? |
is_out_noqc |
0 |
Bool |
[0 or 1] |
Create an html QC report without the QC form? |
img_width |
300 |
Int |
Any positive value |
Width of each snapshot |
label_checkbox1 |
PASS |
Text |
Any text |
Label of the first check box in QC form |
label_checkbox2 |
FAIL |
Text |
Any text |
Label of the second check box in QC form |
label_editbox |
Notes |
Text |
Any text |
Label of the edit box in QC form |
These parameters control few aspects of the final QC report. Users can create a single .html report for the complete set, instead of an independent .html file for each subject (is_out_single); prefer not to include the QC form in the report (is_out_noqc); and set the size of the snapshots in the report (img_width)
Note
Default QC report is a collection of independent .html files. This format was selected as default, because it provides a better separation of subjects and easier annotation using the quick navigation shortcuts (left / right arrows)
Note
The style of the QC report is managed by a stylesheet that is saved in QCReport/subjects/scripts/pagestyle.css. Users can edit this file to modify the style of the QC report without rerunning the report creation (e.g. change the snapshot size by editing the .column:width value)
The QC form includes 2 check boxes and 1 edit box. The names of these objects are used as the columns of the final QC annotation .csv file. Users can rename these objects in a way that will better reflect their task (label_checkbox1, label_checkbox2, label_editbox).
For example, during the QC of raw T1-weighted scans users may prefer to rename the QC form columns as “ImgHasMotion”, “ImgCorrupt” and “Details”