nipype.interfaces.afni.model module

AFNI modeling interfaces.

Examples

See the docstrings of the individual classes for examples.

Deconvolve

Link to code

Bases: AFNICommand

Wrapped executable: 3dDeconvolve.

Performs OLS regression given a 4D neuroimage file and stimulus timings

For complete details, see the 3dDeconvolve Documentation.

Examples

>>> from nipype.interfaces import afni
>>> deconvolve = afni.Deconvolve()
>>> deconvolve.inputs.in_files = ['functional.nii', 'functional2.nii']
>>> deconvolve.inputs.out_file = 'output.nii'
>>> deconvolve.inputs.x1D = 'output.1D'
>>> stim_times = [(1, 'timeseries.txt', 'SPMG1(4)')]
>>> deconvolve.inputs.stim_times = stim_times
>>> deconvolve.inputs.stim_label = [(1, 'Houses')]
>>> deconvolve.inputs.gltsym = ['SYM: +Houses']
>>> deconvolve.inputs.glt_label = [(1, 'Houses')]
>>> deconvolve.cmdline
"3dDeconvolve -input functional.nii functional2.nii -bucket output.nii -x1D output.1D -num_stimts 1 -stim_times 1 timeseries.txt 'SPMG1(4)' -stim_label 1 Houses -num_glt 1 -gltsym 'SYM: +Houses' -glt_label 1 Houses"
>>> res = deconvolve.run()
Optional Inputs:

  • STATmask (a pathlike object or string representing an existing file) – Build a mask from provided file, and use this mask for the purpose of reporting truncation-to float issues AND for computing the FDR curves. The actual results ARE not masked with this option (only with ‘mask’ or ‘automask’ options). Maps to a command-line argument: -STATmask %s.

  • TR_1D (a float) – TR to use with ‘input1D’. This option has no effect if you do not also use ‘input1D’. Maps to a command-line argument: -TR_1D %f.

  • allzero_OK (a boolean) – Don’t consider all zero matrix columns to be the type of error that ‘gotforit’ is needed to ignore. Maps to a command-line argument: -allzero_OK.

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

  • automask (a boolean) – Build a mask automatically from input data (will be slow for long time series datasets). Maps to a command-line argument: -automask.

  • cbucket (a string) – Name for dataset in which to save the regression coefficients (no statistics). This dataset will be used in a -xrestore run [not yet implemented] instead of the bucket dataset, if possible. Maps to a command-line argument: -cbucket %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.

  • dmbase (a boolean) – De-mean baseline time series (default if ‘polort’ >= 0). Maps to a command-line argument: -dmbase.

  • dname (a tuple of the form: (a string, a string)) – Set environmental variable to provided value. Maps to a command-line argument: -D%s=%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: {})

  • force_TR (a float) – Use this value instead of the TR in the ‘input’ dataset. (It’s better to fix the input using Refit.). Maps to a command-line argument: -force_TR %f (position: 0).

  • fout (a boolean) – Output F-statistic for each stimulus. Maps to a command-line argument: -fout.

  • global_times (a boolean) – Use global timing for stimulus timing files. Maps to a command-line argument: -global_times. Mutually exclusive with inputs: local_times.

  • glt_label (a list of items which are a tuple of the form: (an integer, a string)) – General linear test (i.e., contrast) labels. Maps to a command-line argument: -glt_label %d %s... (position: -1). Requires inputs: gltsym.

  • gltsym (a list of items which are a string) – General linear tests (i.e., contrasts) using symbolic conventions (e.g., ‘+Label1 -Label2’). Maps to a command-line argument: -gltsym 'SYM: %s'... (position: -2).

  • goforit (an integer) – Use this to proceed even if the matrix has bad problems (e.g., duplicate columns, large condition number, etc.). Maps to a command-line argument: -GOFORIT %i.

  • in_files (a list of items which are a pathlike object or string representing an existing file) – Filenames of 3D+time input datasets. More than one filename can be given and the datasets will be auto-catenated in time. You can input a 1D time series file here, but the time axis should run along the ROW direction, not the COLUMN direction as in the ‘input1D’ option. Maps to a command-line argument: -input %s (position: 1).

  • input1D (a pathlike object or string representing an existing file) – Filename of single (fMRI) .1D time series where time runs down the column. Maps to a command-line argument: -input1D %s.

  • legendre (a boolean) – Use Legendre polynomials for null hypothesis (baseline model). Maps to a command-line argument: -legendre.

  • local_times (a boolean) – Use local timing for stimulus timing files. Maps to a command-line argument: -local_times. Mutually exclusive with inputs: global_times.

  • mask (a pathlike object or string representing an existing file) – Filename of 3D mask dataset; only data time series from within the mask will be analyzed; results for voxels outside the mask will be set to zero. Maps to a command-line argument: -mask %s.

  • noblock (a boolean) – Normally, if you input multiple datasets with ‘input’, then the separate datasets are taken to be separate image runs that get separate baseline models. Use this options if you want to have the program consider these to be all one big run.* If any of the input dataset has only 1 sub-brick, then this option is automatically invoked!* If the auto-catenation feature isn’t used, then this option has no effect, no how, no way. Maps to a command-line argument: -noblock.

  • nocond (a boolean) – DON’T calculate matrix condition number. Maps to a command-line argument: -nocond.

  • nodmbase (a boolean) – Don’t de-mean baseline time series. Maps to a command-line argument: -nodmbase.

  • nofdr (a boolean) – Don’t compute the statistic-vs-FDR curves for the bucket dataset. Maps to a command-line argument: -noFDR.

  • nolegendre (a boolean) – Use power polynomials for null hypotheses. Don’t do this unless you are crazy!. Maps to a command-line argument: -nolegendre.

  • nosvd (a boolean) – Use Gaussian elimination instead of SVD. Maps to a command-line argument: -nosvd.

  • num_glt (an integer) – Number of general linear tests (i.e., contrasts). Maps to a command-line argument: -num_glt %d (position: -3).

  • num_stimts (an integer) – Number of stimulus timing files. Maps to a command-line argument: -num_stimts %d (position: -6).

  • num_threads (an integer) – Run the program with provided number of sub-processes. Maps to a command-line argument: -jobs %d.

  • ortvec (a tuple of the form: (a pathlike object or string representing an existing file, a string)) – This option lets you input a rectangular array of 1 or more baseline vectors from a file. This method is a fast way to include a lot of baseline regressors in one step. . Maps to a command-line argument: -ortvec %s %s.

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

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

  • polort (an integer) – Degree of polynomial corresponding to the null hypothesis [default: 1]. Maps to a command-line argument: -polort %d.

  • rmsmin (a float) – Minimum rms error to reject reduced model (default = 0; don’t use this option normally!). Maps to a command-line argument: -rmsmin %f.

  • rout (a boolean) – Output the R^2 statistic for each stimulus. Maps to a command-line argument: -rout.

  • sat (a boolean) – Check the dataset time series for initial saturation transients, which should normally have been excised before data analysis. Maps to a command-line argument: -sat. Mutually exclusive with inputs: trans.

  • singvals (a boolean) – Print out the matrix singular values. Maps to a command-line argument: -singvals.

  • stim_label (a list of items which are a tuple of the form: (an integer, a string)) – Label for kth input stimulus (e.g., Label1). Maps to a command-line argument: -stim_label %d %s... (position: -4). Requires inputs: stim_times.

  • stim_times (a list of items which are a tuple of the form: (an integer, a pathlike object or string representing an existing file, a string)) – Generate a response model from a set of stimulus times given in file. Maps to a command-line argument: -stim_times %d %s '%s'... (position: -5).

  • stim_times_subtract (a float) – This option means to subtract specified seconds from each time encountered in any ‘stim_times’ option. The purpose of this option is to make it simple to adjust timing files for the removal of images from the start of each imaging run. Maps to a command-line argument: -stim_times_subtract %f.

  • svd (a boolean) – Use SVD instead of Gaussian elimination (default). Maps to a command-line argument: -svd.

  • tout (a boolean) – Output the T-statistic for each stimulus. Maps to a command-line argument: -tout.

  • trans (a boolean) – Check the dataset time series for initial saturation transients, which should normally have been excised before data analysis. Maps to a command-line argument: -trans. Mutually exclusive with inputs: sat.

  • vout (a boolean) – Output the sample variance (MSE) for each stimulus. Maps to a command-line argument: -vout.

  • x1D (a pathlike object or string representing a file) – Specify name for saved X matrix. Maps to a command-line argument: -x1D %s.

  • x1D_stop (a boolean) – Stop running after writing .xmat.1D file. Maps to a command-line argument: -x1D_stop.

