hcp_temporal_ica#

qx_utilities.hcp.process_hcp.hcp_temporal_ica(sessions, sessionids, options, overwrite=True, thread=0)#

hcp_temporal_ica [... processing options]

hcp_tica [... processing options]

Runs the HCP temporal ICA pipeline (tICAPipeline.sh).

Warning

The code expects the HCP minimal preprocessing pipeline, HCP ICAFix, HCP MSMAll and HCP make average dataset to be executed.

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.

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

--log (str, default 'keep'):

Whether to keep ('keep') or remove ('remove') the temporary logs once jobs are completed. When a comma or pipe ('|') separated list is given, the log will be created at the first provided location and then linked or copied to other locations. The valid locations are:

'study' (for the default: <study>/processing/logs/comlogs location)
'session' (for <sessionid>/logs/comlogs)
'hcp' (for <hcp_folder>/logs/comlogs)
'<path>' (for an arbitrary directory).

--hcp_tica_studyfolder (str, default ''):

Overwrite the automatic QuNex's setup of the study folder, mainly useful for REUSE mode and advanced users.

--hcp_tica_bolds (str, default ''):

A comma separated list of fmri run names. Set to all session BOLDs by default.

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

Name to use for tICA pipeline outputs.

--hcp_tica_surfregname (str, default ''):

The registration string corresponding to the input files.

--hcp_icafix_highpass (str, default detailed below):

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

--hcp_tica_procstring (str, default '<hcp_cifti_tail>_<hcp_tica_surfregname>_hp<hcp_icafix_highpass>_clean'):

File name component representing the preprocessing already done, e.g. '_Atlas_MSMAll_hp0_clean'.

--hcp_outgroupname (str, default ''):

Name to use for the group output folder.

--hcp_bold_res (str, default '2'):

Resolution of data.

--hcp_tica_timepoints (str, default ''):

Output spectra size for sICA individual projection, RunsXNumTimePoints, like '4800'.

--hcp_tica_num_wishart (str, default ''):

How many wisharts to use in icaDim.

--hcp_lowresmesh (int, default 32):

Mesh resolution.

--hcp_tica_mrfix_concat_name (str, default ''):

If multi-run FIX was used, you must specify the concat name with this option.

--hcp_tica_icamode (str, default 'NEW'):

Whether to use parts of a previous tICA run (for instance, if this group has too few subjects to simply estimate a new tICA). Defaults to NEW, all other modes require specifying the hcp_tica_precomputed_* parameters. Value must be one of:

'NEW' ... estimate a new sICA and a new tICA,
'REUSE_SICA_ONLY' ... reuse an existing sICA and estimate a new tICA,
'INITIALIZE_TICA' ... reuse an existing sICA and use an existing tICA to start the estimation,
'REUSE_TICA' ... reuse an existing sICA and an existing tICA.

--hcp_tica_precomputed_clean_folder (str, default ''):

Group folder containing an existing tICA cleanup to make use of for REUSE or INITIALIZE modes.

--hcp_tica_precomputed_fmri_name (str, default ''):

The output fMRI name used in the previously computed tICA.

--hcp_tica_precomputed_group_name (str, default ''):

The group name used during the previously computed tICA.

--hcp_tica_extra_output_suffix (str, default ''):

Add something extra to most output filenames, for collision avoidance.

--hcp_tica_pca_out_dim (str, default ''):

Override number of PCA components to use for group sICA.

--hcp_tica_pca_internal_dim (str, default ''):

Override internal MIGP dimensionality.

--hcp_tica_migp_resume (str, default 'YES'):

Resume from a previous interrupted MIGP run, if present.

--hcp_tica_sicadim_iters (int, default 100):

Number of iterations or mode for estimating sICA dimensionality.

--hcp_tica_sicadim_override (str, default ''):

Use this dimensionality instead of icaDim's estimate.

--hcp_low_sica_dims (str, default '7@8@9@10@11@12@13@14@15@16@17@18@19@20@21'):

The low sICA dimensionalities to use for determining weighting for individual projection.

--hcp_tica_reclean_mode (str, default ''):

Whether the data should use ReCleanSignal.txt for DVARS.

--hcp_tica_starting_step (str, default ''):

