NIPY logo
Home · Quickstart · Documentation · Citation · NiPy
Loading

Table Of Contents

Versions

ReleaseDevel
0.5.3pre-0.6
Download Github

Links

interfaces.freesurfer.utils

ApplyMask

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L388

Wraps command mri_mask

Use Freesurfer’s mri_mask to apply a mask to an image.

The mask file need not be binarized; it can be thresholded above a given value before application. It can also optionally be transformed into input space with an LTA matrix.

Inputs:

[Mandatory]
in_file: (an existing file name)
        input image (will be masked)
mask_file: (an existing file name)
        image defining mask space

[Optional]
args: (a string)
        Additional parameters to the command
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
invert_xfm: (a boolean)
        invert transformation
mask_thresh: (a float)
        threshold mask before applying
out_file: (a file name)
        final image to write
subjects_dir: (an existing directory name)
        subjects directory
use_abs: (a boolean)
        take absolute value of mask before applying
xfm_file: (an existing file name)
        LTA-format transformation matrix to align mask with input
xfm_source: (an existing file name)
        image defining transform source space
xfm_target: (an existing file name)
        image defining transform target space

Outputs:

out_file: (an existing file name)
        masked image

MRIMarchingCubes

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L857

Wraps command mri_mc

Uses Freesurfer’s mri_mc to create surfaces by tessellating a given input volume

Example:

import nipype.interfaces.freesurfer as fs mc = fs.MRIMarchingCubes() mc.inputs.in_file = ‘aseg.mgz’ mc.inputs.label_value = 17 mc.inputs.out_file = ‘lh.hippocampus’ mc.run() # doctest: +SKIP

Inputs:

[Mandatory]
in_file: (an existing file name)
        Input volume to tesselate voxels from.
label_value: (an integer)
        Label value which to tesselate from the input volume. (integer, if input is "filled.mgz"
        volume, 127 is rh, 255 is lh)

[Optional]
args: (a string)
        Additional parameters to the command
connectivity_value: (an integer, nipype default value: 1)
        Alter the marching cubes connectivity: 1=6+,2=18,3=6,4=26 (default=1)
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
out_file: (a file name)
        output filename or True to generate one
subjects_dir: (an existing directory name)
        subjects directory

Outputs:

surface: (an existing file name)
        binary surface of the tessellation

MRITessellate

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L803

Wraps command mri_tessellate

Uses Freesurfer’s mri_tessellate to create surfaces by tessellating a given input volume

Example:

import nipype.interfaces.freesurfer as fs tess = fs.MRITessellate() tess.inputs.in_file = ‘aseg.mgz’ tess.inputs.label_value = 17 tess.inputs.out_file = ‘lh.hippocampus’ tess.run() # doctest: +SKIP

Inputs:

[Mandatory]
in_file: (an existing file name)
        Input volume to tesselate voxels from.
label_value: (an integer)
        Label value which to tesselate from the input volume. (integer, if input is "filled.mgz"
        volume, 127 is rh, 255 is lh)

[Optional]
args: (a string)
        Additional parameters to the command
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
out_file: (a file name)
        output filename or True to generate one
subjects_dir: (an existing directory name)
        subjects directory
tesselate_all_voxels: (a boolean)
        Tessellate the surface of all voxels with different labels
use_real_RAS_coordinates: (a boolean)
        Saves surface with real RAS coordinates where c_(r,a,s) != 0

Outputs:

surface: (an existing file name)
        binary surface of the tessellation

MRIsConvert

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L741

Wraps command mris_convert

Uses Freesurfer’s mris_convert to convert surface files to various formats

Example:

import nipype.interfaces.freesurfer as fs mris = fs.MRIs_Convert() mris.inputs.in_file = ‘lh.pial’ mris.inputs.out_datatype = ‘gii’ mris.run() # doctest: +SKIP

Inputs:

[Mandatory]
in_file: (an existing file name)
        File to read/convert
out_datatype: ('ico' or 'tri' or 'stl' or 'vtk' or 'gii' or 'mgh' or 'mgz')
        These file formats are supported:  ASCII:       .ascICO: .ico, .tri GEO: .geo STL: .stl
        VTK: .vtk GIFTI: .gii MGH surface-encoded 'volume': .mgh, .mgz

[Optional]
annot_file: (an existing file name)
        input is annotation or gifti label data
args: (a string)
        Additional parameters to the command
