API#

Pydra tasks for FreeSurfer.

Recon-All

The main task definition for recon-all can be imported directly from the root package.

>>> from pydra.tasks.freesurfer import ReconAll

Additional task definitions are available under the recon_all namespace for more advanced use cases.

>>> from pydra.tasks.freesurfer.recon_all import BaseReconAll, LongReconAll

Volume Utilities

Task definitions for volume processing utilities are available under the mri namespace.

>>> from pydra.tasks.freesurfer import mri

Surface Utilities

Task definitions for surface processing utilities are available under the mris namespace.

>>> from pydra.tasks.freesurfer import mris

GTMSeg#

Examples

>>> task = GTMSeg(subject_id="subject", generate_segmentation=True)
>>> task.cmdline
'gtmseg --s subject --o gtmseg.mgz --xcerseg'

>>> task = GTMSeg(
...     subject_id="subject",
...     keep_hypointensities=True,
...     subsegment_white_matter=True,
...     output_volume="gtmseg.wmseg.hypo.mgz",
...     upsampling_factor=1,
...     generate_segmentation=False,
... )
>>> task.cmdline
'gtmseg --s subject --o gtmseg.wmseg.hypo.mgz --no-xcerseg --usf 1 --keep-hypo --subsegwm'

>>> task = GTMSeg(
...     subject_id="subject",
...     output_volume="gtmseg+myseg.mgz",
...     head_segmentation="apas+head+myseg.mgz",
...     colortable="myseg.colortable.txt",
... )
>>> task.cmdline
'gtmseg --s subject --o gtmseg+myseg.mgz --head apas+head+myseg.mgz --ctab myseg.colortable.txt'

Volume Utilities#

Aparc2Aseg#

Maps the cortical labels from the automatic cortical parcellation (aparc) to the automatic segmentation volume (aseg).

Examples

>>> task = Aparc2Aseg(subject_id="subjid", annotation_file="atlas.annot", output_image="atlas.mgz")
>>> task.cmdline
'mri_aparc2aseg --s subjid --o atlas.mgz --new-ribbon --annot atlas.annot'

Binarize#

Binarize a volume (or volume-encoded surface file) based on thresholds or match values. Can also be used to merge other results of binarization.

Examples

>>> task = Binarize(input_volume="aseg.nii.gz", min_value=1000, max_value=1999, bin_value=1)
>>> task.cmdline  
'mri_binarize --i aseg.nii.gz --min 1000 --max 1999 --o ...aseg_mask.nii.gz --count ...aseg_count.txt --binval 1'

Convert#

General purpose utility for converting between different file formats.

Examples

Convert volume data to float:

>>> task = Convert(input_volume="orig.nii.gz", output_volume="float.nii.gz", output_datatype="float")
>>> task.cmdline
'mri_convert -odt float orig.nii.gz float.nii.gz'

Coreg#

Perform linear registration between two volumes similar to SPM’s spm_coreg.

Examples

>>> task = Coreg(source_volume="template.nii", target_volume="orig.mgz", degrees_of_freedom=12)
>>> task.cmdline    
'mri_coreg --mov template.nii --ref orig.mgz --reg .../template_coreg.lta --regdat .../template_coreg.dat --dof 12 ...'

Label2Vol#

Converts a label or a set of labels to a volume.

For a single label, the output volume will be binary: 1 where the label is and 0 where it is not.

For multiple labels, the output volume will be 0 where no labels were found, otherwise the value will be the label number.

For a voxel to be assigned a label, it must have enough hits in the voxel (threshold parameter) and more hits than any other label.

Examples

1. Convert a label to a binary mask in the functional space. Require that a functional voxel be filled at least 50% by the label.

>>> task = Label2Vol(
...     label_file="lh-avg_central_sulcus.label",
...     template_volume="f.nii.gz",
...     registration_file="register.dat",
...     threshold=0.5,
...     output_volume="cent-lh.nii.gz",
... )
>>> task.cmdline  
'mri_label2vol --label lh-avg_central_sulcus.label --temp f.nii.gz --reg register.dat --fillthresh 0.5 --o cent-lh.nii.gz'

