3 dqm@sdZddlZddlmZmZmZmZmZmZm Z m Z m Z m Z ddl mZddlmZmZmZmZmZGd d d eZGd d d eZGd ddeZGdddeZGdddeZGdddeZGdddeZGdddeZdS)zj AFNI modeling interfaces. Examples -------- See the docstrings of the individual classes for examples. N) CommandLineInputSpec CommandLine Directory TraitedSpectraits isdefinedFileInputMultiPath UndefinedStr)BibTeX)AFNICommandBase AFNICommandAFNICommandInputSpecAFNICommandOutputSpecInfoc@seZdZeeddddddddZejd d d gd Zejd d dgd Z ejdddZ ej ddddZ eddddZ ej dddZejdddZejdddZejdd dZejd!d"dZejd#d$dZejd%d&dZej d'd(dZejd)d*dZejd+d,dZejd-d.dZejd/d0dZejeed1d2dZed3d4ddZejd5d6dZed7d8ddZ ed9d:ddZ!ejd;ded?d@dAdBdZ#edCdDdZ$ejdEdFdZ%ejdGdHdZ&edIdJdZ'ejdKdLddMZ(ejdNdOdZ)ejdPdQdZ*ejdRdSdZ+ejdTdUdZ,ejdVdWdZ-ejdXdYdZgd Z.ejd[d\d]gd Z/ejd^d_d}dZ0ej1ejejdad@edbdd>edcd@ddded~dZ2ej1ejejdgd@edhd@didjdkgddmZ3ej dndodZ4ejdpdqddZ5ej1edsd@dtduddZ6ej1ejejdwd@edxd@dydzd{gddmZ7d|S)DeconvolveInputSpecT)existsafilenames 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.z -input %sF r)descargstrcopyfileseppositionz~check the dataset time series for initial saturation transients, which should normally have been excised before data analysis.z-sattrans)rrxorz-transsatanormally, 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.z-noblock)rrzduse this value instead of the TR in the 'input' dataset. (It's better to fix the input using Refit.)z -force_TR %fr)rrrzJfilename of single (fMRI) .1D time series where time runs down the column.z -input1D %s)rrrzUTR to use with 'input1D'. This option has no effect if you do not also use 'input1D'.z -TR_1D %fz=use Legendre polynomials for null hypothesis (baseline model)z -legendrezNuse power polynomials for null hypotheses. Don't do this unless you are crazy!z -nolegendrez"don't de-mean baseline time seriesz -nodmbasez7de-mean baseline time series (default if 'polort' >= 0)z-dmbasez1use SVD instead of Gaussian elimination (default)z-svdz'use Gaussian elimination instead of SVDz-nosvdzXminimum rms error to reject reduced model (default = 0; don't use this option normally!)z -rmsmin %fz'DON'T calculate matrix condition numberz-nocondz$print out the matrix singular valuesz -singvalszpuse this to proceed even if the matrix has bad problems (e.g., duplicate columns, large condition number, etc.).z -GOFORIT %izcdon't consider all zero matrix columns to be the type of error that 'gotforit' is needed to ignore.z -allzero_OKz,set environmental variable to provided valuez-D%s=%szfilename 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.z-mask %szWbuild a mask automatically from input data (will be slow for long time series datasets)z -automaskzbuild 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).z -STATmask %szfilename 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).z -censor %szFdegree of polynomial corresponding to the null hypothesis [default: 1]z -polort %dfilename)rrlabel)rzthis 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. z -ortvec %s %szspecify name for saved X matrixz-x1D %sz(stop running after writing .xmat.1D filez -x1D_stopzName 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.z -cbucket %szoutput statistics filez -bucket %sz5run the program with provided number of sub-processesz-jobs %d)rrZnohashz$output F-statistic for each stimulusz-foutz*output the R^2 statistic for each stimulusz-routz(output the T-statistic for each stimulusz-toutz2output the sample variance (MSE) for each stimulusz-voutzADon't compute the statistic-vs-FDR curves for the bucket dataset.z-noFDRz+use global timing for stimulus timing filesz -global_times local_timesz*use local timing for stimulus timing filesz -local_times global_timesznumber of stimulus timing filesz-num_stimts %dzk-th response modelzstimulus timing filemodelzEgenerate a response model from a set of stimulus times given in file.z-stim_times %d %s '%s'...zk-th input stimuluszstimulus labelz+label for kth input stimulus (e.g., Label1)z-stim_label %d %s... stim_times)rrrequiresrzthis 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.z-stim_times_subtract %fz0number of general linear tests (i.e., contrasts)z -num_glt %dr zsymbolic general linear testz[general linear tests (i.e., contrasts) using symbolic conventions (e.g., '+Label1 -Label2')z-gltsym 'SYM: %s'...rzk-th general linear testz GLT labelz+general linear test (i.e., contrast) labelsz-glt_label %d %s...gltsymNi)8__name__ __module__ __qualname__r r in_filesrBoolrrZnoblockFloatZforce_TRZinput1DZTR_1DZlegendreZ nolegendrenodmbaseZdmbaseZsvdZnosvdZrmsminZnocondZsingvalsIntgoforitZ allzero_OKTupler ZdnamemaskautomaskSTATmaskZcensorpolortZortvecx1Dx1D_stopcbucketout_fileZ num_threadsfoutrouttoutZvoutnofdrr#r" num_stimtsListr'Z stim_labelZstim_times_subtractnum_gltr*Z glt_labelrIrI>/tmp/pip-build-7vycvbft/nipype/nipype/interfaces/afni/model.pyr&s                    rc@s:eZdZedddZedddZedddZeddZdS) DeconvolveOutputSpeczoutput statistics fileT)rrz-automatical generated script to run 3dREMLfitzsave out X matrixz2output regression coefficients file (if generated))rN)r0r1r2r rA reml_scriptr>r@rIrIrIrJrK s    rKcsBeZdZdZdZeZeZfddZ d fdd Z dd Z Z S) Deconvolvea%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() # doctest: +SKIP Z 3dDeconvolvecsJ|dkr6x,t|D] \}}|jdr|jd||<qWtt|j|||S)Nr*zSYM: ) enumerate startswithlstripsuperrM _format_arg)selfnameZ trait_specvaluenval) __class__rIrJrR.s  zDeconvolve._format_argNcs|dkr g}t|jjr6t|jj r6t|jj|j_t|jjr`t|jj r`t|jj|j_t|jjstd|j_tt |j |S)Nz Decon.nii) leninputsr'rrFr*rHrArQrM _parse_inputs)rSskip)rXrIrJr[6s zDeconvolve._parse_inputscCs|jj}i}|jj|d<tj|d<t|jjrr|jjjds\tj j |jjd|d<qtj j |jj|d<n|j fddi||d<t|jj rtj j |jj |d<|j fddi||d<|jj r|d =|d=ntj j |jj|d <|S) Nbasenamecwdz.xmat.1Dr>suffixr@z .REML_cmdrLrA) output_specgetrZrAosgetcwdrr>endswithpathabspathZ _gen_fnamer@r?)rSoutputsZ_gen_fname_optsrIrIrJ _list_outputsBs      zDeconvolve._list_outputs)N) r0r1r2__doc___cmdr input_specrKr`rRr[rh __classcell__rIrI)rXrJrMs  rMc@sLeZdZeeddddddddZedd dd Zejd d d gdZ eddd gdZ eddddZ ej ddddZ eddddZeeddddddddZeedddddd Zeedddd!d"d Zej d#d$d Zej d%d&d'd(gd)Zed*ddd+d,Zej d-d.d(gd)Zej d/d0d Zej d1d2d Zej d3d4d Zej d5d6d Zej d7d8d Zejejejeddeejeed9d:d Zed;dd Z!ed?d@d Z"edAdBd Z#edCdDd Z$edEdFd Z%edGdHd Z&ej dIdJd Z'ej dKdLd Z(ej dMdNd Z)edOdPd Z*edQdRd Z+edSdTd Z,edUdVd Z-edWdXd Z.edYdZd Z/d[S)\RemlfitInputSpecT)rzRead time series datasetz -input "%s"Fr)rr mandatoryrrzZthe design matrix file, which should have been output from Deconvolve via the 'x1D' optionz -matrix %s)rrrnzif 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 onesz -polort %dmatrix)rrrzread 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.z -matim %szfilename 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.z-mask %s)rrrz -automaskzWbuild a mask automatically from input data (will be slow for long time series datasets))Z usedefaultrrzfilename 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).z -STATmask %sz3file containing columns to add to regression matrix)rrzfile(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.z -addbase %s)rrrrasimilar 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).z -slibase %s)rrzsimilar to 'slibase', BUT each file much be in slice major order (i.e. all slice0 columns come first, then all slice1 columns, etc).z-slibase_sm %sawrite 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)z-usetempzby 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 offz -nodmbaseaddbasedsort)rrr)z54D dataset to be used as voxelwise baseline regressorz -dsort %s)rrrrzgif 'dsort' option is used, this command will output additional results files excluding the 'dsort' filez -dsort_nodsz$output F-statistic for each stimulusz-foutz*output the R^2 statistic for each stimulusz-routzoutput 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.z-toutz_do NOT add FDR curve data to bucket datasets; FDR curves can take a long time if 'tout' is usedz-noFDRzndo NOT add baseline (null hypothesis) regressor betas to the 'rbeta_file' and/or 'obeta_file' output datasets.z-noboutaCread 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 filez-gltsym "%s" %s...a0output 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.z -Rbuck %sz+output dataset for REML variance parametersz-Rvar %sa>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.z -Rbeta %szoutput 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.z-Rglt %sz#ouput dataset for REML fitted modelz -Rfitts %sz7output dataset for REML residuals = data - fitted modelz -Rerrts %szadataset for REML residual, whitened using the estimated ARMA(1,1) correlation matrix of the noisez -Rwherr %szturn off most progress messagesz-quietzZturns on more progress messages, including memory usage progress reports at various stagesz-verbziWith potential issues flagged in the design matrix, an attempt will nevertheless be made to fit the modelz-GOFORITz3dataset for OLSQ st.dev. parameter (kind of boring)z-Ovar %sz1dataset for beta weights from the OLSQ estimationz -Obeta %sz6dataset for beta + statistics from the OLSQ estimationz -Obuck %sz3dataset for beta + statistics from 'gltsym' optionsz-Oglt %szdataset for OLSQ fitted modelz -Ofitts %sz0dataset for OLSQ residuals (data - fitted model)z -Oerrts %sN)0r0r1r2r r r3rorr7r=Zmatimr:r4r;r<rpZslibaseZ slibase_smZusetempr6rqZ dsort_nodsrBrCrDrEZnoboutrGZEitherr9r r*rAvar_file rbeta_fileglt_file fitts_file errts_file wherr_filequietZverbr8ovarobetaobuckogltofittsoerrtsrIrIrIrJrm^s          "      rmc@seZdZeddZeddZeddZeddZeddZeddZeddZ ed dZ ed dZ ed dZ ed dZ ed dZeddZeddZdS)RemlfitOutputSpeczDdataset for beta + statistics from the REML estimation (if generated)rz3dataset for REML variance parameters (if generated)z@dataset for beta weights from the REML estimation (if generated)zFoutput dataset for beta weights from the REML estimation (if generatedzoutput dataset for beta + statistics from the REML estimation, but ONLY for the GLTs added on the REMLfit command line itself via 'gltsym' (if generated)z2ouput dataset for REML fitted model (if generated)zEoutput dataset for REML residuals = data - fitted model (if generatedzpdataset for REML residual, whitened using the estimated ARMA(1,1) correlation matrix of the noise (if generated)z1dataset for OLSQ st.dev. parameter (if generated)z@dataset for beta weights from the OLSQ estimation (if generated)zEdataset for beta + statistics from the OLSQ estimation (if generated)zAdataset for beta + statistics from 'gltsym' options (if generatedz,dataset for OLSQ fitted model (if generated)z>dataset for OLSQ residuals = data - fitted model (if generatedN)r0r1r2r rArrrsrtrurvrwryrzr{r|r}r~rIrIrIrJr;s0    rcs6eZdZdZdZeZeZdfdd Z ddZ Z S) Remlfita|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() # doctest: +SKIP Z 3dREMLfitNcs|dkr g}tt|j|S)N)rQrr[)rSr\)rXrIrJr[}szRemlfit._parse_inputscCsN|jj}x<|jD]0}t|jj|rtjj|jj|||<qW|S)N)r`rakeysrrZrbrerf)rSrgkeyrIrIrJrhs  zRemlfit._list_outputs)N) r0r1r2rirjrmrkrr`r[rhrlrIrI)rXrJrcs rc@seZdZedddddZedddddZejedd d d dd Z ed dddZ ej dddZ ej dddZejddddddZdS)SynthesizeInputSpeczDRead the dataset output from 3dDeconvolve via the '-cbucket' option.z -cbucket %sFT)rrrrnz?Read the matrix output from 3dDeconvolve via the '-x1D' option.z -matrix %szselected columns to synthesize)rz -select %saA 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'.)rrrnZsynz*output dataset prefix name (default 'syn')z -prefix %s)Z name_templaterrz0Don't compute the output, just check the inputs.z-dry)rrz]TR to set in the output. The default value of TR is read from the header of the matrix file.z-TR %fZzeroZnbhrnonez -cenfill %szxDetermines how censored time points from the 3dDeconvolve run will be filled. Valid types are 'zero', 'nbhr' and 'none'.)rrN)r0r1r2r r@rorrGr selectrAr4dry_runr5ZTREnumZcenfillrIrIrIrJrs<  rc@s$eZdZdZdZeZeZddZ dS) SynthesizeaReads 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() # doctest: +SKIP Z 3dSynthesizecCsN|jj}x<|jD]0}t|jj|rtjj|jj|||<qW|S)N)r`rarrrZrbrerf)rSrgrrIrIrJrhs  zSynthesize._list_outputsN) r0r1r2rirjrrkrr`rhrIrIrIrJrs r)rirbbaserrrrrrr r r r Z external.duerrrrrrrrKrMrmrrrrrIrIrIrJ s0  d L^()3