dataarray_num: (an integer)
        if input is gifti, 'num' specifies which data array to use
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
functional_file: (an existing file name)
        input is functional time-series or other multi-frame data (must specify surface)
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
label_file: (an existing file name)
        infile is .label file, label is name of this label
labelstats_outfile: (a file name)
        outfile is name of gifti file to which label stats will be written
normal: (a boolean)
        output is an ascii file where vertex data
origname: (a string)
        read orig positions
out_file: (a file name)
        output filename or True to generate one
parcstats_file: (an existing file name)
        infile is name of text file containing label/val pairs
patch: (a boolean)
        input is a patch, not a full surface
rescale: (a boolean)
        rescale vertex xyz so total area is same as group average
scalarcurv_file: (an existing file name)
        input is scalar curv overlay file (must still specify surface)
scale: (a float)
        scale vertex xyz by scale
subjects_dir: (an existing directory name)
        subjects directory
talairachxfm_subjid: (a string)
        apply talairach xfm of subject to vertex xyz
vertex: (a boolean)
        Writes out neighbors of a vertex in each row
xyz_ascii: (a boolean)
        Print only surface xyz to ascii file

Outputs:

converted: (an existing file name)
        converted output surface

SampleToSurface

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L122

Wraps command mri_vol2surf

Sample a volume to the cortical surface using Freesurfer’s mri_vol2surf.

You must supply a sampling method, range, and units. You can project either a given distance (in mm) or a given fraction of the cortical thickness at that vertex along the surface normal from the target surface, and then set the value of that vertex to be either the value at that point or the average or maximum value found along the projection vector.

By default, the surface will be saved as a vector with a length equal to the number of vertices on the target surface. This is not a problem for Freesurfer programs, but if you intend to use the file with interfaces to another package, you must set the reshape input to True, which will factor the surface vector into a matrix with dimensions compatible with proper Nifti files.

Examples

>>> import nipype.interfaces.freesurfer as fs
>>> sampler = fs.SampleToSurface(hemi="lh")
>>> sampler.inputs.source_file = "cope1.nii.gz"
>>> sampler.inputs.reg_file = "register.dat"
>>> sampler.inputs.sampling_method = "average"
>>> sampler.inputs.sampling_range = 1
>>> sampler.inputs.sampling_units = "frac"
>>> res = sampler.run() 

Inputs:

[Mandatory]
hemi: ('lh' or 'rh')
        target hemisphere
projection_stem: (a string)
        stem for precomputed linear estimates and volume fractions
        mutually_exclusive: sampling_method
sampling_method: ('point' or 'max' or 'average')
        how to sample -- at a point or at the max or average over a range
        mutually_exclusive: projection_stem
        requires: sampling_range, sampling_units
source_file: (an existing file name)
        volume to sample values from

[Optional]
apply_rot: (a tuple of the form: (a float, a float, a float))
        rotation angles (in degrees) to apply to reg matrix
apply_trans: (a tuple of the form: (a float, a float, a float))
        translation (in mm) to apply to reg matrix
args: (a string)
        Additional parameters to the command
cortex_mask: (a boolean)
        mask the target surface with hemi.cortex.label
        mutually_exclusive: mask_label
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
fix_tk_reg: (a boolean)
        make reg matrix round-compatible
float2int_method: ('round' or 'tkregister')
        method to convert reg matrix values (default is round)
frame: (an integer)
        save only one frame (0-based)
hits_file: (a boolean or an existing file name)
        save image with number of hits at each voxel
hits_type: ('cor' or 'mgh' or 'mgz' or 'minc' or 'analyze' or 'analyze4d' or 'spm' or
         'afni' or 'brik' or 'bshort' or 'bfloat' or 'sdt' or 'outline' or 'otl' or 'gdf' or
         'nifti1' or 'nii' or 'niigz')
        hits file type
ico_order: (an integer)
        icosahedron order when target_subject is 'ico'
        requires: target_subject
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
interp_method: ('nearest' or 'trilinear')
        interpolation method
mask_label: (an existing file name)
        label file to mask output with
        mutually_exclusive: cortex_mask
mni152reg: (a boolean)
        source volume is in MNI152 space
        mutually_exclusive: reg_file, reg_header, mni152reg
no_reshape: (a boolean)
        do not reshape surface vector (default)
        mutually_exclusive: reshape
out_file: (a file name)
        surface file to write
out_type: ('cor' or 'mgh' or 'mgz' or 'minc' or 'analyze' or 'analyze4d' or 'spm' or
         'afni' or 'brik' or 'bshort' or 'bfloat' or 'sdt' or 'outline' or 'otl' or 'gdf' or
         'nifti1' or 'nii' or 'niigz')
        output file type