2. Convert a surface label into a binary mask in the functional space. Fill in all the cortical gray matter. Require that a functional voxel be filled at least 30% by the label.

>>> task = Label2Vol(
...     label_file="lh-avg_central_sulcus.label",
...     template_volume="f.nii.gz",
...     registration_file="register.dat",
...     threshold=0.3,
...     projection=["frac", 0, 1, 0.1],
...     subject_id="bert",
...     hemisphere="lh",
...     output_volume="cent-lh.nii.gz",
... )
>>> task.cmdline  
'mri_label2vol --label lh-avg_central_sulcus.label --temp f.nii.gz --reg register.dat --fillthresh 0.3 --proj frac 0 1 0.1 --subject bert --o cent-lh.nii.gz --hemi lh'

3. Convert a surface label into a binary mask in the functional space. Sample a 1mm ribbon 2mm below the gray / white surface. Do not require a fill threshold.

>>> task = Label2Vol(
...     label_file="lh-avg_central_sulcus.label",
...     template_volume="f.nii.gz",
...     registration_file="register.dat",
...     projection=["abs", -3, -2, 0.1],
...     subject_id="bert",
...     hemisphere="lh",
...     output_volume="cent-lh.nii.gz",
... )
>>> task.cmdline  
'mri_label2vol --label lh-avg_central_sulcus.label --temp f.nii.gz --reg register.dat --proj abs -3 -2 0.1 --subject bert --o cent-lh.nii.gz --hemi lh'

4. Convert two labels into a volume in the same space as the labels. The voxels corresponding to lh-avg_central_sulcus.label will have a value of 1 whereas those assigned to lh-avg_calcarine_sulcus.label will have a value of 2.

>>> task = Label2Vol(
...     label_files=["lh-avg_central_sulcus.label", "lh-avg_calcarine_sulcus.label"],
...     template_volume="$SUBJECTS_DIR/bert/orig",
...     no_registration=True,
...     output_volume="cent_calc.img",
... )
>>> task.cmdline
'mri_label2vol --label lh-avg_central_sulcus.label --label lh-avg_calcarine_sulcus.label --temp $SUBJECTS_DIR/bert/orig --identity --o cent_calc.img'

RobustRegister#

Symmetrically align a source to a target volume using a method based on robust statistics to detect outliers and removes them from the registration.

Examples

>>> task = RobustRegister(source_volume="src.mgz", target_volume="trg.mgz")
>>> task.cmdline    
'mri_robust_register --mov src.mgz --dst trg.mgz --lta .../src_xfm.lta --satit --mapmov .../src_resampled.mgz --mapmovhdr .../src_aligned.mgz --weights .../src_weights.mgz'

RobustTemplate#

Construct an unbiased template from longitudinal volumes using an iterative algorithm to compute an average volume.

Examples

>>> task = RobustTemplate(
...     input_volumes=["tp1.mgz", "tp2.mgz", "tp3.mgz"],
...     output_volume="mean.mgz",
...     output_transforms=["tp1.lta", "tp2.lta", "tp3.lta"],
...     method="mean",
...     enable_intensity_scaling=True,
... )
>>> task.cmdline
'mri_robust_template --mov tp1.mgz tp2.mgz tp3.mgz --template mean.mgz --satit --lta tp1.lta tp2.lta tp3.lta --average 0 --iscale'

parcellation_tableSurf2Surf#

Resamples data from one surface onto another. If both the source and target subjects are the same, this is just a format conversion.

Examples

1. Resample a subject’s thickness of the left cortical hemisphere on to a 7th order icosahedron and save in analyze4d format:

>>> task = Surf2Surf(
...     hemisphere="lh",
...     source_subject_id="bert",
...     source_surface="thickness",
...     source_format="curv",
...     target_subject_id="ico",
...     target_icosahedron_order=7,
...     target_surface="bert-thickness-lh.img",
...     target_format="analyze4d",
... )
>>> task.cmdline
'mri_surf2surf --srcsubject bert --sval thickness --sfmt curv --trgsubject ico --trgicoorder 7 --tval bert-thickness-lh.img --tfmt analyze4d --hemi lh'

Resample data on the icosahedron to the right hemisphere of subject bert:

