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.mean_correlation¶

brainprep.interfaces.mean_correlation(data_files_regex, atlas_file, output_dir, correlation_threshold=0.5, suffix=None, dryrun=False)[source]¶

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

It can use pre-computed correlation data for each subject or compute the correlation internally. If the correlaton is computed internally, individual pre-computed correlation data are saved in the subjects directory. Additionally, it performs quality control based on a specified correlation threshold.

Parameters:

data_files_regexstr: A REGEX to image files, each representing an image of the same shape and geometry as atlas_file or pre-computed TSV correlation data.
atlas_fileFile | None: A file representing the reference image. If None, expect pre-computed correlation data.
output_dirDirectory: Directory where a TSV file containing the mean correlation values is created.
correlation_thresholdfloat | None: Quality control threshold on the correlation score. If None do not add the qc column. Default 0.5.
suffixstr | None: Suffix added to the generated TSV file. Default None.
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. If invalid pre-computed correlation data are provided.

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.