Outputs:

  • cbucket (a pathlike object or string representing a file) – Output regression coefficients file (if generated).

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

  • reml_script (a pathlike object or string representing an existing file) – Automatically generated script to run 3dREMLfit.

  • x1D (a pathlike object or string representing an existing file) – Save out X matrix.

Remlfit

Link to code

Bases: AFNICommand

Wrapped executable: 3dREMLfit.

Performs Generalized least squares time series fit with Restricted Maximum Likelihood (REML) estimation of the temporal auto-correlation structure.

For complete details, see the 3dREMLfit Documentation.

Examples

>>> from nipype.interfaces import afni
>>> remlfit = afni.Remlfit()
>>> remlfit.inputs.in_files = ['functional.nii', 'functional2.nii']
>>> remlfit.inputs.out_file = 'output.nii'
>>> remlfit.inputs.matrix = 'output.1D'
>>> remlfit.inputs.gltsym = [('SYM: +Lab1 -Lab2', 'TestSYM'), ('timeseries.txt', 'TestFile')]
>>> remlfit.cmdline
'3dREMLfit -gltsym "SYM: +Lab1 -Lab2" TestSYM -gltsym "timeseries.txt" TestFile -input "functional.nii functional2.nii" -matrix output.1D -Rbuck output.nii'
>>> res = remlfit.run()
Mandatory Inputs:

  • in_files (a list of items which are a pathlike object or string representing an existing file) – Read time series dataset. Maps to a command-line argument: -input "%s".

  • matrix (a pathlike object or string representing a file) – The design matrix file, which should have been output from Deconvolve via the ‘x1D’ option. Maps to a command-line argument: -matrix %s.