What step to start processing at, one of:

'MIGP',
'GroupSICA',
'indProjSICA',
'ConcatGroupSICA',
'ComputeGroupTICA',
'indProjTICA',
'ComputeTICAFeatures',
'ClassifyTICA',
'CleanData'.

--hcp_tica_stop_after_step (str, default 'ComputeTICAFeatures'):

What step to stop processing after, same valid values as for hcp_tica_starting_step.

--hcp_tica_remove_manual_components (str, default ''):

Text file containing the component numbers to be removed by cleanup, separated by spaces, requires either: --hcp_tica_icamode=REUSE_TICA or --hcp_tica_starting_step=CleanData.

--hcp_tica_fix_legacy_bias (str, default 'YES'):

Whether the input data used the legacy bias correction, YES or NO.

--hcp_parallel_limit (str, default ''):

How many subjects to do in parallel (local, not cluster-distributed) during individual projection.

--hcp_tica_config_out (flag, optional):

A flag that determines whether to generate config file for rerunning with similar settings, or for reusing these results for future cleaning. Not set by default.

--hcp_tica_average_dataset (str, default ''):

Location of the average dataset, the output from hcp_make_average_dataset command. Set this if using the average set from another study, this is usually used in combination with REUSE_TICA mode.

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

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

Output files

If ran on a single session the results of this step can be found in the same sessions's root hcp folder. If ran on multiple sessions then a group folder is created inside the QuNex's session folder.

Notes

the HCP Temporal ICA Pipeline needs to be executed in two steps, the first step runs the following steps:

MIGP,
GroupSICA,
indProjSICA,
ConcatGroupSICA,
ComputeGroupTICA,
indProjTICA,
ComputeTICAFeatures.

Since automatic classification is not yet supported. Users need to classify the components manually and then rerun temporal ICA from CleanData step onwards. This is the reason that the hcp_tica_stop_after_step is by default set to ComputeTICAFeatures. After the manual classification both hcp_tica_starting_step and hcp_tica_stop_after_step need to be set to CleanData.

In practice this means that after the HCP Temporal ICA Pipeline requirements have been satisified (you need to run the HCP Minimnal Preprocessing Pipeline, `hcp_icafix <../../api/gmri/hcp_icafix.rst>`__, `hcp_msmall <../../api/gmri/hcp_msmall.rst>`__ and `hcp_make_average_dataset <../../api/gmri/hcp_make_average_dataset.rst>`__) you can run the first processing part, for example:

qunex hcp_temporal_ica \
    --sessionsfolder="<path_to_study_folder>/sessions" \
    --batchfile="<path_to_study_folder>/processing/batch.txt" \
    --hcp_tica_bolds="fMRI_CONCAT_ALL" \
    --hcp_tica_outfmriname="fMRI_CONCAT_ALL" \
    --hcp_tica_mrfix_concat_name="fMRI_CONCAT_ALL" \
    --hcp_tica_surfregname="MSMAll" \
    --hcp_icafix_highpass="0" \
    --hcp_outgroupname="hcp_group" \
    --hcp_tica_timepoints=<read from post_fix logs> \
    --hcp_tica_num_wishart="6" \
    --hcp_parallel_limit="4"

The hcp_tica_timepoints parameter value can be found inside the hcp post_fix logs under the label NumTimePoints. If your study has many sessions you also need to set the hcp_parallel_limit to prevent too many sessions from processing and parallel. If you do not limit this, your system will most likely run out of memory. Once this part is done (note that this can take a couple of days with larger studies), the command will store the components in <sessionfolderpath>/hcp_group/hcp_group/MNINonLinear/Results/fMRI_CONCAT_ALL/tICA_d<N> where <N> denotes the number of temporal ICA components. To inspect the components you can create a wb_command scene file:

GroupAverageName='hcp_group'
tICADim=<N>
TemplateFolder="/gpfs/gibbs/pi/n3/software/HCP/HCPpipelines/global/templates/tICA"
ResultsFolder="<path_to_study_folder>/sessions/hcp_group/hcp_group/MNINonLinear/Results/fMRI_CONCAT_ALL/tICA_d<N>"
TemplateComponentScene="${TemplateFolder}/tICA.scene"
ResultComponentSceneFile="${ResultsFolder}/tICA_hcp_group.scene"
ResultComponentSceneFileFinal="${ResultsFolder}/tICA_hcp_group_final.scene"
cp ${TemplateComponentScene} ${ResultComponentSceneFile}
cat "${TemplateComponentScene}" | sed s/ExampleGroupAverageName/${GroupAverageName}/g | sed s/ExampleDim/${tICADim}/g >| "${ResultComponentSceneFile}"