override_reg_subj: (a boolean)
        override the subject in the reg file header
        requires: subject_id
reference_file: (an existing file name)
        reference volume (default is orig.mgz)
reg_file: (an existing file name)
        source-to-reference registration file
        mutually_exclusive: reg_file, reg_header, mni152reg
reg_header: (a boolean)
        register based on header geometry
        mutually_exclusive: reg_file, reg_header, mni152reg
        requires: subject_id
reshape: (a boolean)
        reshape surface vector to fit in non-mgh format
        mutually_exclusive: no_reshape
reshape_slices: (an integer)
        number of 'slices' for reshaping
sampling_range: (a float or a tuple of the form: (a float, a float, a float))
        sampling range - a point or a tuple of (min, max, step)
sampling_units: ('mm' or 'frac')
        sampling range type -- either 'mm' or 'frac'
scale_input: (a float)
        multiple all intensities by scale factor
smooth_surf: (a float)
        smooth output surface (mm fwhm)
smooth_vol: (a float)
        smooth input volume (mm fwhm)
subject_id: (a string)
        subject id
subjects_dir: (an existing directory name)
        subjects directory
surf_reg: (a boolean)
        use surface registration to target subject
        requires: target_subject
surface: (a string)
        target surface (default is white)
target_subject: (a string)
        sample to surface of different subject than source
vox_file: (a boolean or a file name)
        text file with the number of voxels intersecting the surface

Outputs:

hits_file: (an existing file name)
        image with number of hits at each voxel
out_file: (an existing file name)
        surface file
vox_file: (an existing file name)
        text file with the number of voxels intersecting the surface

SurfaceSmooth

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L245

Wraps command mri_surf2surf

Smooth a surface image with mri_surf2surf.

The surface is smoothed by an interative process of averaging the value at each vertex with those of its adjacent neighbors. You may supply either the number of iterations to run or a desired effective FWHM of the smoothing process. If the latter, the underlying program will calculate the correct number of iterations internally.

Examples

>>> import nipype.interfaces.freesurfer as fs
>>> smoother = fs.SurfaceSmooth()
>>> smoother.inputs.in_file = "lh.cope1.mgz"
>>> smoother.inputs.subject_id = "subj_1"
>>> smoother.inputs.hemi = "lh"
>>> smoother.inputs.fwhm = 5
>>> smoother.run() 

Inputs:

[Mandatory]
hemi: ('lh' or 'rh')
        hemisphere to operate on
in_file: (a file name)
        source surface file
subject_id: (a string)
        subject id of surface file

[Optional]
args: (a string)
        Additional parameters to the command
cortex: (a boolean, nipype default value: True)
        only smooth within $hemi.cortex.label
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
fwhm: (a float)
        effective FWHM of the smoothing process
        mutually_exclusive: smooth_iters
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
out_file: (a file name)
        surface file to write
reshape: (a boolean)
        reshape surface vector to fit in non-mgh format
smooth_iters: (an integer)
        iterations of the smoothing process
        mutually_exclusive: fwhm
subjects_dir: (an existing directory name)
        subjects directory

Outputs:

out_file: (an existing file name)
        smoothed surface file

SurfaceSnapshots

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L492

Wraps command tksurfer

Use Tksurfer to save pictures of the cortical surface.

By default, this takes snapshots of the lateral, medial, ventral, and dorsal surfaces. See the six_images option to add the anterior and posterior surfaces.

You may also supply your own tcl script (see the Freesurfer wiki for information on scripting tksurfer). The screenshot stem is set as the environment variable “_SNAPSHOT_STEM”, which you can use in your own scripts.

Node that this interface will not run if you do not have graphics enabled on your system.

Examples

>>> import nipype.interfaces.freesurfer as fs
>>> shots = fs.SurfaceSnapshots(subject_id="fsaverage", hemi="lh", surface="pial")
>>> shots.inputs.overlay = "zstat1.nii.gz"
>>> shots.inputs.overlay_range = (2.3, 6)
>>> shots.inputs.overlay_reg = "register.dat"
>>> res = shots.run() 

Inputs:

[Mandatory]
hemi: ('lh' or 'rh')
        hemisphere to visualize
subject_id: (a string)
        subject to visualize
surface: (a string)
        surface to visualize

[Optional]
annot_file: (an existing file name)
        path to annotation file to display
        mutually_exclusive: annot_name
