nipype.interfaces.afni.preprocess module

AFNI preprocessing interfaces.

AlignEpiAnatPy

Link to code

Bases: AFNIPythonCommand

Wrapped executable: align_epi_anat.py.

Align EPI to anatomical datasets or vice versa.

This Python script computes the alignment between two datasets, typically an EPI and an anatomical structural dataset, and applies the resulting transformation to one or the other to bring them into alignment.

This script computes the transforms needed to align EPI and anatomical datasets using a cost function designed for this purpose. The script combines multiple transformations, thereby minimizing the amount of interpolation applied to the data.

Basic Usage:

align_epi_anat.py -anat anat+orig -epi epi+orig -epi_base 5

The user must provide EPI and anatomical datasets and specify the EPI sub-brick to use as a base in the alignment.

Internally, the script always aligns the anatomical to the EPI dataset, and the resulting transformation is saved to a 1D file. As a user option, the inverse of this transformation may be applied to the EPI dataset in order to align it to the anatomical data instead.

This program generates several kinds of output in the form of datasets and transformation matrices which can be applied to other datasets if needed. Time-series volume registration, oblique data transformations and Talairach (standard template) transformations will be combined as needed and requested (with options to turn on and off each of the steps) in order to create the aligned datasets.

Examples

>>> from nipype.interfaces import afni
>>> al_ea = afni.AlignEpiAnatPy()
>>> al_ea.inputs.anat = "structural.nii"
>>> al_ea.inputs.in_file = "functional.nii"
>>> al_ea.inputs.epi_base = 0
>>> al_ea.inputs.epi_strip = '3dAutomask'
>>> al_ea.inputs.volreg = 'off'
>>> al_ea.inputs.tshift = 'off'
>>> al_ea.inputs.save_skullstrip = True
>>> al_ea.cmdline 
'python2 ...align_epi_anat.py -anat structural.nii -epi_base 0 -epi_strip 3dAutomask -epi functional.nii -save_skullstrip -suffix _al -tshift off -volreg off'
>>> res = al_ea.run()

See also

For complete details, see the align_epi_anat.py documentation..

Mandatory Inputs:

  • anat (a pathlike object or string representing an existing file) – Name of structural dataset. Maps to a command-line argument: -anat %s.

  • epi_base (an integer >= 0 or ‘mean’ or ‘median’ or ‘max’) – The epi base used in alignmentshould be one of (0/mean/median/max/subbrick#). Maps to a command-line argument: -epi_base %s.

  • in_file (a pathlike object or string representing an existing file) – EPI dataset to align. Maps to a command-line argument: -epi %s.

Optional Inputs:

  • anat2epi (a boolean) – Align anatomical to EPI dataset (default). Maps to a command-line argument: -anat2epi.

  • 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: {})

  • epi2anat (a boolean) – Align EPI to anatomical dataset. Maps to a command-line argument: -epi2anat.

  • epi_strip (‘3dSkullStrip’ or ‘3dAutomask’ or ‘None’) – Method to mask brain in EPI datashould be one of[3dSkullStrip]/3dAutomask/None). Maps to a command-line argument: -epi_strip %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • py27_path (a pathlike object or string representing an existing file or ‘python2’) – (Nipype default value: python2)

  • save_skullstrip (a boolean) – Save skull-stripped (not aligned). Maps to a command-line argument: -save_skullstrip.

  • suffix (a string) – Append suffix to the original anat/epi dataset to usein the resulting dataset names (default is “_al”). Maps to a command-line argument: -suffix %s. (Nipype default value: _al)

  • tshift (‘on’ or ‘off’) – Do time shifting of EPI dataset before alignmentshould be ‘on’ or ‘off’, defaults to ‘on’. Maps to a command-line argument: -tshift %s. (Nipype default value: on)

  • volreg (‘on’ or ‘off’) – Do volume registration on EPI dataset before alignmentshould be ‘on’ or ‘off’, defaults to ‘on’. Maps to a command-line argument: -volreg %s. (Nipype default value: on)

Outputs:

  • anat_al_mat (a pathlike object or string representing a file) – Matrix to align anatomy to the EPI.

  • anat_al_orig (a pathlike object or string representing a file) – A version of the anatomy that is aligned to the EPI.

  • epi_al_mat (a pathlike object or string representing a file) – Matrix to align EPI to anatomy.

  • epi_al_orig (a pathlike object or string representing a file) – A version of the EPI dataset aligned to the anatomy.

  • epi_al_tlrc_mat (a pathlike object or string representing a file) – Matrix to volume register and align epito anatomy and put into standard space.

  • epi_reg_al_mat (a pathlike object or string representing a file) – Matrix to volume register and align epi to anatomy.

  • epi_tlrc_al (a pathlike object or string representing a file) – A version of the EPI dataset aligned to a standard template.

  • epi_vr_al_mat (a pathlike object or string representing a file) – Matrix to volume register EPI.

  • epi_vr_motion (a pathlike object or string representing a file) – Motion parameters from EPI time-seriesregistration (tsh included in name if slicetiming correction is also included).

  • skullstrip (a pathlike object or string representing a file) – Skull-stripped (not aligned) volume.

Allineate

Link to code

Bases: AFNICommand

Wrapped executable: 3dAllineate.

Program to align one dataset (the ‘source’) to a base dataset

For complete details, see the 3dAllineate Documentation.

Examples

>>> from nipype.interfaces import afni
>>> allineate = afni.Allineate()
>>> allineate.inputs.in_file = 'functional.nii'
>>> allineate.inputs.out_file = 'functional_allineate.nii'
>>> allineate.inputs.in_matrix = 'cmatrix.mat'
>>> allineate.cmdline
'3dAllineate -source functional.nii -prefix functional_allineate.nii -1Dmatrix_apply cmatrix.mat'
>>> res = allineate.run()  

>>> allineate = afni.Allineate()
>>> allineate.inputs.in_file = 'functional.nii'
>>> allineate.inputs.reference = 'structural.nii'
>>> allineate.inputs.allcostx = 'out.allcostX.txt'
>>> allineate.cmdline
'3dAllineate -source functional.nii -base structural.nii -allcostx |& tee out.allcostX.txt'
>>> res = allineate.run()  

>>> allineate = afni.Allineate()
>>> allineate.inputs.in_file = 'functional.nii'
>>> allineate.inputs.reference = 'structural.nii'
>>> allineate.inputs.nwarp_fixmot = ['X', 'Y']
>>> allineate.cmdline
'3dAllineate -source functional.nii -nwarp_fixmotX -nwarp_fixmotY -prefix functional_allineate -base structural.nii'
>>> res = allineate.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input file to 3dAllineate. Maps to a command-line argument: -source %s.

Optional Inputs:

  • allcostx (a pathlike object or string representing a file) – Compute and print ALL available cost functionals for the un-warped inputsAND THEN QUIT. If you use this option none of the other expected outputs will be produced. Maps to a command-line argument: -allcostx |& tee %s (position: -1). Mutually exclusive with inputs: out_file, out_matrix, out_param_file, out_weight_file.

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

  • autobox (a boolean) – Expand the -automask function to enclose a rectangular box that holds the irregular mask. Maps to a command-line argument: -autobox.

  • automask (an integer) – Compute a mask function, set a value for dilation or 0. Maps to a command-line argument: -automask+%d.

  • autoweight (a string) – Compute a weight function using the 3dAutomask algorithm plus some blurring of the base image. Maps to a command-line argument: -autoweight%s.

  • center_of_mass (a string) – Use the center-of-mass calculation to bracket the shifts. Maps to a command-line argument: -cmass%s.

  • check (a list of items which are ‘leastsq’ or ‘ls’ or ‘mutualinfo’ or ‘mi’ or ‘corratio_mul’ or ‘crM’ or ‘norm_mutualinfo’ or ‘nmi’ or ‘hellinger’ or ‘hel’ or ‘corratio_add’ or ‘crA’ or ‘corratio_uns’ or ‘crU’) – After cost functional optimization is done, start at the final parameters and RE-optimize using this new cost functions. If the results are too different, a warning message will be printed. However, the final parameters from the original optimization will be used to create the output dataset. Maps to a command-line argument: -check %s.

  • convergence (a float) – Convergence test in millimeters (default 0.05mm). Maps to a command-line argument: -conv %f.

  • cost (‘leastsq’ or ‘ls’ or ‘mutualinfo’ or ‘mi’ or ‘corratio_mul’ or ‘crM’ or ‘norm_mutualinfo’ or ‘nmi’ or ‘hellinger’ or ‘hel’ or ‘corratio_add’ or ‘crA’ or ‘corratio_uns’ or ‘crU’) – Defines the ‘cost’ function that defines the matching between the source and the base. Maps to a command-line argument: -cost %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: {})

  • epi (a boolean) – Treat the source dataset as being composed of warped EPI slices, and the base as comprising anatomically ‘true’ images. Only phase-encoding direction image shearing and scaling will be allowed with this option. Maps to a command-line argument: -EPI.

  • final_interpolation (‘nearestneighbour’ or ‘linear’ or ‘cubic’ or ‘quintic’ or ‘wsinc5’) – Defines interpolation method used to create the output dataset. Maps to a command-line argument: -final %s.

  • fine_blur (a float) – Set the blurring radius to use in the fine resolution pass to ‘x’ mm. A small amount (1-2 mm?) of blurring at the fine step may help with convergence, if there is some problem, especially if the base volume is very noisy. [Default == 0 mm = no blurring at the final alignment pass]. Maps to a command-line argument: -fineblur %f.

  • in_matrix (a pathlike object or string representing a file) – Matrix to align input file. Maps to a command-line argument: -1Dmatrix_apply %s (position: -3). Mutually exclusive with inputs: out_matrix.

  • in_param_file (a pathlike object or string representing an existing file) – Read warp parameters from file and apply them to the source dataset, and produce a new dataset. Maps to a command-line argument: -1Dparam_apply %s. Mutually exclusive with inputs: out_param_file.

  • interpolation (‘nearestneighbour’ or ‘linear’ or ‘cubic’ or ‘quintic’) – Defines interpolation method to use during matching. Maps to a command-line argument: -interp %s.

  • master (a pathlike object or string representing an existing file) – Write the output dataset on the same grid as this file. Maps to a command-line argument: -master %s.

  • maxrot (a float) – Maximum allowed rotation in degrees. Maps to a command-line argument: -maxrot %f.

  • maxscl (a float) – Maximum allowed scaling factor. Maps to a command-line argument: -maxscl %f.

  • maxshf (a float) – Maximum allowed shift in mm. Maps to a command-line argument: -maxshf %f.

  • maxshr (a float) – Maximum allowed shearing factor. Maps to a command-line argument: -maxshr %f.

  • newgrid (a float) – Write the output dataset using isotropic grid spacing in mm. Maps to a command-line argument: -newgrid %f.

  • nmatch (an integer) – Use at most n scattered points to match the datasets. Maps to a command-line argument: -nmatch %d.

  • no_pad (a boolean) – Do not use zero-padding on the base image. Maps to a command-line argument: -nopad.

  • nomask (a boolean) – Don’t compute the autoweight/mask; if -weight is not also used, then every voxel will be counted equally. Maps to a command-line argument: -nomask.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • nwarp (‘bilinear’ or ‘cubic’ or ‘quintic’ or ‘heptic’ or ‘nonic’ or ‘poly3’ or ‘poly5’ or ‘poly7’ or ‘poly9’) – Experimental nonlinear warping: bilinear or legendre poly. Maps to a command-line argument: -nwarp %s.

  • nwarp_fixdep (a list of items which are ‘X’ or ‘Y’ or ‘Z’ or ‘I’ or ‘J’ or ‘K’) – To fix non-linear warp dependency along directions. Maps to a command-line argument: -nwarp_fixdep%s....

  • nwarp_fixmot (a list of items which are ‘X’ or ‘Y’ or ‘Z’ or ‘I’ or ‘J’ or ‘K’) – To fix motion along directions. Maps to a command-line argument: -nwarp_fixmot%s....

  • one_pass (a boolean) – Use only the refining pass – do not try a coarse resolution pass first. Useful if you know that only small amounts of image alignment are needed. Maps to a command-line argument: -onepass.

  • out_file (a pathlike object or string representing a file) – Output file from 3dAllineate. Maps to a command-line argument: -prefix %s. Mutually exclusive with inputs: allcostx.

  • out_matrix (a pathlike object or string representing a file) – Save the transformation matrix for each volume. Maps to a command-line argument: -1Dmatrix_save %s. Mutually exclusive with inputs: in_matrix, allcostx.

  • out_param_file (a pathlike object or string representing a file) – Save the warp parameters in ASCII (.1D) format. Maps to a command-line argument: -1Dparam_save %s. Mutually exclusive with inputs: in_param_file, allcostx.

  • out_weight_file (a pathlike object or string representing a file) – Write the weight volume to disk as a dataset. Maps to a command-line argument: -wtprefix %s. Mutually exclusive with inputs: allcostx.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • overwrite (a boolean) – Overwrite output file if it already exists. Maps to a command-line argument: -overwrite.

  • quiet (a boolean) – Don’t print out verbose progress reports. Maps to a command-line argument: -quiet.

  • reference (a pathlike object or string representing an existing file) – File to be used as reference, the first volume will be used if not given the reference will be the first volume of in_file. Maps to a command-line argument: -base %s.

  • replacebase (a boolean) – If the source has more than one volume, then after the first volume is aligned to the base. Maps to a command-line argument: -replacebase.

  • replacemeth (‘leastsq’ or ‘ls’ or ‘mutualinfo’ or ‘mi’ or ‘corratio_mul’ or ‘crM’ or ‘norm_mutualinfo’ or ‘nmi’ or ‘hellinger’ or ‘hel’ or ‘corratio_add’ or ‘crA’ or ‘corratio_uns’ or ‘crU’) – After first volume is aligned, switch method for later volumes. For use with ‘-replacebase’. Maps to a command-line argument: -replacemeth %s.

  • source_automask (an integer) – Automatically mask the source dataset with dilation or 0. Maps to a command-line argument: -source_automask+%d.

  • source_mask (a pathlike object or string representing an existing file) – Mask the input dataset. Maps to a command-line argument: -source_mask %s.

  • two_best (an integer) – In the coarse pass, use the best ‘bb’ set of initialpoints to search for the starting point for the finepass. If bb==0, then no search is made for the beststarting point, and the identity transformation isused as the starting point. [Default=5; min=0 max=11]. Maps to a command-line argument: -twobest %d.

  • two_blur (a float) – Set the blurring radius for the first pass in mm. Maps to a command-line argument: -twoblur %f.

  • two_first (a boolean) – Use -twopass on the first image to be registered, and then on all subsequent images from the source dataset, use results from the first image’s coarse pass to start the fine pass. Maps to a command-line argument: -twofirst.

  • two_pass (a boolean) – Use a two pass alignment strategy for all volumes, searching for a large rotation+shift and then refining the alignment. Maps to a command-line argument: -twopass.

  • usetemp (a boolean) – Temporary file use. Maps to a command-line argument: -usetemp.

  • verbose (a boolean) – Print out verbose progress reports. Maps to a command-line argument: -verb.

  • warp_type (‘shift_only’ or ‘shift_rotate’ or ‘shift_rotate_scale’ or ‘affine_general’) – Set the warp type. Maps to a command-line argument: -warp %s.

  • warpfreeze (a boolean) – Freeze the non-rigid body parameters after first volume. Maps to a command-line argument: -warpfreeze.

  • weight (a pathlike object or string representing an existing file or a float) – Set the weighting for each voxel in the base dataset; larger weights mean that voxel count more in the cost function. If an image file is given, the volume must be defined on the same grid as the base dataset. Maps to a command-line argument: -weight %s.

  • weight_file (a pathlike object or string representing an existing file) – Set the weighting for each voxel in the base dataset; larger weights mean that voxel count more in the cost function. Must be defined on the same grid as the base dataset. Maps to a command-line argument: -weight %s.

  • zclip (a boolean) – Replace negative values in the input datasets (source & base) with zero. Maps to a command-line argument: -zclip.

Outputs:

  • allcostx (a pathlike object or string representing a file) – Compute and print ALL available cost functionals for the un-warped inputs.

  • out_file (a pathlike object or string representing an existing file) – Output image file name.

  • out_matrix (a pathlike object or string representing an existing file) – Matrix to align input file.

  • out_param_file (a pathlike object or string representing an existing file) – Warp parameters.

  • out_weight_file (a pathlike object or string representing an existing file) – Weight volume.

AutoTLRC

Link to code

Bases: AFNICommand

Wrapped executable: @auto_tlrc.

A minimal wrapper for the AutoTLRC script The only option currently supported is no_ss. For complete details, see the 3dQwarp Documentation.

Examples