>>> task = Surf2Surf(
...     hemisphere="rh",
...     source_subject_id="ico",
...     source_surface="icodata-rh.mgh",
...     target_subject_id="bert",
...     target_surface="bert-ico-rh.mgh",
... )
>>> task.cmdline
'mri_surf2surf --srcsubject ico --sval icodata-rh.mgh --trgsubject bert --tval bert-ico-rh.mgh --hemi rh'

Convert the surface coordinates of the lh.white of a subject to a (talairach) average:

>>> task = Surf2Surf(
...     source_subject_id="yoursubject",
...     use_vertex_coordinates_in_talairach="white",
...     target_subject_id="youraveragesubject",
...     target_surface="lh.white.yoursubject",
...     save_vertex_coordinates_from_file="$SUBJECTS_DIR/fsaverage/mri/orig.mgz",
... )
>>> task.cmdline
'mri_surf2surf --srcsubject yoursubject --sval-tal-xyz white --trgsubject youraveragesubject --tval lh.white.yoursubject --tval-xyz $SUBJECTS_DIR/fsaverage/mri/orig.mgz'

Convert the surface coordinates of the lh.white of a subject to the subject’s functional space:

>>> task = Surf2Surf(
...     registration_file="register.lta",
...     hemisphere="lh",
...     use_vertex_coordinates_in_surface="white",
...     save_vertex_coordinates_from_file="template.nii.gz",
...     target_surface="./lh.white.func",
...     source_subject_id="yoursubject",
... )
>>> task.cmdline
'mri_surf2surf --srcsubject yoursubject --sval-xyz white --reg register.lta --tval ./lh.white.func --tval-xyz template.nii.gz --hemi lh'

Extract surface normals of the white surface and save in a volume-encoded file:

>>> task = Surf2Surf(
...     source_subject_id="yoursubject",
...     hemisphere="lh",
...     use_vertex_normal_coordinates="white",
...     target_surface="lh.white.norm.mgh",
... )
>>> task.cmdline
'mri_surf2surf --srcsubject yoursubject --sval-nxyz white --tval lh.white.norm.mgh --hemi lh'

Convert the annotation for one subject to the surface of another:

>>> task = Surf2Surf(
...     source_subject_id="subj1",
...     target_subject_id="subj2",
...     hemisphere="lh",
...     source_annotation_file="$SUBJECTS_DIR/subj1/label/lh.aparc.annot",
...     target_annotation_file="$SUBJECTS_DIR/subj2/label/lh.subj1.aparc.annot",
... )
>>> task.cmdline
'mri_surf2surf --srcsubject subj1 --sval-annot $SUBJECTS_DIR/subj1/label/lh.aparc.annot --trgsubject subj2 --tval $SUBJECTS_DIR/subj2/label/lh.subj1.aparc.annot --hemi lh'

Vol2Vol#

Resamples a volume into another field-of-view using various types of matrices (FreeSurfer, FSL, SPM, and MNI).

This is meant to be used in conjunction with tkregister2.

Examples

Resample functional data into anatomical space:

>>> task = Vol2Vol(
...     moving_volume="func.nii.gz",
...     output_volume="func-in-anat.mgh",
...     registration_file="register.dat",
...     use_registered_volume_as_target=True,
... )
>>> task.cmdline
'mri_vol2vol --mov func.nii.gz --o func-in-anat.mgh --reg register.dat --fstarg'

Resample anatomical data into functional space:

>>> task = Vol2Vol(
...     moving_volume="func.nii.gz",
...     output_volume="anat-in-func.mgh",
...     registration_file="register.dat",
...     use_registered_volume_as_target=True,
...     invert_transform=True,
... )
>>> task.cmdline
'mri_vol2vol --mov func.nii.gz --o anat-in-func.mgh --reg register.dat --fstarg --inv'

Map functional to anatomical without resampling:

>>> task = Vol2Vol(
...     moving_volume="func.nii.gz",
...     output_volume="func.new.vox2ras.nii.gz",
...     registration_file="register.dat",
...     use_registered_volume_as_target=True,
...     no_resampling=True,
... )
>>> task.cmdline
'mri_vol2vol --mov func.nii.gz --o func.new.vox2ras.nii.gz --reg register.dat --fstarg --no-resample'

