hcp_nhp_freesurfer

qx_utilities.hcp.hcp_nhp_freesurfer.hcp_nhp_freesurfer(sinfo, options, overwrite=False, thread=0)

hcp_nhp_freesurfer [... processing options]

Runs the NHP (non-human primate) variant of the FS step of the HCP Pipeline (FreeSurferPipelineNHP.sh).

Warning

The code expects the previous step (hcp_pre_freesurfer) to have run successfully and checks for presence of a few key files and folders. Due to the number of inputs that it requires, it does not make a full check for all of them!

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.

--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 logs are to be stored, if other than default.

--hcp_processing_mode (str, default 'HCPStyleData'):

Controls whether the HCP acquisition and processing guidelines should be treated as requirements ('HCPStyleData') or if additional processing functionality is allowed ('LegacyStyleData'). In this case running processing w/o a T2w image.

--hcp_folderstructure (str, default 'hcpls'):

If set to 'hcpya' the folder structure used in the initial HCP Young Adults study is used. Specifically, the source files are stored in individual folders within the main 'hcp' folder in parallel with the working folders and the 'MNINonLinear' folder with results. If set to 'hcpls' the folder structure used in the HCP Life Span study is used. Specifically, the source files are all stored within their individual subfolders located in the joint 'unprocessed' folder in the main 'hcp' folder, parallel to the working folders and the 'MNINonLinear' folder.

--hcp_filename (str, default 'automated'):

How to name the BOLD files once mapped intothe hcp input folder structure. The default ('automated') will automatically name each file by their number (e.g. BOLD_1). The alternative ('userdefined') is to use the file names, which can be defined by the user prior to mapping (e.g. rfMRI_REST1_AP).

--hcp_species (str, default ''):

Species type (required). Controls species-specific processing parameters. One of: Human, Chimp, MacaqueCyno, MacaqueRhesus, MacaqueSnow, NightMonkey, Marmoset.

--hcp_scale_factor (str, default ''):

Brain scale factor for NHP processing (required). Controls volume rescaling for FreeSurfer and some derived parameters. The recommended value is the BrainScaleFactor defined in the species' SetUp script.

--hcp_runmode (str, default ''):

Specify from which step to resume the processing instead of starting from the beginning. Value must be one of: Default, FSinit, FSbrainseg, FSsurfinit, FShires, FSFinish (default: Default).

--hcp_fs_seed (str, default ''):

Recon-all seed value. If not specified, none will be used.

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

Indicates whether manual edits are to be applied to the FreeSurfer outputs. If set to 'TRUE', the user needs to either place the edited files in <sessions folder>/inbox/FS_edits and prepend '<session id>_' to identify them, or place them in the standard FreeSurfer location themselves. The 'existing_session' parameter will be set to TRUE, and 'extra_reconall' parameters will be set as well to only run the necessary steps to incorporate the edits, depending on the edits present and/or specified. This option can be used for edits to control.dat, aseg.mgz, wm.mgz, and brainmask.mgz files. Accepted values are 'FALSE', 'TRUE', or a comma-separated list of edits to apply: 'control', 'aseg', 'wm', 'brainmask'. If edits are not specified explicitly, they will be determined based on the files found in the FS_edits folder.

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

Indicates that the command is to be run on top of an already existing analysis/subject. This excludes the -i flag from the invocation of recon-all. If set, the user needs to specify which recon-all stages to run using the --hcp_fs_extra_reconall parameter. Accepted values are 'TRUE' and 'FALSE'.

--hcp_fs_extra_reconall (str, default ''):

A string with extra parameters to pass to FreeSurfer recon-all. The extra parameters are to be listed in a pipe ('|') separated string. Parameters and their values need to be listed separately. E.g. to pass -norm3diters 3 to reconall, the string has to be: "-norm3diters|3".

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

If set to 'TRUE' indicates that recon-all is to be run with the -FLAIR/-FLAIRpial options (rather than the -T2/-T2pial options). The FLAIR input image itself should be provided as a regular T2w image.

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

If set to 'TRUE' indicates that recon-all is to be run with the -T1wDivFLAIR/-T1wDivFLAIRpial options (rather than the -T2/-T2pial options). The T1w/FLAIR input image itself should be provided as a regular T2w image. NOTE: This is experimental.

--hcp_conf2hires (str, 'TRUE'):

Whether to use the conf2hires flag in recon-all. If set to 'TRUE', the flag will be used, if set to 'FALSE' it will not be used.

--hcp_t2 (str, default 't2'):

'NONE' if no T2w image is available and the preprocessing should be run without them, anything else otherwise. 'NONE' is only valid if 'LegacyStyleData' processing mode was specified.

--hcp_expert_file (str, default ''):

Path to the read-in expert options file for FreeSurfer if one is prepared and should be used empty otherwise.

Output files

The results of this step will be present in the above mentioned T1w folder as well as MNINonLinear folder in the sessions's root hcp folder.

Notes

Runs the NHP variant of the FreeSurfer (FreeSurferPipelineNHP.sh) step of the HCP Pipelines. It takes the T1w and T2w images processed in the previous (hcp_pre_freesurfer) step, segments T1w image by brain matter and CSF, reconstructs the cortical surface of the brain and assigns structure labels for both subcortical and cortical structures, using species-specific templates and parameters selected via the hcp_species and hcp_scale_factor parameters.

hcp_nhp_freesurfer parameter mapping:

QuNex parameter	HCPpipelines parameter
hcp_species	species
hcp_scale_factor	scale-factor
hcp_runmode	runmode
hcp_fs_seed	seed
hcp_processing_mode	processing-mode
hcp_fs_existing_session	existing-subject
hcp_fs_extra_reconall	extra-reconall-arg
hcp_conf2hires	conf2hires
hcp_fs_flair	flair
hcp_fs_t1wdivflair	t1wdivflair

Running FreeSurfer again after PostFreeSurfer:

If FreeSurfer has to be run again after PostFreeSurfer, the files generated during PostFreeSurfer need to be removed to prevent any conflicts. For this reason, when PostFreeSurfer is run, QuNex records the list of files generated during PostFreeSurfer and backs up files known to be modified by PostFreeSurfer. When FreeSurfer is run again, files generated by PostFreeSurfer are removed and the backed up files are restored.

Running with FreeSurfer edits:

Sometimes, after visual inspection of the FreeSurfer outputs, manual edits are needed to correct for misclassified regions. If such edits have been made, they can be applied during the FreeSurfer step as described for hcp_freesurfer, using the hcp_fs_edits, hcp_fs_existing_session and hcp_fs_extra_reconall parameters.

Examples

Example run from the base study folder with test flag:

qunex hcp_nhp_freesurfer \
    --batchfile="processing/batch.txt" \
    --sessionsfolder="sessions" \
    --parsessions="10" \
    --species="MacaqueRhesus" \
    --hcp_scale_factor="1.25" \
    --overwrite="no" \
    --test

Example run with absolute paths with scheduler:

qunex hcp_nhp_freesurfer \
    --batchfile="<path_to_study_folder>/processing/batch.hcp.txt" \
    --sessionsfolder="<path_to_study_folder>/sessions" \
    --parsessions="4" \
    --species="Marmoset" \
    --hcp_scale_factor="0.2" \
    --overwrite="yes" \
    --scheduler="SLURM,time=24:00:00,cpus-per-task=2,mem-per-cpu=1250,partition=day"