neurocaps.extraction.TimeseriesExtractor.report_qc#

TimeseriesExtractor.report_qc(output_dir=None, filename=None, return_df=True)[source]#

Report Quality Control Information.

Converts per-subject, per-run quality control metrics (frame scrubbing and interpolation) stored in self.qc dictionary to a pandas DataFrame for analysis and reporting.

Added in version 0.24.3.

Parameters:

  • output_dir (str, default=None) – Directory to save a pickle file to. The directory will be created if it does not exist. File will not be saved in an output directory is not provided.

  • filename (str or None, default=None) – Name of the file with or without the “csv” extension.

  • return_df (bool, default=True) – If True, returns the dataframe.

Returns:

pandas.Dataframe – Pandas dataframe containing the colums: “Subject_ID”, “Run”, “Frames_Scrubbed”, “Frames_Interpolated”, “Mean_High_Motion_Length”, and “Std_High_Motion_Length”.

Important

Reporting: Statistics for each subject’s run are only reported when fd_threshold is specified, a valid confound tsv file containing the “framewise_displacement” column is found, and the run is not skipped.

FD Threshold: The value of each statistic are specific to the threshold specified by fd_threshold.

Censored & Interpolated Frames: The frame counts reported exclude any dummy volumes, as they are calculated after dummy volumes are removed from the analysis. If a condition was specified in self.get_bold, the reported values reflect only frames specific to that condition; otherwise, metrics represent the entire timeseries (excluding dummy volumes).

The metrics for scrubbed frames and interpolated frames are independent. For instance, two scrubbed frames and three interpolated frames means that three frames were interpolated while two were scrubbed due to excessive motion. Note that only censored frames with valid data on both sides are interpolated, while censored frames at the edge of the timeseries (including frames that border censored edges) are always scrubbed and counted in “Frames_Scrubbed”.

High Motion Length Computation: “Mean_High_Motion_Length” and “Std_High_Motion_Length” represent the average length and population standard deviation of contiguous segments of frames flagged for high-motion frames, respectively. When condition is specified in self.get_bold, only frames associated with that condition are included in these calculations and are treated as a continuous block (per run) for computational simplicity. The computation remains the same regardles if these flagged frames are interpolated.