hcp_temporal_ica
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 toComputeTICAFeatures
. After the manual classification bothhcp_tica_starting_step
andhcp_tica_stop_after_step
need to be set toCleanData
.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 thehcp post_fix
logs under the labelNumTimePoints
. If your study has many sessions you also need to set thehcp_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 awb_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"