>>> from nipype.interfaces import afni
>>> autoTLRC = afni.AutoTLRC()
>>> autoTLRC.inputs.in_file = 'structural.nii'
>>> autoTLRC.inputs.no_ss = True
>>> autoTLRC.inputs.base = "TT_N27+tlrc"
>>> autoTLRC.cmdline
'@auto_tlrc -base TT_N27+tlrc -input structural.nii -no_ss'
>>> res = autoTLRC.run()
Mandatory Inputs:

  • base (a string) – Reference anatomical volume. Usually this volume is in some standard space like TLRC or MNI space and with afni dataset view of (+tlrc). Preferably, this reference volume should have had the skull removed but that is not mandatory. AFNI’s distribution contains several templates. For a longer list, use “whereami -show_templates” TT_N27+tlrc –> Single subject, skull stripped volume. This volume is also known as N27_SurfVol_NoSkull+tlrc elsewhere in AFNI and SUMA land. (www.loni.ucla.edu, www.bic.mni.mcgill.ca) This template has a full set of FreeSurfer (surfer.nmr.mgh.harvard.edu) surface models that can be used in SUMA. For details, see Talairach-related link: https://afni.nimh.nih.gov/afni/suma TT_icbm452+tlrc –> Average volume of 452 normal brains. Skull Stripped. (www.loni.ucla.edu) TT_avg152T1+tlrc –> Average volume of 152 normal brains. Skull Stripped.(www.bic.mni.mcgill.ca) TT_EPI+tlrc –> EPI template from spm2, masked as TT_avg152T1 TT_avg152 and TT_EPI volume sources are from SPM’s distribution. (www.fil.ion.ucl.ac.uk/spm/) If you do not specify a path for the template, the script will attempt to locate the template AFNI’s binaries directory. NOTE: These datasets have been slightly modified from their original size to match the standard TLRC dimensions (Jean Talairach and Pierre Tournoux Co-Planar Stereotaxic Atlas of the Human Brain Thieme Medical Publishers, New York, 1988). That was done for internal consistency in AFNI. You may use the original form of these volumes if you choose but your TLRC coordinates will not be consistent with AFNI’s TLRC database (San Antonio Talairach Daemon database), for example. Maps to a command-line argument: -base %s.

  • in_file (a pathlike object or string representing an existing file) – Original anatomical volume (+orig).The skull is removed by this scriptunless instructed otherwise (-no_ss). Maps to a command-line argument: -input %s.

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: {})

  • no_ss (a boolean) – Do not strip skull of input data set (because skull has already been removed or because template still has the skull) NOTE: The -no_ss option is not all that optional. Here is a table of when you should and should not use -no_ss

    Dataset

    Template

    w/ skull

    wo/ skull

    WITH skull

    -no_ss

    xxx

    WITHOUT skull

    No Cigar

    -no_ss

    Template means: Your template of choice Dset. means: Your anatomical dataset -no_ss means: Skull stripping should not be attempted on Dset xxx means: Don’t put anything, the script will strip Dset No Cigar means: Don’t try that combination, it makes no sense. Maps to a command-line argument: -no_ss.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

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

AutoTcorrelate

Link to code

Bases: AFNICommand

Wrapped executable: 3dAutoTcorrelate.

Computes the correlation coefficient between the time series of each pair of voxels in the input dataset, and stores the output into a new anatomical bucket dataset [scaled to shorts to save memory space].

For complete details, see the 3dAutoTcorrelate Documentation.

Examples

>>> from nipype.interfaces import afni
>>> corr = afni.AutoTcorrelate()
>>> corr.inputs.in_file = 'functional.nii'
>>> corr.inputs.polort = -1
>>> corr.inputs.eta2 = True
>>> corr.inputs.mask = 'mask.nii'
>>> corr.inputs.mask_only_targets = True
>>> corr.cmdline  
'3dAutoTcorrelate -eta2 -mask mask.nii -mask_only_targets -prefix functional_similarity_matrix.1D -polort -1 functional.nii'
>>> res = corr.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Timeseries x space (volume or surface) file. Maps to a command-line argument: %s (position: -1).

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: {})

  • eta2 (a boolean) – Eta^2 similarity. Maps to a command-line argument: -eta2.

  • mask (a pathlike object or string representing an existing file) – Mask of voxels. Maps to a command-line argument: -mask %s.

  • mask_only_targets (a boolean) – Use mask only on targets voxels. Maps to a command-line argument: -mask_only_targets. Mutually exclusive with inputs: mask_source.

  • mask_source (a pathlike object or string representing an existing file) – Mask for source voxels. Maps to a command-line argument: -mask_source %s. Mutually exclusive with inputs: mask_only_targets.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • polort (an integer) – Remove polynomial trend of order m or -1 for no detrending. Maps to a command-line argument: -polort %d.

Outputs:

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

Automask

Link to code

Bases: AFNICommand

Wrapped executable: 3dAutomask.

Create a brain-only mask of the image using AFNI 3dAutomask command

For complete details, see the 3dAutomask Documentation.

Examples

>>> from nipype.interfaces import afni
>>> automask = afni.Automask()
>>> automask.inputs.in_file = 'functional.nii'
>>> automask.inputs.dilate = 1
>>> automask.inputs.outputtype = 'NIFTI'
>>> automask.cmdline  
'3dAutomask -apply_prefix functional_masked.nii -dilate 1 -prefix functional_mask.nii functional.nii'
>>> res = automask.run()
Mandatory Inputs:

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

Optional Inputs:

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

  • brain_file (a pathlike object or string representing a file) – Output file from 3dAutomask. Maps to a command-line argument: -apply_prefix %s.

  • clfrac (a float) – Sets the clip level fraction (must be 0.1-0.9). A small value will tend to make the mask larger [default = 0.5]. Maps to a command-line argument: -clfrac %s.

  • dilate (an integer) – Dilate the mask outwards. Maps to a command-line argument: -dilate %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: {})

  • erode (an integer) – Erode the mask inwards. Maps to a command-line argument: -erode %s.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

  • brain_file (a pathlike object or string representing an existing file) – Brain file (skull stripped).

  • out_file (a pathlike object or string representing an existing file) – Mask file.

Bandpass

Link to code

Bases: AFNICommand

Wrapped executable: 3dBandpass.

Program to lowpass and/or highpass each voxel time series in a dataset, offering more/different options than Fourier

For complete details, see the 3dBandpass Documentation.

Examples

>>> from nipype.interfaces import afni
>>> from nipype.testing import  example_data
>>> bandpass = afni.Bandpass()
>>> bandpass.inputs.in_file = 'functional.nii'
>>> bandpass.inputs.highpass = 0.005
>>> bandpass.inputs.lowpass = 0.1
>>> bandpass.cmdline
'3dBandpass -prefix functional_bp 0.005000 0.100000 functional.nii'
>>> res = bandpass.run()
Mandatory Inputs:

  • highpass (a float) – Highpass. Maps to a command-line argument: %f (position: -3).

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

  • lowpass (a float) – Lowpass. Maps to a command-line argument: %f (position: -2).

Optional Inputs:

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

  • automask (a boolean) – Create a mask from the input dataset. Maps to a command-line argument: -automask.

  • blur (a float) – Blur (inside the mask only) with a filter width (FWHM) of ‘fff’ millimeters. Maps to a command-line argument: -blur %f.

  • despike (a boolean) – Despike each time series before other processing. Hopefully, you don’t actually need to do this, which is why it is optional. Maps to a command-line argument: -despike.

  • 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: {})

  • localPV (a float) – Replace each vector by the local Principal Vector (AKA first singular vector) from a neighborhood of radius ‘rrr’ millimeters. Note that the PV time series is L2 normalized. This option is mostly for Bob Cox to have fun with. Maps to a command-line argument: -localPV %f.

  • mask (a pathlike object or string representing an existing file) – Mask file. Maps to a command-line argument: -mask %s (position: 2).

  • nfft (an integer) – Set the FFT length [must be a legal value]. Maps to a command-line argument: -nfft %d.

  • no_detrend (a boolean) – Skip the quadratic detrending of the input that occurs before the FFT-based bandpassing. You would only want to do this if the dataset had been detrended already in some other program. Maps to a command-line argument: -nodetrend.

  • normalize (a boolean) – Make all output time series have L2 norm = 1 (i.e., sum of squares = 1). Maps to a command-line argument: -norm.

  • notrans (a boolean) – Don’t check for initial positive transients in the data. The test is a little slow, so skipping it is OK, if you KNOW the data time series are transient-free. Maps to a command-line argument: -notrans.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • orthogonalize_dset (a pathlike object or string representing an existing file) – Orthogonalize each voxel to the corresponding voxel time series in dataset ‘fset’, which must have the same spatial and temporal grid structure as the main input dataset. At present, only one ‘-dsort’ option is allowed. Maps to a command-line argument: -dsort %s.

  • orthogonalize_file (a list of items which are a pathlike object or string representing an existing file) – Also orthogonalize input to columns in f.1D. Multiple ‘-ort’ options are allowed. Maps to a command-line argument: -ort %s.

  • out_file (a pathlike object or string representing a file) – Output file from 3dBandpass. Maps to a command-line argument: -prefix %s (position: 1).

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • tr (a float) – Set time step (TR) in sec [default=from dataset header]. Maps to a command-line argument: -dt %f.

Outputs:

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

BlurInMask

Link to code

Bases: AFNICommand

Wrapped executable: 3dBlurInMask.

Blurs a dataset spatially inside a mask. That’s all. Experimental.

For complete details, see the 3dBlurInMask Documentation.

Examples

>>> from nipype.interfaces import afni
>>> bim = afni.BlurInMask()
>>> bim.inputs.in_file = 'functional.nii'
>>> bim.inputs.mask = 'mask.nii'
>>> bim.inputs.fwhm = 5.0
>>> bim.cmdline  
'3dBlurInMask -input functional.nii -FWHM 5.000000 -mask mask.nii -prefix functional_blur'
>>> res = bim.run()
Mandatory Inputs:

  • fwhm (a float) – Fwhm kernel size. Maps to a command-line argument: -FWHM %f.

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

Optional Inputs:

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

  • automask (a boolean) – Create an automask from the input dataset. Maps to a command-line argument: -automask.

  • 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: {})

  • float_out (a boolean) – Save dataset as floats, no matter what the input data type is. Maps to a command-line argument: -float.

  • mask (a pathlike object or string representing a file) – Mask dataset, if desired. Blurring will occur only within the mask. Voxels NOT in the mask will be set to zero in the output. Maps to a command-line argument: -mask %s.

  • multimask (a pathlike object or string representing a file) – Multi-mask dataset – each distinct nonzero value in dataset will be treated as a separate mask for blurring purposes. Maps to a command-line argument: -Mmask %s.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • options (a string) – Options. Maps to a command-line argument: %s (position: 2).

  • out_file (a pathlike object or string representing a file) – Output to the file. Maps to a command-line argument: -prefix %s (position: -1).

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • preserve (a boolean) – Normally, voxels not in the mask will be set to zero in the output. If you want the original values in the dataset to be preserved in the output, use this option. Maps to a command-line argument: -preserve.

Outputs:

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

BlurToFWHM

Link to code

Bases: AFNICommand

Wrapped executable: 3dBlurToFWHM.

Blurs a ‘master’ dataset until it reaches a specified FWHM smoothness (approximately).

For complete details, see the 3dBlurToFWHM Documentation

Examples

>>> from nipype.interfaces import afni
>>> blur = afni.preprocess.BlurToFWHM()
>>> blur.inputs.in_file = 'epi.nii'
>>> blur.inputs.fwhm = 2.5
>>> blur.cmdline  
'3dBlurToFWHM -FWHM 2.500000 -input epi.nii -prefix epi_afni'
>>> res = blur.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – The dataset that will be smoothed. Maps to a command-line argument: -input %s.

Optional Inputs:

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

  • automask (a boolean) – Create an automask from the input dataset. Maps to a command-line argument: -automask.

  • blurmaster (a pathlike object or string representing an existing file) – The dataset whose smoothness controls the process. Maps to a command-line argument: -blurmaster %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: {})

  • fwhm (a float) – Blur until the 3D FWHM reaches this value (in mm). Maps to a command-line argument: -FWHM %f.

  • fwhmxy (a float) – Blur until the 2D (x,y)-plane FWHM reaches this value (in mm). Maps to a command-line argument: -FWHMxy %f.

  • mask (a pathlike object or string representing an existing file) – Mask dataset, if desired. Voxels NOT in mask will be set to zero in output. Maps to a command-line argument: -mask %s.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

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

ClipLevel

Link to code

Bases: AFNICommandBase

Wrapped executable: 3dClipLevel.

Estimates the value at which to clip the anatomical dataset so

that background regions are set to zero.

For complete details, see the 3dClipLevel Documentation.

Examples

>>> from nipype.interfaces.afni import preprocess
>>> cliplevel = preprocess.ClipLevel()
>>> cliplevel.inputs.in_file = 'anatomical.nii'
>>> cliplevel.cmdline
'3dClipLevel anatomical.nii'
>>> res = cliplevel.run()
Mandatory Inputs:

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

Optional Inputs:

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

  • doall (a boolean) – Apply the algorithm to each sub-brick separately. Maps to a command-line argument: -doall (position: 3). Mutually exclusive with inputs: g, r, a, 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: {})

  • grad (a pathlike object or string representing a file) – Also compute a ‘gradual’ clip level as a function of voxel position, and output that to a dataset. Maps to a command-line argument: -grad %s (position: 3). Mutually exclusive with inputs: d, o, a, l, l.

  • mfrac (a float) – Use the number ff instead of 0.50 in the algorithm. Maps to a command-line argument: -mfrac %s (position: 2).

Outputs:

clip_val (a float) – Output.

ClipLevel.aggregate_outputs(runtime=None, needed_outputs=None)

Collate expected outputs and apply output traits validation.

DegreeCentrality

Link to code

Bases: AFNICommand

Wrapped executable: 3dDegreeCentrality.

Performs degree centrality on a dataset using a given maskfile via 3dDegreeCentrality

For complete details, see the 3dDegreeCentrality Documentation.

Examples

>>> from nipype.interfaces import afni
>>> degree = afni.DegreeCentrality()
>>> degree.inputs.in_file = 'functional.nii'
>>> degree.inputs.mask = 'mask.nii'
>>> degree.inputs.sparsity = 1 # keep the top one percent of connections
>>> degree.inputs.out_file = 'out.nii'
>>> degree.cmdline
'3dDegreeCentrality -mask mask.nii -prefix out.nii -sparsity 1.000000 functional.nii'
>>> res = degree.run()
Mandatory Inputs:

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

Optional Inputs:

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

  • autoclip (a boolean) – Clip off low-intensity regions in the dataset. Maps to a command-line argument: -autoclip.

  • automask (a boolean) – Mask the dataset to target brain-only voxels. Maps to a command-line argument: -automask.

  • 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: {})

  • mask (a pathlike object or string representing an existing file) – Mask file to mask input data. Maps to a command-line argument: -mask %s.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • oned_file (a string) – Output filepath to text dump of correlation matrix. Maps to a command-line argument: -out1D %s.

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • polort (an integer) – Maps to a command-line argument: -polort %d.

  • sparsity (a float) – Only take the top percent of connections. Maps to a command-line argument: -sparsity %f.

  • thresh (a float) – Threshold to exclude connections where corr <= thresh. Maps to a command-line argument: -thresh %f.

Outputs:

  • oned_file (a pathlike object or string representing a file) – The text output of the similarity matrix computed after thresholding with one-dimensional and ijk voxel indices, correlations, image extents, and affine matrix.

  • out_file (a pathlike object or string representing an existing file) – Output file.

Despike

Link to code

Bases: AFNICommand

Wrapped executable: 3dDespike.

Removes ‘spikes’ from the 3D+time input dataset

For complete details, see the 3dDespike Documentation.

Examples

>>> from nipype.interfaces import afni
>>> despike = afni.Despike()
>>> despike.inputs.in_file = 'functional.nii'
>>> despike.cmdline
'3dDespike -prefix functional_despike functional.nii'
>>> res = despike.run()
Mandatory Inputs:

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

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: {})

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

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

Detrend

Link to code

Bases: AFNICommand

Wrapped executable: 3dDetrend.

This program removes components from voxel time series using linear least squares

For complete details, see the 3dDetrend Documentation.

Examples

>>> from nipype.interfaces import afni
>>> detrend = afni.Detrend()
>>> detrend.inputs.in_file = 'functional.nii'
>>> detrend.inputs.args = '-polort 2'
>>> detrend.inputs.outputtype = 'AFNI'
>>> detrend.cmdline
'3dDetrend -polort 2 -prefix functional_detrend functional.nii'
>>> res = detrend.run()
Mandatory Inputs:

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

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: {})

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

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

ECM

Link to code

Bases: AFNICommand

Wrapped executable: 3dECM.

Performs degree centrality on a dataset using a given maskfile via the 3dECM command

For complete details, see the 3dECM Documentation.

Examples

>>> from nipype.interfaces import afni
>>> ecm = afni.ECM()
>>> ecm.inputs.in_file = 'functional.nii'
>>> ecm.inputs.mask = 'mask.nii'
>>> ecm.inputs.sparsity = 0.1 # keep top 0.1% of connections
>>> ecm.inputs.out_file = 'out.nii'
>>> ecm.cmdline
'3dECM -mask mask.nii -prefix out.nii -sparsity 0.100000 functional.nii'
>>> res = ecm.run()
Mandatory Inputs:

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

Optional Inputs:

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

  • autoclip (a boolean) – Clip off low-intensity regions in the dataset. Maps to a command-line argument: -autoclip.

  • automask (a boolean) – Mask the dataset to target brain-only voxels. Maps to a command-line argument: -automask.

  • 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: {})

  • eps (a float) – Sets the stopping criterion for the power iteration; \(l2\|v_\text{old} - v_\text{new}\| < eps\|v_\text{old}\|\); default = 0.001. Maps to a command-line argument: -eps %f.

  • fecm (a boolean) – Fast centrality method; substantial speed increase but cannot accommodate thresholding; automatically selected if -thresh or -sparsity are not set. Maps to a command-line argument: -fecm.

  • full (a boolean) – Full power method; enables thresholding; automatically selected if -thresh or -sparsity are set. Maps to a command-line argument: -full.

  • mask (a pathlike object or string representing an existing file) – Mask file to mask input data. Maps to a command-line argument: -mask %s.

  • max_iter (an integer) – Sets the maximum number of iterations to use in the power iteration; default = 1000. Maps to a command-line argument: -max_iter %d.

  • memory (a float) – Limit memory consumption on system by setting the amount of GB to limit the algorithm to; default = 2GB. Maps to a command-line argument: -memory %f.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • polort (an integer) – Maps to a command-line argument: -polort %d.

  • scale (a float) – Scale correlation coefficients in similarity matrix to after shifting, x >= 0.0; default = 1.0 for -full, 0.5 for -fecm. Maps to a command-line argument: -scale %f.

  • shift (a float) – Shift correlation coefficients in similarity matrix to enforce non-negativity, s >= 0.0; default = 0.0 for -full, 1.0 for -fecm. Maps to a command-line argument: -shift %f.

  • sparsity (a float) – Only take the top percent of connections. Maps to a command-line argument: -sparsity %f.

  • thresh (a float) – Threshold to exclude connections where corr <= thresh. Maps to a command-line argument: -thresh %f.