Optional Inputs:

  • STATmask (a pathlike object or string representing an existing file) – Filename of 3D mask dataset to be used for the purpose of reporting truncation-to float issues AND for computing the FDR curves. The actual results ARE not masked with this option (only with ‘mask’ or ‘automask’ options). Maps to a command-line argument: -STATmask %s.

  • addbase (a list of items which are a pathlike object or string representing an existing file) – File(s) to add baseline model columns to the matrix with this option. Each column in the specified file(s) will be appended to the matrix. File(s) must have at least as many rows as the matrix does. Maps to a command-line argument: -addbase %s.

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

  • automask (a boolean) – Build a mask automatically from input data (will be slow for long time series datasets). Maps to a command-line argument: -automask. (Nipype default value: False)

  • dsort (a pathlike object or string representing an existing file) – 4D dataset to be used as voxelwise baseline regressor. Maps to a command-line argument: -dsort %s.

  • dsort_nods (a boolean) – If ‘dsort’ option is used, this command will output additional results files excluding the ‘dsort’ file. Maps to a command-line argument: -dsort_nods. Requires inputs: dsort.

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

  • errts_file (a pathlike object or string representing a file) – Output dataset for REML residuals = data - fitted model. Maps to a command-line argument: -Rerrts %s.

  • fitts_file (a pathlike object or string representing a file) – Output dataset for REML fitted model. Maps to a command-line argument: -Rfitts %s.

  • fout (a boolean) – Output F-statistic for each stimulus. Maps to a command-line argument: -fout.

  • glt_file (a pathlike object or string representing a file) – Output dataset for beta + statistics from the REML estimation, but ONLY for the GLTs added on the REMLfit command line itself via ‘gltsym’; GLTs from Deconvolve’s command line will NOT be included. Maps to a command-line argument: -Rglt %s.

  • gltsym (a list of items which are a tuple of the form: (a pathlike object or string representing an existing file, a string) or a tuple of the form: (a string, a string)) – Read a symbolic GLT from input file and associate it with a label. As in Deconvolve, you can also use the ‘SYM:’ method to provide the definition of the GLT directly as a string (e.g., with ‘SYM: +Label1 -Label2’). Unlike Deconvolve, you MUST specify ‘SYM: ‘ if providing the GLT directly as a string instead of from a file. Maps to a command-line argument: -gltsym "%s" %s....

  • goforit (a boolean) – With potential issues flagged in the design matrix, an attempt will nevertheless be made to fit the model. Maps to a command-line argument: -GOFORIT.

  • mask (a pathlike object or string representing an existing file) – Filename of 3D mask dataset; only data time series from within the mask will be analyzed; results for voxels outside the mask will be set to zero. Maps to a command-line argument: -mask %s.

  • matim (a pathlike object or string representing a file) – Read a standard file as the matrix. You can use only Col as a name in GLTs with these nonstandard matrix input methods, since the other names come from the ‘matrix’ file. These mutually exclusive options are ignored if ‘matrix’ is used. Maps to a command-line argument: -matim %s. Mutually exclusive with inputs: matrix.

  • nobout (a boolean) – Do NOT add baseline (null hypothesis) regressor betas to the ‘rbeta_file’ and/or ‘obeta_file’ output datasets. Maps to a command-line argument: -nobout.

  • nodmbase (a boolean) – By default, baseline columns added to the matrix via ‘addbase’ or ‘slibase’ or ‘dsort’ will each have their mean removed (as is done in Deconvolve); this option turns this centering off. Maps to a command-line argument: -nodmbase. Requires inputs: addbase, dsort.

  • nofdr (a boolean) – Do NOT add FDR curve data to bucket datasets; FDR curves can take a long time if ‘tout’ is used. Maps to a command-line argument: -noFDR.

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

  • obeta (a pathlike object or string representing a file) – Dataset for beta weights from the OLSQ estimation. Maps to a command-line argument: -Obeta %s.

  • obuck (a pathlike object or string representing a file) – Dataset for beta + statistics from the OLSQ estimation. Maps to a command-line argument: -Obuck %s.

  • oerrts (a pathlike object or string representing a file) – Dataset for OLSQ residuals (data - fitted model). Maps to a command-line argument: -Oerrts %s.

  • ofitts (a pathlike object or string representing a file) – Dataset for OLSQ fitted model. Maps to a command-line argument: -Ofitts %s.

  • oglt (a pathlike object or string representing a file) – Dataset for beta + statistics from ‘gltsym’ options. Maps to a command-line argument: -Oglt %s.

  • out_file (a pathlike object or string representing a file) – Output dataset for beta + statistics from the REML estimation; also contains the results of any GLT analysis requested in the Deconvolve setup, similar to the ‘bucket’ output from Deconvolve. This dataset does NOT get the betas (or statistics) of those regressors marked as ‘baseline’ in the matrix file. Maps to a command-line argument: -Rbuck %s.

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

  • ovar (a pathlike object or string representing a file) – Dataset for OLSQ st.dev. parameter (kind of boring). Maps to a command-line argument: -Ovar %s.

  • polort (an integer) – If no ‘matrix’ option is given, AND no ‘matim’ option, create a matrix with Legendre polynomial regressorsup to the specified order. The default value is 0, whichproduces a matrix with a single column of all ones. Maps to a command-line argument: -polort %d. Mutually exclusive with inputs: matrix.

  • quiet (a boolean) – Turn off most progress messages. Maps to a command-line argument: -quiet.

  • rbeta_file (a pathlike object or string representing a file) – Output dataset for beta weights from the REML estimation, similar to the ‘cbucket’ output from Deconvolve. This dataset will contain all the beta weights, for baseline and stimulus regressors alike, unless the ‘-nobout’ option is given – in that case, this dataset will only get the betas for the stimulus regressors. Maps to a command-line argument: -Rbeta %s.

  • rout (a boolean) – Output the R^2 statistic for each stimulus. Maps to a command-line argument: -rout.

  • slibase (a list of items which are a pathlike object or string representing an existing file) – Similar to ‘addbase’ in concept, BUT each specified file must have an integer multiple of the number of slices in the input dataset(s); then, separate regression matrices are generated for each slice, with the first column of the file appended to the matrix for the first slice of the dataset, the second column of the file appended to the matrix for the first slice of the dataset, and so on. Intended to help model physiological noise in FMRI, or other effects you want to regress out that might change significantly in the inter-slice time intervals. This will slow the program down, and make it use a lot more memory (to hold all the matrix stuff). Maps to a command-line argument: -slibase %s.

  • slibase_sm (a list of items which are a pathlike object or string representing an existing file) – Similar to ‘slibase’, BUT each file much be in slice major order (i.e. all slice0 columns come first, then all slice1 columns, etc). Maps to a command-line argument: -slibase_sm %s.

  • tout (a boolean) – Output the T-statistic for each stimulus; if you use ‘out_file’ and do not give any of ‘fout’, ‘tout’,or ‘rout’, then the program assumes ‘fout’ is activated. Maps to a command-line argument: -tout.

  • usetemp (a boolean) – Write intermediate stuff to disk, to economize on RAM. Using this option might be necessary to run with ‘slibase’ and with ‘Grid’ values above the default, since the program has to store a large number of matrices for such a problem: two for every slice and for every (a,b) pair in the ARMA parameter grid. Temporary files are written to the directory given in environment variable TMPDIR, or in /tmp, or in ./ (preference is in that order). Maps to a command-line argument: -usetemp.

  • var_file (a pathlike object or string representing a file) – Output dataset for REML variance parameters. Maps to a command-line argument: -Rvar %s.

  • verb (a boolean) – Turns on more progress messages, including memory usage progress reports at various stages. Maps to a command-line argument: -verb.

  • wherr_file (a pathlike object or string representing a file) – Dataset for REML residual, whitened using the estimated ARMA(1,1) correlation matrix of the noise. Maps to a command-line argument: -Rwherr %s.

