cortex.freesurfer.import_subj

cortex.freesurfer.import_subj(freesurfer_subject, pycortex_subject=None, freesurfer_subject_dir=None, whitematter_surf='smoothwm', autoflatten=True, autoflatten_args=None)

Imports a subject from freesurfer

This will overwrite (after giving a warning and an option to continue) the pre-existing subject, including all blender cuts, masks, transforms, etc., and re-generate surface info files (curvature, sulcal depth, thickness) stored in the surfinfo/ folder for the subject. All cached files for the subject will be deleted.

Parameters:

freesurfer_subjectstr

Freesurfer subject name

pycortex_subjectstr, optional

Pycortex subject name. By default it uses the freesurfer subject name. It is advised to stick to that convention, if possible (your life will go more smoothly.)

freesurfer_subject_dirstr, optional

Freesurfer subject directory to pull data from. By default uses the directory given by the environment variable $SUBJECTS_DIR.

whitematter_surfstr, optional

Which whitematter surface to import as ‘wm’. By default uses ‘smoothwm’, but that surface is smoothed and may not be appropriate. A good alternative is ‘white’.

autoflattenbool, optional

Whether to automatically cut and flatten the surfaces with autoflatten after importing them (True by default), see autoflatten_subject. This step takes a while, typically 15-30 minutes for both hemispheres; set it to False to skip it and cut and flatten the surfaces yourself (or run autoflatten_subject later). autoflatten is an optional dependency; if it is not installed, a warning is issued and this step is skipped.

autoflatten_argslist of str, optional

Extra command line arguments passed to autoflatten run, for example ["--backend", "freesurfer"]. Ignored if autoflatten is False.

Notes

This function uses command line functions from freesurfer, so you should make sure to have freesurfer sourced before running this function.

This function will also generate the fiducial surfaces for the subject, which are halfway between the white matter and pial surfaces. The surfaces will be stored in the freesurfer subject’s directory. These fiducial surfaces are used for cutting and flattening.

Imported files

Only the files listed below are copied over. They are read from the freesurfer subject directory, {freesurfer_subject_dir}/{freesurfer_subject}/, and written into the pycortex filestore entry for the subject, {pycortex_filestore}/{pycortex_subject}/. Flat surfaces are created and imported by autoflatten_subject at the end of this function, unless autoflatten is False; to import flat surfaces that were cut and flattened by hand, use import_flat. Labels and annotations are not imported; use get_label for those.

Anatomical volumes, converted with mri_convert:

freesurfer file	pycortex file	contents
mri/T1.mgz	anatomicals/raw.nii.gz	T1-weighted anatomical
mri/aseg.mgz	anatomicals/aseg.nii.gz	automatic segmentation
mri/wm.mgz	anatomicals/raw_wm.nii.gz	white matter segmentation

Surfaces, for both hemispheres (lh and rh), converted with mris_convert --to-scanner so that they share the coordinate system of the anatomical volumes rather than freesurfer’s TKR coordinate system:

freesurfer file	pycortex file	contents
surf/?h.smoothwm	surfaces/wm_?h.gii	white matter surface
surf/?h.pial	surfaces/pia_?h.gii	pial surface
surf/?h.inflated	surfaces/inflated_?h.gii	inflated surface

The white matter surface that is imported as wm is whichever surface is named by the whitematter_surf parameter (smoothwm by default), so the first row above reads surf/?h.{whitematter_surf}.

Surface info, where both hemispheres are stored together in a single .npz file with the keys left and right. Note that the values are stored negated with respect to the freesurfer values:

freesurfer files	pycortex file	contents
surf/?h.sulc	surface-info/sulcaldepth.npz	sulcal depth
surf/?h.thickness	surface-info/thickness.npz	cortical thickness
surf/?h.curv	surface-info/curvature.npz	curvature