Your scene file called tICA_hcp_group.scene will be created in <path_to_study_folder>/sessions/hcp_group/hcp_group/MNINonLinear/Results/fMRI_CONCAT_ALL/tICA_d<N>. You can then zip the scene file in order to download it and explore it with Workbench on your computer:

cd ${ResultsFolder}
wb_command -zip-scene-file \
    tICA_hcp_group.scene \
    tICA_hcp_group_fMRI_CONCAT_ALL \
    -skip-missing \
    tICA_hcp_group_fMRI_CONCAT_ALL.zip

MATLAB large variable error:

If receiving an error in MATBAL saying that a variable was not saved because it is larger than 2GB, you need to set the default saving format in MATLAB, to do this run MATLAB and execute:

s = settings();
s.matlab.general.matfile.SaveFormat.PersonalValue = 'v7.3';

Mapping of QuNex parameters onto HCP temporal ICA parameters:

Below is a detailed specification about how QuNex parameters are mapped onto the HCP temporal ICA parameters.

QuNex parameter	HCP temporal ICA parameter
`hcp_tica_bolds`	`fmri-names`
`hcp_tica_outfmriname`	`output-fmri-name`
`hcp_tica_surfregname`	`surf-reg-name`
`hcp_tica_procstring`	`proc-string`
`hcp_outgroupname`	`out-group-name`
`hcp_bold_res`	`fmri-resolution`
`hcp_tica_timepoints`	`subject-expected-timepoints`
`hcp_tica_num_wishart`	`num-wishart`
`hcp_lowresmesh`	`low-res`
`hcp_tica_mrfix_concat_name`	`mrfix-concat-name`
`hcp_tica_icamode`	`ica-mode`
`hcp_tica_precomputed_clean_folder`	`precomputed-clean-folder`
`hcp_tica_precomputed_fmri_name`	`precomputed-clean-fmri-name`
`hcp_tica_precomputed_group_name`	`precomputed-group-name`
`hcp_tica_extra_output_suffix`	`extra-output-suffix`
`hcp_tica_pca_out_dim`	`pca-out-dim`
`hcp_tica_pca_internal_dim`	`pca-internal-dim`
`hcp_tica_migp_resume`	`migp-resume`
`hcp_tica_sicadim_iters`	`sicadim-iters`
`hcp_tica_sicadim_override`	`sicadim-override`
`hcp_low_sica_dims`	`low-sica-dims`
`hcp_tica_reclean_mode`	`reclean-mode`
`hcp_tica_starting_step`	`starting-step`
`hcp_tica_stop_after_step`	`stop-after-step`
`hcp_tica_remove_manual_components`	`manual-components-to-remove`
`hcp_tica_fix_legacy_bias`	`fix-legacy-bias`
`hcp_parallel_limit`	`parallel-limit`
`hcp_tica_config_out`	`config-out`
`hcp_matlab_mode`	`matlab-run-mode`

Examples

Example run:

qunex hcp_temporal_ica \
    --sessionsfolder="<path_to_study_folder>/sessions" \
    --batchfile="<path_to_study_folder>/processing/batch.txt" \
    --hcp_tica_bolds="fMRI_CONCAT_ALL" \
    --hcp_tica_outfmriname="fMRI_CONCAT_ALL" \
    --hcp_tica_mrfix_concat_name="fMRI_CONCAT_ALL" \
    --hcp_tica_surfregname="MSMAll" \
    --hcp_icafix_highpass="0" \
    --hcp_outgroupname="hcp_group" \
    --hcp_tica_timepoints="<value can be found in hcp_post_fix logs>" \
    --hcp_tica_num_wishart="6" \
    --hcp_matlab_mode="interpreted"

QuNex documentation

hcp_temporal_ica

hcp_temporal_ica#