Command line usage - Freesurfer

visualqc_freesurfer: rate quality of Freesurfer reconstruction.

usage: visualqc_freesurfer [-h] [-i ID_LIST] [-f FS_DIR] [-o OUT_DIR]
                           [-m MRI_NAME] [-g SEG_NAME] [-l label [label ...]]
                           [-v {cortical_volumetric,cortical_contour,labels_volumetric,labels_contour}]
                           [-c CONTOUR_COLOR] [-a alpha alpha]
                           [-olm OUTLIER_METHOD] [-olf OUTLIER_FRACTION]
                           [-olt OUTLIER_FEAT_TYPES] [-old]
                           [-w VIEWS [VIEWS ...]] [-s NUM_SLICES]
                           [-r NUM_ROWS] [-ns]

Input and output

-i, --id_list

Abs path to file containing list of subject IDs to be processed. If not provided, all the subjects with required files will be processed.


-f, --fs_dir

Absolute path to SUBJECTS_DIR containing the finished runs of Freesurfer parcellation Each subject will be queried after its ID in the metadata file.

E.g. --fs_dir /project/freesurfer_v5.3

-o, --out_dir

Output folder to store the visualizations & ratings. Default: a new folder called visualqc will be created inside the fs_dir

-m, --mri_name

Specifies the name of MRI image to serve as the reference slice. Typical options include orig.mgz, brainmask.mgz, T1.mgz etc. Make sure to choose the right vis_type.

Default: orig.mgz (within the mri folder of Freesurfer format).

-g, --seg_name

Specifies the name of segmentation image (volumetric) to be overlaid on the MRI. Typical options include aparc+aseg.mgz, aseg.mgz, wmparc.mgz. Make sure to choose the right vis_type.

Default: aparc+aseg.mgz (within the mri folder of Freesurfer format).

-l, --labels

Specifies the set of labels to include for overlay.

Atleast one label must be specified when vis_type is labels_volumetric or labels_contour

Default: None (show nothing)

Overlay options

-v, --vis_type

Possible choices: cortical_volumetric, cortical_contour, labels_volumetric, labels_contour

Specifies the type of visualizations/overlay requested. Default: cortical_contour (volumetric overlay of cortical segmentation on T1 mri).

-c, --contour_color

Specifies the color to use for the contours overlaid on MRI (when vis_type requested prescribes contours). Color can be specified in many ways as documented in Default: yellow.

-a, --alpha_set

Alpha values to control the transparency of MRI and aseg. This must be a set of two values (between 0 and 1.0) separated by a space e.g. –alphas 0.7 0.5.

Default: 1.0 0.7. Play with these values to find something that works for you and the dataset.

Outlier detection

options related to automatically detecting possible outliers

-olm, --outlier_method

Method used to detect the outliers.

For more info, read

Default: isolation_forest.

-olf, --outlier_fraction

Fraction of outliers expected in the given sample. Must be >= 1/n and <= (n-1)/n, where n is the number of samples in the current sample.

For more info, read

Default: 0.2.

-olt, --outlier_feat_types

Type of features to be employed in training the outlier detection method. It could be one of ‘cortical’ (aparc.stats: mean thickness and other geometrical features from each cortical label), ‘subcortical’ (aseg.stats: volumes of several subcortical structures), or ‘both’ (using both aseg and aparc stats).

Default: (‘histogram_whole_scan’,).

-old, --disable_outlier_detection

This flag disables outlier detection and alerts altogether.

Layout options

-w, --views

Specifies the set of views to display - could be just 1 view, or 2 or all 3. Example: –views 0 (typically sagittal) or –views 1 2 (axial and coronal) Default: 0 1 2 (show all the views in the selected segmentation)

-s, --num_slices

Specifies the number of slices to display per each view. This must be even to facilitate better division. Default: 12.

-r, --num_rows

Specifies the number of rows to display per each axis. Default: 2.


Options related to workflow e.g. to pre-compute resource-intensive features, and pre-generate all the visualizations required

-ns, --no_surface_vis

This flag disables batch-generation of 3d surface visualizations, which are shown along with cross-sectional overlays. This is not recommended, but could be used in situations where you do not have Freesurfer installed or want to focus solely on cross-sectional views.

Default: False (required visualizations are generated at the beginning, which can take 5-10 seconds for each subject).