Outputs:

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

Fim

Link to code

Bases: AFNICommand

Wrapped executable: 3dfim+.

Program to calculate the cross-correlation of an ideal reference waveform with the measured FMRI time series for each voxel.

For complete details, see the 3dfim+ Documentation.

Examples

>>> from nipype.interfaces import afni
>>> fim = afni.Fim()
>>> fim.inputs.in_file = 'functional.nii'
>>> fim.inputs.ideal_file= 'seed.1D'
>>> fim.inputs.out_file = 'functional_corr.nii'
>>> fim.inputs.out = 'Correlation'
>>> fim.inputs.fim_thr = 0.0009
>>> fim.cmdline
'3dfim+ -input functional.nii -ideal_file seed.1D -fim_thr 0.000900 -out Correlation -bucket functional_corr.nii'
>>> res = fim.run()
Mandatory Inputs:

  • ideal_file (a pathlike object or string representing an existing file) – Ideal time series file name. Maps to a command-line argument: -ideal_file %s (position: 2).

  • in_file (a pathlike object or string representing an existing file) – Input file to 3dfim+. Maps to a command-line argument: -input %s (position: 1).

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: {})

  • fim_thr (a float) – Fim internal mask threshold value. Maps to a command-line argument: -fim_thr %f (position: 3).

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out (a string) – Flag to output the specified parameter. Maps to a command-line argument: -out %s (position: 4).

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -bucket %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

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

Fourier

Link to code

Bases: AFNICommand

Wrapped executable: 3dFourier.

Program to lowpass and/or highpass each voxel time series in a dataset, via the FFT

For complete details, see the 3dFourier Documentation.

Examples

>>> from nipype.interfaces import afni
>>> fourier = afni.Fourier()
>>> fourier.inputs.in_file = 'functional.nii'
>>> fourier.inputs.retrend = True
>>> fourier.inputs.highpass = 0.005
>>> fourier.inputs.lowpass = 0.1
>>> fourier.cmdline
'3dFourier -highpass 0.005000 -lowpass 0.100000 -prefix functional_fourier -retrend functional.nii'
>>> res = fourier.run()
Mandatory Inputs:

  • highpass (a float) – Highpass. Maps to a command-line argument: -highpass %f.

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

  • lowpass (a float) – Lowpass. Maps to a command-line argument: -lowpass %f.

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: {})

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • retrend (a boolean) – Any mean and linear trend are removed before filtering. This will restore the trend after filtering. Maps to a command-line argument: -retrend.

Outputs:

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

Hist

Link to code

Bases: AFNICommandBase

Wrapped executable: 3dHist.

Computes average of all voxels in the input dataset which satisfy the criterion in the options list

For complete details, see the 3dHist Documentation.

Examples

>>> from nipype.interfaces import afni
>>> hist = afni.Hist()
>>> hist.inputs.in_file = 'functional.nii'
>>> hist.cmdline
'3dHist -input functional.nii -prefix functional_hist'
>>> res = hist.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input file to 3dHist. Maps to a command-line argument: -input %s (position: 1).

Optional Inputs:

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

  • bin_width (a float) – Bin width. Maps to a command-line argument: -binwidth %f.

  • 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: {})

  • mask (a pathlike object or string representing an existing file) – Matrix to align input file. Maps to a command-line argument: -mask %s.

  • max_value (a float) – Maximum intensity value. Maps to a command-line argument: -max %f.

  • min_value (a float) – Minimum intensity value. Maps to a command-line argument: -min %f.

  • nbin (an integer) – Number of bins. Maps to a command-line argument: -nbin %d.

  • out_file (a pathlike object or string representing a file) – Write histogram to niml file with this prefix. Maps to a command-line argument: -prefix %s.

  • out_show (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: > %s (position: -1).

  • showhist (a boolean) – Write a text visual histogram. Maps to a command-line argument: -showhist. (Nipype default value: False)

Outputs:

  • out_file (a pathlike object or string representing an existing file) – Output file.

  • out_show (a pathlike object or string representing a file) – Output visual histogram.

LFCD

Link to code

Bases: AFNICommand

Wrapped executable: 3dLFCD.

Performs degree centrality on a dataset using a given maskfile via the 3dLFCD command

For complete details, see the 3dLFCD Documentation.

Examples

>>> from nipype.interfaces import afni
>>> lfcd = afni.LFCD()
>>> lfcd.inputs.in_file = 'functional.nii'
>>> lfcd.inputs.mask = 'mask.nii'
>>> lfcd.inputs.thresh = 0.8 # keep all connections with corr >= 0.8
>>> lfcd.inputs.out_file = 'out.nii'
>>> lfcd.cmdline
'3dLFCD -mask mask.nii -prefix out.nii -thresh 0.800000 functional.nii'
>>> res = lfcd.run()
Mandatory Inputs:

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

Optional Inputs:

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

  • autoclip (a boolean) – Clip off low-intensity regions in the dataset. Maps to a command-line argument: -autoclip.

  • automask (a boolean) – Mask the dataset to target brain-only voxels. Maps to a command-line argument: -automask.

  • 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: {})

  • mask (a pathlike object or string representing an existing file) – Mask file to mask input data. Maps to a command-line argument: -mask %s.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • polort (an integer) – Maps to a command-line argument: -polort %d.

  • thresh (a float) – Threshold to exclude connections where corr <= thresh. Maps to a command-line argument: -thresh %f.

Outputs:

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

Maskave

Link to code

Bases: AFNICommand

Wrapped executable: 3dmaskave.

Computes average of all voxels in the input dataset which satisfy the criterion in the options list

For complete details, see the 3dmaskave Documentation.

Examples

>>> from nipype.interfaces import afni
>>> maskave = afni.Maskave()
>>> maskave.inputs.in_file = 'functional.nii'
>>> maskave.inputs.mask= 'seed_mask.nii'
>>> maskave.inputs.quiet= True
>>> maskave.cmdline  
'3dmaskave -mask seed_mask.nii -quiet functional.nii > functional_maskave.1D'
>>> res = maskave.run()
Mandatory Inputs:

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

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: {})

  • mask (a pathlike object or string representing an existing file) – Matrix to align input file. Maps to a command-line argument: -mask %s (position: 1).

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: > %s (position: -1).

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • quiet (a boolean) – Matrix to align input file. Maps to a command-line argument: -quiet (position: 2).

Outputs:

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

Means

Link to code

Bases: AFNICommand

Wrapped executable: 3dMean.

Takes the voxel-by-voxel mean of all input datasets using 3dMean

For complete details, see the 3dMean Documentation.

Examples

>>> from nipype.interfaces import afni
>>> means = afni.Means()
>>> means.inputs.in_file_a = 'im1.nii'
>>> means.inputs.in_file_b = 'im2.nii'
>>> means.inputs.out_file =  'output.nii'
>>> means.cmdline
'3dMean -prefix output.nii im1.nii im2.nii'
>>> res = means.run()  

>>> from nipype.interfaces import afni
>>> means = afni.Means()
>>> means.inputs.in_file_a = 'im1.nii'
>>> means.inputs.out_file =  'output.nii'
>>> means.inputs.datum = 'short'
>>> means.cmdline
'3dMean -datum short -prefix output.nii im1.nii'
>>> res = means.run()
Mandatory Inputs:

in_file_a (a pathlike object or string representing an existing file) – Input file to 3dMean. Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • count (a boolean) – Compute count of non-zero voxels. Maps to a command-line argument: -count.

  • datum (a string) – Sets the data type of the output dataset. Maps to a command-line argument: -datum %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: {})

  • in_file_b (a pathlike object or string representing an existing file) – Another input file to 3dMean. Maps to a command-line argument: %s (position: -1).

  • mask_inter (a boolean) – Create intersection mask. Maps to a command-line argument: -mask_inter.

  • mask_union (a boolean) – Create union mask. Maps to a command-line argument: -mask_union.

  • non_zero (a boolean) – Use only non-zero values. Maps to a command-line argument: -non_zero.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • scale (a string) – Scaling of output. Maps to a command-line argument: -%sscale.

  • sqr (a boolean) – Mean square instead of value. Maps to a command-line argument: -sqr.

  • std_dev (a boolean) – Calculate std dev. Maps to a command-line argument: -stdev.

  • summ (a boolean) – Take sum, (not average). Maps to a command-line argument: -sum.

Outputs:

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

NetCorr

Link to code

Bases: AFNICommand

Wrapped executable: 3dNetCorr.

Calculate correlation matrix of a set of ROIs (using mean time series of each). Several networks may be analyzed simultaneously, one per brick.

For complete details, see the 3dNetCorr Documentation.

Examples

>>> from nipype.interfaces import afni
>>> ncorr = afni.NetCorr()
>>> ncorr.inputs.in_file = 'functional.nii'
>>> ncorr.inputs.mask = 'mask.nii'
>>> ncorr.inputs.in_rois = 'maps.nii'
>>> ncorr.inputs.ts_wb_corr = True
>>> ncorr.inputs.ts_wb_Z = True
>>> ncorr.inputs.fish_z = True
>>> ncorr.inputs.out_file = 'sub0.tp1.ncorr'
>>> ncorr.cmdline
'3dNetCorr -prefix sub0.tp1.ncorr -fish_z -inset functional.nii -in_rois maps.nii -mask mask.nii -ts_wb_Z -ts_wb_corr'
>>> res = ncorr.run()
Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – Input time series file (4D data set). Maps to a command-line argument: -inset %s.

  • in_rois (a pathlike object or string representing an existing file) – Input set of ROIs, each labelled with distinct integers. Maps to a command-line argument: -in_rois %s.

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: {})

  • fish_z (a boolean) – Switch to also output a matrix of Fisher Z-transform values for the corr coefs (r): Z = atanh(r) , (with Z=4 being output along matrix diagonals where r=1, as the r-to-Z conversion is ceilinged at Z = atanh(r=0.999329) = 4, which is still quite a high Pearson-r value. Maps to a command-line argument: -fish_z.

  • ignore_LT (a boolean) – Switch to ignore any label table labels in the ‘-in_rois’ file, if there are any labels attached. Maps to a command-line argument: -ignore_LT.

  • mask (a pathlike object or string representing an existing file) – Can include a whole brain mask within which to calculate correlation. Otherwise, data should be masked already. Maps to a command-line argument: -mask %s.

  • nifti (a boolean) – Output any correlation map files as NIFTI files (default is BRIK/HEAD). Only useful if using ‘-ts_wb_corr’ and/or ‘-ts_wb_Z’. Maps to a command-line argument: -nifti.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output file name part. Maps to a command-line argument: -prefix %s (position: 1).

  • output_mask_nonnull (a boolean) – Internally, this program checks for where there are nonnull time series, because we don’t like those, in general. With this flag, the user can output the determined mask of non-null time series. Maps to a command-line argument: -output_mask_nonnull.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • part_corr (a boolean) – Output the partial correlation matrix. Maps to a command-line argument: -part_corr.

  • push_thru_many_zeros (a boolean) – By default, this program will grind to a halt and refuse to calculate if any ROI contains >10 percent of voxels with null times series (i.e., each point is 0), as of April, 2017. This is because it seems most likely that hidden badness is responsible. However, if the user still wants to carry on the calculation anyways, then this option will allow one to push on through. However, if any ROI only has null time series, then the program will not calculate and the user will really, really, really need to address their masking. Maps to a command-line argument: -push_thru_many_zeros.

  • ts_indiv (a boolean) – Switch to create a directory for each network that contains the average time series for each ROI in individual files (each file has one line). The directories are labelled PREFIX_000_INDIV/, PREFIX_001_INDIV/, etc. (one per network). Within each directory, the files are labelled ROI_001.netts, ROI_002.netts, etc., with the numbers given by the actual ROI integer labels. Maps to a command-line argument: -ts_indiv.

  • ts_label (a boolean) – Additional switch when using ‘-ts_out’. Using this option will insert the integer ROI label at the start of each line of the *.netts file created. Thus, for a time series of length N, each line will have N+1 numbers, where the first is the integer ROI label and the subsequent N are scientific notation values. Maps to a command-line argument: -ts_label.

  • ts_out (a boolean) – Switch to output the mean time series of the ROIs that have been used to generate the correlation matrices. Output filenames mirror those of the correlation matrix files, with a ‘.netts’ postfix. Maps to a command-line argument: -ts_out.

  • ts_wb_Z (a boolean) – Same as above in ‘-ts_wb_corr’, except that the maps have been Fisher transformed to Z-scores the relation: Z=atanh(r). To avoid infinities in the transform, Pearson values are effectively capped at |r| = 0.999329 (where |Z| = 4.0). Files are labelled WB_Z_ROI_001+orig, etc. Maps to a command-line argument: -ts_wb_Z.

  • ts_wb_corr (a boolean) – Switch to create a set of whole brain correlation maps. Performs whole brain correlation for each ROI’s average time series; this will automatically create a directory for each network that contains the set of whole brain correlation maps (Pearson ‘r’s). The directories are labelled as above for ‘-ts_indiv’ Within each directory, the files are labelled WB_CORR_ROI_001+orig, WB_CORR_ROI_002+orig, etc., with the numbers given by the actual ROI integer labels. Maps to a command-line argument: -ts_wb_corr.

  • ts_wb_strlabel (a boolean) – By default, ‘-ts_wb_{corr,Z}’ output files are named using the int number of a given ROI, such as: WB_Z_ROI_001+orig. With this option, one can replace the int (such as ‘001’) with the string label (such as ‘L-thalamus’) if one has a labeltable attached to the file. Maps to a command-line argument: -ts_wb_strlabel.

  • weight_ts (a pathlike object or string representing an existing file) – Input a 1D file WTS of weights that will be applied multiplicatively to each ROI’s average time series. WTS can be a column- or row-file of values, but it must have the same length as the input time series volume. If the initial average time series was A[n] for n=0,..,(N-1) time points, then applying a set of weights W[n] of the same length from WTS would produce a new time series: B[n] = A[n] * W[n]. Maps to a command-line argument: -weight_ts %s.

Outputs:

  • out_corr_maps (a list of items which are a pathlike object or string representing a file) – Output correlation maps in Pearson and/or Z-scores.

  • out_corr_matrix (a pathlike object or string representing a file) – Output correlation matrix between ROIs written to a text file with .netcc suffix.

OutlierCount

Link to code

Bases: CommandLine

Wrapped executable: 3dToutcount.

Calculates number of ‘outliers’ at each time point of a a 3D+time dataset.

For complete details, see the 3dToutcount Documentation

Examples

>>> from nipype.interfaces import afni
>>> toutcount = afni.OutlierCount()
>>> toutcount.inputs.in_file = 'functional.nii'
>>> toutcount.cmdline  
'3dToutcount -qthr 0.00100 functional.nii'
>>> res = toutcount.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input dataset. Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • autoclip (a boolean) – Clip off small voxels. Maps to a command-line argument: -autoclip. Mutually exclusive with inputs: mask. (Nipype default value: False)

  • automask (a boolean) – Clip off small voxels. Maps to a command-line argument: -automask. Mutually exclusive with inputs: mask. (Nipype default value: False)

  • 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: {})

  • fraction (a boolean) – Write out the fraction of masked voxels which are outliers at each timepoint. Maps to a command-line argument: -fraction. (Nipype default value: False)

  • interval (a boolean) – Write out the median + 3.5 MAD of outlier count with each timepoint. Maps to a command-line argument: -range. (Nipype default value: False)

  • legendre (a boolean) – Use Legendre polynomials. Maps to a command-line argument: -legendre. (Nipype default value: False)

  • mask (a pathlike object or string representing an existing file) – Only count voxels within the given mask. Maps to a command-line argument: -mask %s. Mutually exclusive with inputs: autoclip, automask.

  • out_file (a pathlike object or string representing a file) – Capture standard output.

  • outliers_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -save %s.

  • polort (an integer) – Detrend each voxel timeseries with polynomials. Maps to a command-line argument: -polort %d.

  • qthr (0.0 <= a floating point number <= 1.0) – Indicate a value for q to compute alpha. Maps to a command-line argument: -qthr %.5f. (Nipype default value: 0.001)

  • save_outliers (a boolean) – Enables out_file option. (Nipype default value: False)

Outputs:

  • out_file (a pathlike object or string representing a file) – Capture standard output.

  • out_outliers (a pathlike object or string representing an existing file) – Output image file name.

QualityIndex

Link to code

Bases: CommandLine

Wrapped executable: 3dTqual.

Computes a quality index for each sub-brick in a 3D+time dataset. The output is a 1D time series with the index for each sub-brick. The results are written to stdout.

Examples

>>> from nipype.interfaces import afni
>>> tqual = afni.QualityIndex()
>>> tqual.inputs.in_file = 'functional.nii'
>>> tqual.cmdline  
'3dTqual functional.nii > functional_tqual'
>>> res = tqual.run()

See also