Map a binary mask in functional space to anatomical space:

>>> task = Vol2Vol(
...     moving_volume="mask.nii.gz",
...     output_volume="mask-in-anat.mgh",
...     registration_file="register.dat",
...     use_registered_volume_as_target=True,
...     interpolation="nearest",
... )
>>> task.cmdline
'mri_vol2vol --mov mask.nii.gz --o mask-in-anat.mgh --reg register.dat --fstarg --interp nearest'

Map functional data to talairach (MNI305) space with 2mm isotropic resolution:

>>> task = Vol2Vol(
...     moving_volume="func.nii.gz",
...     output_volume="func-in-tal.2mm.mgh",
...     registration_file="register.dat",
...     resample_to_talairach=True,
...     talairach_resolution=2,
... )
>>> task.cmdline
'mri_vol2vol --mov func.nii.gz --o func-in-tal.2mm.mgh --reg register.dat --tal --talres 2'

Apply an MNI transform by resampling the anatomical data into talairach space:

>>> task = Vol2Vol(
...     moving_volume="orig.mgz",
...     target_volume="$FREESURFER_HOME/average/mni305.cor.mgz",
...     output_volume="orig-in-mni305.mgz",
...     xfm_registration_file="transforms/talairach.xfm",
... )
>>> task.cmdline
'mri_vol2vol --mov orig.mgz --targ $FREESURFER_HOME/average/mni305.cor.mgz --o orig-in-mni305.mgz --xfm transforms/talairach.xfm'

Surface Utilities#

AnatomicalStats#

Computes a number of anatomical properties.

Examples

>>> task = AnatomicalStats(subject_id="subjid", hemisphere="lh", annotation_file="lh.aparc.annot")
>>> task.cmdline    
'mris_anatomical_stats -a lh.aparc.annot -f ...lh.white.stats -log ...lh.white.log subjid lh white'

>>> task = AnatomicalStats(subject_id="subjid", hemisphere="lh", label_file="lh.cortex.label")
>>> task.cmdline    
'mris_anatomical_stats -l lh.cortex.label -f ...lh.white.stats -log ...lh.white.log subjid lh white'

CALabel#

Assign an anatomical label to each cortical surface vertex.

Examples

>>> task = CALabel(
...     subject_id="my_subject",
...     hemisphere="lh",
...     canonical_surface="sphere.reg",
...     surface_atlas="lh.rahul.gcs",
...     original_surface="white",
...     no_covariance=True,
...     parcellation_table="colortable.txt",
...     atlas_name="rahul",
... )
>>> task.cmdline  
'mris_ca_label -orig white -novar -t colortable.txt my_subject lh sphere.reg lh.rahul.gcs ...lh.rahul.annot'

CATrain#

Examples

>>> task = CATrain(
...     hemisphere="lh",
...     canonical_surface="sphere.reg",
...     annotation_file="my_manual_labeling",
...     subject_ids=["subj1", "subj2"],
...     parcellation_table="colortable.txt",
... )
>>> task.cmdline  
'mris_ca_train -orig smoothwm -t colortable.txt -n 2 lh sphere.reg my_manual_labeling subj1 subj2 ...lh.my_atlas.gcs'

Expand#

Expand a surface outwards by a specified amount while maintaining smoothness and self-intersection constraints.

Examples

Expand by cortical thickness:

>>> task = Expand(input_surface="lh.white", distance=0.5, use_thickness=True)
>>> task.cmdline    
'mris_expand -thickness lh.white 0.5 ...lh_expand.white'

Expand by distance from label:

>>> task = Expand(input_surface="lh.white", distance=0.5, output_surface="lh.graymid", label_file="labelfile")
>>> task.cmdline
'mris_expand -label labelfile lh.white 0.5 lh.graymid'

Preproc#

Script to prepare surface-based data for high-level analysis by resampling surface or volume source data to a common subject (usually an average subject) and then concatenating them into one file which can then be used by a number of programs (eg, mri_glmfit).

Examples

>>> source_subject_ids = [f"abc{s:02d}-anat" for s in range(1, 5)]

