qsiprep.interfaces.freesurfer module

FreeSurfer tools interfaces

Fetch some example data:

>>> import os
>>> from niworkflows import data
>>> data_root = data.get_bids_examples(variant='BIDS-examples-1-enh-ds054')
>>> os.chdir(data_root)

Disable warnings:

>>> from nipype import logging
>>> logging.getLogger('nipype.interface').setLevel('ERROR')

class qsiprep.interfaces.freesurfer.FSDetectInputs(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

t1w_list (a list of items which are a pathlike object or string representing an existing file) – Input file, part of a BIDS tree.

Optional Inputs:

• flair_list (a list of items which are a pathlike object or string representing an existing file) – Input file, part of a BIDS tree.

• hires_enabled (a boolean) – Enable hi-resolution processing. (Nipype default value: True)

• t2w_list (a list of items which are a pathlike object or string representing an existing file) – Input file, part of a BIDS tree.

Outputs:

• flair (a pathlike object or string representing a file) – Reference FLAIR image.

• hires (a boolean) – Enable hi-res processing.

• mris_inflate (a string) – Mris_inflate argument.

• t2w (a pathlike object or string representing a file) – Reference T2w image.

• use_flair (a boolean) – Enable use of FLAIR downstream computation.

• use_t2w (a boolean) – Enable use of T2w downstream computation.

class qsiprep.interfaces.freesurfer.FSInjectBrainExtracted(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

• in_brain (a pathlike object or string representing an existing file) – Input file, part of a BIDS tree.

• subject_id (a string) – Subject ID.

• subjects_dir (a pathlike object or string representing a directory) – FreeSurfer SUBJECTS_DIR.

Outputs:

• subject_id (a string) – Subject ID.

• subjects_dir (a pathlike object or string representing a directory) – FreeSurfer SUBJECTS_DIR.

class qsiprep.interfaces.freesurfer.FixHeaderSynthStrip(**inputs)

Bases: SynthStrip

Wrapped executable: mri_synthstrip.

Mandatory Inputs:

input_image (a pathlike object or string representing an existing file) – Maps to a command-line argument: -i %s.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• border (an integer) – Mask border threshold in mm. Default is 1. Maps to a command-line argument: -b %d.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• gpu (a boolean) – Maps to a command-line argument: -g.

• no_csf (a boolean) – Exclude CSF from brain border. Maps to a command-line argument: --no-csf.

• num_threads (an integer) – Allows for specifying more threads.

• out_brain (a pathlike object or string representing a file) – Skull stripped image with corrupt sform. Maps to a command-line argument: -o %s.

• out_brain_mask (a pathlike object or string representing a file) – Mask image with corrupt sform. Maps to a command-line argument: -m %s.

• subjects_dir (a pathlike object or string representing an existing directory) – Subjects directory.

Outputs:

• out_brain (a pathlike object or string representing an existing file)

• out_brain_mask (a pathlike object or string representing an existing file)

class qsiprep.interfaces.freesurfer.MakeMidthickness(**inputs)

Bases: MRIsExpand

Wrapped executable: mris_expand.

Variation on MRIsExpand that checks for an existing midthickness/graymid surface, and copies if available.

mris_expand is an expensive operation, so this avoids re-running it when the working directory is lost. If users provide their own midthickness/graymid file, we assume they have created it correctly.

Mandatory Inputs:

• distance (a float) – Distance in mm or fraction of cortical thickness. Maps to a command-line argument: %g (position: -2).

• in_file (a pathlike object or string representing an existing file) – Surface to expand. Maps to a command-line argument: %s (position: -3).

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• dt (a float) – Dt (implicit: 0.25). Maps to a command-line argument: -T %g.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• graymid (a list of items which are any value) – Existing graymid/midthickness file.

• nsurfaces (an integer) – Number of surfacces to write during expansion. Maps to a command-line argument: -N %d.

• out_name (a string) – Output surface file. If no path, uses directory of in_file. If no path AND missing “lh.” or “rh.”, derive from in_file. Maps to a command-line argument: %s (position: -1). (Nipype default value: expanded)

• pial (a string) – Name of pial file (implicit: “pial”) If no path, uses directory of in_file If no path AND missing “lh.” or “rh.”, derive from in_file. Maps to a command-line argument: -pial %s.

• smooth_averages (an integer) – Smooth surface with N iterations after expansion. Maps to a command-line argument: -A %d.

• sphere (a string) – WARNING: Do not change this trait. (Nipype default value: sphere)

• spring (a float) – Spring term (implicit: 0.05). Maps to a command-line argument: -S %g.

• subjects_dir (a pathlike object or string representing an existing directory) – Subjects directory.

• thickness (a boolean) – Expand by fraction of cortical thickness, not mm. Maps to a command-line argument: -thickness.

• thickness_name (a string) – Name of thickness file (implicit: “thickness”) If no path, uses directory of in_file If no path AND missing “lh.” or “rh.”, derive from in_file. Maps to a command-line argument: -thickness_name %s.

• write_iterations (an integer) – Write snapshots of expansion every N iterations. Maps to a command-line argument: -W %d.

Outputs:

out_file (a pathlike object or string representing a file) – Output surface file.

property cmdline

command plus any arguments (args) validates arguments and generates command line

class qsiprep.interfaces.freesurfer.MockSynthSeg(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

A fake version of synthseg for testing.

Mandatory Inputs:

input_image (a pathlike object or string representing an existing file) – Maps to a command-line argument: --i %s.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• cpu (a boolean) – Enforce running with CPU rather than GPU. Maps to a command-line argument: --cpu. (Nipype default value: True)

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• fast (a boolean) – Fast predictions (lower quality). Maps to a command-line argument: --fast.

• num_threads (an integer) – Number of threads to use. Maps to a command-line argument: --threads %d. (Nipype default value: 0)

• out_post (a pathlike object or string representing a file) – Posteriors image. Maps to a command-line argument: --post %s.

• out_qc (a pathlike object or string representing a file) – Qc csv. Maps to a command-line argument: --qc %s.

• out_seg (a pathlike object or string representing a file) – Segmentation image. Maps to a command-line argument: --o %s.

• robust (a boolean) – Use robust predictions (slower). Maps to a command-line argument: --robust.

• subjects_dir (a pathlike object or string representing an existing directory) – Subjects directory.

Outputs:

• out_post (a pathlike object or string representing an existing file)

• out_qc (a pathlike object or string representing an existing file)

• out_seg (a pathlike object or string representing an existing file)

class qsiprep.interfaces.freesurfer.MockSynthStrip(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

input_image (a pathlike object or string representing an existing file) – Maps to a command-line argument: -i %s.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• border (an integer) – Mask border threshold in mm. Default is 1. Maps to a command-line argument: -b %d.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• gpu (a boolean) – Maps to a command-line argument: -g.

• no_csf (a boolean) – Exclude CSF from brain border. Maps to a command-line argument: --no-csf.

• num_threads (an integer) – Allows for specifying more threads.

• out_brain (a pathlike object or string representing a file) – Skull stripped image with corrupt sform. Maps to a command-line argument: -o %s.

• out_brain_mask (a pathlike object or string representing a file) – Mask image with corrupt sform. Maps to a command-line argument: -m %s.

• subjects_dir (a pathlike object or string representing an existing directory) – Subjects directory.

Outputs:

• out_brain (a pathlike object or string representing an existing file)

• out_brain_mask (a pathlike object or string representing an existing file)

class qsiprep.interfaces.freesurfer.PatchedLTAConvert(command=None, terminal_output=None, write_cmdline=False, **inputs)

Bases: TruncateLTA, LTAConvert

Wrapped executable: lta_convert.

LTAconvert is producing a lta file refer as out_lta truncate filename through mixin TruncateLTA

Mandatory Inputs:

• in_fsl (a pathlike object or string representing an existing file) – Input transform of FSL type. Maps to a command-line argument: --infsl %s. Mutually exclusive with inputs: in_lta, in_fsl, in_mni, in_reg, in_niftyreg, in_itk.

• in_itk (a pathlike object or string representing an existing file) – Input transform of ITK type. Maps to a command-line argument: --initk %s. Mutually exclusive with inputs: in_lta, in_fsl, in_mni, in_reg, in_niftyreg, in_itk.

• in_lta (a pathlike object or string representing an existing file or ‘identity.nofile’) – Input transform of LTA type. Maps to a command-line argument: --inlta %s. Mutually exclusive with inputs: in_lta, in_fsl, in_mni, in_reg, in_niftyreg, in_itk.

• in_mni (a pathlike object or string representing an existing file) – Input transform of MNI/XFM type. Maps to a command-line argument: --inmni %s. Mutually exclusive with inputs: in_lta, in_fsl, in_mni, in_reg, in_niftyreg, in_itk.

• in_niftyreg (a pathlike object or string representing an existing file) – Input transform of Nifty Reg type (inverse RAS2RAS). Maps to a command-line argument: --inniftyreg %s. Mutually exclusive with inputs: in_lta, in_fsl, in_mni, in_reg, in_niftyreg, in_itk.

• in_reg (a pathlike object or string representing an existing file) – Input transform of TK REG type (deprecated format). Maps to a command-line argument: --inreg %s. Mutually exclusive with inputs: in_lta, in_fsl, in_mni, in_reg, in_niftyreg, in_itk.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• invert (a boolean) – Maps to a command-line argument: --invert.

• ltavox2vox (a boolean) – Maps to a command-line argument: --ltavox2vox. Requires inputs: out_lta.

• out_fsl (a boolean or a pathlike object or string representing a file) – Output transform in FSL format. Maps to a command-line argument: --outfsl %s.

• out_itk (a boolean or a pathlike object or string representing a file) – Output transform in ITK format. Maps to a command-line argument: --outitk %s.

• out_lta (a boolean or a pathlike object or string representing a file) – Output linear transform (LTA Freesurfer format). Maps to a command-line argument: --outlta %s.

• out_mni (a boolean or a pathlike object or string representing a file) – Output transform in MNI/XFM format. Maps to a command-line argument: --outmni %s.

• out_reg (a boolean or a pathlike object or string representing a file) – Output transform in reg dat format. Maps to a command-line argument: --outreg %s.

• source_file (a pathlike object or string representing an existing file) – Maps to a command-line argument: --src %s.

• target_conform (a boolean) – Maps to a command-line argument: --trgconform.

• target_file (a pathlike object or string representing an existing file) – Maps to a command-line argument: --trg %s.

Outputs:

• out_fsl (a pathlike object or string representing an existing file) – Output transform in FSL format.

• out_itk (a pathlike object or string representing an existing file) – Output transform in ITK format.

• out_lta (a pathlike object or string representing an existing file) – Output linear transform (LTA Freesurfer format).

• out_mni (a pathlike object or string representing an existing file) – Output transform in MNI/XFM format.

• out_reg (a pathlike object or string representing an existing file) – Output transform in reg dat format.

lta_outputs = ('out_lta',)

class qsiprep.interfaces.freesurfer.PrepareSynthStripGrid(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Mandatory Inputs:

input_image (a pathlike object or string representing an existing file)

Outputs:

prepared_image (a pathlike object or string representing an existing file)

class qsiprep.interfaces.freesurfer.RefineBrainMask(from_file=None, resource_monitor=None, **inputs)

Bases: SimpleInterface

Refine the brain mask implicit in the aseg.mgz file to include possibly missing gray-matter voxels and deep, wide sulci.

Mandatory Inputs:

• in_anat (a pathlike object or string representing an existing file) – Input anatomical reference (INU corrected).

• in_ants (a pathlike object or string representing an existing file) – Brain tissue segmentation generated with antsBrainExtraction.sh.

• in_aseg (a pathlike object or string representing an existing file) – Input aseg file, in NifTi format.

Outputs:

out_file (a pathlike object or string representing an existing file) – New mask.

class qsiprep.interfaces.freesurfer.StructuralReference(**inputs)

Bases: RobustTemplate

Wrapped executable: mri_robust_template.

Variation on RobustTemplate that simply copies the source if a single volume is provided.

>>> from qsiprep.utils.bids import collect_data
>>> t1w = collect_data('ds114', '01')[0]['t1w']
>>> template = StructuralReference()
>>> template.inputs.in_files = t1w
>>> template.inputs.auto_detect_sensitivity = True
>>> template.cmdline  
'mri_robust_template --satit --mov .../sub-01_ses-retest_T1w.nii.gz
    .../sub-01_ses-test_T1w.nii.gz --template mri_robust_template_out.mgz'

Mandatory Inputs:

• auto_detect_sensitivity (a boolean) – Auto-detect good sensitivity (recommended for head or full brain scans). Maps to a command-line argument: --satit. Mutually exclusive with inputs: outlier_sensitivity.

• in_files (a list of items which are a pathlike object or string representing an existing file) – Input movable volumes to be aligned to common mean/median template. Maps to a command-line argument: --mov %s.

• out_file (a pathlike object or string representing a file) – Output template volume (final mean/median image). Maps to a command-line argument: --template %s. (Nipype default value: mri_robust_template_out.mgz)

• outlier_sensitivity (a float) – Set outlier sensitivity manually (e.g. “–sat 4.685” ). Higher values mean less sensitivity. Maps to a command-line argument: --sat %.4f. Mutually exclusive with inputs: auto_detect_sensitivity.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• average_metric (‘median’ or ‘mean’) – Construct template from: 0 Mean, 1 Median (default). Maps to a command-line argument: --average %d.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• fixed_timepoint (a boolean) – Map everything to init TP# (init TP is not resampled). Maps to a command-line argument: --fixtp.

• in_intensity_scales (a list of items which are a pathlike object or string representing an existing file) – Use initial intensity scales. Maps to a command-line argument: --iscalein %s.

• initial_timepoint (an integer) – Use TP# for special init (default random), 0: no init. Maps to a command-line argument: --inittp %d.

• initial_transforms (a list of items which are a pathlike object or string representing an existing file) – Use initial transforms (lta) on source. Maps to a command-line argument: --ixforms %s.

• intensity_scaling (a boolean) – Allow also intensity scaling (default off). Maps to a command-line argument: --iscale.

• no_iteration (a boolean) – Do not iterate, just create first template. Maps to a command-line argument: --noit.

• num_threads (an integer) – Allows for specifying more threads.

• scaled_intensity_outputs (a list of items which are a pathlike object or string representing a file or a boolean) – Final intensity scales (will activate –iscale). Maps to a command-line argument: --iscaleout %s.

• subjects_dir (a pathlike object or string representing an existing directory) – Subjects directory.

• subsample_threshold (an integer) – Subsample if dim > # on all axes (default no subs.). Maps to a command-line argument: --subsample %d.

• transform_outputs (a list of items which are a pathlike object or string representing a file or a boolean) – Output xforms to template (for each input). Maps to a command-line argument: --lta %s.

Outputs:

• out_file (a pathlike object or string representing an existing file) – Output template volume (final mean/median image).

• scaled_intensity_outputs (a list of items which are a pathlike object or string representing an existing file) – Output final intensity scales.

• transform_outputs (a list of items which are a pathlike object or string representing an existing file) – Output xform files from moving to template.

property cmdline

command plus any arguments (args) validates arguments and generates command line

class qsiprep.interfaces.freesurfer.SynthSeg(**inputs)

Bases: FSCommandOpenMP

Wrapped executable: mri_synthseg.

Mandatory Inputs:

input_image (a pathlike object or string representing an existing file) – Maps to a command-line argument: --i %s.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• cpu (a boolean) – Enforce running with CPU rather than GPU. Maps to a command-line argument: --cpu. (Nipype default value: True)

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• fast (a boolean) – Fast predictions (lower quality). Maps to a command-line argument: --fast.

• num_threads (an integer) – Number of threads to use. Maps to a command-line argument: --threads %d. (Nipype default value: 0)

• out_post (a pathlike object or string representing a file) – Posteriors image. Maps to a command-line argument: --post %s.

• out_qc (a pathlike object or string representing a file) – Qc csv. Maps to a command-line argument: --qc %s.

• out_seg (a pathlike object or string representing a file) – Segmentation image. Maps to a command-line argument: --o %s.

• robust (a boolean) – Use robust predictions (slower). Maps to a command-line argument: --robust.

• subjects_dir (a pathlike object or string representing an existing directory) – Subjects directory.

Outputs:

• out_post (a pathlike object or string representing an existing file)

• out_qc (a pathlike object or string representing an existing file)

• out_seg (a pathlike object or string representing an existing file)

class qsiprep.interfaces.freesurfer.SynthStrip(**inputs)

Bases: FSCommandOpenMP

Wrapped executable: mri_synthstrip.

Mandatory Inputs:

input_image (a pathlike object or string representing an existing file) – Maps to a command-line argument: -i %s.

Optional Inputs:

• args (a string) – Additional parameters to the command. Maps to a command-line argument: %s.

• border (an integer) – Mask border threshold in mm. Default is 1. Maps to a command-line argument: -b %d.

• environ (a dictionary with keys which are a bytes or None or a value of class ‘str’ and with values which are a bytes or None or a value of class ‘str’) – Environment variables. (Nipype default value: {})

• gpu (a boolean) – Maps to a command-line argument: -g.

• no_csf (a boolean) – Exclude CSF from brain border. Maps to a command-line argument: --no-csf.

• num_threads (an integer) – Allows for specifying more threads.

• out_brain (a pathlike object or string representing a file) – Skull stripped image with corrupt sform. Maps to a command-line argument: -o %s.

• out_brain_mask (a pathlike object or string representing a file) – Mask image with corrupt sform. Maps to a command-line argument: -m %s.

• subjects_dir (a pathlike object or string representing an existing directory) – Subjects directory.

Outputs:

• out_brain (a pathlike object or string representing an existing file)

• out_brain_mask (a pathlike object or string representing an existing file)

class qsiprep.interfaces.freesurfer.TruncateLTA

Bases: object

Mixin to ensure that LTA files do not store overly long paths, which lead to segmentation faults when read by FreeSurfer tools.

See the following issues for discussion:

• https://github.com/freesurfer/freesurfer/pull/180

• https://github.com/poldracklab/fmriprep/issues/768

• https://github.com/poldracklab/fmriprep/pull/778

• https://github.com/poldracklab/fmriprep/issues/1268

• https://github.com/poldracklab/fmriprep/pull/1274

lta_outputs = ('out_lta_file',)

qsiprep.interfaces.freesurfer.detect_inputs(t1w_list, t2w_list=None, flair_list=None, hires_enabled=True)

qsiprep.interfaces.freesurfer.find_fs_path(freesurfer_dir, subject_id)

qsiprep.interfaces.freesurfer.grow_mask(anat, aseg, ants_segs=None, ww=7, zval=2.0, bw=4)

Grow mask including pixels that have a high likelihood. GM tissue parameters are sampled in image patches of ww size.

This is inspired on mindboggle’s solution to the problem: https://github.com/nipy/mindboggle/blob/master/mindboggle/guts/segment.py#L1660

qsiprep.interfaces.freesurfer.inject_skullstripped(subjects_dir, subject_id, skullstripped)

qsiprep.interfaces.freesurfer.medial_wall_to_nan(in_file, subjects_dir, target_subject, newpath=None)

Convert values on medial wall to NaNs

qsiprep.interfaces.freesurfer.refine_aseg(aseg, ball_size=4)

First step to reconcile ANTs’ and FreeSurfer’s brain masks.

Here, the aseg.mgz mask from FreeSurfer is refined in two steps, using binary morphological operations:

1. With a binary closing operation the sulci are included into the mask. This results in a smoother brain mask that does not exclude deep, wide sulci.

2. Fill any holes (typically, there could be a hole next to the pineal gland and the corpora quadrigemina if the great cerebral brain is segmented out).