cmind.pipeline.cmind_fMRI_outliers

Functions

binstr2dec(binstr) Convert a binary string such as “0100101” to its decimal (base 10)
cmind_fMRI_outliers(output_dir, ...[, ...]) Detect outlier timepoints in fMRI timeseries and generate nuisance
orthogonalize(ts1, ts2) orthogonalize ts1 with respect to ts2
cmind.pipeline.cmind_fMRI_outliers.binstr2dec(binstr)[source]

Convert a binary string such as “0100101” to its decimal (base 10) representation

Parameters:

binstr : str

binary string to convert

Returns:

decval : int

decimal value corresponding to binstr

cmind.pipeline.cmind_fMRI_outliers.cmind_fMRI_outliers(output_dir, contrast_of_interest, regBBR_ref, WM_pve_vol, GM_pve_vol, CSF_pve_vol, vol_file_niigz, filtered_func_data, motion_parfile, unfiltered_design_matrix, FSF_template, noise_est_file, HRtoLR_Affine=None, HRtoLR_Warp=None, Nproc_max=1, generate_figures=True, ForceUpdate=False, verbose=False, logger=None)[source]

Detect outlier timepoints in fMRI timeseries and generate nuisance regressors

Parameters:

output_dir : str

directory in which to store the output

contrast_of_interest : int or list of int

which contrast in FSF_template is of primary interest? Note: Unlike in the FSL GUI, contrast numbering begins from 0!. If this is a list the minimum effect size among the contrasts in the list will be used during the computation

regBBR_ref : str

filename of the regBBR reference image

WM_pve_vol : str

WM partial volume estimate from structural processing

GM_pve_vol : str

GM partial volume estimate from structural processing

CSF_pve_vol : str

CSF partial volume estimate from structural processing

vol_file_niigz : str

unfiltered 4D fMRI timeseries to process

filtered_func_data : str

smoothed and temporal filtered 4D fMRI timeseries file to process

motion_parfile : str

The 6 column motion parameter (.par) file from mcflirt

unfiltered_design_matrix : str

The (unfiltered) Feat design matrix corresponding to vol_file_niigz

FSF_template : str

THE .fsf template corresponding to vol_file_niigz

noise_est_file : str

The noise_est.txt file from cmind_fMRI_preprocess2.py

HRtoLR_Affine : str, optional

filename for the affine transform from functional->structural space

HRtoLR_Warp : str, optional

fieldmap corrected warp from functional->structural space

Nproc_max : int, optional

maximum number of processes to launch simultaneously

generate_figures : bool, optional

if true, generate additional summary images

ForceUpdate : bool, optional

if True, rerun and overwrite any previously existing results

verbose : bool, optional

print additional output (to terminal and log)

logger : logging.Logger or str, optional

logging.Logger object (or string of a filename to log to)

Returns:

default_confound_file : str

confound file with 6 motion + outliers

best_confound_file : str

optimal confound file

worst_confound_file : str

“worst” confound file

mcf06_confound_file : str

6 motion parameters confound file

FSL_outliers_txt : str

outliers confound file

Notes

For the “optimal” nuisance regressor evaluation the following regressor sets are considered:

  1. mean CSF regressor (orthogonalized w.r.t. ASL/BOLD baseline)
  2. mean WM regressor (orthogonalized w.r.t. ASL/BOLD baseline)
  3. 6 rigid body motion parameters
  4. squares of the 6 motion parameters
  5. derivatives of the 6 motion parameters
  6. squares of the derivatives of the 6 motion parameters
  7. outlier regressors

PCA is also applied to the combined set of regressors and thresholds for 75, 90, 95 and 99 percent of explained variance are applied. These four PCA regressor sets are evaluated in addition to the 2**7=128 possible combinations of the 7 regressor sets mentioned above.

cmind.pipeline.cmind_fMRI_outliers.orthogonalize(ts1, ts2)[source]

orthogonalize ts1 with respect to ts2 (Gram-Schmidt orthogonalization)

Parameters:

ts1 : timeseries to process

ts2 : timeseries to remove

Returns:

ts1 : ts1 after orthogonalization to ts2