Resample abcXX-anat/surf/lh.thickness onto fsaverage:

>>> task = Preproc(
...     source_subject_ids=source_subject_ids,
...     target_subject_id="fsaverage",
...     hemisphere="lh",
...     measure="thickness",
...     output_surface="abc-lh-thickness.mgh",
... )
>>> task.cmdline
'mris_preproc --out abc-lh-thickness.mgh --target fsaverage --hemi lh --meas thickness --s abc01-anat --s abc02-anat --s abc03-anat --s abc04-anat'

Same as above but using a fsgd file (which would have the abcXXs as Inputs):

>>> task = Preproc(
...     fsgd_file="abc.fsgd",
...     target_subject_id="fsaverage",
...     hemisphere="lh",
...     measure="thickness",
...     output_surface="abc-lh-thickness.mgh",
... )
>>> task.cmdline
'mris_preproc --out abc-lh-thickness.mgh --target fsaverage --hemi lh --meas thickness --fsgd abc.fsgd'

Same as #1 with additional smoothing by 5mm:

>>> task = Preproc(
...     source_subject_ids=source_subject_ids,
...     target_subject_id="fsaverage",
...     hemisphere="lh",
...     measure="thickness",
...     output_surface="abc-lh-thickness.sm5.mgh",
...     target_smoothing=5,
... )
>>> task.cmdline
'mris_preproc --out abc-lh-thickness.sm5.mgh --target fsaverage --hemi lh --meas thickness --s abc01-anat --s abc02-anat --s abc03-anat --s abc04-anat --fwhm 5'

Same as #1 but using full paths.

>>> task = Preproc(
...     target_subject_id="fsaverage",
...     hemisphere="lh",
...     output_surface="abc-lh-thickness.mgh",
...     fsgd_file="abc.fsgd",
...     source_format="curv",
...     input_surface_paths=[f"abc{s:02d}-anat/surf/lh.thickness" for s in range(1, 5)],
... )
>>> task.cmdline
'mris_preproc --out abc-lh-thickness.mgh --target fsaverage --hemi lh --fsgd abc.fsgd --isp abc01-anat/surf/lh.thickness --isp abc02-anat/surf/lh.thickness --isp abc03-anat/surf/lh.thickness --isp abc04-anat/surf/lh.thickness --srcfmt curv'

Same as #2 but computes paired differences.

>>> task = Preproc(
...     fsgd_file="abc.fsgd",
...     target_subject_id="fsaverage",
...     hemisphere="lh",
...     measure="thickness",
...     output_surface="abc-lh-thickness-pdiff.mgh",
...     compute_paired_differences=True,
... )
>>> task.cmdline
'mris_preproc --out abc-lh-thickness-pdiff.mgh --target fsaverage --hemi lh --meas thickness --fsgd abc.fsgd --paired-diff'

ReconAll#

Performs all, or any part of, the FreeSurfer cortical reconstruction process.

Examples

Cross-sectionally process timepoints:

>>> task = ReconAll(subject_id="tp1", t1_volume="/path/to/tp1.dcm")
>>> task.cmdline
'recon-all -subjid tp1 -i /path/to/tp1.dcm -all'

Create and process the unbiased base template:

>>> task = BaseReconAll(base_template_id="longbase", base_timepoint_ids=["tp1", "tp2"])
>>> task.cmdline
'recon-all -base longbase -base-tp tp1 -base-tp tp2 -all'

Longitudinally process timepoints:

>>> task = LongReconAll(longitudinal_timepoint_id="tp1", longitudinal_template_id="longbase")
>>> task.cmdline
'recon-all -long tp1 longbase -all'

TkRegister2#

Linear registration between two volumes, mainly for the purpose of interacting with the FreeSurfer anatomical stream.

Examples

Create a registration matrix between the conformed space (orig.mgz) and the native anatomical (rawavg.mgz):

>>> task = TkRegister2(moving_volume="rawavg.mgz", target_volume="orig.mgz", register_from_headers=True)
>>> task.cmdline    
'tkregister2 --noedit --mov rawavg.mgz --targ orig.mgz --reg ...rawavg_tkregister2.dat --regheader'