subseg_getvol

subcortexmesh.subseg_getvol.subseg_getvol(inputdir: str | Path, outputdir: str | Path, template: str, toolboxdata: str | Path | None = None, overwrite: bool = True, silent: bool = False)[source]

Extracting and coregistering subcortical volumes from a cohort’s subcortical volumes

This function reads through subjects of a FreeSurfer or FSL FIRST output preprocessing directory and identifies subcortical segmentation volumes. Typically, such volumes are “aseg.mgz” for FreeSurfer, and “*all_fast_firstseg” for FSL FIRST (plus, if applicable, “*Cereb_first.nii.gz”). For each subject, subseg_getvol() uses antspy to coregister the segmentation volumes to their respective template space (fsaverage/MNI305 for FreeSurfer, MNI152 for FSL), and then extracts each subcortical region-of-interest separately.

T1 volumes are required for the coregistration, stored as [sub-ID]/mri/T1.mgz for FreeSurfer and expected to be stored in the same “inputdir” path for FSL FIRST: the function will search for files containing the sub-ID and the “T1w.nii” pattern for each subject.

Parallel processes: to avoid conflicts, subjects will be skipped if a “isrunning” tmp file exists to mark them as currently processing. The tmp file is removed at the end or replaced if 1 hour old. If a process has been interrupted, remove the tmp manually to rerun a subject before the 1 hour (its path is printed when flagged).

Note for (optional) FSL cerebellar segmentation: the cerebella need to be created inside the same output directory as run_first_all’s, naming them “*R_Cereb_first” and “*L_Cereb_first”. It can be done as follows (do the same for L_Cereb):

first_flirt [subject T1file] "[subject_directory]/[sub-id]" -cort
run_first -i [subject T1file] \
    -t "[subject_directory]/[sub-id_cort.mat]" \
    -n 40 \
    -o "[subject_directory]/[sub-id]-R_Cereb_first" \
    -m "${FSLDIR}/data/first/models_336_bin/intref_puta/R_Cereb.bmv" \
    -intref "${FSLDIR}/data/first/models_336_bin/05mm/R_Puta_05mm.bmv"
Parameters:

  • inputdir (str, Path) – The path to a directory containing each individual subject’s directory with preprocessing data inside. For FreeSurfer, typically the $SUBJECTS_DIR given to the recon-all pipeline. For FSL, a directory with one subdirectory per subject, each receiving its output from run_first_all.

  • outputdir (str, Path) – The path where subcortical volumes will be saved (creates the “sub_volumes” directory).

  • toolboxdata (str, Path, optional) – The path of the “subcortexmesh_data” package data directory. The default path is assumed to be the user’s home directory (pathlib’s Path.home()). Users will be prompted to download it if not found.

  • template (str) – The name of the template the surfaces are supposed to be matching to. For FreeSurfer outputs, it is ‘fsaverage’. For FSL FIRST, it is ‘fslfirst’.

  • overwrite (bool) – Whether files are to be overwritten or skipped if already in outputdir. Default is True.

  • silent (bool) – Whether messages about the process are to be silenced. Default is False.