For complete details, see the 3dTqual Documentation

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input dataset. Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • autoclip (a boolean) – Clip off small voxels. Maps to a command-line argument: -autoclip. Mutually exclusive with inputs: mask. (Nipype default value: False)

  • automask (a boolean) – Clip off small voxels. Maps to a command-line argument: -automask. Mutually exclusive with inputs: mask. (Nipype default value: False)

  • clip (a float) – Clip off values below. Maps to a command-line argument: -clip %f.

  • 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: {})

  • interval (a boolean) – Write out the median + 3.5 MAD of outlier count with each timepoint. Maps to a command-line argument: -range. (Nipype default value: False)

  • mask (a pathlike object or string representing an existing file) – Compute correlation only across masked voxels. Maps to a command-line argument: -mask %s. Mutually exclusive with inputs: autoclip, automask.

  • out_file (a pathlike object or string representing a file) – Capture standard output. Maps to a command-line argument: > %s (position: -1).

  • quadrant (a boolean) – Similar to -spearman, but using 1 minus the quadrant correlation coefficient as the quality index. Maps to a command-line argument: -quadrant. (Nipype default value: False)

  • spearman (a boolean) – Quality index is 1 minus the Spearman (rank) correlation coefficient of each sub-brick with the median sub-brick. (default). Maps to a command-line argument: -spearman. (Nipype default value: False)

Outputs:

out_file (a pathlike object or string representing a file) – File containing the captured standard output.

Qwarp

Link to code

Bases: AFNICommand

Wrapped executable: 3dQwarp.

Allineate your images prior to passing them to this workflow.

Examples

>>> from nipype.interfaces import afni
>>> qwarp = afni.Qwarp()
>>> qwarp.inputs.in_file = 'sub-01_dir-LR_epi.nii.gz'
>>> qwarp.inputs.nopadWARP = True
>>> qwarp.inputs.base_file = 'sub-01_dir-RL_epi.nii.gz'
>>> qwarp.inputs.plusminus = True
>>> qwarp.cmdline
'3dQwarp -base sub-01_dir-RL_epi.nii.gz -source sub-01_dir-LR_epi.nii.gz -nopadWARP -prefix ppp_sub-01_dir-LR_epi -plusminus'
>>> res = qwarp.run()  

>>> from nipype.interfaces import afni
>>> qwarp = afni.Qwarp()
>>> qwarp.inputs.in_file = 'structural.nii'
>>> qwarp.inputs.base_file = 'mni.nii'
>>> qwarp.inputs.resample = True
>>> qwarp.cmdline
'3dQwarp -base mni.nii -source structural.nii -prefix ppp_structural -resample'
>>> res = qwarp.run()  

>>> from nipype.interfaces import afni
>>> qwarp = afni.Qwarp()
>>> qwarp.inputs.in_file = 'structural.nii'
>>> qwarp.inputs.base_file = 'epi.nii'
>>> qwarp.inputs.out_file = 'anatSSQ.nii.gz'
>>> qwarp.inputs.resample = True
>>> qwarp.inputs.lpc = True
>>> qwarp.inputs.verb = True
>>> qwarp.inputs.iwarp = True
>>> qwarp.inputs.blur = [0,3]
>>> qwarp.cmdline
'3dQwarp -base epi.nii -blur 0.0 3.0 -source structural.nii -iwarp -prefix anatSSQ.nii.gz -resample -verb -lpc'

>>> res = qwarp.run()  

>>> from nipype.interfaces import afni
>>> qwarp = afni.Qwarp()
>>> qwarp.inputs.in_file = 'structural.nii'
>>> qwarp.inputs.base_file = 'mni.nii'
>>> qwarp.inputs.duplo = True
>>> qwarp.inputs.blur = [0,3]
>>> qwarp.cmdline
'3dQwarp -base mni.nii -blur 0.0 3.0 -duplo -source structural.nii -prefix ppp_structural'

>>> res = qwarp.run()  

>>> from nipype.interfaces import afni
>>> qwarp = afni.Qwarp()
>>> qwarp.inputs.in_file = 'structural.nii'
>>> qwarp.inputs.base_file = 'mni.nii'
>>> qwarp.inputs.duplo = True
>>> qwarp.inputs.minpatch = 25
>>> qwarp.inputs.blur = [0,3]
>>> qwarp.inputs.out_file = 'Q25'
>>> qwarp.cmdline
'3dQwarp -base mni.nii -blur 0.0 3.0 -duplo -source structural.nii -minpatch 25 -prefix Q25'

>>> res = qwarp.run()  
>>> qwarp2 = afni.Qwarp()
>>> qwarp2.inputs.in_file = 'structural.nii'
>>> qwarp2.inputs.base_file = 'mni.nii'
>>> qwarp2.inputs.blur = [0,2]
>>> qwarp2.inputs.out_file = 'Q11'
>>> qwarp2.inputs.inilev = 7
>>> qwarp2.inputs.iniwarp = ['Q25_warp+tlrc.HEAD']
>>> qwarp2.cmdline
'3dQwarp -base mni.nii -blur 0.0 2.0 -source structural.nii -inilev 7 -iniwarp Q25_warp+tlrc.HEAD -prefix Q11'

>>> res2 = qwarp2.run()  
>>> res2 = qwarp2.run()  
>>> qwarp3 = afni.Qwarp()
>>> qwarp3.inputs.in_file = 'structural.nii'
>>> qwarp3.inputs.base_file = 'mni.nii'
>>> qwarp3.inputs.allineate = True
>>> qwarp3.inputs.allineate_opts = '-cose lpa -verb'
>>> qwarp3.cmdline
"3dQwarp -allineate -allineate_opts '-cose lpa -verb' -base mni.nii -source structural.nii -prefix ppp_structural"

>>> res3 = qwarp3.run()

See also

For complete details, see the 3dQwarp Documentation.

Mandatory Inputs:

  • base_file (a pathlike object or string representing an existing file) – Base image (opposite phase encoding direction than source image). Maps to a command-line argument: -base %s.

  • in_file (a pathlike object or string representing an existing file) – Source image (opposite phase encoding direction than base image). Maps to a command-line argument: -source %s.

