hcp_icafix#

qx_utilities.hcp.process_hcp.hcp_icafix(sinfo, options, overwrite=False, thread=0)#

hcp_icafix [... processing options]

Runs the ICAFix step of HCP Pipeline (hcp_fix_multi_run or hcp_fix).

Warning

The code expects the input images to be named and present in the QuNex folder structure. The function will look into folder:

<session id>/hcp/<session id>

for files:

MNINonLinear/Results/<boldname>/<boldname>.nii.gz

Parameters

--batchfile (str, default ''):

The batch.txt file with all the sessions information.

--sessionsfolder (str, default '.'):

The path to the study/sessions folder, where the imaging data is supposed to go.

--parsessions (int, default 1):

How many sessions to run in parallel.

--parelements (int, default 1):

How many elements (e.g. bolds) to run in parallel.

--overwrite (str, default 'no'):

Whether to overwrite existing data (yes) or not (no). Note that previous data is deleted before the run, so in the case of a failed command run, previous results are lost.

--hcp_suffix (str, default ''):

Specifies a suffix to the session id if multiple variants are run, empty otherwise.

--logfolder (str, default ''):

The path to the folder where runlogs and comlogs are to be stored, if other than default.

--hcp_icafix_bolds (str, default ''):

Specify a list of bolds for ICAFix. You should specify how to group/concatenate bolds together along with bolds, e.g. "<group1>:<boldname1>,<boldname2>| <group2>:<boldname3>,<boldname4>", in this case multi-run HCP ICAFix will be executed, which is the default. Instead of full bold names, you can also use bold tags from the batch file. If this parameter is not provided ICAFix will bundle all bolds together and execute multi-run HCP ICAFix, the concatenated file will be named fMRI_CONCAT_ALL. Alternatively, you can specify a comma separated list of bolds without groups, e.g. "<boldname1>,<boldname2>", in this case single-run HCP ICAFix will be executed over specified bolds. This is a legacy option and not recommended.

--hcp_icafix_highpass (int, default detailed below):

Value for the highpass filter, [0] for multi-run HCP ICAFix and [2000] for single-run HCP ICAFix.

--hcp_matlab_mode (str, default default detailed below):

Specifies the Matlab version, can be 'interpreted', 'compiled' or 'octave'. Inside the container 'compiled' will be used, outside 'interpreted' is the default. For single-run HCP ICAFix the default is 'octave'.

--hcp_icafix_domotionreg (str, default detailed below):

Whether to regress motion parameters as part of the cleaning. The default value for single-run HCP ICAFix is [TRUE], while the default for multi-run HCP ICAFix is [FALSE].

--hcp_icafix_traindata (str, default detailed below):

Which file to use for training data. You can provide a full path to a file or just a filename if the file is in the ${FSL_FIXDIR}/training_files folder. [HCP_hp<high-pass>.RData] for single-run HCP ICAFix and [HCP_Style_Single_Multirun_Dedrift.RData] for multi-run HCP ICAFix.

--hcp_icafix_threshold (int, default 10):

ICAFix threshold that controls the sensitivity/specificity tradeoff.

--hcp_icafix_deleteintermediates (str, default 'FALSE'):

If True, deletes both the concatenated high-pass filtered and non-filtered timeseries files that are prerequisites to FIX cleaning.

--hcp_icafix_fallbackthreshold (int, default 0):

If greater than zero, reruns icadim on any run with a VN mean more than this amount greater than the minimum VN mean.

--hcp_config (str, default ''):

Path to the HCP config file where additional parameters can be specified. For hcp_icafix, these parametersa are: volwisharts, ciftiwisharts and icadimmode.

--hcp_icafix_postfix (str, default 'TRUE'):

Whether to automatically run HCP PostFix if HCP ICAFix finishes successfully.

--hcp_icafix_processingmode (str, default ''):

HCPStyleData (default) or LegacyStyleData, controls whether --icadim-mode=fewtimepoints is allowed.

--hcp_reuse_existing_ica (str, default 'FALSE'):

Whether to execute only the FIX step of the pipeline and reuse the previous ICA results.

--hcp_fix_backup (str, default ''):

If provided, the previous FIX solution is backed up to the specified folder, in case hcp_reuse_existing_ica is used.

--hcp_t1wtemplatebrain (str, default ''):

Path to the T1w template brain used by pyfix. Not set by default, you can either set a path or set to "auto" to set as <HCPPIPEDIR>/global/templates/MNI152_T1_<RES>mm_brain.nii.gz.

--hcp_ica_method (str, default 'MELODIC'):

MELODIC or ICASSO. Use single-pass MELODIC (default) or multi-pass ICASSO consensus method for ICA.

--hcp_legacy_fix (flag, not set by default):

Whether to use the legacy MATLAB fix instead of the new pyfix.

Output files

The results of this step will be generated and populated in the MNINonLinear folder inside the same sessions's root hcp folder.

The final clean ICA file can be found in:

MNINonLinear/Results/<boldname>/<boldname>_hp<highpass>_clean.nii.gz,

where highpass is the used value for the highpass filter. The default highpass value is 0 for multi-run HCP ICAFix and 2000 for single-run HCP ICAFix.

Notes

Runs the ICAFix step of HCP Pipeline (hcp_fix_multi_run or hcp_fix). This step attempts to auto-classify ICA components into good and bad components, so that the bad components can be then removed from the 4D FMRI data. If ICAFix step finishes successfully PostFix (PostFix.sh) step will execute automatically, to disable this set the hcp_icafix_postfix to FALSE.

If the hcp_icafix_bolds parameter is not provided ICAFix will bundle all bolds together and execute multi-run HCP ICAFix, the concatenated file will be named fMRI_CONCAT_ALL. WARNING: if session has many bolds such processing requires a lot of computational resources.

hcp_icafix parameter mapping:

QuNex parameter

HCPpipelines parameter

hcp_icafix_highpass

high-pass

hcp_icafix_domotionreg

motion-regression

hcp_icafix_traindata

training-file

hcp_icafix_threshold

fix-threshold

hcp_icafix_deleteintermediates

delete-intermediates

hcp_icafix_fallbackthreshold

fallback-threshold

hcp_config

config

hcp_icafix_processingmode

processing-mode

hcp_reuse_existing_ica

reuse-existing-ica

hcp_fix_backup

fix-backup

hcp_matlab_mode

matlabrunmode

hcp_t1wtemplatebrain

T1wTemplateBrain

hcp_ica_method

ica-method

hcp_legacy_fix

enable-legacy-fix

Examples

qunex hcp_icafix \
    --batchfile=processing/batch.txt \
    --sessionsfolder=sessions

qunex hcp_icafix \
    --batchfile=processing/batch.txt \
    --sessionsfolder=sessions \
    --hcp_icafix_bolds="GROUP_1:BOLD_1,BOLD_2|GROUP_2:BOLD_3,BOLD_4"