hcp_msmall

qx_utilities.hcp.process_hcp.hcp_msmall(sinfo, options, overwrite=True, thread=0)

hcp_msmall [... processing options]

Runs the MSMAll step of the HCP Pipeline (MSMAllPipeline.sh).

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>_<hcp_cifti_tail>_hp<hcp_highpass>_clean.dtseries.nii

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.

--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 ''):

List of bolds on which ICAFix was applied, with the same format as for ICAFix. Typically, this should be identical to the list used in the ICAFix run. If multi-run ICAFix was run with two or more groups then HCP MSMAll will be executed over the first specified group (and the scans listed for hcp_msmall_bolds must be limited to scans in the first concatenation group as well). If not provided MSMAll will assume multi-run ICAFix was executed with all bolds bundled together in a single concatenation called fMRI_CONCAT_ALL (i.e., same default behavior as in ICAFix).

--hcp_msmall_bolds (str, default detailed below):

A comma separated list that defines the bolds that will be used in the computation of the MSMAll registration. Typically, this should be limited to resting-state scans. Specified bolds have to be a subset of bolds used from the hcp_icafix_bolds parameter [if not specified all bolds specified in hcp_icafix_bolds will be used, which is probably NOT what you want to do if hcp_icafix_bolds includes non-resting-state scans].

--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. Should be identical to the value used for ICAFix.

--hcp_msmall_outfmriname (str, default 'rfMRI_REST'):

The name which will be given to the concatenation of scans specified by the hcp_msmall_bold parameter.

--hcp_msmall_templates (str, default <HCPPIPEDIR>/global/templates/MSMAll):

Path to directory containing MSMAll template files.

--hcp_msmall_outregname (str, default 'MSMAll_InitialReg'):

Output registration name.

--hcp_hiresmesh (int, default 164):

High resolution mesh node count.

--hcp_lowresmesh (int, default 32):

Low resolution mesh node count.

--hcp_regname (str, default 'MSMSulc'):

Input registration name.

--hcp_matlab_mode (str, default 'compiled'):

Specifies the MATLAB version, can be 'interpreted', 'compiled' or 'octave'.

--hcp_msmall_procstring (str, default <hcp_cifti_tail>_hp<hcp_highpass>_clean):

Identification for FIX cleaned dtseries to use.

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

Whether to automatically run HCP DeDriftAndResample if HCP MSMAll finishes successfully.

--hcp_msmall_myelin_target (str, default 'Q1-Q6_RelatedParcellation210.MyelinMap_BC_MSMAll_2_d41_WRN_DeDrift.32k_fs_LR.dscalar.nii'):

Myelin map target, will use Q1-Q6_RelatedParcellation210.MyelinMap_BC_MSMAll_2_d41_WRN_DeDrift.32k_fs_LR.dscalar.nii by default.

Output files

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

Notes

Runs the MSMAll step of the HCP Pipeline. This function executes two steps, it first runs MSMAll and if it completes successfully it then executes the DeDriftAndResample step. To disable this automatic execution of DeDriftAndResample set hcp_msmall_resample to FALSE.

The MSMAll step computes the MSMAll registration based on resting-state connectivity, resting-state topography, and myelin-map architecture. The DeDriftAndResample step applies the MSMAll registration to a specified set of maps and fMRI runs.

MSMAll is intended for use with fMRI runs cleaned with hcp_icafix. Except for specialized/expert-user situations, the hcp_icafix_bolds parameter should be identical to what was used in hcp_icafix. If hcp_icafix_bolds is not provided MSMAll/DeDriftAndResample will assume multi-run ICAFix was executed with all bolds bundled together in a single concatenation called fMRI_CONCAT_ALL. (This is the default behavior if hcp_icafix_bolds parameter is not provided in the case of hcp_icafix).

A key parameter in hcp_msmall is hcp_msmall_bolds, which controls the fMRI runs that enter into the computation of the MSMAll registration. Since MSMAll registration was designed to be computed from resting-state scans, this should be a list of the resting-state fMRI scans that you want to contribute to the computation of the MSMAll registration.

However, it is perfectly fine to apply the MSMAll registration to task fMRI scans in the DeDriftAndResample step. The fMRI scans to which the MSMAll registration is applied are controlled by the hcp_icafix_bolds parameter, since typically one wants to apply the MSMAll registration to the same full set of fMRI scans that were cleaned using hcp_icafix.

hcp_msmall parameter mapping:

QuNex parameter	HCPpipelines parameter
hcp_msmall_outfmriname	output-fmri-name
hcp_icafix_highpass	high-pass
hcp_msmall_templates	msm-all-templates
hcp_msmall_outregname	output-registration-name
hcp_hiresmesh	high-res-mesh
hcp_lowresmesh	low-res-mesh
hcp_regname	input-registration-name
hcp_matlab_mode	matlab-run-mode
hcp_msmall_procstring	fmri-proc-string

Examples

HCP MSMAll after application of single-run ICAFix:

qunex hcp_msmall \
    --batchfile=processing/batch.txt \
    --sessionsfolder=sessions \
    --hcp_icafix_bolds="REST_1,REST_2,TASK_1,TASK_2" \
    --hcp_msmall_bolds="REST_1,REST_2" \
    --hcp_matlab_mode="interpreted"

HCP MSMAll after application of multi-run ICAFix:

qunex hcp_msmall \
    --batchfile=processing/batch.txt \
    --sessionsfolder=sessions \
    --hcp_icafix_bolds="GROUP_1:REST_1,REST_2,TASK_1|GROUP_2:REST_3,TASK_2" \
    --hcp_msmall_bolds="REST_1,REST_2" \
    --hcp_matlab_mode="interpreted"