Optional Inputs:

  • Qfinal (a boolean) – At the finest patch size (the final level), use Hermite quintic polynomials for the warp instead of cubic polynomials.

    • In a 3D ‘patch’, there are 2x2x2x3=24 cubic polynomial basis function parameters over which to optimize (2 polynomials dependent on each of the x,y,z directions, and 3 different directions of displacement).

    • There are 3x3x3x3=81 quintic polynomial parameters per patch.

    • With -Qfinal, the final level will have more detail in the allowed warps, at the cost of yet more CPU time.

    • However, no patch below 7x7x7 in size will be done with quintic polynomials.

    • This option is also not usually needed, and is experimental.

    Maps to a command-line argument: -Qfinal.

  • Qonly (a boolean) – Use Hermite quintic polynomials at all levels.

    • Very slow (about 4 times longer). Also experimental.

    • Will produce a (discrete representation of a) C2 warp.

    Maps to a command-line argument: -Qonly.

  • allineate (a boolean) – This option will make 3dQwarp run 3dAllineate first, to align the source dataset to the base with an affine transformation. It will then use that alignment as a starting point for the nonlinear warping. Maps to a command-line argument: -allineate.

  • allineate_opts (a string) – Add extra options to the 3dAllineate command to be run by 3dQwarp. Maps to a command-line argument: -allineate_opts %s. Requires inputs: allineate.

  • allsave (a boolean) – This option lets you save the output warps from each level” of the refinement process. Mostly used for experimenting.” Will only save all the outputs if the program terminates” normally – if it crashes, or freezes, then all these” warps are lost. Maps to a command-line argument: -allsave. Mutually exclusive with inputs: nopadWARP, duplo, plusminus.

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

  • ballopt (a boolean) – Normally, the incremental warp parameters are optimized insidea rectangular ‘box’ (24 dimensional for cubic patches, 81 forquintic patches), whose limits define the amount of distortionallowed at each step. Using ‘-ballopt’ switches these limitsto be applied to a ‘ball’ (interior of a hypersphere), whichcan allow for larger incremental displacements. Use thisoption if you think things need to be able to move farther. Maps to a command-line argument: -ballopt. Mutually exclusive with inputs: workhard, boxopt.

  • baxopt (a boolean) – Use the ‘box’ optimization limits instead of the ‘ball’[this is the default at present].Note that if ‘-workhard’ is used, then ball and box optimizationare alternated in the different iterations at each level, sothese two options have no effect in that case. Maps to a command-line argument: -boxopt. Mutually exclusive with inputs: workhard, ballopt.

  • blur (a list of from 1 to 2 items which are a float) – Gaussian blur the input images by ‘bb’ (FWHM) voxels before doing the alignment (the output dataset will not be blurred). The default is 2.345 (for no good reason).

    • Optionally, you can provide 2 values for ‘bb’, and then the first one is applied to the base volume, the second to the source volume. e.g., ‘-blur 0 3’ to skip blurring the base image (if the base is a blurry template, for example).

    • A negative blur radius means to use 3D median filtering, rather than Gaussian blurring. This type of filtering will better preserve edges, which can be important in alignment.

    • If the base is a template volume that is already blurry, you probably don’t want to blur it again, but blurring the source volume a little is probably a good idea, to help the program avoid trying to match tiny features.

    • Note that -duplo will blur the volumes some extra amount for the initial small-scale warping, to make that phase of the program converge more rapidly.

    Maps to a command-line argument: -blur %s.

  • duplo (a boolean) – Start off with 1/2 scale versions of the volumes,” for getting a speedy coarse first alignment.”

    • Then scales back up to register the full volumes.” The goal is greater speed, and it seems to help this” positively piggish program to be more expeditious.”

    • However, accuracy is somewhat lower with ‘-duplo’,” for reasons that currently elude Zhark; for this reason,” the Emperor does not usually use ‘-duplo’.

    Maps to a command-line argument: -duplo. Mutually exclusive with inputs: gridlist, maxlev, inilev, iniwarp, plusminus, allsave.

  • emask (a pathlike object or string representing an existing file) – Here, ‘ee’ is a dataset to specify a mask of voxelsto EXCLUDE from the analysis – all voxels in ‘ee’that are NONZERO will not be used in the alignment.The base image always automasked – the emask isextra, to indicate voxels you definitely DON’T wantincluded in the matching process, even if they areinside the brain. Maps to a command-line argument: -emask %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: {})

  • expad (an integer) – This option instructs the program to pad the warp by an extra’EE’ voxels (and then 3dQwarp starts optimizing it).This option is seldom needed, but can be useful if youmight later catenate the nonlinear warp – via 3dNwarpCat –with an affine transformation that contains a large shift.Under that circumstance, the nonlinear warp might be shiftedpartially outside its original grid, so expanding that gridcan avoid this problem.Note that this option perforce turns off ‘-nopadWARP’. Maps to a command-line argument: -expad %d. Mutually exclusive with inputs: nopadWARP.

  • gridlist (a pathlike object or string representing an existing file) – This option provides an alternate way to specify the patch grid sizes used in the warp optimization process. ‘gl’ is a 1D file with a list of patches to use – in most cases, you will want to use it in the following form: -gridlist '1D: 0 151 101 75 51'

    • Here, a 0 patch size means the global domain. Patch sizes otherwise should be odd integers >= 5.

    • If you use the ‘0’ patch size again after the first position, you will actually get an iteration at the size of the default patch level 1, where the patch sizes are 75% of the volume dimension. There is no way to force the program to literally repeat the sui generis step of lev=0.

    Maps to a command-line argument: -gridlist %s. Mutually exclusive with inputs: duplo, plusminus.

  • hel (a boolean) – Hellinger distance: a matching function for the adventurousThis option has NOT be extensively tested for usefulnessand should be considered experimental at this infundibulum. Maps to a command-line argument: -hel. Mutually exclusive with inputs: nmi, mi, lpc, lpa, pear.

  • inilev (an integer) – The initial refinement ‘level’ at which to start.

    • Usually used with -iniwarp; CANNOT be used with -duplo.

    • The combination of -inilev and -iniwarp lets you take the results of a previous 3dQwarp run and refine them further: Note that the source dataset in the second run is the SAME as in the first run. If you don’t see why this is necessary, then you probably need to seek help from an AFNI guru.

    Maps to a command-line argument: -inilev %d. Mutually exclusive with inputs: duplo.

  • iniwarp (a list of items which are a pathlike object or string representing an existing file) – A dataset with an initial nonlinear warp to use.

    • If this option is not used, the initial warp is the identity.

    • You can specify a catenation of warps (in quotes) here, as in program 3dNwarpApply.

    • As a special case, if you just input an affine matrix in a .1D file, that will work also – it is treated as giving the initial warp via the string “IDENT(base_dataset) matrix_file.aff12.1D”.

    • You CANNOT use this option with -duplo !!

    • -iniwarp is usually used with -inilev to re-start 3dQwarp from a previous stopping point.

    Maps to a command-line argument: -iniwarp %s. Mutually exclusive with inputs: duplo.

  • iwarp (a boolean) – Do compute and save the _WARPINV file. Maps to a command-line argument: -iwarp. Mutually exclusive with inputs: plusminus.

  • lpa (a boolean) – Local Pearson maximization. This option has not be extensively tested. Maps to a command-line argument: -lpa. Mutually exclusive with inputs: nmi, mi, lpc, hel, pear.

  • lpc (a boolean) – Local Pearson minimization (i.e., EPI-T1 registration)This option has not be extensively testedIf you use ‘-lpc’, then ‘-maxlev 0’ is automatically set.If you want to go to more refined levels, you can set ‘-maxlev’This should be set up to have lpc as the second to last argumentand maxlev as the second to last argument, as needed by AFNIUsing maxlev > 1 is not recommended for EPI-T1 alignment. Maps to a command-line argument: -lpc (position: -2). Mutually exclusive with inputs: nmi, mi, hel, lpa, pear.

  • maxlev (an integer) – The initial refinement ‘level’ at which to start.

    • Usually used with -iniwarp; CANNOT be used with -duplo.

    • The combination of -inilev and -iniwarp lets you take the results of a previous 3dQwarp run and refine them further: Note that the source dataset in the second run is the SAME as in the first run. If you don’t see why this is necessary, then you probably need to seek help from an AFNI guru.

    Maps to a command-line argument: -maxlev %d (position: -1). Mutually exclusive with inputs: duplo.

  • mi (a boolean) – Mutual Information: a matching function for the adventurousThis option has NOT be extensively tested for usefulnessand should be considered experimental at this infundibulum. Maps to a command-line argument: -mi. Mutually exclusive with inputs: mi, hel, lpc, lpa, pear.

  • minpatch (an integer) – The value of mm should be an odd integer.

    • The default value of mm is 25.

    • For more accurate results than mm=25, try 19 or 13.

    • The smallest allowed patch size is 5.

    • You may want stop at a larger patch size (say 7 or 9) and use the -Qfinal option to run that final level with quintic warps, which might run faster and provide the same degree of warp detail.

    • Trying to make two different brain volumes match in fine detail is usually a waste of time, especially in humans. There is too much variability in anatomy to match gyrus to gyrus accurately. For this reason, the default minimum patch size is 25 voxels. Using a smaller ‘-minpatch’ might try to force the warp to match features that do not match, and the result can be useless image distortions – another reason to LOOK AT THE RESULTS.

    Maps to a command-line argument: -minpatch %d.

  • nmi (a boolean) – Normalized Mutual Information: a matching function for the adventurousThis option has NOT been extensively tested for usefulnessand should be considered experimental at this infundibulum. Maps to a command-line argument: -nmi. Mutually exclusive with inputs: nmi, hel, lpc, lpa, pear.

  • noXdis (a boolean) – Warp will not displace in x direction. Maps to a command-line argument: -noXdis.

  • noYdis (a boolean) – Warp will not displace in y direction. Maps to a command-line argument: -noYdis.

  • noZdis (a boolean) – Warp will not displace in z direction. Maps to a command-line argument: -noZdis.

  • noneg (a boolean) – Replace negative values in either input volume with 0.

    • If there ARE negative input values, and you do NOT use -noneg, then strict Pearson correlation will be used, since the ‘clipped’ method only is implemented for non-negative volumes.

    • ‘-noneg’ is not the default, since there might be situations where you want to align datasets with positive and negative values mixed.

    • But, in many cases, the negative values in a dataset are just the result of interpolation artifacts (or other peculiarities), and so they should be ignored. That is what ‘-noneg’ is for.

    Maps to a command-line argument: -noneg.

  • nopad (a boolean) – Do NOT use zero-padding on the 3D base and source images. [Default == zero-pad, if needed]

    • The underlying model for deformations goes to zero at the edge of the volume being warped. However, if there is significant data near an edge of the volume, then it won’t get displaced much, and so the results might not be good.

    • Zero padding is designed as a way to work around this potential problem. You should NOT need the ‘-nopad’ option for any reason that Zhark can think of, but it is here to be symmetrical with 3dAllineate.

    • Note that the output (warped from source) dataset will be on the base dataset grid whether or not zero-padding is allowed. However, unless you use the following option, allowing zero-padding (i.e., the default operation) will make the output WARP dataset(s) be on a larger grid (also see ‘-expad’ below).

    Maps to a command-line argument: -nopad.

  • nopadWARP (a boolean) – If for some reason you require the warp volume tomatch the base volume, then use this option to have the outputWARP dataset(s) truncated. Maps to a command-line argument: -nopadWARP. Mutually exclusive with inputs: allsave, expad.

  • nopenalty (a boolean) – Replace negative values in either input volume with 0.

    • If there ARE negative input values, and you do NOT use -noneg, then strict Pearson correlation will be used, since the ‘clipped’ method only is implemented for non-negative volumes.

    • ‘-noneg’ is not the default, since there might be situations where you want to align datasets with positive and negative values mixed.

    • But, in many cases, the negative values in a dataset are just the result of interpolation artifacts (or other peculiarities), and so they should be ignored. That is what ‘-noneg’ is for.

    Maps to a command-line argument: -nopenalty.

  • nowarp (a boolean) – Do not save the _WARP file. Maps to a command-line argument: -nowarp.

  • noweight (a boolean) – If you want a binary weight (the old default), use this option.That is, each voxel in the base volume automask will beweighted the same in the computation of the cost functional. Maps to a command-line argument: -noweight.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Sets the prefix/suffix for the output datasets.

    • The source dataset is warped to match the base and gets prefix ‘ppp’. (Except if ‘-plusminus’ is used

    • The final interpolation to this output dataset is done using the ‘wsinc5’ method. See the output of 3dAllineate -HELP (in the “Modifying ‘-final wsinc5’” section) for the lengthy technical details.

    • The 3D warp used is saved in a dataset with prefix ‘ppp_WARP’ – this dataset can be used with 3dNwarpApply and 3dNwarpCat, for example.

    • To be clear, this is the warp from source dataset coordinates to base dataset coordinates, where the values at each base grid point are the xyz displacements needed to move that grid point’s xyz values to the corresponding xyz values in the source dataset: base( (x,y,z) + WARP(x,y,z) ) matches source(x,y,z) Another way to think of this warp is that it ‘pulls’ values back from source space to base space.

    • 3dNwarpApply would use ‘ppp_WARP’ to transform datasets aligned with the source dataset to be aligned with the base dataset.

    If you do NOT want this warp saved, use the option ‘-nowarp’. (However, this warp is usually the most valuable possible output!)

    • If you want to calculate and save the inverse 3D warp, use the option ‘-iwarp’. This inverse warp will then be saved in a dataset with prefix ‘ppp_WARPINV’.

    • This inverse warp could be used to transform data from base space to source space, if you need to do such an operation.

    • You can easily compute the inverse later, say by a command like 3dNwarpCat -prefix Z_WARPINV ‘INV(Z_WARP+tlrc)’ or the inverse can be computed as needed in 3dNwarpApply, like 3dNwarpApply -nwarp ‘INV(Z_WARP+tlrc)’ -source Dataset.nii …

    Maps to a command-line argument: -prefix %s.

  • out_weight_file (a pathlike object or string representing a file) – Write the weight volume to disk as a dataset. Maps to a command-line argument: -wtprefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • overwrite (a boolean) – Overwrite outputs. Maps to a command-line argument: -overwrite.

  • pblur (a list of from 1 to 2 items which are a float) – Use progressive blurring; that is, for larger patch sizes, the amount of blurring is larger. The general idea is to avoid trying to match finer details when the patch size and incremental warps are coarse. When ‘-blur’ is used as well, it sets a minimum amount of blurring that will be used. [06 Aug 2014 – ‘-pblur’ may become the default someday].

    • You can optionally give the fraction of the patch size that is used for the progressive blur by providing a value between 0 and 0.25 after ‘-pblur’. If you provide TWO values, the the first fraction is used for progressively blurring the base image and the second for the source image. The default parameters when just ‘-pblur’ is given is the same as giving the options as ‘-pblur 0.09 0.09’.

    • ‘-pblur’ is useful when trying to match 2 volumes with high amounts of detail; e.g, warping one subject’s brain image to match another’s, or trying to warp to match a detailed template.

    • Note that using negative values with ‘-blur’ means that the progressive blurring will be done with median filters, rather than Gaussian linear blurring.

    Note: The combination of the -allineate and -pblur options will make the results of using 3dQwarp to align to a template somewhat less sensitive to initial head position and scaling. Maps to a command-line argument: -pblur %s.

  • pear (a boolean) – Use strict Pearson correlation for matching.Not usually recommended, since the ‘clipped Pearson’ methodused by default will reduce the impact of outlier values. Maps to a command-line argument: -pear.

  • penfac (a float) – Use this value to weight the penalty. The default value is 1. Larger values mean the penalty counts more, reducing grid distortions, insha’Allah; ‘-nopenalty’ is the same as ‘-penfac 0’. In 23 Sep 2013 Zhark increased the default value of the penalty by a factor of 5, and also made it get progressively larger with each level of refinement. Thus, warping results will vary from earlier instances of 3dQwarp.

    • The progressive increase in the penalty at higher levels means that the ‘cost function’ can actually look like the alignment is getting worse when the levels change.

    • IF you wish to turn off this progression, for whatever reason (e.g., to keep compatibility with older results), use the option ‘-penold’.To be completely compatible with the older 3dQwarp, you’ll also have to use ‘-penfac 0.2’.

    Maps to a command-line argument: -penfac %f.

  • plusminus (a boolean) – Normally, the warp displacements dis(x) are defined to match base(x) to source(x+dis(x)). With this option, the match is between base(x-dis(x)) and source(x+dis(x)) – the two images ‘meet in the middle’.

    • One goal is to mimic the warping done to MRI EPI data by field inhomogeneities, when registering between a ‘blip up’ and a ‘blip down’ down volume, which will have opposite distortions.

    • Define Wp(x) = x+dis(x) and Wm(x) = x-dis(x). Then since base(Wm(x)) matches source(Wp(x)), by substituting INV(Wm(x)) wherever we see x, we have base(x) matches source(Wp(INV(Wm(x)))); that is, the warp V(x) that one would get from the ‘usual’ way of running 3dQwarp is V(x) = Wp(INV(Wm(x))).

    • Conversely, we can calculate Wp(x) in terms of V(x) as follows: If V(x) = x + dv(x), define Vh(x) = x + dv(x)/2; then Wp(x) = V(INV(Vh(x)))

    • With the above formulas, it is possible to compute Wp(x) from V(x) and vice-versa, using program 3dNwarpCalc. The requisite commands are left as an exercise for the aspiring AFNI Jedi Master.

    • You can use the semi-secret ‘-pmBASE’ option to get the V(x) warp and the source dataset warped to base space, in addition to the Wp(x) ‘_PLUS’ and Wm(x) ‘_MINUS’ warps.

      • Alas: -plusminus does not work with -duplo or -allineate :-(

      • However, you can use -iniwarp with -plusminus :-)

      • The outputs have _PLUS (from the source dataset) and _MINUS (from the base dataset) in their filenames, in addition to the prefix. The -iwarp option, if present, will be ignored.

    Maps to a command-line argument: -plusminus. Mutually exclusive with inputs: duplo, allsave, iwarp.

  • quiet (a boolean) – Cut out most of the fun fun fun progress messages :-(. Maps to a command-line argument: -quiet. Mutually exclusive with inputs: verb.

  • resample (a boolean) – This option simply resamples the source dataset to match the base dataset grid. You can use this if the two datasets overlap well (as seen in the AFNI GUI), but are not on the same 3D grid.

    • If they don’t overlap well, allineate them first

    • The reampling here is done with the ‘wsinc5’ method, which has very little blurring artifact.

    • If the base and source datasets ARE on the same 3D grid, then the -resample option will be ignored.

    • You CAN use -resample with these 3dQwarp options: -plusminus -inilev -iniwarp -duplo

    Maps to a command-line argument: -resample.

  • verb (a boolean) – More detailed description of the process. Maps to a command-line argument: -verb. Mutually exclusive with inputs: quiet.

  • wball (a list of from 5 to 5 items which are an integer) – “-wball x y z r f Enhance automatic weight from ‘-useweight’ by a factor of 1+f*Gaussian(FWHM=r) centered in the base image at DICOM coordinates (x,y,z) and with radius ‘r’. The goal of this option is to try and make the alignment better in a specific part of the brain. Example: -wball 0 14 6 30 40 to emphasize the thalamic area (in MNI/Talairach space).

    • The ‘r’ parameter must be positive!

    • The ‘f’ parameter must be between 1 and 100 (inclusive).

    • ‘-wball’ does nothing if you input your own weight with the ‘-weight’ option.

    • ‘-wball’ does change the binary weight created by the ‘-noweight’ option.

    • You can only use ‘-wball’ once in a run of 3dQwarp.

    The effect of ‘-wball’ is not dramatic. The example above makes the average brain image across a collection of subjects a little sharper in the thalamic area, which might have some small value. If you care enough about alignment to use ‘-wball’, then you should examine the results from 3dQwarp for each subject, to see if the alignments are good enough for your purposes. Maps to a command-line argument: -wball %s. Mutually exclusive with inputs: wmask.

  • weight (a pathlike object or string representing an existing file) – Instead of computing the weight from the base dataset,directly input the weight volume from dataset ‘www’.Useful if you know what over parts of the base image youwant to emphasize or de-emphasize the matching functional. Maps to a command-line argument: -weight %s.

  • wmask (a tuple of the form: (a pathlike object or string representing an existing file, a float)) – Similar to ‘-wball’, but here, you provide a dataset ‘ws’ that indicates where to increase the weight.

    • The ‘ws’ dataset must be on the same 3D grid as the base dataset.

    • ‘ws’ is treated as a mask – it only matters where it is nonzero – otherwise, the values inside are not used.

    • After ‘ws’ comes the factor ‘f’ by which to increase the automatically computed weight. Where ‘ws’ is nonzero, the weighting will be multiplied by (1+f).

    • As with ‘-wball’, the factor ‘f’ should be between 1 and 100.

    Maps to a command-line argument: -wpass %s %f. Mutually exclusive with inputs: wball.

  • workhard (a boolean) – Iterate more times, which can help when the volumes are hard to align at all, or when you hope to get a more precise alignment.

    • Slows the program down (possibly a lot), of course.

    • When you combine ‘-workhard’ with ‘-duplo’, only the full size volumes get the extra iterations.

    • For finer control over which refinement levels work hard, you can use this option in the form (for example) -workhard:4:7 which implies the extra iterations will be done at levels 4, 5, 6, and 7, but not otherwise.

    • You can also use ‘-superhard’ to iterate even more, but this extra option will REALLY slow things down.

      • Under most circumstances, you should not need to use either -workhard or -superhard.

      • The fastest way to register to a template image is via the -duplo option, and without the -workhard or -superhard options.

      • If you use this option in the form ‘-Workhard’ (first letter in upper case), then the second iteration at each level is done with quintic polynomial warps.

    Maps to a command-line argument: -workhard. Mutually exclusive with inputs: boxopt, ballopt.

Outputs:

  • base_warp (a pathlike object or string representing a file) – Displacement in mm for the base image.If plus minus is used, this is the field suceptibility correctionwarp (in ‘mm’) for base image. This is only output if plusminusor iwarp options are passed.

  • source_warp (a pathlike object or string representing a file) – Displacement in mm for the source image.If plusminus is used this is the field suceptibility correctionwarp (in ‘mm’) for source image.

  • warped_base (a pathlike object or string representing a file) – Undistorted base file.

  • warped_source (a pathlike object or string representing a file) – Warped source file. If plusminus is used, this is the undistortedsource file.

  • weights (a pathlike object or string representing a file) – Auto-computed weight volume.

QwarpPlusMinus

Link to code

Bases: Qwarp

Wrapped executable: 3dQwarp.

A version of 3dQwarp for performing field susceptibility correction using two images with opposing phase encoding directions.

Examples

>>> from nipype.interfaces import afni
>>> qwarp = afni.QwarpPlusMinus()
>>> qwarp.inputs.in_file = 'sub-01_dir-LR_epi.nii.gz'
>>> qwarp.inputs.nopadWARP = True
>>> qwarp.inputs.base_file = 'sub-01_dir-RL_epi.nii.gz'
>>> qwarp.cmdline
'3dQwarp -prefix Qwarp.nii.gz -plusminus -base sub-01_dir-RL_epi.nii.gz -source sub-01_dir-LR_epi.nii.gz -nopadWARP'
>>> res = warp.run()

See also

For complete details, see the 3dQwarp Documentation.

Mandatory Inputs:

  • base_file (a pathlike object or string representing an existing file) – Base image (opposite phase encoding direction than source image). Maps to a command-line argument: -base %s.

  • in_file (a pathlike object or string representing an existing file) – Source image (opposite phase encoding direction than base image). Maps to a command-line argument: -source %s.

Optional Inputs:

  • Qfinal (a boolean) – At the finest patch size (the final level), use Hermite quintic polynomials for the warp instead of cubic polynomials.

    • In a 3D ‘patch’, there are 2x2x2x3=24 cubic polynomial basis function parameters over which to optimize (2 polynomials dependent on each of the x,y,z directions, and 3 different directions of displacement).

    • There are 3x3x3x3=81 quintic polynomial parameters per patch.

    • With -Qfinal, the final level will have more detail in the allowed warps, at the cost of yet more CPU time.

    • However, no patch below 7x7x7 in size will be done with quintic polynomials.

    • This option is also not usually needed, and is experimental.

    Maps to a command-line argument: -Qfinal.

  • Qonly (a boolean) – Use Hermite quintic polynomials at all levels.

    • Very slow (about 4 times longer). Also experimental.

    • Will produce a (discrete representation of a) C2 warp.

    Maps to a command-line argument: -Qonly.

  • allineate (a boolean) – This option will make 3dQwarp run 3dAllineate first, to align the source dataset to the base with an affine transformation. It will then use that alignment as a starting point for the nonlinear warping. Maps to a command-line argument: -allineate.

  • allineate_opts (a string) – Add extra options to the 3dAllineate command to be run by 3dQwarp. Maps to a command-line argument: -allineate_opts %s. Requires inputs: allineate.

  • allsave (a boolean) – This option lets you save the output warps from each level” of the refinement process. Mostly used for experimenting.” Will only save all the outputs if the program terminates” normally – if it crashes, or freezes, then all these” warps are lost. Maps to a command-line argument: -allsave. Mutually exclusive with inputs: nopadWARP, duplo, plusminus.

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

  • ballopt (a boolean) – Normally, the incremental warp parameters are optimized insidea rectangular ‘box’ (24 dimensional for cubic patches, 81 forquintic patches), whose limits define the amount of distortionallowed at each step. Using ‘-ballopt’ switches these limitsto be applied to a ‘ball’ (interior of a hypersphere), whichcan allow for larger incremental displacements. Use thisoption if you think things need to be able to move farther. Maps to a command-line argument: -ballopt. Mutually exclusive with inputs: workhard, boxopt.

  • baxopt (a boolean) – Use the ‘box’ optimization limits instead of the ‘ball’[this is the default at present].Note that if ‘-workhard’ is used, then ball and box optimizationare alternated in the different iterations at each level, sothese two options have no effect in that case. Maps to a command-line argument: -boxopt. Mutually exclusive with inputs: workhard, ballopt.

  • blur (a list of from 1 to 2 items which are a float) – Gaussian blur the input images by ‘bb’ (FWHM) voxels before doing the alignment (the output dataset will not be blurred). The default is 2.345 (for no good reason).

    • Optionally, you can provide 2 values for ‘bb’, and then the first one is applied to the base volume, the second to the source volume. e.g., ‘-blur 0 3’ to skip blurring the base image (if the base is a blurry template, for example).

    • A negative blur radius means to use 3D median filtering, rather than Gaussian blurring. This type of filtering will better preserve edges, which can be important in alignment.

    • If the base is a template volume that is already blurry, you probably don’t want to blur it again, but blurring the source volume a little is probably a good idea, to help the program avoid trying to match tiny features.

    • Note that -duplo will blur the volumes some extra amount for the initial small-scale warping, to make that phase of the program converge more rapidly.

    Maps to a command-line argument: -blur %s.

  • duplo (a boolean) – Start off with 1/2 scale versions of the volumes,” for getting a speedy coarse first alignment.”

    • Then scales back up to register the full volumes.” The goal is greater speed, and it seems to help this” positively piggish program to be more expeditious.”

    • However, accuracy is somewhat lower with ‘-duplo’,” for reasons that currently elude Zhark; for this reason,” the Emperor does not usually use ‘-duplo’.

    Maps to a command-line argument: -duplo. Mutually exclusive with inputs: gridlist, maxlev, inilev, iniwarp, plusminus, allsave.

  • emask (a pathlike object or string representing an existing file) – Here, ‘ee’ is a dataset to specify a mask of voxelsto EXCLUDE from the analysis – all voxels in ‘ee’that are NONZERO will not be used in the alignment.The base image always automasked – the emask isextra, to indicate voxels you definitely DON’T wantincluded in the matching process, even if they areinside the brain. Maps to a command-line argument: -emask %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: {})

  • expad (an integer) – This option instructs the program to pad the warp by an extra’EE’ voxels (and then 3dQwarp starts optimizing it).This option is seldom needed, but can be useful if youmight later catenate the nonlinear warp – via 3dNwarpCat –with an affine transformation that contains a large shift.Under that circumstance, the nonlinear warp might be shiftedpartially outside its original grid, so expanding that gridcan avoid this problem.Note that this option perforce turns off ‘-nopadWARP’. Maps to a command-line argument: -expad %d. Mutually exclusive with inputs: nopadWARP.

  • gridlist (a pathlike object or string representing an existing file) – This option provides an alternate way to specify the patch grid sizes used in the warp optimization process. ‘gl’ is a 1D file with a list of patches to use – in most cases, you will want to use it in the following form: -gridlist '1D: 0 151 101 75 51'

    • Here, a 0 patch size means the global domain. Patch sizes otherwise should be odd integers >= 5.

    • If you use the ‘0’ patch size again after the first position, you will actually get an iteration at the size of the default patch level 1, where the patch sizes are 75% of the volume dimension. There is no way to force the program to literally repeat the sui generis step of lev=0.

    Maps to a command-line argument: -gridlist %s. Mutually exclusive with inputs: duplo, plusminus.

  • hel (a boolean) – Hellinger distance: a matching function for the adventurousThis option has NOT be extensively tested for usefulnessand should be considered experimental at this infundibulum. Maps to a command-line argument: -hel. Mutually exclusive with inputs: nmi, mi, lpc, lpa, pear.

  • inilev (an integer) – The initial refinement ‘level’ at which to start.

    • Usually used with -iniwarp; CANNOT be used with -duplo.

    • The combination of -inilev and -iniwarp lets you take the results of a previous 3dQwarp run and refine them further: Note that the source dataset in the second run is the SAME as in the first run. If you don’t see why this is necessary, then you probably need to seek help from an AFNI guru.

    Maps to a command-line argument: -inilev %d. Mutually exclusive with inputs: duplo.

  • iniwarp (a list of items which are a pathlike object or string representing an existing file) – A dataset with an initial nonlinear warp to use.

    • If this option is not used, the initial warp is the identity.

    • You can specify a catenation of warps (in quotes) here, as in program 3dNwarpApply.

    • As a special case, if you just input an affine matrix in a .1D file, that will work also – it is treated as giving the initial warp via the string “IDENT(base_dataset) matrix_file.aff12.1D”.

    • You CANNOT use this option with -duplo !!

    • -iniwarp is usually used with -inilev to re-start 3dQwarp from a previous stopping point.

    Maps to a command-line argument: -iniwarp %s. Mutually exclusive with inputs: duplo.

  • iwarp (a boolean) – Do compute and save the _WARPINV file. Maps to a command-line argument: -iwarp. Mutually exclusive with inputs: plusminus.

  • lpa (a boolean) – Local Pearson maximization. This option has not be extensively tested. Maps to a command-line argument: -lpa. Mutually exclusive with inputs: nmi, mi, lpc, hel, pear.

  • lpc (a boolean) – Local Pearson minimization (i.e., EPI-T1 registration)This option has not be extensively testedIf you use ‘-lpc’, then ‘-maxlev 0’ is automatically set.If you want to go to more refined levels, you can set ‘-maxlev’This should be set up to have lpc as the second to last argumentand maxlev as the second to last argument, as needed by AFNIUsing maxlev > 1 is not recommended for EPI-T1 alignment. Maps to a command-line argument: -lpc (position: -2). Mutually exclusive with inputs: nmi, mi, hel, lpa, pear.

  • maxlev (an integer) – The initial refinement ‘level’ at which to start.

    • Usually used with -iniwarp; CANNOT be used with -duplo.

    • The combination of -inilev and -iniwarp lets you take the results of a previous 3dQwarp run and refine them further: Note that the source dataset in the second run is the SAME as in the first run. If you don’t see why this is necessary, then you probably need to seek help from an AFNI guru.

    Maps to a command-line argument: -maxlev %d (position: -1). Mutually exclusive with inputs: duplo.

  • mi (a boolean) – Mutual Information: a matching function for the adventurousThis option has NOT be extensively tested for usefulnessand should be considered experimental at this infundibulum. Maps to a command-line argument: -mi. Mutually exclusive with inputs: mi, hel, lpc, lpa, pear.

  • minpatch (an integer) – The value of mm should be an odd integer.

    • The default value of mm is 25.

    • For more accurate results than mm=25, try 19 or 13.

    • The smallest allowed patch size is 5.

    • You may want stop at a larger patch size (say 7 or 9) and use the -Qfinal option to run that final level with quintic warps, which might run faster and provide the same degree of warp detail.

    • Trying to make two different brain volumes match in fine detail is usually a waste of time, especially in humans. There is too much variability in anatomy to match gyrus to gyrus accurately. For this reason, the default minimum patch size is 25 voxels. Using a smaller ‘-minpatch’ might try to force the warp to match features that do not match, and the result can be useless image distortions – another reason to LOOK AT THE RESULTS.

    Maps to a command-line argument: -minpatch %d.

  • nmi (a boolean) – Normalized Mutual Information: a matching function for the adventurousThis option has NOT been extensively tested for usefulnessand should be considered experimental at this infundibulum. Maps to a command-line argument: -nmi. Mutually exclusive with inputs: nmi, hel, lpc, lpa, pear.

  • noXdis (a boolean) – Warp will not displace in x direction. Maps to a command-line argument: -noXdis.

  • noYdis (a boolean) – Warp will not displace in y direction. Maps to a command-line argument: -noYdis.

  • noZdis (a boolean) – Warp will not displace in z direction. Maps to a command-line argument: -noZdis.

  • noneg (a boolean) – Replace negative values in either input volume with 0.

    • If there ARE negative input values, and you do NOT use -noneg, then strict Pearson correlation will be used, since the ‘clipped’ method only is implemented for non-negative volumes.

    • ‘-noneg’ is not the default, since there might be situations where you want to align datasets with positive and negative values mixed.

    • But, in many cases, the negative values in a dataset are just the result of interpolation artifacts (or other peculiarities), and so they should be ignored. That is what ‘-noneg’ is for.

    Maps to a command-line argument: -noneg.

  • nopad (a boolean) – Do NOT use zero-padding on the 3D base and source images. [Default == zero-pad, if needed]

    • The underlying model for deformations goes to zero at the edge of the volume being warped. However, if there is significant data near an edge of the volume, then it won’t get displaced much, and so the results might not be good.

    • Zero padding is designed as a way to work around this potential problem. You should NOT need the ‘-nopad’ option for any reason that Zhark can think of, but it is here to be symmetrical with 3dAllineate.

    • Note that the output (warped from source) dataset will be on the base dataset grid whether or not zero-padding is allowed. However, unless you use the following option, allowing zero-padding (i.e., the default operation) will make the output WARP dataset(s) be on a larger grid (also see ‘-expad’ below).

    Maps to a command-line argument: -nopad.

  • nopadWARP (a boolean) – If for some reason you require the warp volume tomatch the base volume, then use this option to have the outputWARP dataset(s) truncated. Maps to a command-line argument: -nopadWARP. Mutually exclusive with inputs: allsave, expad.

  • nopenalty (a boolean) – Replace negative values in either input volume with 0.

    • If there ARE negative input values, and you do NOT use -noneg, then strict Pearson correlation will be used, since the ‘clipped’ method only is implemented for non-negative volumes.

    • ‘-noneg’ is not the default, since there might be situations where you want to align datasets with positive and negative values mixed.

    • But, in many cases, the negative values in a dataset are just the result of interpolation artifacts (or other peculiarities), and so they should be ignored. That is what ‘-noneg’ is for.

    Maps to a command-line argument: -nopenalty.

  • nowarp (a boolean) – Do not save the _WARP file. Maps to a command-line argument: -nowarp.

  • noweight (a boolean) – If you want a binary weight (the old default), use this option.That is, each voxel in the base volume automask will beweighted the same in the computation of the cost functional. Maps to a command-line argument: -noweight.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output file. Maps to a command-line argument: -prefix %s (position: 0). (Nipype default value: Qwarp.nii.gz)

  • out_weight_file (a pathlike object or string representing a file) – Write the weight volume to disk as a dataset. Maps to a command-line argument: -wtprefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • overwrite (a boolean) – Overwrite outputs. Maps to a command-line argument: -overwrite.

  • pblur (a list of from 1 to 2 items which are a float) – Use progressive blurring; that is, for larger patch sizes, the amount of blurring is larger. The general idea is to avoid trying to match finer details when the patch size and incremental warps are coarse. When ‘-blur’ is used as well, it sets a minimum amount of blurring that will be used. [06 Aug 2014 – ‘-pblur’ may become the default someday].

    • You can optionally give the fraction of the patch size that is used for the progressive blur by providing a value between 0 and 0.25 after ‘-pblur’. If you provide TWO values, the the first fraction is used for progressively blurring the base image and the second for the source image. The default parameters when just ‘-pblur’ is given is the same as giving the options as ‘-pblur 0.09 0.09’.

    • ‘-pblur’ is useful when trying to match 2 volumes with high amounts of detail; e.g, warping one subject’s brain image to match another’s, or trying to warp to match a detailed template.

    • Note that using negative values with ‘-blur’ means that the progressive blurring will be done with median filters, rather than Gaussian linear blurring.

    Note: The combination of the -allineate and -pblur options will make the results of using 3dQwarp to align to a template somewhat less sensitive to initial head position and scaling. Maps to a command-line argument: -pblur %s.

  • pear (a boolean) – Use strict Pearson correlation for matching.Not usually recommended, since the ‘clipped Pearson’ methodused by default will reduce the impact of outlier values. Maps to a command-line argument: -pear.

  • penfac (a float) – Use this value to weight the penalty. The default value is 1. Larger values mean the penalty counts more, reducing grid distortions, insha’Allah; ‘-nopenalty’ is the same as ‘-penfac 0’. In 23 Sep 2013 Zhark increased the default value of the penalty by a factor of 5, and also made it get progressively larger with each level of refinement. Thus, warping results will vary from earlier instances of 3dQwarp.

    • The progressive increase in the penalty at higher levels means that the ‘cost function’ can actually look like the alignment is getting worse when the levels change.

    • IF you wish to turn off this progression, for whatever reason (e.g., to keep compatibility with older results), use the option ‘-penold’.To be completely compatible with the older 3dQwarp, you’ll also have to use ‘-penfac 0.2’.

    Maps to a command-line argument: -penfac %f.

  • plusminus (a boolean) – Normally, the warp displacements dis(x) are defined to matchbase(x) to source(x+dis(x)). With this option, the matchis between base(x-dis(x)) and source(x+dis(x)) – the twoimages ‘meet in the middle’. For more info, view Qwarp` interface. Maps to a command-line argument: -plusminus (position: 1). Mutually exclusive with inputs: duplo, allsave, iwarp. (Nipype default value: True)

  • quiet (a boolean) – Cut out most of the fun fun fun progress messages :-(. Maps to a command-line argument: -quiet. Mutually exclusive with inputs: verb.

  • resample (a boolean) – This option simply resamples the source dataset to match the base dataset grid. You can use this if the two datasets overlap well (as seen in the AFNI GUI), but are not on the same 3D grid.

    • If they don’t overlap well, allineate them first

    • The reampling here is done with the ‘wsinc5’ method, which has very little blurring artifact.

    • If the base and source datasets ARE on the same 3D grid, then the -resample option will be ignored.

    • You CAN use -resample with these 3dQwarp options: -plusminus -inilev -iniwarp -duplo

    Maps to a command-line argument: -resample.

  • source_file (a pathlike object or string representing an existing file) – Source image (opposite phase encoding direction than base image). Maps to a command-line argument: -source %s.

  • verb (a boolean) – More detailed description of the process. Maps to a command-line argument: -verb. Mutually exclusive with inputs: quiet.

  • wball (a list of from 5 to 5 items which are an integer) – “-wball x y z r f Enhance automatic weight from ‘-useweight’ by a factor of 1+f*Gaussian(FWHM=r) centered in the base image at DICOM coordinates (x,y,z) and with radius ‘r’. The goal of this option is to try and make the alignment better in a specific part of the brain. Example: -wball 0 14 6 30 40 to emphasize the thalamic area (in MNI/Talairach space).

    • The ‘r’ parameter must be positive!

    • The ‘f’ parameter must be between 1 and 100 (inclusive).

    • ‘-wball’ does nothing if you input your own weight with the ‘-weight’ option.

    • ‘-wball’ does change the binary weight created by the ‘-noweight’ option.

    • You can only use ‘-wball’ once in a run of 3dQwarp.

    The effect of ‘-wball’ is not dramatic. The example above makes the average brain image across a collection of subjects a little sharper in the thalamic area, which might have some small value. If you care enough about alignment to use ‘-wball’, then you should examine the results from 3dQwarp for each subject, to see if the alignments are good enough for your purposes. Maps to a command-line argument: -wball %s. Mutually exclusive with inputs: wmask.

  • weight (a pathlike object or string representing an existing file) – Instead of computing the weight from the base dataset,directly input the weight volume from dataset ‘www’.Useful if you know what over parts of the base image youwant to emphasize or de-emphasize the matching functional. Maps to a command-line argument: -weight %s.

  • wmask (a tuple of the form: (a pathlike object or string representing an existing file, a float)) – Similar to ‘-wball’, but here, you provide a dataset ‘ws’ that indicates where to increase the weight.

    • The ‘ws’ dataset must be on the same 3D grid as the base dataset.

    • ‘ws’ is treated as a mask – it only matters where it is nonzero – otherwise, the values inside are not used.

    • After ‘ws’ comes the factor ‘f’ by which to increase the automatically computed weight. Where ‘ws’ is nonzero, the weighting will be multiplied by (1+f).

    • As with ‘-wball’, the factor ‘f’ should be between 1 and 100.

    Maps to a command-line argument: -wpass %s %f. Mutually exclusive with inputs: wball.

  • workhard (a boolean) – Iterate more times, which can help when the volumes are hard to align at all, or when you hope to get a more precise alignment.

    • Slows the program down (possibly a lot), of course.

    • When you combine ‘-workhard’ with ‘-duplo’, only the full size volumes get the extra iterations.

    • For finer control over which refinement levels work hard, you can use this option in the form (for example) -workhard:4:7 which implies the extra iterations will be done at levels 4, 5, 6, and 7, but not otherwise.

    • You can also use ‘-superhard’ to iterate even more, but this extra option will REALLY slow things down.

      • Under most circumstances, you should not need to use either -workhard or -superhard.

      • The fastest way to register to a template image is via the -duplo option, and without the -workhard or -superhard options.

      • If you use this option in the form ‘-Workhard’ (first letter in upper case), then the second iteration at each level is done with quintic polynomial warps.

    Maps to a command-line argument: -workhard. Mutually exclusive with inputs: boxopt, ballopt.

Outputs:

  • base_warp (a pathlike object or string representing a file) – Displacement in mm for the base image.If plus minus is used, this is the field suceptibility correctionwarp (in ‘mm’) for base image. This is only output if plusminusor iwarp options are passed.

  • source_warp (a pathlike object or string representing a file) – Displacement in mm for the source image.If plusminus is used this is the field suceptibility correctionwarp (in ‘mm’) for source image.

  • warped_base (a pathlike object or string representing a file) – Undistorted base file.

  • warped_source (a pathlike object or string representing a file) – Warped source file. If plusminus is used, this is the undistortedsource file.

  • weights (a pathlike object or string representing a file) – Auto-computed weight volume.

ROIStats

Link to code

Bases: AFNICommandBase

Wrapped executable: 3dROIstats.

Display statistics over masked regions

For complete details, see the 3dROIstats Documentation

Examples

>>> from nipype.interfaces import afni
>>> roistats = afni.ROIStats()
>>> roistats.inputs.in_file = 'functional.nii'
>>> roistats.inputs.mask_file = 'skeleton_mask.nii.gz'
>>> roistats.inputs.stat = ['mean', 'median', 'voxels']
>>> roistats.inputs.nomeanout = True
>>> roistats.cmdline
'3dROIstats -mask skeleton_mask.nii.gz -nomeanout -nzmean -nzmedian -nzvoxels functional.nii > functional_roistat.1D'
>>> res = roistats.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input dataset. Maps to a command-line argument: %s (position: -2).

Optional Inputs:

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

  • debug (a boolean) – Print debug information. Maps to a command-line argument: -debug.

  • 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: {})

  • format1D (a boolean) – Output results in a 1D format that includes commented labels. Maps to a command-line argument: -1Dformat. Mutually exclusive with inputs: format1DR.

  • format1DR (a boolean) – Output results in a 1D format that includes uncommented labels. May not work optimally with typical 1D functions, but is useful for R functions. Maps to a command-line argument: -1DRformat. Mutually exclusive with inputs: format1D.

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

  • mask_f2short (a boolean) – Tells the program to convert a float mask to short integers, by simple rounding. Maps to a command-line argument: -mask_f2short.

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

  • nobriklab (a boolean) – Do not print the sub-brick label next to its index. Maps to a command-line argument: -nobriklab.

  • nomeanout (a boolean) – Do not include the (zero-inclusive) mean among computed stats. Maps to a command-line argument: -nomeanout.

  • num_roi (an integer) – Forces the assumption that the mask dataset’s ROIs are denoted by 1 to n inclusive. Normally, the program figures out the ROIs on its own. This option is useful if a) you are certain that the mask dataset has no values outside the range [0 n], b) there may be some ROIs missing between [1 n] in the mask data-set and c) you want those columns in the output any-way so the output lines up with the output from other invocations of 3dROIstats. Maps to a command-line argument: -numroi %s.

  • out_file (a pathlike object or string representing a file) – Output file. Maps to a command-line argument: > %s (position: -1).

  • quiet (a boolean) – Execute quietly. Maps to a command-line argument: -quiet.

  • roisel (a pathlike object or string representing an existing file) – Only considers ROIs denoted by values found in the specified file. Note that the order of the ROIs as specified in the file is not preserved. So an SEL.1D of ‘2 8 20’ produces the same output as ‘8 20 2’. Maps to a command-line argument: -roisel %s.

  • stat (a list of items which are ‘mean’ or ‘sum’ or ‘voxels’ or ‘minmax’ or ‘sigma’ or ‘median’ or ‘mode’ or ‘summary’ or ‘zerominmax’ or ‘zerosigma’ or ‘zeromedian’ or ‘zeromode’) –

    Statistics to compute. Options include:

    • mean = Compute the mean using only non_zero voxels.

      Implies the opposite for the mean computed by default.

    • median = Compute the median of nonzero voxels

    • mode = Compute the mode of nonzero voxels.

      (integral valued sets only)

    • minmax = Compute the min/max of nonzero voxels

    • sum = Compute the sum using only nonzero voxels.

    • voxels = Compute the number of nonzero voxels

    • sigma = Compute the standard deviation of nonzero

      voxels

    Statistics that include zero-valued voxels:

    • zerominmax = Compute the min/max of all voxels.

    • zerosigma = Compute the standard deviation of all

      voxels.

    • zeromedian = Compute the median of all voxels.

    • zeromode = Compute the mode of all voxels.

    • summary = Only output a summary line with the grand

      mean across all briks in the input dataset. This option cannot be used with nomeanout.

    More that one option can be specified. Maps to a command-line argument: %s....

  • zerofill (a string) – For ROI labels not found, use the provided string instead of a ‘0’ in the output file. Only active if num_roi is enabled. Maps to a command-line argument: -zerofill %s. Requires inputs: num_roi.

Outputs:

out_file (a pathlike object or string representing an existing file) – Output tab-separated values file.

Retroicor

Link to code

Bases: AFNICommand

Wrapped executable: 3dretroicor.

Performs Retrospective Image Correction for physiological motion effects, using a slightly modified version of the RETROICOR algorithm

The durations of the physiological inputs are assumed to equal the duration of the dataset. Any constant sampling rate may be used, but 40 Hz seems to be acceptable. This program’s cardiac peak detection algorithm is rather simplistic, so you might try using the scanner’s cardiac gating output (transform it to a spike wave if necessary).

This program uses slice timing information embedded in the dataset to estimate the proper cardiac/respiratory phase for each slice. It makes sense to run this program before any program that may destroy the slice timings (e.g. 3dvolreg for motion correction).

For complete details, see the 3dretroicor Documentation.

Examples

>>> from nipype.interfaces import afni
>>> ret = afni.Retroicor()
>>> ret.inputs.in_file = 'functional.nii'
>>> ret.inputs.card = 'mask.1D'
>>> ret.inputs.resp = 'resp.1D'
>>> ret.inputs.outputtype = 'NIFTI'
>>> ret.cmdline
'3dretroicor -prefix functional_retroicor.nii -resp resp.1D -card mask.1D functional.nii'
>>> res = ret.run()
Mandatory Inputs:

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

Optional Inputs:

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

  • card (a pathlike object or string representing an existing file) – 1D cardiac data file for cardiac correction. Maps to a command-line argument: -card %s (position: -2).

  • cardphase (a pathlike object or string representing a file) – Filename for 1D cardiac phase output. Maps to a command-line argument: -cardphase %s (position: -6).

  • 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: {})

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • order (an integer) – The order of the correction (2 is typical). Maps to a command-line argument: -order %s (position: -5).

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s (position: 1).

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • resp (a pathlike object or string representing an existing file) – 1D respiratory waveform data for correction. Maps to a command-line argument: -resp %s (position: -3).

  • respphase (a pathlike object or string representing a file) – Filename for 1D resp phase output. Maps to a command-line argument: -respphase %s (position: -7).

  • threshold (an integer) – Threshold for detection of R-wave peaks in input (Make sure it is above the background noise level, Try 3/4 or 4/5 times range plus minimum). Maps to a command-line argument: -threshold %d (position: -4).

Outputs:

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

Seg

Link to code

Bases: AFNICommandBase

Wrapped executable: 3dSeg.

3dSeg segments brain volumes into tissue classes. The program allows for adding a variety of global and voxelwise priors. However for the moment, only mixing fractions and MRF are documented.

For complete details, see the 3dSeg Documentation.

Examples

>>> from nipype.interfaces.afni import preprocess
>>> seg = preprocess.Seg()
>>> seg.inputs.in_file = 'structural.nii'
>>> seg.inputs.mask = 'AUTO'
>>> seg.cmdline
'3dSeg -mask AUTO -anat structural.nii'
>>> res = seg.run()
Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – ANAT is the volume to segment. Maps to a command-line argument: -anat %s (position: -1).

  • mask (‘AUTO’ or a pathlike object or string representing an existing file) – Only non-zero voxels in mask are analyzed. mask can either be a dataset or the string “AUTO” which would use AFNI’s automask function to create the mask. Maps to a command-line argument: -mask %s (position: -2).

Optional Inputs:

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

  • bias_classes (a string) – A semicolon delimited string of classes that contribute to the estimation of the bias field. Maps to a command-line argument: -bias_classes %s.

  • bias_fwhm (a float) – The amount of blurring used when estimating the field bias with the Wells method. Maps to a command-line argument: -bias_fwhm %f.

  • blur_meth (‘BFT’ or ‘BIM’) – Set the blurring method for bias field estimation. Maps to a command-line argument: -blur_meth %s.

  • bmrf (a float) – Weighting factor controlling spatial homogeneity of the classifications. Maps to a command-line argument: -bmrf %f.

  • classes (a string) – CLASS_STRING is a semicolon delimited string of class labels. Maps to a command-line argument: -classes %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: {})

  • main_N (an integer) – Number of iterations to perform. Maps to a command-line argument: -main_N %d.

  • mixfloor (a float) – Set the minimum value for any class’s mixing fraction. Maps to a command-line argument: -mixfloor %f.

  • mixfrac (a string) – MIXFRAC sets up the volume-wide (within mask) tissue fractions while initializing the segmentation (see IGNORE for exception). Maps to a command-line argument: -mixfrac %s.

  • prefix (a string) – The prefix for the output folder containing all output volumes. Maps to a command-line argument: -prefix %s.

Outputs:

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

Seg.aggregate_outputs(runtime=None, needed_outputs=None)

Collate expected outputs and apply output traits validation.

SkullStrip

Link to code

Bases: AFNICommand

Wrapped executable: 3dSkullStrip.

A program to extract the brain from surrounding tissue from MRI T1-weighted images. TODO Add optional arguments.

For complete details, see the 3dSkullStrip Documentation.

Examples

>>> from nipype.interfaces import afni
>>> skullstrip = afni.SkullStrip()
>>> skullstrip.inputs.in_file = 'functional.nii'
>>> skullstrip.inputs.args = '-o_ply'
>>> skullstrip.cmdline
'3dSkullStrip -input functional.nii -o_ply -prefix functional_skullstrip'
>>> res = skullstrip.run()
Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input file to 3dSkullStrip. Maps to a command-line argument: -input %s (position: 1).

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: {})

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

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

TCorr1D

Link to code

Bases: AFNICommand

Wrapped executable: 3dTcorr1D.

Computes the correlation coefficient between each voxel time series in the input 3D+time dataset.

For complete details, see the 3dTcorr1D Documentation.

>>> from nipype.interfaces import afni
>>> tcorr1D = afni.TCorr1D()
>>> tcorr1D.inputs.xset= 'u_rc1s1_Template.nii'
>>> tcorr1D.inputs.y_1d = 'seed.1D'
>>> tcorr1D.cmdline
'3dTcorr1D -prefix u_rc1s1_Template_correlation.nii.gz  u_rc1s1_Template.nii  seed.1D'
>>> res = tcorr1D.run()
Mandatory Inputs:

  • xset (a pathlike object or string representing an existing file) – 3d+time dataset input. Maps to a command-line argument: %s (position: -2).

  • y_1d (a pathlike object or string representing an existing file) – 1D time series file input. Maps to a command-line argument: %s (position: -1).

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: {})

  • ktaub (a boolean) – Correlation is the Kendall’s tau_b correlation coefficient. Maps to a command-line argument: -ktaub (position: 1). Mutually exclusive with inputs: pearson, spearman, quadrant.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output filename prefix. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • pearson (a boolean) – Correlation is the normal Pearson correlation coefficient. Maps to a command-line argument: -pearson (position: 1). Mutually exclusive with inputs: spearman, quadrant, ktaub.

  • quadrant (a boolean) – Correlation is the quadrant correlation coefficient. Maps to a command-line argument: -quadrant (position: 1). Mutually exclusive with inputs: pearson, spearman, ktaub.

  • spearman (a boolean) – Correlation is the Spearman (rank) correlation coefficient. Maps to a command-line argument: -spearman (position: 1). Mutually exclusive with inputs: pearson, quadrant, ktaub.

Outputs:

out_file (a pathlike object or string representing an existing file) – Output file containing correlations.

TCorrMap

Link to code

Bases: AFNICommand

Wrapped executable: 3dTcorrMap.

For each voxel time series, computes the correlation between it and all other voxels, and combines this set of values into the output dataset(s) in some way.

For complete details, see the 3dTcorrMap Documentation.

Examples

>>> from nipype.interfaces import afni
>>> tcm = afni.TCorrMap()
>>> tcm.inputs.in_file = 'functional.nii'
>>> tcm.inputs.mask = 'mask.nii'
>>> tcm.mean_file = 'functional_meancorr.nii'
>>> tcm.cmdline 
'3dTcorrMap -input functional.nii -mask mask.nii -Mean functional_meancorr.nii'
>>> res = tcm.run()
Mandatory Inputs:

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

Optional Inputs:

  • absolute_threshold (a pathlike object or string representing a file) – Maps to a command-line argument: -Thresh %f %s. Mutually exclusive with inputs: absolute_threshold, var_absolute_threshold, var_absolute_threshold_normalize.

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

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

  • average_expr (a pathlike object or string representing a file) – Maps to a command-line argument: -Aexpr %s %s. Mutually exclusive with inputs: average_expr, average_expr_nonzero, sum_expr.

  • average_expr_nonzero (a pathlike object or string representing a file) – Maps to a command-line argument: -Cexpr %s %s. Mutually exclusive with inputs: average_expr, average_expr_nonzero, sum_expr.

  • bandpass (a tuple of the form: (a float, a float)) – Maps to a command-line argument: -bpass %f %f.

  • blur_fwhm (a float) – Maps to a command-line argument: -Gblur %f.

  • correlation_maps (a pathlike object or string representing a file) – Maps to a command-line argument: -CorrMap %s.

  • correlation_maps_masked (a pathlike object or string representing a file) – Maps to a command-line argument: -CorrMask %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: {})

  • expr (a string)

  • histogram (a pathlike object or string representing a file) – Maps to a command-line argument: -Hist %d %s.

  • histogram_bin_numbers (an integer)

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

  • mean_file (a pathlike object or string representing a file) – Maps to a command-line argument: -Mean %s.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • pmean (a pathlike object or string representing a file) – Maps to a command-line argument: -Pmean %s.

  • polort (an integer) – Maps to a command-line argument: -polort %d.

  • qmean (a pathlike object or string representing a file) – Maps to a command-line argument: -Qmean %s.

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

  • seeds (a pathlike object or string representing an existing file) – Maps to a command-line argument: -seed %s. Mutually exclusive with inputs: s, e, e, d, s, _, w, i, d, t, h.

  • seeds_width (a float) – Maps to a command-line argument: -Mseed %f. Mutually exclusive with inputs: s, e, e, d, s.

  • sum_expr (a pathlike object or string representing a file) – Maps to a command-line argument: -Sexpr %s %s. Mutually exclusive with inputs: average_expr, average_expr_nonzero, sum_expr.

  • thresholds (a list of items which are an integer)

  • var_absolute_threshold (a pathlike object or string representing a file) – Maps to a command-line argument: -VarThresh %f %f %f %s. Mutually exclusive with inputs: absolute_threshold, var_absolute_threshold, var_absolute_threshold_normalize.

  • var_absolute_threshold_normalize (a pathlike object or string representing a file) – Maps to a command-line argument: -VarThreshN %f %f %f %s. Mutually exclusive with inputs: absolute_threshold, var_absolute_threshold, var_absolute_threshold_normalize.

  • zmean (a pathlike object or string representing a file) – Maps to a command-line argument: -Zmean %s.

Outputs:

  • absolute_threshold (a pathlike object or string representing a file)

  • average_expr (a pathlike object or string representing a file)

  • average_expr_nonzero (a pathlike object or string representing a file)

  • correlation_maps (a pathlike object or string representing a file)

  • correlation_maps_masked (a pathlike object or string representing a file)

  • histogram (a pathlike object or string representing a file)

  • mean_file (a pathlike object or string representing a file)

  • pmean (a pathlike object or string representing a file)

  • qmean (a pathlike object or string representing a file)

  • sum_expr (a pathlike object or string representing a file)

  • var_absolute_threshold (a pathlike object or string representing a file)

  • var_absolute_threshold_normalize (a pathlike object or string representing a file)

  • zmean (a pathlike object or string representing a file)

TCorrelate

Link to code

Bases: AFNICommand

Wrapped executable: 3dTcorrelate.

Computes the correlation coefficient between corresponding voxel time series in two input 3D+time datasets ‘xset’ and ‘yset’

For complete details, see the 3dTcorrelate Documentation.

Examples

>>> from nipype.interfaces import afni
>>> tcorrelate = afni.TCorrelate()
>>> tcorrelate.inputs.xset= 'u_rc1s1_Template.nii'
>>> tcorrelate.inputs.yset = 'u_rc1s2_Template.nii'
>>> tcorrelate.inputs.out_file = 'functional_tcorrelate.nii.gz'
>>> tcorrelate.inputs.polort = -1
>>> tcorrelate.inputs.pearson = True
>>> tcorrelate.cmdline
'3dTcorrelate -prefix functional_tcorrelate.nii.gz -pearson -polort -1 u_rc1s1_Template.nii u_rc1s2_Template.nii'
>>> res = tcarrelate.run()
Mandatory Inputs:

  • xset (a pathlike object or string representing an existing file) – Input xset. Maps to a command-line argument: %s (position: -2).

  • yset (a pathlike object or string representing an existing file) – Input yset. Maps to a command-line argument: %s (position: -1).

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: {})

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • pearson (a boolean) – Correlation is the normal Pearson correlation coefficient. Maps to a command-line argument: -pearson.

  • polort (an integer) – Remove polynomial trend of order m. Maps to a command-line argument: -polort %d.

Outputs:

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

TNorm

Link to code

Bases: AFNICommand

Wrapped executable: 3dTnorm.

Shifts voxel time series from input so that separate slices are aligned to the same temporal origin.

For complete details, see the 3dTnorm Documentation.

Examples

>>> from nipype.interfaces import afni
>>> tnorm = afni.TNorm()
>>> tnorm.inputs.in_file = 'functional.nii'
>>> tnorm.inputs.norm2 = True
>>> tnorm.inputs.out_file = 'rm.errts.unit errts+tlrc'
>>> tnorm.cmdline
'3dTnorm -norm2 -prefix rm.errts.unit errts+tlrc functional.nii'
>>> res = tshift.run()
Mandatory Inputs:

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

Optional Inputs:

  • L1fit (a boolean) – Detrend with L1 regression (L2 is the default) This option is here just for the hell of it. Maps to a command-line argument: -L1fit.

  • 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: {})

  • norm1 (a boolean) – L1 normalize (sum of absolute values = 1). Maps to a command-line argument: -norm1.

  • norm2 (a boolean) – L2 normalize (sum of squares = 1) [DEFAULT]. Maps to a command-line argument: -norm2.

  • normR (a boolean) – Normalize so sum of squares = number of time points * e.g., so RMS = 1. Maps to a command-line argument: -normR.

  • normx (a boolean) – Scale so max absolute value = 1 (L_infinity norm). Maps to a command-line argument: -normx.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • polort (an integer) – Detrend with polynomials of order p before normalizing [DEFAULT = don’t do this]. Use ‘-polort 0’ to remove the mean, for example. Maps to a command-line argument: -polort %s.

Outputs:

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

TProject

Link to code

Bases: AFNICommand

Wrapped executable: 3dTproject.

This program projects (detrends) out various ‘nuisance’ time series from each voxel in the input dataset. Note that all the projections are done via linear regression, including the frequency-based options such as -passband. In this way, you can bandpass time-censored data, and at the same time, remove other time series of no interest (e.g., physiological estimates, motion parameters). Shifts voxel time series from input so that separate slices are aligned to the same temporal origin.

Examples

>>> from nipype.interfaces import afni
>>> tproject = afni.TProject()
>>> tproject.inputs.in_file = 'functional.nii'
>>> tproject.inputs.bandpass = (0.00667, 99999)
>>> tproject.inputs.polort = 3
>>> tproject.inputs.automask = True
>>> tproject.inputs.out_file = 'projected.nii.gz'
>>> tproject.cmdline
'3dTproject -input functional.nii -automask -bandpass 0.00667 99999 -polort 3 -prefix projected.nii.gz'
>>> res = tproject.run()

See also

For complete details, see the 3dTproject Documentation.

Mandatory Inputs:

in_file (a pathlike object or string representing an existing file) – Input file to 3dTproject. Maps to a command-line argument: -input %s (position: 1).

Optional Inputs:

  • TR (a float) – Use time step dd for the frequency calculations, rather than the value stored in the dataset header. Maps to a command-line argument: -TR %g.

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

  • automask (a boolean) – Generate a mask automatically. Maps to a command-line argument: -automask. Mutually exclusive with inputs: mask.

  • bandpass (a tuple of the form: (a float, a float)) – Remove all frequencies EXCEPT those in the range. Maps to a command-line argument: -bandpass %g %g.

  • blur (a float) – Blur (inside the mask only) with a filter that has width (FWHM) of fff millimeters. Spatial blurring (if done) is after the time series filtering. Maps to a command-line argument: -blur %g.

  • cenmode (‘KILL’ or ‘ZERO’ or ‘NTRP’) – Specifies how censored time points are treated in the output dataset:

    • mode = ZERO – put zero values in their place; output dataset is same length as input

    • mode = KILL – remove those time points; output dataset is shorter than input

    • mode = NTRP – censored values are replaced by interpolated neighboring (in time) non-censored values, BEFORE any projections, and then the analysis proceeds without actual removal of any time points – this feature is to keep the Spanish Inquisition happy.

    • The default mode is KILL !!!

    Maps to a command-line argument: -cenmode %s.

  • censor (a pathlike object or string representing an existing file) – Filename of censor .1D time series. This is a file of 1s and 0s, indicating which time points are to be included (1) and which are to be excluded (0). Maps to a command-line argument: -censor %s.

  • censortr (a list of items which are a string) – List of strings that specify time indexes to be removed from the analysis. Each string is of one of the following forms:

    • 37 => remove global time index #37

    • 2:37 => remove time index #37 in run #2

    • 37..47 => remove global time indexes #37-47

    • 37-47 => same as above

    • 2:37..47 => remove time indexes #37-47 in run #2

    • *:0-2 => remove time indexes #0-2 in all runs

      • Time indexes within each run start at 0.

      • Run indexes start at 1 (just be to confusing).

      • N.B.: 2:37,47 means index #37 in run #2 and global time index 47; it does NOT mean index #37 in run #2 AND index #47 in run #2.

    Maps to a command-line argument: -CENSORTR %s.

  • concat (a pathlike object or string representing an existing file) – The catenation file, as in 3dDeconvolve, containing the TR indexes of the start points for each contiguous run within the input dataset (the first entry should be 0).

    • Also as in 3dDeconvolve, if the input dataset is automatically catenated from a collection of datasets, then the run start indexes are determined directly, and ‘-concat’ is not needed (and will be ignored).

    • Each run must have at least 9 time points AFTER censoring, or the program will not work!

    • The only use made of this input is in setting up the bandpass/stopband regressors.

    • ‘-ort’ and ‘-dsort’ regressors run through all time points, as read in. If you want separate projections in each run, then you must either break these ort files into appropriate components, OR you must run 3dTproject for each run separately, using the appropriate pieces from the ort files via the {...} selector for the 1D files and the [...] selector for the datasets.

    Maps to a command-line argument: -concat %s.

  • dsort (a list of items which are a pathlike object or string representing an existing file) – Remove the 3D+time time series in dataset fset.

    • That is, ‘fset’ contains a different nuisance time series for each voxel (e.g., from AnatICOR).

    • Multiple -dsort options are allowed.

    Maps to a command-line argument: -dsort %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: {})

  • mask (a pathlike object or string representing an existing file) – Only operate on voxels nonzero in the mset dataset.

    • Voxels outside the mask will be filled with zeros.

    • If no masking option is given, then all voxels will be processed.

    Maps to a command-line argument: -mask %s.

  • noblock (a boolean) – Also as in 3dDeconvolve, if you want the program to treat an auto-catenated dataset as one long run, use this option. However, ‘-noblock’ will not affect catenation if you use the ‘-concat’ option. Maps to a command-line argument: -noblock.

  • norm (a boolean) – Normalize each output time series to have sum of squares = 1. This is the LAST operation. Maps to a command-line argument: -norm.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • ort (a pathlike object or string representing an existing file) – Remove each column in file. Each column will have its mean removed. Maps to a command-line argument: -ort %s.

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s (position: -1).

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • polort (an integer) – Remove polynomials up to and including degree pp.

    • Default value is 2.

    • It makes no sense to use a value of pp greater than 2, if you are bandpassing out the lower frequencies!

    • For catenated datasets, each run gets a separate set set of pp+1 Legendre polynomial regressors.

    • Use of -polort -1 is not advised (if data mean != 0), even if -ort contains constant terms, as all means are removed.

    Maps to a command-line argument: -polort %d.

  • stopband (a tuple of the form: (a float, a float)) – Remove all frequencies in the range. Maps to a command-line argument: -stopband %g %g.

Outputs:

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

TShift

Link to code

Bases: AFNICommand

Wrapped executable: 3dTshift.

Shifts voxel time series from input so that separate slices are aligned to the same temporal origin.

For complete details, see the 3dTshift Documentation.

Examples

Slice timing details may be specified explicitly via the slice_timing input:

>>> from nipype.interfaces import afni
>>> TR = 2.5
>>> tshift = afni.TShift()
>>> tshift.inputs.in_file = 'functional.nii'
>>> tshift.inputs.tzero = 0.0
>>> tshift.inputs.tr = '%.1fs' % TR
>>> tshift.inputs.slice_timing = list(np.arange(40) / TR)
>>> tshift.cmdline
'3dTshift -prefix functional_tshift -tpattern @slice_timing.1D -TR 2.5s -tzero 0.0 functional.nii'

When the slice_timing input is used, the timing_file output is populated, in this case with the generated file.

>>> tshift._list_outputs()['timing_file']  
'.../slice_timing.1D'

>>> np.loadtxt(tshift._list_outputs()['timing_file']).tolist()[:5]
[0.0, 0.4, 0.8, 1.2, 1.6]

If slice_encoding_direction is set to 'k-', the slice timing is reversed:

>>> tshift.inputs.slice_encoding_direction = 'k-'
>>> tshift.cmdline
'3dTshift -prefix functional_tshift -tpattern @slice_timing.1D -TR 2.5s -tzero 0.0 functional.nii'
>>> np.loadtxt(tshift._list_outputs()['timing_file']).tolist()[:5]
[15.6, 15.2, 14.8, 14.4, 14.0]

This method creates a slice_timing.1D file to be passed to 3dTshift. A pre-existing slice-timing file may be used in the same way:

>>> tshift = afni.TShift()
>>> tshift.inputs.in_file = 'functional.nii'
>>> tshift.inputs.tzero = 0.0
>>> tshift.inputs.tr = '%.1fs' % TR
>>> tshift.inputs.slice_timing = 'slice_timing.1D'
>>> tshift.cmdline
'3dTshift -prefix functional_tshift -tpattern @slice_timing.1D -TR 2.5s -tzero 0.0 functional.nii'

When a pre-existing file is provided, timing_file is simply passed through.

>>> tshift._list_outputs()['timing_file']  
'.../slice_timing.1D'

Alternatively, pre-specified slice timing patterns may be specified with the tpattern input. For example, to specify an alternating, ascending slice timing pattern:

>>> tshift = afni.TShift()
>>> tshift.inputs.in_file = 'functional.nii'
>>> tshift.inputs.tzero = 0.0
>>> tshift.inputs.tr = '%.1fs' % TR
>>> tshift.inputs.tpattern = 'alt+z'
>>> tshift.cmdline
'3dTshift -prefix functional_tshift -tpattern alt+z -TR 2.5s -tzero 0.0 functional.nii'

For backwards compatibility, tpattern may also take filenames prefixed with @. However, in this case, filenames are not validated, so this usage will be deprecated in future versions of Nipype.

>>> tshift = afni.TShift()
>>> tshift.inputs.in_file = 'functional.nii'
>>> tshift.inputs.tzero = 0.0
>>> tshift.inputs.tr = '%.1fs' % TR
>>> tshift.inputs.tpattern = '@slice_timing.1D'
>>> tshift.cmdline
'3dTshift -prefix functional_tshift -tpattern @slice_timing.1D -TR 2.5s -tzero 0.0 functional.nii'

In these cases, timing_file is undefined.

>>> tshift._list_outputs()['timing_file']  
<undefined>

In any configuration, the interface may be run as usual:

>>> res = tshift.run()
Mandatory Inputs:

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

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: {})

  • ignore (an integer) – Ignore the first set of points specified. Maps to a command-line argument: -ignore %s.

  • interp (‘Fourier’ or ‘linear’ or ‘cubic’ or ‘quintic’ or ‘heptic’) – Different interpolation methods (see 3dTshift for details) default = Fourier. Maps to a command-line argument: -%s.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • rlt (a boolean) – Before shifting, remove the mean and linear trend. Maps to a command-line argument: -rlt.

  • rltplus (a boolean) – Before shifting, remove the mean and linear trend and later put back the mean. Maps to a command-line argument: -rlt+.

  • slice_encoding_direction (‘k’ or ‘k-’) – Direction in which slice_timing is specified (default: k). If negative,slice_timing is defined in reverse order, that is, the first entry corresponds to the slice with the largest index, and the final entry corresponds to slice index zero. Only in effect when slice_timing is passed as list, not when it is passed as file. (Nipype default value: k)

  • slice_timing (a pathlike object or string representing an existing file or a list of items which are a float) – Time offsets from the volume acquisition onset for each slice. Maps to a command-line argument: -tpattern @%s. Mutually exclusive with inputs: tpattern.

  • tpattern (‘alt+z’ or ‘altplus’ or ‘alt+z2’ or ‘alt-z’ or ‘altminus’ or ‘alt-z2’ or ‘seq+z’ or ‘seqplus’ or ‘seq-z’ or ‘seqminus’ or a string) – Use specified slice time pattern rather than one in header. Maps to a command-line argument: -tpattern %s. Mutually exclusive with inputs: slice_timing.

  • tr (a string) – Manually set the TR. You can attach suffix “s” for seconds or “ms” for milliseconds. Maps to a command-line argument: -TR %s.

  • tslice (an integer) – Align each slice to time offset of given slice. Maps to a command-line argument: -slice %s. Mutually exclusive with inputs: tzero.

  • tzero (a float) – Align each slice to given time offset. Maps to a command-line argument: -tzero %s. Mutually exclusive with inputs: tslice.

Outputs:

  • out_file (a pathlike object or string representing an existing file) – Output file.

  • timing_file (a pathlike object or string representing a file) – AFNI formatted timing file, if slice_timing is a list.

TSmooth

Link to code

Bases: AFNICommand

Wrapped executable: 3dTsmooth.

Smooths each voxel time series in a 3D+time dataset and produces as output a new 3D+time dataset (e.g., lowpass filter in time).

For complete details, see the 3dTsmooth Documentation.

Examples

>>> from nipype.interfaces import afni
>>> from nipype.testing import  example_data
>>> smooth = afni.TSmooth()
>>> smooth.inputs.in_file = 'functional.nii'
>>> smooth.inputs.adaptive = 5
>>> smooth.cmdline
'3dTsmooth -adaptive 5 -prefix functional_smooth functional.nii'
>>> res = smooth.run()
Mandatory Inputs:

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

Optional Inputs:

  • adaptive (an integer) – Use adaptive mean filtering of width N (where N must be odd and bigger than 3). Maps to a command-line argument: -adaptive %d.

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

  • blackman (an integer) – Use N point Blackman windows. (N must be odd and bigger than 1.). Maps to a command-line argument: -blackman %d.

  • custom (a pathlike object or string representing a file) – Odd # of coefficients must be in a single column in ASCII file. Maps to a command-line argument: -custom %s.

  • datum (a string) – Sets the data type of the output dataset. Maps to a command-line argument: -datum %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: {})

  • hamming (an integer) – Use N point Hamming windows. (N must be odd and bigger than 1.). Maps to a command-line argument: -hamming %d.

  • lin (a boolean) – 3 point linear filter: \(0.15\,a + 0.70\,b + 0.15\,c\) [This is the default smoother]. Maps to a command-line argument: -lin.

  • lin3 (an integer) – 3 point linear filter: \(0.5\,(1-m)\,a + m\,b + 0.5\,(1-m)\,c\). Here, ‘m’ is a number strictly between 0 and 1. Maps to a command-line argument: -3lin %d.

  • med (a boolean) – 3 point median filter: median(a,b,c). Maps to a command-line argument: -med.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • osf (a boolean) – 3 point order statistics filter:\(0.15\,min(a,b,c) + 0.70\,median(a,b,c) + 0.15\,max(a,b,c)\). Maps to a command-line argument: -osf.

  • out_file (a pathlike object or string representing a file) – Output file from 3dTSmooth. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

Outputs:

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

Volreg

Link to code

Bases: AFNICommand

Wrapped executable: 3dvolreg.

Register input volumes to a base volume using AFNI 3dvolreg command

For complete details, see the 3dvolreg Documentation.

Examples

>>> from nipype.interfaces import afni
>>> volreg = afni.Volreg()
>>> volreg.inputs.in_file = 'functional.nii'
>>> volreg.inputs.args = '-Fourier -twopass'
>>> volreg.inputs.zpad = 4
>>> volreg.inputs.outputtype = 'NIFTI'
>>> volreg.cmdline  
'3dvolreg -Fourier -twopass -1Dfile functional.1D -1Dmatrix_save functional.aff12.1D -prefix functional_volreg.nii -zpad 4 -maxdisp1D functional_md.1D functional.nii'
>>> res = volreg.run()  

>>> from nipype.interfaces import afni
>>> volreg = afni.Volreg()
>>> volreg.inputs.in_file = 'functional.nii'
>>> volreg.inputs.interp = 'cubic'
>>> volreg.inputs.verbose = True
>>> volreg.inputs.zpad = 1
>>> volreg.inputs.basefile = 'functional.nii'
>>> volreg.inputs.out_file = 'rm.epi.volreg.r1'
>>> volreg.inputs.oned_file = 'dfile.r1.1D'
>>> volreg.inputs.oned_matrix_save = 'mat.r1.tshift+orig.1D'
>>> volreg.cmdline
'3dvolreg -cubic -1Dfile dfile.r1.1D -1Dmatrix_save mat.r1.tshift+orig.1D -prefix rm.epi.volreg.r1 -verbose -base functional.nii -zpad 1 -maxdisp1D functional_md.1D functional.nii'
>>> res = volreg.run()
Mandatory Inputs:

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

Optional Inputs:

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

  • basefile (a pathlike object or string representing an existing file) – Base file for registration. Maps to a command-line argument: -base %s (position: -6).

  • copyorigin (a boolean) – Copy base file origin coords to output. Maps to a command-line argument: -twodup.

  • 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: {})

  • in_weight_volume (a tuple of the form: (a pathlike object or string representing an existing file, an integer) or a pathlike object or string representing an existing file) – Weights for each voxel specified by a file with an optional volume number (defaults to 0). Maps to a command-line argument: -weight '%s[%d]'.

  • interp (‘Fourier’ or ‘cubic’ or ‘heptic’ or ‘quintic’ or ‘linear’) – Spatial interpolation methods [default = heptic]. Maps to a command-line argument: -%s.

  • md1d_file (a pathlike object or string representing a file) – Max displacement output file. Maps to a command-line argument: -maxdisp1D %s (position: -4).

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • oned_file (a pathlike object or string representing a file) – 1D movement parameters output file. Maps to a command-line argument: -1Dfile %s.

  • oned_matrix_save (a pathlike object or string representing a file) – Save the matrix transformation. Maps to a command-line argument: -1Dmatrix_save %s.

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • timeshift (a boolean) – Time shift to mean slice time offset. Maps to a command-line argument: -tshift 0.

  • verbose (a boolean) – More detailed description of the process. Maps to a command-line argument: -verbose.

  • zpad (an integer) – Zeropad around the edges by ‘n’ voxels during rotations. Maps to a command-line argument: -zpad %d (position: -5).

Outputs:

  • md1d_file (a pathlike object or string representing an existing file) – Max displacement info file.

  • oned_file (a pathlike object or string representing an existing file) – Movement parameters info file.

  • oned_matrix_save (a pathlike object or string representing an existing file) – Matrix transformation from base to input.

  • out_file (a pathlike object or string representing an existing file) – Registered file.

Warp

Link to code

Bases: AFNICommand

Wrapped executable: 3dWarp.

Use 3dWarp for spatially transforming a dataset.

Examples

>>> from nipype.interfaces import afni
>>> warp = afni.Warp()
>>> warp.inputs.in_file = 'structural.nii'
>>> warp.inputs.deoblique = True
>>> warp.inputs.out_file = 'trans.nii.gz'
>>> warp.cmdline
'3dWarp -deoblique -prefix trans.nii.gz structural.nii'
>>> res = warp.run()  

>>> warp_2 = afni.Warp()
>>> warp_2.inputs.in_file = 'structural.nii'
>>> warp_2.inputs.newgrid = 1.0
>>> warp_2.inputs.out_file = 'trans.nii.gz'
>>> warp_2.cmdline
'3dWarp -newgrid 1.000000 -prefix trans.nii.gz structural.nii'
>>> res = warp_2.run()

See also

For complete details, see the 3dWarp Documentation..

Mandatory Inputs:

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

Optional Inputs:

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

  • deoblique (a boolean) – Transform dataset from oblique to cardinal. Maps to a command-line argument: -deoblique.

  • 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: {})

  • gridset (a pathlike object or string representing an existing file) – Copy grid of specified dataset. Maps to a command-line argument: -gridset %s.

  • interp (‘linear’ or ‘cubic’ or ‘NN’ or ‘quintic’) – Spatial interpolation methods [default = linear]. Maps to a command-line argument: -%s.

  • matparent (a pathlike object or string representing an existing file) – Apply transformation from 3dWarpDrive. Maps to a command-line argument: -matparent %s.

  • mni2tta (a boolean) – Transform dataset from MNI152 to Talaraich. Maps to a command-line argument: -mni2tta.

  • newgrid (a float) – Specify grid of this size (mm). Maps to a command-line argument: -newgrid %f.

  • num_threads (an integer) – Set number of threads. (Nipype default value: 1)

  • oblique_parent (a pathlike object or string representing an existing file) – Read in the oblique transformation matrix from an oblique dataset and make cardinal dataset oblique to match. Maps to a command-line argument: -oblique_parent %s.

  • out_file (a pathlike object or string representing a file) – Output image file name. Maps to a command-line argument: -prefix %s.

  • outputtype (‘NIFTI’ or ‘AFNI’ or ‘NIFTI_GZ’) – AFNI output filetype.

  • save_warp (a boolean) – Save warp as .mat file. Requires inputs: verbose.

  • tta2mni (a boolean) – Transform dataset from Talairach to MNI152. Maps to a command-line argument: -tta2mni.

  • verbose (a boolean) – Print out some information along the way. Maps to a command-line argument: -verb.

  • zpad (an integer) – Pad input dataset with N planes of zero on all sides. Maps to a command-line argument: -zpad %d.

Outputs:

  • out_file (a pathlike object or string representing an existing file) – Warped file.

  • warp_file (a pathlike object or string representing a file) – Warp transform .mat file.