Outputs:

  • errts_file (a pathlike object or string representing a file) – Output dataset for REML residuals = data - fitted model (if generated).

  • fitts_file (a pathlike object or string representing a file) – Output dataset for REML fitted model (if generated).

  • glt_file (a pathlike object or string representing a file) – Output dataset for beta + statistics from the REML estimation, but ONLY for the GLTs added on the REMLfit command line itself via ‘gltsym’ (if generated).

  • obeta (a pathlike object or string representing a file) – Dataset for beta weights from the OLSQ estimation (if generated).

  • obuck (a pathlike object or string representing a file) – Dataset for beta + statistics from the OLSQ estimation (if generated).

  • oerrts (a pathlike object or string representing a file) – Dataset for OLSQ residuals = data - fitted model (if generated).

  • ofitts (a pathlike object or string representing a file) – Dataset for OLSQ fitted model (if generated).

  • oglt (a pathlike object or string representing a file) – Dataset for beta + statistics from ‘gltsym’ options (if generated).

  • out_file (a pathlike object or string representing a file) – Dataset for beta + statistics from the REML estimation (if generated).

  • ovar (a pathlike object or string representing a file) – Dataset for OLSQ st.dev. parameter (if generated).

  • rbeta_file (a pathlike object or string representing a file) – Output dataset for beta weights from the REML estimation (if generated).

  • var_file (a pathlike object or string representing a file) – Dataset for REML variance parameters (if generated).

  • wherr_file (a pathlike object or string representing a file) – Dataset for REML residual, whitened using the estimated ARMA(1,1) correlation matrix of the noise (if generated).

