Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

brainprep.interfaces.qualcheck.mean_correlation

brainprep.interfaces.qualcheck.mean_correlation(image_files_regex, atlas_file, output_dir, correlation_threshold=0.5, dryrun=False)

Compute the mean Pearson correlation between a reference image and a list of other images.

Parameters:

image_files_regexstr

A REGEX to image files, each representing an image of the same shape and geometry as atlas_file.

atlas_fileFile

An file representing the reference image.

output_dirDirectory

Directory where a TSV file containing the mean correlation values is created.

correlation_thresholdfloat

Quality control threshold on the correlation score. Default 0.5.

dryrunbool

If True, skip actual computation and file writing. Default False.

Returns:

correlations_fileFile

A TSV file containing the Pearson correlation coefficient between the atlas image and each image pointed by the input REGEX. The table includes the columns participant_id, session, run, and mean_correlation, as well as a binary qc column indicating the quality control result.

Raises:

ValueError

If the atlas and an image have incompatible shape or geometry.

Notes

A qc column is added to the output table. It contains a binary flag indicating whether the mean correlation score exceeds the threshold: qc = 1 if mean_correlation > correlation_threshold, otherwise qc = 0.