annot_name: (a string)
        name of annotation to display (must be in $subject/label directory
        mutually_exclusive: annot_file
args: (a string)
        Additional parameters to the command
colortable: (an existing file name)
        load colortable file
demean_overlay: (a boolean)
        remove mean from overlay
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
identity_reg: (a boolean)
        use the identity matrix to register the overlay to the surface
        mutually_exclusive: overlay_reg, identity_reg, mni152_reg
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
invert_overlay: (a boolean)
        invert the overlay display
label_file: (an existing file name)
        path to label file to display
        mutually_exclusive: label_name
label_name: (a string)
        name of label to display (must be in $subject/label directory
        mutually_exclusive: label_file
label_outline: (a boolean)
        draw label/annotation as outline
label_under: (a boolean)
        draw label/annotation under overlay
mni152_reg: (a boolean)
        use to display a volume in MNI152 space on the average subject
        mutually_exclusive: overlay_reg, identity_reg, mni152_reg
orig_suffix: (a string)
        set the orig surface suffix string
overlay: (an existing file name)
        load an overlay volume/surface
        requires: overlay_range
overlay_range: (a float or a tuple of the form: (a float, a float) or a tuple of the
         form: (a float, a float, a float))
        overlay range--either min, (min, max) or (min, mid, max)
overlay_range_offset: (a float)
        overlay range will be symettric around offset value
overlay_reg: (a file name)
        registration matrix file to register overlay to surface
        mutually_exclusive: overlay_reg, identity_reg, mni152_reg
patch_file: (an existing file name)
        load a patch
reverse_overlay: (a boolean)
        reverse the overlay display
screenshot_stem: (a string)
        stem to use for screenshot file names
show_color_scale: (a boolean)
        display the color scale bar
show_color_text: (a boolean)
        display text in the color scale bar
show_curv: (a boolean)
        show curvature
        mutually_exclusive: show_gray_curv
show_gray_curv: (a boolean)
        show curvature in gray
        mutually_exclusive: show_curv
six_images: (a boolean)
        also take anterior and posterior snapshots
sphere_suffix: (a string)
        set the sphere.reg suffix string
stem_template_args: (a list of items which are a string)
        input names to use as arguments for a string-formated stem template
        requires: screenshot_stem
subjects_dir: (an existing directory name)
        subjects directory
tcl_script: (an existing file name)
        override default screenshot script
truncate_overlay: (a boolean)
        truncate the overlay display

Outputs:

snapshots: (an existing file name)
        tiff images of the surface from different perspectives

SurfaceTransform

Code: file:///tmp/buildd/nipype-0.5.3/nipype/interfaces/freesurfer/utils.py#L313

Wraps command mri_surf2surf

Transform a surface file from one subject to another via a spherical registration.

Both the source and target subject must reside in your Subjects Directory, and they must have been processed with recon-all, unless you are transforming to one of the icosahedron meshes.

Examples

>>> from nipype.interfaces.freesurfer import SurfaceTransform
>>> sxfm = SurfaceTransform()
>>> sxfm.inputs.source_file = "lh.cope1.nii.gz"
>>> sxfm.inputs.source_subject = "my_subject"
>>> sxfm.inputs.target_subject = "fsaverage"
>>> sxfm.inputs.hemi = "lh"
>>> sxfm.run() 

Inputs:

[Mandatory]
hemi: ('lh' or 'rh')
        hemisphere to transform
source_file: (an existing file name)
source_subject: (a string)
target_subject: (a string)

[Optional]
args: (a string)
        Additional parameters to the command
environ: (a dictionary with keys which are a value of type 'str' and with values which
         are a value of type 'str', nipype default value: {})
        Environment variables
ignore_exception: (a boolean, nipype default value: False)
        Print an error message instead of throwing an exception in case the interface fails to
        run
out_file: (a file name)
        surface file to write
reshape: (a boolean)
reshape_factor: (an integer)
subjects_dir: (an existing directory name)
        subjects directory
target_ico_order: (1 or 2 or 3 or 4 or 5 or 6 or 7)
target_type: ('cor' or 'mgh' or 'mgz' or 'minc' or 'analyze' or 'analyze4d' or 'spm' or
         'afni' or 'brik' or 'bshort' or 'bfloat' or 'sdt' or 'outline' or 'otl' or 'gdf' or
         'nifti1' or 'nii' or 'niigz')

Outputs:

out_file: (an existing file name)
        transformed surface file