Synthesize

Link to code

Bases: AFNICommand

Wrapped executable: 3dSynthesize.

Reads a ‘-cbucket’ dataset and a ‘.xmat.1D’ matrix from 3dDeconvolve,

and synthesizes a fit dataset using user-selected sub-bricks and matrix columns.

For complete details, see the 3dSynthesize Documentation.

Examples

>>> from nipype.interfaces import afni
>>> synthesize = afni.Synthesize()
>>> synthesize.inputs.cbucket = 'functional.nii'
>>> synthesize.inputs.matrix = 'output.1D'
>>> synthesize.inputs.select = ['baseline']
>>> synthesize.cmdline
'3dSynthesize -cbucket functional.nii -matrix output.1D -select baseline'
>>> syn = synthesize.run()
Mandatory Inputs:

  • cbucket (a pathlike object or string representing a file) – Read the dataset output from 3dDeconvolve via the ‘-cbucket’ option. Maps to a command-line argument: -cbucket %s.

  • matrix (a pathlike object or string representing a file) – Read the matrix output from 3dDeconvolve via the ‘-x1D’ option. Maps to a command-line argument: -matrix %s.

  • select (a list of items which are a string) – A list of selected columns from the matrix (and the corresponding coefficient sub-bricks from the cbucket). Valid types include ‘baseline’, ‘polort’, ‘allfunc’, ‘allstim’, ‘all’, Can also provide ‘something’ where something matches a stim_label from 3dDeconvolve, and ‘digits’ where digits are the numbers of the select matrix columns by numbers (starting at 0), or number ranges of the form ‘3..7’ and ‘3-7’. Maps to a command-line argument: -select %s.

Optional Inputs:

  • TR (a float) – TR to set in the output. The default value of TR is read from the header of the matrix file. Maps to a command-line argument: -TR %f.

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

  • cenfill (‘zero’ or ‘nbhr’ or ‘none’) – Determines how censored time points from the 3dDeconvolve run will be filled. Valid types are ‘zero’, ‘nbhr’ and ‘none’. Maps to a command-line argument: -cenfill %s.

  • dry_run (a boolean) – Don’t compute the output, just check the inputs. Maps to a command-line argument: -dry.

  • 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 dataset prefix name (default ‘syn’). 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.