.. AUTO-GENERATED FILE -- DO NOT EDIT!

nipype.interfaces.freesurfer.utils
==================================


:class:`ApplyMask`
------------------


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')
		Environment variables
	ignore_exception : (a boolean)
		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

:class:`ImageInfo`
------------------


Wraps command **mri_info**



Inputs:: 

	[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')
		Environment variables
	ignore_exception : (a boolean)
		Print an error message instead of throwing an exception in case the interface fails to run
	in_file : (an existing file name)
		image to query
	subjects_dir : (an existing directory name)
		subjects directory


Outputs:: 

	TE : (a string)
		echo time (msec)
	TI : (a string)
		inversion time (msec)
	TR : (a string)
		repetition time(msec)
	data_type : (a string)
		image data type
	dimensions : (a tuple)
		image dimensions (voxels)
	file_format : (a string)
		file format
	info	output of mri_info
	orientation : (a string)
		image orientation
	out_file : (an existing file name)
		text file with image information
	ph_enc_dir : (a string)
		phase encode direction
	vox_sizes : (a tuple)
		voxel sizes (mm)

:class:`MRIsConvert`
--------------------


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()

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')
		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)
		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

:class:`SampleToSurface`
------------------------


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() # doctest: +SKIP

Inputs:: 

	[Mandatory]
	hemi : ('lh' or 'rh')
		target hemisphere
	projection_stem : (a string)
		stem for precomputed linear estimates and volume fractions
		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
		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
		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')
		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)
		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
		exclusive: cortex_mask
	mni152reg : (a boolean)
		source volume is in MNI152 space
		exclusive: reg_file,reg_header,mni152reg
	no_reshape : (a boolean)
		do not reshape surface vector (default)
		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
		exclusive: reg_file,reg_header,mni152reg
	reg_header : (a boolean)
		register based on header geometry
		exclusive: reg_file,reg_header,mni152reg
		requires: subject_id
	reshape : (a boolean)
		reshape surface vector to fit in non-mgh format
		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

:class:`SurfaceSmooth`
----------------------


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() # doctest: +SKIP

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)
		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')
		Environment variables
	fwhm : (a float)
		effective FWHM of the smoothing process
		exclusive: smooth_iters
	ignore_exception : (a boolean)
		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
		exclusive: fwhm
	subjects_dir : (an existing directory name)
		subjects directory


Outputs:: 

	out_file : (an existing file name)
		smoothed surface file

:class:`SurfaceSnapshots`
-------------------------


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() # doctest: +SKIP

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
		exclusive: annot_name
	annot_name : (a string)
		name of annotation to display (must be in $subject/label directory
		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')
		Environment variables
	identity_reg : (a boolean)
		use the identity matrix to register the overlay to the surface
		exclusive: overlay_reg,identity_reg,mni152_reg
	ignore_exception : (a boolean)
		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
		exclusive: label_name
	label_name : (a string)
		name of label to display (must be in $subject/label directory
		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
		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
		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
		exclusive: show_gray_curv
	show_gray_curv : (a boolean)
		show curvature in gray
		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

:class:`SurfaceTransform`
-------------------------


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() # doctest: +SKIP

Inputs:: 

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

	[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')
		Environment variables
	ignore_exception : (a boolean)
		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)
		Unknown
	reshape_factor : (an integer)
		Unknown
	subjects_dir : (an existing directory name)
		subjects directory
	target_ico_order : (1 or 2 or 3 or 4 or 5 or 6 or 7)
		Unknown
	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')
		Unknown


Outputs:: 

	out_file : (an existing file name)
		transformed surface file
