All AFNI program `-help` files

This page auto-generated on Tue May 6 10:05:35 PM EDT 2025

AFNI program: 1dApar2mat
Usage: 1dApar2mat dx dy dz a1 a2 a3 sx sy sz hx hy hz * This program computes the affine transformation matrix from the set of 3dAllineate parameters. * The result is printed to stdout, and can be captured by Unix shell redirection (e.g., '|', '>', '>>', etc.). See the EXAMPLE, far below. * One use for 1dApar2mat is to take a set of parameters from '3dAllineate -1Dparam_save', alter them in some way, and re-compute the corresponding matrix. For example, compute the full affine transform with 12 parameters, but then omit the final 6 parameters to see what the 'pure' shift+rotation matrix looks like. * The 12 parameters are, in the order used on the 1dApar2mat command line (the same order as output by 3dAllineate): x-shift in mm y-shift in mm z-shift in mm z-angle (roll) in degrees (not radians!) x-angle (pitch) in degrees y-angle (yaw) in degrees x-scale unitless factor, in [0.10,10.0] y-scale unitless factor, in [0.10,10.0] z-scale unitless factor, in [0.10,10.0] y/x-shear unitless factor, in [-0.3333,0.3333] z/x-shear unitless factor, in [-0.3333,0.3333] z/y-shear unitless factor, in [-0.3333,0.3333] * Parameters omitted from the end of the command line get their default values (0 except for scales, which default to 1). * At least 1 parameter must be given, or you get this help message :) The minimum command line is 1dApar2mat 0 which will output the identity matrix. * Legal scale and shear factors have limited ranges, as described above. An input value outside the given range will be reset to the default value for that factor (1 or 0). * UNUSUAL SPECIAL CASES: If you used 3dAllineate with any of the options described under 'CHANGING THE ORDER OF MATRIX APPLICATION' or you used the '-EPI' option, then the order of parameters inside 3dAllineate will no longer be the same as the parameter order in 1dApar2mat. In such a situation, the matrix output by this program will NOT agree with that output by 3dAllineate for the same set of parameter numbers :( * EXAMPLE: 1dApar2mat 0 1 2 3 4 5 to get a rotation matrix with some shifts; the output is: # mat44 1dApar2mat 0 1 2 3 4 5 : 0.994511 0.058208 -0.086943 0.000000 -0.052208 0.996197 0.069756 1.000000 0.090673 -0.064834 0.993768 2.000000 If you wish to capture this matrix all on one line, you can combine various Unix shell and command tricks/tools, as in echo `1dApar2mat 0 1 2 3 4 5 | tail -3` > Fred.aff12.1D This 12-numbers-in-one-line is the format output by '-1Dmatrix_save' in 3dAllineate and 3dvolreg. * FANCY EXAMPLE: Tricksy command line stuff to compute the inverse of a matrix set fred = `1dApar2mat 0 0 0 3 4 5 1 1 1 0.2 0.1 0.2 | tail -3` cat_matvec `echo $fred | sed -e 's/ /,/g' -e 's/^/MATRIX('/`')' -I * ALSO SEE: Programs cat_matvec and 1dmatcalc for doing simple matrix arithmetic on such files. * OPTIONS: This program has no options. Love it or leave it :) * AUTHOR: Zhark the Most Affine and Sublime - April 2019

AFNI program: 1dAstrip
Usage: 1dAstrip < input > output This very simple program strips non-numeric characters from a file, so that it can be processed by other AFNI 1d programs. For example, if your input is x=3.6 y=21.6 z=14.2 then your output would be 3.6 21.6 14.2 * Non-numeric characters are replaced with blanks. * The letter 'e' is preserved if it is preceded or followed by a numeric character. This is to allow for numbers like '1.2e-3'. * Numeric characters, for the purpose of this program, are defined as the digits '0'..'9', and '.', '+', '-'. * The program is simple and can easily end up leaving undesired junk characters in the output. Sorry. * This help string is longer than the rest of the source code to this program!

AFNI program: 1dBandpass
Usage: 1dBandpass [options] fbot ftop infile ~1~ * infile is an AFNI *.1D file; each column is processed * fbot = lowest frequency in the passband, in Hz [can be 0 if you want to do a lowpass filter only,] but the mean and Nyquist freq are always removed ] * ftop = highest frequency in the passband (must be > fbot) [if ftop > Nyquist freq, then we have a highpass filter only] * You cannot construct a 'notch' filter with this program! * Output vectors appear on stdout; redirect as desired * Program will fail if fbot and ftop are too close for comfort * The actual FFT length used will be printed, and may be larger than the input time series length for the sake of efficiency. Options: ~1~ -dt dd = set time step to 'dd' sec [default = 1.0] -ort f.1D = Also orthogonalize input to columns in f.1D [only one '-ort' option is allowed] -nodetrend = Skip the quadratic detrending of the input -norm = Make output time series have L2 norm = 1 Example: ~1~ 1deval -num 1000 -expr 'gran(0,1)' > r1000.1D 1dBandpass 0.025 0.20 r1000.1D > f1000.1D 1dfft f1000.1D - | 1dplot -del 0.000977 -stdin -plabel 'Filtered |FFT|' Goal: ~1~ * Mostly to test the functions in thd_bandpass.c -- RWCox -- May 2009 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dBport
Usage: 1dBport [options] Creates a set of columns of sines and cosines for the purpose of bandpassing via regression (e.g., in 3dDeconvolve). Various option are given to specify the duration and structure of the time series to be created. Results are written to stdout, and usually should be redirected appropriately (cf. EXAMPLES, infra). The file produced could be used with the '-ortvec' option to 3dDeconvolve, for example. OPTIONS ------- -band fbot ftop = Specify lowest and highest frequencies in the passband. fbot can be 0 if you want to do a highpass filter only; on the other hand, if ftop > Nyquist frequency, then it's a lowpass filter only. ** This 'option' is actually mandatory! (At least once.) * For the un-enlightened, the Nyquist frequency is the highest frequency supported on the given grid, and is equal to 0.5/TR (units are Hz if TR is in s). * The lowest nonzero frequency supported on the grid is equal to 1/(N*TR), where N=number of time points. ** Multiple -band options can be used, if needed. If the bands overlap, regressors will NOT be duplicated. * That is, '-band 0.01 0.05 -band 0.03 0.08' is the same as using '-band 0.01 0.08'. ** Note that if fbot==0 and ftop>=Nyquist frequency, you get a 'complete' set of trig functions, meaning that using these in regression is effectively a 'no-pass' filter -- probably not what you want! ** It is legitimate to set fbot = ftop. ** The 0 frequency (fbot = 0) component is all 1, of course. But unless you use the '-quad' option, nothing generated herein will deal well with linear-ish or quadratic-ish trends, which fall below the lowest nonzero frequency representable in a full cycle on the grid: f_low = 1 / ( NT * TR ) where NT = number of time points. ** See the fourth EXAMPLE to learn how to use 3dDeconvolve to generate a file of polynomials for regression fun. -invert = After computing which frequency indexes correspond to the input band(s), invert the selection -- that is, output all those frequencies NOT selected by the -band option(s). See the fifth EXAMPLE. -nozero } Do NOT generate the 0 frequency (constant) component *OR } when fbot = 0; this has the effect of setting fbot to -noconst } 1/(N*TR), and is essentially a convenient way to say 'eliminate all oscillations below the ftop frequency'. -quad = Add regressors for linear and quadratic trends. (These will be the last columns in the output.) -input dataset } One of these options is used to specify the number of *OR* } time points to be created, as in 3dDeconvolve. -input1D 1Dfile } ** '-input' allow catenated datasets, as in 3dDeconvolve. *OR* } ** '-input1D' assumes TR=1 unless you use the '-TR' option. -nodata NT [TR] } ** One of these options is mandatory, to specify the length of the time series file to generate. -TR del = Set the time step to 'del' rather than use the one given in the input dataset (if any). ** If TR is not specified by the -input dataset or by -nodata or by -TR, the program will assume it is 1.0 s. -concat rname = As in 3dDeconvolve, used to specify the list of start indexes for concatenated runs. ** Also as in 3dDeconvolve, if the -input dataset is auto- catenated (by providing a list of more than one dataset), the run start list is automatically generated. Otherwise, this option is needed if more than one run is involved. EXAMPLES -------- The first example provides basis functions to filter out all frequency components from 0 to 0.25 Hz: 1dBport -nodata 100 1 -band 0 0.25 > highpass.1D The second example provides basis functions to filter out all frequency components from 0.25 Hz up to the Nyquist frequency: 1dBport -nodata 100 1 -band 0.25 666 > lowpass.1D The third example shows how to examine the results visually, for fun: 1dBport -nodata 100 1 -band 0.41 0.43 | 1dplot -stdin -thick The fourth example shows how to use 3dDeconvolve to generate a file of polynomial 'orts', in case you find yourself needing this ability someday (e.g., when stranded on a desert isle, with Gilligan, the Skipper, et al.): 3dDeconvolve -nodata 100 1 -polort 2 -x1D_stop -x1D stdout: | 1dcat stdin: > pol3.1D The fifth example shows how to use 1dBport to generate a set of regressors to eliminate all frequencies EXCEPT those in the selected range: 1dBport -nodata 100 1 -band 0.03 0.13 -nozero -invert | 1dplot -stdin In this example, the '-nozero' flag is used because the next step will be to 3dDeconvolve with '-polort 2' and '-ortvec' to get rid of the undesirable stuff. ETYMOLOGICAL NOTES ------------------ * The word 'ort' was coined by Andrzej Jesmanowicz, as a shorthand name for a timeseries to which you want to 'orthogonalize' your data. * 'Ort' actually IS an English word, and means 'a scrap of food left from a meal'. As far as I know, its only usage in modern English is in crossword puzzles, and in Scrabble. * For other meanings of 'ort', see http://en.wikipedia.org/wiki/Ort * Do not confuse 'ort' with 'Oort': http://en.wikipedia.org/wiki/Oort_cloud AUTHOR -- RWCox -- Jan 2012 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dcat
Usage: 1dcat [options] a.1D b.1D ... where each file a.1D, b.1D, etc. is a 1D file. In the simplest form, a 1D file is an ASCII file of numbers arranged in rows and columns. 1dcat takes as input one or more 1D files, and writes out a 1D file containing the side-by-side concatenation of all or a subset of the columns from the input files. * Output goes to stdout (the screen); redirect (e.g., '>') to save elsewhere. * All files MUST have the same number of rows! * Any header lines (i.e., lines that start with '#') will be lost. * For generic 1D file usage help and information, see '1dplot -help' ----------- TSV files: [Sep 2018] ----------- * 1dcat can now also read .tsv files, which are columns of values separated by tab characters (tsv = tab separated values). The first row of a .tsv file is a set of column labels. After the header row, each column is either all numbers, or is a column of strings. For example Col 1 Col 2 Col 3 3.2 7.2 Elvis 8.2 -1.2 Sinatra 6.66 33.3 20892 In this example, the column labels contain spaces, which are NOT separators; the only column separator used in a .tsv file is the tab character. The first and second columns are converted to number columns, since every value (after the label/header row) is a numeric string. The third column is stored as strings, since some of the entries are not valid numbers. * 1dcat can deal with a mix of .1D and .tsv files. The .tsv file header rows are NOT output by default, since .1D files don't have such headers. * The usual output from 1dcat is NOT a .tsv file - blanks are used for separators. You can use the '-tsvout' option to get TSV formatted output. * If you mix .1D and .tsv files, the number of data rows in each file must be the same. Since the header row in a .tsv file is NOT used here, the total number of lines in a .tsv file must be 1 more than the number of lines in a .1D file for the two files to match in this program. * The purpose of supporting .tsv files is for eventual compatibility with the BIDS format http://bids.neuroimaging.io - which uses .tsv files extensively to provide auxiliary information for (F)MRI datasets. * Column selectors (like '[0,3]') can be used on .tsv files, but row selectors (like '{0,3..5}') cannot be used on .tsv files - at this time :( * You can also select a column in a .tsv file by using the label at the top of of the column. A BIDS-related example: 1dcat sub-666_task-XXX_events.tsv'[onset,duration,trial_type,reaction_time]' A similar example, which outputs a list of the trial types in an imaging run: 1dcat sub-666_task-XXX_events.tsv'[trial_type]' | sort | uniq * Since .1D files don't have headers, the label method of column selection doesn't work with such inputs; you must use integer column selectors on .1D files. * NOTE WELL: The string 'N/A' or 'n/a' in a column that is otherwise numeric will be considered to be a number, and will be replaced on input with the mean of the "true" numbers in the column -- there is no concept of missing data in an AFNI .1D file. ++ If you don't like this, well ... too bad for you. * NOTE WELL: 1dcat now also allows comma separated value (.csv) files. These are treated the same as .tsv files, with a header line, et cetera. -------- OPTIONS: -------- -tsvout = Output in a TSV (.tsv) format, where the values in each row are separated by tabs, not blanks. Also, a header line will be provided, as TSV files require. -csvout = Output in a CSV (.csv) format, where the values in each row are separated by commas, not blanks. Also, a header line will be provided, as CSV files require. -nonconst = Columns that are identically constant should be omitted from the output. -nonfixed = Keep only columns that are marked as 'free' in the 3dAllineate header from '-1Dparam_save'. If there is no such header, all columns are kept. * NOTE: -nconst and -nonfixed don't have any effect on .tsv/.csv files, and the use of these options has NOT been tested at all when the inputs are mixture of .tsv/.csv and .1D files. -form FORM = Format of the numbers to be output. You can also substitute -form FORM with shortcuts such as -i, -f, or -c. For help on -form's usage, and its shortcut versions see ccalc's help for the option of the same name. -stack = Stack the columns of the resultant matrix in the output. You can't use '-stack' with .tsv/.csv files :( -sel SEL = Apply the same column/row selection string to all filenames on the command line. For example: 1dcat -sel '[0,2]' f1.1D f2.1D is the same as: 1dcat f1.1D'[1,2]' f2.1D'[1,2]' The advantage of the option is that it allows wildcard use in file specification so that you can run something like: 1dcat -sel '[0,2]' f?.1D -OKempty: Exit quietly when encountering an empty file on disk. Note that if the file is poorly formatted, it might be considered empty. EXAMPLE: -------- Input file 1: 1 2 3 4 Input file 2: 5 6 7 8 1dcat data1.1D data2.1D > catout.1D Output file: 1 5 2 6 3 7 4 8 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dCorrelate
Usage: 1dCorrelate [options] 1Dfile 1Dfile ... ------ * Each input 1D column is a collection of data points. * The correlation coefficient between each column pair is computed, along with its confidence interval (via a bias-corrected bootstrap procedure). * The minimum sensible column length is 7. * At least 2 columns are needed [in 1 or more .1D files]. * If there are N input columns, there will be N*(N-1)/2 output rows. * Output appears on stdout; redirect ('>' or '>>') as needed. * Only one correlation method can be used in one run of this program. * This program is basically the basterd offspring of program 1ddot. * Also see http://en.wikipedia.org/wiki/Confidence_interval ------- Methods [actually, only the first letter is needed to choose a method] ------- [and the case doesn't matter: '-P' and '-p' both = '-Pearson'] -Pearson = Pearson correlation [the default method] -Spearman = Spearman (rank) correlation [more robust vs. outliers] -Quadrant = Quadrant (binarized) correlation [most robust, but weaker] -Ktaub = Kendall's tau_b 'correlation' [popular somewhere, maybe] ------------- Other Options [these options cannot be abbreviated!] ------------- -nboot B = Set the number of bootstrap replicates to 'B'. * The default value of B is 4000. * A larger number will give somewhat more accurate confidence intervals, at the cost of more CPU time. -alpha A = Set the 2-sided confidence interval width to '100-A' percent. * The default value of A is 5, giving the 2.5..97.5% interval. * The smallest allowed A is 1 (0.5%..99.5%) and the largest allowed value of A is 20 (10%..90%). * If you are interested assessing if the 'p-value' of a correlation is smaller than 5% (say), then you should use '-alpha 10' and see if the confidence interval includes 0. -block = Attempt to allow for serial correlation in the data by doing *OR* variable-length block resampling, rather than completely -blk random resampling as in the usual bootstrap. * You should NOT do this unless you believe that serial correlation (along each column) is present and significant. * Block resampling requires at least 20 data points in each input column. Fewer than 20 will turn off this option. ----- Notes ----- * For each pair of columns, the output include the correlation value as directly calculated, plus the bias-corrected bootstrap value, and the desired (100-A)% confidence interval [also via bootstrap]. * The primary purpose of this program is to provide an easy way to get the bootstrap confidence intervals, since people almost always seem to use the asymptotic normal theory to decide if a correlation is 'significant', and this often seems misleading to me [especially for short columns]. * Bootstrapping confidence intervals for the inverse correlations matrix (i.e., partial correlations) would be interesting -- anyone out there need this ability? ------------- Sample output [command was '1dCorrelate -alpha 10 A2.1D B2.1D'] ------------- # Pearson correlation [n=12 #col=2] # Name Name Value BiasCorr 5.00% 95.00% N: 5.00% N:95.00% # -------- -------- -------- -------- -------- -------- -------- -------- A2.1D[0] B2.1D[0] +0.57254 +0.57225 -0.03826 +0.86306 +0.10265 +0.83353 * Bias correction of the correlation had little effect; this is very common. ++ To be clear, the bootstrap bias correction is to allow for potential bias in the statistical estimate of correlation when the sample size is small. ++ It cannot correct for biases that result from faulty data (or faulty assumptions about the data). * The correlation is NOT significant at this level, since the CI (confidence interval) includes 0 in its range. * For the Pearson method ONLY, the last two columns ('N:', as above) also show the widely used asymptotic normal theory confidence interval. As in the example, the bootstrap interval is often (but not always) wider than the theoretical interval. * In the example, the normal theory might indicate that the correlation is significant (less than a 5% chance that the CI includes 0), but the bootstrap CI shows that is not a reasonable statistical conclusion. ++ The principal reason that I wrote this program was to make it easy to check if the normal (Gaussian) theory for correlation significance testing is reasonable in any given case -- for small samples, it often is NOT reasonable! * Using the same data with the '-S' option gives the table below, again indicating that there is no significant correlation between the columns (note also the lack of the 'N:' results for Spearman correlation): # Spearman correlation [n=12 #col=2] # Name Name Value BiasCorr 5.00% 95.00% # -------- -------- -------- -------- -------- -------- A2.1D[0] B2.1D[0] +0.46154 +0.42756 -0.23063 +0.86078 ------------- SAMPLE SCRIPT ------------- This script generates random data and correlates it until it is statistically significant at some level (default=2%). Then it plots the data that looks correlated. The point is to show what purely random stuff that appears correlated can look like. (Like most AFNI scripts, this is written in tcsh, not bash.) #!/bin/tcsh set npt = 20 set alp = 2 foreach fred ( `count_afni -dig 1 1 1000` ) 1dcat jrandom1D:${npt},2 > qqq.1D set aabb = ( `1dCorrelate -spearman -alpha $alp qqq.1D | grep qqq.1D | colrm 1 42` ) set ab = `ccalc -form rint "1000 * $aabb[1] * $aabb[2]"` echo $fred $ab if( $ab > 1 )then 1dplot -one -noline -x qqq.1D'[0]' -xaxis -1:1:20:5 -yaxis -1:1:20:5 \ -DAFNI_1DPLOT_BOXSIZE=0.012 \ -plabel "N=$npt trial#=$fred \alpha=${alp}% => r\in[$aabb[1],$aabb[2]]" \ qqq.1D'[1]' break endif end \rm qqq.1D ---------------------------------------------------------------------- *** Written by RWCox (AKA Zhark the Mad Correlator) -- 19 May 2011 *** ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: @1dDiffMag
Usage: @1dDiffMag file.1D * Computes a magnitude estimate of the first differences of a 1D file. * Differences are computed down each column. * The result -- a single number -- is on stdout. * But (I hear you say), what IS the result? * For each column, the standard deviation of the first differences is computed. * The final result is the square-root of the sum of the squares of these stdev values.

AFNI program: 1ddot
Usage: 1ddot [options] 1Dfile 1Dfile ... * Prints out correlation matrix of the 1D files and their inverse correlation matrix. * Output appears on stdout. * Program 1dCorrelate does something similar-ish. Options: -one = Make 1st vector be all 1's. -dem = Remove mean from all vectors (conflicts with '-one') -cov = Compute with covariance matrix instead of correlation -inn = Computed with inner product matrix instead -rank = Compute Spearman rank correlation instead (also implies '-terse') -terse= Output only the correlation or covariance matrix and without any of the garnish. -okzero= Do not quit if a vector is all zeros. The correlation matrix will have 0 where NaNs ought to go. Expect rubbish in the inverse matrices if all zero vectors exist. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dDW_Grad_o_Mat++
++ Program version: 2.2 Simple function to manipulate DW gradient vector files, b-value files, and b- or g-matrices. Let: g_i be one of Ng spatial gradients in three dimensions; |g_i| = 1, and the g-matrix is G_{ij} = g_i * g_j (i.e., dyad of gradients, without b-value included); and the DW-scaled b-matrix is B_{ij} = b * g_i * g_j. **This new version of the function** will replace the original/older version (1dDW_Grad_o_Mat). The new has similar functionality, but improved defaults: + it does not average b=0 volumes together by default; + it does not remove top b=0 line from top by default; + output has same scaling as input by default (i.e., by bval or not); and a switch is used to turn *off* scaling, for unit magn output (which is cleverly concealed under the name '-unit_mag_out'). Wherefore, you ask? Well, times change, and people change. The above functionality is still available, but each just requires selection with command line switches. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * As of right now, one can input: + 3 rows of gradients (as output from dcm2nii, for example); + 3 columns of gradients; + 6 columns of g- or b-matrices, in `diagonal-first' (-> matA) order: Bxx, Byy, Bzz, Bxy, Bxz, Byz, which is used in 3dDWItoDT, for example; + 6 columns of g- or b-matrices, in `row-first' (-> matT) order: Bxx, 2*Bxy, 2*Bxz, Byy, 2*Byz, Bzz, which is output by TORTOISE, for example; + when specifying input file, one can use the brackets '{ }' in order to specify a subset of rows to keep (NB: probably can't use this grad-filter when reading in row-data right now). During processing, one can: + flip the sign of any of the x-, y- or z-components, which may be necessary to do to make the scanned data and tracking work happily together; + filter out all `zero' rows of recorded reference images, THOUGH this is not really recommended. One can then output: + 3 columns of gradients; + 6 columns of g- or b-matrices, in 'diagonal-first' order; + 6 columns of g- or b-matrices, in 'row-first' order; + as well as including a column of b-values (such as used in, e.g., DSI-Studio); + as well as explicitly include a row of zeros at the top; * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + RUNNING: 1dDW_Grad_o_Mat++ \ { -in_row_vec | -in_col_vec | \ -in_col_matA | -in_col_matT } INFILE \ { -flip_x | -flip_y | -flip_z | -no_flip } \ { -out_row_vec | -out_col_vec | \ -out_col_matA | -out_col_matT } OUTFILE \ { -in_bvals BVAL_FILE } \ { -out_col_bval } \ { -out_row_bval_sep BB | -out_col_bval_sep BB } \ { -unit_mag_out } \ { -bref_mean_top } \ { -bmax_ref THRESH } \ { -put_zeros_top } \ where: (one of the following formats of input must be given): -in_row_vec INFILE :input file of 3 rows of gradients (e.g., dcm2nii-format output). -in_col_vec INFILE :input file of 3 columns of gradients. -in_col_matA INFILE :input file of 6 columns of b- or g-matrix in 'A(FNI)' `diagonal first'-format. (See above.) -in_col_matT INFILE :input file of 6 columns of b- or g-matrix in 'T(ORTOISE)' `row first'-format. (See above.) (one of the following formats of output must be given): -out_row_vec OUTFILE :output file of 3 rows of gradients. -out_col_vec OUTFILE :output file of 3 columns of gradients. -out_col_matA OUTFILE :output file of 6 columns of b- or g-matrix in 'A(FNI)' `diagonal first'-format. (See above.) -out_col_matT OUTFILE :output file of 6 cols of b- or g-matrix in 'T(ORTOISE)' `row first'-format. (See above.) (and any of the following options may be used): -in_bvals BVAL_FILE :BVAL_FILE is a file of b-values, either a single row (such as the 'bval' file generated by dcm2nii) or a single column of numbers. Must have the same number of entries as the number of grad vectors or matrices. -out_col_bval :switch to put a column of the bvalues as the first column in the output data. -out_row_bval_sep BB :output a file BB of bvalues in a single row. -out_col_bval_sep BB :output a file BB of bvalues in a single column. -unit_mag_out :switch so that each vector/matrix from the INFILE is scaled to either unit or zero magnitude. (Supplementary input bvalues would be ignored in the output matrix/vector, but not in the output bvalues themselves.) The default behavior of the function is to leave the output scaled however it is input (while also applying any input BVAL_FILE). -flip_x :change sign of first column of gradients (or of the x-component parts of the matrix) -flip_y :change sign of second column of gradients (or of the y-component parts of the matrix) -flip_z :change sign of third column of gradients (or of the z-component parts of the matrix) -no_flip :don't change any gradient/matrix signs. This is an extraneous switch, as the default is to not flip any signs (this is mainly used for some scripting convenience -check_abs_min VVV :By default, this program checks input matrix formats for consistency (having positive semi- definite diagonal matrix elements). It will fail if those don't occur. However, sometimes there is just a tiny values <0, like a rounding error; you can specify to push throughfor negative diagonal elements with magnitude <VVV, with those values getting replaced by zero. Be judicious with this power! (E.g., maybe VVV ~ 0.0001 might be OK... but if you get looots of negatives, then you really, really need to check your data for badness. (and the follow options are probably mainly extraneous, nowadays) -bref_mean_top :when averaging the reference X 'b0' values (the default behavior), have the mean of the X values be represented in the top row; default behavior is to have nothing representing the b0 information in the top row (for historical functionality reasons). NB: if your reference 'b0' actually has b>0, you might not want to average the b0 refs together, because their images could have differing contrast if the same reference vector wasn't used for each. -put_zeros_top :whatever the output format is, add a row at the top with all zeros. -bmax_ref THRESH :THRESH is a scalar number below which b-values (in BVAL_IN) are considered `zero' or reference. Sometimes, for the reference images, the scanner has a value like b=5 s/mm^2, instead of strictly b=0 strictly. One can still flag such values as being associated with a reference image and trim it out, using, for the example case here, '-bmax_ref 5.1'. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * EXAMPLES # An example of type-conversion from a TORTOISE-style matrix to column # gradients (if the matT file has bweights, so will the grad values): 1dDW_Grad_o_Mat++ \ -in_col_matT BMTXT_TORT.txt \ -out_col_vec GRAD.dat # An example of filtering (note the different styles of parentheses # for the column- and row-type files) and type-conversion (to an # AFNI-style matrix that should have the bvalue weights afterwards): 1dDW_Grad_o_Mat++ \ -in_col_vec GRADS_col.dat'{0..10,12..30}' \ -in_bvals BVALS_row.dat'[0..10,12..30]' \ -out_col_matA FILT_matA.dat # An example of filtering *without* type-conversion. Here, note # the '-unit_mag_out' flag is used so that the output row-vec does # not carry the bvalue weight with it; it does not affect the output # bval file. As Levon might say, the '-unit_mag_out' option acts to # 'Take a load off bvecs, take a load for free; # Take a load off bvecs, and you put the load right on bvals only.' # This example might be useful for working with dcm2nii* output: 1dDW_Grad_o_Mat++ \ -in_row_vec ap.bvec'[0..10,12..30]' \ -in_bvals ap.bval'[0..10,12..30]' \ -out_row_vec FILT_ap.bvec \ -out_row_bval_sep FILT_ap.bval \ -unit_mag_out * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ___________________________________________________________________________

AFNI program: 1deval
Usage: 1deval [options] -expr 'expression' Evaluates an expression that may include columns of data from one or more text files and writes the result to stdout. ** Only a single column can be used for each input 1D file. ** * Simple multiple column operations (e.g., addition, scaling) can be done with program 1dmatcalc. * Any single letter from a-z can be used as the independent variable in the expression. * Unless specified using the '[]' notation (cf. 1dplot -help), only the first column of an input 1D file is used, and other columns are ignored. * Only one column of output will be produced -- if you want to calculate a multi-column output file, you'll have to run 1deval separately for each column, and then glue the results together using program 1dcat. [However, see the 1dcat example combined with the '-1D:' option, infra.] Options: -------- -del d = Use 'd' as the step for a single undetermined variable in the expression [default = 1.0] SYNONYMS: '-dx' and '-dt' -start s = Start at value 's' for a single undetermined variable in the expression [default = 0.0] That is, for the indeterminate variable in the expression (if any), the i-th value will be s+i*d for i=0, 1, .... SYNONYMS: '-xzero' and '-tzero' -num n = Evaluate the expression 'n' times. If -num is not used, then the length of an input time series is used. If there are no time series input, then -num is required. -a q.1D = Read time series file q.1D and assign it to the symbol 'a' (as in 3dcalc). * Letters 'a' to 'z' may be used as symbols. * You can use the filename 'stdin:' to indicate that the data for 1 symbol comes from standard input: 1dTsort q.1D stdout: | 1deval -a stdin: -expr 'sqrt(a)' | 1dplot stdin: -a=NUMBER = set the symbol 'a' to a fixed numerical value rather than a variable value from a 1D file. * Letters 'a' to 'z' may be used as symbols. * You can't assign the same symbol twice! -index i.1D = Read index column from file i.1D and write it out as 1st column of output. This option is useful when working with surface data. -1D: = Write output in the form of a single '1D:' string suitable for input on the command line of another program. [-1D: is incompatible with the -index option!] [This won't work if the output string is very long,] [since the maximum command line length is limited. ] Examples: --------- * 't' is the indeterminate variable in the expression below: 1deval -expr 'sin(2*PI*t)' -del 0.01 -num 101 > sin.1D * Multiply two columns of data (no indeterminate variable): 1deval -expr 'a*b' -a fred.1D -b ethel.1D > ab.1D * Compute and plot the F-statistic corresponding to p=0.001 for varying degrees of freedom given by the indeterminate variable 'n': 1deval -start 10 -num 90 -expr 'fift_p2t(0.001,n,2*n)' | 1dplot -xzero 10 -stdin * Compute the square root of some numbers given in '1D:' form directly on the command line: 1deval -x '1D: 1 4 9 16' -expr 'sqrt(x)' Examples using '-1D:' as the output format: ------------------------------------------- The examples use the shell backquote `xxx` operation, where the command inside the backquotes is executed, its stdout is captured into a string, and placed back on the command line. When you have mastered this idea, you have taken another step towards becoming a Jedi AFNI Master! 1dplot `1deval -1D: -num 71 -expr 'cos(t/2)*exp(-t/19)'` 1dcat `1deval -1D: -num 100 -expr 'cos(t/5)'` \ `1deval -1D: -num 100 -expr 'sin(t/5)'` > sincos.1D 3dTfitter -quiet -prefix - \ -RHS `1deval -1D: -num 30 -expr 'cos(t)*exp(-t/7)'` \ -LHS `1deval -1D: -num 30 -expr 'cos(t)'` \ `1deval -1D: -num 30 -expr 'sin(t)'` Notes: ------ * Program 3dcalc operates on 3D and 3D+time datasets in a similar way. * Program ccalc can be used to evaluate a single numeric expression. * If I had any sense, THIS program would have been called 1dcalc! * For generic 1D file usage help, see '1dplot -help' * For help with expression format, see '3dcalc -help', or type 'help' when using ccalc in interactive mode. * 1deval only produces a single column of output. 3dcalc can be tricked into doing multi-column 1D format output by treating a 1D file as a 3D dataset and auto-transposing it with \' For example: 3dcalc -a '1D: 3 4 5 | 1 2 3'\' -expr 'cbrt(a)' -prefix - The input has 2 'columns' and so does the output. Note that the 1D 'file' is transposed on input to 3dcalc! This is essential, or 3dcalc will not treat the 1D file as a dataset, and the results will be very different. Recall that when a 1D file is read as an 3D AFNI dataset, the row direction corresponds to the sub-brick (e.g., time) direction, and the column direction corresponds to the voxel direction. A Dastardly Trick: ------------------ If you use some other letter than 'z' as the indeterminate variable in the calculation, and if 'z' is not assigned to any input 1D file, then 'z' in the expression will be the previous value computed. This trick can be used to create 1 point recursions, as in the following command for creating a AR(1) noise time series: 1deval -num 500 -expr 'gran(0,1)+(i-i)+0.7*z' > g07.1D Note the use of '(i-i)' to intoduce the variable 'i' so that 'z' would be used as the previous output value, rather than as the indeterminate variable generated by '-del' and '-start'. The initial value of 'z' is 0 (for the first evaluation). * [02 Apr 2010] You can set the initial value of 'z' to a nonzero value by using the environment variable AFNI_1DEVAL_ZZERO, as in 1deval -DAFNI_1DEVAL_ZZERO=1 -num 10 -expr 'i+z' -- RW Cox -- ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dfft
Usage: 1dfft [options] infile outfile where infile is an AFNI *.1D file (ASCII list of numbers arranged in columns); outfile will be a similar file, with the absolute value of the FFT of the input columns. The length of the file will be 1+(FFT length)/2. Options: -ignore sss = Skip the first 'sss' lines in the input file. [default = no skipping] -use uuu = Use only 'uuu' lines of the input file. [default = use them all, Frank] -nfft nnn = Set FFT length to 'nnn'. [default = length of data (# of lines used)] -tocx = Save Re and Im parts of transform in 2 columns. -fromcx = Convert 2 column complex input into 1 column real output. [-fromcx will not work if the original] [data FFT length was an odd number! :(] -hilbert = When -fromcx is used, the inverse FFT will do the Hilbert transform instead. -nodetrend = Skip the detrending of the input. Nota Bene: * Each input time series has any quadratic trend of the form 'a+b*t+c*t*t' removed before the FFT, where 't' is the line number. * The FFT length can be any positive even integer, but the Fast Fourier Transform algorithm will be slower if any prime factors of the FFT length are large (say > 997) Unless you are applying this program to VERY long files, this slowdown will probably not be appreciable. * If the FFT length is longer than the file length, the data is zero-padded to make up the difference. * Do NOT call the output of this program the Power Spectrum! That is something else entirely. * If 'outfile' is '-' (or missing), the output appears on stdout. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dFlagMotion
Usage: 1dFlagMotion [options] MotionParamsFile Produces an list of time points that have more than a user specified amount of motion relative to the previous time point. Options: -MaxTrans maximum translation allowed in any direction [defaults to 1.5mm] -MaxRot maximum rotation allowed in any direction [defaults to 1.25 degrees] ** The input file must have EXACTLY 6 columns of input, in the order: roll pitch yaw delta-SI delta-LR delta-AP (angles in degrees first, then translations in mm) ** The program does NOT accept column '[...]' selectors on the input file name, or comments in the file itself. As a palliative, if the input file name is '-', then the input numbers are read from stdin, so you could do something like the following: 1dcat mfile.1D'[1..6]' | 1dFlagMotion - e.g., to work with the output from 3dvolreg's '-dfile' option (where the first column is just the time index). ** The output is in a 1D format, with comments on '#' comment lines, and the list of points exceeding the motion bounds listed being intercalated on normal (non-comment) lines. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dgenARMA11
Program to generate an ARMA(1,1) time series, for simulation studies. Results are written to stdout. Usage: 1dgenARMA11 [options] Options: ======== -num N } These equivalent options specify the length of the time -len N } series vector to generate. -nvec M = The number of time series vectors to generate; if this option is not given, defaults to 1. -a a = Specify ARMA(1,1) parameters 'a'. -b b = Specify ARMA(1,1) parameter 'b' directly. -lam lam = Specify ARMA(1,1) parameter 'b' indirectly. -sig ss = Set standard deviation of results [default=1]. -norm = Normalize time series so sum of squares is 1. -seed dd = Set random number seed. * The correlation coefficient r(k) of noise samples k units apart in time, for k >= 1, is given by r(k) = lam * a^(k-1) where lam = (b+a)(1+a*b)/(1+2*a*b+b*b) (N.B.: lam=a when b=0 -- AR(1) noise has r(k)=a^k for k >= 0) (N.B.: lam=b when a=0 -- MA(1) noise has r(k)=b for k=1, r(k)=0 for k>1) * lam can be bigger or smaller than a, depending on the sign of b: b > 0 means lam > a; b < 0 means lam < a. * What I call (a,b) here is sometimes called (p,q) in the ARMA literature. * For a noise model which is the sum of AR(1) and white noise, 0 < lam < a (i.e., a > 0 and -a < b < 0 ). -CORcut cc = The exact ARMA(1,1) correlation matrix (for a != 0) has no non-zero entries. The calculations in this program set correlations below a cutoff to zero. The default cutoff is 0.00010, but can be altered with this option. The usual reason to use this option is to test the sensitivity of the results to the cutoff. ----------------------------- A restricted ARMA(3,1) model: ----------------------------- Skip the '-a', '-b', and '-lam' options, and use a model with 3 roots -arma31 a r theta vrat where the roots are z = a, z = r*exp(I*theta), z = r*exp(-I*theta) and vrat = s^2/(s^2+w^2) [so 0 < vrat < 1], where s = variance of the pure AR(3) component and w = variance of extra white noise added to the AR(3) process -- this is the 'restricted' ARMA(3,1). If the data has given TR, and you want a frequency of f Hz, in the noise model, then theta = 2 * PI * TR * f. If theta > PI, then you are modeling noise beyond the Nyquist frequency and the gods (and this program) won't be happy. # csh syntax for 'set' variable assignment commands set nt = 500 set tr = 1 set df = `ccalc "1/($nt*$tr)"` set f1 = 0.10 set t1 = `ccalc "2*PI*$tr*$f1"` 1dgenARMA11 -nvec 500 -len $nt -arma31 0.8 0.9 $t1 0.9 -CORcut 0.0001 \ | 1dfft -nodetrend stdin: > qqq.1D 3dTstat -mean -prefix stdout: qqq.1D \ | 1dplot -stdin -num 201 -dt $df -xlabel 'frequency' -ylabel '|FFT|' --------------------------------------------------------------------------- A similar option is now available for a restricted ARMA(5,1) model: -arma51 a r1 theta1 r2 theta2 vrat where now the roots are z = a z = r1*exp(I*theta1) z = r1*exp(-I*theta1) z = r2*exp(I*theta2) z = r2*exp(-I*theta2) This model allows the simulation of two separate frequencies in the 'noise'. --------------------------------------------------------------------------- Author: RWCox [for his own demented and deranged purposes] Examples: 1dgenARMA11 -num 200 -a .8 -lam 0.7 | 1dplot -stdin 1dgenARMA11 -num 2000 -a .8 -lam 0.7 | 1dfft -nodetrend stdin: stdout: | 1dplot -stdin

AFNI program: 1dgrayplot
Usage: 1dgrayplot [options] tsfile Graphs the columns of a *.1D type time series file to the screen, sort of like 1dplot, but in grayscale. Options: -install = Install a new X11 colormap (for X11 PseudoColor) -ignore nn = Skip first 'nn' rows in the input file [default = 0] -flip = Plot x and y axes interchanged. [default: data columns plotted DOWN the screen] -sep = Separate scales for each column. -use mm = Plot 'mm' points [default: all of them] -ps = Don't draw plot in a window; instead, write it to stdout in PostScript format. N.B.: If you view this result in 'gv', you should turn 'anti-alias' off, and switch to landscape mode. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dMarry
Usage: 1dMarry [options] file1 file2 ... Joins together 2 (or more) ragged-right .1D files, for use with 3dDeconvolve -stim_times_AM2. **_OR_** Breaks up 1 married file into 2 (or more) single-valued files. OPTIONS: ======= -sep abc == Use the first character (e.g., 'a') as the separator between values 1 and 2, the second character (e.g., 'b') as the separator between values 2 and 3, etc. * These characters CANNOT be a blank, a tab, a digit, or a non-printable control character! * Default separator string is '*,' which will result in output similar to '3*4,5,6' -divorce == Instead of marrying the files, assume that file1 is already a married file: split time*value*value... tuples into separate files, and name them in the pattern 'file2_A.1D' 'file2_B.1D' et cetera. If not divorcing, the 'married' file is written to stdout, and probably should be captured using a redirection such as '>'. NOTES: ===== * You cannot use column [...] or row {...} selectors on ragged-right .1D files, so don't even think about trying! * The maximum number of values that can be married is 26. (No polygamy or polyandry jokes here, please.) * For debugging purposes, with '-divorce', if 'file2' is '-', then all the divorcees are written directly to stdout. -- RWCox -- written hastily in March 2007 -- hope I don't repent -- modified to deal with multiple marriages -- December 2008 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dmatcalc
Usage: 1dmatcalc [-verb] expression Evaluate a space delimited RPN matrix-valued expression: * The operations are on a stack, each element of which is a real-valued matrix. * N.B.: This is a computer-science stack of separate matrices. If you want to join two matrices in separate files into one 'stacked' matrix, then you must use program 1dcat to join them as columns, or the system program cat to join them as rows. * You can also save matrices by name in an internal buffer using the '=NAME' operation and then retrieve them later using just the same NAME. * You can read and write matrices from files stored in ASCII columns (.1D format) using the &read and &write operations. * The following 5 operations, input as a single string, '&read(V.1D) &read(U.1D) &transp * &write(VUT.1D)' - reads matrices V and U from disk (separately), - transposes U (on top of the stack) into U', - multiplies V and U' (the two matrices on top of the stack), - and writes matrix VU' out (the matrix left on the stack by '*'). * Calculations are carried out in single precision ('float'). * Operations mostly contain characters such as '&' and '*' that are special to Unix shells, so you'll probably need to put the arguments to this program in 'single quotes'. * You can use '%' or '@' in place of the '&' character, if you wish. STACK OPERATIONS ----------------- number == push scalar value (1x1 matrix) on stack; a number starts with a digit or a minus sign =NAME == save a copy matrix on top of stack as 'NAME' NAME == push a copy of NAME-ed matrix onto top of stack; names start with an alphabetic character &clear == erase all named matrices (to save memory); does not affect the stack at all &purge == erase the stack; does not affect named matrices &read(FF) == read ASCII (.1D) file onto top of stack from file 'FF' &read4x4Xform(FF) == Similar to &read(FF), except that it expects data for a 12-parameter spatial affine transform. FF can contain 12x1, 1x12, 16x1, 1x16, 3x4, or 4x4 values. The read operation loads the data into a 4x4 matrix r11 r12 r13 r14 r21 r22 r23 r24 r31 r32 r33 r34 0.0 0.0 0.0 1.0 This option was added to simplify the combination of linear spatial transformations. However, you are better off using cat_matvec for that purpose. &write(FF) == write top matrix to ASCII file to file 'FF'; if 'FF' == '-', writes to stdout &transp == replace top matrix with its transpose &ident(N) == push square identity matrix of order N onto stack N is an fixed integer, OR &R to indicate the row dimension of the current top matrix, OR &C to indicate the column dimension of the current top matrix, OR =X to indicate the (1,1) element of the matrix named X &Psinv == replace top matrix with its pseudo-inverse [computed via SVD, not via inv(A'*A)*A'] &Sqrt == replace top matrix with its square root [computed via Denman & Beavers iteration] N.B.: not all real matrices have real square roots, and &Sqrt will fail if you push it N.B.: the matrix must be square! &Pproj == replace top matrix with the projection onto its column space; Input=A; Output = A*Psinv(A) N.B.: result P is symmetric and P*P=P &Qproj == replace top matrix with the projection onto the orthogonal complement of its column space Input=A; Output=I-Pproj(A) * == replace top 2 matrices with their product; OR stack = [ ... C A B ] (where B = top) goes to &mult stack = [ ... C AB ] if either of the top matrices is a 1x1 scalar, then the result is the scalar multiplication of the other matrix; otherwise, matrices must conform + OR &add == replace top 2 matrices with sum A+B - OR &sub == replace top 2 matrices with difference A-B &dup == push duplicate of top matrix onto stack &pop == discard top matrix &swap == swap top two matrices (A <-> B) &Hglue == glue top two matrices together horizontally: stack = [ ... C A B ] goes to stack = [ ... C A|B ] this is like what program 1dcat does. &Vglue == glue top two matrices together vertically: stack = [ ... C A B ] goes to A stack = [ ... C - ] B this is like what program cat does. SIMPLE EXAMPLES --------------- * Multiply each element of an input 1D file by a constant factor and write to disk. 1dmatcalc "&read(in.1D) 3.1416 * &write(out.1D)" * Subtract two 1D files 1dmatcalc "&read(a.1D) &read(b.1D) - &write(stdout:)"

AFNI program: 1dNLfit
Program to fit a model to a vector of data. The model is given by a symbolic expression, with parameters to be estimated. Usage: 1dNLfit OPTIONS Options: [all but '-meth' are actually mandatory] -------- -expr eee = The expression for the fit. It must contain one symbol from 'a' to 'z' which is marked as the independent variable by option '-indvar', and at least one more symbol which is a parameter to be estimated. ++ Expressions use the same syntax as 3dcalc, ccalc, and 1deval. ++ Note: expressions and symbols are not case sensitive. -indvar c d = Indicates which variable in '-expr' is the independent variable. All other symbols are parameters, which are either fixed (constants) or variables to be estimated. ++ Then, read the values of the independent variable from 1D file 'd' (only the first column will be used). ++ If the independent variable has a constant step size, you can input it via with 'd' replaced by a string like '1D: 100%0:2.1' which creates an array with 100 value, starting at 0, then adding 2.1 for each step: 0 2.1 4.2 6.3 8.4 ... -param ppp = Set fixed value or estimating range for a particular symbol. ++ For a fixed value, 'ppp' takes the form 'a=3.14', where the first letter is the symbol name, which must be followed by an '=', then followed by a constant expression. This expression can be symbolic, as in 'a=cbrt(3)'. ++ For a parameter to be estimated, 'ppp' takes the form of two constant expressions separated by a ':', as in 'q=-sqrt(2):sqrt(2)'. ++ All symbols in '-expr' must have a corresponding '-param' option, EXCEPT for the '-indvar' symbol (which will be set by its data file). -depdata v = Read the values of the dependent variable (to be fitted to '-expr') from 1D file 'v'. ++ File 'v' must have the same number of rows as file 'd' from the '-indvar' option! ++ File 'v' can have more than one column; each will be fitted separately to the expression. -meth m = Set the method for fitting: '1' for L1, '2' for L2. (The default method is L2, which is usually better.) Example: -------- Create a sin wave corrupted by logistic noise, to file ss.1D. Create a cos wave similarly, to file cc.1D. Put these files together into a 2 column file sc.1D. Fit both columns to a 3 parameter model and write the fits to file ff.1D. Plot the data and the fit together, for fun and profit(?). 1deval -expr 'sin(2*x)+lran(0.3)' -del 0.1 -num 100 > ss.1D 1deval -expr 'cos(2*x)+lran(0.3)' -del 0.1 -num 100 > cc.1D 1dcat ss.1D cc.1D > sc.1D ; \rm ss.1D cc.1D 1dNLfit -depdata sc.1D -indvar x '1D: 100%0:0.1' -expr 'a*sin(b*x)+c*cos(b*x)' \ -param a=-2:2 -param b=1:3 -param c=-2:2 > ff.1D 1dplot -one -del 0.1 -ynames sin:data cos:data sin:fit cos:fit - sc.1D ff.1D Notes: ------ * PLOT YOUR RESULTS! There is no guarantee that you'll get a good fit. * This program is not particularly efficient, so using it on a large scale (e.g., for lots of columns, or in a shell loop) will be slow. * The results (fitted time series models) are written to stdout, and should be saved by '>' redirection (as in the example). The first few lines of the output from the example are: # 1dNLfit output (meth=L2) # expr = a*sin(b*x)+c*cos(b*x) # Fitted parameters: # A = 1.0828 0.12786 # B = 1.9681 2.0208 # C = 0.16905 1.0102 # ----------- ----------- 0.16905 1.0102 0.37753 1.0153 0.57142 0.97907 * Coded by Zhark the Well-Fitted - during Snowzilla 2016.

AFNI program: 1dnorm
Usage: 1dnorm [options] infile outfile where infile is an AFNI *.1D file (ASCII list of numbers arranged in columns); outfile will be a similar file, with each column being L_2 normalized (sum of squares = 1). * If 'infile' is '-', it will be read from stdin. * If 'outfile' is '-', it will be written to stdout. Options: -------- -norm1 = Normalize so sum of absolute values is 1 (L_1 norm) -normx = So that max absolute value is 1 (L_infinity norm) -demean = Subtract each column's mean before normalizing -demed = Subtract each column's median before normalizing [-demean and -demed are mutually exclusive!] ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dplot
++ 1dplot: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: RWC et al. Usage: 1dplot [options] tsfile ... Graphs the columns of a *.1D time series file to the X11 screen, or to an image file (.jpg or .png). ** This is the original C-language plotting program in AFNI, first created ** ** in 1999 (by RW Cox), built on routines he first wrote in the 1980s. ** ** Also see the much newer and similar Python-language program 1dplot.py ** ** (created by PA Taylor in 2018), which can produce nicer looking graphs. ** ------- OPTIONS ------- -install = Install a new X11 colormap. -sep = Plot each column in a separate sub-graph. -one = Plot all columns together in one big graph. [default = -sep] -sepscl = Plot each column in a separate sub-graph and allow each sub-graph to have a different y-scale. -sepscl is meaningless with -one! -noline = Don't plot the connecting lines (also implies '-box'). -NOLINE = Same as '-noline', but will not try to plot values outside the rectangular box that contains the graph axes. -box = Plot a small 'box' at each data point, in addition to the lines connecting the points. * The box size can be set via the environment variable AFNI_1DPLOT_BOXSIZE; the value is a fraction of the overall plot size. The standard box size is 0.006. Example with a bigger box: 1dplot -DAFNI_1DPLOT_BOXSIZE=0.01 -box A.1D * The box shapes are different for different time series columns. At present, there is no way to control which shape is used for what column (unless you modify the source code, that is). * If you want some data columns plotted with boxes and some with lines, don't use '-box'. Instead, use option '-dashed'. * You can set environment variable AFNI_1DPLOT_RANBOX to YES to get the '-noline' boxes plotted in a pseudo-random order, so that one particular color doesn't dominate just because it is last in the plotting order; for example: 1dplot -DAFNI_1DPLOT_RANBOX=YES -one -x X.1D -noline Y1.1D Y2.1D Y3.1D -hist = Plot graphs in histogram style (i.e., vertical boxes). * Histograms can be generated from 3D or 1D files using program 3dhistog; for example 3dhistog -nbin 50 -notitle -min 0 -max .04 err.1D > eh.1D 1dplot -hist -x eh.1D'[0]' -xlabel err -ylabel hist eh.1D'[1]' or, for something a little more fun looking: 1dplot -one -hist -dashed 1:2 -x eh.1D'[0]' \ -xlabel err -ylabel hist eh.1D'[1]' eh.1D'[1]' ** The '-norm' options below can be useful for plotting data with different value ranges on top of each other via '-one': -norm2 = Independently scale each time series plotted to have L_2 norm = 1 (sum of squares). -normx = Independently scale each time series plotted to have max absolute value = 1 (L_infinity norm). -norm1 = Independently scale each time series plotted to have max sum of absolute values = 1 (L_1 norm). -demean = This option will remove the mean from each time series (before normalizing). The combination '-demean -normx -one' can be useful when plotting disparate data together. * If you use '-demean' twice, you will get linear detrending. * Et cetera (e.g,, 4 times gives you cubic detrending.) -x X.1D = Use for X axis the data in X.1D. Note that X.1D should have one column of the same length as the columns in tsfile. ** Coupled with '-box -noline', you can use '-x' to make a scatter plot, as in graphing file A1.1D along the x-axis and file A2.1D along the y-axis: 1dplot -box -noline -x A1.1D -xlabel A1 -ylabel A2 A2.1D ** '-x' will override -dx and -xzero; -xaxis still works -xl10 X.1D = Use log10(X.1D) as the X axis. -xmulti X1.1D X2.1D ... This new [Oct 2013] option allows you to plot different columns from the data with different values along the x-axis. You can supply one or more 1D files after the '-xmulti' option. The columns from these files are catenated, and then the first xmulti column is used as as x-axis values for the first data column plotted, the second xmulti column gives the x-axis values for the second data column plotted, and so on. ** The command line arguments after '-xmulti' are taken as 1D filenames to read, until an argument starts with a '-' character -- this would either be another option, or just a single '-' to separate the xmulti 1D files from the data files to be plotted. ** If you don't provide enough xmulti columns for all the data files, the last xmulti column will be reused. ** Useless but fun example: 1deval -num 100 -expr '(i-i)+z+gran(0,6)' > X1.1D 1deval -num 100 -expr '(i-i)+z+gran(0,6)' > X2.1D 1dplot -one -box -xmulti X1.1D X2.1D - X2.1D X1.1D -dx xx = Spacing between points on the x-axis is 'xx' [default = 1] SYNONYMS: '-dt' and '-del' -xzero zz = Initial x coordinate is 'zz' [default = 0] SYNONYMS: '-tzero' and '-start' -nopush = Don't 'push' axes ranges outwards. -ignore nn = Skip first 'nn' rows in the input file [default = 0] -use mm = Plot 'mm' points [default = all of them] -xlabel aa = Put string 'aa' below the x-axis [default = no axis label] -ylabel aa = Put string 'aa' to the left of the y-axis [default = no axis label] -plabel pp = Put string 'pp' atop the plot. Some characters, such as '_' have special formatting effects. You can escape that with ''. For example: echo 2 4.5 -1 | 1dplot -plabel 'test_underscore' -stdin versus echo 2 4.5 -1 | 1dplot -plabel 'test\_underscore' -stdin -title pp = Same as -plabel, but only works with -ps/-png/-jpg/-pnm options. -wintitle pp = Set string 'pp' as the title of the frame containing the plot. Default is based on input. -naked = Do NOT plot axes or labels, just the graph(s). You might want to use '-nopush' with '-naked'. -aspect A = Set the width-to-height ratio of the plot region to 'A'. Default value is 1.3. Larger 'A' means a wider graph. -stdin = Don't read from tsfile; instead, read from stdin and plot it. You cannot combine input from stdin and tsfile(s). If you want to do so, use program 1dcat first. -ps = Don't draw plot in a window; instead, write it to stdout in PostScript format. * If you view the result in 'gv', you should turn 'anti-alias' off, and switch to landscape mode. * You can use the 'gs' program to convert PostScript to other formats; for example, a .bmp file: 1dplot -ps ~/data/verbal/cosall.1D | gs -r100 -sOutputFile=fred.bmp -sDEVICE=bmp256 -q -dBATCH - * 1dplot is built on some line drawing software written a long time ago in a galaxy far away, which is why PostScript output was a natural thing to do -- I doubt that anyone uses this feature in these decadent modern times. -jpg fname } = Render plot to an image and save to a file named -jpeg fname } = 'fname', in JPEG mode or in PNG mode or in PNM mode. -png fname } = The default image width is 1024 pixels; to change -pnm fname } = this value to 2048 pixels (say), do setenv AFNI_1DPLOT_IMSIZE 2048 before running 1dplot, or add -DAFNI_1DPLOT_IMSIZE=2048 to the 1dplot command line. Widths over 4096 might start to look odd in some cases. The largest allowed size is 8192 pixels. * PNG files created by 1dplot will be smaller than JPEG, and are compressed without loss. * PNG output requires that the netpbm program pnmtopng be installed somewhere in your PATH. This program is NOT supplied with AFNI, but must be installed separately: https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/index.html * PNM output files are not compressed, and are manipulable by the netpbm package: http://netpbm.sourceforge.net/ Otherwise, this format isn't very useful anymore. * There will be small drawing differences between the X11 (interactive) plotting window and the images saved by these options -- or by the interactive button. These differences arise from the use of different line drawing functions for X11 windows and for off-screen bitmap images. -pngs size fname } = convenience options equivalent to -jpgs size fname } = -DAFNI_1DPLOT_IMSIZE=size followed by -jpegs size fname} = -png fname (or -jpg or -jpeg or -pnm) -pnms size fname } = The largest allowed size is 8192 pixels. -ytran 'expr' = Transform the data along the y-axis by applying the expression to each input value. For example: -ytran 'log10(z)' will take log10 of each input time series value before plotting it. * The expression should have one variable (any letter from a-z will do), which stands for the time series data to be transformed. * An expression such as 'sqrt(x*x+i)' will use 'x' for the time series value and use 'i' for the time index (starting at 0) -- in this way, you can use time-dependent transformations, if needed. * This transformation applies to all input time series (at present, there is no way to transform different time series in distinct ways inside 1dplot). * '-ytran' is applied BEFORE the various '-norm' options. -xtran 'expr' = Similar, but for the x-axis. ** Applies to '-xmulti' , '-x' , or the default x-axis. -xaxis b:t:n:m = Set the x-axis to run from value 'b' to value 't', with 'n' major divisions and 'm' minor tic marks per major division. For example: -xaxis 0:100:5:20 Setting 'n' to 0 means no tic marks or labels. * You can set 'b' to be greater than 't', to have the x-coordinate decrease from left-to-right. * This is the only way to have this effect in 1dplot. * In particular, '-dx' with a negative value will not work! -yaxis b:t:n:m = Similar to above, for the y-axis. These options override the normal autoscaling of their respective axes. -ynames a b ... = Use the strings 'a', 'b', etc., as labels to the right of the graphs, corresponding to each input column. These strings CANNOT start with the '-' character. N.B.: Each separate string after '-ynames' is taken to be a new label, until the end of the command line or until some string starts with a '-'. In particular, This means you CANNOT do something like 1dplot -ynames a b c file.1D since the input filename 'file.1D' will be used as a label string, not a filename. Instead, you must put another option between the end of the '-ynames' label list, OR you can put a single '-' at the end of the label list to signal its end: 1dplot -ynames a b c - file.1D TSV files: When plotting a TSV file, where the first row is the set of column labels, you can use this Unix trick to put the column labels here: -ynames `head -1 file.tsv` The 'head' command copies just the first line of the file to stdout, and the backquotes `...` capture stdout and put it onto the command line. * You might need to put a single '-' after this option to prevent the problem alluded to above. In any case, it can't hurt to use '-' as an option after '-ynames'. * If any of the TSV labels start with the '-' character, peculiar and unpleasant things might transpire. -volreg = Makes the 'ynames' be the same as the 6 labels used in plug_volreg for Roll, Pitch, Yaw, I-S, R-L, and A-P movements, in that order. -thick = Each time you give this, it makes the line thickness used for plotting a little larger. [An alternative to using '-DAFNI_1DPLOT_THIK=...'] -THICK = Twice the power of '-thick' at no extra cost!! -dashed codes = Plot dashed lines between data points. The 'codes' are a colon-separated list of dash values, which can be 1 (solid), 2 (longer dashes), or 3 (shorter dashes). 0 can be used to indicate that a time series is to be plotted without lines but with boxes instead. ** Example: '-dashed 1:2:3' means to plot the first time series with solid lines, the second with long dashes, and the third with short dashes. -Dname=val = Set environment variable 'name' to 'val' for this run of the program only: 1dplot -DAFNI_1DPLOT_THIK=0.01 -DAFNI_1DPLOT_COLOR_01=blue '1D:3 4 5 3 1 0' You may also select a subset of columns to display using a tsfile specification like 'fred.1D[0,3,5]', indicating that columns #0, #3, and #5 will be the only ones plotted. For more details on this selection scheme, see the output of '3dcalc -help'. Example: graphing a 'dfile' output by 3dvolreg, when TR=5: 1dplot -volreg -dx 5 -xlabel Time 'dfile[1..6]' You can also input more than one tsfile, in which case the files will all be plotted. However, if the files have different column lengths, the shortest one will rule. The colors for the line graphs cycle between black, red, green, and blue. You can alter these colors by setting Unix environment variables of the form AFNI_1DPLOT_COLOR_xx -- cf. README.environment. You can alter the thickness of the lines by setting the variable AFNI_1DPLOT_THIK to a value between 0.00 and 0.05 -- the units are fractions of the page size; of course, you can also use the options '-thick' or '-THICK' if you prefer. ---------------- RENDERING METHOD ---------------- On 30 Apr 2012, a new method of rendering the 1dplot graph into an X11 window was introduced -- this method uses 'anti-aliasing' to produce smoother-looking lines and characters. If you want the old coarser-looking rendering method, set environment variable AFNI_1DPLOT_RENDEROLD to YES. The program always uses the new rendering method when drawing to a JPEG or PNG or PNM file (which is not and never has been just a screen capture). There is no way to disable the new rendering method for image-file saves. ------ LABELS ------ Besides normal alphabetic text, the various labels can include some special characters, using TeX-like escapes starting with '\'. Also, the '^' and '_' characters denote super- and sub-scripts, respectively. The following command shows many of the escapes: 1deval -num 100 -expr 'J0(t/4)' | 1dplot -stdin -thick \ -xlabel '\alpha\beta\gamma\delta\epsilon\zeta\eta^{\oplus\dagger}\times c' \ -ylabel 'Bessel Function \green J_0(t/4)' \ -plabel '\Upsilon\Phi\Chi\Psi\Omega\red\leftrightarrow\blue\partial^{2}f/\partial x^2' TIMESERIES (1D) INPUT --------------------- A timeseries file is in the form of a 1D or 2D table of ASCII numbers; for example: 3 5 7 2 4 6 0 3 3 7 2 9 This example has 4 rows and 3 columns. Each column is considered as a timeseries in AFNI. The convention is to store this type of data in a filename ending in '.1D'. ** COLUMN SELECTION WITH [] ** When specifying a timeseries file to an command-line AFNI program, you can select a subset of columns using the '[...]' notation: 'fred.1D[5]' ==> use only column #5 'fred.1D[5,9,17]' ==> use columns #5, #9, and #17 'fred.1D[5..8]' ==> use columns #5, #6, #7, and #8 'fred.1D[5..13(2)]' ==> use columns #5, #7, #9, #11, and #13 Column indices start at 0. You can use the character '$' to indicate the last column in a 1D file; for example, you can select every third column in a 1D file by using the selection list 'fred.1D[0..$(3)]' ==> use columns #0, #3, #6, #9, .... ** ROW SELECTION WITH {} ** Similarly, you select a subset of the rows using the '{...}' notation: 'fred.1D{0..$(2)}' ==> use rows #0, #2, #4, .... You can also use both notations together, as in 'fred.1D[1,3]{1..$(2)}' ==> columns #1 and #3; rows #1, #3, #5, .... ** DIRECT INPUT OF DATA ON THE COMMAND LINE WITH 1D: ** You can also input a 1D time series 'dataset' directly on the command line, without an external file. The 'filename' for such input has the general format '1D:n_1@val_1,n_2@val_2,n_3@val_3,...' where each 'n_i' is an integer and each 'val_i' is a float. For example -a '1D:5@0,10@1,5@0,10@1,5@0' specifies that variable 'a' be assigned to a 1D time series of 35, alternating in blocks between values 0 and value 1. * Spaces or commas can be used to separate values. * A '|' character can be used to start a new input "line": Try 1dplot '1D: 3 4 3 5 | 3 5 4 3' ** TRANSPOSITION WITH \' ** Finally, you can force most AFNI programs to transpose a 1D file on input by appending a single ' character at the end of the filename. N.B.: Since the ' character is also special to the shell, you'll probably have to put a \ character before it. Examples: 1dplot '1D: 3 2 3 4 | 2 3 4 3' and 1dplot '1D: 3 2 3 4 | 2 3 4 3'\' When you have reached this level of understanding, you are ready to take the AFNI Jedi Master test. I won't insult you by telling you where to find this examination. TAB SEPARATED VALUE (.tsv) FILES [Sep 2018] ------------------------------------------- These files are used in BIDS http://bids.neuroimaging.io and AFNI programs can read these in a few places. The format of a .tsv file is a set of columns, where the values in each row are separated by tab characters -- spaces are NOT separators. Each element is string, some of which are numeric (e.g. 3.1416). The first row of a .tsv file is a set of strings which are column descriptors (separated by tabs, of course). For the most part, the following data in each column are exclusively numeric or exclusively strings. Strings can contain blanks/spaces since only tabs are used to separate values. A .tsv file can be read in most places where a .1D file is read. However, columns (after the header row) that are not purely numeric will be ignored, since the internal usage of .1D data in AFNI is numeric. Thus, you can do something like 1dplot -nopush -sepscl sub-10506_task-pamenc_events.tsv and you will get a plot of all the numeric columns in this BIDS file. Column selection '[]' can be done, using numbers to specify columns or using the column labels in the .tsv file. N.B.: The string 'N/A' or 'n/a' in a column that is otherwise numeric will be considered to be a number, and will be replaced on input with the mean of the "true" numbers in the column -- there is no concept of missing data in an AFNI .1D file. ++ If you don't like this, well ... too bad for you. Program 1dcat has special knowledge of .tsv files, and will cat (sideways - along rows) .tsv and .1D files together. It also has an option to write the output in .tsv format. For example, to get the 'onset', 'duration', and 'trial_type' columns out of a BIDS task .tsv file, a command like this could be used: 1dcat sub-10506_task-pamenc_events.tsv'[onset,duration,trial_type]' Note that the column headers are lost in this output, but could be kept if the 1dcat '-tsvout' option were used. In reverse, a numeric .1D file can be converted to .tsv format by a command like: 1dcat -tsvout Fred.1D In this case, since a the data for .1D file doesn't have headers for its columns, 1dcat will invent some column names. At this time, other programs don't 'know' much about .tsv files, and will ignore the header row and non-numeric columns when reading a .tsv file. in place of a .1D file. -------------- MARKING BLOCKS (e.g., censored time points) -------------- The following options let you mark blocks along the x-axis, by drawing colored vertical boxes over the standard white background. * The intended use is to mark blocks of time points that are censored out of an analysis, which is why the options are the same as those in 3dDeconvolve -- but you can mark blocks for any reason, of course. * These options don't do anything when the '-x' option is used to alter the x-axis spacings. * To see what the various color markings look like, try this silly example: 1deval -num 100 -expr 'lran(2)' > zz.1D 1dplot -thick -censor_RGB red -CENSORTR 3-8 \ -censor_RGB green -CENSORTR 11-16 \ -censor_RGB blue -CENSORTR 22-27 \ -censor_RGB yellow -CENSORTR 34-39 \ -censor_RGB violet -CENSORTR 45-50 \ -censor_RGB pink -CENSORTR 55-60 \ -censor_RGB gray -CENSORTR 65-70 \ -censor_RGB #2cf -CENSORTR 75-80 \ -plabel 'red green blue yellow violet pink gray #2cf' zz.1D & -censor_RGB clr = set the color used for the marking to 'clr', which can be one of the strings below: red green blue yellow violet pink gray (OR grey) * OR 'clr' can be in the form '#xyz' or '#xxyyzz', where 'x', 'y', and 'z' are hexadecimal digits -- for example, '#2cf' is sort of a cyan color. * OR 'clr' can be in the form 'rgbi:rf/gf/bf' where each color intensity (rf, gf, bf) is a number between 0.0 and 1.0 -- e.g., white is 'rgbi:1.0/1.0/1.0'. Since the background is white, dark colors don't look good here, and will obscure the graphs; for example, pink is defined here as 'rgbi:1.0/0.5/0.5'. * The default color is (a rather pale) yellow. * You can use '-censor_RGB' more than once. The color most recently specified previous on the command line is what will be used with the '-censor' and '-CENSORTR' options. This allows you to mark different blocks with different colors (e.g., if they were censored for different reasons). * The feature of allowing multiple '-censor_RGB' options means that you must put this option BEFORE the relevant '-censor' and/or '-CENSORTR' options. Otherwise, you'll get the default yellow color! -censor cname = cname is the filename of censor .1D time series * This is a file of 1s and 0s, indicating which time points are to be un-marked (1) and which are to be marked (0). * Please note that only one '-censor' option can be used, for compatibility with 3dDeconvolve. * The option below may be simpler to use! (And can be used multiple times.) -CENSORTR clist = clist is a list of strings that specify time indexes to be marked in the graph(s). Each string is of one of the following forms: 37 => mark global time index #37 2:37 => mark time index #37 in run #2 37..47 => mark global time indexes #37-47 37-47 => same as above *:0-2 => mark time indexes #0-2 in all runs 2:37..47 => mark time indexes #37-47 in run #2 * Time indexes within each run start at 0. * Run indexes start at 1 (just be to confusing). * Multiple -CENSORTR options may be used, or multiple -CENSORTR strings can be given at once, separated by spaces or commas. * Each argument on the command line after '-CENSORTR' is treated as a censoring string, until an argument starts with a '-' or an alphabetic character, or it contains the substring '1D'. This means that if you want to plot a file named '9zork.xyz', you may have to do this: 1dplot -CENSORTR 3-7 18-22 - 9zork.xyz The stand-alone '-' will stop the processing of censor strings; otherwise, the '9zork.xyz' string, since it doesn't start with a letter, would be treated as a censoring string, which you would find 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. -concat rname = rname is the filename for list of concatenated runs * 'rname' can be in the format '1D: 0 100 200 300' which indicates 4 runs, the first of which starts at time index=0, second at index=100, and so on. * The ONLY function of '-concat' is for use with '-CENSORTR', to be compatible with 3dDeconvolve [e.g., for plotting motion parameters from] [3dvolreg -1Dfile, where you've cat-enated] [the 1D files from separate runs into one ] [long file for plotting with this program.] -rbox x1 y1 x2 y2 color1 color2 = Draw a rectangular box with corners (x1,y1) to (x2,y2), in color1, with an outline in color2. Colors are names, such as 'green'. [This option lets you make bar] [charts, *if* you care enough.] -Rbox x1 y1 x2 y2 y3 color1 color2 = As above, with an extra horizontal line at y3. -line x1 y1 x2 y2 color dashcode = Draw one line segment. Another fun fun example: 1dplot -censor_RGB #ffa -CENSORTR '0-99' \ `1deval -1D: -num 61 -dx 0.3 -expr 'J0(x)'` which illustrates the use of 'censoring' to mark the entire graph background in pale yellow '#ffa', and also illustrates the use of the '-1D:' option in 1deval to produce output that can be used directly on the command line, via the backquote `...` operator. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dplot.py
OVERVIEW ~1~ This program is for making images to visualize columns of numbers from "1D" text files. It is based heavily on RWCox's 1dplot program, just using Python (particularly matplotlib). To use this program, Python version >=2.7 is required, as well as matplotlib modules (someday numpy might be needed, as well). This program takes very few required options-- mainly, file names and an output prefix-- but it allows the user to control/add many features, such as axis labels, titles, colors, adding in censor information, plotting summary boxplots and more. ++ constructed by PA Taylor (NIMH, NIH, USA). # ========================================================================= COMMAND OPTIONS ~1~ -help, -h :see helpfile -infiles II :(req) one or more file names of text files. Each column in this file will be treated as a separate time series for plotting (i.e., as 'y-values'). One can use AFNI-style column '{ }' and row '[ ]' selectors. One or more files may be entered, but they must all be of equal length. -yfiles YY :exactly the same behavior as "-infiles ..", just another option name for it that might be more consistent with other options. -prefix PP :output filename or prefix; if no file extension for an image is included in 'PP', one will be added from a list. At present, OK file types to output should include: .jpg, .png, .tif, .pdf, .svg ... but note that the kinds of image files you may output may be limited by packages (or lack thereof) installed on your own computer. Default output image type is .jpg -boxplot_on :a fun feature to show an small, additional boxplot adjacent to each time series. The plot is a standard Python boxplot of that times series's values. The box shows the 25-75%ile range (interquartile range, IQR); the median value highlighted by a white line; whiskers stretch to 1.5*IQR; circles show outliers. When using this option and censoring, by default both a boxplot of data "before censoring" (BC) and "after censoring (AC) will be added after. See '-bplot_view ...' about current opts to change that, if desired. -bplot_view BC_ONLY | AC_ONLY :when using '-boxplot_on' and censoring, by default the plotter will put one boxplot of data "before censoring" (BC) and after censoring (AC). To show *only* the uncensored one, use this option and keyword. -margin_off :use this option to have the plot frame fill the figure window completely; thus, no labels, frame, titles or other parts of the 'normal' image outside the plot window will be visible. Tick lines will still be present, living their best lives. This is probably only useful/recommended/tested for plots with a single panel. -scale SCA1 SCA2 SCA3 ... :provide a list of scales to apply to the y-values. These will be applied multiplicatively to the y-values; there should either be 1 (applied to all time series) or the same number as the time series (in the same order as those were entered). The scale values are also applied to the censor_hline values, but *not* to the "-yaxis ..." range(s). Note that there are a couple keywords that can be used instead of SCA* values: SCALE_TO_HLINE: each input time series is vertically scaled so that its censor_hline -> 1. That is, each time point is divided by the censor_hline value. When using this, a visually pleasing yaxis range might be 0:3. SCALE_TO_MAX: each input time series is vertically scaled so that its max value -> 1. That is, each time point is divided by the max value. When using this, a visually pleasing yaxis range might be 0:1.1. -yfiles_pm YP :one or more file names of text files. Each column in this file will be treated as a separate time series for plotting a plus/minus colorized range for an associated yfile/infile line. The number of files input with YP must exactly match that of either '-infiles ..' or '-yfiles ..'. The color will match the line color, but at greatly reduced opacity. -ylim_use_pm :by default, if not '-yaxis ..' opt is used, the ylim range each subplot comes from (slightly expanded) bounds of the min and max yvalue in each. But if '-yfiles_pm ..' is used, you can use this option to expand those limits by the min and max of the extra error-bounded space. -xfile XX :one way to input x-values explicitly: as a "1D" file XX, a containing a single file of numbers. If no xfile is entered, then a list of integers is created, 0..N-1, based on the length of the "-infiles ..". -xvals START STOP STEP :an alternative means for entering abscissa values: one can provide exactly 3 numbers, the start (inclusive) the stop (exclusive) and the steps to take, following Python conventions-- that is, numbers are generated [START,STOP) in stepsizes of STEP. -yaxis YMIN1:YMAX1 YMIN2:YMAX2 YMIN3:YMAX3 ... :optional range for each "infile" y-axis; note the use of a colon to designate the min/max of the range. One can also specify just the min (e.g., "YMIN:") or just the max (e.g., ":YMAX"). The final number of y-axis values or pairs *must* match the total number of columns of data from infiles; a placeholder could just be ":". Without specifying a range, one is calculated automatically from the min and max of the dsets themselves. The order of ylabels should match the order of infiles. -ylabels YL1 YL2 YL3 ... :optional text labels for each "infile" column; the final number of ylabels *must* match the total number of columns of data from infiles. The order of ylabels should match the order of infiles. These labels are plotted vertically along the y-axis of the plot. * For 1D files output by 3dvolreg, one can automatically provide the 6 associated ylabels by providing the keyword 'VOLREG' (and this counts as 6 labels). * For 1D files output by '3dAllineate -1Dparam_save ..', if you are using just the 6 rigid body parameters, you can automatically provide the 6 associated ylabels by providing the keyword 'ALLINPAR6' (and this counts as 6 labels). If using the 6 rigid body parameters and 3 scaling, you can use the keyword 'ALLINPAR9' (which counts as 9 labels). If using all 12 affine parameters, you can use the keyword 'ALLINPAR12' (which counts as 9 labels). -ylabels_maxlen MM :y-axis labels can get long; this opt allows you to have them wrap into multiple rows, each of length <=MM. At the moment, this wrapping is done with some "logic" that tries to be helpful (e.g., split at underscores where possible), as long as that helpfulness doesn't increase line numbers a lot. The value entered here will apply to all y-axis labels in the plot. -legend_on :turn on the plotting of a legend in the plot(s). Legend will not be shown in the boxplot panels, if using. -legend_labels LL1 LL2 LL3 ... :optional legend labels, if using '-legend_on' to show a legend. If no arguments are provided for this option, then the labels will be the arguments to '-infiles ..' (or '-yfiles ..'). If arguments ARE input, then they must match the number of '-infiles ..' (or '-yfiles ..'). -legend_locs LOC1 LOC2 LOC3 ... :optional legend locations, if using '-legend_on' to show a legend. If no arguments are provided for this option, then the locations will be the ones picked by Python (reasonable starting point) If arguments ARE input, then they must match the number of '-infiles ..' (or '-yfiles ..'). Valid entries are strings recognizable by matplotlib's plt.legend()'s "loc" opt; this includes: 'best', 'right', 'upper right', 'lower right', 'center right', etc. Note that if you use a two-word argument here, you MUST put it in quotes (or, as a special treat, you can combine it with an underscore, and it will be parsed correctly. So, valid values of LOC* could be: left 'lower left' upper_center -xlabel XL :optional text labels for the abscissa/x-axis. Only one may be entered, and it will *only* be displayed on the bottom panel of the output plot. Using labels is good practice!! -title TT :optional title for the set of plots, placed above the top- most subplot -reverse_order :optional switch; by default, the entered time series are plotted top to bottom according to the order they were entered (i.e., first- listed plot at the top). This option reverses that order (to first-listed plot at the bottom), in order to match with 1dplot's behavior. -sepscl :make each graph have its own y-range, determined by slightly padding its min and max values. By default, the separate plots all have the same y-range, which is determined by taking the min-of-mins and max-of- maxes, and padding slightly outward. -one_graph :plot multiple infiles in a single subplot (default is to put each one in a new subplot). -dpi DDD :choose the output image's DPI. The default value is 150. -figsize FX FY :choose the output image's dimensions (units are inches). The default width is 10; the default height is 0.5 + N*0.75, where 'N' is the number of infile columns. -fontsize FS :change image fontsize; default is 10. -fontfamily FF :change font-family used; default is the luvly monospace. -fontstyles FSS :add in a fontname; should match with chosen font-family; default is whatever Python has on your system for the given family. Whether your prescribed font gets used depends on what is installed on your comp. -colors C1 C2 C3 ... :you can decide what color(s) to cycle through in plots (enter one or more); if there are more infile columns than entered colors, the program just keeps cycling through the list. By default, if only 1 infile column is given, the plotline will be black; when more than one infile column is given, a default palette of 10 colors, chosen for their mutual-distinguishable-ness, will be cycled through. One of the colors can also be a decimal in range [0.0, 1.0], which will correspond to grayscale in range [black, white], respectively. -patches RL1 RL2 RL3 ... :when viewing data from multiple runs that have been processing+concatenated, knowing where they start/stop can be useful. This option helps with that, by alternating patches of the background slightly between white and light gray. The user enters any appropriate number of run lengths, and the background patch for the duration of the first is white, then light gray, etc. (to *start* with light gray, one can have '0' be the first RL value). -censor_trs CS1 CS2 CS3 ... :specify time points where censoring has occurred (e.g., due to a motion or outlier criterion). With this option, the values are entered using AFNI index notation, such as '0..3,8,25,99..$'. Note that if you use special characters like the '$', then the given string must be enclosed on quotes. One or more string can be entered, and results are simply combined (as well as if censor files are entered-- see the '-censor_files ..' opt). In order to highlight censored points, a translucent background color will be added to all plots of width 1. -censor_files CF1 CF2 CF3 ... :specify time points where censoring has occurred (e.g., due to a motion or outlier criterion). With this option, the values are entered as 1D files, columns where 0 indicates censoring at that [i]th time point, and 1 indicates *no* censoring there. One or more file can be entered, and results are simply combined (as well as if censor strings are entered-- see the '-censor_str ..' opt). In order to highlight censored points, a translucent background color will be added to all plots of width 1. -censor_hline CH1 CH2 CH3 ... :one can add a dotted horizontal line to the plot, with the intention that it represents the relevant threshold (for example, motion limit or outlier fraction limit). One can specify more than one hline: if one line is entered, it will be applied to each plot; if more than one hline is entered, there must be the same number of values as infile columns. Ummm, it is also assumed that all censor hline values are >=0; if negative, it will be a problem-- ask if this is a problem! A value of 'NONE' can also be input, to be a placeholder in a list, when some subplots have censor_hline values and others don't. -censor_RGB COL :choose the color of the censoring background; from the command line, users enter a string, which could be: + 3 space-separated floats in range [0, 1], of RGB values + 4 space-separated floats in range [0, 1], of RGBA values + 1 string of a valid matplotlib color + 1 string of a valid matplotlib color and 1 floats in range [0, 1], which is an alpha opacity value. (default is: '1 0.7 0.7'). -bkgd_color BC :change the background color outside of the plot windows. Default is the Python color: 0.9. EXAMPLES ~1~ 1) Plot Euclidean norm (enorm) profile, with the censor limit and related file of censoring: 1dplot.py \ -sepscl \ -boxplot_on \ -infiles motion_sub-10506_enorm.1D \ -censor_files motion_sub-10506_censor.1D \ -censor_hline 0.2 \ -title "Motion censoring" \ -ylabels enorm \ -xlabel "vols" \ -title "Motion censoring" \ -prefix mot_cen_plot.jpg 2) Plot the 6 solid body parameters from 3dvolreg, along with the useful composite 'enorm' and outlier time series: 1dplot.py \ -sepscl \ -boxplot_on \ -reverse_order \ -infiles dfile_rall.1D \ motion_sub-10506_enorm.1D \ outcount_rall.1D \ -ylabels VOLREG enorm outliers \ -xlabel "vols" \ -title "Motion and outlier plots" \ -prefix mot_outlier_plot.png 3) Use labels and locations to plot 3dhistog output (there will be some minor whining about failing to process comment label *.1D files, but won't cause any problems for plot); here, legend labels will be the args after '-yfiles ..' (with the part in square brackets, but without the quotes): 1dplot.py \ -xfile HOUT_A.1D'[0]' \ -yfiles HOUT_A.1D'[1]' HOUT_B.1D'[1]' \ -prefix img_histog.png \ -colors blue 0.6 \ -boxplot_on \ -legend_on 4) Same as #3, but using some additional opts to control legends. Here, am using 2 different formats of providing the legend locations in each separate subplot, just for fun: 1dplot.py \ -xfile HOUT_A.1D'[0]' \ -yfiles HOUT_A.1D'[1]' HOUT_B.1D'[1]' \ -prefix img_histog.png \ -colors blue 0.6 \ -boxplot_on \ -legend_on \ -legend_locs upper_right "lower left" \ -legend_labels A B

AFNI program: 1dRplot
Usage: ------ 1dRplot is a program for plotting a 1D file Options in alphabetical order: ------------------------------ -addavg: Add line at average of column -col.color COL1 [COL2 ...]: Colors for each column in -input. COL? are integers for now. -col.grp 1Dfile or Rexp: integer labels defining column grouping -col.line.type LT1 [LT2 ...]: Line type for each column in -input. LT? are integers for now. -col.name NAME1 [NAME2 ...]: Name of each column in -input. Special flags: VOLREG: --> 'Roll Pitch Yaw I-S R-L A-P' -col.name.show : Show names of column in -input. -col.nozeros: Do not plot all zeros columns -col.plot.char CHAR1 [CHAR2 ...] : Symbols for each column in -input. CHAR? are integers (usually 0-127), or characters + - I etc. See the following link for what CHAR? values you can use: http://stat.ethz.ch/R-manual/R-patched/library/graphics/html/points.html -col.plot.type PLOT_TYPE: Column plot type. 'l' for line, 'p' for points, 'b' for both -col.text.lym LYM_TEXT: Text to be placed at left Y margin. You need one string per column. Special Flags: You can also use COL.NAME to use column names for the margin text, or you can use COL.IND to use the colum's index in the file -col.text.rym RYM_TEXT: Text to be placed at right Y margin. You need one string per column. See also Special Flags section under -col.text.lym -col.ystack: Scale each column and offset it based on its column index. This is useful for stacking a large number of columns on one plot. It is only carried out when graphing more than one series with the -one option. -grid.show : Show grid. -grp.label GROUP1 [GROUP2 ...]: Labels assigned to each group. Default is no labeling -help: this help message -i 1D_INPUT: file to plot. This field can have multiple formats. See Data Strings section below. 1dRplot will automatically detect certain 1D files ouput by some programs such as 3dhistog or 3ddot and adjust parameters accordingly. -input 1D_INPUT: Same as -i -input_delta 1D_INPUT: file containing value for error bars -input_type 1D_TYPE: Type of data in 1D file. Choose from 'VOLREG', or 'XMAT' -leg.fontsize : fontsize for legend text. -leg.line.color : Color to use for items in legend. Default is taken from column line color. -leg.line.type : Line type to use for items in legend. Default is taken from column line types. If you want no line, set -leg.line.type = 0 -leg.names : Names to use for items in legend. Default is taken from column names. -leg.ncol : Number of columns in legend. -leg.plot.char : plot characters to use for items in legend. Default is taken from column plot character (-col.plot.char). -leg.position : Legend position. Choose from: bottomright, bottom, bottomleft left, topleft, top, topright, right, and center -leg.show : Show legend. -load.Rdat RDAT: load data list from save.Rdat for reproducing plot. Note that you cannot override the settings in RDAT, unless you run in the interactive R mode. For example, say you have dice.Rdat saved from a previous command and you want to change P$nodisp to TRUE: load('dice.Rdat'); P$nodisp <- TRUE; plot.1D.eng(P) -mat: Display as matrix -matplot: Display as matrix -msg.trace: Output trace information along with errors and notices -multi: Put columns in separate graphs -multiplot: Put columns in separate graphs -nozeros: Do not plot all zeros time series -one: Put all columns on one graph -oneplot: Put all columns on one graph -prefix PREFIX: Output prefix. See also -save. -row.name NAME1 [NAME2 ...]: Name of each row in -input. For the moment, this is only used with -matplot -rowcol.name NAME1 [NAME2 ...]: Names of rows, same as name of columns. For the moment, this is only used with -matplot. -run_examples: Run all examples, one after the other. -save PREFIX: Save plot and quit No need for -prefix with this option -save.Rdat : Save data list for reproducing plot in R. You need to specify -prefix or -save along with this option to set the prefix. See also -load.Rdat -save.size width height: Save figure size in pixels Default is 2000 2000 -show_allowed_options: list of allowed options -title TITLE: Graph title. File name is used by default. Use NONE to be sure no title is used. -TR TR: Sampling period, in seconds. -verb VERB: VERB is an integer specifying verbosity level. 0 for quiet (Default). 1 or more: talkative. -x 1D_INPUT: x axis. You can also use the string 'ENUM' to indicate that the x axis should go from 1 to N, the number of samples in -input -xax.label XLABEL: Label of X axis -xax.lim MIN MAX [STEP]: Range of X axis, STEP is optional -xax.tic.text XTTEXT: X tics text -yax.label YLABEL: Label of Y axis -yax.lim MIN MAX [STEP]: Range of X axis, STEP is optional -yax.tic.text YTTEXT: Y tics text -zeros: Do plot all zeros time series Data Strings: ------------- You can specify input matrices and vectors in a variety of ways. The simplest is by specifying a .1D file with all the trimmings of column and row selectors. You can also specify a string that gets evaluated on the fly. For example: '1D: 1 4 8' evaluates to a vector of values 1 4 and 8. Also, you can use R expressions such as: 'R: seq(0,10,3)' To download demo data from AFNI's website run this command: ----------------------------------------------------------- curl -o demo.X.xmat.1D afni.nimh.nih.gov/pub/dist/edu/data/samples/X.xmat.1D curl -o demo.motion.1D afni.nimh.nih.gov/pub/dist/edu/data/samples/motion.1D Example 1 --- : -------------------------------- 1dRplot -input demo.X.xmat.1D'[5..10]' Example 2 --- : -------------------------------- 1dRplot -input demo.X.xmat.1D'[5..10]' \ -input_type XMAT Example 3 --- : -------------------------------- 1dRplot -input demo.motion.1D \ -input_type VOLREG Example 4 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 10)' Example 5 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 5)' \ -one Example 6 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 10)' \ -one \ -col.ystack Example 7 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 10)' \ -one \ -col.ystack \ -col.grp '1D:1 1 1 2 2 2 3 3 3 3' \ -grp.label slow medium fast \ -prefix ta.jpg \ -yax.lim 0 18 \ -leg.show \ -leg.position top Example 8 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 10)' \ -one \ -col.ystack \ -col.grp '1D:1 1 1 2 2 2 3 3 3 3' \ -grp.label slow medium fast \ -prefix tb.jpg \ -yax.lim 0 18 \ -leg.show \ -leg.position top \ -nozeros \ -addavg Example 9 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 10)' \ -one \ -col.ystack \ -col.grp '1D:1 1 1 2 2 2 3 3 3 3' \ -grp.label slow medium fast \ -prefix tb.jpg \ -yax.lim 0 18 \ -leg.show \ -leg.position top \ -nozeros \ -addavg \ -col.text.lym Tutti mi chiedono tutti mi vogliono \ Donne ragazzi vecchi fanciulle \ -col.text.rym "R:paste('Col',seq(1,10), sep='')" Example 10 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 2)' \ -one \ -col.plot.char 2 \ -col.plot.type p Example 11 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 2)' \ -one \ -col.line.type 3 \ -col.plot.type l Example 12 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 2)' \ -one \ -col.plot.char 2 \ -col.line.type 3 \ -col.plot.type b Example 13 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 2)' \ -one \ -col.plot.char 2 5\ -col.line.type 3 4\ -col.plot.type b \ -TR 2 Example 14 --- : -------------------------------- 1dRplot -input 'R:plot.1D.testmat(100, 2)' \ -one -col.plot.char 2 -col.line.type 3 \ -col.plot.type b -TR 2 \ -yax.tic.text 'numa numa numa numaei' \ -xax.tic.text 'Alo' 'Salut' 'sunt eu' 'un haiduc'

AFNI program: 1dSEM
Usage: 1dSEM [options] -theta 1dfile -C 1dfile -psi 1dfile -DF nn.n Computes path coefficients for connection matrix in Structural Equation Modeling (SEM) The program takes as input : 1. A 1D file with an initial representation of the connection matrix with a 1 for each interaction component to be modeled and a 0 if if it is not to be modeled. This matrix should be PxP rows and column 2. A 1D file of the C, correlation matrix, also with dimensions PxP 3. A 1D file of the residual variance vector, psi 4. The degrees of freedom, DF Output is printed to the terminal and may be redirected to a 1D file The path coefficient matrix is printed for each matrix computed Options: -theta file.1D = connection matrix 1D file with initial representation -C file.1D = correlation matrix 1D file -psi file.1D = residual variance vector 1D file -DF nn.n = degrees of freedom -max_iter n = maximum number of iterations for convergence (Default=10000). Values can range from 1 to any positive integer less than 10000. -nrand n = number of random trials before optimization (Default = 100) -limits m.mmm n.nnn = lower and upper limits for connection coefficients (Default = -1.0 to 1.0) -calccost = no modeling at all, just calculate the cost function for the coefficients as given in the theta file. This may be useful for verifying published results -verbose nnnnn = print info every nnnnn steps Model search options: Look for best model. The initial connection matrix file must follow these specifications. Each entry must be 0 for entries excluded from the model, 1 for each required entry in the minimum model, 2 for each possible path to try. -tree_growth or -model_search = search for best model by growing a model for one additional coefficient from the previous model for n-1 coefficients. If the initial theta matrix has no required coefficients, the initial model will grow from the best model for a single coefficient -max_paths n = maximum number of paths to include (Default = 1000) -stop_cost n.nnn = stop searching for paths when cost function is below this value (Default = 0.1) -forest_growth or -grow_all = search over all possible models by comparing models at incrementally increasing number of path coefficients. This algorithm searches all possible combinations; for the number of coeffs this method can be exceptionally slow, especially as the number of coefficients gets larger, for example at n>=9. -leafpicker = relevant only for forest growth searches. Expands the search optimization to look at multiple paths to avoid local minimum. This method is the default technique for tree growth and standard coefficient searches This program uses a Powell optimization algorithm to find the connection coefficients for any particular model. References: Powell, MJD, "The NEWUOA software for unconstrained optimization without derivatives", Technical report DAMTP 2004/NA08, Cambridge University Numerical Analysis Group: See: http://www.ii.uib.no/~lennart/drgrad/Powell2004.pdf Bullmore, ET, Horwitz, B, Honey, GD, Brammer, MJ, Williams, SCR, Sharma, T, How Good is Good Enough in Path Analysis of fMRI Data? NeuroImage 11, 289-301 (2000) Stein, JL, et al., A validated network of effective amygdala connectivity, NeuroImage (2007), doi:10.1016/j.neuroimage.2007.03.022 The initial representation in the theta file is non-zero for each element to be modeled. The 1D file can have leading columns for labels that will be used in the output. Label rows must be commented with the # symbol If using any of the model search options, the theta file should have a '1' for each required coefficient, '0' for each excluded coefficient, '2' for an optional coefficient. Excluded coefficients are not modeled. Required coefficients are included in every computed model. N.B. - Connection directionality in the path connection matrices is from column to row of the output connection coefficient matrices. Be very careful when interpreting those path coefficients. First of all, they are not correlation coefficients. Suppose we have a network with a path connecting from region A to region B. The meaning of the coefficient theta (e.g., 0.81) is this: if region A increases by one standard deviation from its mean, region B would be expected to increase by 0.81 its own standard deviations from its own mean while holding all other relevant regional connections constant. With a path coefficient of -0.16, when region A increases by one standard deviation from its mean, region B would be expected to decrease by 0.16 its own standard deviations from its own mean while holding all other relevant regional connections constant. So theoretically speaking the range of the path coefficients can be anything, but most of the time they range from -1 to 1. To save running time, the default values for -limits are set with -1 and 1, but if the result hits the boundary, increase them and re-run the analysis. Examples: To confirm a specific model: 1dSEM -theta inittheta.1D -C SEMCorr.1D -psi SEMvar.1D -DF 30 To search models by growing from the best single coefficient model up to 12 coefficients 1dSEM -theta testthetas_ms.1D -C testcorr.1D -psi testpsi.1D \ -limits -2 2 -nrand 100 -DF 30 -model_search -max_paths 12 To search all possible models up to 8 coefficients: 1dSEM -theta testthetas_ms.1D -C testcorr.1D -psi testpsi.1D \ -nrand 10 -DF 30 -stop_cost 0.1 -grow_all -max_paths 8 | & tee testgrow.txt For more information, see https://afni.nimh.nih.gov/sscc/gangc/PathAna.html and our HBM 2007 poster at https://sscc.nimh.nih.gov/sscc/posters/file.2007-06-07.0771819246 If you find this program useful, please cite: G Chen, DR Glen, JL Stein, AS Meyer-Lindenberg, ZS Saad, RW Cox, Model Validation and Automated Search in FMRI Path Analysis: A Fast Open-Source Tool for Structural Equation Modeling, Human Brain Mapping Conference, 2007

AFNI program: 1dsound
Usage: 1dsound [options] tsfile Program to create a sound file from a 1D file (column of numbers). Is this program useful? Probably not, but it can be fun. ------- OPTIONS ------- ===== output filename ===== -prefix ppp = Output filename will be ppp.au [Sun audio format https://en.wikipedia.org/wiki/Au_file_format] + If you don't use '-prefix', the output is file 'sound.au'. + If 'ppp' ends in '.au', this program won't add another '.au. ===== encoding details ===== -16PCM = Output in 16-bit linear PCM encoding (uncompressed) + Less quantization noise (audible hiss) :) + Takes twice as much disk space for output as 8-bit output :( +++ This is the default method now! + https://en.wikipedia.org/wiki/Pulse-code_modulation -8PCM = Output in 8-bit linear PCM encoding + There is no good reason to use this option. -8ulaw = Output in 8-bit mu-law encoding. + Provides a little better quality than -8PCM, but still has audible quantization noise hiss. + https://en.wikipedia.org/wiki/M-law_algorithm -tper X = X seconds of sound per time point in 'tsfile'. -TR X Allowed range for 'X' is 0.01 to 1.0 (inclusive). -dt X [default time step is 0.2 s] You can use '-tper', '-dt', or '-TR', as you like. ===== how the sound timeseries is produced from the data timeseries ===== -FM = Output sound is frequency modulated between 110 and 1760 Hz from min to max in the input 1D file. + Usually 'sounds terrible'. + The only reason this is here is that it was the first method I implemented, and I kept it for the sake of nostalgia. -notes = Output sound is a sequence of notes, low to high pitch based on min to max in the input 1D file. +++ This is the default method of operation. + A pentatonic scale is used, which usually 'sounds nice': https://en.wikipedia.org/wiki/Pentatonic_scale -notewave W = Selects the shape of the notes used. 'W' is one of these: -waveform W sine = pure sine wave (sounds simplistic) sqsine = square root of sine wave (a little harsh and loud) square = square wave (a lot harsh and loud) triangle = triangle wave [the default waveform] -despike = apply a simple despiking algorithm, to avoid the artifact of one very large or small value making all the other notes end up being the same. ===== Notes about notes ===== ** At this time, the default production method is '-notes', ** ** using the triangle waveform (I like this best). ** ** With '-notes', up to 6 columns of the input file will be used ** ** to produce a polyphonic sound (in a single channel). ** ** (Any columns past the 6th in the input 'tsfile' are ignored.) ** ===== hear the sound right away! ===== -play = Plays the sound file after it is written. On this computer: uses program /usr/bin/aplay ===>> Playing sound on a remote computer is annoying, pointless, and likely to get you punched. -------- EXAMPLES -------- The first 2 examples are purely synthetic, using 'data' files created on the command line. The third example uses a data file that was written out of an AFNI graph viewer using the 'w' keystroke. 1dsound -prefix A1 '1D: 0 1 2 1 0 1 2 0 1 2' 1deval -num 100 -expr 'sin(x+0.01*x*x)' | 1dsound -tper 0.1 -prefix A2 1D:stdin 1dsound -prefix -tper 0.1 A3 028_044_003.1D ----- NOTES ----- * File can be played with the 'sox' audio package command play A1.au gain -5 + Here 'gain -5' turns the volume down :) + sox is not provided with AFNI :( + To see if sox is on your system, type the command 'which sox' + If you have sox, you can add 'reverb 99' at the end of the 'play' command line, and have some extra fun. + Many other effects are available with sox 'play', and they can also be used to produce edited sound files: http://sox.sourceforge.net/sox.html#EFFECTS + You can convert the .au file produced from here to other formats using sox; for example: sox Bob.au Cox.au BobCox.aiff combines the 2 .au input files to a 2-channel (stereo) Apple .aiff output file. See this for more information: http://sox.sourceforge.net/soxformat.html * Creation of the file does not depend on sox, so if you have another way to play .au files, you can use that. * Mac OS X: Quicktime (GUI) or afplay (command line) programs. + sox can be installed by first installing 'brew' -- see https://brew.sh/ -- and then using command 'brew install sox'. * Linux: Getting sox is probably the simplest thing to do. + Or install the mplayer package (which also does videos). + Another possibility is the aplay program. * The audio output file is sampled at 16K bytes per second. For example, a 30 second file will be 960K bytes in size, at 16 bits per sample. * The auditory effect varies significantly with the '-tper' parameter X; '-tper 0.02' is very different than '-tper 0.4'. --- Quick hack for experimentation and fun - RWCox - Aug 2018 ---

AFNI program: 1dsum
Usage: 1dsum [options] a.1D b.1D ... where each file a.1D, b.1D, etc. is an ASCII file of numbers arranged in rows and columns. The sum of each column is written to stdout. Options: -ignore nn = skip the first nn rows of each file -use mm = use only mm rows from each file -mean = compute the average instead of the sum -nocomment = the # comments from the header of the first input file will be reproduced to the output; if you do NOT want this to happen, use the '-nocomment' option. -OKempty = If you encounter an empty 1D file, print 0 and exit quietly instead of exiting with an error message ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dsvd
Usage: 1dsvd [options] 1Dfile 1Dfile ... - Computes SVD of the matrix formed by the 1D file(s). - Output appears on stdout; to save it, use '>' redirection. OPTIONS: -one = Make 1st vector be all 1's. -vmean = Remove mean from each vector (can't be used with -one). -vnorm = Make L2-norm of each vector = 1 before SVD. * The above 2 options mirror those in 3dpc. -cond = Only print condition number (ratio of extremes) -sing = Only print singular values * To compare the singular values from 1dsvd with those from 3dDeconvolve you must use the -vnorm option with 1dsvd. For example, try 3dDeconvolve -nodata 200 1 -polort 5 -num_stimts 1 \ -stim_times 1 '1D: 30 130' 'BLOCK(50,1)' -singvals 1dsvd -sing -vnorm nodata.xmat.1D -sort = Sort singular values (descending) [the default] -nosort = Don't bother to sort the singular values -asort = Sort singular values (ascending) -1Dleft = Only output left eigenvectors, in a .1D format This might be useful for reducing the number of columns in a design matrix. The singular values are printed at the top of each vector column, as a '#...' comment line. -nev n = If -1Dleft is used, '-nev' specifies to output only the first 'n' eigenvectors, rather than all of them. * If you are a tricky person, such as Souheil, you can put a '%' after the value, and then you are saying keep eigenvectors until at least n% of the sum of singular values is accounted for. In this usage, 'n' must be a number less than 100; for example, to reduce a matrix down to a smaller set of columns that capture most of its column space, try something like 1dsvd -1Dleft -nev 99% Xorig.1D > X99.1D EXAMPLE: 1dsvd -vmean -vnorm -1Dleft fred.1D'[1..6]' | 1dplot -stdin NOTES: * Call the input n X m matrix [A] (n rows, m columns). The SVD is the factorization [A] = [U] [S] [V]' ('=transpose), where - [U] is an n x m matrix (whose columns are the 'Left vectors') - [S] is a diagonal m x m matrix (the 'singular values') - [V] is an m x m matrix (whose columns are the 'Right vectors') * The default output of the program is - An echo of the input [A] - The [U] matrix, each column headed by its singular value - The [V] matrix, each column headed by its singular value (please note that [V] is output, not [V]') - The pseudo-inverse of [A] * This program was written simply for some testing purposes, but is distributed with AFNI because it might be useful-ish. * Recall that you can transpose a .1D file on input by putting an escaped ' character after the filename. For example, 1dsvd fred.1D\' You can use this feature to get around the fact that there is no '-1Dright' option. If you understand. * For more information on the SVD, you can start at http://en.wikipedia.org/wiki/Singular_value_decomposition * Author: Zhark the Algebraical (Linear). ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1d_tool.py
============================================================================= 1d_tool.py - for manipulating and evaluating 1D files --------------------------------------------------------------------------- purpose: ~1~ This program is meant to read/manipulate/write/diagnose 1D datasets. Input can be specified using AFNI sub-brick[]/time{} selectors. --------------------------------------------------------------------------- examples (very basic for now): ~1~ Example 1. Select by rows and columns, akin to 1dcat. ~2~ Note: columns can be X-matrix labels. 1d_tool.py -infile 'data/X.xmat.1D[0..3]{0..5}' -write t1.1D or using column labels: 1d_tool.py -infile 'data/X.xmat.1D[Run#1Pol#0..Run#1Pol#3]' \ -write run0_polorts.1D Example 2. Compare with selection by separate options. ~2~ 1d_tool.py -infile data/X.xmat.1D \ -select_cols '0..3' -select_rows '0..5' \ -write t2.1D diff t1.1D t2.1D Example 2b. Select or remove columns by label prefixes. ~2~ Keep only bandpass columns: 1d_tool.py -infile X.xmat.1D -write X.bandpass.1D \ -label_prefix_keep bandpass Remove only bandpass columns (maybe for 3dRFSC): 1d_tool.py -infile X.xmat.1D -write X.no.bandpass.1D \ -label_prefix_drop bandpass Keep polort columns (start with 'Run') motion shifts ('d') and labels starting with 'a' and 'b'. But drop 'bandpass' columns: 1d_tool.py -infile X.xmat.1D -write X.weird.1D \ -label_prefix_keep Run d a b \ -label_prefix_drop bandpass Example 2c. Select columns by group values, 3 examples. ~2~ First be sure of what the group labels represent. 1d_tool.py -infile X.xmat.1D -show_group_labels i) Select polort (group -1) and other baseline (group 0) terms. 1d_tool.py -infile X.xmat.1D -select_groups -1 0 -write baseline.1D ii) Select everything but baseline groups (anything positive). 1d_tool.py -infile X.xmat.1D -select_groups POS -write regs.of.int.1D iii) Reorder to have rests of interest, then motion, then polort. 1d_tool.py -infile X.xmat.1D -select_groups POS 0, -1 -write order.1D iv) Create stim-only X-matrix file: select non-baseline columns of X-matrix and write with header comment. 1d_tool.py -infile X.xmat.1D -select_groups POS \ -write_with_header yes -write X.stim.xmat.1D Or, using a convenience option: 1d_tool.py -infile X.xmat.1D -write_xstim X.stim.xmat.1D Example 2d. Select specific runs from the input. ~2~ Note that X.xmat.1D may have runs defined automatically, but for an arbitrary input, they may need to be specified via -set_run_lengths. i) .... apparently I forgot to do this... Example 2e. Select tedana mixing columns by accept or reject. ~2~ ME-ICA tedana outputs component metrics in desc-tedana_metrics.tsv and the actual components in desc-ICA_mixing.tsv. Write the rejected components to tedana.rejected.1D. 1d_tool.py -infile desc-ICA_mixing.tsv \ -select_cols_via_TSV_table desc-tedana_metrics.tsv \ Component classification=rejected \ -write tedana.rejected.1D -verb 2 Example 2f. Select fMRIPrep confounds. ~2~ fMRIPrep outputs many time series to optionally use for regression. Assuming this is in a file fmriprep_confounds.tsv: select AROMA motion time series: 1d_tool.py -infile fmriprep_confounds.tsv'[aroma_mot*]' \ -write aroma_motion.1D select standard motion parameters (3 rotations, 3 shifts): 1d_tool.py -infile fmriprep_confounds.tsv'[rot_?,trans_?]' \ -write fmriprep_motion.1D verify the labels chosen by selector: 1d_tool.py -infile fmriprep_confounds.tsv'[rot_?,trans_?]' \ -show_group_labels Example 3. Transpose a dataset, akin to 1dtranspose. ~2~ 1d_tool.py -infile t3.1D -transpose -write ttr.1D Example 4a. Zero-pad a single-run 1D file across many runs. ~2~ Given a file of regressors (for example) across a single run (run 2), created a new file that is padded with zeros, so that it now spans many (7) runs. Runs are 1-based here. 1d_tool.py -infile ricor_r02.1D -pad_into_many_runs 2 7 \ -write ricor_r02_all.1D Example 4b. Similar to 4a, but specify varying TRs per run. ~2~ The number of runs must match the number of run_lengths parameters. 1d_tool.py -infile ricor_r02.1D -pad_into_many_runs 2 7 \ -set_run_lengths 64 61 67 61 67 61 67 \ -write ricor_r02_all.1D Example 5. Display small details about a 1D dataset: ~2~ a. Display number of rows and columns for a 1D dataset. Note: to display them "quietly" (only the numbers), add -verb 0. This is useful for setting a script variable. 1d_tool.py -infile X.xmat.1D -show_rows_cols 1d_tool.py -infile X.xmat.1D -show_rows_cols -verb 0 b. Display indices of regressors of interest from an X-matrix. 1d_tool.py -infile X.xmat.1D -show_indices_interest c. Display X-matrix labels by group. 1d_tool.py -infile X.xmat.1D -show_group_labels d. Display "degree of freedom" information: 1d_tool.py -infile X.xmat.1D -show_df_info e. Display X-matrix stimulus class information (for one class or ALL). 1d_tool.py -infile X.xmat.1D -show_xmat_stim_info aud 1d_tool.py -infile X.xmat.1D -show_xmat_stim_info ALL f. Display X-matrix column index list for those of the given classes. Display regressor labels or in encoded column index format. 1d_tool.py -infile X.xmat.1D -show_xmat_stype_cols AM IM 1d_tool.py -infile X.xmat.1D -show_xmat_stype_cols ALL \ -show_regs_style encoded g. Display X-matrix column index list for all-zero regressors. Display regressor labels or in encoded column index format. 1d_tool.py -infile X.xmat.1D -show_xmat_stype_cols AM IM Example 6a. Show correlation matrix warnings for this matrix. ~2~ This option does not include warnings from baseline regressors, which are common (from polort 0, from similar motion, etc). 1d_tool.py -infile X.xmat.1D -show_cormat_warnings Example 6b. Show entire correlation matrix. ~2~ 1d_tool.py -infile X.xmat.1D -show_cormat Example 6c. Like 6a, but include warnings for baseline regressors. ~2~ 1d_tool.py -infile X.xmat.1D -show_cormat_warnings_full Example 7a. Output temporal derivative of motion regressors. ~2~ There are 9 runs in dfile_rall.1D, and derivatives are applied per run. 1d_tool.py -infile dfile_rall.1D -set_nruns 9 \ -derivative -write motion.deriv.1D Example 7b. Similar to 7a, but let the run lengths vary. ~2~ The sum of run lengths should equal the number of time points. 1d_tool.py -infile dfile_rall.1D \ -set_run_lengths 64 64 64 64 64 64 64 64 64 \ -derivative -write motion.deriv.rlens.1D Example 7c. Use forward differences. ~2~ instead of the default backward differences... 1d_tool.py -infile dfile_rall.1D \ -set_run_lengths 64 64 64 64 64 64 64 64 64 \ -forward_diff -write motion.deriv.rlens.1D Example 8. Verify whether labels show slice-major ordering. This is where all slice0 regressors come first, then all slice1 regressors, etc. Either show the labels and verify visually, or print whether it is true. 1d_tool.py -infile scan_2.slibase.1D'[0..12]' -show_labels 1d_tool.py -infile scan_2.slibase.1D -show_labels 1d_tool.py -infile scan_2.slibase.1D -show_label_ordering Example 9a. Given motion.1D, create an Enorm time series. ~2~ Take the derivative (ignoring run breaks) and the Euclidean Norm, and write as e.norm.1D. This might be plotted to show show sudden motion as a single time series. 1d_tool.py -infile motion.1D -set_nruns 9 \ -derivative -collapse_cols euclidean_norm \ -write e.norm.1D Example 9b. Like 9a, but supposing the run lengths vary (still 576 TRs). ~2~ 1d_tool.py -infile motion.1D \ -set_run_lengths 64 61 67 61 67 61 67 61 67 \ -derivative -collapse_cols euclidean_norm \ -write e.norm.rlens.1D Example 9c. Like 9b, but weight the rotations as 0.9 mm. ~2~ 1d_tool.py -infile motion.1D \ -set_run_lengths 64 61 67 61 67 61 67 61 67 \ -derivative -collapse_cols weighted_enorm \ -weight_vec .9 .9 .9 1 1 1 \ -write e.norm.weighted.1D Example 10. Given motion.1D, create censor files to use in 3dDeconvolve. ~2~ Here a TR is censored if the derivative values have a Euclidean Norm above 1.2. It is common to also censor each previous TR, as motion may span both (previous because "derivative" is actually a backward difference). The file created by -write_censor can be used with 3dD's -censor option. The file created by -write_CENSORTR can be used with -CENSORTR. They should have the same effect in 3dDeconvolve. The CENSORTR file is more readable, but the censor file is better for plotting against the data. a. general example ~3~ 1d_tool.py -infile motion.1D -set_nruns 9 \ -derivative -censor_prev_TR \ -collapse_cols euclidean_norm \ -moderate_mask -1.2 1.2 \ -show_censor_count \ -write_censor subjA_censor.1D \ -write_CENSORTR subjA_CENSORTR.txt b. using -censor_motion ~3~ The -censor_motion option is available, which implies '-derivative', '-collapse_cols euclidean_norm', 'moderate_mask -LIMIT LIMIT', and the prefix for '-write_censor' and '-write_CENSORTR' output files. This option will also result in subjA_enorm.1D being written, which is the euclidean norm of the derivative, before the extreme mask is applied. 1d_tool.py -infile motion.1D -set_nruns 9 \ -show_censor_count \ -censor_motion 1.2 subjA \ -censor_prev_TR c. allow the run lengths to vary ~3~ 1d_tool.py -infile motion.1D \ -set_run_lengths 64 61 67 61 67 61 67 61 67 \ -show_censor_count \ -censor_motion 1.2 subjA_rlens \ -censor_prev_TR Consider also '-censor_prev_TR' and '-censor_first_trs'. Example 11. Demean the data. Use motion parameters as an example. ~2~ The demean operation is done per run (default is 1 when 1d_tool.py does not otherwise know). a. across all runs (if runs are not known from input file) 1d_tool.py -infile dfile_rall.1D -demean -write motion.demean.a.1D b. per run, over 9 runs of equal length 1d_tool.py -infile dfile_rall.1D -set_nruns 9 \ -demean -write motion.demean.b.1D c. per run, over 9 runs of varying length 1d_tool.py -infile dfile_rall.1D \ -set_run_lengths 64 61 67 61 67 61 67 61 67 \ -demean -write motion.demean.c.1D Example 12. "Uncensor" the data, zero-padding previously censored TRs. ~2~ Note that an X-matrix output by 3dDeconvolve contains censor information in GoodList, which is the list of uncensored TRs. a. if the input dataset has censor information 1d_tool.py -infile X.xmat.1D -censor_fill -write X.uncensored.1D b. if censor information needs to come from a parent 1d_tool.py -infile sum.ideal.1D -censor_fill_parent X.xmat.1D \ -write sum.ideal.uncensored.1D c. if censor information needs to come from a simple 1D time series 1d_tool.py -censor_fill_parent motion_FT_censor.1D \ -infile cdata.1D -write cdata.zeropad.1D Example 13. Show whether the input file is valid as a numeric data file. ~2~ a. as any generic 1D file 1d_tool.py -infile data.txt -looks_like_1D b. as a 1D stim_file, of 3 runs of 64 TRs (TR is irrelevant) 1d_tool.py -infile data.txt -looks_like_1D \ -set_run_lengths 64 64 64 c. as a stim_times file with local times 1d_tool.py -infile data.txt -looks_like_local_times \ -set_run_lengths 64 64 64 -set_tr 2 d. as a 1D or stim_times file with global times 1d_tool.py -infile data.txt -looks_like_global_times \ -set_run_lengths 64 64 64 -set_tr 2 e. report modulation type (amplitude and/or duration) 1d_tool.py -infile data.txt -looks_like_AM f. perform all tests, reporting all errors 1d_tool.py -infile data.txt -looks_like_test_all \ -set_run_lengths 64 64 64 -set_tr 2 Example 14. Split motion parameters across runs. ~2~ Split, but keep them at the original length so they apply to the same multi-run regression. Each file will be the same as the original for the run it applies to, but zero across all other runs. Note that -split_into_pad_runs takes the output prefix as a parameter. 1d_tool.py -infile motion.1D \ -set_run_lengths 64 64 64 \ -split_into_pad_runs mot.padded The output files are: mot.padded.r01.1D mot.padded.r02.1D mot.padded.r03.1D If the run lengths are the same -set_nruns is shorter... 1d_tool.py -infile motion.1D \ -set_nruns 3 \ -split_into_pad_runs mot.padded Example 15a. Show the maximum pairwise displacement. ~2~ Show the max pairwise displacement in the motion parameter file. So over all TRs pairs, find the biggest displacement. In one direction it is easy (AP say). If the minimum AP shift is -0.8 and the maximum is 1.5, then the maximum displacement is 2.3 mm. It is less clear in 6-D space, and instead of trying to find an enveloping set of "coordinates", distances between all N choose 2 pairs are evaluated (brute force). 1d_tool.py -infile dfile_rall.1D -show_max_displace Example 15b. Like 15a, but do not include displacement from censored TRs. ~2~ 1d_tool.py -infile dfile_rall.1D -show_max_displace \ -censor_infile motion_censor.1D Example 15c. Show the entire distance/displacement matrix. ~2~ Show all pairwise displacements (vector distances) in a (motion param?) row vector file. Note that the maximum element of this matrix should be the one output by -show_max_displace. 1d_tool.py -infile coords.1D -show_distmat Example 16. Randomize a list of numbers, say, those from 1..40. ~2~ The numbers can come from 1deval, with the result piped to '1d_tool.py -infile stdin -randomize_trs ...'. 1deval -num 40 -expr t+1 | \ 1d_tool.py -infile stdin -randomize_trs -write stdout See also -seed. Example 17. Display min, mean, max, stdev of 1D file. ~2~ 1d_tool.py -show_mmms -infile data.1D To be more detailed, get stats for each of x, y, and z directional blur estimates for all subjects. Cat(enate) all of the subject files and pipe that to 1d_tool.py with infile - (meaning stdin). cat subject_results/group.*/sub*/*.results/blur.errts.1D \ | 1d_tool.py -show_mmms -infile - Example 18. Just output censor count for default method. ~2~ This will output nothing but the number of TRs that would be censored, akin to using -censor_motion and -censor_prev_TR. 1d_tool.py -infile dfile_rall.1D -set_nruns 3 -quick_censor_count 0.3 1d_tool.py -infile dfile_rall.1D -set_run_lengths 100 80 120 \ -quick_censor_count 0.3 Example 19. Compute GCOR from some 1D file. ~2~ * Note, time should be in the vertical direction of the file (else use -transpose). 1d_tool.py -infile data.1D -show_gcor Or get some GCOR documentation and many values. 1d_tool.py -infile data.1D -show_gcor_doc 1d_tool.py -infile data.1D -show_gcor_all Example 20. Display censored or uncensored TRs lists (for use in 3dTcat). ~2~ TRs which were censored: 1d_tool.py -infile X.xmat.1D -show_trs_censored encoded TRs which were applied in analysis (those NOT censored): 1d_tool.py -infile X.xmat.1D -show_trs_uncensored encoded Only those applied in run #2 (1-based). 1d_tool.py -infile X.xmat.1D -show_trs_uncensored encoded \ -show_trs_run 2 Example 21. Convert to rank order. ~2~ a. show rank order of slice times from a 1D file 1d_tool.py -infile slice_times.1D -rank -write - b. show rank order of slice times piped directly from 3dinfo Note: input should be space separated, not '|' separated. 3dinfo -slice_timing -sb_delim ' ' epi+orig \ | 1d_tool.py -infile - -rank -write - c. show rank order using 'competition' rank, instead of default 'dense' 3dinfo -slice_timing -sb_delim ' ' epi+orig \ | 1d_tool.py -infile - -rank_style competition -write - Example 22. Guess volreg base index from motion parameters. ~2~ 1d_tool.py -infile dfile_rall.1D -collapse_cols enorm -show_argmin Example 23. Convert volreg parameters to those suitable for 3dAllineate. ~2~ 1d_tool.py -infile dfile_rall.1D -volreg2allineate \ -write allin_rall_aff12.1D Example 24. Show TR counts per run. ~2~ a. list the number of TRs in each run 1d_tool.py -infile X.xmat.1D -show_tr_run_counts trs b. list the number of TRs censored in each run 1d_tool.py -infile X.xmat.1D -show_tr_run_counts trs_cen c. list the number of TRs prior to censoring in each run 1d_tool.py -infile X.xmat.1D -show_tr_run_counts trs_no_cen d. list the fraction of TRs censored per run 1d_tool.py -infile X.xmat.1D -show_tr_run_counts frac_cen e. list the fraction of TRs censored in run 3 1d_tool.py -infile X.xmat.1D -show_tr_run_counts frac_cen \ -show_trs_run 3 Example 25. Show number of runs. ~2~ 1d_tool.py -infile X.xmat.1D -show_num_runs Example 26. Convert global index to run and TR index. ~2~ Note that run indices are 1-based, while TR indices are 0-based, as usual. Confusion is key. a. explicitly, given run lengths 1d_tool.py -set_run_lengths 100 80 120 -index_to_run_tr 217 b. implicitly, given an X-matrix (** be careful about censoring **) 1d_tool.py -infile X.nocensor.xmat.1D -index_to_run_tr 217 Example 27. Display length of response curve. ~2~ 1d_tool.py -show_trs_to_zero -infile data.1D Print out the length of the input (in TRs, say) until the data values become a constant zero. Zeros that are followed by non-zero values are irrelevant. Example 28. Convert slice order to slice times. ~2~ A slice order might be the sequence in which slices were acquired. For example, with 33 slices, perhaps the order is: set slice_order = ( 0 6 12 18 24 30 1 7 13 19 25 31 2 8 14 20 \ 26 32 3 9 15 21 27 4 10 16 22 28 5 11 17 23 29 ) Put this in a file: echo $slice_order > slice_order.1D 1d_tool.py -set_tr 2 -slice_order_to_times \ -infile slice_order.1D -write slice_times.1D Or as a filter: echo $slice_order | 1d_tool.py -set_tr 2 -slice_order_to_times \ -infile - -write - Example 29. Display minimum cluster size from 3dClustSim output. ~2~ Given a text file output by 3dClustSim, e.g. ClustSim.ACF.NN1_1sided.1D, and given both an uncorrected (pthr) and a corrected (alpha) p-value, look up the entry that specifies the minimum cluster size needed for corrected p-value significance. If requested in afni_proc.py, they are under files_ClustSim. a. with modestly verbose output (default is -verb 1) 1d_tool.py -infile ClustSim.ACF.NN1_1sided.1D -csim_show_clustsize b. quiet, to see just the output value 1d_tool.py -infile ClustSim.ACF.NN1_1sided.1D -csim_show_clustsize \ -verb 0 c. quiet, and capture the output value (tcsh syntax) set clustsize = `1d_tool.py -infile ClustSim.ACF.NN1_1sided.1D \ -csim_show_clustsize -verb 0` Example 30. Display columns that are all-zero (e.g. censored out) ~2~ Given a regression matrix, list columns that are entirely zero, such as those for which there were no events, or those for which event responses were censored out. a. basic output Show the number of such columns and a list of labels 1d_tool.py -show_regs allzero -infile zerocols.X.xmat.1D b. quiet output (do not include the number of such columns) 1d_tool.py -show_regs allzero -infile zerocols.X.xmat.1D -verb 0 c. quiet encoded index list 1d_tool.py -show_regs allzero -infile zerocols.X.xmat.1D \ -show_regs_style encoded -verb 0 d. list all labels of regressors of interest (with no initial count) 1d_tool.py -show_regs set -infile zerocols.X.xmat.1D \ -select_groups POS -verb 0 Example 31. Determine slice timing pattern (for EPI data) ~2~ Determine the slice timing pattern from a list of slice times. The output is : - multiband level (usually 1) - tpattern, one such pattern from those in 'to3d -help' a. where slice times are in a file 1d_tool.py -show_slice_timing_pattern -infile slice_times.1D b. or as a filter 3dinfo -slice_timing -sb_delim ' ' FT_epi_r1+orig \ | 1d_tool.py -show_slice_timing_pattern -infile - c. or if it fails, be gentle and verbose 1d_tool.py -infile slice_times.1D \ -show_slice_timing_gentle -verb 3 --- d. Related, show slice timing resolution, the accuracy of the slice times, assuming they should be multiples of a constant (the slice duration). 1d_tool.py -infile slice_times.1D -show_slice_timing_resolution e. or as a filter 3dinfo -slice_timing -sb_delim ' ' FT_epi_r1+orig \ | 1d_tool.py -show_slice_timing_resolution -infile - Example 32. Display slice timing ~2~ Display slice timing given a to3d timing pattern, the number of slices, the multiband level, and optionally the TR. a. pattern alt+z, 40 slices, multiband 1, TR 2s (40 slices in 2s means slices are acquired every 0.05 s) 1d_tool.py -slice_pattern_to_times alt+z 40 1 -set_tr 2 b. same, but multiband 2 (so slices are acquired every 0.1 s, and there are 2 such sets) 1d_tool.py -slice_pattern_to_times alt+z 40 2 -set_tr 2 c. test this by feeding the output to -show_slice_timing_pattern 1d_tool.py -slice_pattern_to_times alt+z 40 2 -set_tr 2 \ | 1d_tool.py -show_slice_timing_pattern -infile - --------------------------------------------------------------------------- command-line options: ~1~ --------------------------------------------------------------------------- basic informational options: ~2~ -help : show this help -hist : show the module history -show_valid_opts : show all valid options -ver : show the version number ---------------------------------------- required input: ~2~ -infile DATASET.1D : specify input 1D file ---------------------------------------- general options: ~2~ -add_cols NEW_DSET.1D : extend dset to include these columns -backward_diff : take derivative as first backward difference Take the backward differences at each time point. For each index > 0, value[index] = value[index] - value[index-1], and value[0] = 0. This option is identical to -derivative. See also -forward_diff, -derivative, -set_nruns, -set_run_lens. -collapse_cols METHOD : collapse multiple columns into one, where METHOD is one of: min, max, minabs, maxabs, euclidean_norm, weighted_enorm. Consideration of the euclidean_norm method: For censoring, the euclidean_norm method is used (sqrt(sum squares)). This combines rotations (in degrees) with shifts (in mm) as if they had the same weight. Note that assuming rotations are about the center of mass (which should produce a minimum average distance), then the average arc length (averaged over the brain mask) of a voxel rotated by 1 degree (about the CM) is the following (for the given datasets): TT_N27+tlrc: 0.967 mm (average radius = 55.43 mm) MNIa_caez_N27+tlrc: 1.042 mm (average radius = 59.69 mm) MNI_avg152T1+tlrc: 1.088 mm (average radius = 62.32 mm) The point of these numbers is to suggest that equating degrees and mm should be fine. The average distance caused by a 1 degree rotation is very close to 1 mm (in an adult human). * 'enorm' is short for 'euclidean_norm'. * Use of weighted_enorm requires the -weight_vec option. e.g. -collapse_cols weighted_enorm -weight_vec .9 .9 .9 1 1 1 -censor_motion LIMIT PREFIX : create censor files This option implies '-derivative', '-collapse_cols euclidean_norm', 'moderate_mask -LIMIT LIMIT' and applies PREFIX for '-write_censor' and '-write_CENSORTR' output files. It also outputs the derivative of the euclidean norm, before the limit it applied. The temporal derivative is taken with run breaks applied (derivative of the first run of a TR is 0), then the columns are collapsed into one via each TR's vector length (Euclidean Norm: sqrt(sum of squares)). After that, a mask time series is made from TRs with values outside (-LIMIT,LIMIT), i.e. if >= LIMIT or <= LIMIT, result is 1. This binary time series is then written out in -CENSORTR format, with the moderate TRs written in -censor format (either can be applied in 3dDeconvolve). The output files will be named PREFIX_censor.1D, PREFIX_CENSORTR.txt and PREFIX_enorm.1D (e.g. subj123_censor.1D, subj123_CENSORTR.txt and subj123_enorm.1D). Besides an input motion file (-infile), the number of runs is needed (-set_nruns or -set_run_lengths). Consider also '-censor_prev_TR' and '-censor_first_trs'. See example 10. -censor_fill : expand data, filling censored TRs with zeros -censor_fill_parent PARENT : similar, but get censor info from a parent The output of these operation is a longer dataset. Each TR that had previously been censored is re-inserted as a zero. The purpose of this is to make 1D time series data properly align with the all_runs dataset, for example. Otherwise, the ideal 1D data might have missing TRs, and so will align worse with responses over the duration of all runs (it might start aligned, but drift earlier and earlier as more TRs are censored). See example 12. -censor_infile CENSOR_FILE : apply censoring to -infile dataset This removes TRs from the -infile dataset where the CENSOR_FILE is 0. The censor file is akin to what is used with "3dDeconvolve -censor", where TRs with 1 are kept and those with 0 are excluded from analysis. See example 15b. -censor_first_trs N : when censoring motion, also censor the first N TRs of each run -censor_next_TR : for each censored TR, also censor next one (probably for use with -forward_diff) -censor_prev_TR : for each censored TR, also censor previous -cormat_cutoff CUTOFF : set cutoff for cormat warnings (in [0,1]) -csim_show_clustsize : for 3dClustSim input, show min clust size Given a 3dClustSim table output (e.g. ClustSim.ACF.NN1_1sided.1D), along with uncorrected (pthr) and corrected (alpha) p-values, show the minimum cluster size to achieve significance. The pthr and alpha values can be controlled via the options -csim_pthr and -csim_alpha (with defaults of 0.001 and 0.05, respectively). The -verb option can be used to provide additional or no details about the clustering method. See Example 29, along with options -csim_pthr, -csim_alpha and -verb. -csim_pthr THRESH : specify uncorrected threshold for csim output e.g. -csim_pthr 0.0001 This option implies -csim_show_clustsize, and is used to specify the uncorrected p-value of the 3dClustSim output. See also -csim_show_clustsize. -csim_alpha THRESH : specify corrected threshold for csim output e.g. -csim_alpha 0.01 This option implies -csim_show_clustsize, and is used to specify the corrected, cluster-wise p-value of the 3dClustSim output. See also -csim_show_clustsize. -demean : demean each run (new mean of each run = 0.0) -derivative : take the temporal derivative of each vector (done as first backward difference) Take the backward differences at each time point. For each index > 0, value[index] = value[index] - value[index-1], and value[0] = 0. This option is identical to -backward_diff. See also -backward_diff, -forward_diff, -set_nruns, -set_run_lens. -extreme_mask MIN MAX : make mask of extreme values Convert to a 0/1 mask, where 1 means the given value is extreme (outside the (MIN, MAX) range), and 0 means otherwise. This is the opposite of -moderate_mask (not exactly, both are inclusive). Note: values = MIN or MAX will be in both extreme and moderate masks. Note: this was originally described incorrectly in the help. -forward_diff : take first forward difference of each vector Take the first forward differences at each time point. For index<last, value[index] = value[index+1] - value[index], and value[last] = 0. The difference between -forward_diff and -backward_diff is a time shift by one index. See also -backward_diff, -derivative, -set_nruns, -set_run_lens. -index_to_run_tr INDEX : convert global INDEX to run and TR indices Given a list of run lengths, convert INDEX to a run and TR index pair. This option requires -set_run_lens or maybe an Xmat. See also -set_run_lens example 26. -moderate_mask MIN MAX : make mask of moderate values Convert to a 0/1 mask, where 1 means the given value is moderate (within [MIN, MAX]), and 0 means otherwise. This is useful for censoring motion (in the -censor case, not -CENSORTR), where the -censor file should be a time series of TRs to apply. See also -extreme_mask. -label_prefix_drop prefix1 prefix2 ... : remove labels matching prefix list e.g. to remove motion shift (starting with 'd') and bandpass labels: -label_prefix_drop d bandpass This is a type of column selection. Use this option to remove columns from a matrix that have labels starting with any from the given prefix list. This option can be applied along with -label_prefix_keep. See also -label_prefix_keep and example 2b. -label_prefix_keep prefix1 prefix2 ... : keep labels matching prefix list e.g. to keep only motion shift (starting with 'd') and bandpass labels: -label_prefix_keep d bandpass This is a type of column selection. Use this option to keep columns from a matrix that have labels starting with any from the given prefix list. This option can be applied along with -label_prefix_drop. See also -label_prefix_drop and example 2b. "Looks like" options: These are terminal options that check whether the input file seems to be of type 1D, local stim_times or global stim_times formats. The only associated options are currently -infile, -set_run_lens, -set_tr and -verb. They are terminal in that no other 1D-style actions are performed. See 'timing_tool.py -help' for details on stim_times operations. -looks_like_1D : is the file in 1D format Does the input data file seem to be in 1D format? - must be rectangular (same number of columns per row) - duration must match number of rows (if run lengths are given) -looks_like_AM : does the file have modulators? Does the file seem to be in local or global times format, and do the times have modulators? - amplitude modulators should use '*' format (e.g. 127.3*5.1) - duration modulators should use trailing ':' format (12*5.1:3.4) - number of amplitude modulators should be constant -looks_like_local_times : is the file in local stim_times format Does the input data file seem to be in the -stim_times format used by 3dDeconvolve (and timing_tool.py)? More specifically, is it the local format, with one scanning run per row. - number of rows must match number of runs - times cannot be negative - times must be unique per run (per row) - times cannot exceed the current run time -looks_like_global_times : is the file in global stim_times format Does the input data file seem to be in the -stim_times format used by 3dDeconvolve (and timing_tool.py)? More specifically, is it the global format, either as one long row or one long line? - must be one dimensional (either a single row or column) - times cannot be negative - times must be unique - times cannot exceed total duration of all runs -looks_like_test_all : run all -looks_like tests Applies all "looks like" test options: -looks_like_1D, -looks_like_AM, -looks_like_local_times and -looks_like_global_times. -overwrite : allow overwriting of any output dataset -pad_into_many_runs RUN NRUNS : pad as current run of num_runs e.g. -pad_into_many_runs 2 7 This option is used to create a longer time series dataset where the input is consider one particular run out of many. The output is padded with zero for all run TRs before and after this run. Given the example, there would be 1 run of zeros, then the input would be treated as run 2, and there would be 5 more runs of zeros. -quick_censor_count LIMIT : output # TRs that would be censored e.g. -quick_censor_count 0.3 This is akin to -censor_motion, but it only outputs the number of TRs that would be censored. It does not actually create a censor file. This option essentially replaces these: -derivative -demean -collapse_cols euclidean_norm -censor_prev_TR -verb 0 -show_censor_count -moderate_mask 0 LIMIT -rank : convert data to rank order 0-based index order of small to large values The default rank STYLE is 'dense'. See also -rank_style. -rank_style STYLE : convert to rank using the given style The STYLE refers to what to do in the case of repeated values. Assuming inputs 4 5 5 9... dense - repeats get same rank, no gaps in rank - same a "3dmerge -1rank" - result: 0 1 1 2 competition - repeats get same rank, leading to gaps in rank - same a "3dmerge -1rank" - result: 0 1 1 3 (case '2' is counted, though no such rank occurs) Option '-rank' uses style 'dense'. See also -rank. -reverse_rank : convert data to reverse rank order (large values come first) -reverse : reverse data over time -randomize_trs : randomize the data over time -seed SEED : set random number seed (integer) -select_groups g0 g1 ... : select columns by group numbers e.g. -select groups 0 e.g. -select groups POS 0 An X-matrix dataset (e.g. X.xmat.1D) often has columns partitioned by groups, such as: -1 : polort regressors 0 : motion regressors and other (non-polort) baseline terms N>0: regressors of interest This option can be used to select columns by integer groups, with special cases of POS (regs of interest), NEG (probably polort). Note that NONNEG is unneeded as it is the pair POS 0. See also -show_group_labels. -select_cols SELECTOR : apply AFNI column selectors, [] is optional e.g. '[5,0,7..21(2)]' e.g. '[aroma_mot*]' # aroma_motion e.g. '[rot_?,trans_?]' " 6 motion params -select_cols_via_TSV_table TABLE FIELD WHERE : use tsv TABLE to select FIELD elements where WHERE is true; resulting values are then taken as column headers to select from any -input tsv data file -select_rows SELECTOR : apply AFNI row selectors, {} is optional e.g. '{5,0,7..21(2)}' -select_runs r1 r2 ... : extract the given runs from the dataset (these are 1-based run indices) e.g. 2 e.g. 2 3 1 1 1 1 1 4 -set_nruns NRUNS : treat the input data as if it has nruns (e.g. applies to -derivative and -demean) See examples 7a, 10a and b, and 14. -set_run_lengths N1 N2 ... : treat as if data has run lengths N1, N2, etc. (applies to -derivative, for example) Notes: o option -set_nruns is not allowed with -set_run_lengths o the sum of run lengths must equal NT See examples 7b, 10c and 14. -set_tr TR : set the TR (in seconds) for the data -show_argmin : display the index of min arg (of first column) -show_censor_count : display the total number of censored TRs Note : if input is a valid xmat.1D dataset, then the count will come from the header. Otherwise the input is assumed to be a binary censor file, and zeros are simply counted. -show_cormat : display correlation matrix -show_cormat_warnings : display correlation matrix warnings (this does not include baseline terms) -show_cormat_warnings_full : display correlation matrix warnings (this DOES include baseline terms) -show_distmat : display distance matrix Expect input as one coordinate vector per row. Output NROWxNROW matrix of vector distances. See Example 15c. -show_df_info : display info about degrees of freedom (found in in xmat.1D formatted files) -show_df_protect yes/no : protection flag (def=yes) -show_gcor : display GCOR: the average correlation -show_gcor_all : display many ways of computing (a) GCOR -show_gcor_doc : display descriptions of those ways -show_group_labels : display group and label, per column -show_indices_baseline : display column indices for baseline -show_indices_interest : display column indices for regs of interest -show_indices_motion : display column indices for motion regressors -show_indices_zero : display column indices for all-zero columns -show_label_ordering : display the labels -show_labels : display the labels -show_max_displace : display max displacement (from motion params) - the maximum pairwise distance (enorm) -show_mmms : display min, mean, max, stdev of columns -show_num_runs : display number of runs found -show_regs PROPERTY : display regressors with the given property Show column indices or labels for those columns where PROPERTY holds: allzero : the entire column is exactly 0 set : (NOT allzero) the column has some set (non-zero) value How the columns are displayed is controlled by -show_regs_style (label, encoded, comma, space) and -verb (0, 1 or 2). With -verb > 0, the number of matching columns is also output. See also -show_regs_style, -verb. See example 30. -show_regs_style STYLE : use STYLE for how to -show_regs This only applies when using -show_regs, and specifies the style for how to show matching columns. space : show indices as a space-separated list comma : show indices as a comma-separated list encoded : succinct selector list (like sub-brick selectors) label : if xmat.1D has them, show space separated labels set : (NOT allzero) the column has some set (non-zero) value How the columns are displayed is controlled by -show_regs_style (label, encoded, comma, space) and -verb (0, 1 or 2). -show_rows_cols : display the number of rows and columns -show_slice_timing_pattern : display the to3d tpattern for the data e.g. -show_slice_timing_pattern -infile slice_times.txt The output will be 2 values, the multiband level (the number of sets of unique slice times) and the tpattern for those slice times. The tpattern will be one of those from 'to3d -help', such as alt+z. This operation is the reverse of -slice_pattern_to_times. See also -slice_pattern_to_times. See example 31 and example 32 -show_slice_timing_resolution : display the to3d tpattern for the data e.g. -show_slice_timing_resolution -infile slice_times.txt Display the apparent resolution of values expected to be on a grid, where zero is good. The slice times are supposed to be multiples of some constant C, such that the sorted list of unique values should be: {0*C, 1*C, 2*C, ..., (N-1)*C}. In such a case, the first diffs would all be C, and the second diffs would be zero. The displayed resolution would be zero. If the first diffs are not all exactly some constant C, the largest difference between those diffs should implicate the numerical resolution, like a truncation error. So display the largest first diff minus the smallest first diff. For Siemens data, this might be 0.025 (2.5 ms), as reported by D Glen. See also -show_slice_timing_pattern. See example 31. -show_tr_run_counts STYLE : display TR counts per run, according to STYLE STYLE can be one of: trs : TR counts trs_cen : censored TR counts trs_no_cen : TR counts, as if no censoring frac_cen : fractions of TRs censored See example 24. -show_trs_censored STYLE : display a list of TRs which were censored -show_trs_uncensored STYLE : display a list of TRs which were not censored STYLE can be one of: comma : comma delimited space : space delimited encoded : succinct selector list verbose : chatty See example 20. -show_trs_run RUN : restrict -show_trs_[un]censored to the given 1-based run -show_trs_to_zero : display number of TRs before final zero value (e.g. length of response curve) -show_xmat_stype_cols T1 ... : display columns of the given class types Display the columns (labels, indices or encoded) of the given stimulus types. These types refer specifically to those with basis functions, and correspond with 3dDeconvolve -stim_* options as follows: times : -stim_times AM : -stim_times_AM1 or -stim_times_AM2 AM1 : -stim_times_AM1 AM2 : -stim_times_AM2 IM : -stim_times_IM Multiple types can be provided. See example 5f. See also -show_regs_style. -show_xmat_stim_info CLASS : display information for the given stim class (CLASS can be a specific one, or 'ALL') Display information for a specific (3dDeconvolve -stim_*) stim class. This includes the class Name, the 3dDeconvolve Option, the basis Function, and the relevant Columns of the X-matrix. See example 5e. See also -show_regs_style. -show_group_labels : display group and label, per column -slice_order_to_times : convert a list of slice indices to times Programs like to3d, 3drefit, 3dTcat and 3dTshift expect slice timing to be a list of slice times over the sequential slices. But in some cases, people have an ordered list of slices. So the sorting needs to change. input: a file with TIME-SORTED slice indices output: a SLICE-SORTED list of slice times * Note, this is a list of slice indices over time (one TR interval). Across one TR, this lists each slice index as acquired. It IS a per-slice-time index of acquired slices. It IS **NOT** a per-slice index of its acquisition position. (this latter case could be output by -slice_pattern_to_times) If TR=2 and the slice order is alt+z: 0 2 4 6 8 1 3 5 7 9 Then the slices/times ordered by time (as input) are: times: 0.0 0.2 0.4 0.6 0.8 1.0 1.2 1.4 1.6 1.8 input-> slices: 0 2 4 6 8 1 3 5 7 9 (slices across time) And the slices/times ordered instead by slice index are: slices: 0 1 2 3 4 5 6 7 8 9 output-> times: 0.0 1.0 0.2 1.2 0.4 1.4 0.6 1.6 0.8 1.8 (timing across slices) It is this final list of times that is output. For kicks, note that one can convert from per-time slice indices to per-slice acquisition indices by setting TR=nslices. See example 28. -slice_pattern_to_times PAT NS MB : output slice timing, given: slice pattern, nslices, MBlevel (TR is optionally set via -set_tr) e.g. -slice_pattern_to_times alt+z 30 1 -set_tr 2.0 Input description: PAT : a valid to3d-style slice timing pattern, one of: zero simult seq+z seqplus seq-z seqminus alt+z altplus alt+z2 alt-z altminus alt-z2 NS : the total number of slices (MB * nunique_times) MB : the multiband level For a volume with NS slices and multiband MB and a slice timing pattern PAT with NST unique slice times, we must have: NS = MB * NST TR : (optional) the volume repetition time TR is specified via -set_tr. Output the appropriate slice times for the timing pattern, also given the number of slices, multiband level and TR. If TR is not specified, the output will be as if TR=NST (number of unique slice times), which means the output is order index of each slice. This operation is the reverse of -show_slice_timing_pattern. See also -show_slice_timing_pattern, -show_slice_timing_resolution. See example 32. -sort : sort data over time (smallest to largest) - sorts EVERY vector - consider the -reverse option -split_into_pad_runs PREFIX : split input into one padded file per run e.g. -split_into_pad_runs motion.pad This option is used for breaking a set of regressors up by run. The output would be one file per run, where each file is the same as the input for the run it corresponds to, and is padded with 0 across all other runs. Assuming the 300 row input dataset spans 3 100-TR runs, then there would be 3 output datasets created, each still be 300 rows: motion.pad.r01.1D : 100 rows as input, 200 rows of 0 motion.pad.r02.1D : 100 rows of 0, 100 rows as input, 100 of 0 motion.pad.r03.1D : 200 rows of 0, 100 rows as input This option requires either -set_nruns or -set_run_lengths. See example 14. -transpose : transpose the input matrix (rows for columns) -transpose_write : transpose the output matrix before writing -volreg2allineate : convert 3dvolreg parameters to 3dAllineate This option should be used when the -infile file is a 6 column file of motion parameters (roll, pitch, yaw, dS, dL, dP). The output would be converted to a 12 parameter file, suitable for input to 3dAllineate via the -1Dparam_apply option. volreg: roll, pitch, yaw, dS, dL, dP 3dAllinate: -dL, -dP, -dS, roll, pitch, yaw, 0,0,0, 0,0,0 These parameters would be to correct the motion, akin to what 3dvolreg did (i.e. they are the negative estimates of how the subject moved). See example 23. -write FILE : write the current 1D data to FILE -write_sep SEP : use SEP for column separators -write_style STYLE : write using one of the given styles basic: the default, don't work too hard ljust: left-justified columns of the same width rjust: right-justified columns of the same width tsv: tab-separated (use <tab> as in -write_sep '\t') -weight_vec v1 v2 ... : supply weighting vector e.g. -weight_vec 0.9 0.9 0.9 1 1 1 This vector currently works only with the weighted_enorm method for the -collapse_cols option. If supplied (as with the example), it will weight the angles at 0.9 times the weights of the shifts in the motion parameters output by 3dvolreg. See also -collapse_cols. -write_censor FILE : write as boolean censor.1D e.g. -write_censor subjA_censor.1D This file can be given to 3dDeconvolve to censor TRs with excessive motion, applied with the -censor option. e.g. 3dDeconvolve -censor subjA_censor.1D This file works well for plotting against the data, where the 0 entries are removed from the regression of 3dDeconvolve. Alternatively, the file created with -write_CENSORTR is probably more human readable. -write_CENSORTR FILE : write censor times as CENSORTR string e.g. -write_CENSORTR subjA_CENSORTR.txt This file can be given to 3dDeconvolve to censor TRs with excessive motion, applied with the -CENSORTR option. e.g. 3dDeconvolve -CENSORTR `cat subjA_CENSORTR.txt` Which might expand to: 3dDeconvolve -CENSORTR '1:16..19,44 3:28 4:19,37..39' Note that the -CENSORTR option requires the text on the command line. This file is in the easily readable format applied with -CENSORTR. It has the same effect on 3dDeconvolve as the sister file from -write_censor, above. -verb LEVEL : set the verbosity level ----------------------------------------------------------------------------- R Reynolds March 2009 =============================================================================

AFNI program: 1dtranspose
Usage: 1dtranspose infile outfile where infile is an AFNI *.1D file (ASCII list of numbers arranged in columns); outfile will be a similar file, but transposed. You can use a column subvector selector list on infile, as in 1dtranspose 'fred.1D[0,3,7]' ethel.1D * This program may produce files with lines longer than a text editor can handle. * If 'outfile' is '-' (or missing entirely), output goes to stdout. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dTsort
Usage: 1dTsort [options] file.1D Sorts each column of the input 1D file and writes result to stdout. Options ------- -inc = sort into increasing order [default] -dec = sort into decreasing order -flip = transpose the file before OUTPUT * the INPUT can be transposed using file.1D\' * thus, to sort each ROW, do something like 1dTsort -flip file.1D\' > sfile.1D -col j = sort only on column #j (counting starts at 0), and carry the rest of the columns with it. -imode = typecast all values to integers, return the mode in the input then exit. No sorting results are returned. N.B.: Data will be read from standard input if the filename IS stdin, and will also be row/column transposed if the filename is stdin\' For example: 1deval -num 100 -expr 'uran(1)' | 1dTsort stdin | 1dplot stdin ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 1dUpsample
Program 1dUpsample: Upsamples a 1D time series (along the column direction) to a finer time grid. Usage: 1dUpsample [options] n fred.1D > ethel.1D Where 'n' is the upsample factor (integer from 2..32) NOTES: ------ * Interpolation is done with 7th order polynomials. (Why 7? It's a nice number, and the code already existed.) * The only option is '-1' or '-one', to use 1st order polynomials instead (i.e., linear interpolation). * Output is written to stdout. * If you want to interpolate along the row direction, transpose before input, then transpose the output. * Example: 1dUpsample 5 '1D: 4 5 4 3 4' | 1dplot -stdin -dx 0.2 * If the input has M time points, the output will have n*M time points. The last n-1 of them will be past the end of the original time series. * This program is a quick hack for Gang Chen. Where are my Twizzlers?

AFNI program: 24swap
Usage: 24swap [options] file ... Swaps bytes pairs and/or quadruples on the files listed. Options: -q Operate quietly -pattern pat 'pat' determines the pattern of 2 and 4 byte swaps. Each element is of the form 2xN or 4xN, where N is the number of bytes to swap as pairs (for 2x) or as quadruples (for 4x). For 2x, N must be divisible by 2; for 4x, N must be divisible by 4. The whole pattern is made up of elements separated by colons, as in '-pattern 4x39984:2x0'. If bytes are left over after the pattern is used up, the pattern starts over. However, if a byte count N is zero, as in the example below, then it means to continue until the end of file. N.B.: You can also use 1xN as a pattern, indicating to skip N bytes without any swapping. N.B.: A default pattern can be stored in the Unix environment variable AFNI_24SWAP_PATTERN. If no -pattern option is given, the default will be used. If there is no default, then nothing will be done. N.B.: If there are bytes 'left over' at the end of the file, they are written out unswapped. This will happen if the file is an odd number of bytes long. N.B.: If you just want to swap pairs, see program 2swap. For quadruples only, see program 4swap. N.B.: This program will overwrite the input file! You might want to test it first. Example: 24swap -pat 4x8:2x0 fred If fred contains 'abcdabcdabcdabcdabcd' on input, then fred has 'dcbadcbabadcbadcbadc' on output.

AFNI program: 2dcat
Usage: 2dcat [options] fname1 fname2 etc. Puts a set images into an image matrix (IM) montage of NX by NY images. The minimum set of input is N images (N >= 1). If need be, the default is to reuse images until the desired NX by NY size is achieved. See options -zero_wrap and -image_wrap for more detail. OPTIONS: ++ Options for editing, coloring input images: -scale_image SCALE_IMG: Multiply each image IM(i,j) in output image matrix IM by the color or intensity of the pixel (i,j) in SCALE_IMG. -scale_pixels SCALE_PIX: Multiply each pixel (i,j) in output image by the color or intensity of the pixel (i,j) in SCALE_IMG. SCALE_IMG is automatically resized to the resolution of the output image. -scale_intensity: Instead of multiplying by the color of pixel (i,j), use its intensity (average color) -gscale FAC: Apply FAC in addition to scaling of -scale_* options -rgb_out: Force output to be in rgb, even if input is bytes. This option is turned on automatically in certain cases. -res_in RX RY: Set resolution of all input images to RX by RY pixels. Default is to make all input have the same resolution as the first image. -respad_in RPX RPY: Like -res_in, but resample to the max while respecting the aspect ratio, and then pad to achieve desired pixel count. -pad_val VAL: Set the padding value, should it be needed by -respad_in to VAL. VAL is typecast to byte, default is 0, max is 255. -crop L R T B: Crop images by L (Left), R (Right), T (Top), B (Bottom) pixels. Cutting is performed after any resolution change, if any, is to be done. -autocrop_ctol CTOL: A line is eliminated if none of its R G B values differ by more than CTOL% from those of the corner pixel. -autocrop_atol ATOL: A line is eliminated if none of its R G B values differ by more than ATOL% from those of line average. -autocrop: This option is the same as using both of -autocrop_atol 20 and -autocrop_ctol 20 NOTE: Do not mix -autocrop* options with -crop Cropping is determined from the 1st input image and applied to to all remaining ones. ++ Options for output: -zero_wrap: If number of images is not enough to fill matrix solid black images are used. -white_wrap: If number of images is not enough to fill matrix solid white images are used. -gray_wrap GRAY: If number of images is not enough to fill matrix solid gray images are used. GRAY must be between 0 and 1.0 -image_wrap: If number of images is not enough to fill matrix images on command line are reused (default) -rand_wrap: When reusing images to fill matrix, randomize the order in refill section only. -prefix ppp = Prefix the output files with string 'ppp' Note: If the prefix ends with .1D, then a 1D file containing the average of RGB values. You can view the output with 1dgrayplot. -matrix NX NY: Specify number of images in each row and column of IM at the same time. -nx NX: Number of images in each row (3 for example below) -ny NY: Number of images in each column (4 for example below) Example: If 12 images appearing on the command line are to be assembled into a 3x4 IM matrix they would appear in this order: 0 1 2 3 4 5 6 7 8 9 10 11 NOTE: The program will try to guess if neither NX nor NY are specified. -matrix_from_scale: Set NX and NY to be the same as the SCALE_IMG's dimensions. (needs -scale_image) -gap G: Put a line G pixels wide between images. -gap_col R G B: Set color of line to R G B values. Values range between 0 and 255. Example 0 (assuming afni is in ~/abin directory): Resizing an image: 2dcat -prefix big -res_in 1024 1024 \ ~/abin/funstuff/face_zzzsunbrain.jpg 2dcat -prefix small -res_in 64 64 \ ~/abin/funstuff/face_zzzsunbrain.jpg aiv small.ppm big.ppm Example 1: Stitching together images: (Can be used to make very high resolution SUMA images. Read about 'Ctrl+r' in SUMA's GUI help.) 2dcat -prefix cat -matrix 14 12 \ ~/abin/funstuff/face_*.jpg aiv cat.ppm Example 2: Stitching together 3 images getting rid of annoying white boundary: 2dcat -prefix surfview_pry3b.jpg -ny 1 -autocrop surfview.000[789].jpg Example 20 (assuming afni is in ~/abin directory): 2dcat -prefix bigcat.jpg -scale_image ~/abin/afnigui_logo.jpg \ -matrix_from_scale -rand_wrap -rgb_out -respad_in 128 128 \ -pad_val 128 ~/abin/funstuff/face_*.jpg aiv bigcat.jpg bigcat.jpg Crop/Zoom in to see what was done. In practice, you want to use a faster image viewer to examine the result. Zooming on such a large image is not fast in aiv. Be careful with this toy. Images get real big, real quick. You can look at the output image file with afni -im ppp.ppm [then open the Sagittal image window] Deprecation warning: The imcat program will be replaced by 2dcat in the future.

AFNI program: 2dImReg
++ 2dImReg: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] This program performs 2d image registration. Image alignment is performed on a slice-by-slice basis for the input 3d+time dataset, relative to a user specified base image. ** Note that the script @2dwarper.Allin can do similar things, ** ** with nonlinear (polynomial) warping on a slice-wise basis. ** Usage: 2dImReg -input fname Filename of input 3d+time dataset to process -basefile fname Filename of 3d+time dataset for base image (default = current input dataset) -base num Time index for base image (0 <= num) (default: num = 3) -nofine Deactivate fine fit phase of image registration (default: fine fit is active) -fine blur dxy dphi Set fine fit parameters where: blur = FWHM of blurring prior to registration (in pixels) (default: blur = 1.0) dxy = Convergence tolerance for translations (in pixels) (default: dxy = 0.07) dphi = Convergence tolerance for rotations (in degrees) (default: dphi = 0.21) -prefix pname Prefix name for output 3d+time dataset -dprefix dname Write files 'dname'.dx, 'dname'.dy, 'dname'.psi containing the registration parameters for each slice in chronological order. File formats: 'dname'.dx: time(sec) dx(pixels) 'dname'.dy: time(sec) dy(pixels) 'dname'.psi: time(sec) psi(degrees) -dmm Change dx and dy output format from pixels to mm -rprefix rname Write files 'rname'.oldrms and 'rname'.newrms containing the volume RMS error for the original and the registered datasets, respectively. File formats: 'rname'.oldrms: volume(number) rms_error 'rname'.newrms: volume(number) rms_error -debug Lots of additional output to screen

AFNI program: @2dwarper.Allin
script to do 2D registration on each slice of a 3D+time dataset, and glue the results back together at the end This script is structured to operate only on an AFNI +orig.HEAD dataset. The one input on the command line is the prefix for the dataset. Modified 07 Dec 2010 by RWC to use 3dAllineate instead of 3dWarpDrive, with nonlinear slice-wise warping. Set prefix of input 3D+time dataset here. In this example with 'wilma' as the command line argument, the output dataset will be 'wilma_reg+orig'. The output registration parameters files will be 'wilma_param_ssss.1D', where 'ssss' is the slice number. usage: @2dwarper.Allin [options] INPUT_PREFIX example: @2dwarper.Allin epi_run1 example: @2dwarper.Allin -mask my_mask epi_run1 options: -mask MSET : provide the prefix of an existing mask dataset -prefix PREFIX : provide the prefix for output datasets

AFNI program: 2perm
Usage: 2perm [-prefix PPP] [-comma] bot top [n1 n2] This program creates 2 random non-overlapping subsets of the set of integers from 'bot' to 'top' (inclusive). The first subset is of length 'n1' and the second of length 'n2'. If those values are not given, then equal size subsets of length (top-bot+1)/2 are used. This program is intended for use in various simulation and/or randomization scripts, or for amusement/hilarity. OPTIONS: ======== -prefix PPP == Two output files are created, with names PPP_A and PPP_B, where 'PPP' is the given prefix. If no '-prefix' option is given, then the string 'AFNIroolz' will be used. ++ Each file is a single column of numbers. ++ Note that the filenames do NOT end in '.1D'. -comma == Write each file as a single row of comma-separated numbers. EXAMPLE: ======== This illustration shows the purpose of 2perm -- for use in permutation and/or randomization tests of statistical significance and power. Given a dataset with 100 sub-bricks (indexed 0..99), split it into two random halves and do a 2-sample t-test between them. 2perm -prefix Q50 0 99 3dttest++ -setA dataset+orig"[1dcat Q50_A]" \ -setB dataset+orig"[1dcat Q50_B]" \ -no1sam -prefix Q50 \rm -f Q50_? Alternatively: 2perm -prefix Q50 -comma 0 99 3dttest++ -setA dataset+orig"[`cat Q50_A`]" \ -setB dataset+orig"[`cat Q50_B`]" \ -no1sam -prefix Q50 \rm -f Q50_? Note the combined use of the double quote " and backward quote ` shell operators in this second approach. AUTHOR: (no one want to admit they wrote this trivial code). ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 2swap
Usage: 2swap [-q] file ... -- Swaps byte pairs on the files listed. The -q option means to work quietly.

AFNI program: 3dABoverlap
Usage: 3dABoverlap [options] A B Output (to screen) is a count of various things about how the automasks of datasets A and B overlap or don't overlap. * Dataset B will be resampled to match dataset A, if necessary, which will be slow if A is high resolution. In such a case, you should only use one sub-brick from dataset B. ++ The resampling of B is done before the automask is generated. * The values output are labeled thusly: #A = number of voxels in the A mask #B = number of voxels in the B mask #(A uni B) = number of voxels in the either or both masks (set union) #(A int B) = number of voxels present in BOTH masks (set intersection) #(A \ B) = number of voxels in A mask that aren't in B mask #(B \ A) = number of voxels in B mask that aren't in A mask %(A \ B) = percentage of voxels from A mask that aren't in B mask %(B \ A) = percentage of voxels from B mask that aren't in A mask Rx(B/A) = radius of gyration of B mask / A mask, in x direction Ry(B/A) = radius of gyration of B mask / A mask, in y direction Rz(B/A) = radius of gyration of B mask / A mask, in z direction * If B is an EPI dataset sub-brick, and A is a skull stripped anatomical dataset, then %(B \ A) might be useful for assessing if the EPI brick B is grossly misaligned with respect to the anatomical brick A. * The radius of gyration ratios might be useful for determining if one dataset is grossly larger or smaller than the other. OPTIONS ------- -no_automask = consider input datasets as masks (automask does not work on mask datasets) -quiet = be as quiet as possible (without being entirely mute) -verb = print out some progress reports (to stderr) NOTES ----- * If an input dataset is comprised of bytes and contains only one sub-brick, then this program assumes it is already an automask- generated dataset and the automask operation will be skipped. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAFNIto3D
[7m*+ WARNING:[0m This program (3dAFNIto3D) is old, not maintained, and probably useless! Usage: 3dAFNIto3D [options] dataset Reads in an AFNI dataset, and writes it out as a 3D file. OPTIONS: -prefix ppp = Write result into file ppp.3D; default prefix is same as AFNI dataset's. -bin = Write data in binary format, not text. -txt = Write data in text format, not binary. NOTES: * At present, all bricks are written out in float format. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAFNItoANALYZE
[7m*+ WARNING:[0m This program (3dAFNItoANALYZE) is old, not maintained, and probably useless! Usage: 3dAFNItoANALYZE [-4D] [-orient code] aname dset Writes AFNI dataset 'dset' to 1 or more ANALYZE 7.5 format .hdr/.img file pairs (one pair for each sub-brick in the AFNI dataset). The ANALYZE files will be named aname_0000.hdr aname_0000.img for sub-brick #0 aname_0001.hdr aname_0001.img for sub-brick #1 and so forth. Each file pair will contain a single 3D array. * If the AFNI dataset does not include sub-brick scale factors, then the ANALYZE files will be written in the datum type of the AFNI dataset. * If the AFNI dataset does have sub-brick scale factors, then each sub-brick will be scaled to floating format and the ANALYZE files will be written as floats. * The .hdr and .img files are written in the native byte order of the computer on which this program is executed. Options ------- -4D [30 Sep 2002]: If you use this option, then all the data will be written to one big ANALYZE file pair named aname.hdr/aname.img, rather than a series of 3D files. Even if you only have 1 sub-brick, you may prefer this option, since the filenames won't have the '_0000' appended to 'aname'. -orient code [19 Mar 2003]: This option lets you flip the dataset to a different orientation when it is written to the ANALYZE files. The orientation code is formed as follows: The code must be 3 letters, one each from the pairs {R,L} {A,P} {I,S}. The first letter gives the orientation of the x-axis, the second the orientation of the y-axis, the third the z-axis: R = Right-to-Left L = Left-to-Right A = Anterior-to-Posterior P = Posterior-to-Anterior I = Inferior-to-Superior S = Superior-to-Inferior For example, 'LPI' means -x = Left +x = Right -y = Posterior +y = Anterior -z = Inferior +z = Superior * For display in SPM, 'LPI' or 'RPI' seem to work OK. Be careful with this: you don't want to confuse L and R in the SPM display! * If you DON'T use this option, the dataset will be written out in the orientation in which it is stored in AFNI (e.g., the output of '3dinfo dset' will tell you this.) * The dataset orientation is NOT stored in the .hdr file. * AFNI and ANALYZE data are stored in files with the x-axis varying most rapidly and the z-axis most slowly. * Note that if you read an ANALYZE dataset into AFNI for display, AFNI assumes the LPI orientation, unless you set environment variable AFNI_ANALYZE_ORIENT. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAFNItoNIFTI
Usage: 3dAFNItoNIFTI [options] dataset Reads an AFNI dataset, writes it out as a NIfTI-1.1 file. NOTES: * The nifti_tool program can be used to manipulate the contents of a NIfTI-1.1 file. * The input dataset can actually be in any input format that AFNI can read directly (e.g., MINC-1). * There is no 3dNIFTItoAFNI program, since AFNI programs can directly read .nii files. If you wish to make such a conversion anyway, one way to do so is like so: 3dcalc -a ppp.nii -prefix ppp -expr 'a' OPTIONS: -prefix ppp = Write the NIfTI-1.1 file as 'ppp.nii'. Default: the dataset's prefix is used. * You can use 'ppp.hdr' to output a 2-file NIfTI-1.1 file pair 'ppp.hdr' & 'ppp.img'. * If you want a compressed file, try using a prefix like 'ppp.nii.gz'. * Setting the Unix environment variable AFNI_AUTOGZIP to YES will result in all output .nii files being gzip-ed. -verb = Be verbose = print progress messages. Repeating this increases the verbosity (maximum setting is 3 '-verb' options). -float = Force the output dataset to be 32-bit floats. This option should be used when the input AFNI dataset has different float scale factors for different sub-bricks, an option that NIfTI-1.1 does not support. The following options affect the contents of the AFNI extension field that is written by default into the NIfTI-1.1 header: -pure = Do NOT write an AFNI extension field into the output file. Only use this option if needed. You can also use the 'nifti_tool' program to strip extensions from a file. -denote = When writing the AFNI extension field, remove text notes that might contain subject identifying information. -oldid = Give the new dataset the input dataset's AFNI ID code. -newid = Give the new dataset a new AFNI ID code, to distinguish it from the input dataset. **** N.B.: -newid is now the default action. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAFNItoNIML
Usage: 3dAFNItoNIML [options] dset Dumps AFNI dataset header information to stdout in NIML format. Mostly for debugging and testing purposes! OPTIONS: -data == Also put the data into the output (will be huge). -ascii == Format in ASCII, not binary (even huger). -tcp:host:port == Instead of stdout, send the dataset to a socket. (implies '-data' as well) -- RWCox - Mar 2005 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAFNItoRaw
[7m*+ WARNING:[0m This program (3dAFNItoRaw) is old, not maintained, and probably useless! Usage: 3dAFNItoRaw [options] dataset Convert an AFNI brik file with multiple sub-briks to a raw file with each sub-brik voxel concatenated voxel-wise. For example, a dataset with 3 sub-briks X,Y,Z with elements x1,x2,x3,...,xn, y1,y2,y3,...,yn and z1,z2,z3,...,zn will be converted to a raw dataset with elements x1,y1,z1, x2,y2,z2, x3,y3,z3, ..., xn,yn,zn The dataset is kept in the original data format (float/short/int) Options: -output / -prefix = name of the output file (not an AFNI dataset prefix) the default output name will be rawxyz.dat -datum float = force floating point output. Floating point forced if any sub-brik scale factors not equal to 1. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAllineate
Usage: 3dAllineate [options] sourcedataset -------------------------------------------------------------------------- Program to align one dataset (the 'source') to a 'base' dataset, using an affine (matrix) transformation of space. -------------------------------------------------------------------------- -------------------------------------------------------------------------- ***** Please check your results visually, or at some point ***** ***** in time you will have bad results and not know it :-( ***** ***** ***** ***** No method for 3D image alignment, however tested it ***** ***** was, can be relied upon 100% of the time, and anyone ***** ***** who tells you otherwise is a madman or is a liar!!!! ***** ***** ***** ***** In particular, if you are aligning two datasets with ***** ***** significantly different spatial coverage (e.g., ***** ***** -source = whole head T1w and -base = MNI template), ***** ***** the be careful to check the results. In such a case, ***** ***** using '-twobest MAX' should increase the chance of ***** ***** getting a good alignment (at the cost of CPU time). ***** ***** ***** ***** Furthermore, don't EVER think that "I have so much ***** ***** data that a few errors will not matter"!!!! ***** -------------------------------------------------------------------------- * Options (lots of them!) are available to control: ++ How the matching between the source and the base is computed (i.e., the 'cost functional' measuring image mismatch). ++ How the resliced source is interpolated to the base space. ++ The complexity of the spatial transformation ('warp') used. ++ And many many technical options to control the process in detail, if you know what you are doing (or just like to fool around). * This program is a generalization of and improvement on the older software 3dWarpDrive. * For nonlinear transformations, see program 3dQwarp. * 3dAllineate can also be used to apply a pre-computed matrix to a dataset to produce the transformed output. In this mode of operation, it just skips the alignment process, whose function is to compute the matrix, and instead it reads the matrix in, computes the output dataset, writes it out, and stops. * If you are curious about the stepwise process used, see the section below titled: SUMMARY of the Default Allineation Process. =====---------------------------------------------------------------------- NOTES: For most 3D image registration purposes, we now recommend that you ===== use Daniel Glen's script align_epi_anat.py (which, despite its name, can do many more registration problems than EPI-to-T1-weighted). -->> In particular, using 3dAllineate with the 'lpc' cost functional (to align EPI and T1-weighted volumes) requires using a '-weight' volume to get good results, and the align_epi_anat.py script will automagically generate such a weight dataset that works well for EPI-to-structural alignment. -->> This script can also be used for other alignment purposes, such as T1-weighted alignment between field strengths using the '-lpa' cost functional. Investigate align_epi_anat.py to see if it will do what you need -- you might make your life a little easier and nicer and happier and more tranquil. -->> Also, if/when you ask for registration help on the AFNI message board, we'll probably start by recommending that you try align_epi_anat.py if you haven't already done so. -->> For aligning EPI and T1-weighted volumes, we have found that using a flip angle of 50-60 degrees for the EPI works better than a flip angle of 90 degrees. The reason is that there is more internal contrast in the EPI data when the flip angle is smaller, so the registration has some image structure to work with. With the 90 degree flip angle, there is so little internal contrast in the EPI dataset that the alignment process ends up being just trying to match brain outlines -- which doesn't always give accurate results: see http://dx.doi.org/10.1016/j.neuroimage.2008.09.037 -->> Although the total MRI signal is reduced at a smaller flip angle, there is little or no loss in FMRI/BOLD information, since the bulk of the time series 'noise' is from physiological fluctuation signals, which are also reduced by the lower flip angle -- for more details, see http://dx.doi.org/10.1016/j.neuroimage.2010.11.020 --------------------------------------------------------------------------- **** New (Summer 2013) program 3dQwarp is available to do nonlinear **** *** alignment between a base and source dataset, including the use *** ** of 3dAllineate for the preliminary affine alignment. If you are ** * interested, see the output of '3dQwarp -help' for the details. * --------------------------------------------------------------------------- COMMAND LINE OPTIONS: ==================== -base bbb = Set the base dataset to be the #0 sub-brick of 'bbb'. If no -base option is given, then the base volume is taken to be the #0 sub-brick of the source dataset. (Base must be stored as floats, shorts, or bytes.) ** -base is not needed if you are just applying a given transformation to the -source dataset to produce the output, using -1Dmatrix_apply or -1Dparam_apply ** Unless you use the -master option, the aligned output dataset will be stored on the same 3D grid as the -base dataset. -source ttt = Read the source dataset from 'ttt'. If no -source *OR* (or -input) option is given, then the source dataset -input ttt is the last argument on the command line. (Source must be stored as floats, shorts, or bytes.) ** This is the dataset to be transformed, to match the -base dataset, or directly with one of the options -1Dmatrix_apply or -1Dparam_apply ** 3dAllineate can register 2D datasets (single slice), but both the base and source must be 2D -- you cannot use this program to register a 2D slice into a 3D volume! -- However, the 'lpc' and 'lpa' cost functionals do not work properly with 2D images, as they are designed around local 3D neighborhoods and that code has not been patched to work with 2D neighborhoods :( -- You can input .jpg files as 2D 'datasets', register them with 3dAllineate, and write the result back out using a prefix that ends in '.jpg'; HOWEVER, the color information will not be used in the registration, as this program was written to deal with monochrome medical datasets. At the end, if the source was RGB (color), then the output will be also be RGB, and then a color .jpg can be output. -- The above remarks also apply to aligning 3D RGB datasets: it will be done using only the 3D volumes converted to grayscale, but the final output will be the source RGB dataset transformed to the (hopefully) aligned grid. * However, I've never tested aligning 3D color datasets; you can be the first one ever! ** See the script @2dwarper.Allin for an example of using 3dAllineate to do slice-by-slice nonlinear warping to align 3D volumes distorted by time-dependent magnetic field inhomogeneities. ** NOTA BENE: The base and source dataset do NOT have to be defined ** ** [that's] on the same 3D grids; the alignment process uses the ** ** [Latin ] coordinate systems defined in the dataset headers to ** ** [ for ] make the match between spatial locations, rather than ** ** [ NOTE ] matching the 2 datasets on a voxel-by-voxel basis ** ** [ WELL ] (as 3dvolreg and 3dWarpDrive do). ** ** -->> However, this coordinate-based matching requires that ** ** image volumes be defined on roughly the same patch of ** ** of (x,y,z) space, in order to find a decent starting ** ** point for the transformation. You might need to use ** ** the script @Align_Centers to do this, if the 3D ** ** spaces occupied by the images do not overlap much. ** ** -->> Or the '-cmass' option to this program might be ** ** sufficient to solve this problem, maybe, with luck. ** ** (Another reason why you should use align_epi_anat.py) ** ** -->> If the coordinate system in the dataset headers is ** ** WRONG, then 3dAllineate will probably not work well! ** ** And I say this because we have seen this in several ** ** datasets downloaded from online archives. ** -prefix ppp = Output the resulting dataset to file 'ppp'. If this *OR* option is NOT given, no dataset will be output! The -out ppp transformation matrix to align the source to the base will be estimated, but not applied. You can save the matrix for later use using the '-1Dmatrix_save' option. *N.B.: By default, the new dataset is computed on the grid of the base dataset; see the '-master' and/or the '-mast_dxyz' options to change this grid. *N.B.: If 'ppp' is 'NULL', then no output dataset will be produced. This option is for compatibility with 3dvolreg. -floatize = Write result dataset as floats. Internal calculations -float are all done on float copies of the input datasets. [Default=convert output dataset to data format of ] [ source dataset; if the source dataset was ] [ shorts with a scale factor, then the new ] [ dataset will get a scale factor as well; ] [ if the source dataset was shorts with no ] [ scale factor, the result will be unscaled.] -1Dparam_save ff = Save the warp parameters in ASCII (.1D) format into file 'ff' (1 row per sub-brick in source). * A historical synonym for this option is '-1Dfile'. * At the top of the saved 1D file is a #comment line listing the names of the parameters; those parameters that are fixed (e.g., via '-parfix') will be marked by having their symbolic names end in the '$' character. You can use '1dcat -nonfixed' to remove these columns from the 1D file if you just want to further process the varying parameters somehow (e.g., 1dsvd). * However, the '-1Dparam_apply' option requires the full list of parameters, including those that were fixed, in order to work properly! -1Dparam_apply aa = Read warp parameters from file 'aa', apply them to the source dataset, and produce a new dataset. (Must also use the '-prefix' option for this to work! ) (In this mode of operation, there is no optimization of) (the cost functional by changing the warp parameters; ) (previously computed parameters are applied directly. ) *N.B.: If you use -1Dparam_apply, you may also want to use -master to control the grid on which the new dataset is written -- the base dataset from the original 3dAllineate run would be a good possibility. Otherwise, the new dataset will be written out on the 3D grid coverage of the source dataset, and this might result in clipping off part of the image. *N.B.: Each row in the 'aa' file contains the parameters for transforming one sub-brick in the source dataset. If there are more sub-bricks in the source dataset than there are rows in the 'aa' file, then the last row is used repeatedly. *N.B.: A trick to use 3dAllineate to resample a dataset to a finer grid spacing: 3dAllineate -input dataset+orig \ -master template+orig \ -prefix newdataset \ -final wsinc5 \ -1Dparam_apply '1D: 12@0'\' Here, the identity transformation is specified by giving all 12 affine parameters as 0 (note the extra \' at the end of the '1D: 12@0' input!). ** You can also use the word 'IDENTITY' in place of '1D: 12@0'\' (to indicate the identity transformation). **N.B.: Some expert options for modifying how the wsinc5 method works are described far below, if you use '-HELP' instead of '-help'. ****N.B.: The interpolation method used to produce a dataset is always given via the '-final' option, NOT via '-interp'. If you forget this and use '-interp' along with one of the 'apply' options, this program will chastise you (gently) and change '-final' to match what the '-interp' input. -1Dmatrix_save ff = Save the transformation matrix for each sub-brick into file 'ff' (1 row per sub-brick in the source dataset). If 'ff' does NOT end in '.1D', then the program will append '.aff12.1D' to 'ff' to make the output filename. *N.B.: This matrix is the coordinate transformation from base to source DICOM coordinates. In other terms: Xin = Xsource = M Xout = M Xbase or Xout = Xbase = inv(M) Xin = inv(M) Xsource where Xin or Xsource is the 4x1 coordinates of a location in the input volume. Xout is the coordinate of that same location in the output volume. Xbase is the coordinate of the corresponding location in the base dataset. M is ff augmented by a 4th row of [0 0 0 1], X. is an augmented column vector [x,y,z,1]' To get the inverse matrix inv(M) (source to base), use the cat_matvec program, as in cat_matvec fred.aff12.1D -I -1Dmatrix_apply aa = Use the matrices in file 'aa' to define the spatial transformations to be applied. Also see program cat_matvec for ways to manipulate these matrix files. *N.B.: You probably want to use either -base or -master with either *_apply option, so that the coordinate system that the matrix refers to is correctly loaded. ** You can also use the word 'IDENTITY' in place of a filename to indicate the identity transformation -- presumably for the purpose of resampling the source dataset to a new grid. * The -1Dmatrix_* options can be used to save and reuse the transformation * * matrices. In combination with the program cat_matvec, which can multiply * * saved transformation matrices, you can also adjust these matrices to * * other alignments. These matrices can also be combined with nonlinear * * warps (from 3dQwarp) using programs 3dNwarpApply or 3dNwarpCat. * * The script 'align_epi_anat.py' uses 3dAllineate and 3dvolreg to align EPI * * datasets to T1-weighted anatomical datasets, using saved matrices between * * the two programs. This script is our currently recommended method for * * doing such intra-subject alignments. * -cost ccc = Defines the 'cost' function that defines the matching between the source and the base; 'ccc' is one of ls *OR* leastsq = Least Squares [Pearson Correlation] mi *OR* mutualinfo = Mutual Information [H(b)+H(s)-H(b,s)] crM *OR* corratio_mul = Correlation Ratio (Symmetrized*) nmi *OR* norm_mutualinfo = Normalized MI [H(b,s)/(H(b)+H(s))] hel *OR* hellinger = Hellinger metric crA *OR* corratio_add = Correlation Ratio (Symmetrized+) crU *OR* corratio_uns = Correlation Ratio (Unsym) lpc *OR* localPcorSigned = Local Pearson Correlation Signed lpa *OR* localPcorAbs = Local Pearson Correlation Abs lpc+ *OR* localPcor+Others= Local Pearson Signed + Others lpa+ *OR* localPcorAbs+Others= Local Pearson Abs + Others You can also specify the cost functional using an option of the form '-mi' rather than '-cost mi', if you like to keep things terse and cryptic (as I do). [Default == '-hel' (for no good reason, but it sounds nice).] **NB** See more below about lpa and lpc, which are typically what we would recommend as first-choice cost functions now: lpa if you have similar contrast vols to align; lpc if you have *non*similar contrast vols to align! -interp iii = Defines interpolation method to use during matching process, where 'iii' is one of NN *OR* nearestneighbour *OR nearestneighbor linear *OR* trilinear cubic *OR* tricubic quintic *OR* triquintic Using '-NN' instead of '-interp NN' is allowed (e.g.). Note that using cubic or quintic interpolation during the matching process will slow the program down a lot. Use '-final' to affect the interpolation method used to produce the output dataset, once the final registration parameters are determined. [Default method == 'linear'.] ** N.B.: Linear interpolation is used during the coarse alignment pass; the selection here only affects the interpolation method used during the second (fine) alignment pass. ** N.B.: '-interp' does NOT define the final method used to produce the output dataset as warped from the input dataset. If you want to do that, use '-final'. -final iii = Defines the interpolation mode used to create the output dataset. [Default == 'cubic'] ** N.B.: If you are applying a transformation to an integer-valued dataset (such as an atlas), then you should use '-final NN' to avoid interpolation of the integer labels. ** N.B.: For '-final' ONLY, you can use 'wsinc5' to specify that the final interpolation be done using a weighted sinc interpolation method. This method is so SLOW that you aren't allowed to use it for the registration itself. ++ wsinc5 interpolation is highly accurate and should reduce the smoothing artifacts from lower order interpolation methods (which are most visible if you interpolate an EPI time series to high resolution and then make an image of the voxel-wise variance). ++ On my Intel-based Mac, it takes about 2.5 s to do wsinc5 interpolation, per 1 million voxels output. For comparison, quintic interpolation takes about 0.3 s per 1 million voxels: 8 times faster than wsinc5. ++ The '5' refers to the width of the sinc interpolation weights: plus/minus 5 grid points in each direction; this is a tensor product interpolation, for speed. TECHNICAL OPTIONS (used for fine control of the program): ================= -nmatch nnn = Use at most 'nnn' scattered points to match the datasets. The smaller nnn is, the faster the matching algorithm will run; however, accuracy may be bad if nnn is too small. If you end the 'nnn' value with the '%' character, then that percentage of the base's voxels will be used. [Default == 47% of voxels in the weight mask] -nopad = Do not use zero-padding on the base image. (I cannot think of a good reason to use this option.) [Default == zero-pad, if needed; -verb shows how much] -zclip = Replace negative values in the input datasets (source & base) -noneg with zero. The intent is to clip off a small set of negative values that may arise when using 3dresample (say) with cubic interpolation. -conv mmm = Convergence test is set to 'mmm' millimeters. This doesn't mean that the results will be accurate to 'mmm' millimeters! It just means that the program stops trying to improve the alignment when the optimizer (NEWUOA) reports it has narrowed the search radius down to this level. * To set this value to the smallest allowable, use '-conv 0'. * A coarser value for 'quick-and-dirty' alignment is 0.05. -verb = Print out verbose progress reports. [Using '-VERB' will give even more prolix reports :] -quiet = Don't print out verbose stuff. (But WHY?) -usetemp = Write intermediate stuff to disk, to economize on RAM. Using this will slow the program down, but may make it possible to register datasets that need lots of space. **N.B.: Temporary files are written to the directory given in environment variable TMPDIR, or in /tmp, or in ./ (preference in that order). If the program crashes, these files are named TIM_somethingrandom, and you may have to delete them manually. (TIM=Temporary IMage) **N.B.: If the program fails with a 'malloc failure' type of message, then try '-usetemp' (malloc=memory allocator). * If the program just stops with a message 'killed', that means the operating system (Unix/Linux) stopped the program, which almost always is due to the system running low on memory -- so it starts killing programs to save itself. -nousetemp = Don't use temporary workspace on disk [the default]. -check hhh = After cost functional optimization is done, start at the final parameters and RE-optimize using the new cost function 'hhh'. 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. Using '-check' increases the CPU time, but can help you feel sure that the alignment process did not go wild and crazy. [Default == no check == don't worry, be happy!] **N.B.: You can put more than one function after '-check', as in -nmi -check mi hel crU crM to register with Normalized Mutual Information, and then check the results against 4 other cost functionals. **N.B.: On the other hand, some cost functionals give better results than others for specific problems, and so a warning that 'mi' was significantly different than 'hel' might not actually mean anything useful (e.g.). ** PARAMETERS THAT AFFECT THE COST OPTIMIZATION STRATEGY ** -onepass = 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. [The default is to use both passes.] -twopass = Use a two pass alignment strategy, first searching for a large rotation+shift and then refining the alignment. [Two passes are used by default for the first sub-brick] [in the source dataset, and then one pass for the others.] ['-twopass' will do two passes for ALL source sub-bricks.] *** The first (coarse) pass is relatively slow, as it tries to search a large volume of parameter (rotations+shifts) space for initial guesses at the alignment transformation. * A lot of these initial guesses are kept and checked to see which ones lead to good starting points for the further refinement. * The winners of this competition are then passed to the '-twobest' (infra) successive optimization passes. * The ultimate winner of THAT stage is what starts the second (fine) pass alignment. Usually, this starting point is so good that the fine pass optimization does not provide a lot of improvement; that is, most of the run time ends up in coarse pass with its multiple stages. * All of these stages are intended to help the program avoid stopping at a 'false' minimum in the cost functional. They were added to the software as we gathered experience with difficult 3D alignment problems. The combination of multiple stages of partial optimization of multiple parameter candidates makes the coarse pass slow, but also makes it (usually) work well. -twoblur rr = Set the blurring radius for the first pass to 'rr' millimeters. [Default == 11 mm] **N.B.: You may want to change this from the default if your voxels are unusually small or unusually large (e.g., outside the range 1-4 mm along each axis). -twofirst = 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. (Useful when there may be large motions between the ) (source and the base, but only small motions within ) (the source dataset itself; since the coarse pass can ) (be slow, doing it only once makes sense in this case.) **N.B.: [-twofirst is on by default; '-twopass' turns it off.] -twobest bb = In the coarse pass, use the best 'bb' set of initial points to search for the starting point for the fine pass. If bb==0, then no search is made for the best starting point, and the identity transformation is used as the starting point. [Default=5; min=0 max=29] **N.B.: Setting bb=0 will make things run faster, but less reliably. Setting bb = 'MAX' will make it be the max allowed value. -fineblur x = 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] **NOTES ON **STRATEGY: * If you expect only small-ish (< 2 voxels?) image movement, then using '-onepass' or '-twobest 0' makes sense. * If you expect large-ish image movements, then do not use '-onepass' or '-twobest 0'; the purpose of the '-twobest' parameter is to search for large initial rotations/shifts with which to start the coarse optimization round. * If you have multiple sub-bricks in the source dataset, then the default '-twofirst' makes sense if you don't expect large movements WITHIN the source, but expect large motions between the source and base. * '-twopass' re-starts the alignment process for each sub-brick in the source dataset -- this option can be time consuming, and is really intended to be used when you might expect large movements between sub-bricks; for example, when the different volumes are gathered on different days. For most purposes, '-twofirst' (the default process) will be adequate and faster, when operating on multi-volume source datasets. -cmass = Use the center-of-mass calculation to determine an initial shift [This option is OFF by default] can be given as cmass+a, cmass+xy, cmass+yz, cmass+xz where +a means to try determine automatically in which direction the data is partial by looking for a too large shift If given in the form '-cmass+xy' (for example), means to do the CoM calculation in the x- and y-directions, but not the z-direction. * MY OPINION: This option is REALLY useful in most cases. However, if you only have partial coverage in the -source dataset, you will need to use one of the '+' additions to restrict the use of the CoM limits. -nocmass = Don't use the center-of-mass calculation. [The default] (You would not want to use the C-o-M calculation if the ) (source sub-bricks have very different spatial locations,) (since the source C-o-M is calculated from all sub-bricks) **EXAMPLE: You have a limited coverage set of axial EPI slices you want to register into a larger head volume (after 3dSkullStrip, of course). In this case, '-cmass+xy' makes sense, allowing CoM adjustment along the x = R-L and y = A-P directions, but not along the z = I-S direction, since the EPI doesn't cover the whole brain along that axis. -autoweight = Compute a weight function using the 3dAutomask algorithm plus some blurring of the base image. **N.B.: '-autoweight+100' means to zero out all voxels with values below 100 before computing the weight. '-autoweight**1.5' means to compute the autoweight and then raise it to the 1.5-th power (e.g., to increase the weight of high-intensity regions). These two processing steps can be combined, as in '-autoweight+100**1.5' ** Note that '**' must be enclosed in quotes; otherwise, the shell will treat it as a wildcard and you will get an error message before 3dAllineate even starts!! ** UPDATE: one can now use '^' for power notation, to avoid needing to enclose the string in quotes. **N.B.: Some cost functionals do not allow -autoweight, and will use -automask instead. A warning message will be printed if you run into this situation. If a clip level '+xxx' is appended to '-autoweight', then the conversion into '-automask' will NOT happen. Thus, using a small positive '+xxx' can be used trick -autoweight into working on any cost functional. -automask = Compute a mask function, which is like -autoweight, but the weight for a voxel is set to either 0 or 1. **N.B.: '-automask+3' means to compute the mask function, and then dilate it outwards by 3 voxels (e.g.). ** Note that '+' means something very different for '-automask' and '-autoweight'!! -autobox = Expand the -automask function to enclose a rectangular box that holds the irregular mask. **N.B.: This is the default mode of operation! For intra-modality registration, '-autoweight' may be better! * If the cost functional is 'ls', then '-autoweight' will be the default, instead of '-autobox'. -nomask = Don't compute the autoweight/mask; if -weight is not also used, then every voxel will be counted equally. -weight www = Set the weighting for each voxel in the base dataset; larger weights mean that voxel counts more in the cost function. **N.B.: The weight dataset must be defined on the same grid as the base dataset. **N.B.: Even if a method does not allow -autoweight, you CAN use a weight dataset that is not 0/1 valued. The risk is yours, of course (!*! as always in AFNI !*!). -wtprefix p = Write the weight volume to disk as a dataset with prefix name 'p'. Used with '-autoweight/mask', this option lets you see what voxels were important in the algorithm. -emask ee = This option lets you specify a mask of voxels to EXCLUDE from the analysis. The voxels where the dataset 'ee' is nonzero will not be included (i.e., their weights will be set to zero). * Like all the weight options, it applies in the base image coordinate system. ** Like all the weight options, it means nothing if you are using one of the 'apply' options. Method Allows -autoweight ------ ------------------ ls YES mi NO crM YES nmi NO hel NO crA YES crU YES lpc YES lpa YES lpc+ YES lpa+ YES -source_mask sss = Mask the source (input) dataset, using 'sss'. -source_automask = Automatically mask the source dataset. [By default, all voxels in the source] [dataset are used in the matching. ] **N.B.: You can also use '-source_automask+3' to dilate the default source automask outward by 3 voxels. -warp xxx = Set the warp type to 'xxx', which is one of shift_only *OR* sho = 3 parameters shift_rotate *OR* shr = 6 parameters shift_rotate_scale *OR* srs = 9 parameters affine_general *OR* aff = 12 parameters [Default = affine_general, which includes image] [ shifts, rotations, scaling, and shearing] * MY OPINION: Shearing is usually unimportant, so you can omit it if you want: '-warp srs'. But it doesn't hurt to keep shearing, except for a little extra CPU time. On the other hand, scaling is often important, so should not be omitted. -warpfreeze = Freeze the non-rigid body parameters (those past #6) after doing the first sub-brick. Subsequent volumes will have the same spatial distortions as sub-brick #0, plus rigid body motions only. * MY OPINION: This option is almost useless. -replacebase = If the source has more than one sub-brick, and this option is turned on, then after the #0 sub-brick is aligned to the base, the aligned #0 sub-brick is used as the base image for subsequent source sub-bricks. * MY OPINION: This option is almost useless. -replacemeth m = After sub-brick #0 is aligned, switch to method 'm' for later sub-bricks. For use with '-replacebase'. * MY OPINION: This option is almost useless. -EPI = 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. **N.B.: For most people, the base dataset will be a 3dSkullStrip-ed T1-weighted anatomy (MPRAGE or SPGR). If you don't remove the skull first, the EPI images (which have little skull visible due to fat-suppression) might expand to fit EPI brain over T1-weighted skull. **N.B.: Usually, EPI datasets don't have as complete slice coverage of the brain as do T1-weighted datasets. If you don't use some option (like '-EPI') to suppress scaling in the slice- direction, the EPI dataset is likely to stretch the slice thickness to better 'match' the T1-weighted brain coverage. **N.B.: '-EPI' turns on '-warpfreeze -replacebase'. You can use '-nowarpfreeze' and/or '-noreplacebase' AFTER the '-EPI' on the command line if you do not want these options used. ** OPTIONS to change search ranges for alignment parameters ** -smallrange = Set all the parameter ranges to be smaller (about half) than the default ranges, which are rather large for many purposes. * Default angle range is plus/minus 30 degrees * Default shift range is plus/minus 32% of grid size * Default scaling range is plus/minus 20% of grid size * Default shearing range is plus/minus 0.1111 -parfix n v = Fix parameter #n to be exactly at value 'v'. -parang n b t = Allow parameter #n to range only between 'b' and 't'. If not given, default ranges are used. -parini n v = Initialize parameter #n to value 'v', but then allow the algorithm to adjust it. **N.B.: Multiple '-par...' options can be used, to constrain multiple parameters. **N.B.: -parini has no effect if -twopass is used, since the -twopass algorithm carries out its own search for initial parameters. -maxrot dd = Allow maximum rotation of 'dd' degrees. Equivalent to '-parang 4 -dd dd -parang 5 -dd dd -parang 6 -dd dd' [Default=30 degrees] -maxshf dd = Allow maximum shift of 'dd' millimeters. Equivalent to '-parang 1 -dd dd -parang 2 -dd dd -parang 3 -dd dd' [Default=32% of the size of the base image] **N.B.: This max shift setting is relative to the center-of-mass shift, if the '-cmass' option is used. -maxscl dd = Allow maximum scaling factor to be 'dd'. Equivalent to '-parang 7 1/dd dd -parang 8 1/dd dd -paran2 9 1/dd dd' [Default=1.4=image can go up or down 40% in size] -maxshr dd = Allow maximum shearing factor to be 'dd'. Equivalent to '-parang 10 -dd dd -parang 11 -dd dd -parang 12 -dd dd' [Default=0.1111 for no good reason] NOTE: If the datasets being registered have only 1 slice, 3dAllineate will automatically fix the 6 out-of-plane motion parameters to their 'do nothing' values, so you don't have to specify '-parfix'. -master mmm = Write the output dataset on the same grid as dataset 'mmm'. If this option is NOT given, the base dataset is the master. **N.B.: 3dAllineate transforms the source dataset to be 'similar' to the base image. Therefore, the coordinate system of the master dataset is interpreted as being in the reference system of the base image. It is thus vital that these finite 3D volumes overlap, or you will lose data! **N.B.: If 'mmm' is the string 'SOURCE', then the source dataset is used as the master for the output dataset grid. You can also use 'BASE', which is of course the default. -mast_dxyz del = Write the output dataset using grid spacings of *OR* 'del' mm. If this option is NOT given, then the -newgrid del grid spacings in the master dataset will be used. This option is useful when registering low resolution data (e.g., EPI time series) to high resolution datasets (e.g., MPRAGE) where you don't want to consume vast amounts of disk space interpolating the low resolution data to some artificially fine (and meaningless) spatial grid. ---------------------------------------------- DEFINITION OF AFFINE TRANSFORMATION PARAMETERS ---------------------------------------------- The 3x3 spatial transformation matrix is calculated as [S][D][U], where [S] is the shear matrix, [D] is the scaling matrix, and [U] is the rotation (proper orthogonal) matrix. Thes matrices are specified in DICOM-ordered (x=-R+L,y=-A+P,z=-I+S) coordinates as: [U] = [Rotate_y(param#6)] [Rotate_x(param#5)] [Rotate_z(param #4)] (angles are in degrees) [D] = diag( param#7 , param#8 , param#9 ) [ 1 0 0 ] [ 1 param#10 param#11 ] [S] = [ param#10 1 0 ] OR [ 0 1 param#12 ] [ param#11 param#12 1 ] [ 0 0 1 ] The shift vector comprises parameters #1, #2, and #3. The goal of the program is to find the warp parameters such that I([x]_warped) 'is similar to' J([x]_in) as closely as possible in some sense of 'similar', where J(x) is the base image, and I(x) is the source image. Using '-parfix', you can specify that some of these parameters are fixed. For example, '-shift_rotate_scale' is equivalent '-affine_general -parfix 10 0 -parfix 11 0 -parfix 12 0'. Don't even think of using the '-parfix' option unless you grok this example! ----------- Special Note for the '-EPI' Option's Coordinates ----------- In this case, the parameters above are with reference to coordinates x = frequency encoding direction (by default, first axis of dataset) y = phase encoding direction (by default, second axis of dataset) z = slice encoding direction (by default, third axis of dataset) This option lets you freeze some of the warping parameters in ways that make physical sense, considering how echo-planar images are acquired. The x- and z-scaling parameters are disabled, and shears will only affect the y-axis. Thus, there will be only 9 free parameters when '-EPI' is used. If desired, you can use a '-parang' option to allow the scaling fixed parameters to vary (put these after the '-EPI' option): -parang 7 0.833 1.20 to allow x-scaling -parang 9 0.833 1.20 to allow z-scaling You could also fix some of the other parameters, if that makes sense in your situation; for example, to disable out-of-slice rotations: -parfix 5 0 -parfix 6 0 and to disable out of slice translation: -parfix 3 0 NOTE WELL: If you use '-EPI', then the output warp parameters (e.g., in '-1Dparam_save') apply to the (freq,phase,slice) xyz coordinates, NOT to the DICOM xyz coordinates, so equivalent transformations will be expressed with different sets of parameters entirely than if you don't use '-EPI'! This comment does NOT apply to the output of '-1Dmatrix_save', since that matrix is defined relative to the RAI (DICOM) spatial coordinates. *********** CHANGING THE ORDER OF MATRIX APPLICATION *********** {{{ There is no good reason to ever use these options! }}} -SDU or -SUD }= Set the order of the matrix multiplication -DSU or -DUS }= for the affine transformations: -USD or -UDS }= S = triangular shear (params #10-12) D = diagonal scaling matrix (params #7-9) U = rotation matrix (params #4-6) Default order is '-SDU', which means that the U matrix is applied first, then the D matrix, then the S matrix. -Supper }= Set the S matrix to be upper or lower -Slower }= triangular [Default=lower triangular] NOTE: There is no '-Lunch' option. There is no '-Faster' option. -ashift OR }= Apply the shift parameters (#1-3) after OR -bshift }= before the matrix transformation. [Default=after] ================================================== ===== RWCox - September 2006 - Live Long and Prosper ===== ================================================== ******************************************************** *** From Webster's Dictionary: Allineate == 'to align' *** ******************************************************** =========================================================================== FORMERLY SECRET HIDDEN OPTIONS --------------------------------------------------------------------------- ** N.B.: Most of these are experimental! [permanent beta] ** =========================================================================== -num_rtb n = At the beginning of the fine pass, the best set of results from the coarse pass are 'refined' a little by further optimization, before the single best one is chosen for for the final fine optimization. * This option sets the maximum number of cost functional evaluations to be used (for each set of parameters) in this step. * The default is 99; a larger value will take more CPU time but may give more robust results. * If you want to skip this step entirely, use '-num_rtb 0'. then, the best of the coarse pass results is taken straight to the final optimization passes. **N.B.: If you use '-VERB', you will see that one extra case is involved in this initial fine refinement step; that case is starting with the identity transformation, which helps insure against the chance that the coarse pass optimizations ran totally amok. * MY OPINION: This option is mostly useless - but not always! * Every step in the multi-step alignment process was added at some point to solve a difficult alignment problem. * Since you usually don't know if YOUR problem is difficult, you should not reduce the default process without good reason. -nocast = By default, parameter vectors that are too close to the best one are cast out at the end of the coarse pass refinement process. Use this option if you want to keep them all for the fine resolution pass. * MY OPINION: This option is nearly useless. -norefinal = Do NOT re-start the fine iteration step after it has converged. The default is to re-start it, which usually results in a small improvement to the result (at the cost of CPU time). This re-start step is an an attempt to avoid a local minimum trap. It is usually not necessary, but sometimes helps. -realaxes = Use the 'real' axes stored in the dataset headers, if they conflict with the default axes. [For Jedi AFNI Masters only!] -savehist sss = Save start and final 2D histograms as PGM files, with prefix 'sss' (cost: cr mi nmi hel). * if filename contains 'FF', floats is written * these are the weighted histograms! * -savehist will also save histogram files when the -allcost evaluations takes place * this option is mostly useless unless '-histbin' is also used * MY OPINION: This option is mostly for debugging. -median = Smooth with median filter instead of Gaussian blur. (Somewhat slower, and not obviously useful.) * MY OPINION: This option is nearly useless. -powell m a = Set the Powell NEWUOA dimensional parameters to 'm' and 'a' (cf. source code in powell_int.c). The number of points used for approximating the cost functional is m*N+a, where N is the number of parameters being optimized. The default values are m=2 and a=3. Larger values will probably slow the program down for no good reason. The smallest allowed values are 1. * MY OPINION: This option is nearly useless. -target ttt = Same as '-source ttt'. In the earliest versions, what I now call the 'source' dataset was called the 'target' dataset: Try to remember the kind of September (2006) When life was slow and oh so mellow Try to remember the kind of September When grass was green and source was target. -Xwarp =} Change the warp/matrix setup so that only the x-, y-, or z- -Ywarp =} axis is stretched & sheared. Useful for EPI, where 'X', -Zwarp =} 'Y', or 'Z' corresponds to the phase encoding direction. -FPS fps = Generalizes -EPI to arbitrary permutation of directions. -histpow pp = By default, the number of bins in the histogram used for calculating the Hellinger, Mutual Information, and Correlation Ratio statistics is n^(1/3), where n is the number of data points. You can change that exponent to 'pp' with this option. -histbin nn = Or you can just set the number of bins directly to 'nn'. -eqbin nn = Use equalized marginal histograms with 'nn' bins. -clbin nn = Use 'nn' equal-spaced bins except for the bot and top, which will be clipped (thus the 'cl'). If nn is 0, the program will pick the number of bins for you. **N.B.: '-clbin 0' is now the default [25 Jul 2007]; if you want the old all-equal-spaced bins, use '-histbin 0'. **N.B.: '-clbin' only works when the datasets are non-negative; any negative voxels in either the input or source volumes will force a switch to all equal-spaced bins. * MY OPINION: The above histogram-altering options are useless. -wtmrad mm = Set autoweight/mask median filter radius to 'mm' voxels. -wtgrad gg = Set autoweight/mask Gaussian filter radius to 'gg' voxels. -nmsetup nn = Use 'nn' points for the setup matching [default=98756] -ignout = Ignore voxels outside the warped source dataset. -blok bbb = Blok definition for the 'lp?' (Local Pearson) cost functions: 'bbb' is one of 'BALL(r)' or 'CUBE(r)' or 'RHDD(r)' or 'TOHD(r)' corresponding to spheres or cubes or rhombic dodecahedra or truncated octahedra where 'r' is the size parameter in mm. [Default is 'TOHD(r)' = truncated octahedron] [with 'radius' r chosen to include about 500] [voxels in the base dataset 3D grid. ] * Changing the 'blok' definition/radius should only be needed in unusual situations, as when you are trying to have fun fun fun. * You can change the blok shape but leave the program to set the radius, using (say) 'RHDD(0)'. * The old default blok shape/size was 'RHDD(6.54321)', so if you want to maintain backward compatibility, you should use option '-blok "RHDD(6.54321)"' * Only voxels in the weight mask will be used inside a blok. * HISTORICAL NOTES: * CUBE, RHDD, and TOHD are space filling polyhedra. That is, they are shapes that fit together without overlaps or gaps to fill up 3D space. * To even approximately fill space, BALLs must overlap, unlike the other blok shapes. Which means that BALL bloks will use some voxels more than once. * Kepler discovered/invented the RHDD (honeybees also did). * The TOHD is the 'most compact' or 'most ball-like' of the known convex space filling polyhedra. [Which is why TOHD is the default blok shape.] -PearSave sss = Save the final local Pearson correlations into a dataset *OR* with prefix 'sss'. These are the correlations from -SavePear sss which the lpc and lpa cost functionals are calculated. * The values will be between -1 and 1 in each blok. See the 'Too Much Detail' section below for how these correlations are used to compute lpc and lpa. * Locations not used in the matching will get 0. ** Unless you use '-nmatch 100%', there will be holes of 0s in the bloks, as not all voxels are used in the matching algorithm (speedup attempt). * All the matching points in a given blok will get the same value, which makes the resulting dataset look jauntily blocky, especially in color. * This saved dataset will be on the grid of the base dataset, and may be zero padded if the program chose to do so in it wisdom. This padding means that the voxels in this output dataset may not match one-to-one with the voxels in the base dataset; however, AFNI displays things using coordinates, so overlaying this dataset on the base dataset (say) should work OK. * If you really want this saved dataset to be on the grid as the base dataset, you'll have use 3dZeropad -master {Base Dataset} .... * Option '-PearSave' works even if you don't use the 'lpc' or 'lpa' cost functionals. * If you use this option combined with '-allcostX', then the local correlations will be saved from the INITIAL alignment parameters, rather than from the FINAL optimized parameters. (Of course, with '-allcostX', there IS no final result.) * This option does NOT work with '-allcost' or '-allcostX1D'. -allcost = Compute ALL available cost functionals and print them at various points in the optimization progress. -allcostX = Compute and print ALL available cost functionals for the un-warped inputs, and then quit. * This option is for testing purposes (AKA 'fun'). -allcostX1D p q = Compute ALL available cost functionals for the set of parameters given in the 1D file 'p' (12 values per row), write them to the 1D file 'q', then exit. (For you, Zman) * N.B.: If -fineblur is used, that amount of smoothing will be applied prior to the -allcostX evaluations. The parameters are the rotation, shift, scale, and shear values, not the affine transformation matrix. An identity matrix could be provided as "0 0 0 0 0 0 1 1 1 0 0 0" for instance or by using the word "IDENTITY" * This option is for testing purposes (even more 'fun'). =========================================================================== Too Much Detail -- How Local Pearson Correlations Are Computed and Used ----------------------------------------------------------------------- * The automask region of the base dataset is divided into a discrete set of 'bloks'. Usually there are several thousand bloks. * In each blok, the voxel values from the base and the source (after the alignment transformation is applied) are extracted and the correlation coefficient is computed -- either weighted or unweighted, depending on the options used in 3dAllineate (usually weighted). * Let p[i] = correlation coefficient in blok #i, w[i] = sum of weights used in blok #i, or = 1 if unweighted. ** The values of p[i] are what get output via the '-PearSave' option. * Define pc[i] = arctanh(p[i]) = 0.5 * log( (1+p[i]) / (1-p[i]) ) This expression is designed to 'stretch' out larger correlations, giving them more emphasis in psum below. The same reasoning is why pc[i]*abs(pc[i]) is used below, to make bigger correlations have a bigger impact in the final result. * psum = SUM_OVER_i { w[i]*pc[i]*abs(pc[i]) } wsum = SUM_OVER_i { w[i] } lpc = psum / wsum ==> negative correlations are good (smaller lpc) lpa = 1 - abs(lpc) ==> positive correlations are good (smaller lpa) =========================================================================== Modifying '-final wsinc5' -- for the truly crazy people out there ----------------------------------------------------------------- * The windowed (tapered) sinc function interpolation can be modified by several environment variables. This is expert-level stuff, and you should understand what you are doing if you use these options. The simplest way to use these would be on the command line, as in -DAFNI_WSINC5_RADIUS=9 -DAFNI_WSINC5_TAPERFUN=Hamming * AFNI_WSINC5_TAPERFUN lets you choose the taper function. The default taper function is the minimum sidelobe 3-term cosine: 0.4243801 + 0.4973406*cos(PI*x) + 0.0782793*cos(2*PI*x) If you set this environment variable to 'Hamming', then the minimum sidelobe 2-term cosine will be used instead: 0.53836 + 0.46164*cos(PI*x) Here, 'x' is between 0 and 1, where x=0 is the center of the interpolation mask and x=1 is the outer edge. ++ Unfortunately, the 3-term cosine doesn't have a catchy name; you can find it (and many other) taper functions described in the paper AH Nuttall, Some Windows with Very Good Sidelobe Behavior. IEEE Trans. ASSP, 29:84-91 (1981). In particular, see Fig.14 and Eq.36 in this paper. * AFNI_WSINC5_TAPERCUT lets you choose the start 'x' point for tapering: This value should be between 0 and 0.8; for example, 0 means to taper all the way from x=0 to x=1 (maximum tapering). The default value is 0. Setting TAPERCUT to 0.5 (say) means only to taper from x=0.5 to x=1; thus, a larger value means that fewer points are tapered inside the interpolation mask. * AFNI_WSINC5_RADIUS lets you choose the radius of the tapering window (i.e., the interpolation mask region). This value is an integer between 3 and 21. The default value is 5 (which used to be the ONLY value, thus 'wsinc5'). RADIUS is measured in voxels, not mm. * AFNI_WSINC5_SPHERICAL lets you choose the shape of the mask region. If you set this value to 'Yes', then the interpolation mask will be spherical; otherwise, it defaults to cubical. * The Hamming taper function is a little faster than the 3-term function, but will have a little more Gibbs phenomenon. * A larger TAPERCUT will give a little more Gibbs phenomenon; compute speed won't change much with this parameter. * Compute time goes up with (at least) the 3rd power of the RADIUS; setting RADIUS to 21 will be VERY slow. * Visually, RADIUS=3 is similar to quintic interpolation. Increasing RADIUS makes the interpolated images look sharper and more well- defined. However, values of RADIUS greater than or equal to 7 appear (to Zhark's eagle eye) to be almost identical. If you really care, you'll have to experiment with this parameter yourself. * A spherical mask is also VERY slow, since the cubical mask allows evaluation as a tensor product. There is really no good reason to use a spherical mask; I only put it in for fun/experimental purposes. ** For most users, there is NO reason to ever use these environment variables to modify wsinc5. You should only do this kind of thing if you have a good and articulable reason! (Or if you really like to screw around.) ** The wsinc5 interpolation function is parallelized using OpenMP, which makes its usage moderately tolerable. =========================================================================== Hidden experimental cost functionals: ------------------------------------- sp *OR* spearman = Spearman [rank] Correlation je *OR* jointentropy = Joint Entropy [H(b,s)] lss *OR* signedPcor = Signed Pearson Correlation Notes for the new [Feb 2010] lpc+ cost functional: -------------------------------------------------- * The cost functional named 'lpc+' is a combination of several others: lpc + hel*0.4 + crA*0.4 + nmi*0.2 + mi*0.2 + ov*0.4 ++ 'hel', 'crA', 'nmi', and 'mi' are the histogram-based cost functionals also available as standalone options. ++ 'ov' is a measure of the overlap of the automasks of the base and source volumes; ov is not available as a standalone option. * The purpose of lpc+ is to avoid situations where the pure lpc cost goes wild; this especially happens if '-source_automask' isn't used. ++ Even with lpc+, you should use '-source_automask+2' (say) to be safe. * You can alter the weighting of the extra functionals by giving the option in the form (for example) '-lpc+hel*0.5+nmi*0+mi*0+crA*1.0+ov*0.5' * The quotes are needed to prevent the shell from wild-card expanding the '*' character. --> You can now use ':' in place of '*' to avoid this wildcard problem: -lpc+hel:0.5+nmi:0+mi:0+crA:1+ov:0.5+ZZ * Notice the weight factors FOLLOW the name of the extra functionals. ++ If you want a weight to be 0 or 1, you have to provide for that explicitly -- if you leave a weight off, then it will get its default value! ++ The order of the weight factor names is unimportant here: '-lpc+hel*0.5+nmi*0.8' == '-lpc+nmi*0.8+hel*0.5' * Only the 5 functionals listed (hel,crA,nmi,mi,ov) can be used in '-lpc+'. * In addition, if you want the initial alignments to be with '-lpc+' and then finish the Final alignment with pure '-lpc', you can indicate this by putting 'ZZ' somewhere in the option string, as in '-lpc+ZZ'. ***** '-cost lpc+ZZ' is very useful for aligning EPI to T1w volumes ***** * [28 Nov 2018] All of the above now applies to the 'lpa+' cost functional, which can be used as a robust method for like-to-like alignment. For example, aligning 3T and 7T T1-weighted datasets from the same person. * [28 Sep 2021] However, the default multiplier constants for cost 'lpa+' are now different from the 'lpc+' multipliers -- to make 'lpa+' more robust. The new default for 'lpa+' is lpa + hel*0.4 + crA*0.4 + nmi*0.2 + mi*0.0 + ov*0.4 ***** '-cost lpa+ZZ' is very useful for T1w to T1w volumes (or any ***** ***** similar-contrast datasets). ***** *** Note that in trial runs, we have found that lpc+ZZ and lpa+ZZ are *** *** more robust than lpc+ and lpa+ -- which is why the '+ZZ' amendment *** *** was created. *** Cost functional descriptions (for use with -allcost output): ------------------------------------------------------------ ls :: 1 - abs(Pearson correlation coefficient) sp :: 1 - abs(Spearman correlation coefficient) mi :: - Mutual Information = H(base,source)-H(base)-H(source) crM :: 1 - abs[ CR(base,source) * CR(source,base) ] nmi :: 1/Normalized MI = H(base,source)/[H(base)+H(source)] je :: H(base,source) = joint entropy of image pair hel :: - Hellinger distance(base,source) crA :: 1 - abs[ CR(base,source) + CR(source,base) ] crU :: CR(source,base) = Var(source|base) / Var(source) lss :: Pearson correlation coefficient between image pair lpc :: nonlinear average of Pearson cc over local neighborhoods lpa :: 1 - abs(lpc) lpc+:: lpc + hel + mi + nmi + crA + overlap lpa+:: lpa + hel + nmi + crA + overlap * N.B.: Some cost functional values (as printed out above) are negated from their theoretical descriptions (e.g., 'hel') so that the best image alignment will be found when the cost is minimized. See the descriptions above and the references below for more details for each functional. * MY OPINIONS: * Some of these cost functionals were implemented only for the purposes of fun and/or comparison and/or experimentation and/or special circumstances. These are sp je lss crM crA crM hel mi nmi * For many purposes, lpc+ZZ and lpa+ZZ are the most robust cost functionals, but usually the slowest to evaluate. * HOWEVER, just because some method is best MOST of the time does not mean it is best ALL of the time. Please check your results visually, or at some point in time you will have bad results and not know it! * For speed and for 'like-to-like' alignment, '-cost ls' can work well. * For more information about the 'lpc' functional, see ZS Saad, DR Glen, G Chen, MS Beauchamp, R Desai, RW Cox. A new method for improving functional-to-structural MRI alignment using local Pearson correlation. NeuroImage 44: 839-848, 2009. http://dx.doi.org/10.1016/j.neuroimage.2008.09.037 https://pubmed.ncbi.nlm.nih.gov/18976717 The '-blok' option can be used to control the regions (size and shape) used to compute the local correlations. *** Using the 'lpc' functional wisely requires the use of a proper weight volume. We HIGHLY recommend you use the align_epi_anat.py script if you want to use this cost functional! Otherwise, you are likely to get less than optimal results (and then swear at us unjustly). * For more information about the 'cr' functionals, see http://en.wikipedia.org/wiki/Correlation_ratio Note that CR(x,y) is not the same as CR(y,x), which is why there are symmetrized versions of it available. * For more information about the 'mi', 'nmi', and 'je' cost functionals, see http://en.wikipedia.org/wiki/Mutual_information http://en.wikipedia.org/wiki/Joint_entropy http://www.cs.jhu.edu/~cis/cista/746/papers/mutual_info_survey.pdf * For more information about the 'hel' functional, see http://en.wikipedia.org/wiki/Hellinger_distance * Some cost functionals (e.g., 'mi', 'cr', 'hel') are computed by creating a 2D joint histogram of the base and source image pair. Various options above (e.g., '-histbin', etc.) can be used to control the number of bins used in the histogram on each axis. (If you care to control the program in such detail!) * Minimization of the chosen cost functional is done via the NEWUOA software, described in detail in MJD Powell. 'The NEWUOA software for unconstrained optimization without derivatives.' In: GD Pillo, M Roma (Eds), Large-Scale Nonlinear Optimization. Springer, 2006. http://www.damtp.cam.ac.uk/user/na/NA_papers/NA2004_08.pdf =========================================================================== SUMMARY of the Default Allineation Process ------------------------------------------ As mentioned earlier, each of these steps was added to deal with a problem that came up over the years. The resulting process is reasonably robust :), but then tends to be slow :(. If you use the '-verb' or '-VERB' option, you will get a lot of fun fun fun progress messages that show the results from this sequence of steps. Below, I refer to different scales of effort in the optimizations at each step. Easier/faster optimization is done using: matching with fewer points from the datasets; more smoothing of the base and source datasets; and by putting a smaller upper limit on the number of trials the optimizer is allowed to take. The Coarse phase starts with the easiest optimization, and increases the difficulty a little at each refinement. The Fine phase starts with the most difficult optimization setup: the most points for matching, little or no smoothing, and a large limit on the number of optimizer trials. 0. Preliminary Setup [Goal: create the basis for the following steps] a. Create the automask and/or autoweight from the '-base' dataset. The cost functional will only be computed from voxels inside the automask, and only a fraction of those voxels will actually be used for evaluating the cost functional (unless '-nmatch 100%' is used). b. If the automask is 'too close' to the outside of the base 3D volume, zeropad the base dataset to avoid edge effects. c. Determine the 3D (x,y,z) shifts for the '-cmass' center-of-mass crude alignment, if ordered by the user. d. Set ranges of transformation parameters and which parameters are to be frozen at fixed values. 1. Coarse Phase [Goal: explore the vastness of 6-12D parameter space] a. The first step uses only the first 6 parameters (shifts + rotations), and evaluates thousands of potential starting points -- selected from a 6D grid in parameter space and also from random points in 6D parameter space. This step is fairly slow. The best 45 parameter sets (in the sense of the cost functional) are kept for the next step. b. Still using only the first 6 parameters, the best 45 sets of parameters undergo a little optimization. The best 6 parameter sets after this refinement are kept for the next step. (The number of sets chosen to go on to the next step can be set by the '-twobest' option.) The optimizations in this step use the blurring radius that is given by option '-twoblur', which defaults to 7.77 mm, and use relatively few points in each dataset for computing the cost functional. c. These 6 best parameter sets undergo further, more costly, optimization, now using all 12 parameters. This optimization runs in 3 passes, each more costly (less smoothing, more matching points) than the previous. (If 2 sets get too close in parameter space, 1 of them will be cast out -- this does not happen often.) Output parameter sets from the 3rd pass of successive refinement are inputs to the fine refinement phase. 2. Fine Phase [Goal: use more expensive optimization on good starting points] a. The 6 outputs from step 1c have the null parameter set (all 0, except for the '-cmass' shifts) appended. Then a small amount of optimization is applied to each of these 7 parameter sets ('-num_rtb'). The null parameter set is added here to insure against the possibility that the coarse optimizations 'ran away' to some unpleasant locations in the 12D parameter space. These optimizations use the full set of points specified by '-nmatch', and the smoothing specified by '-fineblur' (default = 0), but the number of functional evaluations is small, to make this step fast. b. The best (smallest cost) set from step 2a is chosen for the final optimization, which is run until the '-conv' limit is reached. These are the 'Finalish' parameters (shown using '-verb'). c. The set of parameters from step 2b is used as the starting point for a new optimization, in an attempt to avoid a false minimum. The results of this optimization are the final parameter set. 3. The final set of parameters is used to produce the output volume, using the '-final' interpolation method. In practice, the output from the Coarse phase successive refinements is usually so good that the Fine phase runs quickly and makes only small adjustments. The quality resulting from the Coarse phase steps is mostly due, in my opinion, to the large number of initial trials (1ab), followed by by the successive refinements of several parameter sets (1c) to help usher 'good' candidates to the starting line for the Fine phase. For some 'easy' registration problems -- such as T1w-to-T1w alignment, high quality images, a lot of overlap to start with -- the process can be sped up by reducing the number of steps. For example, '-num_rtb 0 -twobest 0' would eliminate step 2a and speed up step 1c. Even more extreme, '-onepass' could be used to skip all of the Coarse phase. But be careful out there! For 'hard' registration problems, cleverness is usually needed. Choice of cost functional matters. Preprocessing the datasets may be necessary. Using '-twobest 29' could help by providing more candidates for the Fine phase -- at the cost of CPU time. If you run into trouble -- which happens sooner or later -- try the AFNI Message Board -- and please give details, including the exact command line(s) you used. ========================================================================= * This binary version of 3dAllineate is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. * OpenMP may or may not speed up the program significantly. Limited tests show that it provides some benefit, particularly when using the more complicated interpolation methods (e.g., '-cubic' and/or '-final wsinc5'), for up to 3-4 CPU threads. * But the speedup is definitely not linear in the number of threads, alas. Probably because my parallelization efforts were pretty limited. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAmpToRSFC
This program is for converting spectral amplitudes into standard RSFC parameters. This function is made to work directly with the outputs of 3dLombScargle, but you could use other inputs that have similar formatting. (3dLombScargle's main algorithm is special because it calculates spectra from time series with nonconstant sampling, such as if some time points have been censored during processing-- check it out!.) At present, 6 RSFC parameters get returned in separate volumes: ALFF, mALFF, fALFF, RSFA, mRSFA and fRSFA. For more information about each RSFC parameter, see, e.g.: ALFF/mALFF -- Zang et al. (2007), fALFF -- Zou et al. (2008), RSFA -- Kannurpatti & Biswal (2008). You can also see the help of 3dRSFC, as well as the Appendix of Taylor, Gohel, Di, Walter and Biswal (2012) for a mathematical description and set of relations. NB: *if* you want to input an unbandpassed time series and do some filtering/other processing at the same time as estimating RSFC parameters, then you would want to use 3dRSFC, instead. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: 3dAmpToRSFC { -in_amp AMPS | -in_pow POWS } -prefix PREFIX \ -band FBOT FTOP { -mask MASK } { -nifti } * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + RUNNING: -in_amp AMPS :input file of one-sided spectral amplitudes, such as output by 3dLombScargle. It is also assumed that the the frequencies are uniformly spaced with a single DF ('delta f'), and that the zeroth brick is at 1*DF (i.e. that the zeroth/baseline frequency is not present in the or spectrum. -in_pow POWS :input file of a one-sided power spectrum, such as output by 3dLombScargle. Similar freq assumptions as in '-in_amp ...'. -band FBOT FTOP :lower and upper boundaries, respectively, of the low frequency fluctuations (LFFs), which will be in the inclusive interval [FBOT, FTOP], within the provided input file's frequency range. -prefix PREFIX :output file prefix; file names will be: PREFIX_ALFF*, PREFIX_FALFF*, etc. -mask MASK :volume mask of voxels to include for calculations; if no mask is included, values are calculated for voxels whose values are not identically zero across time. -nifti :output files as *.nii.gz (default is BRIK/HEAD). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUT: Currently, 6 volumes of common RSFC parameters, briefly: PREFIX_ALFF+orig :amplitude of low freq fluctuations (L1 sum). PREFIX_MALFF+orig :ALFF divided by the mean value within the input/estimated whole brain mask (a.k.a. 'mean-scaled ALFF'). PREFIX_FALFF+orig :ALFF divided by sum of full amplitude spectrum (-> 'fractional ALFF'). PREFIX_RSFA+orig :square-root of summed square of low freq fluctuations (L2 sum). PREFIX_MRSFA+orig :RSFA divided by the mean value within the input/estimated whole brain mask (a.k.a. 'mean-scaled RSFA'). PREFIX_FRSFA+orig :ALFF divided by sum of full amplitude spectrum (a.k.a. 'fractional RSFA'). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dAmpToRSFC \ -in_amp SUBJ_01_amp.nii.gz \ -prefix SUBJ_01 \ -mask mask_WB.nii.gz \ -band 0.01 0.1 \ -nifti ___________________________________________________________________________

AFNI program: 3dAnhist
Usage: 3dAnhist [options] dataset Input dataset is a T1-weighted high-res of the brain (shorts only). Output is a list of peaks in the histogram, to stdout, in the form ( datasetname #peaks peak1 peak2 ... ) In the C-shell, for example, you could do set anhist = `3dAnhist -q -w1 dset+orig` Then the number of peaks found is in the shell variable $anhist[2]. Options: -q = be quiet (don't print progress reports) -h = dump histogram data to Anhist.1D and plot to Anhist.ps -F = DON'T fit histogram with stupid curves. -w = apply a Winsorizing filter prior to histogram scan (or -w7 to Winsorize 7 times, etc.) -2 = Analyze top 2 peaks only, for overlap etc. -label xxx = Use 'xxx' for a label on the Anhist.ps plot file instead of the input dataset filename. -fname fff = Use 'fff' for the filename instead of 'Anhist'. If the '-2' option is used, AND if 2 peaks are detected, AND if the -h option is also given, then stdout will be of the form ( datasetname 2 peak1 peak2 thresh CER CJV count1 count2 count1/count2) where 2 = number of peaks thresh = threshold between peak1 and peak2 for decision-making CER = classification error rate of thresh CJV = coefficient of joint variation count1 = area under fitted PDF for peak1 count2 = area under fitted PDF for peak2 count1/count2 = ratio of the above quantities NOTA BENE --------- * If the input is a T1-weighted MRI dataset (the usual case), then peak 1 should be the gray matter (GM) peak and peak 2 the white matter (WM) peak. * For the definitions of CER and CJV, see the paper Method for Bias Field Correction of Brain T1-Weighted Magnetic Resonance Images Minimizing Segmentation Error JD Gispert, S Reig, J Pascau, JJ Vaquero, P Garcia-Barreno, and M Desco, Human Brain Mapping 22:133-144 (2004). * Roughly speaking, CER is the ratio of the overlapping area of the 2 peak fitted PDFs to the total area of the fitted PDFS. CJV is (sigma_GM+sigma_WM)/(mean_WM-mean_GM), and is a different, ad hoc, measurement of how much the two PDF overlap. * The fitted PDFs are NOT Gaussians. They are of the form f(x) = b((x-p)/w,a), where p=location of peak, w=width, 'a' is a skewness parameter between -1 and 1; the basic distribution is defined by b(x)=(1-x^2)^2*(1+a*x*abs(x)) for -1 < x < 1. -- RWCox - November 2004 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3danisosmooth
Usage: 3danisosmooth [options] dataset Smooths a dataset using an anisotropic smoothing technique. The output dataset is preferentially smoothed to preserve edges. Options : -prefix pname = Use 'pname' for output dataset prefix name. -iters nnn = compute nnn iterations (default=10) -2D = smooth a slice at a time (default) -3D = smooth through slices. Can not be combined with 2D option -mask dset = use dset as mask to include/exclude voxels -automask = automatically compute mask for dataset Can not be combined with -mask -viewer = show central axial slice image every iteration. Starts aiv program internally. -nosmooth = do not do intermediate smoothing of gradients -sigma1 n.nnn = assign Gaussian smoothing sigma before gradient computation for calculation of structure tensor. Default = 0.5 -sigma2 n.nnn = assign Gaussian smoothing sigma after gradient matrix computation for calculation of structure tensor. Default = 1.0 -deltat n.nnn = assign pseudotime step. Default = 0.25 -savetempdata = save temporary datasets each iteration. Dataset prefixes are Gradient, Eigens, phi, Dtensor. Ematrix, Flux and Gmatrix are also stored for the first sub-brick. Where appropriate, the filename is suffixed by .ITER where ITER is the iteration number. Existing datasets will get overwritten. -save_temp_with_diff_measures: Like -savetempdata, but with a dataset named Diff_measures.ITER containing FA, MD, Cl, Cp, and Cs values. -phiding = use Ding method for computing phi (default) -phiexp = use exponential method for computing phi -noneg = set negative voxels to 0 -setneg NEGVAL = set negative voxels to NEGVAL -edgefraction n.nnn = adjust the fraction of the anisotropic component to be added to the original image. Can vary between 0 and 1. Default =0.5 -datum type = Coerce the output data to be stored as the given type which may be byte, short or float. [default=float] -matchorig - match datum type and clip min and max to match input data -help = print this help screen References: Z Ding, JC Gore, AW Anderson, Reduction of Noise in Diffusion Tensor Images Using Anisotropic Smoothing, Mag. Res. Med., 53:485-490, 2005 J Weickert, H Scharr, A Scheme for Coherence-Enhancing Diffusion Filtering with Optimized Rotation Invariance, CVGPR Group Technical Report at the Department of Mathematics and Computer Science,University of Mannheim,Germany,TR 4/2000. J.Weickert,H.Scharr. A scheme for coherence-enhancing diffusion filtering with optimized rotation invariance. J Visual Communication and Image Representation, Special Issue On Partial Differential Equations In Image Processing,Comp Vision Computer Graphics, pages 103-118, 2002. Gerig, G., Kubler, O., Kikinis, R., Jolesz, F., Nonlinear anisotropic filtering of MRI data, IEEE Trans. Med. Imaging 11 (2), 221-232, 1992. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dANOVA
++ 3dANOVA: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program performs single factor Analysis of Variance (ANOVA) on 3D datasets --------------------------------------------------------------- Usage: ----- 3dANOVA -levels r : r = number of factor levels -dset 1 filename : data set for factor level 1 . . .. . . -dset 1 filename data set for factor level 1 . . .. . . -dset r filename data set for factor level r . . .. . . -dset r filename data set for factor level r [-voxel num] : screen output for voxel # num [-diskspace] : print out disk space required for program execution [-mask mset] : use sub-brick #0 of dataset 'mset' to define which voxels to process [-debug level] : request extra output The following commands generate individual AFNI 2-sub-brick datasets: (In each case, output is written to the file with the specified prefix file name.) [-ftr prefix] : F-statistic for treatment effect [-mean i prefix] : estimate of factor level i mean [-diff i j prefix] : difference between factor levels [-contr c1...cr prefix] : contrast in factor levels Modified ANOVA computation options: (December, 2005) ** For details, see https://afni.nimh.nih.gov/sscc/gangc/ANOVA_Mod.html [-old_method] request to perform ANOVA using the previous functionality (requires -OK, also) [-OK] confirm you understand that contrasts that do not sum to zero have inflated t-stats, and contrasts that do sum to zero assume sphericity (to be used with -old_method) [-assume_sph] assume sphericity (zero-sum contrasts, only) This allows use of the old_method for computing contrasts which sum to zero (this includes diffs, for instance). Any contrast that does not sum to zero is invalid, and cannot be used with this option (such as ameans). The following command generates one AFNI 'bucket' type dataset: [-bucket prefix] : create one AFNI 'bucket' dataset whose sub-bricks are obtained by concatenating the above output files; the output 'bucket' is written to file with prefix file name N.B.: For this program, the user must specify 1 and only 1 sub-brick with each -dset command. That is, if an input dataset contains more than 1 sub-brick, a sub-brick selector must be used, e.g., -dset 2 'fred+orig[3]' Example of 3dANOVA: ------------------ Example is based on a study with one factor (independent variable) called 'Pictures', with 3 levels: (1) Faces, (2) Houses, and (3) Donuts The ANOVA is being conducted on the data of subjects Fred and Ethel: 3dANOVA -levels 3 \ -dset 1 fred_Faces+tlrc \ -dset 1 ethel_Faces+tlrc \ \ -dset 2 fred_Houses+tlrc \ -dset 2 ethel_Houses+tlrc \ \ -dset 3 fred_Donuts+tlrc \ -dset 3 ethel_Donuts+tlrc \ \ -ftr Pictures \ -mean 1 Faces \ -mean 2 Houses \ -mean 3 Donuts \ -diff 1 2 FvsH \ -diff 2 3 HvsD \ -diff 1 3 FvsD \ -contr 1 1 -1 FHvsD \ -contr -1 1 1 FvsHD \ -contr 1 -1 1 FDvsH \ -bucket fred_n_ethel_ANOVA INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. --------------------------------------------------- Also see HowTo#5 - Group Analysis on the AFNI website: https://afni.nimh.nih.gov/pub/dist/HOWTO/howto/ht05_group/html/index.shtml ------------------------------------------------------------------------- STORAGE FORMAT: --------------- The default output format is to store the results as scaled short (16-bit) integers. This truncantion might cause significant errors. If you receive warnings that look like this: *+ WARNING: TvsF[0] scale to shorts misfit = 8.09% -- *** Beware then you can force the results to be saved in float format by defining the environment variable AFNI_FLOATIZE to be YES before running the program. For convenience, you can do this on the command line, as in 3dANOVA -DAFNI_FLOATIZE=YES ... other options ... Also see the following links: https://afni.nimh.nih.gov/pub/dist/doc/program_help/common_options.html https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.environment.html ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dANOVA2
++ 3dANOVA: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program performs a two-factor Analysis of Variance (ANOVA) on 3D datasets. Please also see (and consider using) AFNI's gen_group_command.py program to construct your 3dANOVA2 command. That program helps simplify the process of specifying your command. ----------------------------------------------------------- Usage ~1~ 3dANOVA2 -type k : type of ANOVA model to be used: k=1 fixed effects model (A and B fixed) k=2 random effects model (A and B random) k=3 mixed effects model (A fixed, B random) -alevels a : a = number of levels of factor A -blevels b : b = number of levels of factor B -dset 1 1 filename : data set for level 1 of factor A and level 1 of factor B . . . . . . -dset i j filename : data set for level i of factor A and level j of factor B . . . . . . -dset a b filename : data set for level a of factor A and level b of factor B [-voxel num] : screen output for voxel # num [-diskspace] : print out disk space required for program execution [-mask mset] : use sub-brick #0 of dataset 'mset' to define which voxels to process The following commands generate individual AFNI 2-sub-brick datasets: (In each case, output is written to the file with the specified prefix file name.) [-ftr prefix] : F-statistic for treatment effect [-fa prefix] : F-statistic for factor A effect [-fb prefix] : F-statistic for factor B effect [-fab prefix] : F-statistic for interaction [-amean i prefix] : estimate mean of factor A level i [-bmean j prefix] : estimate mean of factor B level j [-xmean i j prefix] : estimate mean of cell at level i of factor A, level j of factor B [-adiff i j prefix] : difference between levels i and j of factor A [-bdiff i j prefix] : difference between levels i and j of factor B [-xdiff i j k l prefix] : difference between cell mean at A=i,B=j and cell mean at A=k,B=l [-acontr c1 ... ca prefix] : contrast in factor A levels [-bcontr c1 ... cb prefix] : contrast in factor B levels [-xcontr c11 ... c1b c21 ... c2b ... ca1 ... cab prefix] : contrast in cell means The following command generates one AFNI 'bucket' type dataset: [-bucket prefix] : create one AFNI 'bucket' dataset whose sub-bricks are obtained by concatenating the above output files; the output 'bucket' is written to file with prefix file name Modified ANOVA computation options: (December, 2005) ~1~ ** These options apply to model type 3, only. For details, see https://afni.nimh.nih.gov/sscc/gangc/ANOVA_Mod.html [-old_method] : request to perform ANOVA using the previous functionality (requires -OK, also) [-OK] : confirm you understand that contrasts that do not sum to zero have inflated t-stats, and contrasts that do sum to zero assume sphericity (to be used with -old_method) [-assume_sph] : assume sphericity (zero-sum contrasts, only) This allows use of the old_method for computing contrasts which sum to zero (this includes diffs, for instance). Any contrast that does not sum to zero is invalid, and cannot be used with this option (such as ameans). ---------------------------------------------------------- Examples of 3dANOVA2 ~1~ (And see also AFNI's gen_group_command.py for what might is likely a simpler method for constructing these commands.) 1) This example is based on a study with a 3 x 4 mixed factorial: design: Factor 1 - DONUTS has 3 levels: (1) chocolate, (2) glazed, (3) sugar Factor 2 - SUBJECTS, of which there are 4 in this analysis: (1) fred, (2) ethel, (3) lucy, (4) ricky 3dANOVA2 \ -type 3 -alevels 3 -blevels 4 \ -dset 1 1 fred_choc+tlrc \ -dset 2 1 fred_glaz+tlrc \ -dset 3 1 fred_sugr+tlrc \ -dset 1 2 ethel_choc+tlrc \ -dset 2 2 ethel_glaz+tlrc \ -dset 3 2 ethel_sugr+tlrc \ -dset 1 3 lucy_choc+tlrc \ -dset 2 3 lucy_glaz+tlrc \ -dset 3 3 lucy_sugr+tlrc \ -dset 1 3 ricky_choc+tlrc \ -dset 2 3 ricky_glaz+tlrc \ -dset 3 3 ricky_sugr+tlrc \ -amean 1 Chocolate \ -amean 2 Glazed \ -amean 3 Sugar \ -adiff 1 2 CvsG \ -adiff 2 3 GvsS \ -adiff 1 3 CvsS \ -acontr 1 1 -2 CGvsS \ -acontr -2 1 1 CvsGS \ -acontr 1 -2 1 CSvsG \ -fa Donuts \ -bucket ANOVA_results The -bucket option will place all of the 3dANOVA2 results (i.e., main effect of DONUTS, means for each of the 3 levels of DONUTS, and contrasts between the 3 levels of DONUTS) into one big dataset with multiple sub-bricks called ANOVA_results+tlrc. ----------------------------------------------------------- Notes ~1~ For this program, the user must specify 1 and only 1 sub-brick with each -dset command. That is, if an input dataset contains more than 1 sub-brick, a sub-brick selector must be used, e.g.: -dset 2 4 'fred+orig[3]' INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. Also see HowTo #5: Group Analysis on the AFNI website: https://afni.nimh.nih.gov/pub/dist/HOWTO/howto/ht05_group/html/index.shtml ------------------------------------------------------------------------- STORAGE FORMAT: --------------- The default output format is to store the results as scaled short (16-bit) integers. This truncantion might cause significant errors. If you receive warnings that look like this: *+ WARNING: TvsF[0] scale to shorts misfit = 8.09% -- *** Beware then you can force the results to be saved in float format by defining the environment variable AFNI_FLOATIZE to be YES before running the program. For convenience, you can do this on the command line, as in 3dANOVA -DAFNI_FLOATIZE=YES ... other options ... Also see the following links: https://afni.nimh.nih.gov/pub/dist/doc/program_help/common_options.html https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.environment.html ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dANOVA3
This program performs three-factor ANOVA on 3D data sets. Please also see (and consider using) AFNI's gen_group_command.py program to construct your 3dANOVA2 command. That program helps simplify the process of specifying your command. ----------------------------------------------------------- Usage ~1~ 3dANOVA3 -type k type of ANOVA model to be used: k = 1 A,B,C fixed; AxBxC k = 2 A,B,C random; AxBxC k = 3 A fixed; B,C random; AxBxC k = 4 A,B fixed; C random; AxBxC k = 5 A,B fixed; C random; AxB,BxC,C(A) -alevels a a = number of levels of factor A -blevels b b = number of levels of factor B -clevels c c = number of levels of factor C -dset 1 1 1 filename data set for level 1 of factor A and level 1 of factor B and level 1 of factor C . . . . . . -dset i j k filename data set for level i of factor A and level j of factor B and level k of factor C . . . . . . -dset a b c filename data set for level a of factor A and level b of factor B and level c of factor C [-voxel num] screen output for voxel # num [-diskspace] print out disk space required for program execution [-mask mset] use sub-brick #0 of dataset 'mset' to define which voxels to process The following commands generate individual AFNI 2 sub-brick datasets: (In each case, output is written to the file with the specified prefix file name.) [-fa prefix] F-statistic for factor A effect [-fb prefix] F-statistic for factor B effect [-fc prefix] F-statistic for factor C effect [-fab prefix] F-statistic for A*B interaction [-fac prefix] F-statistic for A*C interaction [-fbc prefix] F-statistic for B*C interaction [-fabc prefix] F-statistic for A*B*C interaction [-amean i prefix] estimate of factor A level i mean [-bmean i prefix] estimate of factor B level i mean [-cmean i prefix] estimate of factor C level i mean [-xmean i j k prefix] estimate mean of cell at factor A level i, factor B level j, factor C level k [-adiff i j prefix] difference between factor A levels i and j (with factors B and C collapsed) [-bdiff i j prefix] difference between factor B levels i and j (with factors A and C collapsed) [-cdiff i j prefix] difference between factor C levels i and j (with factors A and B collapsed) [-xdiff i j k l m n prefix] difference between cell mean at A=i,B=j, C=k, and cell mean at A=l,B=m,C=n [-acontr c1...ca prefix] contrast in factor A levels (with factors B and C collapsed) [-bcontr c1...cb prefix] contrast in factor B levels (with factors A and C collapsed) [-ccontr c1...cc prefix] contrast in factor C levels (with factors A and B collapsed) [-aBcontr c1 ... ca : j prefix] 2nd order contrast in A, at fixed B level j (collapsed across C) [-Abcontr i : c1 ... cb prefix] 2nd order contrast in B, at fixed A level i (collapsed across C) [-aBdiff i_1 i_2 : j prefix] difference between levels i_1 and i_2 of factor A, with factor B fixed at level j [-Abdiff i : j_1 j_2 prefix] difference between levels j_1 and j_2 of factor B, with factor A fixed at level i [-abmean i j prefix] mean effect at factor A level i and factor B level j The following command generates one AFNI 'bucket' type dataset: [-bucket prefix] create one AFNI 'bucket' dataset whose sub-bricks are obtained by concatenating the above output files; the output 'bucket' is written to file with prefix file name Modified ANOVA computation options: (December, 2005) ~1~ ** These options apply to model types 4 and 5, only. For details, see: https://afni.nimh.nih.gov/sscc/gangc/ANOVA_Mod.html https://afni.nimh.nih.gov/afni/doc/manual/ANOVAm.pdf [-old_method] request to perform ANOVA using the previous functionality (requires -OK, also) [-OK] confirm you understand that contrasts that do not sum to zero have inflated t-stats, and contrasts that do sum to zero assume sphericity (to be used with -old_method) [-assume_sph] assume sphericity (zero-sum contrasts, only) This allows use of the old_method for computing contrasts which sum to zero (this includes diffs, for instance). Any contrast that does not sum to zero is invalid, and cannot be used with this option (such as ameans). ----------------------------------------------------------------- Examples ~1~ (And see also AFNI's gen_group_command.py for what might is likely a simpler method for constructing these commands.) 1) The "classic" houses/faces/donuts for 4 subjects (2 genders) (level sets are gender (M/W), image (H/F/D), and subject) Note: factor C is really subject within gender (since it is nested). There are 4 subjects in this example, and 2 subjects per gender. So clevels is 2. 3dANOVA3 -type 5 \ -alevels 2 \ -blevels 3 \ -clevels 2 \ -dset 1 1 1 man1_houses+tlrc \ -dset 1 2 1 man1_faces+tlrc \ -dset 1 3 1 man1_donuts+tlrc \ -dset 1 1 2 man2_houses+tlrc \ -dset 1 2 2 man2_faces+tlrc \ -dset 1 3 2 man2_donuts+tlrc \ -dset 2 1 1 woman1_houses+tlrc \ -dset 2 2 1 woman1_faces+tlrc \ -dset 2 3 1 woman1_donuts+tlrc \ -dset 2 1 2 woman2_houses+tlrc \ -dset 2 2 2 woman2_faces+tlrc \ -dset 2 3 2 woman2_donuts+tlrc \ -adiff 1 2 MvsW \ -bdiff 2 3 FvsD \ -bcontr -0.5 1 -0.5 FvsHD \ -aBcontr 1 -1 : 1 MHvsWH \ -aBdiff 1 2 : 1 same_as_MHvsWH \ -Abcontr 2 : 0 1 -1 WFvsWD \ -Abdiff 2 : 2 3 same_as_WFvsWD \ -Abcontr 2 : 1 7 -4.2 goofy_example \ -bucket donut_anova Notes ~1~ For this program, the user must specify 1 and only 1 sub-brick with each -dset command. That is, if an input dataset contains more than 1 sub-brick, a sub-brick selector must be used, e.g.: -dset 2 4 5 'fred+orig[3]' INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ------------------------------------------------------------------------- STORAGE FORMAT: --------------- The default output format is to store the results as scaled short (16-bit) integers. This truncantion might cause significant errors. If you receive warnings that look like this: *+ WARNING: TvsF[0] scale to shorts misfit = 8.09% -- *** Beware then you can force the results to be saved in float format by defining the environment variable AFNI_FLOATIZE to be YES before running the program. For convenience, you can do this on the command line, as in 3dANOVA -DAFNI_FLOATIZE=YES ... other options ... Also see the following links: https://afni.nimh.nih.gov/pub/dist/doc/program_help/common_options.html https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.environment.html ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAttribute
Usage ~1~ 3dAttribute [options] aname dset Prints (to stdout) the value of the attribute 'aname' from the header of dataset 'dset'. If the attribute doesn't exist, prints nothing and sets the exit status to 1. See the full list of attributes in README.attributes here: https://afni.nimh.nih.gov/pub/dist/doc/program_help/README.attributes.html Options ~1~ -name = Include attribute name in printout -all = Print all attributes [don't put aname on command line] Also implies '-name'. Attributes print in whatever order they are in the .HEAD file, one per line. You may want to do '3dAttribute -all elvis+orig | sort' to get them in alphabetical order. -center = Center of volume in RAI coordinates. Note that center is not itself an attribute in the .HEAD file. It is calculated from other attributes. Special options for string attributes: -ssep SSEP Use string SSEP as a separator between strings for multiple sub-bricks. The default is '~', which is what is used internally in AFNI's .HEAD file. For tcsh, I recommend ' ' which makes parsing easy, assuming each individual string contains no spaces to begin with. Try -ssep 'NUM' -sprep SPREP Use string SPREP to replace blank space in string attributes. -quote Use single quote around each string. Examples ~1~ 3dAttribute -quote -ssep ' ' BRICK_LABS SomeStatDset+tlrc.HEAD 3dAttribute -quote -ssep 'NUM' -sprep '+' BRICK_LABS SomeStatDset+tlrc.HEAD 3dAttribute BRICK_STATAUX SomeStatDset+tlrc.HEAD'[0]' # ... which outputs information for just the [0]th brick of a dset. # If that dset were an F-stat, then the output might look like: # 0 4 2 2 430 # ... which, in order, translate to: # 0 --> the index of the brick in question # 4 --> the brick's statistical code, findable in README.attributes: # '#define FUNC_FT_TYPE 4 /* fift: F-statistic */' # to be an F-statistic # 2 --> the number of parameters for that stat (shown subsequently) # 2 --> here, the 1st parameter for the F-stat: 'Numerator DOF' # 430 --> here, the 2nd parameter for the F-stat: 'Denominator DOF' ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAutobox
++ 3dAutobox: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] Usage: 3dAutobox [options] DATASET Computes size of a box that fits around the volume. Also can be used to crop the volume to that box. The default 'info message'-based terminal text is a set of IJK coords. See below for options to display coordinates in other ways, as well as to save them in a text file. Please note in particular the difference between *ijk* and *ijkord* outputs, for scripting. OPTIONS: ~1~ -prefix PREFIX :Crop the input dataset to the size of the box, and write an output dataset with PREFIX for the name. *If -prefix is not used, no new volume is written out, just the (x,y,z) extents of the voxels to be kept. -input DATASET :An alternate way to specify the input dataset. The default method is to pass DATASET as the last parameter on the command line. -noclust :Don't do any clustering to find box. Any non-zero voxel will be preserved in the cropped volume. The default method uses some clustering to find the cropping box, and will clip off small isolated blobs. -extent :Write to standard out the spatial extent of the box -extent_xyz_quiet :The same numbers as '-extent', but only numbers and no string content. Ordering is RLAPIS. -extent_ijk :Write out the 6 auto bbox ijk slice numbers to screen: imin imax jmin jmax kmin kmax Note that resampling would affect the ijk vals (but not necessarily the xyz ones). -extent_ijk_to_file FF :Write out the 6 auto bbox ijk slice numbers to a simple-formatted text file FF (single row file): imin imax jmin jmax kmin kmax (same notes as above apply). -extent_ijk_midslice :Write out the 3 ijk midslices of the autobox to the screen: imid jmid kmid These are obtained via: (imin + imax)/2, etc. -extent_ijkord :Write out the 6 auto bbox ijk slice numbers to screen but in a particular order and format (see 'NOTE on *ijkord* format', below). NB: This ordering is useful if you want to use the output indices in 3dcalc expressions. -extent_ijkord_to_file FFORRD :Write out the 6 auto bbox ijk slice numbers to a file but in a particular order and format (see 'NOTE on *ijkord* format', below). NB: This option is quite useful if you want to use the output indices in 3dcalc expressions. -extent_xyz_to_file GG :Write out the 6 auto bbox xyz coords to a simple-formatted text file GG (single row file): xmin xmax ymin ymax zmin zmax (same values as '-extent'). -extent_xyz_midslice :Write out the 3 xyz midslices of the autobox to the screen: xmid ymid zmid These are obtained via: (xmin + xmax)/2, etc. These follow the same meaning as '-extent'. -npad NNN :Number of extra voxels to pad on each side of box, since some troublesome people (that's you, LRF) want this feature for no apparent reason. ** With this option, it is possible to get a dataset thatis actually bigger than the input. ** You can input a negative value for NNN, which will crop the dataset even more than the automatic method. -npad_safety_on :Constrain npad-ded extents to be within dset. So, each index is bounded to be in range [0, L-1], where L is matrix length along that dimension. NOTE on *ijkord* format ~1~ Using any of the '-*ijkord*' options above will output pairs of ijk indices just like the regular ijk options, **but** they will be ordered in a way that you can associate each of the i, j, and k indices with a standard x, y and z coordinate direction. Without this ordering, resampling a dataset could change what index is associated with which coordinate axis. That situation can be confusing for scripting (and by confusing, we mean 'bad'). The output format for any '-*ijkord*' options is a 3x3 table, where the first column is the index value (i, j or k), and the next two columns are the min and max interval boundaries for the autobox. Importantly, the rows are placed in order so that the top corresponds to the x-axis, the middle to the y-axis and the bottom to the z-axis. So, if you had the following table output for a dset: k 10 170 i 35 254 j 21 199 ... you would look at the third row for the min/max slice values along the z-axis, and you would use the index 'j' to refer to it in, say, a 3dcalc expression. Note that the above example table output came from a dataset with ASL orientation. We can see how that fits, recalling that the first, second and third rows tell us about x, y and z info, respectively; and that i, j and k refer to the first, second and third characters in the orientation string. So, the third (z-like) row contains a j, which points us at the middle character in the orientation, which is S, which is along the z-axis---all consistent! Similarly, the top (x-like) row contains a k, which points us at the last char in the orientation, which is L and that is along the x-axis---phew! The main point of this would be to extra this information and use it in a script. If you knew that you wanted the z-slice range to use in a 3dcalc 'within()' expression, then you could extract the 3rd row to get the correct index and slice ranges, e.g., in tcsh: set vvv = `sed -n 3p FILE_ijkord.txt` ... where now ${vvv} will have 3 values, the first of which is the relevant index letter, then the min and max slice range values. So an example 3dcalc expression to keep values only within that slice range: 3dcalc \ -a DSET \ -expr "a*within(${vvv[1]},${vvv[2]},${vvv[3]})" \ -prefix DSET_SUBSET ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAutomask
Usage: 3dAutomask [options] dataset Input dataset is EPI 3D+time, or a skull-stripped anatomical. Output dataset is a brain-only mask dataset. This program by itself does NOT do 'skull-stripping'. Use program 3dSkullStrip for that purpose! Method: + Uses 3dClipLevel algorithm to find clipping level. + Keeps only the largest connected component of the supra-threshold voxels, after an erosion/dilation step. + Writes result as a 'fim' type of functional dataset, which will be 1 inside the mask and 0 outside the mask. Options: -------- -prefix ppp = Write mask into dataset with prefix 'ppp'. [Default == 'automask'] -apply_prefix ppp = Apply mask to input dataset and save masked dataset. If an apply_prefix is given and not the usual prefix, the only output will be the applied dataset -clfrac cc = Set the 'clip level fraction' to 'cc', which must be a number between 0.1 and 0.9. A small 'cc' means to make the initial threshold for clipping (a la 3dClipLevel) smaller, which will tend to make the mask larger. [default=0.5] -nograd = The program uses a 'gradual' clip level by default. To use a fixed clip level, use '-nograd'. [Change to gradual clip level made 24 Oct 2006.] -peels pp = Peel (erode) the mask 'pp' times, then unpeel (dilate). Using NN2 neighborhoods, clips off protuberances less than 2*pp voxels thick. Turn off by setting to 0. [Default == 1] -NN1 -NN2 -NN3 = Erode and dilate using different neighbor definitions NN1=faces, NN2=edges, NN3= corners [Default=NN2] Applies to erode and dilate options, if present. Note the default peeling processes still use NN2 unless the peels are set to 0 -nbhrs nn = Define the number of neighbors needed for a voxel NOT to be eroded. The 18 nearest neighbors in the 3D lattice are used, so 'nn' should be between 6 and 26. [Default == 17] -q = Don't write progress messages (i.e., be quiet). -eclip = After creating the mask, remove exterior voxels below the clip threshold. -dilate nd = Dilate the mask outwards 'nd' times. -erode ne = Erode the mask inwards 'ne' times. -SI hh = After creating the mask, find the most superior voxel, then zero out everything more than 'hh' millimeters inferior to that. hh=130 seems to be decent (i.e., for Homo Sapiens brains). -depth DEP = Produce a dataset (DEP) that shows how many peel operations it takes to get to a voxel in the mask. The higher the number, the deeper a voxel is located in the mask. Note this uses the NN1,2,3 neighborhoods above with a default of 2 for edge-sharing neighbors None of -peels, -dilate, or -erode affect this option. -------------------------------------------------------------------- How to make an edge-of-brain mask from an anatomical volume: * 3dSkullStrip to create a brain-only dataset; say, Astrip+orig * 3dAutomask -prefix Amask Astrip+orig * Create a mask of edge-only voxels via 3dcalc -a Amask+orig -b a+i -c a-i -d a+j -e a-j -f a+k -g a-k \ -expr 'ispositive(a)*amongst(0,b,c,d,e,f,g)' -prefix Aedge which will be 1 at all voxels in the brain mask that have a nearest neighbor that is NOT in the brain mask. * cf. '3dcalc -help' DIFFERENTIAL SUBSCRIPTS for information on the 'a+i' et cetera inputs used above. * In regions where the brain mask is 'stair-stepping', then the voxels buried inside the corner of the steps probably won't show up in this edge mask: ...00000000... ...aaa00000... ...bbbaa000... ...bbbbbaa0... Only the 'a' voxels are in this edge mask, and the 'b' voxels down in the corners won't show up, because they only touch a 0 voxel on a corner, not face-on. Depending on your use for the edge mask, this effect may or may not be a problem. -------------------------------------------------------------------- ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dAutoTcorrelate
Usage: 3dAutoTcorrelate [options] dset 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]. *** Also see program 3dTcorrMap *** Options: -pearson = Correlation is the normal Pearson (product moment) correlation coefficient [default]. -eta2 = Output is eta^2 measure from Cohen et al., NeuroImage, 2008: http://www.ncbi.nlm.nih.gov/pmc/articles/PMC2705206/ http://dx.doi.org/10.1016/j.neuroimage.2008.01.066 ** '-eta2' is intended to be used to measure the similarity between 2 correlation maps; therefore, this option is to be used in a second stage analysis, where the input dataset is the output of running 3dAutoTcorrelate with the '-pearson' option -- the voxel 'time series' from that first stage run is the correlation map of that voxel with all other voxels. ** '-polort -1' is recommended with this option! ** Odds are you do not want use this option if the dataset on which eta^2 is to be computed was generated with options -mask_only_targets or -mask_source. In this program, the eta^2 is computed between pseudo- timeseries (the 4th dimension of the dataset). If you want to compute eta^2 between sub-bricks then use 3ddot -eta2 instead. -spearman AND -quadrant are disabled at this time :-( -polort m = Remove polynomial trend of order 'm', for m=-1..3. [default is m=1; removal is by least squares]. Using m=-1 means no detrending; this is only useful for data/information that has been pre-processed. -autoclip = Clip off low-intensity regions in the dataset, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The mask is determined the same way that 3dAutomask works. -mask mmm = Mask of both 'source' and 'target' voxels. ** Restricts computations to those in the mask. Output volumes are restricted to masked voxels. Also, only masked voxels will have non-zero output. ** A dataset with 1000 voxels would lead to output of 1000 sub-bricks. With a '-mask' of 50 voxels, the output dataset have 50 sub-bricks, where the 950 unmasked voxels would be all zero in all 50 sub-bricks (unless option '-mask_only_targets' is also used). ** The mask is encoded in the output dataset header in the attribute named 'AFNI_AUTOTCORR_MASK' (cf. 3dMaskToASCII). -mask_only_targets = Provide output for all voxels. ** Used with '-mask': every voxel is correlated with each of the mask voxels. In the example above, there would be 50 output sub-bricks; the n-th output sub-brick would contain the correlations of the n-th voxel in the mask with ALL 1000 voxels in the dataset (rather than with just the 50 voxels in the mask). -mask_source sss = Provide output for voxels only in mask sss ** For each seed in mask mm, compute correlations only with non-zero voxels in sss. If you have 250 non-zero voxels in sss, then the output will still have 50 sub-bricks, but each n-th sub-brick will have non-zero values at the 250 non-zero voxels in sss Do not use this option along with -mask_only_targets -prefix p = Save output into dataset with prefix 'p' [default prefix is 'ATcorr']. -out1D FILE.1D = Save output in a text file formatted thusly: Row 1 contains the 1D indices of non zero voxels in the mask from option -mask. Column 1 contains the 1D indices of non zero voxels in the mask from option -mask_source The rest of the matrix contains the correlation/eta2 values. Each column k corresponds to sub-brick k in the output volume p. To see 1D indices in AFNI, right click on the top left corner of the AFNI controller - where coordinates are shown - and chose voxel indices. A 1D index (ijk) is computed from the 3D (i,j,k) indices: ijk = i + j*Ni + k*Ni*Nj , with Ni and Nj being the number of voxels in the slice orientation and given by: 3dinfo -ni -nj YOUR_VOLUME_HERE This option can only be used in conjunction with options -mask and -mask_source. Otherwise it makes little sense to write a potentially enormous text file. -time = Mark output as a 3D+time dataset instead of an anat bucket. -mmap = Write .BRIK results to disk directly using Unix mmap(). This trick can speed the program up when the amount of memory required to hold the output is very large. ** In many case, the amount of time needed to write the results to disk is longer than the CPU time. This option can shorten the disk write time. ** If the program crashes, you'll have to manually remove the .BRIK file, which will have been created before the loop over voxels and written into during that loop, rather than being written all at once at the end of the analysis, as is usually the case. ** If the amount of memory needed is bigger than the RAM on your system, this program will be very slow with or without '-mmap'. ** This option won't work with NIfTI-1 (.nii) output! Example: correlate every voxel in mask_in+tlrc with only those voxels in mask_out+tlrc (the rest of each volume is zero, for speed). Assume detrending was already done along with other pre-processing. The output will have one volume per masked voxel in mask_in+tlrc. Volumes will be labeled by the ijk index triples of mask_in+tlrc. 3dAutoTcorrelate -mask_source mask_out+tlrc -mask mask_in+tlrc \ -polort -1 -prefix test_corr clean_epi+tlrc Notes: * The output dataset is anatomical bucket type of shorts (unless '-time' is used). * Values are scaled so that a correlation (or eta-squared) of 1 corresponds to a value of 10000. * The output file might be gigantic and you might run out of memory running this program. Use at your own risk! ++ If you get an error message like *** malloc error for dataset sub-brick this means that the program ran out of memory when making the output dataset. ++ If this happens, you can try to use the '-mmap' option, and if you are lucky, the program may actually run. * The program prints out an estimate of its memory usage when it starts. It also prints out a progress 'meter' to keep you pacified. * This is a quick hack for Peter Bandettini. Now pay up. * OpenMP-ized for Hang Joon Jo. Where's my baem-sul? -- RWCox - 31 Jan 2002 and 16 Jul 2010 ========================================================================= * This binary version of 3dAutoTcorrelate is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3daxialize
[7m*+ WARNING:[0m This program (3daxialize) is old, not maintained, and probably useless! Usage: 3daxialize [options] dataset Purpose: Read in a dataset and write it out as a new dataset with the data brick oriented as axial slices. The input dataset must have a .BRIK file. One application is to create a dataset that can be used with the AFNI volume rendering plugin. Options: -prefix ppp = Use 'ppp' as the prefix for the new dataset. [default = 'axialize'] -verb = Print out a progress report. The following options determine the order/orientation in which the slices will be written to the dataset: -sagittal = Do sagittal slice order [-orient ASL] -coronal = Do coronal slice order [-orient RSA] -axial = Do axial slice order [-orient RAI] This is the default AFNI axial order, and is the one currently required by the volume rendering plugin; this is also the default orientation output by this program (hence the program's name). -orient code = Orientation code for output. The code must be 3 letters, one each from the pairs {R,L} {A,P} {I,S}. The first letter gives the orientation of the x-axis, the second the orientation of the y-axis, the third the z-axis: R = Right-to-left L = Left-to-right A = Anterior-to-posterior P = Posterior-to-anterior I = Inferior-to-superior S = Superior-to-inferior If you give an illegal code (e.g., 'LPR'), then the program will print a message and stop. N.B.: 'Neurological order' is -orient LPI -frugal = Write out data as it is rotated, a sub-brick at a time. This saves a little memory and was the previous behavior. Note the frugal option is not available with NIFTI datasets INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dBallMatch
-------------------------------------- Usage #1: 3dBallMatch dataset [radius] -------------------------------------- ----------------------------------------------------------------------- Usage #2: 3dBallMatch [options] where the pitifully few options are: -input dataset = read this dataset -ball radius = set the radius of the 3D ball to match (mm) -spheroid a b = match with a spheroid of revolution, with principal axis radius of 'a' and secondary axes radii 'b' ++ this option is considerably slower ----------------------------------------------------------------------- ------------------- WHAT IT IS GOOD FOR ------------------- * This program tries to find a good match between a ball (filled sphere) of the given radius (in mm) and a dataset. The goal is to find a crude approximate center of the brain quickly. * The output can be used to re-center a dataset so that its coordinate origin is inside the brain and/or as a starting point for more refined 3D alignment. Sample scripts are given below. * The reason for this program is that not all brain images are even crudely centered by using the center-of-mass ('3dAllineate -cmass') as a starting point -- if the volume covered by the image includes a lot of neck or even shoulders, then the center-of-mass may be far from the brain. * If you don't give a radius, the default is 72 mm, which is about the radius of an adult human brain/cranium. A larger value would be needed for elephant brain images. A smaller value for marmosets. * For advanced use, you could try a prolate spheroid, using something like 3dBallMatch -input Fred.nii -spheroid 90 70 for a human head image (that was not skull stripped). This option is several times slower than the 'ball' option, as multiple spheroids have to be correlated with the input dataset. * This program does NOT work well with datasets containing large amounts of negative values or background junk -- such as I've seen with animal MRI scans and CT scans. Such datasets will likely require some repair first, such as cropping (cf. 3dZeropad), to make this program useful. * Frankly, this program may not be that useful for any purpose :( * The output is text to stdout containing 3 triples of numbers, all on one line: i j k xs ys zs xd yd zd where i j k = index triple of the central voxel xs ys zs = values to use in '3drefit -dxxorigin' (etc.) to make (i,j,k) be at coordinates (x,y,z)=(0,0,0) xd yd zd = DICOM-order (x,y,z) coordinates of (i,j,k) in the input dataset * The intention is that this output line be captured and then the appropriate pieces be used for some higher purpose. -------------------------------------------------------------- SAMPLE SCRIPT - VISUALIZING THE MATCHED LOCATION (csh syntax) -------------------------------------------------------------- Below is a script to process all the entries in a directory. #!/bin/tcsh # optional: start a virtual X11 server set xdisplay = `count_afni -dig 1 3 999 R1` echo " -- trying to start Xvfb :${xdisplay}" Xvfb :${xdisplay} -screen 0 1024x768x24 >& /dev/null & sleep 1 set display_old = $DISPLAY setenv DISPLAY :${xdisplay} # loop over all subjects foreach sss ( sub-?????_T1w.nii.gz ) # extract subject ID code set sub = `echo $sss | sed -e 's/sub-//' -e 's/_T1w.nii.gz//'` # skip if already finished if ( -f $sub.match ) continue if ( -f $sub.sag.jpg ) continue if ( -f $sub.cor.jpg ) continue # run the program, save output to a file 3dBallMatch $sss > $sub.match # capture the output for use below set ijk = ( `cat $sub.match` ) echo $sub $ijk # run afni to make some QC images afni -DAFNI_NOSPLASH=YES \ -DAFNI_NOPLUGINS=YES \ -com "OPEN_WINDOW A.sagittalimage" \ -com "OPEN_WINDOW A.coronalimage" \ -com "SET_IJK $ijk[1-3]" \ -com "SAVE_JPEG A.sagittalimage $sub.sag.jpg" \ -com "SAVE_JPEG A.coronalimage $sub.cor.jpg" \ -com "QUITT" \ $sss # end of loop over subject end # kill the virtual X11 server (if it was started above) sleep 1 killall Xvfb # make a movie of the sagittal slices im_to_mov -resize -prefix Bsag -npure 4 -nfade 0 *.sag.jpg # make a movie of the coronal slices im_to_mov -resize -prefix Bcor -npure 4 -nfade 0 *.cor.jpg exit 0 ------------------------------------------------------------ SAMPLE SCRIPT - IMPROVING THE MATCHED LOCATION (csh syntax) ------------------------------------------------------------ This script is an extension of the one above, where it uses 3dAllineate to align the human brain image to the MNI template, guided by the initial point computed by 3dBallMatch. The output of 3dAllineate is the coordinate of the center of the original volume, in the first 3 values stored in '*Aparam.1D' file. * Note that the 3dAllineate step presumes that the input dataset is a T1-weighted volume. A different set of options would have to be used for an EPI (T2*-weighted) or T2-weighted volume. * This script worked pretty well for putting the crosshairs at the 'origin' of the brain -- near the anterior commissure. Of course, you will need to evaluate its performance yourself. #!/bin/tcsh # optional: start Xvfb to avoid the AFNI GUI starting visibly set xdisplay = `count_afni -dig 1 3 999 R1` echo " -- trying to start Xvfb :${xdisplay}" Xvfb :${xdisplay} -screen 0 1024x768x24 >& /dev/null & sleep 1 set display_old = $DISPLAY setenv DISPLAY :${xdisplay} # loop over datasets in the current directory foreach sss ( anat_sub?????.nii.gz ) # extract the subject identifier code (the '?????') set sub = `echo $sss | sed -e 's/anat_sub//' -e 's/.nii.gz//'` # if 3dAllineate was already run on this, skip to next dataset if ( -f $sub.Aparam.1D ) continue # find the 'center' voxel location with 3dBallMatch if ( ! -f $sub.match ) then echo "Running 3dBallMatch $sss" 3dBallMatch $sss | tee $sub.match endif # extract results from 3dBallMatch output # in this case, we want the final triplet of coordinates set ijk = ( `cat $sub.match` ) # set shift range to be 55 mm about 3dBallMatch coordinates set xd = $ijk[7] ; set xbot = `ccalc "${xd}-55"` ; set xtop = `ccalc "${xd}+55"` set yd = $ijk[8] ; set ybot = `ccalc "${yd}-55"` ; set ytop = `ccalc "${yd}+55"` set zd = $ijk[9] ; set zbot = `ccalc "${zd}-55"` ; set ztop = `ccalc "${zd}+55"` # Align the brain image volume with 3dAllineate: # match to 'skull on' part of MNI template = sub-brick [1] # only save the parameters, not the final aligned dataset 3dAllineate \ -base ~/abin/MNI152_2009_template_SSW.nii.gz'[1]' \ -source $sss \ -parang 1 $xbot $xtop \ -parang 2 $ybot $ytop \ -parang 3 $zbot $ztop \ -prefix NULL -lpa \ -1Dparam_save $sub.Aparam.1D \ -conv 3.666 -fineblur 3 -num_rtb 0 -norefinal -verb # 1dcat (instead of cat) to strip off the comments at the top of the file # the first 3 values in 'param' are the (x,y,z) shifts # Those values could be used in 3drefit to re-center the dataset set param = ( `1dcat $sub.Aparam.1D` ) # run AFNI to produce the snapshots with crosshairs at # the 3dBallMatch center and the 3dAllineate center # - B.*.jpg = 3dBallMatch result in crosshairs # - A.*.jpg = 3dAllineate result in crosshairs afni -DAFNI_NOSPLASH=YES \ -DAFNI_NOPLUGINS=YES \ -com "OPEN_WINDOW A.sagittalimage" \ -com "SET_IJK $ijk[1-3]" \ -com "SAVE_JPEG A.sagittalimage B.$sub.sag.jpg" \ -com "SET_DICOM_XYZ $param[1-3]" \ -com "SAVE_JPEG A.sagittalimage A.$sub.sag.jpg" \ -com "QUITT" \ $sss # End of loop over datasets end # stop Xvfb (only needed if it was started above) sleep 1 killall Xvfb # make movies from the resulting images im_to_mov -resize -prefix Bsag -npure 4 -nfade 0 B.[1-9]*.sag.jpg im_to_mov -resize -prefix Asag -npure 4 -nfade 0 A.[1-9]*.sag.jpg exit 0 ---------------------------- HOW IT WORKS (approximately) ---------------------------- 1] Create the automask of the input dataset (as in 3dAutomask). + This is a 0/1 binary marking of outside/inside voxels. + Then convert it to a -1/+1 mask instead. 2] Create a -1/+1 mask for the ball [-1=outside, +1=inside], inside a rectangular box. 3] Convolve these 2 masks (using FFTs for speed). + Basically, this is moving the ball around, then adding up the voxel counts where the masks match sign (both positive means ball and dataset are both 'inside'; both negative means ball and dataset are both 'outside'), and subtracting off the voxel counts where the mask differ in sign (one is 'inside' and one is 'outside' == not matched). + That is, the convolution value is the sum of matched voxels minus the sum of mismatched voxels, at every location of offset (i,j,k) of the corner of the ball mask. + The ball mask is in a cube of side 2*radius, which has volume 8*radius^3. The volume of the ball is 4*pi/3*radius^3, so the inside of the ball is about 4*pi/(3*8) = 52% of the volume of the cube -- that is, inside and outside voxels are (roughly) matched, so they have (approximately) equal weight. + Most of the CPU time is in the 3D FFTs required. 4] Find the centroid of the locations where the convolution is positive (matches win over non-matches) and at least 5% of the maximum convolution. This centroid gives (i,j,k). Why the centroid? I found that the peak convolution location is not very stable, as a lot of locations have results barely less than the peak value -- it was more stable to average them together. ------------------------ WHY 'ball' NOT 'sphere'? ------------------------ * Because a 'sphere' is a 2D object, the surface of the 3D object 'ball'. * Because my training was in mathematics, where precise terminology has been developed and honed for centuries. * Because I'm yanking your chain. Any other questions? No? Good. ------- CREDITS ------- By RWCox, September 2020 (the year it all fell apart). Delenda est. Never forget.

AFNI program: 3dBandpass
-------------------------------------------------------------------------- ** NOTA BENE: For the purpose of preparing resting-state FMRI datasets ** ** for analysis (e.g., with 3dGroupInCorr), this program is now mostly ** ** superseded by the afni_proc.py script. See the 'afni_proc.py -help' ** ** section 'Resting state analysis (modern)' to get our current rs-FMRI ** ** pre-processing recommended sequence of steps. -- RW Cox, et alii. ** -------------------------------------------------------------------------- ** If you insist on doing your own bandpassing, I now recommend using ** ** program 3dTproject instead of this program. 3dTproject also can do ** ** censoring and other nuisance regression at the same time -- RW Cox. ** -------------------------------------------------------------------------- Usage: 3dBandpass [options] fbot ftop dataset * One function of this program is to prepare datasets for input to 3dSetupGroupInCorr. Other uses are left to your imagination. * 'dataset' is a 3D+time sequence of volumes ++ This must be a single imaging run -- that is, no discontinuities in time from 3dTcat-ing multiple datasets together. * fbot = lowest frequency in the passband, in Hz ++ fbot can be 0 if you want to do a lowpass filter only; HOWEVER, the mean and Nyquist freq are always removed. * ftop = highest frequency in the passband (must be > fbot) ++ if ftop > Nyquist freq, then it's a highpass filter only. * Set fbot=0 and ftop=99999 to do an 'allpass' filter. ++ Except for removal of the 0 and Nyquist frequencies, that is. * You cannot construct a 'notch' filter with this program! ++ You could use 3dBandpass followed by 3dcalc to get the same effect. ++ If you are understand what you are doing, that is. ++ Of course, that is the AFNI way -- if you don't want to understand what you are doing, use Some other PrograM, and you can still get Fine StatisticaL maps. * 3dBandpass will fail if fbot and ftop are too close for comfort. ++ Which means closer than one frequency grid step df, where df = 1 / (nfft * dt) [of course] * The actual FFT length used will be printed, and may be larger than the input time series length for the sake of efficiency. ++ The program will use a power-of-2, possibly multiplied by a power of 3 and/or 5 (up to and including the 3rd power of each of these: 3, 9, 27, and 5, 25, 125). * Note that the results of combining 3dDetrend and 3dBandpass will depend on the order in which you run these programs. That's why 3dBandpass has the '-ort' and '-dsort' options, so that the time series filtering can be done properly, in one place. * The output dataset is stored in float format. * The order of processing steps is the following (most are optional): (0) Check time series for initial transients [does not alter data] (1) Despiking of each time series (2) Removal of a constant+linear+quadratic trend in each time series (3) Bandpass of data time series (4) Bandpass of -ort time series, then detrending of data with respect to the -ort time series (5) Bandpass and de-orting of the -dsort dataset, then detrending of the data with respect to -dsort (6) Blurring inside the mask [might be slow] (7) Local PV calculation [WILL be slow!] (8) L2 normalization [will be fast.] -------- OPTIONS: -------- -despike = Despike each time series before other processing. ++ Hopefully, you don't actually need to do this, which is why it is optional. -ort f.1D = Also orthogonalize input to columns in f.1D ++ Multiple '-ort' options are allowed. -dsort fset = 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. -nodetrend = 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. -dt dd = set time step to 'dd' sec [default=from dataset header] -nfft N = set the FFT length to 'N' [must be a legal value] -norm = Make all output time series have L2 norm = 1 ++ i.e., sum of squares = 1 -mask mset = Mask dataset -automask = Create a mask from the input dataset -blur fff = Blur (inside the mask only) with a filter width (FWHM) of 'fff' millimeters. -localPV rrr = 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. -input dataset = Alternative way to specify input dataset. -band fbot ftop = Alternative way to specify passband frequencies. -prefix ppp = Set prefix name of output dataset. -quiet = Turn off the fun and informative messages. (Why?) -notrans = Don't check for initial positive transients in the data: *OR* ++ The test is a little slow, so skipping it is OK, -nosat if you KNOW the data time series are transient-free. ++ Or set AFNI_SKIP_SATCHECK to YES. ++ Initial transients won't be handled well by the bandpassing algorithm, and in addition may seriously contaminate any further processing, such as inter-voxel correlations via InstaCorr. ++ No other tests are made [yet] for non-stationary behavior in the time series data. ========================================================================= * This binary version of 3dBandpass is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. * At present, the only part of 3dBandpass that is parallelized is the '-blur' option, which processes each sub-brick independently. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dBlurInMask
Usage: ~1~ 3dBlurInMask [options] Blurs a dataset spatially inside a mask. That's all. Experimental. OPTIONS ~1~ ------- -input ddd = This required 'option' specifies the dataset that will be smoothed and output. -FWHM f = Add 'f' amount of smoothness to the dataset (in mm). **N.B.: This is also a required 'option'. -FWHMdset d = Read in dataset 'd' and add the amount of smoothness given at each voxel -- spatially variable blurring. ** EXPERIMENTAL EXPERIMENTAL EXPERIMENTAL ** -mask mmm = Mask dataset, if desired. Blurring will occur only within the mask. Voxels NOT in the mask will be set to zero in the output. -Mmask mmm = Multi-mask dataset -- each distinct nonzero value in dataset 'mmm' will be treated as a separate mask for blurring purposes. **N.B.: 'mmm' must be byte- or short-valued! -automask = Create an automask from the input dataset. **N.B.: only 1 masking option can be used! -preserve = 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. -prefix ppp = Prefix for output dataset will be 'ppp'. **N.B.: Output dataset is always in float format. -quiet = Don't be verbose with the progress reports. -float = Save dataset as floats, no matter what the input data type is. **N.B.: If the input dataset is unscaled shorts, then the default is to save the output in short format as well. In EVERY other case, the program saves the output as floats. Thus, the ONLY purpose of the '-float' option is to force an all-shorts input dataset to be saved as all-floats after blurring. ** NEW IN 2021 ** -FWHMxyz fx fy fz = Add different amounts of smoothness in the 3 spatial directions. ** If one of the 'f' values is 0, no smoothing is done in that direction. ** Here, the axes names ('x', 'y', 'z') refer to the order of storage in the dataset, as can be seen in the output of 3dinfo; for example, from a dataset that I happen to have lying around: Data Axes Orientation: first (x) = Anterior-to-Posterior second (y) = Superior-to-Inferior third (z) = Left-to-Right In this example, 'fx' is the FWHM blurring along the A-P direction, et cetera. ** In other words, x-y-z does not necessarily refer to the DICOM order of coordinates (R-L, A-P, I-S)! NOTES ~1~ ----- * If you don't provide a mask, then all voxels will be included in the blurring. (But then why are you using this program?) * Note that voxels inside the mask that are not contiguous with any other voxels inside the mask will not be modified at all! * Works iteratively, similarly to 3dBlurToFWHM, but without the extensive overhead of monitoring the smoothness. * But this program will be faster than 3dBlurToFWHM, and probably slower than 3dmerge. * Since the blurring is done iteratively, rather than all-at-once as in 3dmerge, the results will be slightly different than 3dmerge's, even if no mask is used here (3dmerge, of course, doesn't take a mask). * If the original FWHM of the dataset was 'S' and you input a value 'F' with the '-FWHM' option, then the output dataset's smoothness will be about sqrt(S*S+F*F). The number of iterations will be about (F*F/d*d) where d=grid spacing; this means that a large value of F might take a lot of CPU time! * The spatial smoothness of a 3D+time dataset can be estimated with a command similar to the following: 3dFWHMx -detrend -mask mmm+orig -input ddd+orig * The minimum number of voxels in the mask is 9 * Isolated voxels will be removed from the mask! ========================================================================= * This binary version of 3dBlurInMask is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dBlurToFWHM
Usage: 3dBlurToFWHM [options] Blurs a 'master' dataset until it reaches a specified FWHM smoothness (approximately). The same blurring schedule is applied to the input dataset to produce the output. The goal is to make the output dataset have the given smoothness, no matter what smoothness it had on input (however, the program cannot 'unsmooth' a dataset!). See below for the METHOD used. OPTIONS ------- -input ddd = This required 'option' specifies the dataset that will be smoothed and output. -blurmaster bbb = This option specifies the dataset whose whose smoothness controls the process. **N.B.: If not given, the input dataset is used. **N.B.: This should be one continuous run. Do not input catenated runs! -prefix ppp = Prefix for output dataset will be 'ppp'. **N.B.: Output dataset is always in float format. -mask mmm = Mask dataset, if desired. Blurring will occur only within the mask. Voxels NOT in the mask will be set to zero in the output. -automask = Create an automask from the input dataset. **N.B.: Not useful if the input dataset has been detrended or otherwise regressed before input! -FWHM f = Blur until the 3D FWHM is 'f'. -FWHMxy f = Blur until the 2D (x,y)-plane FWHM is 'f'. No blurring is done along the z-axis. **N.B.: Note that you can't REDUCE the smoothness of a dataset. **N.B.: Here, 'x', 'y', and 'z' refer to the grid/slice order as stored in the dataset, not DICOM ordered coordinates! **N.B.: With -FWHMxy, smoothing is done only in the dataset xy-plane. With -FWHM, smoothing is done in 3D. **N.B.: The actual goal is reached when -FWHM : cbrt(FWHMx*FWHMy*FWHMz) >= f -FWHMxy: sqrt(FWHMx*FWHMy) >= f That is, when the area or volume of a 'resolution element' goes past a threshold. -quiet Shut up the verbose progress reports. **N.B.: This should be the first option, to stifle any verbosity from the option processing code. FILE RECOMMENDATIONS for -blurmaster: For FMRI statistical purposes, you DO NOT want the FWHM to reflect the spatial structure of the underlying anatomy. Rather, you want the FWHM to reflect the spatial structure of the noise. This means that the -blurmaster dataset should not have anatomical structure. One good form of input is the output of '3dDeconvolve -errts', which is the residuals left over after the GLM fitted signal model is subtracted out from each voxel's time series. You can also use the output of '3dREMLfit -Rerrts' or '3dREMLfit -Rwherr' for this purpose. You CAN give a multi-brick EPI dataset as the -blurmaster dataset; the dataset will be detrended in time (like the -detrend option in 3dFWHMx) which will tend to remove the spatial structure. This makes it practicable to make the input and blurmaster datasets be the same, without having to create a detrended or residual dataset beforehand. Considering the accuracy of blurring estimates, this is probably good enough for government work [that is an insider's joke :-]. N.B.: Do not use catenated runs as blurmasters. There should be no discontinuities in the time axis of blurmaster, which would make the simple regression detrending do peculiar things. ALSO SEE: * 3dFWHMx, which estimates smoothness globally * 3dLocalstat -stat FWHM, which estimates smoothness locally * This paper, which discusses the need for a fixed level of smoothness when combining FMRI datasets from different scanner platforms: Friedman L, Glover GH, Krenz D, Magnotta V; The FIRST BIRN. Reducing inter-scanner variability of activation in a multicenter fMRI study: role of smoothness equalization. Neuroimage. 2006 Oct 1;32(4):1656-68. METHOD: The blurring is done by a conservative finite difference approximation to the diffusion equation: du/dt = d/dx[ D_x(x,y,z) du/dx ] + d/dy[ D_y(x,y,z) du/dy ] + d/dz[ D_z(x,y,z) du/dz ] = div[ D(x,y,z) grad[u(x,y,z)] ] where diffusion tensor D() is diagonal, Euler time-stepping is used, and with Neumann (reflecting) boundary conditions at the edges of the mask (which ensures that voxel data inside and outside the mask don't mix). * At each pseudo-time step, the FWHM is estimated globally (like '3dFWHMx') and locally (like '3dLocalstat -stat FWHM'). Voxels where the local FWHM goes past the goal will not be smoothed any more (D gets set to zero). * When the global smoothness estimate gets close to the goal, the blurring rate (pseudo-time step) will be reduced, to avoid over-smoothing. * When an individual direction's smoothness (e.g., FWHMz) goes past the goal, all smoothing in that direction stops, but the other directions continue to be smoothed until the overall resolution element goal is achieved. * When the global FWHM estimate reaches the goal, the program is done. It will also stop if progress stalls for some reason, or if the maximum iteration count is reached (infinite loops being unpopular). * The output dataset will NOT have exactly the smoothness you ask for, but it will be close (fondly we do hope). In our Imperial experiments, the results (measured via 3dFWHMx) are within 10% of the goal (usually better). * 2D blurring via -FWHMxy may increase the smoothness in the z-direction reported by 3dFWHMx, even though there is no inter-slice processing. At this moment, I'm not sure why. It may be an estimation artifact due to increased correlation in the xy-plane that biases the variance estimates used to calculate FWHMz. ADVANCED OPTIONS: -maxite ccc = Set maximum number of iterations to 'ccc' [Default=variable]. -rate rrr = The value of 'rrr' should be a number between 0.05 and 3.5, inclusive. It is a factor to change the overall blurring rate (slower for rrr < 1) and thus require more or less blurring steps. This option should only be needed to slow down the program if the it over-smooths significantly (e.g., it overshoots the desired FWHM in Iteration #1 or #2). You can increase the speed by using rrr > 1, but be careful and examine the output. -nbhd nnn = As in 3dLocalstat, specifies the neighborhood used to compute local smoothness. [Default = 'SPHERE(-4)' in 3D, 'SPHERE(-6)' in 2D] ** N.B.: For the 2D -FWHMxy, a 'SPHERE()' nbhd is really a circle in the xy-plane. ** N.B.: If you do NOT want to estimate local smoothness, use '-nbhd NULL'. -ACF or -acf = Use the 'ACF' method (from 3dFWHMx) to estimate the global smoothness, rather than the 'classic' Forman 1995 method. This option will be somewhat slower. It will also set '-nbhd NULL', since there is no local ACF estimation method implemented. -bsave bbb = Save the local smoothness estimates at each iteration with dataset prefix 'bbb' [for debugging purposes]. -bmall = Use all blurmaster sub-bricks. [Default: a subset will be chosen, for speed] -unif = Uniformize the voxel-wise MAD in the blurmaster AND input datasets prior to blurring. Will be restored in the output dataset. -detrend = Detrend blurmaster dataset to order NT/30 before starting. -nodetrend = Turn off detrending of blurmaster. ** N.B.: '-detrend' is the new default [05 Jun 2007]! -detin = Also detrend input before blurring it, then retrend it afterwards. [Off by default] -temper = Try harder to make the smoothness spatially uniform. -- Author: The Dreaded Emperor Zhark - Nov 2006 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dBrainSync
Usage: 3dBrainSync [options] This program 'synchronizes' the -inset2 dataset to match the -inset1 dataset, as much as possible (average voxel-wise correlation), using the same transformation on each input time series from -inset2: ++ With the -Qprefix option, the transformation is an orthogonal matrix, computed as described in Joshi's original OHBM 2017 presentations, and in the corresponding NeuroImage 2018 paper. -->> Anand Joshi's presentation at OHBM was the genesis of this program. ++ With the -Pprefix option, the transformation is simply a permutation of the time order of -inset2 (a very special case of an orthogonal matrix). ++ The algorithms and a little discussion of the different features of these two techniques are discussed in the METHODS section, infra. ++ At least one of '-Qprefix' or '-Pprefix' must be given, or this program does not do anything! You can use both methods, if you want to compare them. ++ 'Harmonize' might be a better name for what this program does, but calling it 3dBrainHarm would probably not be good marketing (except for Traumatic Brain Injury researchers?). One possible application of this program is to correlate resting state FMRI datasets between subjects, voxel-by-voxel, as is sometimes done with naturalistic stimuli (e.g., movie viewing). It would be amusing to see if within-subject resting state FMRI runs can be BrainSync-ed better than between-subject runs. -------- OPTIONS: -------- -inset1 dataset1 = Reference dataset -inset2 dataset2 = Dataset to be matched to the reference dataset, as much as possible. ++ These 2 datasets must be on the same spatial grid, and must have the same number of time points! ++ There must be at least twice as many voxels being processed as there are time points (see '-mask', below). ++ These are both MANDATORY 'options'. ++ As usual in AFNI, since the computations herein are voxel-wise, it is possible to input plain text .1D files as datasets. When doing so, remember that a ROW in the .1D file is interpreted as a time series (single voxel's data). If your .1D files are oriented so that time runs in down the COLUMNS, you will have to transpose the inputs, which can be done on the command line with the \' operator, or externally using the 1dtranspose program. -->>++ These input datasets should be pre-processed first to remove undesirable components (motions, baseline, spikes, breathing, etc). Otherwise, you will be trying to match artifacts between the datasets, which is not likely to be interesting or useful. 3dTproject would be one way to do this. Even better: afni_proc.py! ++ In particular, the mean of each time series should have been removed! Otherwise, the calculations are fairly meaningless. -Qprefix qqq = Specifies the output dataset to be used for the orthogonal matrix transformation. ++ This will be the -inset2 dataset transformed to be as correlated as possible (in time) with the -inset1 dataset, given the constraint that the transformation applied to each time series is an orthogonal matrix. -Pprefix ppp = Specifies the output dataset to be used for the permutation transformation. ++ The output dataset is the -inset2 dataset re-ordered in time, again to make the result as correlated as possible with the -inset1 dataset. -normalize = Normalize the output dataset(s) so that each time series has sum-of-squares = 1. ++ This option is not usually needed in AFNI (e.g., 3dTcorrelate does not care). -mask mset = Only operate on nonzero voxels in the mset dataset. ++ Voxels outside the mask will not be used in computing the transformation, but WILL be transformed for your application and/or edification later. ++ For FMRI purposes, a gray matter mask would make sense here, or at least a brain mask. ++ If no masking option is given, then all voxels will be processed in computing the transformation. This set will include all non-brain voxels (if any). ++ Any voxel which is all constant in time (in either input) will be removed from the mask. ++ This mask dataset must be on the same spatial grid as the other input datasets! -verb = Print some progress reports and auxiliary information. ++ Use this option twice to get LOTS of progress reports; mostly useful for debugging, or for fun. ------ NOTES: ------ * Is this program useful? Not even The Shadow knows! (But do NOT call it BS.) * The output dataset is in floating point format. * Although the goal of 3dBrainSync is to make the transformed -inset2 as correlated (voxel-by-voxel) as possible with -inset1, it does not actually compute or output that correlation dataset. You can do that computation with program 3dTcorrelate, as in 3dBrainSync -inset1 dataset1 -inset2 dataset2 \ -Qprefix transformed-dataset2 3dTcorrelate -polort -1 -prefix AB.pcor.nii \ dataset1 transformed-dataset2 * Besides the transformed dataset(s), if the '-verb' option is used, some other (text formatted) files are written out: {Qprefix}.sval.1D = singular values from the BC' decomposition {Qprefix}.qmat.1D = Q matrix {Pprefix}.perm.1D = permutation indexes p(i) You probably do not have any use for these files; they are mostly present to diagnose any problems. -------- METHODS: -------- * Notation used in the explanations below: M = Number of time points N = Number of voxels > M (N = size of mask) B = MxN matrix of time series from -inset1 C = MxN matrix of time series from -inset2 Both matrices will have each column normalized to have sum-of-squares = 1 (L2 normalized) -- The program does this operation internally; you do not have to ensure that the input datasets are so normalized. Q = Desired orthgonal MxM matrix to transform C such that B-QC is as small as possible (sum-of-squares = Frobenius norm). That is, Q transforms dataset C to be as close as possible to dataset B, given that Q is an orthogonal matrix. normF(A) = sum_{ij} A_{ij}^2 = trace(AA') = trace(A'A). NOTE: This norm is different from the matrix L2 norm. NOTE: A' denotes the transpose of A. NOTE: trace(A) = sum of diagonal element of square matrix A. https://en.wikipedia.org/wiki/Matrix_norm * The expansion below shows why the matrix BC' is crucial to the analysis: normF(B-QC) = trace( [B-QC][B'-C'Q'] ) = trace(BB') + trace(QCC'Q') - trace(BC'Q') - trace(QCB') = trace(BB') + trace(C'C) - 2 trace(BC'Q') The second term collapses because trace(AA') = trace(A'A), so trace([QC][QC]') = trace([QC]'[QC]) = trace(C'Q'QC) = trace(C'C) because Q is orthogonal. So the first 2 terms in the expansion of normF(B-QC) do not depend on Q at all. Thus, to minimize normF(B-QC), we have to maximize trace(BC'Q') = trace([B][QC]') = trace([QC][B]'). Since the columns of B and C are the (normalized) time series, each row represents the image at a particular time. So the (i,j) element of BC' is the (spatial) dot product of the i-th TR image from -inset1 with the j-th TR image from -inset2. Furthermore, trace(BC') = trace(C'B) = sum of dot products (correlations) of all time series. So maximizing trace(BC'Q') will maximize the summed correlations of B (time series from -inset1) and QC (transformed time series from -inset2). Note again that the sum of correlations (dot products) of all the time series is equal to the sum of dot products of all the spatial images. So the algorithm to find the transformation Q is to maximize the sum of dot products of spatial images from B with Q-transformed spatial images from C -- since there are fewer time points than voxels, this is more efficient and elegant than trying to maximize the sum over voxels of dot products of time series. If you use the '-verb' option, these summed correlations ('scores') are printed to stderr during the analysis, for your fun and profit(?). ******************************************************************************* * Joshi method [-Qprefix]: (a) compute MxM matrix B C' (b) compute SVD of B C' = U S V' (U, S, V are MxM matrices) (c) Q = U V' [note: if B=C, then U=V, so Q=I, as it should] (d) transform each time series from -inset2 using Q This matrix Q is the solution to the restricted least squares problem (i.e., restricted to have Q be an orthogonal matrix). NOTE: The sum of the singular values in S is equal to the sum of the time series dot products (correlations) in B and QC, when Q is calculated as above. An article describing this method is available as: AA Joshi, M Chong, RM Leahy. Are you thinking what I'm thinking? Synchronization of resting fMRI time-series across subjects. NeuroImage v172:740-752 (2018). https://doi.org/10.1016/j.neuroimage.2018.01.058 https://pubmed.ncbi.nlm.nih.gov/29428580/ https://www.google.com/search?q=joshi+brainsync ******************************************************************************* * Permutation method [-Pprefix]: (a) Compute B C' (same as above) (b) Find a permutation p(i) of the integers {0..M-1} such that sum_i { (BC')[i,p(i)] } is as large as possible (i.e., p() is used as a permutation of the COLUMNS of BC'). This permutation is equivalent to post-multiplying BC' by an orthogonal matrix P representing the permutation; such a P is full of 0s except for a single 1 in each row and each column. (c) Permute the ROWS (time direction) of the time series matrix from -inset2 using p(). Only an approximate (greedy) algorithm is used to find this permutation; that is, the BEST permutation is not guaranteed to be found (just a 'good' permutation -- it is the best thing I could code quickly :). Algorithm currently implemented (let D=BC' for notational simplicity): 1) Find the largest element D(i,j) in the matrix. Then the permutation at row i is p(i)=j. Strike row i and column j out of the matrix D. 2) Repeat, finding the largest element left, say at D(f,g). Then p(f) = g. Strike row f and column g from the matrix. Repeat until done. (Choosing the largest possible element at each step is what makes this method 'greedy'.) This permutation is not optimal but is pretty good, and another step is used to improve it: 3) For all pairs (i,j), p(i) and p(j) are swapped and that permutation is tested to see if the trace gets bigger. 4) This pair-wise swapping is repeated until it does not improve things any more (typically, it improves the trace about 1-2% -- not much). The purpose of the pair swapping is to deal with situations where D looks something like this: [ 1 70 ] [ 70 99 ] Step 1 would pick out 99, and Step 2 would pick out 1; that is, p(2)=2 and then p(1)=1, for a total trace/score of 100. But swapping 1 and 2 would give a total trace/score of 140. In practice, extreme versions of this situation do not seem common with real FMRI data, probably because the subject's brain isn't actively conspiring against this algorithm :) [Something called the 'Hungarian algorithm' can solve for the optimal] [permutation exactly, but I've not had the inclination to program it.] This whole permutation optimization procedure is very fast: about 1 second. In the RS-FMRI data I've tried this on, the average time series correlation resulting from this optimization is 30-60% of that which comes from optimizing over ALL orthogonal matrices (Joshi method). If you use '-verb', the stderr output line that looks like this + corr scores: original=-722.5 Q matrix=22366.0 permutation=12918.7 57.8% shows trace(BC') before any transforms, with the Q matrix transform, and with the permutation transform. As explained above, trace(BC') is the summed correlations of the time series (since the columns of B and C are normalized prior to the optimizations); in this example, the ratio of the average time series correlation between the permutation method and the Joshi method is about 58% (in a gray matter mask with 72221 voxels). * Results from the permutation method MUST be less correlated (on average) with -inset1 than the Joshi method's results: the permutation can be thought of as an orthogonal matrix containing only 1s and 0s, and the BEST possible orthogonal matrix, from Joshi's method, has more general entries. ++ However, the permutation method has an obvious interpretation (re-ordering time points), while the general method linearly combines different time points (perhaps far apart); the interpretation of this combination in terms of synchronizing brain activity is harder to intuit (at least for me). ++ Another feature of a permutation-only transformation is that it cannot change the sign of data, unlike a general orthgonal matrix; e.g., [ 0 -1 0 ] [-1 0 0 ] [ 0 0 1 ], which swaps the first 2 time points AND negates them, and leave the 3rd time point unchanged, is a valid orthogonal matrix. For rs-FMRI datasets, this consideration might not be important, since rs-FMRI correlations are generally positive, so don't often need sign-flipping to make them so. ******************************************************************************* * This program is NOT multi-threaded. Typically, I/O is the biggest part of the run time (at least, for the cases I've tested). The '-verb' option will give progress reports with elapsed-time stamps, making it easy to see which parts of the program take the most time. * Author: RWCox, servant of the ChronoSynclastic Infundibulum - July 2017 * Thanks go to Anand Joshi for his clear exposition of BrainSync at OHBM 2017, and his encouragement about the development of this program. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dBRAIN_VOYAGERtoAFNI
Usage: 3dBRAIN_VOYAGERtoAFNI <-input BV_VOLUME.vmr> [-bs] [-qx] [-tlrc|-acpc|-orig] [<-prefix PREFIX>] Converts a BrainVoyager vmr dataset to AFNI's BRIK format The conversion is based on information from BrainVoyager's website: www.brainvoyager.com. Sample data and information provided by Adam Greenberg and Nikolaus Kriegeskorte. If you get error messages about the number of voxels and file size, try the options below. I hope to automate these options once I have a better description of the BrainVoyager QX format. Optional Parameters: -bs: Force byte swapping. -qx: .vmr file is from BrainVoyager QX -tlrc: dset in tlrc space -acpc: dset in acpc-aligned space -orig: dset in orig space If unspecified, the program attempts to guess the view from the name of the input. [-novolreg]: Ignore any Rotate, Volreg, Tagalign, or WarpDrive transformations present in the Surface Volume. [-noxform]: Same as -novolreg [-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname to be ENVvalue. Quotes are necessary. Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'" See also options -update_env, -environment, etc in the output of 'suma -help' Common Debugging Options: [-trace]: Turns on In/Out debug and Memory tracing. For speeding up the tracing log, I recommend you redirect stdout to a file when using this option. For example, if you were running suma you would use: suma -spec lh.spec -sv ... > TraceFile This option replaces the old -iodbg and -memdbg. [-TRACE]: Turns on extreme tracing. [-nomall]: Turn off memory tracing. [-yesmall]: Turn on memory tracing (default). NOTE: For programs that output results to stdout (that is to your shell/screen), the debugging info might get mixed up with your results. Global Options (available to all AFNI/SUMA programs) -h: Mini help, at time, same as -help in many cases. -help: The entire help output -HELP: Extreme help, same as -help in majority of cases. -h_view: Open help in text editor. AFNI will try to find a GUI editor -hview : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_web: Open help in web browser. AFNI will try to find a browser. -hweb : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_find WORD: Look for lines in this programs's -help output that match (approximately) WORD. -h_raw: Help string unedited -h_spx: Help string in sphinx loveliness, but do not try to autoformat -h_aspx: Help string in sphinx with autoformatting of options, etc. -all_opts: Try to identify all options for the program from the output of its -help option. Some options might be missed and others misidentified. Use this output for hints only. Compile Date: May 6 2025 Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov

AFNI program: 3dBrickStat
Usage: 3dBrickStat [options] dataset Compute maximum and/or minimum voxel values of an input dataset The output is a number to the console. The input dataset may use a sub-brick selection list, as in program 3dcalc. Note that this program computes ONE number as the output; e.g., the mean over all voxels and time points. If you want (say) the mean over all voxels but for each time point individually, see program 3dmaskave. Note: If you don't specify one sub-brick, the parameter you get ----- back is computed from all the sub-bricks in dataset. Options : -quick = get the information from the header only (default) -slow = read the whole dataset to find the min and max values all other options except min and max imply slow -min = print the minimum value in dataset -max = print the maximum value in dataset (default) -mean = print the mean value in dataset -sum = print the sum of values in the dataset -var = print the variance in the dataset -stdev = print the standard deviation in the dataset -stdev and -var are mutually exclusive -count = print the number of voxels included -volume = print the volume of voxels included in microliters -positive = include only positive voxel values -negative = include only negative voxel values -zero = include only zero voxel values -non-positive = include only voxel values 0 or negative -non-negative = include only voxel values 0 or greater -non-zero = include only voxel values not equal to 0 -absolute = use absolute value of voxel values for all calculations can be combined with restrictive non-positive, non-negative, etc. even if not practical. Ignored for percentile and median computations. -nan = include only voxel values that are not numbers (e.g., NaN or inf). This is basically meant for counting bad numbers in a dataset. -nan forces -slow mode. -nonan = exclude voxel values that are not numbers (exclude any NaN or inf values from computations). -mask dset = use dset as mask to include/exclude voxels -mrange MIN MAX = Only accept values between MIN and MAX (inclusive) from the mask. Default it to accept all non-zero voxels. -mvalue VAL = Only accept values equal to VAL from the mask. -automask = automatically compute mask for dataset Can not be combined with -mask -percentile p0 ps p1 write the percentile values starting at p0% and ending at p1% at a step of ps% Output is of the form p% value p% value ... Percentile values are output first. Only one sub-brick is accepted as input with this option. Write the author if you REALLY need this option to work with multiple sub-bricks. -perclist NUM_PERC PERC1 PERC2 ... Like -percentile, but output the given percentiles, rather than a list on an evenly spaced grid using 'ps'. -median a shortcut for -percentile 50 1 50 (or -perclist 1 50) -perc_quiet = only print percentile results, not input percentile cutoffs -ver = print author and version info -help = print this help screen INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dbucket
++ 3dbucket: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] Concatenate sub-bricks from input datasets into one big 'bucket' dataset. ~1~ Usage: 3dbucket options where the options are: ~1~ -prefix pname = Use 'pname' for the output dataset prefix name. OR -output pname [default='buck'] -session dir = Use 'dir' for the output dataset session directory. [default='./'=current working directory] -glueto fname = Append bricks to the end of the 'fname' dataset. This command is an alternative to the -prefix and -session commands. * Note that fname should include the view, as in 3dbucket -glueto newset+orig oldset+orig'[7]' -aglueto fname= If fname dset does not exist, create it (like -prefix). Otherwise append to fname (like -glueto). This option is useful when appending in a loop. * As with -glueto, fname should include the view, e.g. 3dbucket -aglueto newset+orig oldset+orig'[7]' -dry = Execute a 'dry run'; that is, only print out what would be done. This is useful when combining sub-bricks from multiple inputs. -verb = Print out some verbose output as the program proceeds (-dry implies -verb). -fbuc = Create a functional bucket. -abuc = Create an anatomical bucket. If neither of these options is given, the output type is determined from the first input type. Command line arguments after the above are taken as input datasets. A dataset is specified using one of these forms: 'prefix+view', 'prefix+view.HEAD', or 'prefix+view.BRIK'. You can also add a sub-brick selection list after the end of the dataset name. This allows only a subset of the sub-bricks to be included into the output (by default, all of the input dataset is copied into the output). A sub-brick selection list looks like one of the following forms: fred+orig[5] ==> use only sub-brick #5 fred+orig[5,9,17] ==> use #5, #9, and #17 fred+orig[5..8] or [5-8] ==> use #5, #6, #7, and #8 fred+orig[5..13(2)] or [5-13(2)] ==> use #5, #7, #9, #11, and #13 Sub-brick indexes start at 0. You can use the character '$' to indicate the last sub-brick in a dataset; for example, you can select every third sub-brick by using the selection list fred+orig[0..$(3)] Notes: ~1~ N.B.: The sub-bricks are output in the order specified, which may not be the order in the original datasets. For example, using fred+orig[0..$(2),1..$(2)] will cause the sub-bricks in fred+orig to be output into the new dataset in an interleaved fashion. Using fred+orig[$..0] will reverse the order of the sub-bricks in the output. N.B.: Bucket datasets have multiple sub-bricks, but do NOT have a time dimension. You can input sub-bricks from a 3D+time dataset into a bucket dataset. You can use the '3dinfo' program to see how many sub-bricks a 3D+time or a bucket dataset contains. N.B.: The '$', '(', ')', '[', and ']' characters are special to the shell, so you will have to escape them. This is most easily done by putting the entire dataset plus selection list inside single quotes, as in 'fred+orig[5..7,9]'. N.B.: In non-bucket functional datasets (like the 'fico' datasets output by FIM, or the 'fitt' datasets output by 3dttest), sub-brick [0] is the 'intensity' and sub-brick [1] is the statistical parameter used as a threshold. Thus, to create a bucket dataset using the intensity from dataset A and the threshold from dataset B, and calling the output dataset C, you would type 3dbucket -prefix C -fbuc 'A+orig[0]' -fbuc 'B+orig[1]' WARNING: ~1~ Using this program, it is possible to create a dataset that has different basic datum types for different sub-bricks (e.g., shorts for brick 0, floats for brick 1). Do NOT do this! Very few AFNI programs will work correctly with such datasets! ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dcalc
++ 3dcalc: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: A cast of thousands Program: 3dcalc Author: RW Cox et al 3dcalc - AFNI's calculator program ~1~ This program does voxel-by-voxel arithmetic on 3D datasets (only limited inter-voxel computations are possible). The program assumes that the voxel-by-voxel computations are being performed on datasets that occupy the same space and have the same orientations. 3dcalc has a lot of input options, as its capabilities have grown over the years. So this 'help' output has gotten kind of long. For simple voxel-wise averaging of datasets: cf. 3dMean For averaging along the time axis: cf. 3dTstat For smoothing in time: cf. 3dTsmooth For statistics from a region around each voxel: cf. 3dLocalstat ------------------------------------------------------------------------ Usage: ~1~ ----- 3dcalc -a dsetA [-b dsetB...] \ -expr EXPRESSION \ [options] Examples: ~1~ -------- 1. Average datasets together, on a voxel-by-voxel basis: 3dcalc -a fred+tlrc -b ethel+tlrc -c lucy+tlrc \ -expr '(a+b+c)/3' -prefix subjects_mean Averaging datasets can also be done by programs 3dMean and 3dmerge. Use 3dTstat to averaging across sub-bricks in a single dataset. 2. Perform arithmetic calculations between the sub-bricks of a single dataset by noting the sub-brick number on the command line: 3dcalc -a 'func+orig[2]' -b 'func+orig[4]' -expr 'sqrt(a*b)' 3. Create a simple mask that consists only of values in sub-brick #0 that are greater than 3.14159: 3dcalc -a 'func+orig[0]' -expr 'ispositive(a-3.14159)' \ -prefix mask 4. Normalize subjects' time series datasets to percent change values in preparation for group analysis: Voxel-by-voxel, the example below divides each intensity value in the time series (epi_r1+orig) with the voxel's mean value (mean+orig) to get a percent change value. The 'ispositive' command will ignore voxels with mean values less than 167 (i.e., they are labeled as 'zero' in the output file 'percent_change+orig') and are most likely background/noncortical voxels. 3dcalc -a epi_run1+orig -b mean+orig \ -expr '100 * a/b * ispositive(b-167)' -prefix percent_chng 5. Create a compound mask from a statistical dataset, where 3 stimuli show activation. NOTE: 'step' and 'ispositive' are identical expressions that can be used interchangeably: 3dcalc -a 'func+orig[12]' -b 'func+orig[15]' -c 'func+orig[18]' \ -expr 'step(a-4.2)*step(b-2.9)*step(c-3.1)' \ -prefix compound_mask In this example, all 3 statistical criteria must be met at once for a voxel to be selected (value of 1) in this mask. 6. Same as example #5, but this time create a mask of 8 different values showing all combinations of activations (i.e., not only where everything is active, but also each stimulus individually, and all combinations). The output mask dataset labels voxel values as such: 0 = none active 1 = A only active 2 = B only active 3 = A and B only 4 = C only active 5 = A and C only 6 = B and C only 7 = all A, B, and C active 3dcalc -a 'func+orig[12]' -b 'func+orig[15]' -c 'func+orig[18]' \ -expr 'step(a-4.2)+2*step(b-2.9)+4*step(c-3.1)' \ -prefix mask_8 In displaying such a binary-encoded mask in AFNI, you would probably set the color display to have 8 discrete levels (the '#' menu). 7. Create a region-of-interest mask comprised of a 3-dimensional sphere. Values within the ROI sphere will be labeled as '1' while values outside the mask will be labeled as '0'. Statistical analyses can then be done on the voxels within the ROI sphere. The example below puts a solid ball (sphere) of radius 3=sqrt(9) about the point with coordinates (x,y,z)=(20,30,70): 3dcalc -a anat+tlrc \ -expr 'step(9-(x-20)*(x-20)-(y-30)*(y-30)-(z-70)*(z-70))' \ -prefix ball The spatial meaning of (x,y,z) is discussed in the 'COORDINATES' section of this help listing (far below). 8. Some datasets are 'short' (16 bit) integers with a scalar attached, which allow them to be smaller than float datasets and to contain fractional values. Dataset 'a' is always used as a template for the output dataset. For the examples below, assume that datasets d1+orig and d2+orig consist of small integers. a) When dividing 'a' by 'b', the result should be scaled, so that a value of 2.4 is not truncated to '2'. To avoid this truncation, force scaling with the -fscale option: 3dcalc -a d1+orig -b d2+orig -expr 'a/b' -prefix quot -fscale b) If it is preferable that the result is of type 'float', then set the output data type (datum) to float: 3dcalc -a d1+orig -b d2+orig -expr 'a/b' -prefix quot \ -datum float c) Perhaps an integral division is desired, so that 9/4=2, not 2.24. Force the results not to be scaled (opposite of example 8a) using the -nscale option: 3dcalc -a d1+orig -b d2+orig -expr 'a/b' -prefix quot -nscale 9. Compare the left and right amygdala between the Talairach atlas, and the CA_N27_ML atlas. The result will be 1 if TT only, 2 if CA only, and 3 where they overlap. 3dcalc -a 'TT_Daemon::amygdala' -b 'CA_N27_ML::amygdala' \ -expr 'step(a)+2*step(b)' -prefix compare.maps (see 'whereami_afni -help' for more information on atlases) 10. Convert a dataset from AFNI short format storage to NIfTI-1 floating point (perhaps for input to an non-AFNI program that requires this): 3dcalc -a zork+orig -prefix zfloat.nii -datum float -expr 'a' This operation could also be performed with program 3dAFNItoNIFTI. 11. Compute the edge voxels of a mask dataset. An edge voxel is one that shares some face with a non-masked voxel. This computation assumes 'a' is a binary mask (particularly for 'amongst'). 3dcalc -a mask+orig -prefix edge \ -b a+i -c a-i -d a+j -e a-j -f a+k -g a-k \ -expr 'a*amongst(0,b,c,d,e,f,g)' consider similar erode or dilate operations: erosion: -expr 'a*(1-amongst(0,b,c,d,e,f,g))' dilation: -expr 'amongst(1,a,b,c,d,e,f,g)' ------------------------------------------------------------------------ ARGUMENTS for 3dcalc (must be included on command line): ~1~ --------- -a dname = Read dataset 'dname' and call the voxel values 'a' in the expression (-expr) that is input below. Up to 26 dnames (-a, -b, -c, ... -z) can be included in a single 3dcalc calculation/expression. ** If some letter name is used in the expression, but not present in one of the dataset options here, then that variable is set to 0. ** You can use the subscript '[]' method to select sub-bricks of datasets, as in -b dname+orig'[3]' ** If you just want to test some 3dcalc expression, you can supply a dataset 'name' of the form jRandomDataset:64,64,16,40 to have the program create and use a dataset with a 3D 64x64x16 grid, with 40 time points, filled with random numbers (uniform on [-1,1]). -expr = Apply the expression - within quotes - to the input datasets (dnames), one voxel at time, to produce the output dataset. ** You must use 1 and only 1 '-expr' option! NOTE: If you want to average or sum up a lot of datasets, programs 3dTstat and/or 3dMean and/or 3dmerge are better suited for these purposes. A common request is to increase the number of input datasets beyond 26, but in almost all cases such users simply want to do simple addition! NOTE: If you want to include shell variables in the expression (or in the dataset sub-brick selection), then you should use double "quotes" and the '$' notation for the shell variables; this example uses csh notation to set the shell variable 'z': set z = 3.5 3dcalc -a moose.nii -prefix goose.nii -expr "a*$z" The shell will not expand variables inside single 'quotes', and 3dcalc's parser will not understand the '$' character. NOTE: You can use the ccalc program to play with the expression evaluator, in order to get a feel for how it works and what it accepts. ------------------------------------------------------------------------ OPTIONS for 3dcalc: ~1~ ------- -help = Show this help. -verbose = Makes the program print out various information as it progresses. -datum type= Coerce the output data to be stored as the given type, which may be byte, short, or float. [default = datum of first input dataset] -float } -short } = Alternative options to specify output data format. -byte } -fscale = Force scaling of the output to the maximum integer range. This only has effect if the output datum is byte or short (either forced or defaulted). This option is often necessary to eliminate unpleasant truncation artifacts. [The default is to scale only if the computed values seem to need it -- are all <= 1.0 or there is at least one value beyond the integer upper limit.] ** In earlier versions of 3dcalc, scaling (if used) was applied to all sub-bricks equally -- a common scale factor was used. This would cause trouble if the values in different sub-bricks were in vastly different scales. In this version, each sub-brick gets its own scale factor. To override this behavior, use the '-gscale' option. -gscale = Same as '-fscale', but also forces each output sub-brick to get the same scaling factor. This may be desirable for 3D+time datasets, for example. ** N.B.: -usetemp and -gscale are incompatible!! -nscale = Don't do any scaling on output to byte or short datasets. This may be especially useful when operating on mask datasets whose output values are only 0's and 1's. ** Only use this option if you are sure you want the output dataset to be integer-valued! -prefix pname = Use 'pname' for the output dataset prefix name. [default='calc'] -session dir = Use 'dir' for the output dataset session directory. [default='./'=current working directory] You can also include the output directory in the 'pname' parameter to the -prefix option. -usetemp = With this option, a temporary file will be created to hold intermediate results. This will make the program run slower, but can be useful when creating huge datasets that won't all fit in memory at once. * The program prints out the name of the temporary file; if 3dcalc crashes, you might have to delete this file manually. ** N.B.: -usetemp and -gscale are incompatible!! -dt tstep = Use 'tstep' as the TR for "manufactured" 3D+time *OR* datasets. -TR tstep = If not given, defaults to 1 second. -taxis N = If only 3D datasets are input (no 3D+time or .1D files), *OR* then normally only a 3D dataset is calculated. With -taxis N:tstep: this option, you can force the creation of a time axis of length 'N', optionally using time step 'tstep'. In such a case, you will probably want to use the pre- defined time variables 't' and/or 'k' in your expression, or each resulting sub-brick will be identical. For example: '-taxis 121:0.1' will produce 121 points in time, spaced with TR 0.1. N.B.: You can also specify the TR using the -dt option. N.B.: You can specify 1D input datasets using the '1D:n@val,n@val' notation to get a similar effect. For example: -dt 0.1 -w '1D:121@0' will have pretty much the same effect as -taxis 121:0.1 N.B.: For both '-dt' and '-taxis', the 'tstep' value is in seconds. -rgbfac A B C = For RGB input datasets, the 3 channels (r,g,b) are collapsed to one for the purposes of 3dcalc, using the formula value = A*r + B*g + C*b The default values are A=0.299 B=0.587 C=0.114, which gives the grayscale intensity. To pick out the Green channel only, use '-rgbfac 0 1 0', for example. Note that each channel in an RGB dataset is a byte in the range 0..255. Thus, '-rgbfac 0.001173 0.002302 0.000447' will compute the intensity rescaled to the range 0..1.0 (i.e., 0.001173=0.299/255, etc.) -cx2r METHOD = For complex input datasets, the 2 channels must be converted to 1 real number for calculation. The methods available are: REAL IMAG ABS PHASE * The default method is ABS = sqrt(REAL^2+IMAG^2) * PHASE = atan2(IMAG,REAL) * Multiple '-cx2r' options can be given: when a complex dataset is given on the command line, the most recent previous method will govern. This also means that for -cx2r to affect a variable it must precede it. For example, to compute the phase of data in 'a' you should use 3dcalc -cx2r PHASE -a dft.lh.TS.niml.dset -expr 'a' However, the -cx2r option will have no effect in 3dcalc -a dft.lh.TS.niml.dset -cx2r PHASE -expr 'a' which will produce the default ABS of 'a' The -cx2r option in the latter example only applies to variables that will be defined after it. When in doubt, check your output. * If a complex dataset is used in a differential subscript, then the most recent previous -cx2r method applies to the extraction; for example -cx2r REAL -a cx+orig -cx2r IMAG -b 'a[0,0,0,0]' means that variable 'a' refers to the real part of the input dataset and variable 'b' to the imaginary part of the input dataset. * 3dcalc cannot be used to CREATE a complex dataset! [See program 3dTwotoComplex for that purpose.] -sort = Sort each output brick separately, before output: -SORT 'sort' ==> increasing order, 'SORT' ==> decreasing. [This is useful only under unusual circumstances!] [Sorting is done in spatial indexes, not in time.] [Program 3dTsort will sort voxels along time axis] -isola = After computation, remove isolated non-zero voxels. This option can be repeated to iterate the process; each copy of '-isola' will cause the isola removal process to be repeated one more time. ------------------------------------------------------------------------ DATASET TYPES: ~1~ ------------- The most common AFNI dataset types are 'byte', 'short', and 'float'. A byte value is an 8-bit signed integer (0..255), a short value ia a 16-bit signed integer (-32768..32767), and a float value is a 32-bit real number. A byte value has almost 3 decimals of accuracy, a short has almost 5, and a float has approximately 7 (from a 23+1 bit mantissa). Datasets can also have a scalar attached to each sub-brick. The main use of this is allowing a short type dataset to take on non-integral values, while being half the size of a float dataset. As an example, consider a short dataset with a scalar of 0.0001. This could represent values between -32.768 and +32.767, at a resolution of 0.001. One could represent the difference between 4.916 and 4.917, for instance, but not 4.9165. Each number has 15 bits of accuracy, plus a sign bit, which gives 4-5 decimal places of accuracy. If this is not enough, then it makes sense to use the larger type, float. ------------------------------------------------------------------------ 3D+TIME DATASETS: ~1~ ---------------- This version of 3dcalc can operate on 3D+time datasets. Each input dataset will be in one of these conditions: (A) Is a regular 3D (no time) dataset; or (B) Is a 3D+time dataset with a sub-brick index specified ('[3]'); or (C) Is a 3D+time dataset with no sub-brick index specified ('-b'). If there is at least one case (C) dataset, then the output dataset will also be 3D+time; otherwise it will be a 3D dataset with one sub-brick. When producing a 3D+time dataset, datasets in case (A) or (B) will be treated as if the particular brick being used has the same value at each point in time. Multi-brick 'bucket' datasets may also be used. Note that if multi-brick (bucket or 3D+time) datasets are used, the lowest letter dataset will serve as the template for the output; that is, '-b fred+tlrc' takes precedence over '-c wilma+tlrc'. (The program 3drefit can be used to alter the .HEAD parameters of the output dataset, if desired.) ------------------------------------------------------------------------ INPUT DATASET NAMES ------------------- An input dataset is specified using one of these forms: 'prefix+view', 'prefix+view.HEAD', or 'prefix+view.BRIK'. You can also add a sub-brick selection list after the end of the dataset name. This allows only a subset of the sub-bricks to be read in (by default, all of a dataset's sub-bricks are input). A sub-brick selection list looks like one of the following forms: fred+orig[5] ==> use only sub-brick #5 fred+orig[5,9,17] ==> use #5, #9, and #17 fred+orig[5..8] or [5-8] ==> use #5, #6, #7, and #8 fred+orig[5..13(2)] or [5-13(2)] ==> use #5, #7, #9, #11, and #13 Sub-brick indexes start at 0. You can use the character '$' to indicate the last sub-brick in a dataset; for example, you can select every third sub-brick by using the selection list fred+orig[0..$(3)] N.B.: The sub-bricks are read in the order specified, which may not be the order in the original dataset. For example, using fred+orig[0..$(2),1..$(2)] will cause the sub-bricks in fred+orig to be input into memory in an interleaved fashion. Using fred+orig[$..0] will reverse the order of the sub-bricks. N.B.: You may also use the syntax <a..b> after the name of an input dataset to restrict the range of values read in to the numerical values in a..b, inclusive. For example, fred+orig[5..7]<100..200> creates a 3 sub-brick dataset with values less than 100 or greater than 200 from the original set to zero. If you use the <> sub-range selection without the [] sub-brick selection, it is the same as if you had put [0..$] in front of the sub-range selection. N.B.: Datasets using sub-brick/sub-range selectors are treated as: - 3D+time if the dataset is 3D+time and more than 1 brick is chosen - otherwise, as bucket datasets (-abuc or -fbuc) (in particular, fico, fitt, etc datasets are converted to fbuc!) N.B.: The characters '$ ( ) [ ] < >' are special to the shell, so you will have to escape them. This is most easily done by putting the entire dataset plus selection list inside forward single quotes, as in 'fred+orig[5..7,9]', or double quotes "x". CATENATED AND WILDCARD DATASET NAMES ------------------------------------ Datasets may also be catenated or combined in memory, as if one first ran 3dTcat or 3dbucket. An input with space-separated elements will be read as a concatenated dataset, as with 'dset1+tlrc dset2+tlrc dset3+tlrc', or with paths, 'dir/dset1+tlrc dir/dset2+tlrc dir/dset3+tlrc'. The datasets will be combined (as if by 3dTcat) and then treated as a single input dataset. Note that the quotes are required to specify them as a single argument. Sub-brick selection using '[]' works with space separated dataset names. If the selector is at the end, it is considered global and applies to all inputs. Otherwise, it applies to the adjacent input. For example: local: 'dset1+tlrc[2,3] dset2+tlrc[7,0,1] dset3+tlrc[5,0,$]' global: 'dset1+tlrc dset2+tlrc dset3+tlrc[5,6]' N.B. If AFNI_PATH_SPACES_OK is set to Yes, will be considered as part of the dataset name, and not as a separator between them. Similar treatment applies when specifying datasets using a wildcard pattern, using '*' or '?', as in: 'dset*+tlrc.HEAD'. Any sub-brick selectors would apply to all matching datasets, as with: 'dset*+tlrc.HEAD[2,5,3]' N.B.: complete filenames are required when using wildcard matching, or no files will exist to match, e.g. 'dset*+tlrc' would not work. N.B.: '[]' are processed as sub-brick or time point selectors. They are therefore not allowed as wildcard characters in this context. Space and wildcard catenation can be put together. In such a case, spaces divide the input into wildcard pieces, which are processed individually. Examples (each is processed as a single, combined dataset): 'dset1+tlrc dset2+tlrc dset3+tlrc' 'dset1+tlrc dset2+tlrc dset3+tlrc[2,5,3]' 'dset1+tlrc[3] dset2+tlrc[0,1] dset3+tlrc[3,0,1]' 'dset*+tlrc.HEAD' 'dset*+tlrc.HEAD[2,5,3]' 'dset1*+tlrc.HEAD[0,1] dset2*+tlrc.HEAD[7,8]' 'group.*/subj.*/stats*+tlrc.HEAD[7]' ------------------------------------------------------------------------ 1D TIME SERIES: ~1~ -------------- You can also input a '*.1D' time series file in place of a dataset. In this case, the value at each spatial voxel at time index n will be the same, and will be the n-th value from the time series file. At least one true dataset must be input. If all the input datasets are 3D (single sub-brick) or are single sub-bricks from multi-brick datasets, then the output will be a 'manufactured' 3D+time dataset. For example, suppose that 'a3D+orig' is a 3D dataset: 3dcalc -a a3D+orig -b b.1D -expr "a*b" The output dataset will 3D+time with the value at (x,y,z,t) being computed by a3D(x,y,z)*b(t). The TR for this dataset will be set to 'tstep' seconds -- this could be altered later with program 3drefit. Another method to set up the correct timing would be to input an unused 3D+time dataset -- 3dcalc will then copy that dataset's time information, but simply do not use that dataset's letter in -expr. If the *.1D file has multiple columns, only the first read will be used in this program. You can select a column to be the first by using a sub-vector selection of the form 'b.1D[3]', which will choose the 4th column (since counting starts at 0). '{...}' row selectors can also be used - see the output of '1dcat -help' for more details on these. Note that if multiple timeseries or 3D+time or 3D bucket datasets are input, they must all have the same number of points along the 'time' dimension. N.B.: To perform calculations ONLY on .1D files, use program 1deval. 3dcalc takes .1D files for use in combination with 3D datasets! N.B.: If you auto-transpose a .1D file on the command line, (by ending the filename with \'), then 3dcalc will NOT treat it as the special case described above, but instead will treat it as a normal dataset, where each row in the transposed input is a 'voxel' time series. This would allow you to do differential subscripts on 1D time series, which program 1deval does not implement. For example: 3dcalc -a '1D: 3 4 5 6'\' -b a+l -expr 'sqrt(a+b)' -prefix - This technique allows expression evaluation on multi-column .1D files, which 1deval also does not implement. For example: 3dcalc -a '1D: 3 4 5 | 1 2 3'\' -expr 'cbrt(a)' -prefix - ------------------------------------------------------------------------ '1D:' INPUT: ~1~ ----------- You can input a 1D time series 'dataset' directly on the command line, without an external file. The 'filename for such input takes the general format '1D:n_1@val_1,n_2@val_2,n_3@val_3,...' where each 'n_i' is an integer and each 'val_i' is a float. For example -a '1D:5@0,10@1,5@0,10@1,5@0' specifies that variable 'a' be assigned to a 1D time series of 35, alternating in blocks between values 0 and value 1. You can combine 3dUndump with 3dcalc to create an all zero 3D+time dataset from 'thin air', as in the commands 3dUndump -dimen 128 128 32 -prefix AllZero_A -datum float 3dcalc -a AllZero_A+orig -b '1D: 100@' -expr 0 -prefix AllZero_B If you replace the '0' expression with 'gran(0,1)', you'd get a random 3D+time dataset, which might be useful for testing purposes. ------------------------------------------------------------------------ 'I:*.1D' and 'J:*.1D' and 'K:*.1D' INPUT: ~1~ ---------------------------------------- You can input a 1D time series 'dataset' to be defined as spatially dependent instead of time dependent using a syntax like: -c I:fred.1D This indicates that the n-th value from file fred.1D is to be associated with the spatial voxel index i=n (respectively j=n and k=n for 'J: and K: input dataset names). This technique can be useful if you want to scale each slice by a fixed constant; for example: -a dset+orig -b K:slicefactor.1D -expr 'a*b' In this example, the '-b' value only varies in the k-index spatial direction. ------------------------------------------------------------------------ COORDINATES and PREDEFINED VALUES: ~1~ --------------------------------- If you don't use '-x', '-y', or '-z' for a dataset, then the voxel spatial coordinates will be loaded into those variables. For example, the expression 'a*step(x*x+y*y+z*z-100)' will zero out all the voxels inside a 10 mm radius of the origin x=y=z=0. Similarly, the '-t' value, if not otherwise used by a dataset or *.1D input, will be loaded with the voxel time coordinate, as determined from the header file created for the OUTPUT. Please note that the units of this are variable; they might be in milliseconds, seconds, or Hertz. In addition, slices of the dataset might be offset in time from one another, and this is allowed for in the computation of 't'. Use program 3dinfo to find out the structure of your datasets, if you are not sure. If no input datasets are 3D+time, then the effective value of TR is tstep in the output dataset, with t=0 at the first sub-brick. Similarly, the '-i', '-j', and '-k' values, if not otherwise used, will be loaded with the voxel spatial index coordinates. The '-l' (letter 'ell') value will be loaded with the temporal index coordinate. The '-n' value, if not otherwise used, will be loaded with the overall voxel 1D index. For a 3D dataset, n = i + j*NX + k*NX*NY, where NX, NY, NZ are the array dimensions of the 3D grid. [29 Jul 2010] Otherwise undefined letters will be set to zero. In the future, new default values for other letters may be added. NOTE WELL: By default, the coordinate order of (x,y,z) is the order in ********* which the data array is stored on disk; this order is output by 3dinfo. The options below control can change this order: -dicom }= Sets the coordinates to appear in DICOM standard (RAI) order, -RAI }= (the AFNI standard), so that -x=Right, -y=Anterior , -z=Inferior, +x=Left , +y=Posterior, +z=Superior. -SPM }= Sets the coordinates to appear in SPM (LPI) order, -LPI }= so that -x=Left , -y=Posterior, -z=Inferior, +x=Right, +y=Anterior , +z=Superior. The -LPI/-RAI behavior can also be achieved via the AFNI_ORIENT environment variable (27 Aug, 2014). ------------------------------------------------------------------------ DIFFERENTIAL SUBSCRIPTS [22 Nov 1999]: ~1~ ----------------------- Normal calculations with 3dcalc are strictly on a per-voxel basis: there is no 'cross-talk' between spatial or temporal locations. The differential subscript feature allows you to specify variables that refer to different locations, relative to the base voxel. For example, -a fred+orig -b 'a[1,0,0,0]' -c 'a[0,-1,0,0]' -d 'a[0,0,2,0]' means: symbol 'a' refers to a voxel in dataset fred+orig, symbol 'b' refers to the following voxel in the x-direction, symbol 'c' refers to the previous voxel in the y-direction symbol 'd' refers to the 2nd following voxel in the z-direction To use this feature, you must define the base dataset (e.g., 'a') first. Then the differentially subscripted symbols are defined using the base dataset symbol followed by 4 integer subscripts, which are the shifts in the x-, y-, z-, and t- (or sub-brick index) directions. For example, -a fred+orig -b 'a[0,0,0,1]' -c 'a[0,0,0,-1]' -expr 'median(a,b,c)' will produce a temporal median smoothing of a 3D+time dataset (this can be done more efficiently with program 3dTsmooth). Note that the physical directions of the x-, y-, and z-axes depend on how the dataset was acquired or constructed. See the output of program 3dinfo to determine what direction corresponds to what axis. For convenience, the following abbreviations may be used in place of some common subscript combinations: [1,0,0,0] == +i [-1, 0, 0, 0] == -i [0,1,0,0] == +j [ 0,-1, 0, 0] == -j [0,0,1,0] == +k [ 0, 0,-1, 0] == -k [0,0,0,1] == +l [ 0, 0, 0,-1] == -l The median smoothing example can thus be abbreviated as -a fred+orig -b a+l -c a-l -expr 'median(a,b,c)' When a shift calls for a voxel that is outside of the dataset range, one of three things can happen: STOP => shifting stops at the edge of the dataset WRAP => shifting wraps back to the opposite edge of the dataset ZERO => the voxel value is returned as zero Which one applies depends on the setting of the shifting mode at the time the symbol using differential subscripting is defined. The mode is set by one of the switches '-dsSTOP', '-dsWRAP', or '-dsZERO'. The default mode is STOP. Suppose that a dataset has range 0..99 in the x-direction. Then when voxel 101 is called for, the value returned is STOP => value from voxel 99 [didn't shift past edge of dataset] WRAP => value from voxel 1 [wrapped back through opposite edge] ZERO => the number 0.0 You can set the shifting mode more than once - the most recent setting on the command line applies when a differential subscript symbol is encountered. N.B.: You can also use program 3dLocalstat to process data from a spatial neighborhood of each voxel; for example, to compute the maximum over a sphere of radius 9 mm placed around each voxel: 3dLocalstat -nbhd 'SPHERE(9)' -stat max -prefix Amax9 A+orig ------------------------------------------------------------------------ ISSUES: ~1~ ------ * Complex-valued datasets cannot be processed, except via '-cx2r'. * This program is not very efficient (but is faster than it once was). * Differential subscripts slow the program down even more. ------------------------------------------------------------------------ ------------------------------------------------------------------------ EXPRESSIONS: ~1~ ----------- As noted above, datasets are referred to by single letter variable names. Arithmetic expressions are allowed, using + - * / ** ^ and parentheses. C relational, boolean, and conditional expressions are NOT implemented! * Note that the expression evaluator is designed not to fail; illegal * * operations like 'sqrt(-1)' are changed to legal ones to avoid crashes.* Built in functions include: sin , cos , tan , asin , acos , atan , atan2, sinh , cosh , tanh , asinh , acosh , atanh , exp , log , log10, abs , int , sqrt , max , min , J0 , J1 , Y0 , Y1 , erf , erfc , qginv, qg , rect , step , astep, bool , and , or , mofn , sind , cosd , tand , median, lmode , hmode , mad , gran , uran , iran , eran , lran , orstat, mod , mean , stdev, sem , Pleg , cbrt , rhddc2, hrfbk4,hrfbk5 minabove, maxbelow, extreme, absextreme , acfwxm gamp , gampq where some of the less obvious functions are: * qg(x) = reversed cdf of a standard normal distribution * qginv(x) = inverse function to qg * min, max, atan2 each take 2 arguments ONLY * J0, J1, Y0, Y1 are Bessel functions (see the holy book: Watson) * Pleg(m,x) is the m'th Legendre polynomial evaluated at x * erf, erfc are the error and complementary error functions * sind, cosd, tand take arguments in degrees (vs. radians) * median(a,b,c,...) computes the median of its arguments * mad(a,b,c,...) computes the MAD of its arguments * mean(a,b,c,...) computes the mean of its arguments * stdev(a,b,c,...) computes the standard deviation of its arguments * sem(a,b,c,...) computes standard error of the mean of its arguments, where sem(n arguments) = stdev(same)/sqrt(n) * orstat(n,a,b,c,...) computes the n-th order statistic of {a,b,c,...} - that is, the n-th value in size, starting at the bottom (e.g., orstat(1,a,b,c) is the minimum) * minabove(X,a,b,c,...) computes the smallest value amongst {a,b,c,...} that is LARGER than the first argument X; if all values are smaller than X, then X will be returned * maxbelow(X,a,b,c,...) similarly returns the largest value amongst {a,b,c,...} that is SMALLER than the first argument X. * extreme(a,b,c,...) finds the largest absolute value amongst {a,b,c,...} returning one of the original a,b,c,... values. * absextreme(a,b,c,...) finds the largest absolute value amongst {a,b,c,...} returning the maximum absolute value of a,b,c,... values. * lmode(a,b,c,...) and hmode(a,b,c,...) compute the mode of their arguments - lmode breaks ties by choosing the smallest value with the maximal count, hmode breaks ties by choosing the largest value with the maximal count ["a,b,c,..." indicates a variable number of arguments] * gran(m,s) returns a Gaussian deviate with mean=m, stdev=s * uran(r) returns a uniform deviate in the range [0,r] * iran(t) returns a random integer in the range [0..t] * eran(s) returns an exponentially distributed deviate with parameter s; mean=s * lran(t) returns a logistically distributed deviate with parameter t; mean=0, stdev=t*1.814 * mod(a,b) returns (a modulo b) = a - b*int(a/b) * hrfbk4(t,L) and hrfbk5(t,L) are the BLOCK4 and BLOCK5 hemodynamic response functions from 3dDeconvolve (L=stimulus duration in sec, and t is the time in sec since start of stimulus); for example: 1deval -del 0.1 -num 400 -expr 'hrfbk5(t-2,20)' | 1dplot -stdin -del 0.1 These HRF functions are scaled to return values in the range [0..1] * ACFWXM(a,b,c,x) returns the Full Width at X Maximum for the mixed model ACF function f(r) = a*expr(-r*r/(2*b*b))+(1-a)*exp(-r/c) for X between 0 and 1 (not inclusive). This is the model function estimated in program 3dFWHMx. * gamp(peak,fwhm) returns the parameter p in the formula g(t) = (t/(p*q))^p * exp(p-t/q) that gives the peak value of g(t) occurring at t=peak when the FWHM of g(t) is given by fwhm; gamq(peak,fwhm) gives the q parameter. These functions are largely used for creating FMRI hemodynamic shapes. You may use the symbol 'PI' to refer to the constant of that name. This is the only 2 letter symbol defined; all variables are referred to by 1 letter symbols. The case of the expression is ignored (in fact, it is converted to uppercase as the first step in the parsing algorithm). The following functions are designed to help implement logical functions, such as masking of 3D volumes against some criterion: step(x) = {1 if x>0 , 0 if x<=0}, posval(x) = {x if x>0 , 0 if x<=0}, astep(x,y) = {1 if abs(x) > y , 0 otherwise} = step(abs(x)-y) within(x,MI,MX) = {1 if MI <= x <= MX , 0 otherwise}, rect(x) = {1 if abs(x)<=0.5, 0 if abs(x)>0.5}, bool(x) = {1 if x != 0.0 , 0 if x == 0.0}, notzero(x) = bool(x), iszero(x) = 1-bool(x) = { 0 if x != 0.0, 1 if x == 0.0 }, not(x) = same as iszero(x) equals(x,y) = 1-bool(x-y) = { 1 if x == y , 0 if x != y }, ispositive(x) = { 1 if x > 0; 0 if x <= 0 }, isnegative(x) = { 1 if x < 0; 0 if x >= 0 }, ifelse(x,t,f) = { t if x != 0; f if x == 0 }, not(x) = same as iszero(x) = Boolean negation and(a,b,...,c) = {1 if all arguments are nonzero, 0 if any are zero} or(a,b,...,c) = {1 if any arguments are nonzero, 0 if all are zero} mofn(m,a,...,c) = {1 if at least 'm' arguments are nonzero, else 0 } argmax(a,b,...) = index of largest argument; = 0 if all args are 0 argnum(a,b,...) = number of nonzero arguments pairmax(a,b,...)= finds the 'paired' argument that corresponds to the maximum of the first half of the input arguments; for example, pairmax(a,b,c,p,q,r) determines which of {a,b,c} is the max, then returns corresponding value from {p,q,r}; requires even number of args. pairmin(a,b,...)= Similar to pairmax, but for minimum; for example, pairmin(a,b,c,p,q,r} finds the minimum of {a,b,c} and returns the corresponding value from {p,q,r}; pairmin(3,2,7,5,-1,-2,-3,-4) = -2 (The 'pair' functions are Lukas Pezawas specials!) amongst(a,b,...)= Return value is 1 if any of the b,c,... values equals the a value; otherwise, return value is 0. choose(n,a,b,...)= chooses the n-th value from the a,b,... values. (e.g., choose(2,a,b,c) is b) isprime(n) = 1 if n is a positive integer and a prime number 0 if n is a positive integer and not a prime number -1 if n is not a positive integer or if n is bigger than 2^31-1 [These last 9 functions take a variable number of arguments.] The following 27 functions are used for statistical conversions, as in the program 'cdf': fico_t2p(t,a,b,c), fico_p2t(p,a,b,c), fico_t2z(t,a,b,c), fitt_t2p(t,a) , fitt_p2t(p,a) , fitt_t2z(t,a) , fift_t2p(t,a,b) , fift_p2t(p,a,b) , fift_t2z(t,a,b) , fizt_t2p(t) , fizt_p2t(p) , fizt_t2z(t) , fict_t2p(t,a) , fict_p2t(p,a) , fict_t2z(t,a) , fibt_t2p(t,a,b) , fibt_p2t(p,a,b) , fibt_t2z(t,a,b) , fibn_t2p(t,a,b) , fibn_p2t(p,a,b) , fibn_t2z(t,a,b) , figt_t2p(t,a,b) , figt_p2t(p,a,b) , figt_t2z(t,a,b) , fipt_t2p(t,a) , fipt_p2t(p,a) , fipt_t2z(t,a) . See the output of 'cdf -help' for documentation on the meanings of and arguments to these functions. The two functions below use the NIfTI-1 statistical codes to map between statistical values and cumulative distribution values: cdf2stat(val,code,p1,p2,p3) -- val is between 0 and 1 stat2cdf(val,code,p1,p2,p3) -- val is legal for the given distribution where code is 2 = correlation statistic p1 = DOF 3 = t statistic (central) p1 = DOF 4 = F statistic (central) p1 = num DOF, p2 = den DOF 5 = N(0,1) statistic no parameters (p1=p2=p3=0) 6 = Chi-squared (central) p1 = DOF 7 = Beta variable (central) p1 = a , p2 = b 8 = Binomial variable p1 = #trials, p2 = prob per trial 9 = Gamma distribution p1 = shape, p2 = scale 10 = Poisson distribution p1 = mean 11 = N(mu,variance) normal p1 = mean, p2 = scale 12 = noncentral F statistic p1 = num DOF, p2 = den DOF, p3 = noncen 13 = noncentral chi-squared p1 = DOF, p2 = noncentrality parameter 14 = Logistic distribution p1 = mean, p2 = scale 15 = Laplace distribution p1 = mean, p2 = scale 16 = Uniform distribution p1 = min, p2 = max 17 = noncentral t statistic p1 = DOF, p2 = noncentrality parameter 18 = Weibull distribution p1 = location, p2 = scale, p3 = power 19 = Chi statistic (central) p1 = DOF 20 = inverse Gaussian variable p1 = mu, p2 = lambda 21 = Extreme value type I p1 = location, p2 = scale 22 = 'p-value' no parameters 23 = -ln(p) no parameters 24 = -log10(p) no parameters When fewer than 3 parameters are needed, the values for later parameters are still required, but will be ignored. An extreme case is code=5, where the correct call is (e.g.) cdf2stat(p,5,0,0,0) Finally, note that the expression evaluator is designed not to crash, or to return NaN or Infinity. Illegal operations, such as division by 0, logarithm of negative value, etc., are intercepted and something else (usually 0) will be returned. To find out what that 'something else' is in any specific case, you should play with the ccalc program. ** If you modify a statistical sub-brick, you may want to use program '3drefit' to modify the dataset statistical auxiliary parameters. ** Computations are carried out in double precision before being truncated to the final output 'datum'. ** Note that the quotes around the expression are needed so the shell doesn't try to expand * characters, or interpret parentheses. ** Try the 'ccalc' program to see how the expression evaluator works. The arithmetic parser and evaluator is written in Fortran-77 and is derived from a program written long ago by RW Cox to facilitate compiling on an array processor hooked up to a VAX. (It's a mess, but it works - somewhat slowly - but hey, computers are fast these days.) ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dClipLevel
Usage: 3dClipLevel [options] dataset Estimates the value at which to clip the anatomical dataset so that background regions are set to zero. The program's output is a single number sent to stdout. This value can be 'captured' to a shell variable using the backward single quote operator; a trivial csh/tcsh example is set ccc = `3dClipLevel -mfrac 0.333 Elvis+orig` 3dcalc -a Elvis+orig -expr "step(a-$ccc)" -prefix Presley Algorithm: (a) Set some initial clip value using wizardry (AKA 'variance'). (b) Find the median of all positive values >= clip value. (c) Set the clip value to 0.50 of this median. (d) Loop back to (b) until the clip value doesn't change. This method was made up out of nothing, based on histogram gazing. Options: -------- -mfrac ff = Use the number ff instead of 0.50 in the algorithm. -doall = Apply the algorithm to each sub-brick separately. [Cannot be combined with '-grad'!] -grad ppp = In addition to using the 'one size fits all routine', also compute a 'gradual' clip level as a function of voxel position, and output that to a dataset with prefix 'ppp'. [This is the same 'gradual' clip level that is now the default in 3dAutomask - as of 24 Oct 2006. You can use this option to see how 3dAutomask clips the dataset as its first step. The algorithm above is is used in each octant of the dataset, and then these 8 values are interpolated to cover the whole volume.] Notes: ------ * Use at your own risk! You might want to use the AFNI Histogram plugin to see if the results are reasonable. This program is likely to produce bad results on images gathered with local RF coils, or with pulse sequences with unusual contrasts. * For brain images, most brain voxels seem to be in the range from the clip level (mfrac=0.5) to about 3-3.5 times the clip level. - In T1-weighted images, voxels above that level are usually blood vessels (e.g., inflow artifact brightens them). * If the input dataset has more than 1 sub-brick, the data is analyzed on the median volume -- at each voxel, the median of all sub-bricks at that voxel is computed, and then this median volume is used in the histogram algorithm. * If the input dataset is short- or byte-valued, the output will be an integer; otherwise, the output is a float value. * Example -- Scaling a sequence of sub-bricks from a collection of anatomicals from different sites to have about the same numerical range (from 0 to 255): 3dTcat -prefix input anat_*+tlrc.HEAD 3dClipLevel -doall input+tlrc > clip.1D 3dcalc -datum byte -nscale -a input+tlrc -b clip.1D \ -expr '255*max(0,min(1,a/(3.2*b)))' -verb -prefix scaled ---------------------------------------------------------------------- * Author: Emperor Zhark -- Sadistic Galactic Domination since 1994! ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dclust
Program: 3dclust Author: RW Cox et alii Date: 12 Jul 2017 3dclust - performs simple-minded cluster detection in 3D datasets *** PLEASE NOTE THAT THE NEWER PROGRAM 3dClusterize *** *** IS BETTER AND YOU SHOULD USE THAT FROM NOW ON!! *** This program can be used to find clusters of 'active' voxels and print out a report about them. * 'Active' refers to nonzero voxels that survive the threshold that you (the user) have specified * Clusters are defined by a connectivity radius parameter 'rmm' *OR* Clusters are defined by how close neighboring voxels must be in the 3D grid: first nearest neighbors (-NN1) second nearest neighbors (-NN2) third nearest neighbors (-NN3) Note: by default, this program clusters on the absolute values of the voxels ----------------------------------------------------------------------- Usage: 3dclust [editing options] [other options] rmm vmul dset ... *OR* 3dclust [editing options] -NNx dset ... where '-NNx' is one of '-NN1' or '-NN2' or '-NN3': -NN1 == 1st nearest-neighbor (faces touching) clustering -NN2 == 2nd nearest-neighbor (edges touching) clustering -NN2 == 3rd nearest-neighbor (corners touching) clustering Optionally, you can put an integer after the '-NNx' option, to indicate the minimum number of voxels to allow in a cluster; for example: -NN2 60 ----------------------------------------------------------------------- Examples: --------- 3dclust -1clip 0.3 5 2000 func+orig'[1]' 3dclust -1noneg -1thresh 0.3 5 2000 func+orig'[1]' 3dclust -1noneg -1thresh 0.3 5 2000 func+orig'[1]' func+orig'[3] 3dclust -noabs -1clip 0.5 -dxyz=1 1 10 func+orig'[1]' 3dclust -noabs -1clip 0.5 5 700 func+orig'[1]' 3dclust -noabs -2clip 0 999 -dxyz=1 1 10 func+orig'[1]' 3dclust -1clip 0.3 5 3000 func+orig'[1]' 3dclust -quiet -1clip 0.3 5 3000 func+orig'[1]' 3dclust -summarize -quiet -1clip 0.3 5 3000 func+orig'[1]' 3dclust -1Dformat -1clip 0.3 5 3000 func+orig'[1]' > out.1D ----------------------------------------------------------------------- Arguments (must be included on command line): --------- THE OLD WAY TO SPECIFY THE TYPE OF CLUSTERING rmm : cluster connection radius (in millimeters). All nonzero voxels closer than rmm millimeters (center-to-center distance) to the given voxel are included in the cluster. * If rmm = 0, then clusters are defined by nearest- neighbor connectivity vmul : minimum cluster volume (micro-liters) i.e., determines the size of the volume cluster. * If vmul = 0, then all clusters are kept. * If vmul < 0, then the absolute vmul is the minimum number of voxels allowed in a cluster. If you do not use one of the '-NNx' options, you must give the numbers for rmm and vmul just before the input dataset name(s) THE NEW WAY TO SPECIFY TYPE OF CLUSTERING [13 Jul 2017] -NN1 or -NN2 or -NN3 If you use one of these '-NNx' options, you do NOT give the rmm and vmul values. Instead, after all the options that start with '-', you just give the input dataset name(s). If you want to set a minimum cluster size using '-NNx', put the minimum voxel count immediately after, as in '-NN3 100'. FOLLOWED BY ONE (or more) DATASETS dset : input dataset (more than one allowed, but only the first sub-brick of the dataset) The results are sent to standard output (i.e., the screen): if you want to save them in a file, then use redirection, as in 3dclust -1thresh 0.4 -NN2 Elvis.nii'[1]' > Elvis.clust.txt ----------------------------------------------------------------------- Options: ------- Editing options are as in 3dmerge (see 3dmerge -help) (including -1thresh, -1dindex, -1tindex, -dxyz=1 options) -NN1 => described earlier; -NN2 => replaces the use of 'rmm' to specify the -NN3 => clustering method (vmul is set to 2 voxels) -noabs => Use the signed voxel intensities (not the absolute value) for calculation of the mean and Standard Error of the Mean (SEM) -summarize => Write out only the total nonzero voxel count and volume for each dataset -nosum => Suppress printout of the totals -verb => Print out a progress report (to stderr) as the computations proceed -1Dformat => Write output in 1D format (now default). You can redirect the output to a .1D file and use the file as input to whereami_afni for obtaining Atlas-based information on cluster locations. See whereami_afni -help for more info. -no_1Dformat => Do not write output in 1D format. -quiet => Suppress all non-essential output -mni => If the input dataset has the +tlrc view, this option will transform the output xyz-coordinates from TLRC to MNI space. N.B.0: Only use this option if the dataset is in Talairach space, NOT when it is already in MNI space. N.B.1: The MNI template brain is about 5 mm higher (in S), 10 mm lower (in I), 5 mm longer (in PA), and tilted about 3 degrees backwards, relative to the Talairach- Tournoux Atlas brain. For more details, see, e.g.: https://imaging.mrc-cbu.cam.ac.uk/imaging/MniTalairach N.B.2: If the input dataset does not have the +tlrc view, then the only effect is to flip the output coordinates to the 'LPI' (neuroscience) orientation, as if you gave the '-orient LPI' option.) -isovalue => Clusters will be formed only from contiguous (in the rmm sense) voxels that also have the same value. N.B.: The normal method is to cluster all contiguous nonzero voxels together. -isomerge => Clusters will be formed from each distinct value in the dataset; spatial contiguity will not be used (but you still have to supply rmm and vmul on the command line). N.B.: 'Clusters' formed this way may well have components that are widely separated! -inmask => If 3dClustSim put an internal attribute into the input dataset that describes a mask, 3dclust will use this mask to eliminate voxels before clustering, if you give this option. '-inmask' is how the AFNI AFNI Clusterize GUI works by default. [If there is no internal mask in the dataset] [header, then '-inmask' doesn't do anything.] N.B.: The usual way for 3dClustSim to have put this internal mask into a functional dataset is via afni_proc.py. -prefix ppp => Write a new dataset that is a copy of the input, but with all voxels not in a cluster set to zero; the new dataset's prefix is 'ppp' N.B.: Use of the -prefix option only affects the first input dataset. -savemask q => Write a new dataset that is an ordered mask, such that the largest cluster is labeled '1', the next largest '2' and so forth. Should be the same as '3dmerge -1clust_order' or Clusterize 'SaveMsk'. -binary => This turns the output of '-savemask' into a binary (0 or 1) mask, rather than a cluster-index mask. **-->> If no clusters are found, the mask is not written! ----------------------------------------------------------------------- N.B.: 'N.B.' is short for 'Nota Bene', Latin for 'Note Well'; also see http://en.wikipedia.org/wiki/Nota_bene ----------------------------------------------------------------------- E.g., 3dclust -1clip 0.3 5 3000 func+orig'[1]' The above command tells 3dclust to find potential cluster volumes for dataset func+orig, sub-brick #1, where the threshold has been set to 0.3 (i.e., ignore voxels with activation threshold >0.3 or <-0.3). Voxels must be no more than 5 mm apart, and the cluster volume must be at least 3000 micro-liters in size. Explanation of 3dclust Output: ----------------------------- Volume : Volume that makes up the cluster, in microliters (mm^3) (or the number of voxels, if -dxyz=1 is given) CM RL : Center of mass (CM) for the cluster in the Right-Left direction (i.e., the coordinates for the CM) CM AP : Center of mass for the cluster in the Anterior-Posterior direction CM IS : Center of mass for the cluster in the Inferior-Superior direction minRL, maxRL : Bounding box for the cluster, min and max coordinates in the Right-Left direction minAP, maxAP : Min and max coordinates in the Anterior-Posterior direction of the volume cluster minIS, max IS: Min and max coordinates in the Inferior-Superior direction of the volume cluster Mean : Mean value for the volume cluster SEM : Standard Error of the Mean for the volume cluster Max Int : Maximum Intensity value for the volume cluster MI RL : Coordinate of the Maximum Intensity value in the Right-Left direction of the volume cluster MI AP : Coordinate of the Maximum Intensity value in the Anterior-Posterior direction of the volume cluster MI IS : Coordinate of the Maximum Intensity value in the Inferior-Superior direction of the volume cluster ----------------------------------------------------------------------- Nota Bene: * The program does not work on complex- or rgb-valued datasets! * Using the -1noneg option is strongly recommended! * 3D+time datasets are allowed, but only if you use the -1tindex and -1dindex options. * Bucket datasets are allowed, but you will almost certainly want to use the -1tindex and -1dindex options with these. * SEM values are not realistic for interpolated data sets! A ROUGH correction is to multiply the SEM of the interpolated data set by the square root of the number of interpolated voxels per original voxel. * If you use -dxyz=1, then rmm should be given in terms of voxel edges (not mm) and vmul should be given in terms of voxel counts (not microliters). Thus, to connect to only 3D nearest neighbors and keep clusters of 10 voxels or more, use something like '3dclust -dxyz=1 1.01 10 dset+orig'. In the report, 'Volume' will be voxel count, but the rest of the coordinate dependent information will be in actual xyz millimeters. * The default coordinate output order is DICOM. If you prefer the SPM coordinate order, use the option '-orient LPI' or set the environment variable AFNI_ORIENT to 'LPI'. For more information, see file README.environment. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dClustCount
Usage: 3dClustCount [options] dataset1 ... This program takes as input 1 or more datasets, thresholds them at various levels, and counts up the number of clusters of various sizes. It is adapted from 3dClustSim, but only does the cluster counting functions -- where the datasets come from is the user's business. It is intended for use in a simulation script. ------- OPTIONS ------- -prefix sss = Use string 'sss' as the prefix of the filename into which results will be summed. The actual filename will be 'sss.clustcount.niml'. If this file already exists, then the results from the current run will be summed into the existing results, and the file then re-written. -final = If this option is given, then the results will be output in a format like that used from 3dClustSim -- as 1D and NIML formatted files with probabilities of various cluster sizes. ++ You can use '-final' without any input datasets if you want to create the final output files from the saved '.clustcount.niml' output file from earlier runs. -quiet = Don't print out the progress reports, etc. ++ Put this option first to quiet most informational messages. -------- EXAMPLE: ------- The steps here are (a) Create a set of 250 3dGroupInCorr results from a set of 190 subjects, using 250 randomly located seed locations. Note the use of '-sendall' to get the individual subject results -- these are used in the next step, and are in sub-bricks 2..191 -- the collective 3dGroupInCorr results (in sub-bricks 0..1) are not actually used here. (b) For each of these 250 output datasets, create 80 random splittings into 2 groups of 95 subjects each, and carry out a 2-sample t-test between these groups. ++ Note the use of program 2perm to create the random splittings into files QQ_A and QQ_B, drawn from sub-bricks 2..191 of the ${fred} datasets. ++ Note the use of the '[1dcat filename]' construction to specify which sub-bricks of the ${fred} dataset are used for input to the '-setX' options of 3dttest++. (c) Count clusters from the '[1]' sub-brick of the 80 t-test outputs -- the t-statistic sub-brick. ++ Note the use of a wildcard filename with a sub-brick selector: 'QQ*.HEAD[1]' -- 3dClustCount will do the wildcard expansion internally, then add the sub-brick selector '[1]' to each expanded dataset filename. (d) Produce the final report files for empirical cluster-size thresholds for 3dGroupInCorr analyses -- rather than rely on 3dClustSim's assumption of Gaussian-shaped spatial correlation structure. The syntax is C-shell (tcsh), naturally. \rm -f ABscat* 3dGroupInCorr -setA A.errts.grpincorr.niml \ -setB B.errts.grpincorr.niml \ -labelA A -labelB B -seedrad 5 -nosix -sendall \ -batchRAND 250 ABscat foreach fred ( ABscat*.HEAD ) foreach nnn ( `count_afni -dig 2 0 79` ) 2perm -prefix QQ 2 191 3dttest++ -setA ${fred}'[1dcat QQ_A]' \ -setB ${fred}'[1dcat QQ_B]' \ -no1sam -prefix QQ${nnn} end 3dClustCount -prefix ABcount 'QQ*.HEAD[1]' \rm -f QQ* end 3dClustCount -final -prefix ABcount \rm -f ABscat* -------------------------------- ---- RW Cox -- August 2012 ----- -------------------------------- ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dClusterize
PURPOSE ~1~ This program is for performing clusterizing: one can perform voxelwise thresholding on a dataset (such as a statistic), and then make a map of remaining clusters of voxels larger than a certain volume. The main output of this program is a single volume dataset showing a map of the cluster ROIs. As of Apr 24, 2020, this program now behaves less (unnecessarily) guardedly when thresholding non-stat volumes. About time, right? This program is specifically meant to reproduce behavior of the muuuch older 3dclust, but this new program: + uses simpler syntax (hopefully); + includes additional clustering behavior such as the '-bisided ...' variety (essentially, two-sided testing where all voxels in a given cluster come from either the left- or right- tail, but not mixed); + a mask (such as the whole brain) can be entered in; + voxelwise thresholds can be input as statistic values or p-values. This program was also written to have simpler/more direct syntax of usage than 3dclust. Some minor options have been carried over for similar behavior, but many of the major option names have been altered. Please read the helps for those below carefully. This program was cobbled together by PA Taylor (NIMH, NIH), but it predominantly uses code written by many legends: RW Cox, BD Ward, MS Beauchamp, ZS Saad, and more. USAGE ~1~ Input: ~2~ + A dataset of one or more bricks + Specify an index of the volume to threshold + Declare a voxelwise threshold, and optionally a cluster-volume threshold + Optionally specify the index an additional 'data' brick + Optionally specify a mask Output: ~2~ + A report about the clusters (center of mass, extent, volume, etc.) that can be dumped into a text file. + Optional: A dataset volume containing a map of cluster ROIs (sorted by size) after thresholding (and clusterizing, if specified). That is, a data set where the voxels in the largest cluster all have a value 1, those in the next largest are all 2, etc. + Optional: a cluster-masked version of an input data set. That is, the values of a selected data set (e.g., effect estimate) that fall within a cluster are output unchanged, and those outside a cluster are zeroed. + Optional: a mask. Explanation of 3dClusterize text report: ~2~ The following columns of cluster summary information are output for quick reference (and please see the asterisked notes below for some important details on the quantities displayed): Nvoxel : Number of voxels in the cluster CM RL : Center of mass (CM) for the cluster in the Right-Left direction (i.e., the coordinates for the CM) CM AP : Center of mass for the cluster in the Anterior-Posterior direction CM IS : Center of mass for the cluster in the Inferior-Superior direction minRL, maxRL : Bounding box for the cluster, min and max coordinates in the Right-Left direction minAP, maxAP : Min and max coordinates in the Anterior-Posterior direction of the volume cluster minIS, maxIS : Min and max coordinates in the Inferior-Superior direction of the volume cluster Mean : Mean value for the volume cluster SEM : Standard Error of the Mean for the volume cluster Max Int : Maximum Intensity value for the volume cluster MI RL : Coordinate of the Maximum Intensity value in the Right-Left direction of the volume cluster MI AP : Coordinate of the Maximum Intensity value in the Anterior-Posterior direction of the volume cluster MI IS : Coordinate of the Maximum Intensity value in the Inferior-Superior direction of the volume cluster * The CM, Mean, SEM, Max Int and MI values are all calculated using using the '-idat ..' subvolume/dataset. In general, those peaks and weighted centers of mass will be different than those of the '-ithr ..' dset (if those are different subvolumes). * CM values use the absolute value of the voxel values as weights. * The program does not work on complex- or rgb-valued datasets! * SEM values are not realistic for interpolated data sets! A ROUGH correction is to multiply the SEM of the interpolated data set by the square root of the number of interpolated voxels per original voxel. * Some summary or 'global' values are placed at the bottoms of report columns, by default. These include the 'global' volume, CM of the combined cluster ROIs, and the mean+SEM of that Pangaea. COMMAND OPTIONS ~1~ -inset III :Load in a dataset III of one or more bricks for thresholding and clusterizing; one can choose to use either just a single sub-brick within it for all operations (e.g., a 'statistics' brick), or to specify an additional sub-brick within it for the actual clusterizing+reporting (after the mask from the thresholding dataset has been applied to it). -mask MMM :Load in a dataset MMM to use as a mask, within which to look for clusters. -mask_from_hdr :If 3dClustSim put an internal attribute into the input dataset that describes a mask, 3dClusterize will use this mask to eliminate voxels before clustering, if you give this option (this is how the AFNI Clusterize GUI works by default). If there is no internal mask in the dataset header, then this doesn't do anything. -out_mask OM :specify that you wanted the utilized mask dumped out as a single volume dataset OM. This is probably only really useful if you are using '-mask_from_hdr'. If not mask option is specified, there will be no output. -ithr j :(required) Uses sub-brick [j] as the threshold source; 'j' can be either an integer *or* a brick_label string. -idat k :Uses sub-brick [k] as the data source (optional); 'k' can be either an integer *or* a brick_label string. If this option is used, thresholding is still done by the 'threshold' dataset, but that threshold map is applied to this 'data' set, which is in turn used for clusterizing and the 'data' set values are used to make the report. If a 'data' dataset is NOT input with '-idat ..', then thresholding, clustering and reporting are all done using the 'threshold' dataset. -1sided SSS TT :Perform one-sided testing. Two arguments are required: SSS -> either 'RIGHT_TAIL' (or 'RIGHT') or 'LEFT_TAIL' (or 'LEFT') to specify which side of the distribution to test. TT -> the threshold value itself. See 'NOTES' below to use a p-value as threshold. -2sided LL RR :Perform two-sided testing. Two arguments are required: LL -> the upper bound of the left tail. RR -> lower bound of the right tail. *NOTE* that in this case, potentially a cluster could be made of both left- and right-tail survivors (e.g., both positive and negative values). For this reason, probably '-bisided ...' is a preferable choice. See 'NOTES' below to use a p-value as threshold. -bisided LL RR :Same as '-2sided ...', except that the tails are tested independently, so a cluster cannot be made of both. See 'NOTES' below to use a p-value as threshold. -within_range AA BB :Perform a kind of clustering where a different kind of thresholding is first performed, compared to the above cases; here, one keeps values within the range [AA, BB], INSTEAD of keeping values on the tails. Is this useful? Who knows, but it exists. See 'NOTES' below to use a p-value as threshold. -NN {1|2|3} :Necessary option to specify how many neighbors a voxel has; one MUST put one of 1, 2 or 3 after it: 1 -> 6 facewise neighbors 2 -> 18 face+edgewise neighbors 3 -> 26 face+edge+cornerwise neighbors If using 3dClustSim (or any other method), make sure that this NN value matches what was used there. (In many AFNI programs, NN=1 is a default choice, but BE SURE YOURSELF!) -clust_nvox M :specify the minimum cluster size in terms of number of voxels M (such as output by 3dClustSim). -clust_vol V :specify the minimum cluster size in terms of volume V, in microliters (requires knowing the voxel size). Probably '-clust_nvox ...' is more useful. -pref_map PPP :The prefix/filename of the output map of cluster ROIs. The 'map' shows each cluster as a set of voxels with the same integer. The clusters are ordered by size, so the largest cluster is made up of 1s, the next largest of 2s, etc. (def: no map of clusters output). -pref_dat DDD :Including this option instructs the program to output a cluster-masked version of the 'data' volume specified by the '-idat ..' index. That is, only data values within the cluster ROIs are included in the output volume. Requires specifying '-idat ..'. (def: no cluster-masked dataset output). -1Dformat :Write output in 1D format (now default). You can redirect the output to a .1D file and use the file as input to whereami_afni for obtaining Atlas-based information on cluster locations. See whereami_afni -help for more info. -no_1Dformat :Do not write output in 1D format. -summarize :Write out only the total nonzero voxel count and volume for each dataset -nosum :Suppress printout of the totals -quiet :Suppress all non-essential output -outvol_if_no_clust: flag to still output an (empty) vol if no clusters are found. Even in this case, no report is is produced if no clusters are found. This option is likely used for some scripting scenarios; also, the user would still need to specify '-pref_* ...' options as above in order to output any volumes with this opt. (def: no volumes output if no clusters found). -orient OOO :in the output report table, make the coordinate order be 'OOO' (def: RAI, the DICOM standard); alternatively, one could set the environment variable AFNI_ORIENT (see the file README.environment). NB: this only affects the coordinate orientation in the *text table*; the dset orientation of the output cluster maps and other volumetric data will match that of the input dataset. -abs_table_data :(new, from Apr 29, 2021) Use the absolute value of voxel intensities (not the raw values) for calculation of the mean and Standard Error of the Mean (SEM) in the report table. Prior to the cited date, this was default behavior (with '-noabs' switching out of it) but no longer. ### -noabs :(as of Apr 29, 2021, this option is no longer needed) Previously this option switched from using default absolute values of voxel intensities for calculation of the mean and Standard Error of the Mean (SEM). But this has now changed, and the default is to just use the signed values themselves; this option will not cause an error, but is not needed. See '-abs_table_data' for reporting abs values. -binary :This turns the output map of cluster ROIs into a binary (0 or 1) mask, rather than a cluster-index mask. If no clusters are found, the mask is not written! (def: each cluster has separate values) NOTES ~1~ Saving the text report ~2~ To save the text file report, use the redirect '>' after the 3dClusterize command and dump the text into a separate file of your own naming. Using p-values as thresholds for statistic volumes ~2~ By default, numbers entered as voxelwise thresholds are assumed to be appropriate statistic values that you have calculated for your desired significance (e.g., using p2dsetstat). HOWEVER, if you just want to enter p-values and have the program do the conversion work for you, then do as follows: prepend 'p=' to your threshold number. - For one-sided tests, the *_TAIL specification is still used, so in either case the p-value just represents the area in the statistical distribution's tail (i.e., you don't have to worry about doing '1-p'). Examples: -1sided RIGHT_TAIL p=0.005 -1sided LEFT_TAIL p=0.001 - For the two-sided/bi-sided tests, the a single p-value is entered to represent the total area under both tails in the statistical distribution, which are assumed to be symmetric. Examples: -bisided p=0.001 -2sided p=0.005 If you want asymmetric tails, you will have to enter both threshold values as statistic values (NB: you could use p2dsetstat to convert each desired p-value to a statistic, and then put in those stat values to this program). You will probably NEED to have negative signs for the cases of '-1sided LEFT_TAIL ..', and for the first entries of '-bisided ..' or '-2sided ..'. You cannot mix p-values and statistic values (for two-sided things, enter either the single p-value or both stats). You cannot use this internal p-to-stat conversion if the volume you are thresholding is not recognized as a stat. Performing appropriate testing ~2~ Don't use a pair of one-sided tests when you *should* be using a two-sided test! EXAMPLES ~1~ 1. Take an output of FMRI testing (e.g., from afni_proc.py), whose [1] brick contains the effect estimate from a statistical model and whose [2] brick contains the associated statistic; use the results of 3dClustSim run with NN=1 (here, a cluster threshold volume of 157 voxels) and perform one-sided testing with a threshold at an appropriate value (here, 3.313). 3dClusterize \ -inset stats.FT+tlrc. \ -ithr 2 \ -idat 1 \ -mask mask_group+tlrc. \ -NN 1 \ -1sided RIGHT_TAIL 3.313 \ -clust_nvox 157 \ -pref_map ClusterMap 2. The same as Ex. 1, but using bisided testing (two sided testing where the results of each tail can't be joined into the same cluster). Note, the tail thresholds do NOT have to be symmetric (but often they are). Also, here we output the cluster-masked 'data' volume. 3dClusterize \ -inset stats.FT+tlrc. \ -ithr 2 \ -idat 1 \ -mask mask_group+tlrc. \ -NN 1 \ -bisided -3.313 3.313 \ -clust_nvox 157 \ -pref_map ClusterMap \ -pref_dat ClusterEffEst 3. The same as Ex. 2, but specifying a p-value to set the voxelwise thresholds (in this case, tails DO have to be symmetric). 3dClusterize \ -inset stats.FT+tlrc. \ -ithr 2 \ -idat 1 \ -mask mask_group+tlrc. \ -NN 1 \ -bisided p=0.001 \ -clust_nvox 157 \ -pref_map ClusterMap \ -pref_dat ClusterEffEst 4. Threshold a non-stat dset. 3dClusterize \ -inset anat+orig \ -ithr 0 \ -idat 0 \ -NN 1 \ -within_range 500 1000 \ -clust_nvox 100 \ -pref_map ClusterMap \ -pref_dat ClusterEffEst # ------------------------------------------------------------------------

AFNI program: 3dClustSim
Usage: 3dClustSim [options] Program to estimate the probability of false positive (noise-only) clusters. An adaptation of Doug Ward's AlphaSim, streamlined for various purposes. ----------------------------------------------------------------------------- This program has several different modes of operation, each one involving simulating noise-only random volumes, thresholding and clustering them, and counting statistics of how often data 'survives' these processes at various threshold combinations (per-voxel and cluster-size). OLDEST method = simulate noise volume assuming the spatial auto-correlation function (ACF) is given by a Gaussian-shaped function, where this shape is specified using the FWHM parameter. The FWHM parameter can be estimated by program 3dFWHMx. ** THIS METHOD IS NO LONGER RECOMMENDED ** NEWER method = simulate noise volume assuming the ACF is given by a mixed-model of the form a*exp(-r*r/(2*b*b))+(1-a)*exp(-r/c), where a,b,c are 3 parameters giving the shape, and can also be estimated by program 3dFWHMx. ** THIS METHOD IS ACCEPTABLE ** NEWEST method = program 3dttest++ simulates the noise volumes by randomizing and permuting input datasets, and sending those volumes into 3dClustSim directly. There is no built-in math model for the spatial ACF. ** THIS METHOD IS MOST ACCURATE AT CONTROLLING FALSE POSITIVE RATE ** ** You invoke this method with the '-Clustsim' option in 3dttest++ ** 3dClustSim computes a cluster-size threshold for a given voxel-wise p-value threshold, such that the probability of anything surviving the dual thresholds is at some given level (specified by the '-athr' option). Note that this cluster-size threshold is the same for all brain regions. There is an implicit assumption that the noise spatial statistics are the same everywhere. Program 3dXClustSim introduces the idea of spatially variable cluster-size thresholds, which may be more useful in some cases. 3dXClustSim's method is invoked by using the '-ETAC' option in 3dttest++. ----------------------------------------------------------------------------- **** NOTICE **** You should use the -acf method, NOT the -fwhm method, when determining cluster-size thresholds for FMRI data. The -acf method will give more accurate false positive rate (FPR) control. **************** In particular, this program lets you run with multiple p-value thresholds (the '-pthr' option) and only outputs the cluster size threshold at chosen values of the alpha significance level (the '-athr' option). In addition, the program allows the output to be formatted for inclusion into an AFNI dataset's header, whence it can be used in the AFNI Clusterize interface to show approximate alpha values for the displayed clusters, where the per-voxel p-value is taken from the interactive threshold slider in the AFNI 'Define Overlay' control panel, and then the per-cluster alpha value is interpolated in this table from 3dClustSim. As you change the threshold slider, the per-voxel p-value (shown below the slider) changes, and then the interpolated alpha values are updated. ************* IMPORTANT NOTE [Dec 2015] *************************************** A completely new method for estimating and using noise smoothness values is now available in 3dFWHMx and 3dClustSim. This method is implemented in the '-acf' options to both programs. 'ACF' stands for (spatial) AutoCorrelation Function, and it is estimated by calculating moments of differences out to a larger radius than before. Notably, real FMRI data does not actually have a Gaussian-shaped ACF, so the estimated ACF is then fit (in 3dFWHMx) to a mixed model (Gaussian plus mono-exponential) of the form ACF(r) = a * exp(-r*r/(2*b*b)) + (1-a)*exp(-r/c) where 'r' is the radius, and 'a', 'b', 'c' are the fitted parameters. The apparent FWHM from this model is usually somewhat larger in real data than the FWHM estimated from just the nearest-neighbor differences used in the 'classic' analysis. The longer tails provided by the mono-exponential are also significant. 3dClustSim has also been modified to use the ACF model given above to generate noise random fields. **----------------------------------------------------------------------------** ** The take-away (TL;DR or summary) message is that the 'classic' 3dFWHMx and ** ** 3dClustSim analysis, using a pure Gaussian ACF, is not very correct for ** ** FMRI data -- I cannot speak for PET or MEG data. ** **----------------------------------------------------------------------------** ** ---------------------------------------------------------------------------** ** IMPORTANT CHANGES -- February 2015 ****************************************** ** ---------------------------------------------------------------------------** ** In the past, 3dClustSim did '1-sided' testing; that is, the random dataset ** of Gaussian noise-only values is generated, and then it is thresholded on ** the positive side so that the N(0,1) upper tail probability is pthr. ** ** NOW, 3dClustSim does 3 different types of thresholding: ** 1-sided: as above ** 2-sided: where positive and negative values above the threshold ** are included, and then clustered together ** (in this case, the threshold on the Gaussian values is) ** (fixed so that the 1-sided tail probability is pthr/2.) ** bi-sided: where positive values and negative values above the ** threshold are clustered SEPARATELY (with the 2-sided threshold) ** For high levels of smoothness, the results from bi-sided and 2-sided are ** very similar -- since for smooth data, it is unlikely that large clusters of ** positive and negative values will be next to each other. With high smoothness, ** it is also true that the 2-sided results for 2*pthr will be similar to the ** 1-sided results for pthr, for the same reason. Since 3dClustSim is meant to be ** useful when the noise is NOT very smooth, we provide tables for all 3 cases. ** ** In particular, note that when the AFNI GUI threshold is set to a t-statistic, ** 2-sided testing is what is usually appropriate -- in that case, the cluster ** size thresholds tend to be smaller than the 1-sided case, which means that ** more clusters tend to be significant than in the past. ** ** In addition, the 3 different NN approaches (NN=1, NN=2, NN=3) are ALL ** always computed now. That is, 9 different tables are produced, each ** of which has its proper place when combined with the AFNI Clusterize GUI. ** The 3 different NN methods are: ** 1 = Use first-nearest neighbor clustering ** * above threshold voxels cluster together if faces touch ** 2 = Use second-nearest neighbor clustering ** * voxels cluster together if faces OR edges touch ** 3 = Use third-nearest neighbor clustering ** * voxels cluster together if faces OR edges OR corners touch ** The clustering method only makes a difference at higher (less significant) ** values of pthr. At small values of pthr (more significant), all three ** clustering methods will give very similar results. ** **** PLEASE NOTE that the NIML outputs from this new version are not named the **** same as those from the older version. Thus, any script that takes the NIML **** format tables and inserts them into an AFNI dataset header must be modified **** to match the new names. The 3drefit command fragment output at the end of **** this program (and echoed into file '3dClustSim.cmd') shows the new form **** of the names involved. **** -------------------------------------------------------------------------** **** SMOOTHING CHANGE -- May 2015 ********************************************** ** ---------------------------------------------------------------------------** ** It was pointed out to me (by Anders Eklund and Tom Nichols) that smoothing ** the simulated data over a finite volume introduces 2 artifacts, which might ** be called 'edge effects'. To minimize these problems, this program now makes ** extra-large (padded) simulated volumes before blurring, and then trims those ** back down to the desired size, before continuing with the thresholding and ** cluster-counting steps. To run 3dClustSim without this padding added, use ** the new '-nopad' option. **** -------------------------------------------------------------------------** ------- OPTIONS [at least 1 option is required, or you'll get this help message!] ------- ******* Specify the volume over which the simulation will occur ******* -----** (a) Directly give the spatial domain that will be used **----- -nxyz n1 n2 n3 = Size of 3D grid to use for simulation [default values = 64 64 32] -dxyz d1 d2 d3 = give all 3 voxel sizes at once [default values = 3.5 3.5 3.5] -BALL = inside the 3D grid, mask off points outside a ball at the center of the grid and touching the edges; this will keep about 1/2 the points in the 3D grid. [default = use all voxels in the 3D grid] -----** OR: (b) Specify the spatial domain using a dataset mask **----- -mask mset = Use the 0 sub-brick of dataset 'mset' as a mask to indicate which voxels to analyze (a sub-brick selector '[]' is allowed) -OKsmallmask = Allow small masks. Normally, a mask volume must have 128 or more nonzero voxels. However, IF you know what you are doing, and IF you are willing to live life on the edge of statistical catastrophe, then you can use this option to allow smaller masks -- in a sense, this is the 'consent form' for such strange shenanigans. * If you use this option, it must come BEFORE '-mask'. * Also read the 'CAUTION and CAVEAT' section, far below. -->>** This option is really only recommended for users who understand what they are doing. Misuse of this option could easily be construed as 'p-hacking'; for example, finding results, but your favorite cluster is too small to survive thresholding, so you post-hoc put a small mask down in that region. DON'T DO THIS! ** '-mask' means that '-nxyz' & '-dxyz' & '-BALL' will be ignored. ** -----** OR: (c) Specify the spatial domain by directly giving simulated volumes **----- -inset iset [iset ...] = Read the 'iset' dataset(s) and use THESE volumes as the simulations to threshold and clusterize, [Feb 2016] rather than create the simulations internally. * For example, these datasets could come from 3dttest++ -toz -randomsign 1000 -setA ... * This can be combined with '-mask'. * Using '-inset' means that '-fwhm', '-acf', '-nopad', '-niter', and '-ssave' are ignored as meaningless. ---** the remaining options control how the simulation is done **--- -fwhm s = Gaussian filter width (all 3 dimensions) in mm (non-negative) [default = 0.0 = no smoothing] * If you wish to set different smoothing amounts for each axis, you can instead use option -fwhmxyz sx sy sz to specify the three values separately. **** This option is no longer recommended, since FMRI data **** **** does not have a Gaussian-shaped spatial autocorrelation. **** **** Consider using '-acf' or '3dttest++ -Clustsim' instead. **** -acf a b c = Alternative to Gaussian filtering: use the spherical autocorrelation function parameters output by 3dFWHMx to do non-Gaussian (long-tailed) filtering. * Using '-acf' will make '-fwhm' pointless! * The 'a' parameter must be between 0 and 1. * The 'b' and 'c' parameters (scale radii) must be positive. * The spatial autocorrelation function is given by ACF(r) = a * exp(-r*r/(2*b*b)) + (1-a)*exp(-r/c) >>---------->>*** Combined with 3dFWHMx, the '-acf' method is now a recommended way to generate clustering statistics in AFNI! *** Alternative methods we also recommend: 3dttest++ with the -Clustsim and/or -ETAC options. -nopad = The program now [12 May 2015] adds 'padding' slices along each face to allow for edge effects of the smoothing process. If you want to turn this feature off, use the '-nopad' option. * For example, if you want to compare the 'old' (un-padded) results with the 'new' (padded) results. * '-nopad' has no effect when '-acf' is used, since that option automatically pads the volume when creating it (via FFTs) and then truncates it back to the desired size for clustering. -pthr p1 .. pn = list of uncorrected (per voxel) p-values at which to threshold the simulated images prior to clustering. [default = 0.05 0.02 0.01 0.005 0.002 0.001 0.0005 0.0002 0.0001] -athr a1 .. an = list of corrected (whole volume) alpha-values at which the simulation will print out the cluster size thresholds. For each 'p' and 'a', the smallest cluster size C(p,a) for which the probability of the 'p'-thresholded image having a noise-only cluster of size C is less than 'a' is the output (cf. the sample output, below) [default = 0.10 0.05 0.02 0.01] ** It is possible to use only ONE value in each of '-pthr' and ** ** '-athr', and then you will get exactly one line of output ** ** for each sided-ness and NN case. For example: ** ** -pthr 0.001 -athr 0.05 ** ** Both lists '-pthr' and '-athr' (of values between 0 and 0.2) ** ** should be given in DESCENDING order. They will be sorted to be ** ** that way in any case, and such is how the output will be given. ** ** The list of values following '-pthr' or '-athr' can be replaced ** ** with the single word 'LOTS', which will tell the program to use ** ** a longer list of values for these probabilities [try it & see!] ** ** (i.e., '-pthr LOTS' and/or '-athr LOTS' are legal options) ** -LOTS = the same as using '-pthr LOTS -athr LOTS' -MEGA = adds even MORE values to the '-pthr' and '-athr' grids. * NOTE: you can also invoke '-MEGA' by setting environment variable AFNI_CLUSTSIM_MEGA to YES. * Doing this will over-ride any use of other options to set the '-pthr' and '-athr' lists! -iter n = number of Monte Carlo simulations [default = 10000] -nodec = normally, the program prints the cluster size threshold to 1 decimal place (e.g., 27.2). Of course, clusters only come with an integer number of voxels -- this fractional value is interpolated to give the desired alpha level. If you want no decimal places (so that 27.2 becomes 28), use '-nodec'. -seed S = random number seed [default seed = 123456789] * if seed=0, then program will quasi-randomize it -niml = Output the table in an XML/NIML format, rather than a .1D format. * This option is for use with other software programs; see the NOTES section below for details. * '-niml' also implicitly means '-LOTS'. -both = Output the table in XML/NIML format AND in .1D format. * You probably want to use '-prefix' with this option! Otherwise, everything is mixed together on stdout. * '-both' implies 'niml' which implies '-LOTS' (unless '-MEGA'). So '-pthr' (if desired) should follow '-both'/'-niml' -prefix ppp = Write output for NN method #k to file 'ppp.NNk_Xsided.1D', for k=1, 2, 3, and for X=1sided, 2sided, bisided. * If '-prefix is not used, all results go to standard output. You will probably find this confusing. * If '-niml' is used, the filename is 'ppp.NNk_Xsided.niml'. To be clear, the 9 files that will be named ppp.NN1_1sided.niml ppp.NN1_2sided.niml ppp.NN1_bisided.niml ppp.NN2_1sided.niml ppp.NN2_2sided.niml ppp.NN2_bisided.niml ppp.NN3_1sided.niml ppp.NN3_2sided.niml ppp.NN3_bisided.niml * If '-niml' AND '-mask' are both used, then a compressed ASCII encoding of the mask volume is stored into file 'ppp.mask'. This string can be stored into a dataset header as an attribute with name AFNI_CLUSTSIM_MASK, and will be used in the AFNI Clusterize GUI, if present, to mask out above-threshold voxels before the clusterizing is done (which is how the mask is used here in 3dClustSim). * If the ASCII mask string is NOT stored into the statistics dataset header, then the Clusterize GUI will try to find the original mask dataset and use that instead. If that fails, then masking won't be done in the Clusterize process. -cmd ccc = Write command for putting results into a file's header to a file named 'ccc' instead of '3dClustSim.cmd'. This option is mostly to help with scripting, as in 3dClustSim -cmd XXX.cmd -prefix XXX.nii ... `cat XXX.cmd` XXX.nii -quiet = Don't print out the progress reports, etc. * Put this option first to silence most informational messages. -ssave:TYPE ssprefix = Save the un-thresholded generated random volumes into datasets ('-iter' of them). Here, 'TYPE' is one of these: * blurred == save the blurred 3D volume before masking * masked == save the blurred volume after masking The output datasets will actually get prefixes generated with the string 'ssprefix' being appended by a 6 digit integer (the iteration index), starting at 000000. (You can use SOMETHING.nii as a prefix; it will work OK.) N.B.: This option will slow the program down a lot, and was intended to help just one specific user. ------ NOTES: ------ * This program is like running AlphaSim once for each '-pthr' value and then extracting the relevant information from its 'Alpha' output column. ++ One reason for 3dClustSim to be used in place of AlphaSim is that it will be much faster than running AlphaSim multiple times. ++ Another reason is that the resulting table can be stored in an AFNI dataset's header, and used in the AFNI Clusterize GUI to see estimated cluster significance (alpha) levels. * To be clear, the C(p,alpha) thresholds that are calculated are for alpha = probability of a noise-only smooth random field, after masking and then thresholding at the given per-voxel p value, producing a cluster of voxels at least this big. ++ So if your cluster is larger than the C(p,0.01) threshold in size (say), then it is very unlikely that noise BY ITSELF produced this result. ++ This statement does not mean that ALL the voxels in the cluster are 'truly' active -- it means that at least SOME of them are (very probably) active. The statement of low probability (0.01 in this example) of a false positive result applies to the cluster as a whole, not to each voxel within the cluster. * To add the cluster simulation C(p,alpha) table to the header of an AFNI dataset, something like the following can be done [tcsh syntax]: set fx = ( `3dFWHMx -detrend time_series_dataset+orig` ) 3dClustSim -mask mask+orig -acf $fx[5] $fx[6] $fx[7] -niml -prefix CStemp 3drefit -atrstring AFNI_CLUSTSIM_NN1_1sided file:CStemp.NN1_1sided.niml \ -atrstring AFNI_CLUSTSIM_MASK file:CStemp.mask \ statistics_dataset+orig rm -f CStemp.* AFNI's Clusterize GUI makes use of these attributes, if stored in a statistics dataset (e.g., something from 3dDeconvolve, 3dREMLfit, etc.). ** Nota Bene: afni_proc.py will automatically run 3dClustSim, and ** *** put the results into the statistical results dataset for you. *** **** Another reason to use afni_proc.py for single-subject analyses! **** * 3dClustSim will print (to stderr) a 3drefit command fragment, similar to the one above, that you can use to add cluster tables to any relevant statistical datasets you have lolling about. * The C(p,alpha) table will be used in Clusterize to provide the cluster level alpha value when the AFNI GUI is set so that the Overlay threshold sub-brick is a statistical parameter (e.g., a t- or F-statistic), from which a per-voxel p-value can be calculated, so that Clusterize can interpolate in the C(p,alpha) table. ++ To be clear, the per-voxel p-value is taken from the AFNI GUI threshold slider (the p-value is shown beneath the slider), and then the C(p,alpha) table is inverse-interpolated to find the per-cluster alpha value for each different cluster size. ++ As you move the AFNI threshold slider, the per-voxel (uncorrected for multiple comparisons) p-value changes, the cluster sizes change (as fewer or more voxels are included), and so the reported per-cluster alpha values change for both reasons -- different p and different cluster size. ++ The alpha values reported are 'per-cluster', and are not themselves corrected for multiple comparisons ACROSS clusters. These alpha values are corrected for multiple comparisons WITHIN a cluster. * AFNI will use the NN1, NN2, NN3 tables as needed in its Clusterize interface if they are all stored in the statistics dataset header, depending on the NN level chosen in the Clusterize controller. * The blur estimates (provided to 3dClustSim via -acf) comes from using program 3dFWHMx. ------------------- CAUTION and CAVEAT: [January 2011] ------------------- * If you use a small ROI mask and also have a large blur, then it might happen that it is impossible to find a cluster size threshold C that works for a given (p,alpha) combination. * Generally speaking, C(p,alpha) gets smaller as p gets smaller and C(p,alpha) gets smaller as alpha gets larger. As a result, in a small mask with small p and large alpha, C(p,alpha) might shrink below 1. But clusters of size C less than 1 don't make any sense! * For example, suppose that for p=0.0005 that only 6% of the simulations have ANY above-threshold voxels inside the ROI mask. In that case, C(p=0.0005,alpha=0.06) = 1. There is no smaller value of C where 10% of the simulations have a cluster of size C or larger. Thus, it is impossible to find the cluster size threshold for the combination of p=0.0005 and alpha=0.10 in this case. * 3dClustSim will report a cluster size threshold of C=1 for such cases. It will also print (to stderr) a warning message for all the (p,alpha) combinations that had this problem. ----------------------------- ---- RW Cox -- July 2010 ---- ------------- SAMPLE OUTPUT from the command '3dClustSim -fwhm 7' [only the NN=1 1-sided results] ------------- # 3dClustSim -fwhm 7 # 1-sided thresholding # Grid: 64x64x32 3.50x3.50x3.50 mm^3 (131072 voxels) # # CLUSTER SIZE THRESHOLD(pthr,alpha) in Voxels # -NN 1 | alpha = Prob(Cluster >= given size) # pthr | 0.100 0.050 0.020 0.010 # ------ | ------ ------ ------ ------ 0.050000 162.5 182.2 207.8 225.7 0.020000 64.3 71.0 80.5 88.5 0.010000 40.3 44.7 50.7 55.1 0.005000 28.0 31.2 34.9 38.1 0.002000 19.0 21.2 24.2 26.1 0.001000 14.6 16.3 18.9 20.5 0.000500 11.5 13.0 15.1 16.7 0.000200 8.7 10.0 11.6 12.8 0.000100 7.1 8.3 9.7 10.9 e.g., for this sample volume, if the per-voxel p-value threshold is set at 0.005, then to keep the probability of getting a single noise-only cluster at 0.05 or less, the cluster size threshold should be 32 voxels (the next integer above 31.2). If you ran the same simulation with the '-nodec' option, then the last line above would be 0.000100 8 9 10 11 If you set the per voxel p-value to 0.0001 (1e-4), and want the chance of a noise-only false-positive cluster to be 5% or less, then the cluster size threshold would be 9 -- that is, you would keep all NN clusters with 9 or more voxels. The header lines start with the '#' (commenting) character so that the result is a correctly formatted AFNI .1D file -- it can be used in 1dplot, etc. ========================================================================= * This binary version of 3dClustSim is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dCM
Usage: 3dCM [options] dset Output = center of mass of dataset, to stdout. Note: by default, the output is (x,y,z) values in RAI-DICOM coordinates. But as of Dec, 2016, there are now command line switches for other options (see -local* below). -mask mset :Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be averaged from 'dataset'. Note that the mask dataset and the input dataset must have the same number of voxels. -automask :Generate the mask automatically. -set x y z :After computing the CM of the dataset, set the origin fields in the header so that the CM will be at (x,y,z) in DICOM coords. -local_ijk :Output values as (i,j,k) in local orientation. -roi_vals v0 v1 v2 ... :Compute center of mass for each blob with voxel value of v0, v1, v2, etc. This option is handy for getting ROI centers of mass. -all_rois :Don't bother listing the values of ROIs you want the program will find all of them and produce a full list. -Icent :Compute Internal Center. For some shapes, the center can lie outside the shape. This option finds the location of the center of a voxel closest to the center of mass It will be the same or similar to a center of mass if the CM lies within the volume. It will lie necessarily on an edge voxel if the CMass lies outside the volume -Dcent :Compute Distance Center, i.e. the center of the voxel that has the shortest average distance to all the other voxels. This is much more computational expensive than Cmass or Icent centers -rep_xyz_orient RRR :when reporting (x,y,z) coordinates, use the specified RRR orientation (def: RAI). NB: this does not apply when using '-local_ijk', and will not change the orientation of the dset when using '-set ..'. NOTE: Masking options are ignored with -roi_vals and -all_rois

AFNI program: 3dCompareAffine
Usage: 3dCompareAffine [options] ~1 This program compares two (or more) affine spatial transformations on a dataset, and outputs various measurements of how much these transformations differ in spatial displacements. One use for this program is to compare affine alignment matrices from different methods for aligning 3D brain images. Transformation matrices are specified in a few different ways: * ASCII filename containing 12 numbers arranged in 3 lines: u11 u12 u13 v1 u21 u22 u23 v2 u31 u32 u33 v3 * ASCII filename containing with 12 numbers in a single line: u11 u12 u13 v1 u21 u22 u23 v2 u31 u32 u33 v3 This is the '.aff12.1D' format output by 3dAllineate, and this is the only format that can contain more than one matrix in one file. * Directly on the command line: 'MATRIX(u11,u12,u13,v1,u21,u22,u23,v2,u31,u32,u33,v3)' ------- Options ------- -mask mmm = Read in dataset 'mmm' and use non-zero voxels as the region over which to compare the two affine transformations. * You can specify the use of the MNI152 built-in template mask by '-mask MNI152'. * In the future, perhaps other built-in masks will be created? *OR* -dset ddd = Read in dataset 'mmm', compute an automask from it (via program 3dAutomask), and use that mask as the spatial region for comparison. * If you don't give EITHER '-mask' or '-dset', then this program will use an internal mask derived from the MNI152 template (skull off). -affine aaa = Input an affine transformation (file or 'MATRIX'). *OR* * You can give more than one '-affine' option to -matrix aaa input multiple files. * You can also put multiple filenames after the '-affine' option, as in '-affine aaa.aff12.1D bbb.aff12.1D' * The first matrix found in the first '-affine' option is the base transformation to which all following transformations will be compared. ------ Method ------ 1) The input mask is hollowed out -- that is, all nonzero mask voxels that do NOT neighbor a zero voxel are turned to zero. Thus, only the 'edge' voxels are used in the computations below. For example, the default MNI152 mask has 1818562 nonzero voxels before hollowing out, and has 74668 after hollowing out. The hollowing out algorithm is described in the help for program 3dAutomask. 2) For each surviving voxel, the xyz coordinates are calculated and then transformed by the pair of matrices being compared. Then the Euclidean distance between these two sets of transformed xyz vectors is calculated. The outputs for each comparison are the maximum distance and the root-mean-square (RMS) distance, over the set of hollowed out mask voxels. The purpose of this program is to compare the results from 3dAllineate and other registration programs, run under different conditions. -- Author: RWCox - Mar 2020 at the Tulsa bootcamp

AFNI program: 3dConformist
** Program 3dConformist reads in a collection of datasets and zero pads them to the same size. ** The output volume size is the smallest region that includes all datasets (i.e., the minimal covering box). ** If the datasets cannot be processed (e.g., different grid spacings), then nothing will happen except for error messages. ** The purpose of this program is to be used in scripts that process lots of datasets and needs to make them all conform to the same size for collective voxel-wise analyses. ** The input datasets ARE ALTERED (embiggened)! <<<<<<------****** Therefore, don't use this program casually.

AFNI program: 3dConvolve
** :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( ** ** ** ** This program, 3dConvolve, is no longer supported in AFNI ** ** ** ** :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( :( ** ** Program compile date = May 6 2025

AFNI program: 3dcopy
Usage 1: 3dcopy [-verb] [-denote] old_prefix new_prefix ~1~ Will copy all datasets using the old_prefix to use the new_prefix; 3dcopy fred ethel will copy fred+orig.HEAD to ethel+orig.HEAD fred+orig.BRIK to ethel+orig.BRIK fred+tlrc.HEAD to ethel+tlrc.HEAD fred+tlrc.BRIK.gz to ethel+tlrc.BRIK.gz Usage 2: 3dcopy old_prefix+view new_prefix ~1~ Will copy only the dataset with the given view (orig, acpc, tlrc). Usage 3: 3dcopy old_dataset new_prefix ~1~ Will copy the non-AFNI formatted dataset (e.g., MINC, ANALYZE, CTF) to the AFNI formatted dataset with the given new prefix. Notes: ~1~ * This is to copy entire datasets, possibly with multiple views. So sub-brick selection is not allowed. Please use 3dbucket or 3dTcat for that purpose. * The new datasets have new ID codes. If you are renaming multiple datasets (as in Usage 1), then if the old +orig dataset is the warp parent of the old +acpc and/or +tlrc datasets, then the new +orig dataset will be the warp parent of the new +acpc and +tlrc datasets. If any other datasets point to the old datasets as anat or warp parents, they will still point to the old datasets, not these new ones. * The BRIK files are copied if they exist, keeping the compression suffix unchanged (if any). * The old_prefix may have a directory name attached in front, as in 'gerard/manley/hopkins'. * If the new_prefix does not have a directory name attached (i.e., does NOT look like 'homer/simpson'), then the new datasets will be written in the current directory ('./'). * The new can JUST be a directory now (like the Unix utility 'cp'); in this case the output has the same prefix as the input. * The '-verb' option will print progress reports; otherwise, the program operates silently (unless an error is detected). * The '-denote' option will remove any Notes from the file. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dCRUISEtoAFNI
Usage: 3dCRUISEtoAFNI -input CRUISE_HEADER.dx Converts a CRUISE dataset defined by a header in OpenDX format The conversion is based on sample data and information provided by Aaron Carass from JHU's IACL iacl.ece.jhu.edu [-novolreg]: Ignore any Rotate, Volreg, Tagalign, or WarpDrive transformations present in the Surface Volume. [-noxform]: Same as -novolreg [-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname to be ENVvalue. Quotes are necessary. Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'" See also options -update_env, -environment, etc in the output of 'suma -help' Common Debugging Options: [-trace]: Turns on In/Out debug and Memory tracing. For speeding up the tracing log, I recommend you redirect stdout to a file when using this option. For example, if you were running suma you would use: suma -spec lh.spec -sv ... > TraceFile This option replaces the old -iodbg and -memdbg. [-TRACE]: Turns on extreme tracing. [-nomall]: Turn off memory tracing. [-yesmall]: Turn on memory tracing (default). NOTE: For programs that output results to stdout (that is to your shell/screen), the debugging info might get mixed up with your results. Global Options (available to all AFNI/SUMA programs) -h: Mini help, at time, same as -help in many cases. -help: The entire help output -HELP: Extreme help, same as -help in majority of cases. -h_view: Open help in text editor. AFNI will try to find a GUI editor -hview : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_web: Open help in web browser. AFNI will try to find a browser. -hweb : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_find WORD: Look for lines in this programs's -help output that match (approximately) WORD. -h_raw: Help string unedited -h_spx: Help string in sphinx loveliness, but do not try to autoformat -h_aspx: Help string in sphinx with autoformatting of options, etc. -all_opts: Try to identify all options for the program from the output of its -help option. Some options might be missed and others misidentified. Use this output for hints only. Compile Date: May 6 2025 Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov

AFNI program: 3dDeconvolve
++ 3dDeconvolve: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward, et al. ------------------------------------------------------------------------ ----- DESCRIPTION and PROLEGOMENON ----- ------------------------------------------------------------------------ Program to calculate the deconvolution of a measurement 3D+time dataset with a specified input stimulus time series. This program can also perform multiple linear regression using multiple input stimulus time series. Output consists of an AFNI 'bucket' type dataset containing (for each voxel) * the least squares estimates of the linear regression coefficients * t-statistics for significance of the coefficients * partial F-statistics for significance of individual input stimuli * the F-statistic for significance of the overall regression model The program can optionally output extra datasets containing * the estimated impulse response function * the fitted model and error (residual) time series ------------------------------------------------------------------------ * Program 3dDeconvolve does Ordinary Least Squares (OLSQ) regression. * Program 3dREMLfit can be used to do Generalized Least Squares (GLSQ) regression (AKA 'pre-whitened' least squares) combined with REML estimation of an ARMA(1,1) temporal correlation structure: https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dREMLfit.html * The input to 3dREMLfit is the .xmat.1D matrix file output by 3dDeconvolve, which also writes a 3dREMLfit command line to a file to make it relatively easy to use the latter program. * 3dREMLfit also allows for voxel-specific regressors, unlike 3dDeconvolve. This feature is used with the '-fanaticor' option to afni_proc.py, for example. * Nonlinear time series model fitting can be done with program 3dNLfim: https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dNLfim.html * Preprocessing of the time series input can be done with various AFNI programs, or with the 'uber-script' afni_proc.py: https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html ------------------------------------------------------------------------ ------------------------------------------------------------------------ **** The recommended way to use 3dDeconvolve is via afni_proc.py, **** **** which will pre-process the data, and also provide some useful **** **** diagnostic tools/outputs for assessing the data's quality. **** **** It can also run 3dREMLfit for you 'at no extra charge'. **** **** [However, it will not wax your car or wash your windows.] **** ------------------------------------------------------------------------ ------------------------------------------------------------------------ Consider the time series model Z(t) = K(t)*S(t) + baseline + noise, where Z(t) = data K(t) = kernel (e.g., hemodynamic response function or HRF) S(t) = stimulus time series baseline = constant, drift, etc. [regressors of no interest] and * = convolution Then 3dDeconvolve solves for K(t) given S(t). If you want to process the reverse problem and solve for S(t) given the kernel K(t), use the program 3dTfitter with the '-FALTUNG' option. The difference between the two cases is that K(t) is presumed to be causal and have limited support, whereas S(t) is a full-length time series. Note that program 3dTfitter does not have all the capabilities of 3dDeconvolve for calculating output statistics; on the other hand, 3dTfitter can solve a deconvolution problem (in either direction) with L1 or L2 regression, and with sign constraints on the computed values (e.g., requiring that the output S(t) or K(t) be non-negative): https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dTfitter.html ------------------------------------------------------------------------ The 'baseline model' in 3dDeconvolve (and 3dREMLfit) does not mean just a constant (mean) level of the signal, or even just the slow drifts that happen in FMRI time series. 'Baseline' here also means the model that forms the null hypothesis. The Full_Fstat result is the F-statistic of the full model (all regressors) vs. the baseline model. Thus, it it common to include irregular time series, such as estimated motion parameters, in the baseline model via the -stim_file/-stim_base options, or by using the -ortvec option (to include multiple regressors at once). Thus, the 'baseline model' is really the 'null hypothesis model'. ------------------------------------------------------------------------ It is VERY important to realize that statistics (F, t, R^2) computed in 3dDeconvolve are MARGINAL (or partial) statistics. For example, the t-statistic for a single beta coefficient measures the significance of that beta value against the regression model where ONLY that one column of the matrix is removed; that is, the null hypothesis for that t-statistic is the full regression model minus just that single regressor. Similarly, the F-statistic for a set of regressors measures the significance of that set of regressors (eg, a set of TENT functions) against the full model with just that set of regressors removed. If this explanation or its consequences are unclear, you need to consult with a statistician, or with the AFNI message board guru entities (when they can be lured down from the peak of Mt Taniquetil or Kailash). ------------------------------------------------------------------------ Regression Programs in the AFNI Package: * At its core, 3dDeconvolve solves a linear regression problem z = X b for the parameter vector b, given the data vector z in each voxel, and given the SAME matrix X in each voxel. The solution is calculated in the Ordinary Least Squares (OLSQ) sense. * Program 3dREMLfit does something similar, but allows for ARMA(1,1) serial correlation in the data, so the solution method is called Generalized Least Squares (GLSQ). * If you want to solve a problem where some of the matrix columns in X (the regressors) are different in different voxels (spatially variable), then use program 3dTfitter, which uses OLSQ, or used 3dREMLfit. * 3dTfitter can also use L1 and LASSO regression, instead of OLSQ; if you want to use such 'robust' fitting methods, this program is your friend. It can also impose sign constraints (positivity or negativity) on the parameters b, and can (as mentioned above) do deconvolution. * 3dBandpass and 3dTproject can do a sequence of 'time series cleanup' operations, including 'regressing out' (via OLSQ) a set of nuisance vectors (columns). * 3dLSS can be used to solve -stim_times_IM systems using an alternative linear technique that gives biased results, but with smaller variance. ------------------------------------------------------------------------ Usage Details: 3dDeconvolve command-line-arguments ... **** Input data and control options **** -input fname fname = filename of 3D+time input dataset [more than one filename can be given] [here, and these datasets will be] [auto-catenated in time; if you do this,] ['-concat' is not needed and is ignored.] **** 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. You can automatically transpose a 1D file on input using the \' operator at the end of the filename, as in -input fred.1D\' ** This is the only way to use 3dDeconvolve with a multi-column 1D time series file. * The output datasets by default will then be in 1D format themselves. To have them formatted as AFNI datasets instead, use -DAFNI_WRITE_1D_AS_PREFIX=YES on the command line. * You should use '-force_TR' to set the TR of the 1D 'dataset' if you use '-input' rather than '-input1D' [the default is 1.0 sec]. -sat OR -trans * 3dDeconvolve can check the dataset time series for initial saturation transients, which should normally have been excised before data analysis. (Or should be censored out: see '-censor' below.) If you want to have it do this somewhat time consuming check, use the option '-sat'. * Or set environment variable AFNI_SKIP_SATCHECK to NO. * Program 3dSatCheck does this check, also. [-noblock] Normally, if you input multiple datasets with '-input', then the separate datasets are taken to be separate image runs that get separate baseline models. If you want to have the program consider these to be all one big run, use -noblock. * If any of the input datasets 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. [-force_TR TR] Use this value of TR instead of the one in the -input dataset. (It's better to fix the input using 3drefit.) [-input1D dname] dname = filename of single (fMRI) .1D time series where time run downs the column. * If you want to analyze multiple columns from a .1D file, see the '-input' option above for the technique. [-TR_1D tr1d] tr1d = TR for .1D time series [default 1.0 sec]. This option has no effect without -input1D [-nodata [NT [TR]] Evaluate experimental design only (no input data) * Optional, but highly recommended: follow the '-nodata' with two numbers, NT=number of time points, and TR=time spacing between points (sec) [-mask mname] mname = 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. [-automask] Build a mask automatically from input data (will be slow for long time series datasets) ** If you don't specify ANY mask, the program will build one automatically (from each voxel's RMS) and use this mask solely for the purpose of reporting truncation-to-short errors (if '-short' is used) AND for computing the FDR curves in the bucket dataset's header (unless '-noFDR' is used, of course). * If you don't want the FDR curves to be computed inside this automatically generated mask, then use '-noFDR' and later run '3drefit -addFDR' on the bucket dataset. * To be precise, the above default masking only happens when you use '-input' to run the program with a 3D+time dataset; not with '-input1D'. [-STATmask sname] Build a mask from file 'sname', 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) * If you don't use '-STATmask', then the mask from '-mask' or '-automask' is used for these purposes. If neither of those is given, then the automatically generated mask described just above is used for these purposes. [-censor cname] cname = 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). * Option '-censor' can only be used once! * The option below may be simpler to use! [-CENSORTR clist] clist = 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). +Multiple -CENSORTR options may be used, or multiple -CENSORTR strings can be given at once, separated by spaces or commas. +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. [-concat rname] rname = filename for list of concatenated runs * 'rname' can be in the format '1D: 0 100 200 300' which indicates 4 runs, the first of which starts at time index=0, second at index=100, and so on. [-nfirst fnum] fnum = number of first dataset image to use in the deconvolution procedure. [default = max maxlag] [-nlast lnum] lnum = number of last dataset image to use in the deconvolution procedure. [default = last point] [-polort pnum] pnum = degree of polynomial corresponding to the null hypothesis [default: pnum = 1] ** For pnum > 2, this type of baseline detrending is roughly equivalent to a highpass filter with a cutoff of (p-2)/D Hz, where 'D' is the duration of the imaging run: D = N*TR ** If you use 'A' for pnum, the program will automatically choose a value based on the time duration D of the longest run: pnum = 1 + int(D/150) ==>>** 3dDeconvolve is the ONLY AFNI program with the -polort option that allows the use of 'A' to set the polynomial order automatically!!! ** Use '-1' for pnum to specifically NOT include any polynomials in the baseline model. Only do this if you know what this means! [-legendre] use Legendre polynomials for null hypothesis (baseline model) [-nolegendre] use power polynomials for null hypotheses [default is -legendre] ** Don't do this unless you are crazy! [-nodmbase] don't de-mean baseline time series (i.e., polort>0 and -stim_base inputs) [-dmbase] de-mean baseline time series [default if polort>=0] [-svd] Use SVD instead of Gaussian elimination [default] [-nosvd] Use Gaussian elimination instead of SVD (only use for testing + backwards compatibility) [-rmsmin r] r = minimum rms error to reject reduced model (default = 0; don't use this option normally!) [-nocond] DON'T calculate matrix condition number ** This value is NOT the same as Matlab! [-singvals] Print out the matrix singular values (useful for some testing/debugging purposes) Also see program 1dsvd. [-GOFORIT [g]] Use this to proceed even if the matrix has bad problems (e.g., duplicate columns, large condition number, etc.). *N.B.: Warnings that you should particularly heed have the string '!!' somewhere in their text. *N.B.: Error and Warning messages go to stderr and also to file 3dDeconvolve.err. ++ You can disable the creation of this .err file by setting environment variable AFNI_USE_ERROR_FILE to NO before running this program. *N.B.: The optional number 'g' that appears is the number of warnings that can be ignored. That is, if you use -GOFORIT 7 and 9 '!!' matrix warnings appear, then the program will not run. If 'g' is not present, 1 is used. [-allzero_OK] Don't consider all zero matrix columns to be the type of error that -GOFORIT is needed to ignore. * Please know what you are doing when you use this option! [-Dname=val] = Set environment variable 'name' to 'val' for this run of the program only. ******* Input stimulus options ******* -num_stimts num num = number of input stimulus time series (0 <= num) [default: num = 0] *N.B.: '-num_stimts' must come before any of the following '-stim' options! *N.B.: Most '-stim' options have as their first argument an integer 'k', ranging from 1..num, indicating which stimulus class the argument is defining. *N.B.: The purpose of requiring this option is to make sure your model is complete -- that is, you say you are giving 5 '-stim' options, and then the program makes sure that all of them are given -- that is, that you don't forget something. -stim_file k sname sname = filename of kth time series input stimulus *N.B.: This option directly inserts a column into the regression matrix; unless you are using the 'old' method of deconvolution (cf below), you would normally only use '-stim_file' to insert baseline model components such as motion parameters. [-stim_label k slabel] slabel = label for kth input stimulus *N.B.: This option is highly recommended, so that output sub-bricks will be labeled for ease of recognition when you view them in the AFNI GUI. [-stim_base k] kth input stimulus is part of the baseline model *N.B.: 'Baseline model' == Null Hypothesis model *N.B.: The most common baseline components to add are the 6 estimated motion parameters from 3dvolreg. -ortvec fff lll This option lets you input a rectangular array of 1 or more baseline vectors from file 'fff', which will get the label 'lll'. Functionally, it is the same as using '-stim_file' on each column of 'fff' separately (plus '-stim_base'). This method is just a faster and simpler way to include a lot of baseline regressors in one step. -->>**N.B.: This file is NOT included in the '-num_stimts' count that you provide. *N.B.: These regression matrix columns appear LAST in the matrix, after everything else. *N.B.: You can use column '[..]' and/or row '{..}' selectors on the filename 'fff' to pick out a subset of the numbers in that file. *N.B.: The q-th column of 'fff' will get a label like 'lll[q]' in the 3dDeconvolve results. *N.B.: This option is known as the 'Inati Option'. *N.B.: Unlike the original 'Inati' (who is unique), it is allowed to have more than one '-ortvec' option. *N.B.: Program 1dBport is one place to generate a file for use with '-ortvec'; 1deval might be another. **N.B.: You must have -num_stimts > 0 AND/OR You must use -ortvec AND/OR You must have -polort >= 0 Otherwise, there is no regression model! An example using -polort only: 3dDeconvolve -x1D_stop -polort A -nodata 300 2 -x1D stdout: | 1dplot -one -stdin **N.B.: The following 3 options are for the 'old' style of explicit deconvolution. For most purposes, their usage is no longer recommended. Instead, you should use the '-stim_times' options to directly input the stimulus times, rather than code the stimuli as a sequence of 0s and 1s in this 'old' method! [-stim_minlag k m] m = minimum time lag for kth input stimulus [default: m = 0] [-stim_maxlag k n] n = maximum time lag for kth input stimulus [default: n = 0] [-stim_nptr k p] p = number of stimulus function points per TR Note: This option requires 0 slice offset times [default: p = 1] **N.B.: The '-stim_times' options below are the recommended way of analyzing FMRI time series data now. The options directly above are only maintained for the sake of backwards compatibility! For most FMRI users, the 'BLOCK' and 'TENT' (or 'CSPLIN') response models will serve their needs. The other models are for users with specific needs who understand clearly what they are doing. [-stim_times k tname Rmodel] Generate the k-th response model from a set of stimulus times given in file 'tname'. *** The format of file 'tname' is one line per imaging run (cf. '-concat' above), and each line contains the list of START times (in seconds) for the stimuli in class 'k' for its corresponding run of data; times are relative to the start of the run (i.e., sub-brick #0 occurring at time=0). *** The DURATION of the stimulus is encoded in the 'Rmodel' argument, described below. Units are in seconds, not TRs! -- If different stimuli in the same class 'k' have different durations, you'll have to use the dmBLOCK response model and '-stim_times_AM1' or '-stim_times_AM2', described below. *** Different lines in the 'tname' file can contain different numbers of start times. Each line must contain at least 1 time. *** If there is no stimulus in class 'k' in a particular imaging run, there are two ways to indicate that: (a) put a single '*' on the line, or (b) put a very large number or a negative number (e.g., 99999, or -1) on the line -- times outside the range of the imaging run will cause a warning message, but the program will soldier on. *** In the case where the stimulus doesn't actually exist in the data model (e.g., every line in 'tname' is a '*'), you will also have to use the '-allzero_OK' option to force 3dDeconvolve to run with regressor matrix columns that are filled with zeros. The response model is specified by the third argument after '-stim_times' ('Rmodel'), and can be one of the following: *** In the descriptions below, a '1 parameter' model has a fixed shape, and only the estimated amplitude ('Coef') varies: BLOCK GAM TWOGAM SPMG1 WAV MION *** Models with more than 1 parameter have multiple basis functions, and the estimated parameters ('Coef') are their amplitudes. The estimated shape of the response to a stimulus will be different in different voxels: TENT CSPLIN SPMG2 SPMG3 POLY SIN EXPR *** Many models require the input of the start and stop times for the response, 'b' and 'c'. Normally, 'b' would be zero, but in some cases, 'b' could be negative -- for example, if you are concerned about anticipatory effects. The stop time 'c' should be based on how long you realistically expect the hemodynamic response to last after the onset of the stimulus; e.g., the duration of the stimulus plus 14 seconds for BOLD. *** If you use '-tout', each parameter will get a separate t-statistic. As mentioned far above, this is a marginal statistic, measuring the impact of that model component on the regression fit, relative to the fit with that one component (matrix column) removed. *** If you use '-fout', each stimulus will also get an F-statistic, which is the collective impact of all the model components it contains, relative to the regression fit with the entire stimulus removed. (If there is only 1 parameter, then F = t*t.) *** Some models below are described in terms of a simple response function that is then convolved with a square wave whose duration is a parameter you give (duration is NOT a parameter that will be estimated). Read the descriptions below carefully: not all functions are (or can be) convolved in this way: * ALWAYS convolved: BLOCK dmBLOCK MION MIONN * OPTIONALLY convolved: GAM TWOGAM SPMGx WAV * NEVER convolved: TENT CSPLIN POLY SIN EXPR Convolution is specified by providing the duration parameter as described below for each particular model function. 'BLOCK(d,p)' = 1 parameter block stimulus of duration 'd' ** There are 2 variants of BLOCK: BLOCK4 [the default] and BLOCK5 which have slightly different delays: HRF(t) = int( g(t-s) , s=0..min(t,d) ) where g(t) = t^q * exp(-t) /(q^q*exp(-q)) and q = 4 or 5. The case q=5 is delayed by about 1 second from the case q=4. ==> ** Despite the name, you can use 'BLOCK' for event- related analyses just by setting the duration to a small value; e.g., 'BLOCK5(1,1)' ** The 'p' parameter is the amplitude of the basis function, and should usually be set to 1. If 'p' is omitted, the amplitude will depend on the duration 'd', which is useful only in special circumstances!! ** For bad historical reasons, the peak amplitude 'BLOCK' without the 'p' parameter does not go to 1 as the duration 'd' gets large. Correcting this oversight would break some people's lives, so that's just the way it is. ** The 'UBLOCK' function (U for Unit) is the same as the 'BLOCK' function except that when the 'p' parameter is missing (or 0), the peak amplitude goes to 1 as the duration gets large. If p > 0, 'UBLOCK(d,p)' and 'BLOCK(d,p)' are identical. 'TENT(b,c,n)' = n parameter tent function expansion from times b..c after stimulus time [piecewise linear] [n must be at least 2; time step is (c-b)/(n-1)] 'CSPLIN(b,c,n)'= n parameter cubic spline function expansion from times b..c after stimulus time [n must be at least 4] ** CSPLIN is a drop-in upgrade of TENT to a differentiable set of functions. ** TENT and CSPLIN are 'cardinal' interpolation functions: their parameters are the values of the HRF model at the n 'knot' points b , b+dt , b+2*dt , ... [dt = (c-b)/(n-1)] In contrast, in a model such as POLY or SIN, the parameters output are not directly the hemodynamic response function values at any particular point. ==> ** You can also use 'TENTzero' and 'CSPLINzero', which means to eliminate the first and last basis functions from each set. The effect of these omissions is to force the deconvolved HRF to be zero at t=b and t=c (to start and and end at zero response). With these 'zero' response models, there are n-2 parameters (thus for 'TENTzero', n must be at least 3). ** These 'zero' functions will force the HRF to be continuous, since they will now be unable to suddenly rise up from 0 at t=b and/or drop down to 0 at t=c. 'GAM(p,q)' = 1 parameter gamma variate (t/(p*q))^p * exp(p-t/q) Defaults: p=8.6 q=0.547 if only 'GAM' is used ** The peak of 'GAM(p,q)' is at time p*q after the stimulus. The FWHM is about 2.35*sqrt(p)*q; this approximation is accurate for p > 0.3*q. ** To check this approximation, try the command 1deval -num 100 -del 0.02 -xzero 0.02 \ -expr 'sqrt(gamp(x,1))/2.35/x' | \ 1dplot -stdin -del 0.02 -xzero 0.02 -yaxis 1:1.4:4:10 If the two functions gamp(x,1) and 2.35*x were equal, the plot would be constant y=1. ==> ** If you add a third argument 'd', then the GAM function is convolved with a square wave of duration 'd' seconds; for example: 'GAM(8.6,.547,17)' for a 17 second stimulus. [09 Aug 2010] 'GAMpw(K,W)' = Same as 'GAM(p,q)' but where the shape parameters are specified at time to peak 'K' and full width at half max (FWHM) 'W'. You can also add a third argument as the duration. The (K,W) parameters are converted to (p,q) values for the actual computations; the (p,q) parameters are printed to the text (stderr) output. ** Note that if you give weird values for K and W, weird things will happen: (tcsh syntax) set pp = `ccalc 'gamp(2,8)'` set qq = `ccalc 'gamq(2,8)'` 1deval -p=$pp -q=$qq -num 200 -del 0.1 \ -expr '(t/p/q)^p*exp(p-t/q)' | \ 1dplot -stdin -del 0.1 Here, K is significantly smaller than W, so a gamma variate that fits peak=2 width=8 must be weirdly shaped. [Also note use of the 'calc' functions gamp(K,W) and gamq(K,W) to calculate p and q from K and W in the script.] 'TWOGAM(p1,q1,r,p2,q2)' = 1 parameter (amplitude) model: = A combination of two 'GAM' functions: GAM(p1,q1) - r*GAM(p2,q2) This model is intended to let you use a HRF similar to BrainVoyager (e.g.). You can add a sixth argument as the duration. ** Note that a positive 'r' parameter means to subtract the second GAM function (undershoot). 'TWOGAMpw(K1,W1,r,K2,W2)' = Same as above, but where the peaks and widths of the 2 component gamma variates are given instead of the less intuitive p and q. For FMRI work, K2 > K1 is usual, as the second (subtracted) function is intended to model the 'undershoot' after the main positive part of the model. You can also add a sixth argument as the duration. ** Example (no duration given): 3dDeconvolve -num_stimts 1 -polort -1 -nodata 81 0.5 \ -stim_times 1 '1D: 0' 'TWOGAMpw(3,6,0.2,10,12)' \ -x1D stdout: | 1dplot -stdin -THICK -del 0.5 'SPMG1' = 1 parameter SPM gamma variate basis function exp(-t)*(A1*t^P1-A2*t^P2) where A1 = 0.0083333333 P1 = 5 (main positive lobe) A2 = 1.274527e-13 P2 = 15 (undershoot part) This function is NOT normalized to have peak=1! 'SPMG2' = 2 parameter SPM: gamma variate + d/dt derivative [For backward compatibility: 'SPMG' == 'SPMG2'] 'SPMG3' = 3 parameter SPM basis function set ==> ** The SPMGx functions now can take an optional (duration) argument, specifying that the primal SPM basis functions should be convolved with a square wave 'duration' seconds long and then be normalized to have peak absolute value = 1; e.g., 'SPMG3(20)' for a 20 second duration with three basis function. [28 Apr 2009] ** Note that 'SPMG1(0)' will produce the usual 'SPMG1' wavefunction shape, but normalized to have peak value = 1 (for example). 'POLY(b,c,n)' = n parameter Legendre polynomial expansion from times b..c after stimulus time [n can range from 1 (constant) to 20] 'SIN(b,c,n)' = n parameter sine series expansion from times b..c after stimulus time [n must be at least 1] 'WAV(d)' = 1 parameter block stimulus of duration 'd'. * This is the '-WAV' function from program waver! * If you wish to set the shape parameters of the WAV function, you can do that by adding extra arguments, in the order delay time , rise time , fall time , undershoot fraction, undershoot restore time * The default values are 'WAV(d,2,4,6,0.2,2)' * Omitted parameters get the default values. * 'WAV(d,,,,0)' (setting undershoot=0) is very similar to 'BLOCK5(d,1)', for d > 0. * Setting duration d to 0 (or just using 'WAV') gives the pure '-WAV' impulse response function from waver. * If d > 0, the WAV(0) function is convolved with a square wave of duration d to make the HRF, and the amplitude is scaled back down to 1. 'EXPR(b,c) exp1 ... expn' = n parameter; arbitrary expressions from times b..c after stimulus time * Expressions are separated by spaces, so each expression must be a contiguous block of non-whitespace characters * The entire model, from 'EXPR' to the final expression must be enclosed in one set of quotes. The individual component expressions are separated by blanks. Example: '-EXPR(0,20) sin(PI*t/20)^2' * Expressions use the same format as 3dcalc * Symbols that can be used in an expression: t = time in sec since stimulus time x = time scaled to be x= 0..1 for t=bot..top z = time scaled to be z=-1..1 for t=bot..top * Spatially dependent regressors are not allowed! * Other symbols are set to 0 (silently). ==> ** There is no convolution of the 'EXPR' functions with a square wave implied. The expressions you input are what you get, evaluated over times b..c after each stimulus time. To be sure of what your response model is, you should plot the relevant columns from the matrix .xmat.1D output file. 'MION(d)' = 1 parameter block stimulus of duration 'd', intended to model the response of MION. The zero-duration impulse response 'MION(0)' is h(t) = 16.4486 * ( -0.184/ 1.5 * exp(-t/ 1.5) +0.330/ 4.5 * exp(-t/ 4.5) +0.670/13.5 * exp(-t/13.5) ) which is adapted from the paper FP Leite, et al. NeuroImage 16:283-294 (2002) http://dx.doi.org/10.1006/nimg.2002.1110 ** Note that this is a positive function, but MION produces a negative response to activation, so the beta and t-statistic for MION are usually negative. ***** If you want a negative MION function (so you get a positive beta), use the name 'MIONN' instead. ** After convolution with a square wave 'd' seconds long, the resulting single-trial waveform is scaled to have magnitude 1. For example, try this fun command to compare BLOCK and MION: 3dDeconvolve -nodata 300 1 -polort -1 -num_stimts 2 \ -stim_times 1 '1D: 10 150' 'MION(70)' \ -stim_times 2 '1D: 10 150' 'BLOCK(70,1)' \ -x1D stdout: | 1dplot -stdin -one -thick You will see that the MION curve rises and falls much more slowly than the BLOCK curve. ==> ** Note that 'MION(d)' is already convolved with a square wave of duration 'd' seconds. Do not convolve it again by putting in multiple closely spaced stimulus times (this mistake has been made)! ** Scaling the single-trial waveform to have magnitude 1 means that trials with different durations 'd' will have the same magnitude for their regression models. * 3dDeconvolve does LINEAR regression, so the model parameters are amplitudes of the basis functions; 1 parameter models are 'simple' regression, where the shape of the impulse response function is fixed and only the magnitude/amplitude varies. Models with more free parameters have 'variable' shape impulse response functions. * LINEAR regression means that each data time series (thought of as a single column of numbers = a vector) is fitted to a sum of the matrix columns, each one multiplied by an amplitude parameter to be calculated ('Coef'). The purpose of the various options '-stim_times', '-polort', '-ortvec', and/or '-stim_file' is to build the columns of the regression matrix. * If you want NONLINEAR regression, see program 3dNLfim. * If you want LINEAR regression with allowance for non-white noise, use program 3dREMLfit, after using 3dDeconvolve to set up the regression model (in the form of a matrix file). ** When in any doubt about the shape of the response model you are ** * asking for, you should plot the relevant columns from the X matrix * * to help develop some understanding of the analysis. The 'MION' * * example above can be used as a starting point for how to easily * * setup a quick command pipeline to graph response models. In that * * example, '-polort -1' is used to suppress the usual baseline model * * since graphing that part of the matrix would just be confusing. * * Another example, for example, comparing the similar models * ** 'WAV(10)', 'BLOCK4(10,1)', and 'SPMG1(10)': ** 3dDeconvolve -nodata 100 1.0 -num_stimts 3 -polort -1 \ -local_times -x1D stdout: \ -stim_times 1 '1D: 10 60' 'WAV(10)' \ -stim_times 2 '1D: 10 60' 'BLOCK4(10,1)' \ -stim_times 3 '1D: 10 60' 'SPMG1(10)' \ | 1dplot -thick -one -stdin -xlabel Time -ynames WAV BLOCK4 SPMG1 * For the format of the 'tname' file, see the last part of https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html and also see the other documents stored in the directory below: https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/ and also read the presentation below: https://afni.nimh.nih.gov/pub/dist/edu/latest/afni_handouts/afni05_regression.pdf ** Note Well: * The contents of the 'tname' file are NOT just 0s and 1s, but are the actual times of the stimulus events IN SECONDS. * You can give the times on the command line by using a string of the form '1D: 3.2 7.9 | 8.2 16.2 23.7' in place of 'tname', where the '|' character indicates the start of a new line (so this example is for a case with 2 catenated runs). => * You CANNOT USE the '1D:' form of input for any of the more complicated '-stim_times_*' options below!! * The '1D:' form of input is mostly useful for quick tests, as in the examples above, rather than for production analyses with lots of different stimulus times and multiple imaging runs. [-stim_times_AM1 k tname Rmodel] Similar, but generates an amplitude modulated response model. The 'tname' file should consist of 'time*amplitude' pairs. As in '-stim_times', the '*' character can be used as a placeholder when an imaging run doesn't have any stimulus of a given class. *N.B.: What I call 'amplitude' modulation is called 'parametric' modulation in Some other PrograM. ***N.B.: If NO run at all has a stimulus of a given class, then you must have at least 1 time that is not '*' for -stim_times_* to work (so that the proper number of regressors can be set up). You can use a negative time for this purpose, which will produce a warning message but otherwise will be ignored, as in: -1*37 * for a 2 run 'tname' file to be used with -stim_times_*. ** In such a case, you will also need the -allzero_OK option, and probably -GOFORIT as well. ** It is possible to combine '-stim_times_AM1' with the Rmodel being TENT. If you have an amplitude parameter at each TR, and you want to try to deconvolve its impact on the data, you can try the following: a) create a 1D column file with the amplitude parameter, one value per TR, matching the length of the data; say this file is called Akk.1D b) create a 1D column file with the actual TR time in each row; for example, if you have 150 time points and TR=2 s, then 1deval -num 150 -expr '2*i' > Att.1D c) glue these files together for use with -stim_times_AM1: echo `1dMarry Att.1D Akk.1D` > Atk.1D d) Use option -stim_times 1 Atk.1D 'TENT(0,20,11)' -stim_label 1 TENT which gives a TENT response lasting 20s with 11 parameters -- one every TR. e) Use all the other clever options you need in 3dDeconvolve, such as censoring, baseline, motion parameters, .... Variations on the options chosen here can be made to constrain the deconvolution; e.g., use CSPLIN vs. TENT, or CSPLINzero; use fewer parameters in the TENT/CSPLIN to force a smoother deconvolution, etc. Graphing the regression matrix is useful in this type of analysis, to be sure you are getting the analysis you want; for example: 1dplot -sep_scl prefix.xmat.1D [-stim_times_AM2 k tname Rmodel] Similar, but generates 2 response models: one with the mean amplitude and one with the differences from the mean. *** Please note that 'AM2' is the option you should probably use! *** 'AM1' is for special cases, and normally should not be used for FMRI task activation analyses!! *** 'AM2' will give you the ability to detect voxels that activate but do not change proportional to the amplitude factor, as well as provide a direct measure of the proportionality of the activation to changes in the input amplitude factors. 'AM1' will do neither of these things. *** Normally, 3dDeconvolve removes the mean of the auxiliary parameter(s) from the modulated regressor(s). However, if you set environment variable AFNI_3dDeconvolve_rawAM2 to YES, then the mean will NOT be removed from the auxiliary parameter(s). This ability is provided for users who want to center their parameters using their own method. *** [12 Jul 2012] You can now specify the value to subtract from each modulation parameter -- this value will replace the subtraction of the average parameter value that usually happens. To do this, add an extra parameter after the option, as in -stim_times_AM2 1 timesAM.1D 'BLOCK(2,1)' :5.2:x:2.0 The extra argument must start with the colon ':' character, and there should be as many different values (separated by ':') as there are parameters in the timing file (timesAM.1D above). ==> In the example above, ':5.2:x:2.0' means subtract 5.2 from each value of the first parameter in timesAM.1D subtract the MEAN from each value of the second parameter (since 'x' doesn't translate to a number) subtract 2.0 from each value of the third parameter ==> What is this option for, anyway? The purpose is to facilitate GROUP analysis the results from a collection of subjects, where you want to treat each subject's analysis exactly the same way -- and thus, the subtraction value for a parameter (e.g., reaction time) should then be the mean over all the reaction times from all trials in all subjects. ** NOTE [04 Dec 2008] ** -stim_times_AM1 and -stim_times_AM2 now take files with more than 1 amplitude attached to each time; for example, 33.7*9,-2,3 indicates a stimulus at time 33.7 seconds with 3 amplitudes attached (9 and -2 and 3). In this example, -stim_times_AM2 would generate 4 response models: 1 for the constant response case and 1 scaled by each of the amplitude sets. ** Please don't carried away and use too many parameters!! ** For more information on modulated regression, see https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/AMregression.pdf ** NOTE [08 Dec 2008] ** -stim_times_AM1 and -stim_times_AM2 now have 1 extra response model function available: dmBLOCK (or dmBLOCK4 or dmBLOCK5) where 'dm' means 'duration modulated'. If you use this response model, then the LAST married parameter in the timing file will be used to modulate the duration of the block stimulus. Any earlier parameters will be used to modulate the amplitude, and should be separated from the duration parameter by a ':' character, as in '30*5,3:12' which means (for dmBLOCK): a block starting at 30 s, with amplitude modulation parameters 5 and 3, and with duration 12 s. The unmodulated peak response of dmBLOCK depends on the duration of the stimulus, as the BOLD response accumulates. If you want the peak response to be a set to a fixed value, use dmBLOCK(p) where p = the desired peak value (e.g., 1). *** Understand what you doing when you use dmBLOCK, and look at *** *** the regression matrix! Otherwise, you will end up confused. *** *N.B.: The maximum allowed dmBLOCK duration is 999 s. *N.B.: You cannot use '-iresp' or '-sresp' with dmBLOCK! *N.B.: If you are NOT doing amplitude modulation at the same time (and so you only have 1 'married' parameter per time), use '-stim_times_AM1' with dmBLOCK. If you also want to do amplitude modulation at the same time as duration modulation (and so you have 2 or more parameters with each time), use '-stim_times_AM2' instead. If you use '-stim_times_AM2' and there is only 1 'married' parameter, the program will print a warning message, then convert to '-stim_times_AM1', and continue -- so nothing bad will happen to your analysis! (But you will be embarrassed in front of your friends.) *N.B.: If you are using AM2 (amplitude modulation) with dmBLOCK, you might want to use 'dmBLOCK(1)' to make each block have native amplitude 1 before it is scaled by the amplitude parameter. Or maybe not -- this is a matter for fine judgment. *N.B.: You can also use dmBLOCK with -stim_times_IM, in which case each time in the 'tname' file should have just ONE extra parameter -- the duration -- married to it, as in '30:15', meaning a block of duration 15 seconds starting at t=30 s. *N.B.: For bad historical reasons, the peak amplitude dmBLOCK without the 'p' parameter does not go to 1 as the duration gets large. Correcting this oversight would break some people's lives, so that's just the way it is. *N.B.: The 'dmUBLOCK' function (U for Unit) is the same as the 'dmBLOCK' function except that when the 'p' parameter is missing (or 0), the peak amplitude goes to 1 as the duration gets large. If p > 0, 'dmUBLOCK(p)' and 'dmBLOCK(p)' are identical For some graphs of what dmBLOCK regressors look like, see https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/AMregression.pdf and/or try the following command: 3dDeconvolve -nodata 350 1 -polort -1 -num_stimts 1 \ -stim_times_AM1 1 q.1D 'dmBLOCK' \ -x1D stdout: | 1dplot -stdin -thick -thick where file q.1D contains the single line 10:1 40:2 70:3 100:4 130:5 160:6 190:7 220:8 250:9 280:30 Change 'dmBLOCK' to 'dmBLOCK(1)' and see how the matrix plot changes. **************** Further notes on dmBLOCK [Nov 2013] **************** Basically (IMHO), there are 2 rational choices to use: (a) 'dmUBLOCK' = allow the amplitude of the response model to vary with the duration of the stimulus; getting larger with larger durations; for durations longer than about 15s, the amplitude will become 1. -->> This choice is equivalent to 'dmUBLOCK(0)', but is NOT equivalent to 'dmBLOCK(0)' due to the historical scaling issue alluded to above. (b) 'dmUBLOCK(1)' = all response models will get amplitude 1, no matter what the duration of the stimulus. -->> This choice is equivalent to 'dmBLOCK(1)'. Some users have expressed the desire to allow the amplitude to vary with duration, as in case (a), BUT to specify the duration at which the amplitude goes to 1. This desideratum has now been implemented, and provides the case below: (a1) 'dmUBLOCK(-X)' = set the amplitude to be 1 for a duration of 'X' seconds; e.g., 'dmBLOCK(-5)' means that a stimulus with duration 5 gets amplitude 1, shorter durations get amplitudes smaller than 1, and longer durations get amplitudes larger than 1. -->> Please note that 'dmBLOCK(-X)' is NOT the same as this case (a1), and in fact it has no meaning. I hope this clarifies things and makes your life simpler, happier, and more carefree. (If not, please blame Gang Chen, not me.) An example to clarify the difference between these cases: 3dDeconvolve -nodata 350 1 -polort -1 -num_stimts 3 \ -stim_times_AM1 1 q.1D 'dmUBLOCK' \ -stim_times_AM1 2 q.1D 'dmUBLOCK(1)' \ -stim_times_AM1 3 q.1D 'dmUBLOCK(-4)' \ -x1D stdout: | \ 1dplot -stdin -thick \ -ynames 'dmUBLOCK' 'dmUB(1)' 'dmUB(-4)' where file q.1D contains the single line 10:1 60:2 110:4 160:10 210:20 260:30 Note how the 'dmUBLOCK(-4)' curve (green) peaks at 1 for the 3rd stimulus, and peaks at larger values for the later (longer) blocks. Whereas the 'dmUBLOCK' curve (black) peaks at 1 at only the longest blocks, and the 'dmUBLOCK(1)' curve (red) peaks at 1 for ALL blocks. ********************************************************************* [-stim_times_FSL k tname Rmodel] This option allows you to input FSL-style 3-column timing files, where each line corresponds to one stimulus event/block; the line '40 20 1' means 'stimulus starts at 40 seconds, lasts for 20 seconds, and is given amplitude 1'. Since in this format, each stimulus can have a different duration and get a different response amplitude, the 'Rmodel' must be one of the 'dm' duration-modulated options above ['dmUBLOCK(1)' is probably the most useful]. The amplitude modulation is taken to be like '-stim_times_AM1', where the given amplitude in the 'tname' file multiplies the basic response shape. *** We DO NOT advocate the use of this '_FSL' option, but it's here to make some scripting easier for some (unfortunate) people. *** The results of 3dDeconvolve (or 3dREMLfit) cannot be expected to be exactly the same as FSL FEAT, since the response model shapes are different, among myriad other details. *** You can also use '-stim_times_FS1' to indicate that the amplitude factor in the 'tname' file should be ignored and replaced with '1' in all cases. *** FSL FEAT only analyzes contiguous time series -- nothing like '-concat' allowing for multiple EPI runs is possible in FSL (AFAIK). So the FSL stimulus time format doesn't allow for this possibility. In 3dDeconvolve, you can get around this problem by using a line consisting of '* * *' to indicate the break between runs, as in the example below: 1 2 3 4 5 6 * * * 7 8 9 that indicates 2 runs, the first of which has 2 stimuli and the second of which has just 1 stimulus. If there is a run that has NO copies of this type of stimulus, then you would use two '* * *' lines in succession. Of course, a file using the '* * *' construction will NOT be compatible with FSL! [-stim_times_IM k tname Rmodel] Similar, but each separate time in 'tname' will get a separate regressor; 'IM' means 'Individually Modulated' -- that is, each event will get its own amplitude estimated. Presumably you will collect these many amplitudes afterwards and do some sort of statistics or analysis on them. *N.B.: Each time in the 'tname' file will get a separate regressor. If some time is outside the duration of the imaging run(s), or if the response model for that time happens to hit only censored-out data values, then the corresponding regressor will be all zeros. Normally, 3dDeconvolve will not run if the matrix has any all zero columns. To carry out the analysis, use the '-allzero_OK' option. Amplitude estimates for all zero columns will be zero, and should be excluded from any subsequent analysis. (Probably you should fix the times in the 'tname' file instead of using '-allzero_OK'.) [-global_times] [-local_times] By default, 3dDeconvolve guesses whether the times in the 'tname' files for the various '-stim_times' options are global times (relative to the start of run #1) or local times (relative to the start of each run). With one of these options, you can force the times to be considered as global or local for '-stim_times' options that are AFTER the '-local_times' or '-global_times'. ** Using one of these options (most commonly, '-local_times') is VERY highly recommended. [-stim_times_millisec] This option scales all the times in any '-stim_times_*' option by 0.001; the purpose is to allow you to input the times in ms instead of in s. This factor will be applied to ALL '-stim_times' inputs, before or after this option on the command line. This factor will be applied before -stim_times_subtract, so the subtraction value (if present) must be given in seconds, NOT milliseconds! [-stim_times_subtract SS] This option means to subtract 'SS' 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. Note that this option will be useful only if both of the following are true: (a) each imaging run has exactly the same number of images removed (b) the times in the 'tname' files were not already adjusted for these image removal (i.e., the times refer to the image runs as acquired, not as input to 3dDeconvolve). In other words, use this option with understanding and care! ** Note that the subtraction of 'SS' applies to ALL '-stim_times' inputs, before or after this option on the command line! ** And it applies to global times and local times alike! ** Any time (thus subtracted) below 0 will be ignored, as falling before the start of the imaging run. ** This option, and the previous one, are simply for convenience, to help you in setting up your '-stim_times*' timing files from whatever source you get them. [-basis_normall a] Normalize all basis functions for '-stim_times' to have amplitude 'a' (must have a > 0). The peak absolute value of each basis function will be scaled to be 'a'. NOTES: * -basis_normall only affect -stim_times options that appear LATER on the command line * The main use for this option is for use with the 'EXPR' basis functions. ******* General linear test (GLT) options ******* -num_glt num num = number of general linear tests (GLTs) (0 <= num) [default: num = 0] **N.B.: You only need this option if you have more than 10 GLTs specified; the program has built-in space for 10 GLTs, and this option is used to expand that space. If you use this option, you should place it on the command line BEFORE any of the other GLT options. [-glt s gltname] Perform s simultaneous linear tests, as specified by the matrix contained in file 'gltname' [-glt_label k glabel] glabel = label for kth general linear test [-gltsym gltname] Read the GLT with symbolic names from the file 'gltname'; see the document below for details: https://afni.nimh.nih.gov/pub/dist/doc/misc/Decon/DeconSummer2004.html ******* Options to create 3D+time datasets ******* [-iresp k iprefix] iprefix = prefix of 3D+time output dataset which will contain the kth estimated impulse response [-tshift] Use cubic spline interpolation to time shift the estimated impulse response function, in order to correct for differences in slice acquisition times. Note that this effects only the 3D+time output dataset generated by the -iresp option. **N.B.: This option only applies to the 'old' style of deconvolution analysis. Do not use this with -stim_times analyses! [-sresp k sprefix] sprefix = prefix of 3D+time output dataset which will contain the standard deviations of the kth impulse response function parameters [-fitts fprefix] fprefix = prefix of 3D+time output dataset which will contain the (full model) time series fit to the input data [-errts eprefix] eprefix = prefix of 3D+time output dataset which will contain the residual error time series from the full model fit to the input data [-TR_times dt] Use 'dt' as the stepsize for output of -iresp and -sresp file for response models generated by '-stim_times' options. Default is same as time spacing in the '-input' 3D+time dataset. The units here are in seconds! **** Options to control the contents of the output bucket dataset **** [-fout] Flag to output the F-statistics for each stimulus ** F tests the null hypothesis that each and every beta coefficient in the stimulus set is zero ** If there is only 1 stimulus class, then its '-fout' value is redundant with the Full_Fstat computed for all stimulus coefficients together. [-rout] Flag to output the R^2 statistics [-tout] Flag to output the t-statistics ** t tests a single beta coefficient against zero ** If a stimulus class has only one regressor, then F = t^2 and the F statistic is redundant with t. [-vout] Flag to output the sample variance (MSE) map [-nobout] Flag to suppress output of baseline coefficients (and associated statistics) [** DEFAULT **] [-bout] Flag to turn on output of baseline coefs and stats. ** Will make the output dataset larger. [-nocout] Flag to suppress output of regression coefficients (and associated statistics) ** Useful if you just want GLT results. [-full_first] Flag to specify that the full model statistics will be first in the bucket dataset [** DEFAULT **] [-nofull_first] Flag to specify that full model statistics go last [-nofullf_atall] Flag to turn off the full model F statistic ** DEFAULT: the full F is always computed, even if sub-model partial F's are not ordered with -fout. [-bucket bprefix] Create one AFNI 'bucket' dataset containing various parameters of interest, such as the estimated IRF coefficients, and full model fit statistics. Output 'bucket' dataset is written to bprefix. [-nobucket] Don't output a bucket dataset. By default, the program uses '-bucket Decon' if you don't give either -bucket or -nobucket on the command line. [-noFDR] Don't compute the statistic-vs-FDR curves for the bucket dataset. [same as 'setenv AFNI_AUTOMATIC_FDR NO'] [-xsave] Flag to save X matrix into file bprefix.xsave (only works if -bucket option is also given) [-noxsave] Don't save X matrix [this is the default] [-cbucket cprefix] Save the regression coefficients (no statistics) into a dataset named 'cprefix'. This dataset will be used in a -xrestore run instead of the bucket dataset, if possible. ** Also, the -cbucket and -x1D output can be combined in 3dSynthesize to produce 3D+time datasets that are derived from subsets of the regression model [generalizing the -fitts option, which produces] [a 3D+time dataset derived from the full model]. [-xrestore f.xsave] Restore the X matrix, etc. from a previous run that was saved into file 'f.xsave'. You can then carry out new -glt tests. When -xrestore is used, most other command line options are ignored. [-float] Write output datasets in float format, instead of as scaled shorts [** now the default **] [-short] Write output as scaled shorts [no longer default] ***** The following options control miscellaneous outputs ***** [-quiet] Flag to suppress most screen output [-xout] Flag to write X and inv(X'X) matrices to screen [-xjpeg filename] Write a JPEG file graphing the X matrix * If filename ends in '.png', a PNG file is output [-x1D filename] Save X matrix to a .xmat.1D (ASCII) file [default] ** If 'filename' is 'stdout:', the file is written to standard output, and could be piped into 1dplot (some examples are given earlier). * This can be used for quick checks to see if your inputs are setting up a 'reasonable' matrix. [-nox1D] Don't save X matrix [a very bad idea] [-x1D_uncensored ff] Save X matrix to a .xmat.1D file, but WITHOUT ANY CENSORING. Might be useful in 3dSynthesize. [-x1D_regcensored f] Save X matrix to a .xmat.1D file with the censoring imposed by adding 0-1 columns instead excising the censored rows. [-x1D_stop] Stop running after writing .xmat.1D files. * Useful for testing, or if you are going to run 3dREMLfit instead -- that is, you are just using 3dDeconvolve to set up the matrix file. [-progress n] Write statistical results for every nth voxel * To let you know that something is happening! [-fdisp fval] Write statistical results to the screen, for those voxels whose full model F-statistic is > fval [-help] Oh go ahead, try it! **** Multiple CPU option (local CPUs only, no networking) **** -jobs J Run the program with 'J' jobs (sub-processes). On a multi-CPU machine, this can speed the program up considerably. On a single CPU machine, using this option would be silly. * J should be a number from 1 up to the number of CPUs sharing memory on the system. * J=1 is normal (single process) operation. * The maximum allowed value of J is 32. * Unlike other parallelized AFNI programs, this one does not use OpenMP; it directly uses fork() and shared memory to run multiple processes. * For more information on parallelizing, see https://afni.nimh.nih.gov/afni/doc/misc/afni_parallelize * Also use -mask or -automask to get more speed; cf. 3dAutomask. -virtvec To save memory, write the input dataset to a temporary file and then read data vectors from it only as needed. This option is for Javier and will probably not be useful for anyone else. And it only takes effect if -jobs is greater than 1. ** NOTE ** This version of the program has been compiled to use double precision arithmetic for most internal calculations. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dDegreeCentrality
Usage: 3dDegreeCentrality [options] dset Computes voxelwise weighted and binary degree centrality and stores the result in a new 3D bucket dataset as floats to preserve their values. Degree centrality reflects the strength and extent of the correlation of a voxel with every other voxel in the brain. Conceptually the process involves: 1. Calculating the correlation between voxel time series for every pair of voxels in the brain (as determined by masking) 2. Applying a threshold to the resulting correlations to exclude those that might have arisen by chance, or to sparsify the connectivity graph. 3. At each voxel, summarizing its correlation with other voxels in the brain, by either counting the number of voxels correlated with the seed voxel (binary) or by summing the correlation coefficients (weighted). Practically the algorithm is ordered differently to optimize for computational time and memory usage. The threshold can be supplied as a correlation coefficient, or a sparsity threshold. The sparsity threshold reflects the fraction of connections that should be retained after the threshold has been applied. To minimize resource consumption, using a sparsity threshold involves a two-step procedure. In the first step, a correlation coefficient threshold is applied to substantially reduce the number of correlations. Next, the remaining correlations are sorted and a threshold is calculated so that only the specified fraction of possible correlations are above threshold. Due to ties between correlations, the fraction of correlations that pass the sparsity threshold might be slightly more than the number specified. Regardless of the thresholding procedure employed, negative correlations are excluded from the calculations. Options: -pearson = Correlation is the normal Pearson (product moment) correlation coefficient [default]. -spearman AND -quadrant are disabled at this time :-( -thresh r = exclude correlations <= r from calculations -sparsity s = only use top s percent of correlations in calculations s should be an integer between 0 and 100. Uses an an adaptive thresholding procedure to reduce memory. The speed of determining the adaptive threshold can be improved by specifying an initial threshold with the -thresh flag. -polort m = Remove polynomial trend of order 'm', for m=-1..3. [default is m=1; removal is by least squares]. Using m=-1 means no detrending; this is only useful for data/information that has been pre-processed. -autoclip = Clip off low-intensity regions in the dataset, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The mask is determined the same way that 3dAutomask works. -mask mmm = Mask to define 'in-brain' voxels. Reducing the number the number of voxels included in the calculation will significantly speedup the calculation. Consider using a mask to constrain the calculations to the grey matter rather than the whole brain. This is also preferable to using -autoclip or -automask. -prefix p = Save output into dataset with prefix 'p', this file will contain bricks for both 'weighted' or 'degree' centrality [default prefix is 'deg_centrality']. -out1D f = Save information about the above threshold correlations to 1D file 'f'. Each row of this file will contain: Voxel1 Voxel2 i1 j1 k1 i2 j2 k2 Corr Where voxel1 and voxel2 are the 1D indices of the pair of voxels, i j k correspond to their 3D coordinates, and Corr is the value of the correlation between the voxel time courses. Notes: * The output dataset is a bucket type of floats. * The program prints out an estimate of its memory used when it ends. It also prints out a progress 'meter' to keep you pacified. -- RWCox - 31 Jan 2002 and 16 Jul 2010 -- Cameron Craddock - 26 Sept 2015 ========================================================================= * This binary version of 3dDegreeCentrality is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3ddelay
++ 3ddelay: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: Ziad Saad (with help from B Douglas Ward) The program estimates the time delay between each voxel time series in a 3D+time dataset and a reference time series[1][2]. The estimated delays are relative to the reference time series. For example, a delay of 4 seconds means that the voxel time series is delayed by 4 seconds with respect to the reference time series. Usage: 3ddelay -input fname fname = filename of input 3d+time dataset DO NOT USE CATENATED timeseries! Time axis is assumed to be continuous and not evil. -ideal_file rname rname = input ideal time series file name The length of the reference time series should be equal to that of the 3d+time data set. The reference time series vector is stored in an ascii file. The programs assumes that there is one value per line and that all values in the file are part of the reference vector. PS: Unlike with 3dfim, and FIM in AFNI, values over 33333 are treated as part of the time series. -fs fs Sampling frequency in Hz. of data time series (1/TR). -T Tstim Stimulus period in seconds. If the stimulus is not periodic, you can set Tstim to 0. [-prefix bucket] The prefix for the results Brick. The first subbrick is for Delay. The second subbrick is for Covariance, which is an estimate of the power in voxel time series at the frequencies present in the reference time series. The third subbrick is for the Cross Correlation Coefficients between FMRI time series and reference time series. The fourth subbrick contains estimates of the Variance of voxel time series. The default prefix is the prefix of the input dset with a '.DEL' extension appended to it. [-polort order] Detrend input time series with polynomial of order 'order'. If you use -1 for order then the program will suggest an order for you (about 1 for each 150 seconds) The minimum recommended is 1. The default is -1 for auto selection. This is the same as option Nort in the plugin version. [-nodtrnd] Equivalent to polort 0, whereby only the mean is removed. NOTE: Regardless of these detrending options, No detrending is done to the reference time series. [-uS/-uD/-uR] Units for delay estimates. (Seconds/Degrees/Radians) You can't use Degrees or Radians as units unless you specify a value for Tstim > 0. [-phzwrp] Delay (or phase) wrap. This switch maps delays from: (Seconds) 0->T/2 to 0->T/2 and T/2->T to -T/2->0 (Degrees) 0->180 to 0->180 and 180->360 to -180->0 (Radians) 0->pi to 0->pi and pi->2pi to -pi->0 You can't use this option unless you specify a value for Tstim > 0. [-nophzwrp] Do not wrap phase (default). [-phzreverse] Reverse phase such that phase -> (T-phase) [-phzscale SC] Scale phase: phase -> phase*SC (default no scaling) [-bias] Do not correct for the bias in the estimates [1][2] [-nobias | -correct_bias] Do correct for the bias in the estimates (default). [-dsamp] Correct for slice timing differences (default). [-nodsamp ] Do not correct for slice timing differences . [-mask mname] mname = filename of 3d mask dataset only voxels with non-zero values in the mask would be considered. [-nfirst fnum] fnum = number of first dataset image to use in the delay estimate. (default = 0) [-nlast lnum] lnum = number of last dataset image to use in the delay estimate. (default = last) [-co CCT] Cross Correlation Coefficient threshold value. This is only used to limit the ascii output (see below). [-asc [out]] Write the results to an ascii file for voxels with [-ascts [out]] cross correlation coefficients larger than CCT. If 'out' is not specified, a default name similar to the default output prefix is used. -asc, only files 'out' and 'out.log' are written to disk (see ahead) -ascts, an additional file, 'out.ts', is written to disk (see ahead) There a 9 columns in 'out' which hold the following values: 1- Voxel Index (VI) : Each voxel in an AFNI brick has a unique index. Indices map directly to XYZ coordinates. See AFNI plugin documentations for more info. 2..4- Voxel coordinates (X Y Z): Those are the voxel slice coordinates. You can see these coordinates in the upper left side of the AFNI window. To do so, you must first switch the voxel coordinate units from mm to slice coordinates. Define Datamode -> Misc -> Voxel Coords ? PS: The coords that show up in the graph window may be different from those in the upper left side of AFNI's main window. 5- Duff : A value of no interest to you. It is preserved for backward compatibility. 6- Delay (Del) : The estimated voxel delay. 7- Covariance (Cov) : Covariance estimate. 8- Cross Correlation Coefficient (xCorCoef) : Cross Correlation Coefficient. 9- Variance (VTS) : Variance of voxel's time series. The file 'out' can be used as an input to two plugins: '4Ddump' and '3D+t Extract' The log file 'out.log' contains all parameter settings used for generating the output brick. It also holds any warnings generated by the plugin. Some warnings, such as 'null time series ...' , or 'Could not find zero crossing ...' are harmless. ' I might remove them in future versions. A line (L) in the file 'out.ts' contains the time series of the voxel whose results are written on line (L) in the file 'out'. The time series written to 'out.ts' do not contain the ignored samples, they are detrended and have zero mean. Random Comments/Advice: The longer you time series, the better. It is generally recommended that the largest delay be less than N/10, N being time series' length. The algorithm does go all the way to N/2. If you have/find questions/comments/bugs about the plugin, send me an E-mail: saadz@mail.nih.gov Ziad Saad Dec 8 00. [1] : Bendat, J. S. (1985). The Hilbert transform and applications to correlation measurements, Bruel and Kjaer Instruments Inc. [2] : Bendat, J. S. and G. A. Piersol (1986). Random Data analysis and measurement procedures, John Wiley & Sons. Author's publications on delay estimation using the Hilbert Transform: [3] : Saad, Z.S., et al., Analysis and use of FMRI response delays. Hum Brain Mapp, 2001. 13(2): p. 74-93. [4] : Saad, Z.S., E.A. DeYoe, and K.M. Ropella, Estimation of FMRI Response Delays. Neuroimage, 2003. 18(2): p. 494-504. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dDepthMap
Overview ~1~ This program calculates the depth of ROIs, masks and 'background', using the fun Euclidean Distance Transform (EDT). Basically, this means calculating the Euclidean distance of each voxel's centroid to the nearest boundary with a separate ROI (well, to be brutally technical, to centroid of the nearest voxel in a neighboring ROI. The input dataset should be a map of ROIs (so, integer-valued). The EDT values are calculated throughout the entire FOV by default, even in the zero/background regions (there is an option to control this). written by: PA Taylor and P Lauren (SSCC, NIMH, NIH) Description ~2~ This code calculates the Euclidean Distance Transform (EDT) for 3D volumes following this nice, efficient algorithm, by Felzenszwalb and Huttenlocher (2012; FH2012): Felzenszwalb PF, Huttenlocher DP (2012). Distance Transforms of Sampled Functions. Theory of Computing 8:415-428. https://cs.brown.edu/people/pfelzens/papers/dt-final.pdf Thanks to C. Rorden for pointing this paper out and discussing it. The current code here extends/tweaks the FH2012 algorithm to a more general case of having several different ROIs present, for running in 3D (trivial extension), and for having voxels of non-unity and non-isotropic lengths. It does this by utilizing the fact that at its very heart, the FH2012 algorithm works line by line and can even be thought of as working boundary-by-boundary. Here, the zero-valued 'background' is also just treated like an ROI, with one difference. At a FOV boundary, the zero-valued ROI/background is treated as open, so that the EDT value at each 'zero' voxel is always to one of the shapes within the FOV. For nonzero ROIs, one can treat the FOV boundary *either* as an ROI edge (EDT value there will be 1 edge length) *or* as being open. ========================================================================== Command usage and option list ~1~ 3dDepthMap [options] -prefix PREF -input DSET where: -input DSET :(req) input dataset -prefix PREF :(req) output prefix name -mask MASK :mask dataset. NB: this mask is only applied *after* the EDT has been calculated. Therefore, the boundaries of this mask have no affect on the calculated distance values, except for potentially zeroing some out at the end. -dist_sq :by default, the output EDT volume contains distance values. By using this option, the output values are distance**2. -ignore_voxdims :this EDT algorithm works in terms of physical distance and uses the voxel dimension info in each direction, by default. However, using this option will ignore voxel size, producing outputs as if each voxel dimension was unity. -rimify RIM :instead of outputting a depthmap for each ROI, output a map of each ROI's 'rim' voxels---that is, the boundary layer or periphery up to thickness RIM---if RIM>0. + Note that RIM is applied to whatever kind of depth information you are calculating: if you use '-dist_sq' then the voxel's distance-squared value to the ROI edge is compared with RIM; if using '-ignore_voxdims', then the number-of-voxels to the edge is compared with RIM. The depthmap thresholding is applied as: abs(DEPTH)<=RIM. + When using this opt, any labeltable/atlastable from the original should be passed along, as well. + A negative RIM value inverts the check, and the output is kept if the depth info is: abs(DEPTH)>=abs(RIM). NB: with a negative RIM value, it is possible an ROI could disappear! -zeros_are_zero :by default, EDT values are output for the full FOV, even zero-valued regions. If this option is used, EDT values are only reported within the nonzero locations of the input dataset. -zeros_are_neg :if this option is used, EDT in the zero/background of the input will be negative (def: they are positive). This opt cannot be used if '-zeros_are_zero' is. -nz_are_neg :if this option is used, EDT in the nonzero ROI regions of the input will be negative (def: they are positive). -bounds_are_not_zero :this flag affects how FOV boundaries are treated for nonzero ROIs: by default, they are viewed as ROI boundaries (so the FOV is a closed boundary for an ROI, as if the FOV were padded by an extra layer of zeros); but when this option is used, the ROI behaves as if it continued 'infinitely' at the FOV boundary (so it is an open boundary). Zero-valued ROIs (= background) are not affected by this option. -only2D SLI :instead of running full 3D EDT, run just in 2D, per. plane. Provide the slice plane you want to run along as the single argument SLI: "axi" -> for axial slice "cor" -> for coronal slice "sag" -> for sagittal slice -binary_only :if the input is a binary mask or should be treated as one (all nonzero voxels -> 1; all zeros stay 0), then using this option will speed up the calculation. See Notes below for more explanation of this. NOT ON YET! -verb V :manage verbosity when running code (def: 1). Providing a V of 0 means to run quietly. ========================================================================== Notes ~1~ Depth and the Euclidean Distance Transform ~2~ The original EDT algorithm of FH2012 was developed for a simple binary mask input (and actually for homogeneous data grids of spacing=1). This program, however, was built to handle more generalized cases of inputs, namely ROI maps (and arbitrary voxel dimensions). The tradeoff of the expansion to handling ROI maps is an increase in processing time---the original binary-mask algorithm is *very* efficient, and the generalized one is still pretty quick but less so. So, if you know that your input should be treated as a binary mask, then you can use the '-binary_only' option to utilize the more efficient (and less generalized) algorithm. The output dataset should be the same in either case---this option flag is purely about speed of computation. All other options about outputting dist**2 or negative values/etc. can be used in conjunction with the '-binary_only', too. ========================================================================== Examples ~1~ 1) Basic case: 3dDepthMap \ -input roi_map.nii.gz \ -prefix roi_map_EDT.nii.gz 2) Same as above, but only output distances within nonzero regions/ROIs: 3dDepthMap \ -zeros_are_zero \ -input roi_map.nii.gz \ -prefix roi_map_EDT_ZZ.nii.gz 3) Output distance-squared at each voxel: 3dDepthMap \ -dist_sq \ -input mask.nii.gz \ -prefix mask_EDT_SQ.nii.gz 4) Distinguish ROIs from nonzero background by making the former have negative distance values in output: 3dDepthMap \ -nz_are_neg \ -input roi_map.nii.gz \ -prefix roi_map_EDT_NZNEG.nii.gz 5) Have output voxel values represent (number of vox)**2 from a boundary; voxel dimensions are ignored here: 3dDepthMap \ -ignore_voxdims \ -dist_sq \ -input roi_map.nii.gz \ -prefix roi_map_EDT_SQ_VOX.nii.gz 6) Basic case, with option for speed-up because the input is a binary mask (i.e., only ones and zeros); any of the other above options can be combined with this, too: 3dDepthMap \ -binary_only \ -input roi_mask.nii.gz \ -prefix roi_mask_EDT.nii.gz 7) Instead of outputting ROI depth, output a map of the ROI rims, keeping: the part of the ROI up to where depth is >=1.6mm 3dDepthMap \ -input roi_map.nii.gz \ -rimify 1.6 \ -prefix roi_map_rim.nii.gz ==========================================================================

AFNI program: 3dDespike
Usage: 3dDespike [options] dataset Removes 'spikes' from the 3D+time input dataset and writes a new dataset with the spike values replaced by something more pleasing to the eye. ------------------ Outline of Method: ------------------ * L1 fit a smooth-ish curve to each voxel time series [see -corder option for description of the curve] [see -NEW option for a different & faster fitting method] * Compute the MAD of the difference between the curve and the data time series (the residuals). * Estimate the standard deviation 'sigma' of the residuals from the MAD. * For each voxel value, define s = (value-curve)/sigma. * Values with s > c1 are replaced with a value that yields a modified s' = c1+(c2-c1)*tanh((s-c1)/(c2-c1)). * c1 is the threshold value of s for a 'spike' [default c1=2.5]. * c2 is the upper range of the allowed deviation from the curve: s=[c1..infinity) is mapped to s'=[c1..c2) [default c2=4]. An alternative method for replacing the spike value is provided by the '-localedit' option, and that method is preferred by many users. The input dataset can be stored in short or float formats. The output dataset will always be stored in floats. [Feb 2017] -------- Options: -------- -ignore I = Ignore the first I points in the time series: these values will just be copied to the output dataset [default I=0]. -corder L = Set the curve fit order to L: the curve that is fit to voxel data v(t) is k=L [ (2*PI*k*t) (2*PI*k*t) ] f(t) = a+b*t+c*t*t + SUM [ d * sin(--------) + e * cos(--------) ] k=1 [ k ( T ) k ( T ) ] where T = duration of time series; the a,b,c,d,e parameters are chosen to minimize the sum over t of |v(t)-f(t)| (L1 regression); this type of fitting is is insensitive to large spikes in the data. The default value of L is NT/30, where NT = number of time points. -cut c1 c2 = Alter default values for the spike cut values [default c1=2.5, c2=4.0]. -prefix pp = Save de-spiked dataset with prefix 'pp' [default pp='despike'] -ssave ttt = Save 'spikiness' measure s for each voxel into a 3D+time dataset with prefix 'ttt' [default=no save] -nomask = Process all voxels [default=use a mask of high-intensity voxels, ] [as created via '3dAutomask -dilate 4 dataset']. -dilate nd = Dilate 'nd' times (as in 3dAutomask). The default value of 'nd' is 4. -q[uiet] = Don't print '++' informational messages. -localedit = Change the editing process to the following: If a voxel |s| value is >= c2, then replace the voxel value with the average of the two nearest non-spike (|s| < c2) values; the first one previous and the first one after. Note that the c1 cut value is not used here. -NEW = Use the 'new' method for computing the fit, which should be faster than the L1 method for long time series (200+ time points); however, the results are similar but NOT identical. [29 Nov 2013] * You can also make the program use the 'new' method by setting the environment variable AFNI_3dDespike_NEW to the value YES; as in setenv AFNI_3dDespike_NEW YES (csh) export AFNI_3dDespike_NEW=YES (bash) * If this variable is set to YES, you can turn off the '-NEW' processing by using the '-OLD' option. -->>* For time series more than 500 points long, the '-OLD' algorithm is tremendously slow. You should use the '-NEW' algorithm in such cases. ** At some indeterminate point in the future, the '-NEW' method will become the default! -->>* As of 29 Sep 2016, '-NEW' is the default if there is more than 500 points in the time series dataset. -NEW25 = A slightly more aggressive despiking approach than the '-NEW' method. -------- Caveats: -------- * Despiking may interfere with image registration, since head movement may produce 'spikes' at the edge of the brain, and this information would be used in the registration process. This possibility has not been explored or calibrated. * [LATER] Actually, it seems like the registration problem does NOT happen, and in fact, despiking seems to help! * Check your data visually before and after despiking and registration! ========================================================================= * This binary version of 3dDespike is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dDetrend
Usage: 3dDetrend [options] dataset * This program removes components from voxel time series using linear least squares. Each voxel is treated independently. * Note that least squares detrending is equivalent to orthogonalizing the input dataset time series with respect to the basis time series provided by the '-vector', '-polort', et cetera options. * The input dataset may have a sub-brick selector string; otherwise, all sub-bricks will be used. *** You might also want to consider using program 3dBandpass *** General Options: -prefix pname = Use 'pname' for the output dataset prefix name. [default='detrend'] -session dir = Use 'dir' for the output dataset session directory. [default='./'=current working directory] -verb = Print out some verbose output as the program runs. -replace = Instead of subtracting the fit from each voxel, replace the voxel data with the time series fit. -normalize = Normalize each output voxel time series; that is, make the sum-of-squares equal to 1. N.B.: This option is only valid if the input dataset is stored as floats! (1D files are always floats.) -byslice = Treat each input vector (infra) as describing a set of time series interlaced across slices. If NZ is the number of slices and NT is the number of time points, then each input vector should have NZ*NT values when this option is used (usually, they only need NT values). The values must be arranged in slice order, then time order, in each vector column, as shown here: f(z=0,t=0) // first slice, first time f(z=1,t=0) // second slice, first time ... f(z=NZ-1,t=0) // last slice, first time f(z=0,t=1) // first slice, second time f(z=1,t=1) // second slice, second time ... f(z=NZ-1,t=NT-1) // last slice, last time Component Options: These options determine the components that will be removed from each dataset voxel time series. They may be repeated to specify multiple regression. At least one component must be specified. -vector vvv = Remove components proportional to the columns vectors of the ASCII *.1D file 'vvv'. You may use a sub-vector selector string to specify which columns to use; otherwise, all columns will be used. For example: -vector 'xyzzy.1D[3,5]' will remove the 4th and 6th columns of file xyzzy.1D from the dataset (sub-vector indexes start at 0). You can use multiple -vector instances to specify components from different files. -expr eee = Remove components proportional to the function specified in the expression string 'eee'. Any single letter from a-z may be used as the independent variable in 'eee'. For example: -expr 'cos(2*PI*t/40)' -expr 'sin(2*PI*t/40)' will remove sine and cosine waves of period 40 from the dataset. -polort ppp = Add Legendre polynomials of order up to and including 'ppp' in the list of vectors to remove. -del ddd = Use the numerical value 'ddd' for the stepsize in subsequent -expr options. If no -del option is ever given, then the TR given in the dataset header is used for 'ddd'; if that isn't available, then 'ddd'=1.0 is assumed. The j-th time point will have independent variable = j * ddd, starting at j=0. For example: -expr 'sin(x)' -del 2.0 -expr 'z**3' means that the stepsize in 'sin(x)' is delta-x=TR, but the stepsize in 'z**3' is delta-z = 2. N.B.: expressions are NOT calculated on a per-slice basis when the -byslice option is used. If you have to do this, you could compute vectors with the required time series using 1deval. Detrending 1D files ------------------- As far as '3d' programs are concerned, you can input a 1D file as a 'dataset'. Each row is a separate voxel, and each column is a separate time point. If you want to detrend a single column, then you need to transpose it on input. For example: 3dDetrend -prefix - -vector G1.1D -polort 3 G5.1D\' | 1dplot -stdin Note that the '-vector' file is NOT transposed with \', but that the input dataset file IS transposed. This is because in the first case the program expects a 1D file, and so knows that the column direction is time. In the second case, the program expects a 3D dataset, and when given a 1D file, knows that the row direction is time -- so it must be transposed. I'm sorry if this is confusing, but that's the way it is. NOTE: to have the output file appear so that time is in the column direction, you'll have to add the option '-DAFNI_1D_TRANOUT=YES' to the command line, as in 3dDetrend -DAFNI_1D_TRANOUT=YES -prefix - -vector G1.1D -polort 3 G5.1D\' > Q.1D ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dDFT
++ Authored by: Kevin Murphy & Zhark the Transformer Usage: 3dDFT [options] dataset where 'dataset' is complex- or float-valued. * Carries out the DFT along the time axis. * To do the DFT along the spatial axes, use program 3dFFT. * The input dataset can be complex-valued or float-valued. If it is any other data type, it will be converted to floats before processing. * [June 2018] The FFT length used is NOT rounded up to a convenient FFT radix; instead, the FFT size is actual value supplied in option '-nfft' or the number of time points (if '-nfft' isn't used). * However, if the FFT length has large prime factors (say > 97), the Fast Fourier Transform algorithm will be relatively slow. This slowdown is probably only noticeable for very long files, since reading and writing datasets seems to take most of the elapsed time in 'normal' cases. OPTIONS: -------- -prefix PP == use 'PP' as the prefix of the output file -abs == output float dataset = abs(DFT) * Otherwise, the output file is complex-valued. You can then use 3dcalc to extract the real part, the imaginary part, the phase, etc.; see its '-cx2r' option: 3dcalc -cx2r REAL -a cxset+orig-expr a -prefix rset+orig * Please note that if you view a complex dataset in AFNI, the default operation is that you are looking at the absolute value of the dataset. ++ You can control the way a complex IMAGE appears via the 'Disp' control panel (ABS, PHASE, REAL, IMAGE). ++ You can control the way a complex TIME SERIES graph appears via environment variable AFNI_GRAPH_CX2R (in 'EditEnv'). -nfft N == use 'N' for DFT length (must be >= #time points) -detrend == least-squares remove linear drift before DFT [for more intricate detrending, use 3dDetrend first] -taper f == taper 'f' fraction of data at ends (0 <= f <= 1). [Hamming 'raised cosine' taper of f/2 of the ] [data length at each end; default is no taper] [cf. 3dPeriodogam -help for tapering details!] -inverse == Do the inverse DFT: SUM{ data[j] * exp(+2*PI*i*j/nfft) } * 1/nfft instead of the forward transform SUM{ data[j] * exp(-2*PI*i*j/nfft) } ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dDiff
This is a program to examine element-wise differences between two images. Usage ~1~ 3dDiff [display opt] [-tol TOLERANCE] [-mask MASK] <DSET_1> <DSET_2> where: -tol TOLERANCE :(opt) the floating-point tolerance/epsilon -mask MASK: :(opt) the mask to use when comparing -a DSET_1 :(req) input dataset a -b DSET_2 :(req) input dataset b ... and there are the following (mutually exclusive) display options: -q :(opt) quiet mode, indicate 0 for no differences and 1 for differences. -1 indicates that an error has occurred (aka "Rick Mode"). -tabular :(opt) display only a table of differences, plus a summary line (the same one as -brutalist) Mostly for use with 4D data. -brutalist :(opt) display one-liner. The first number indicates whether there is a difference, the second number indicates how many elements (3D) or volumes (4D) were different, and the last number indicates the total number of elements/volumes compared. if there is a dataset dimension mismatch or an error, then this will be a line of all -1s. See examples below for sample output. -long_report :(opt) print a large report with lots of information. If no display options are used, a short message with a summary will print. =========================================================================== Examples ~1~ 1) Basic Example: comparing two images A) In the 3D case, you get a short message indicating if there is no difference: $ 3dDiff -a image.nii -b image.nii ++ Images do NOT differ ... or a bit more information if there is a difference: $ 3dDiff -a mine.nii -b yours.nii ++ Images differ: 126976 of 126976 elements differ (100.00%) B) In the 4D case, the total number of elements AND total number of volumes which differ are reported: $ 3dDiff -a mine.nii -b yours.nii ++ Images differ: 10 of 10 volumes differ (100.00%) and 5965461 of 6082560 elements (98.07%) 2) A tolerance can be used to be more permissive of differences. In this example, any voxel difference of 100 or less is considered equal: $ 3dDiff -tol 100 -a mine.nii -b yours.nii ++ Images differ: 234529 of 608256 elements differ (38.56%) 3) A mask can be used to limit which regions are being compared: $ 3dDiff -mask roi.nii -a mine.nii -b yours.nii ++ Images differ: 5 of 10 volumes differ (50.00%) and 675225 of 1350450 elements (50.00%) NB: The mask is assumed to have a single time point; volumes in the mask beyond the [0]th are ignored. =========================================================================== Modes of output/reporting ~1~ There are a variety of reporting modes for 3dDiff, with varying levels of verbosity. They can be used to view the image comparison in both human and machine-readable formats. The default mode is the version shown in the above examples, where a short statement is made summarizing the differences. Reporting modes are mutually exclusive, but may be used with any of the other program options without restriction. 1) Quiet Mode (-q) ~2~ Returns a single integer value in the range [-1, 1]: -1 indicates a program error (e.g., grids do not match) 0 indicates that the images have no differences 1 indicates that the images have differences Examples: $ 3dDiff -q -a image.nii # no image b supplied -1 $ 3dDiff -q -a image.nii -b image.nii # an image agrees with itself 0 $ 3dDiff -q -a mine.nii -b yours.nii # two different images 1 2) Tabular Mode (-tabular) ~2~ Prints out a table of values. Useful for 4D data, but not recommended for 3D data. Each row of the table will indicate the volume index and number of differing elements. At the end of the table, a summary line will appear (see -brutalist). Example (just using the first 10 volumes of two datasets): $ 3dDiff -tabular -a "mine.nii[0..9]" -b "yours.nii[0..9]" 0: 596431 1: 596465 2: 596576 3: 596644 4: 596638 5: 596658 6: 596517 7: 596512 8: 596500 9: 596520 1 10 10 1.00000 3) Brutalist Mode (-brutalist) ~2~ Creates a one-line summary of the differences. The numbers appear in the following order: Summary [-1, 1], -1 failure, 1 differences, 0 agreement Differences [0, NV/NT], the number of differing elements (3D) or volumes (4D) Total Compared NV/NT, the number of elements/volumes compared Fraction Diff [0, 1.0], the fraction of differing elements/volumes Examples: $ 3dDiff -brutalist -a "mine.nii[0]" -b "yours.nii[0]" # 3D 1 596431 608256 0.98056 ... which means: There is a difference, 596431 elements differed, 608256 elements were compared. The fraction of differing elements is 0.98056.) $ 3dDiff -brutalist -a "mine.nii[0..9]" -b "yours.nii[0..9]" # 4D 1 10 10 1.00000 ... which means: There is a difference, 10 volumes differed, 10 volumes were compared. The fraction of differing volumes is 1.0). If the program fails for some reason, brutalist output will be an array of all -1s, like this: $ 3dDiff -brutalist -a image.nii # no dataset b to compare to -1 -1 -1 -1 4) Long Report Mode (-long_report) Prints a very large report with lots of information. **WARNING:** this report is intended for use with humans, not machines! The author makes no guarantee of backwards compatibility for this mode, and will add or remove report outputs at his own (shocking whimsical) discretion. =========================================================================== Note on unhappy comparisons ~1~ If this program reports that the images cannot be element-wise compared, you can examine the header information with 3dinfo. In particular, check out the section, "Options requiring dataset pairing at input", most notably options starting with "same", for example, -same_grid. =========================================================================== Author note: ~1~ Written by JB Teves, who notes: "Perfection is achieved not when there is no data left to add, but when there is no data left to throw away." ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3ddot
Usage: 3ddot [options] dset1 [dset2 dset3 ...] Output = correlation coefficient between sub-brick pairs All datasets on the command line will get catenated at loading time and should all be on the same grid. - you can use sub-brick selectors on the dsets - the result is a number printed to stdout Options: -mask mset Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be averaged from 'dataset'. Note that the mask dataset and the input dataset must have the same number of voxels. -mrange a b Means to further restrict the voxels from 'mset' so that only those mask values between 'a' and 'b' (inclusive) will be used. If this option is not given, all nonzero values from 'mset' are used. Note that if a voxel is zero in 'mset', then it won't be included, even if a < 0 < b. -demean Means to remove the mean from each volume prior to computing the correlation. -docor Return the correlation coefficient (default). -dodot Return the dot product (unscaled). -docoef Return the least square fit coefficients {a,b} so that dset2 is approximately a + b*dset1 -dosums Return the 6 numbers xbar=<x> ybar=<y> <(x-xbar)^2> <(y-ybar)^2> <(x-xbar)(y-ybar)> and the correlation coefficient. -doeta2 Return eta-squared (Cohen, NeuroImage 2008). -dodice Return the Dice coefficient (the Sorensen-Dice index). -show_labels Print sub-brick labels to help identify what is being correlated. This option is useful when you have more than 2 sub-bricks at input. -upper Compute upper triangular matrix -full Compute the whole matrix. A waste of time, but handy for parsing. -1D Comment headings in order to read in 1D format. This is only useful with -full. -NIML Write output in NIML 1D format. Nicer for plotting. -full and -show_labels are automatically turned on with -NIML. For example: 3ddot -NIML anat.001.sc7z.sigset+orig"[0,1,2,3,4]" \ > corrmat.1D 1dRplot corrmat.1D or 1dRplot -save somecorr.jpg -i corrmat.1D Note: This program is not efficient when more than two subbricks are input. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3ddot_beta
Beta version of updating 3ddot. Right now, *only* doing eta2 tests, and only outputting a full matrix to a text file. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: 3ddot_beta -input FILE -doeta2 \ {-mask MASK } -prefix PREFIX * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUT: 1) A single text file with the correlation-like matrix. If the input data set has N bricks, then the matrix will be NxN. + RUNNING: -input FILE :file with N bricks. -prefix PREFIX :output test file will be called PREFIX_eta2.dat. -doeta2 :right now, required switch (more tests might be present in the future, if demand calls for it). -mask MASK :can include a mask within which to take values. Otherwise, data should be masked already. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3ddot_beta \ -input RSFC_MAPS_cat+orig \ -mask mask.nii.gz \ -doeta2 \ -prefix My_Matrix_File * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ___________________________________________________________________________

AFNI program: 3dDTeig
Usage: 3dDTeig [options] dataset Computes eigenvalues and eigenvectors for an input dataset of 6 sub-bricks Dxx,Dxy,Dyy,Dxz,Dyz,Dzz (lower diagonal order). The results are stored in a 14-subbrick bucket dataset. The resulting 14-subbricks are lambda_1,lambda_2,lambda_3, eigvec_1[1-3],eigvec_2[1-3],eigvec_3[1-3], FA,MD. The output is a bucket dataset. The input dataset may use a sub-brick selection list, as in program 3dcalc. Options: -prefix pname = Use 'pname' for the output dataset prefix name. [default='eig'] -datum type = Coerce the output data to be stored as the given type which may be byte, short or float. [default=float] -sep_dsets = save eigenvalues,vectors,FA,MD in separate datasets -uddata = tensor data is stored as upper diagonal instead of lower diagonal Mean diffusivity (MD) calculated as simple average of eigenvalues. Fractional Anisotropy (FA) calculated according to Pierpaoli C, Basser PJ. Microstructural and physiological features of tissues elucidated by quantitative-diffusion tensor MRI, J Magn Reson B 1996; 111:209-19 INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dDTtoDWI
Usage: 3dDTtoDWI [options] gradient-file I0-dataset DT-dataset Computes multiple gradient images from 6 principle direction tensors and corresponding gradient vector coordinates applied to the I0-dataset. The program takes three parameters as input : a 1D file of the gradient vectors with lines of ASCII floats Gxi,Gyi,Gzi. Only the non-zero gradient vectors are included in this file (no G0 line). The I0 dataset is a volume without any gradient applied. The DT dataset is the 6-sub-brick dataset containing the diffusion tensor data, Dxx, Dxy, Dyy, Dxz, Dyz, Dzz (lower triangular row-wise order) Options: -prefix pname = Use 'pname' for the output dataset prefix name. [default='DWI'] -automask = mask dataset so that the gradient images are computed only for high-intensity (presumably brain) voxels. The intensity level is determined the same way that 3dClipLevel works. -datum type = output dataset type [float/short/byte] (default is float). -help = show this help screen. -scale_out_1000 = matches with 3dDWItoDT's '-scale_out_1000' functionality. If the option was used there, then use it here, too. Example: 3dDTtoDWI -prefix DWI -automask tensor25.1D 'DT+orig[26]' DT+orig. The output is a n sub-brick bucket dataset containing computed DWI images. where n is the number of vectors in the gradient file + 1 INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'.

AFNI program: 3dDTtoNoisyDWI
Take an AFNI-style DT file as input, such as might be output by 3dDWItoDT (which means that the DT elements are ordered: Dxx,Dxy,Dyy,Dxz,Dyz,Dzz), as well as a set of gradients, and then generate a synthetic set of DWI measures with a given SNR. Might be useful for simulations/testing. Part of FATCAT (Taylor & Saad, 2013) in AFNI. It is similar in premise to 3dDTtoDWI, however this allows for the modeled inclusion of Rician noise (such as appears in MRI magnitude images). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: 3dDTtoNoisyDWI -dt_in DTFILE -grads GRADFILE -noise_frac0 FF \ {-bval BB} {-S0 SS} {-mask MASK } -prefix PREFIX * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUT: 1) If N gradients are input, then the output is a file with N+1 bricks that mimics a set of B0+DWI data (0th brick is the B0 reference). + RUNNING: -dt_in DTFILE :diffusion tensor file, which should have six bricks of DT components ordered in the AFNI (i.e., 3dDWItoDT) manner: Dxx,Dxy,Dyy,Dxz,Dyz,Dzz. -grads GRADFILE :text file of gradients arranged in three columns. It is assumed that there is no row of all zeros in the GRADFILE (i.e., representing the b=0 line). If there are N rows in GRADFILE, then the output DWI file will have N+1 bricks (0th will be the b=0 reference set of noise S0 measures). -noise_DWI FF :fractional value of noise in DWIs. The magnitude will be set by the b=0 reference signal, S0. Rician noise is used, which is characterized by a standard deviation, sigma, so that FF = sigma/S0 = 1/SNR0. For example, FF=0.05 roughly corresponds to an SNR0=20 'measurement'. -noise_B0 FF2 :optional switch to use a different fraction of Rician noise in the b=0 reference image; one might consider it realistic to have a much lower level of noise in the reference signal, S0, mirroring the fact that generally multiple averages of b=0 acquisitions are averaged together. If no fraction is entered here, then the simulation will run with FF2=FF. -prefix PREFIX :output file name prefix. Will have N+1 bricks when GRADFILE has N rows of gradients. -mask MASK :can include a mask within which to calculate uncert. Otherwise, data should be masked already. -bval BB :optional DW factor to use if one has DT values scaled to something physical (NB: AFNI 3dDWItoDT works in a world of b=1, so the default setting here is BB=1; one probably doesn't need to change this if using DTs made by 3dDWItoDT). -S0 SS :optional reference b=0 signal strength. Default value SS=1000. This just sets scale of output. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dDTtoNoisyDWI \ -dt_in DTI/DT_DT+orig \ -grads GRADS.dat \ -noise_DWI 0.1 \ -noise_B0 0 \ -prefix NEW_DWIs_SNR10 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________

AFNI program: 3dDWItoDT
Usage: 3dDWItoDT [options] gradient-file dataset Computes 6 principle direction tensors from multiple gradient vectors and corresponding DTI image volumes. The program takes two parameters as input : a 1D file of the gradient vectors with lines of ASCII floats: Gxi, Gyi, Gzi. Only the non-zero gradient vectors are included in this file (no G0 line). ** Now, a '1D' file of b-matrix elements can alternatively be input, and *all* the gradient values are included!** A 3D bucket dataset with Np+1 sub-briks where the first sub-brik is the volume acquired with no diffusion weighting. OUTPUTS: + you can output all 6 of the independent tensor values (Dxx, Dyy, etc.), as well as all three eigenvalues (L1, L2, L3) and eigenvectors (V1, V2, V3), and useful DTI parameters FA, MD and RD. + 'Debugging bricks' can also be output, see below. Options: -prefix pname = Use 'pname' for the output dataset prefix name. [default='DT'] -automask = mask dataset so that the tensors are computed only for high-intensity (presumably brain) voxels. The intensity level is determined the same way that 3dClipLevel works. -mask dset = use dset as mask to include/exclude voxels -bmatrix_NZ FF = switch to note that the input dataset is b-matrix, not gradient directions, and there is *no* row of zeros at the top of the file, similar to the format for the grad input: N-1 rows in this file for N vols in matched data set. There must be 6 columns of data, representing either elements of G_{ij} = g_i*g_j (i.e., dyad of gradients, without b-value included) or of the DW scaled version, B_{ij} = b*g_i*g_j. The order of components is: G_xx G_yy G_zz G_xy G_xz G_yz. -bmatrix_Z FF = similar to '-bmatrix_NZ' above, but assumes that first row of the file is all zeros (or whatever the b-value for the reference volume was!), i.e. there are N rows to the text file and N volumes in the matched data set. -bmatrix_FULL FF = exact same as '-bmatrix_Z FF' above (i.e. there are N rows to the text file and N volumes in the matched data set) with just a lot more commonsensical name. Definitely would be preferred way to go, for ease of usage! -scale_out_1000 = increase output parameters that have physical units (DT, MD, RD, L1, L2 and L3) by multiplying them by 1000. This might be convenient, as the input bmatrix/gradient values can have their physical magnitudes of ~1000 s/mm^2, for which typical adult WM has diffusion values of MD~0.0007 (in physical units of mm^2/s), and people might not like so many decimal points output; using this option rescales the input b-values and would lead to having a typical MD~0.7 (now in units of x10^{-3} mm^2/s). If you are not using bmatrix/gradient values that have their physical scalings, then using this switch probably wouldn't make much sense. FA, V1, V2 and V3 are unchanged. -bmax_ref THR = if the 'reference' bvalue is actually >0, you can flag that here. Otherwise, it is assumed to be zero. At present, this is probably only useful/meaningful if using the '-bmatrix_Z ...' or '-bmatrix_FULL ...' option, where the reference bvalue must be found and identified from the input info alone. -nonlinear = compute iterative solution to avoid negative eigenvalues. This is the default method. -linear = compute simple linear solution. -reweight = recompute weight factors at end of iterations and restart -max_iter n = maximum number of iterations for convergence (Default=10). Values can range from -1 to any positive integer less than 101. A value of -1 is equivalent to the linear solution. A value of 0 results in only the initial estimate of the diffusion tensor solution adjusted to avoid negative eigenvalues. -max_iter_rw n = max number of iterations after reweighting (Default=5) values can range from 1 to any positive integer less than 101. -eigs = compute eigenvalues, eigenvectors, fractional anisotropy and mean diffusivity in sub-briks 6-19. Computed as in 3dDTeig -debug_briks = add sub-briks with Ed (error functional), Ed0 (orig. error), number of steps to convergence and I0 (modeled B0 volume). [May, 2017] This also now calculates two goodness-of-fit measures and outputs a new PREFIX_CHI* dset that has two briks: brik [0]: chi^2_p, brik [1]: chi^2_c. These values are essentially calculated according to Papadakis et al. (2003, JMRI), Eqs. 4 and 3, respectively (in chi^2_c, the sigma value is the variance of measured DWIs *per voxel*). Note for both chi* values, only DWI signal values are used in the calculation (i.e., where b>THR; by default, THR=0.01, which can be changed using '-bmax_ref ...'). In general, chi^2_p values seem to be <<1, consistent with Papadakis et al.'s Fig. 4; the chi^2_c values are are also pretty consistent with the same fig and seem to be best viewed with the upper limit being roughly =Ndwi or =Ndwi-7 (with the latter being the given degrees of freedom value by Papadakis et al.) -cumulative_wts = show overall weight factors for each gradient level May be useful as a quality control -verbose nnnnn = print convergence steps every nnnnn voxels that survive to convergence loops (can be quite lengthy). -drive_afni nnnnn = show convergence graphs every nnnnn voxels that survive to convergence loops. AFNI must have NIML communications on (afni -niml) -sep_dsets = save tensor, eigenvalues, vectors, FA, MD in separate datasets -csf_val n.nnn = assign diffusivity value to DWI data where the mean values for b=0 volumes is less than the mean of the remaining volumes at each voxel. The default value is '1.0 divided by the max bvalue in the grads/bmatrices'. The assumption is that there are flow artifacts in CSF and blood vessels that give rise to lower b=0 voxels. NB: MD, RD L1, L2, L3, Dxx, Dyy, etc. values are all scaled in the same way. -min_bad_md N = change the min MD value used as a 'badness check' for tensor fits that have veeery (-> unreasonably) large MD values. Voxels where MD > N*(csf_val) will be treated like CSF and turned into spheres with radius csf_val (default N=100). -csf_fa n.nnn = assign a specific FA value to those voxels described above The default is 0.012345678 for use in tractography programs that may make special use of these voxels -opt mname = if mname is 'powell', use Powell's 2004 method for optimization. If mname is 'gradient' use gradient descent method. If mname is 'hybrid', use combination of methods. MJD Powell, "The NEWUOA software for unconstrained optimization without derivatives", Technical report DAMTP 2004/NA08, Cambridge University Numerical Analysis Group: See: http://www.ii.uib.no/~lennart/drgrad/Powell2004.pdf -mean_b0 = use mean of all b=0 volumes for linear computation and initial linear for nonlinear method Example: 3dDWItoDT -prefix rw01 -automask -reweight -max_iter 10 \ -max_iter_rw 10 tensor25.1D grad02+orig. The output is a 6 sub-brick bucket dataset containing Dxx, Dxy, Dyy, Dxz, Dyz, Dzz (the lower triangular, row-wise elements of the tensor in symmetric matrix form). Additional sub-briks may be appended with the -eigs and -debug_briks options. These results are appropriate as the input to 3dDTeig. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'.

AFNI program: 3dDWUncert
OVERVIEW ~1~ Use jackknifing to estimate uncertainty of DTI parameters which are important for probabilistic tractography on per voxel basis. Produces useful input for 3dTrackID, which does both mini- and full probabilistic tractography for GM ROIs in networks, part of FATCAT (Taylor & Saad, 2013) in AFNI. This version has been reprogrammed to include parallelized running via OpenMP (as of Oct, 2016). So, it has the potential to run a lot more quickly, assuming you have an OpenMPable setup for AFNI. The types/formats of inputs and outputs have not changed from before. **************************************************************************** OUTPUT ~1~ 1) AFNI-format file with 6 subbricks, containing uncertainty information. The bricks are in the following order: [0] bias of e1 in direction of e2 [1] stdev of e1 in direction of e2 [2] bias of e1 in direction of e3 [3] stdev of e1 in direction of e3 [4] bias of FA [5] stdev of FA RUNNING ~1~ 3dDWUncert -inset FILE -input [base of FA/MD/etc.] \ {-grads | -bmatrix_FULL} FILE -prefix NAME -iters NUMBER ... where: -inset FILE :file with b0 and DWI subbricks (e.g., input to 3dDWtoDTI) -prefix PREFIX :output file name part. -input INPREF :basename of DTI volumes output by, e.g., 3dDWItoDT or TORTOISE. Assumes format of name is, e.g.: INPREF_FA+orig.HEAD or INPREF_FA.nii.gz . Files needed with same prefix are: *FA*, *L1*, *V1*, *V2*, *V3* . -input_list FILE :an alternative way to specify DTI input files, where FILE is a NIML-formatted text file that lists the explicit/specific files for DTI input. This option is used in place of '-input INPREF'. See below for a 'INPUT LIST FILE EXAMPLE'. -grads FF :file with 3 columns for x-, y-, and z-comps of DW-gradients (which have unit magnitude). NB: this option also assumes that only 1st DWI subbrick has a b=0 image (i.e., all averaging of multiple b=0 images has been done already); if such is not the case, then you should convert your grads to the bmatrix format and use `-bmatrix_FULL'. OR -bmatrix_Z FF :using this means that file with gradient info is in b-matrix format, with 6 columns representing: b_xx b_yy b_zz b_xy b_xz b_yz. NB: here, bvalue per image is the trace of the bmatr, bval = b_xx+b_yy+b_zz, such as 1000 s/mm^2. This option might be used, for example, if multiple b-values were used to measure DWI data; this is an AFNI-style bmatrix that needs to be input. -bmatrix_FULL FF :exact same as '-bmatrix_Z FF' above (i.e. there are N rows to the text file and N volumes in the matched data set) with just a lot more commonsensical name. Definitely would be preferred way to go, for ease of usage! -iters NUMBER :number of jackknife resample iterations, e.g. 300. -mask MASK :can include a mask within which to calculate uncert. Otherwise, data should be masked already. -calc_thr_FA FF :set a threshold for the minimum FA value above which one calculates uncertainty; useful if one doesn't want to waste time calculating uncertainty in very low-FA voxels that are likely GM/CSF. For example, in adult subjects one might set FF=0.1 or 0.15, depending on SNR and user's whims (default: FF=-1, i.e., do all). -csf_fa NUMBER :number marking FA value of `bad' voxels, such as those with S0 value <=mean(S_i), which breaks DT assumptions due to, e.g., bulk/flow motion. Default value of this matches 3dDWItoDT value of csf_fa=0.012345678. * * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** DTI LIST FILE EXAMPLE ~1~ Consider, for example, if you hadn't used the '-sep_dsets' option when outputting all the tensor information from 3dDWItoDT. Then one could specify the DTI inputs for this program with a file called, e.g., FILE_DTI_IN.niml.opts (the name *must* end with '.niml.opts'): <DTIFILE_opts dti_V1="SINGLEDT+orig[9..11]" dti_V2="SINGLEDT+orig[12..14]" dti_V3="SINGLEDT+orig[15..17]" dti_FA="SINGLEDT+orig[18]" dti_L1="SINGLEDT+orig[6]" /> This represents the *minimum* set of input files needed when running 3dDWUncert. (Note that MD isn't needed here.) You can also recycle a NIMLly formatted file from '3dTrackID -dti_list'-- the extra inputs needed for the latter are a superset of those needed here, and won't affect anything detrimentally (I hope). **************************************************************************** COMMENTS (mainly about running speedily)~1~ + This program can be slow if you have looots of voxels and/or looots of of grads. *But*, it is written with OpenMP parallelization, so you can make use of having multiple CPUs. The system environment variable to specify the number of CPUs to use is OMP_NUM_THREADS. You can specify OMP_NUM_THREADS in your ~/.bashrc, ~/.cshrc or other shell RC file. Or, you can set it in the script you are using. To verify that your OMP_NUM_THREAD variable has been set as you want, you can use command line program 'afni_check_omp', and see what number is output. + If your input DWI dataset has not masked, you probably should input a mask with '-mask ..', because otherwise the program will waste a looot of time calculating DWI uncertainty of air and skull and other things of no practical consequence. EXAMPLES ~1~ 1) Basic example (probably assuming data has been masked): 3dDWUncert \ -inset TEST_FILES/DTI/fin2_DTI_3mm_1+orig \ -prefix TEST_FILES/DTI/o.UNCERT \ -input TEST_FILES/DTI/DT \ -grads TEST_FILES/Siemens_d30_GRADS.dat \ -iters 300 2) Same as above, with mask include as opt: 3dDWUncert \ -inset TEST_FILES/DTI/fin2_DTI_3mm_1+orig \ -prefix TEST_FILES/DTI/o.UNCERT \ -input TEST_FILES/DTI/DT \ -grads TEST_FILES/Siemens_d30_GRADS.dat \ -mask TEST_FILES/dwi_mask.nii.gz \ -iters 300 CITING ~1~ If you use this program, please reference the jackknifing algorithm done with nonlinear fitting described in: Taylor PA, Biswal BB (2011). Geometric analysis of the b-dependent effects of Rician signal noise on diffusion tensor imaging estimates and determining an optimal b value. MRI 29:777-788. and the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________

AFNI program: 3dECM
Usage: 3dECM [options] dset Computes voxelwise eigenvector centrality (ECM) and stores the result in a new 3D bucket dataset as floats to preserve their values. ECM of a voxel reflects the strength and extent of a voxel's global connectivity as well as the importance of the voxels that it is directly connected to. Conceptually the process involves: 1. Calculating the correlation between voxel time series for every pair of voxels in the brain (as determined by masking) 2. Calculate the eigenvector corresponding to the largest eigenvalue of the similarity matrix. Guaranteeing that the largest eigenvector is unique and therefore, that an ECM solution exists, requires that the similarity matrix is strictly positive. This is enforced by either adding one to the correlations as in (Lohmann et. al. 2010), or by adding one and dividing by two (Wink et al. 2012). Calculating the first eigenvector of a whole-brain similarity matrix requires a lot of system memory and time. 3dECM uses the optimizations described in (Wink et al 2012) to improve performance. It additionally provides a mechanism for limited the amount of system memory used to avoid memory related crashes. The performance can also be improved by reducing the number of connections in the similarity matrix using either a correlation or sparsity threshold. The correlation threshold simply removes all connections with a correlation less than the threshold. The sparsity threshold is a percentage and reflects the fraction of the strongest connections that should be retained for analysis. Sparsity thresholding uses a histogram approach to 'learn' a correlation threshold that would result in the desired level of sparsity. Due to ties and virtual ties due to poor precision for differentiating connections, the desired level of sparsity will not be met exactly, 3dECM will retain more connections than requested. Whole brain ECM results in very small voxel values and small differences between cortical areas. Reducing the number of connections in the analysis improves the voxel values and provides greater contrast between cortical areas . Lohmann G, Margulies DS, Horstmann A, Pleger B, Lepsien J, et al. (2010) Eigenvector Centrality Mapping for Analyzing Connectivity Patterns in fMRI Data of the Human Brain. PLoS ONE 5(4): e10232. doi: 10.1371/journal.pone.0010232 Wink, A. M., de Munck, J. C., van der Werf, Y. D., van den Heuvel, O. A., & Barkhof, F. (2012). Fast Eigenvector Centrality Mapping of Voxel-Wise Connectivity in Functional Magnetic Resonance Imaging: Implementation, Validation, and Interpretation. Brain Connectivity, 2(5), 265-274. doi:10.1089/brain.2012.0087 Options: -full = uses the full power method (Lohmann et. al. 2010). Enables the use of thresholding and calculating thresholded centrality. Uses sparse array to reduce memory requirement. Automatically selected if -thresh, or -sparsity are used. -fecm = uses a shortcut that substantially speeds up computation, but is less flexibile in what can be done the similarity matrix. i.e. does not allow thresholding correlation coefficients. based on fast eigenvector centrality mapping (Wink et. al 2012). Default when -thresh, or -sparsity are NOT used. -thresh r = exclude connections with correlation < r. cannot be used with FECM -sparsity p = only include the top p% (0 < p <= 100) connections in the calculation cannot be used with FECM method. (default) -do_binary = perform the ECM calculation on a binarized version of the connectivity matrix, this requires a connnectivity or sparsity threshold. -shift s = value that should be added to correlation coeffs to enforce non-negativity, s >= 0. [default = 0.0, unless -fecm is specified in which case the default is 1.0 (e.g. Wink et al 2012)]. -scale x = value that correlation coeffs should be multiplied by after shifting, x >= 0 [default = 1.0, unless -fecm is specified in which case the default is 0.5 (e.g. Wink et al 2012)]. -eps p = sets the stopping criterion for the power iteration l2|v_old - v_new| < eps*|v_old|. default = .001 (0.1%) -max_iter i = sets the maximum number of iterations to use in in the power iteration. default = 1000 -polort m = Remove polynomial trend of order 'm', for m=0..3. [default is m=1; removal is by least squares]. Using m=0 means that just the mean is removed. -autoclip = Clip off low-intensity regions in the dataset, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The mask is determined the same way that 3dAutomask works. -mask mmm = Mask to define 'in-brain' voxels. Reducing the number the number of voxels included in the calculation will significantly speedup the calculation. Consider using a mask to constrain the calculations to the grey matter rather than the whole brain. This is also preferable to using -autoclip or -automask. -prefix p = Save output into dataset with prefix 'p' [default prefix is 'ecm']. -memory G = Calculating eignevector centrality can consume a lot of memory. If unchecked this can crash a computer or cause it to hang. If the memory hits this limit the tool will error out, rather than affecting the system [default is 2G]. Notes: * The output dataset is a bucket type of floats. * The program prints out an estimate of its memory used when it ends. It also prints out a progress 'meter' to keep you pacified. -- RWCox - 31 Jan 2002 and 16 Jul 2010 -- Cameron Craddock - 13 Nov 2015 -- Daniel Clark - 14 March 2016 ========================================================================= * This binary version of 3dECM is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dedge3
Usage: 3dedge3 [options] dset dset ... Does 3D Edge detection using the library 3DEdge by; by Gregoire Malandain (gregoire.malandain@sophia.inria.fr) Options : -input iii = Input dataset -verbose = Print out some information along the way. -prefix ppp = Sets the prefix of the output dataset. -datum ddd = Sets the datum of the output dataset. -fscale = Force scaling of the output to the maximum integer range. -gscale = Same as '-fscale', but also forces each output sub-brick to to get the same scaling factor. -nscale = Don't do any scaling on output to byte or short datasets. -scale_floats VAL = Multiply input by VAL, but only if the input datum is float. This is needed when the input dataset has a small range, like 0 to 2.0 for instance. With such a range, very few edges are detected due to what I suspect to be truncation problems. Multiplying such a dataset by 10000 fixes the problem and the scaling is undone at the output. -automask = For automatic, internal calculation of a mask in the usual AFNI way. Again, this mask is only applied after all calcs (so using this does not speed up the calc or affect distance values). ** Special note: you can also write '-automask+X', where X is some integer; this will dilate the initial automask number of times (as in 3dAllineate); must have X>0. References for the algorithms: - Optimal edge detection using recursive filtering R. Deriche, International Journal of Computer Vision, pp 167-187, 1987. - Recursive filtering and edge tracking: two primary tools for 3-D edge detection, O. Monga, R. Deriche, G. Malandain and J.-P. Cocquerez, Image and Vision Computing 4:9, pp 203-214, August 1991. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dedgedog
Overview ~1~ This program calculates edges in an image using the Difference of Gaussians (DOG) method by Wilson and Giese (1977) and later combined with work by Marr and Hildreth (1980) to provide a computationally efficient approximation to their Lagrangian of Gaussian (LOG) method for calculating edges in an image. This is a fascinating set of papers to read. But you don't have to take *my* word for it!... Generating edges in this way has some interesting properties, such as numerical efficiency and edges that are closed loops/surfaces. The edges can be tuned to focus on structures of a particular size, too, which can be particularly useful in some applications. written by: PA Taylor and DR Glen (SSCC, NIMH, NIH) Description ~2~ The primary papers for learning more about the DOG and LOG methods are: Wilson HR, Giese SC (1977). Threshold visibility of frequency gradient patterns. Vision Res. 17(10):1177-90. doi: 10.1016/0042-6989(77)90152-3. PMID: 595381. Marr D, Hildreth E (1980). Theory of edge detection. Proc R Soc Lond B Biol Sci. 207(1167):187-217. doi: 10.1098/rspb.1980.0020. PMID: 6102765. Thanks to C. Rorden for pointing these papers out and discussing them. The current code here extends/tweaks the MH1980 algorithm a bit. It runs in 3D by default (a straightforward extension), it also employs the Euclidean Distance Transform (EDT) to pick out the actual edges from the DOG step---see 3dDepthMap for more information about the EDT. The DOG-based edges require specifying a couple parameters, the main one being interpretable as a minimal 'scale size' for structures. In this code, this is the 'sigma_rad' (or 'sigma_nvox', if you want to specify it in terms of the number of voxels along a given axis), which is the 'inner Gaussian' sigma value, if you are following MH1980. The default for this sigma_rad parameter is set based on the expected average thickness of adult human GM, but it is easily alterable at the command line for any other values. ========================================================================== Command usage and option list ~1~ 3dedgedog [options] -prefix PREF -input DSET where: -input DSET :(req) input dataset -prefix PREF :(req) output prefix name -mask MASK :mask dataset. NB: this mask is only applied *after* the EDT has been calculated. Therefore, the boundaries of this mask have no affect on the calculated distance values, except for potentially zeroing some out at the end. Mask only gets made from [0]th vol. -automask :alternative to '-mask ..', for automatic internal calculation of a mask in the usual AFNI way. Again, this mask is only applied after all calcs (so using this does not speed up the calc or affect distance values). ** Special note: you can also write '-automask+X', where X is some integer; this will dilate the initial automask X number of times (as in 3dAllineate); must have X>0. -sigma_rad RRR :radius for 'inner' Gaussian, in units of mm; RRR must by greater than zero (def: 1.40). Default is chosen to capture useful features in typical adult, human GM, which has typical thickness of 2-2.5mm. So, if you are analyzing some other kind of data, you might want to adapt this value appropriately. -sigma_nvox NNN :define radius for 'inner' Gaussian by providing a multiplicative factor for voxel edge length, which will be applied in each direction; NNN can be any float greater than zero. This is an alternative to the '-sigma_rad ..' opt (def: use '-sigma_rad' and its default value). -ratio_sigma RS :the ratio of inner and outer Gaussian sigma values. That is, RS defines the size of the outer Gaussian, by scaling up the inner value. RS can be any float greater than 1 (def: 1.40). See 'Notes' for more about this parameter. -output_intermed :use this option flag if you would like to output some intermediate dataset(s): + DOG (difference of Gaussian) + EDT2 (Euclidean Distance Transform, dist**2 vals), [0]th vol only + BLURS (inner- and outer-Gaussian blurred dsets), [0]th vol only (def: not output). Output names will be user-entered prefix with a representative suffix appended. -edge_bnd_NN EBN :specify the 'nearest neighbor' (NN) value for the connectedness of the drawn boundaries. EBN must be one of the following integer values: 1 -> for face only 2 -> for face+edge 3 -> for face+edge+node (def: 1). -edge_bnd_side EBS :specify which boundary layer around the zero-layer to use in the algorithm. EBS must be one of the following keywords: "NEG" -> for negative (inner) boundary "POS" -> for positive (outer) boundary "BOTH" -> for both (inner+outer) boundary "BOTH_SIGN" -> for both (inner+outer) boundary, with pos/neg sides keeping sign (def: "NEG"). -edge_bnd_scale :by default, this program outputs a mask of edges, so edge locations have value=1, and everything else is 0. Using this option means the edges will have values scaled to have a relative magnitude between 0 and 100 (NB: the output dset will still be datum=short) depending on the gradient value at the edge. When using this opt, likely setting the colorbar scale to 25 will provide nice images (in N=1 cases tested, at least!). -only2D SLI :instead of estimating edges in full 3D volume, calculate edges just in 2D, per plane. Provide the slice plane you want to run along as the single argument SLI: "axi" -> for axial slice "cor" -> for coronal slice "sag" -> for sagittal slice ========================================================================== Notes ~1~ The value of sigma_rad ~2~ (... which sounds like the title of a great story, no? Anyways...) This parameter represents the ratio of the width of the two Gaussians that are blurred in the first stage of the DOG estimation. In the limit that sigma_rad approaches 1, the DOG -> LOG. So, we want to keep the value of this parameter in the general vicinity of 1 (and it can't be less than 1, because the ratio is of the outer-to-the-inner Gaussian). MH1980 suggested that sigma_rad=1.6 was optimal 'on engineering grounds' of bandwidth sensitivity of filters. This is *very approximate* reasoning, but provides another reference datum for selection. Because the DOG approximation used here is for visual purposes of MRI datasets, often even more specifically for alignment purposes, we have chosen a default value that seemed visually appropriate to real data. Values of sigma_rad close to one show much noisier, scattered images---that is, they pick up *lots* of contrast differences, probably too many for most visualization purposes. Edge images smoothen as sigma_rad increases, but as it gets larger, it can also blend together edges of features---such as gyri of the brain with dura. So, long story short, the default value here tries to pick a reasonable middle ground. ========================================================================== Examples ~1~ 1) Basic case: 3dedgedog \ -input anat+orig.HEAD \ -prefix anat_EDGE.nii.gz 2) Same as above, but output both edges from the DOG+EDT steps, keeping the sign of each side: 3dedgedog \ -edge_bnd_side BOTH_SIGN \ -input anat+orig.HEAD \ -prefix anat_EDGE_BOTHS.nii.gz 3) Output both sides of edges, and scale the edge values (by DOG value): 3dedgedog \ -edge_bnd_side BOTH_SIGN \ -edge_bnd_scale \ -input anat+orig.HEAD \ -prefix anat_EDGE_BOTHS_SCALE.nii.gz 4) Increase scale size of edged shapes to 2.7mm: 3dedgedog \ -sigma_rad 2.7 \ -edge_bnd_scale \ -input anat+orig.HEAD \ -prefix anat_EDGE_BOTHS_SCALE.nii.gz 5) Apply automasking, with a bit of mask dilation so outer boundary is included: 3dedgedog \ -automask+2 \ -input anat+orig.HEAD \ -prefix anat_EDGE_AMASK.nii.gz ==========================================================================

AFNI program: 3dEdu_01_scale
Overview ~1~ This is an example starting program for those who want to create a new AFNI program to see some examples of possible I/O and internal calcs. Please see the source code file in the main afni/src/3dEdu_01_scale.c for more information. This program is intended purely for educational and code-development purposes. written by: PA Taylor Description ~2~ This program will take one dataset as input, and output a copy of its [0]th volume. A mask can be provided, as well as two multiplicative factors to mask and scale the output, respectively. ========================================================================== Command usage and option list ~1~ 3dEdu_01_scale [something] where: -input DSET :(req) input dataset -mask DSET_MASK :(opt) mask dataset on same grid/data structure as the input dset -some_opt :(opt) option flag to do something -mult_facs A B :(opt) numerical factors for multiplying each voxel; that is, each voxel is multiplied by both A and B. ========================================================================== Examples ~1~ 1) Output a copy of the [0]th volume of the input: 3dEdu_01_scale \ -input epi_r1+orig.HEAD \ -prefix OUT_edu_01 2) Output a masked copy of the [0]th volume of the input: 3dEdu_01_scale \ -input epi_r1+orig.HEAD \ -mask mask.auto.nii.gz \ -prefix OUT_edu_02 3) Output a masked+scaled copy of the [0]th volume of the input: 3dEdu_01_scale \ -mult_facs 3 5.5 \ -input epi_r1+orig.HEAD \ -mask mask.auto.nii.gz \ -prefix OUT_edu_03 ==========================================================================

AFNI program: 3dEigsToDT
Convert set of DTI eigenvectors and eigenvalues to a diffusion tensor, while also allowing for some potentially useful value-scaling and vector- flipping. May be helpful in converting output from different software packages. Part of FATCAT (Taylor & Saad, 2013) in AFNI. It is essentially the inverse of the existing AFNI command: 3dDTeig. Minor note and caveat: This program has been checked for consistency with 3dDWItoDT outputs (that is using its output eigenvalues and eigenvectors to estimate a DT, which was then compared with that of the original 3dDWItoDT fit). This program will *mostly* return the same DTs that one would get from using the eigenvalues and eigenvectors of 3dDWItoDT to very high agreement The values generally match to <10**-5 or so, except in CSF where there can be small/medium differences, apparently due to the noisiness or non- tensor-fittability of the original DWI data in those voxels. However, these discrepancies *shouldn't* really affect most cases of using DTI data. This is probably generally true for reconstructing DTs of most software program output: the results match well for most WM and GM, but there might be trouble in partial-volumed and CSF regions, where the DT model likely did not fit well anyways. Caveat emptor. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: 3dEigsToDT -eig_vals NAME1 -eig_vecs NAME2 {-mask MASK } \ {-flip_x | -flip_y | flip_z} {-scale_eigs X} -prefix PREFIX * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUT: 1) AFNI-format DT file with 6 subbricks in the same format as output by, for example, 3dDWItoDT (the lower triangular, row-wise elements of the tensor in symmetric matrix form) [0] Dxx [1] Dxy [2] Dyy [3] Dxz [4] Dyz [5] Dzz + RUNNING: -eig_vals NAME1 :Should be a searchable descriptor for finding all three required eigenvalue files. Thus, on a Linux commandline, one would expect: $ ls NAME1 to list all three eigenvalue files in descending order of magnitude. This program will also only take the first three matches (not including doubling of BRIK/HEAD files in AFNI-format). -eig_vecs NAME2 :Should be a searchable descriptor for finding all three required eigenvector files. Thus, on a Linux commandline, one would expect: $ ls NAME2 to list all three eigenvector files in order matching the eigenvalue files. This program will also only take the first three matches (not including doubling of BRIK/HEAD files in AFNI-format). -> Try to make NAME1 and NAME2 as specific as possible, so that the search&load gets everything as right as possible. Also, if using the wildcard character, '*', then make sure to enclose the option value with apostrophes (see EXAMPLE, below). -prefix PREFIX :output file name prefix. Would suggest putting a 'DT' label in it. -mask MASK :can include a mask within which to calculate uncert. Otherwise, data should be masked already. -flip_x :change sign of first element of eigenvectors. -flip_y :change sign of second element of eigenvectors. -flip_z :change sign of third element of eigenvectors. -> Only a single flip would ever be necessary; the combination of any two flips is mathematically equivalent to the sole application of the remaining one. -scale_eigs X :rescale the eigenvalues, dividing by a number that is X>0. Could be used to reintroduce the DW scale of the original b-values, if some other program has remorselessly scaled it away. * * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** + EXAMPLE: 3dEigsToDT \ -eig_vals 'DTI/DT_L*' \ -eig_vecs 'DTI/DT_V*' \ -prefix DTI/NEW_DT \ -scale_eigs 1000 \ -flip_y * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity.

AFNI program: 3dEmpty
Usage: 3dEmpty [options] Makes an 'empty' dataset .HEAD file. Options: ======= -prefix p = Prefix name for output file (default = 'Empty') -nxyz x y z = Set number of voxels to be 'x', 'y', and 'z' along the 3 axes [defaults=64] *OR* -geometry m = Set the 3D geometry of the grid using a string 'm' of the form 'MATRIX(a11,a12,a13,a14,a21,a22,a23,a24,a31,a32,a33,a34):nx,ny,nz' which defines the number of grid points, as well as relationship between grid indexes (voxel centers) and the 3D xyz coordinates. * Sample 'MATRIX()' entries can be found by using program 3dinfo on an existing datasets. * Each .niml file used by 3dGroupInCorr has a 'geometry="MATRIX(...)" entry. -nt = Number of time points [default=1] * Other dataset parameters can be changed with 3drefit. * The purpose of this program (combined with 3drefit) is to allow you to make up an AFNI header for an existing data file. * This program does NOT create data to fill up the dataset. * If you want to create a dataset of a given size with random values attached, a command like 3dcalc -a jRandomDataset:32,32,16,10 -expr a -prefix Something would work. In this example, nx=ny=32 nz=16 nt=10. (Changing '-expr a' to '-expr 0' would fill the dataset with zeros.) ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dEntropy
Usage: 3dEntropy [-zskip] dataset ... * Datasets must be stored as 16 bit shorts. * -zskip option means to skip 0 values in the computation. * This program is not very useful :) :( ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dExchange
Usage: 3dExchange [-prefix PREFIX] <-input DATASET> Replaces voxel values using mapping file with two columns of numbers with the first column of the input value and the second has the output value -input DATASET : Input dataset Acceptable data types are: byte, short, and floats. -map MAPCOLS.1D : Mapping columns - input is first column output is second column -prefix PREFIX: Output prefix -ver = print author and version info -help = print this help screen INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dExtractGroupInCorr
++ 3dExtractGroupInCorr: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: RW Cox Usage: 3dExtractGroupInCorr [options] AAA.grpincorr.niml This program breaks the collection of images from a GroupInCorr file back into individual AFNI 3D+time datasets. Of course, only the data inside the mask used in 3dSetupGroupInCorr is stored in the .data file, so only those portions of the input files can be reconstructed :) The output datasets will be stored in float format, no matter what the storage type of the original datasets or of the .data file. OPTION: ------- -prefix PPP The actual dataset prefix with be the internal dataset label with the string 'PPP_' pre-prended. ++ Use NULL to skip the use of the prefix. Author -- RWCox -- May 2012 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dExtrema
++ 3dExtrema: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program finds local extrema (minima or maxima) of the input dataset values for each sub-brick of the input dataset. The extrema may be determined either for each volume, or for each individual slice. Only those voxels whose corresponding intensity value is greater than the user specified data threshold will be considered. Usage: 3dExtrema options datasets where the options are: -prefix pname = Use 'pname' for the output dataset prefix name. OR [default = NONE; only screen output] -output pname -session dir = Use 'dir' for the output dataset session directory. [default='./'=current working directory] -quiet = Flag to suppress screen output -mask_file mname = Use mask statistic from file mname. Note: If file mname contains more than 1 sub-brick, the mask sub-brick must be specified! -mask_thr m Only voxels whose mask statistic is >= m in absolute value will be considered. A default value of 1 is assumed. -data_thr d Only voxels whose value (intensity) is greater than d in absolute value will be considered. -nbest N Only print the first N extrema. -sep_dist d Min. separation distance [mm] for distinct extrema Choose type of extrema (one and only one choice): -minima Find local minima. -maxima [default] Find local maxima. Choose form of binary relation (one and only one choice): -strict [default] > for maxima, < for minima -partial >= for maxima, <= for minima Choose boundary criteria (one and only one choice): -interior [default]Extrema must be interior points (not on boundary) -closure Extrema may be boundary points Choose domain for finding extrema (one and only one choice): -slice [default] Each slice is considered separately -volume The volume is considered as a whole Choose option for merging of extrema (one and only one choice): -remove [default] Remove all but strongest of neighboring extrema -average Replace neighboring extrema by average -weight Replace neighboring extrema by weighted average Command line arguments after the above are taken to be input datasets. Examples: Compute maximum value in amygdala region of Talairach-transformed dataset 3dExtrema -volume -closure -sep_dist 512 \ -mask_file 'TT_Daemon::amygdala' func_slim+tlrc'[0]' Show minimum voxel values not on edge of mask, where the mask >= 0.95 3dExtrema -minima -volume -mask_file 'statmask+orig' \ -mask_thr 0.95 func_slim+tlrc'[0]' Get the maximum 3 values across the given ROI. 3dExtrema -volume -closure -mask_file MY_ROI+tlrc \ -nbest 3 func_slim+tlrc'[0]' INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dFDR
++ 3dFDR: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program implements the False Discovery Rate (FDR) algorithm for thresholding of voxelwise statistics. Program input consists of a functional dataset containing one (or more) statistical sub-bricks. Output consists of a bucket dataset with one sub-brick for each input sub-brick. For non-statistical input sub-bricks, the output is a copy of the input. However, statistical input sub-bricks are replaced by their corresponding FDR values, as follows: For each voxel, the minimum value of q is determined such that E(FDR) <= q leads to rejection of the null hypothesis in that voxel. Only voxels inside the user specified mask will be considered. These q-values are then mapped to z-scores for compatibility with the AFNI statistical threshold display: stat ==> p-value ==> FDR q-value ==> FDR z-score The reason for the final conversion from q to z is so that larger values are more 'significant', which is how the usual thresholding procedure in the AFNI GUI works. Usage: 3dFDR -input fname fname = filename of input 3d functional dataset OR -input1D dname dname = .1D file containing column of p-values -mask_file mname Use mask values from file mname. *OR* Note: If file mname contains more than 1 sub-brick, -mask mname the mask sub-brick must be specified! Default: No mask ** Generally speaking, you really should use a mask to avoid counting non-brain voxels. However, with the changes described below, the program will automatically ignore voxels where the statistics are set to 0, so if the program that created the dataset used a mask, then you don't need one here. -mask_thr m Only voxels whose corresponding mask value is greater than or equal to m in absolute value will be considered. Default: m=1 Constant c(N) depends on assumption about p-values: -cind c(N) = 1 p-values are independent across N voxels -cdep c(N) = sum(1/i), i=1,...,N any joint distribution Default: c(N) = 1 -quiet Flag to suppress screen output -list Write sorted list of voxel q-values to screen -prefix pname Use 'pname' for the output dataset prefix name. OR -output pname =========================================================================== January 2008: Changes to 3dFDR ------------------------------ The default mode of operation of 3dFDR has altered somewhat: * Voxel p-values of exactly 1 (e.g., from t=0 or F=0 or correlation=0) are ignored by default; in the old mode of operation, they were included in the count which goes into the FDR algorithm. The old process tends to increase the q-values and so decrease the z-scores. * The array of voxel p-values are now sorted via Quicksort, rather than by binning, as in the old mode. This (by itself) probably has no discernible effect on the results, but should be faster. New Options: ------------ -old = Use the old mode of operation (for compatibility/nostalgia) -new = Use the new mode of operation [now the default] N.B.: '-list' does not work in the new mode! -pmask = Instruct the program to ignore p=1 voxels [the default in the new mode, but not in the old mode] N.B.: voxels that were masked in 3dDeconvolve (etc.) will have their statistics set to 0, which means p=1, which means that such voxels are implicitly masked with '-new', and so don't need to be explicitly masked with the '-mask' option. -nopmask = Instruct the program to count p=1 voxels [the default in the old mode, but NOT in the new mode] -force = Force the conversion of all sub-bricks, even if they are not marked as with a statistical code; such sub-bricks are treated as though they were p-values. -float = Force the output of z-scores in floating point format. -qval = Force the output of q-values rather than z-scores. N.B.: A smaller q-value is more significant! [-float is strongly recommended when -qval is used] * To be clear, you can use '-new -nopmask' to have the new mode of computing carried out, but with p=1 voxels included (which should give results nearly identical to '-old'). * Or you can use '-old -pmask' to use the old mode of computing but where p=1 voxels are not counted (which should give results virtually identical to '-new'). * However, the combination of '-new', '-nopmask' and '-mask_file' does not work -- if you try it, '-pmask' will be turned back on and a warning message printed to aid your path towards elucidation and enlightenment. Other Notes: ------------ * '3drefit -addFDR' can be used to add FDR curves of z(q) as a function of threshold for all statistic sub-bricks in a dataset; in turn, these curves let you see the (estimated) q-value as you move the threshold slider in AFNI. - Since 3drefit doesn't have a '-mask' option, you will have to mask statistical sub-bricks yourself via 3dcalc (if desired): 3dcalc -a stat+orig -b mask+orig -expr 'a*step(b)' -prefix statmm - '-addFDR' runs as if '-new -pmask' were given to 3dFDR, so that stat values == 0 are ignored in the FDR calculations. - most AFNI statistical programs now automatically add FDR curves to the output dataset header, so you can see the q-value as you adjust the threshold slider. * q-values are estimates of the False Discovery Rate at a given threshold; that is, about 5% of all voxels with q <= 0.05 (z >= 1.96) are (presumably) 'false positive' detections, and the other 95% are (presumably) 'true positives'. Of course, there is no way to tell which above-threshold voxels are 'true' detections and which are 'false'. * Note the use of the words 'estimate' and 'about' in the above statement! In particular, the accuracy of the q-value calculation depends on the assumption that the p-values calculated from the input statistics are correctly distributed (e.g., that the DOF parameters are correct). * The z-score is the conversion of the q-value to a double-sided tail probability of the unit Gaussian N(0,1) distribution; that is, z(q) is the value such that if x is a N(0,1) random variable, then Prob[|x|>z] = q: for example, z(0.05) = 1.95996. The reason for using z-scores here is simply that their range is highly compressed relative to the range of q-values (e.g., z(1e-9) = 6.10941), so z-scores are easily stored as shorts, whereas q-values are much better stored as floats. * Changes above by RWCox -- 18 Jan 2008 == Cary Grant's Birthday! 26 Mar 2009 -- Yet Another Change [RWCox] ----------------------------------------- * FDR calculations in AFNI now 'adjust' the q-values downwards by estimating the number of true negatives [m0 in the statistics literature], and then reporting q_new = q_old * m0 / m, where m = number of voxels being tested. If you do NOT want this adjustment, then set environment variable AFNI_DONT_ADJUST_FDR to YES. You can do this on the 3dFDR command line with the option '-DAFNI_DONT_ADJUST_FDR=YES' For Further Reading and Amusement --------------------------------- * cf. http://en.wikipedia.org/wiki/False_discovery_rate [Easy overview of FDR] * cf. http://dx.doi.org/10.1093/bioinformatics/bti448 [False Negative Rate] * cf. http://dx.doi.org/10.1093/biomet/93.3.491 [m0 adjustment idea] * cf. C implementation in mri_fdrize.c [trust in the Source] * cf. https://afni.nimh.nih.gov/pub/dist/doc/misc/FDR/FDR_Jan2008.pdf ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dFFT
Usage: 3dFFT [options] dataset * Does the FFT of the input dataset in 3 directions (x,y,z) and produces the output dataset. * Why you'd want to do this is an interesting question. * Program 3dcalc can operate on complex-valued datasets, but only on one component at a time (cf. the '-cx2r' option). * Most other AFNI programs can only operate on real-valued datasets. * You could use 3dcalc (twice) to split a complex-valued dataset into two real-valued datasets, do your will on those with other AFNI programs, then merge the results back into a complex-valued dataset with 3dTwotoComplex. Options ======= -abs = Outputs the magnitude of the FFT [default] -phase = Outputs the phase of the FFT (-PI..PI == no unwrapping!) -complex = Outputs the complex-valued FFT -inverse = Does the inverse FFT instead of the forward FFT -Lx xx = Use FFT of length 'xx' in the x-direction -Ly yy = Use FFT of length 'yy' in the y-direction -Lz zz = Use FFT of length 'zz' in the z-direction * Set a length to 0 to skip the FFT in that direction -altIN = Alternate signs of input data before FFT, to bring zero frequency from edge of FFT-space to center of grid for cosmetic purposes. -altOUT = Alternate signs of output data after FFT. If you use '-altI' on the forward transform, then you should use '-altO' an the inverse transform, to get the signs of the recovered image correct. **N.B.: You cannot use '-altIN' and '-altOUT' in the same run! -input dd = Read the input dataset from 'dd', instead of from the last argument on the command line. -prefix pp = Use 'pp' for the output dataset prefix. Notes ===== * The program can only do FFT lengths that are positive even integers. * The 'x', 'y', and 'z' axes here refer to the order the data is stored, not DICOM coordinates; cf. 3dinfo. * If you force (via '-Lx' etc.) an FFT length that is not allowed, the program will stop with an error message. * If you force an FFT length that is shorter than an dataset axis dimension, the program will stop with an error message. * If you don't force an FFT length along a particular axis, the program will pick the smallest legal value that is greater than or equal to the corresponding dataset dimension. + e.g., 123 would be increased to 124. * If an FFT length is longer than an axis length, then the input data in that direction is zero-padded at the end. * For -abs and -phase, the output dataset is in float format. * If you do the forward and inverse FFT, then you should get back the original dataset, except for roundoff error and except that the new dataset axis dimensions may be longer than the original. * Forward FFT = sum_{k=0..N-1} [ exp(-2*PI*i*k/N) * data(k) ] * Inverse FFT = sum_{k=0..N-1} [ exp(+2*PI*i*k/N) * data(k) ] / N * Started a long time ago, but only finished in Aug 2009 at the request of John Butman, because he asked so nicely. (Now pay up!) ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dfim+
++ 3dfim+: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward [7m*+ WARNING:[0m This program (3dfim+) is very old, may not be useful, and will not be maintained. Program to calculate the cross-correlation of an ideal reference waveform with the measured FMRI time series for each voxel. Usage: 3dfim+ -input fname fname = filename of input 3d+time dataset [-input1D dname] dname = filename of single (fMRI) .1D time series [-mask mname] mname = filename of 3d mask dataset [-nfirst fnum] fnum = number of first dataset image to use in the cross-correlation procedure. (default = 0) [-nlast lnum] lnum = number of last dataset image to use in the cross-correlation procedure. (default = last) [-polort pnum] pnum = degree of polynomial corresponding to the baseline model (pnum = 0, 1, etc.) (default: pnum = 1). Use -1 for no baseline model. [-fim_thr p] p = fim internal mask threshold value (0 <= p <= 1) to get rid of low intensity voxels. (default: p = 0.0999), set p = 0.0 for no masking. [-cdisp cval] Write (to screen) results for those voxels whose correlation stat. > cval (0 <= cval <= 1) (default: disabled) [-ort_file sname] sname = input ort time series file name -ideal_file rname rname = input ideal time series file name Note: The -ort_file and -ideal_file commands may be used more than once. Note: If files sname or rname contain multiple columns, then ALL columns will be used as ort or ideal time series. However, individual columns or a subset of columns may be selected using a file name specification like 'fred.1D[0,3,5]', which indicates that only columns #0, #3, and #5 will be used for input. [-out param] Flag to output the specified parameter, where the string 'param' may be any one of the following: Fit Coef L.S. fit coefficient for Best Ideal Best Index Index number for Best Ideal (count starts at 1) % Change P-P amplitude of signal response / Baseline Baseline Average of baseline model response Correlation Best Ideal product-moment correlation coefficient % From Ave P-P amplitude of signal response / Average Average Baseline + average of signal response % From Top P-P amplitude of signal response / Topline Topline Baseline + P-P amplitude of signal response Sigma Resid Std. Dev. of residuals from best fit All This specifies all of the above parameters Spearman CC Spearman correlation coefficient Quadrant CC Quadrant correlation coefficient Note: Multiple '-out' commands may be used. Note: If a parameter name contains embedded spaces, the entire parameter name must be enclosed by quotes, e.g., -out 'Fit Coef' [-bucket bprefix] Create one AFNI 'bucket' dataset containing the parameters of interest, as specified by the above '-out' commands. The output 'bucket' dataset is written to a file with the prefix name bprefix. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dfractionize
Usage: 3dfractionize [options] * For each voxel in the output dataset, computes the fraction of it that is occupied by nonzero voxels from the input. * The fraction is stored as a short in the range 0..10000, indicating fractions running from 0..1. * The template dataset is used only to define the output grid; its brick(s) will not be read into memory. (The same is true of the warp dataset, if it is used.) * The actual values stored in the input dataset are irrelevant, except in that they are zero or nonzero (UNLESS the -preserve option is used). The purpose of this program is to allow the resampling of a mask dataset (the input) from a fine grid to a coarse grid (defined by the template). When you are using the output, you will probably want to threshold the mask so that voxels with a tiny occupancy fraction aren't used. This can be done in 3dmaskave, by using 3calc, or with the '-clip' option below. Options are [the first 2 are 'mandatory options']: -template tset = Use dataset 'tset' as a template for the output. The output dataset will be on the same grid as this dataset. -input iset = Use dataset 'iset' for the input. Only the sub-brick #0 of the input is used. You can use the sub-brick selection technique described in '3dcalc -help' to choose the desired sub-brick from a multi-brick dataset. -prefix ppp = Use 'ppp' for the prefix of the output. [default prefix = 'fractionize'] -clip fff = Clip off voxels that are less than 'fff' occupied. 'fff' can be a number between 0.0 and 1.0, meaning the fraction occupied, can be a number between 1.0 and 100.0, meaning the percent occupied, or can be a number between 100.0 and 10000.0, meaning the direct output value to use as a clip level. ** Some sort of clipping is desirable; otherwise, an output voxel that is barely overlapped by a single nonzero input voxel will enter the mask. [default clip = 0.0] -warp wset = If this option is used, 'wset' is a dataset that provides a transformation (warp) from +orig coordinates to the coordinates of 'iset'. In this case, the output dataset will be in +orig coordinates rather than the coordinates of 'iset'. With this option: ** 'tset' must be in +orig coordinates ** 'iset' must be in +acpc or +tlrc coordinates ** 'wset' must be in the same coordinates as 'iset' -preserve = When this option is used, the program will copy or the nonzero values of input voxels to the output -vote dataset, rather than create a fractional mask. Since each output voxel might be overlapped by more than one input voxel, the program 'votes' for which input value to preserve. For example, if input voxels with value=1 occupy 10% of an output voxel, and inputs with value=2 occupy 20% of the same voxel, then the output value in that voxel will be set to 2 (provided that 20% is >= to the clip fraction). ** Voting can only be done on short-valued datasets, or on byte-valued datasets. ** Voting is a relatively time-consuming option, since a separate loop is made through the input dataset for each distinct value found. ** Combining this with the -warp option does NOT make a general +tlrc to +orig transformer! This is because for any value to survive the vote, its fraction in the output voxel must be >= clip fraction, regardless of other values present in the output voxel. Sample usage: 1. Compute the fraction of each voxel occupied by the warped input. 3dfractionize -template grid+orig -input data+tlrc \ -warp anat+tlrc -clip 0.2 2. Apply the (inverse) -warp transformation to transform the -input from +tlrc space to +orig space, storing it according to the grid of the -template. A voxel in the output dataset gets the value that occupies most of its volume, providing that value occupies 20% of the voxel. Note that the essential difference from above is '-preserve'. 3dfractionize -template grid+orig -input data+tlrc \ -warp anat+tlrc -preserve -clip 0.2 \ -prefix new_data Note that 3dAllineate can also be used to warp from +tlrc to +orig space. In this case, data is computed through interpolation, rather than voting based on the fraction of a voxel occupied by each data value. The transformation comes from the WARP_DATA attribute directly. Nearest neighbor interpolation is used in this 'mask' example. cat_matvec -ONELINE anat+tlrc::WARP_DATA > tlrc.aff12.1D 3dAllineate -1Dmatrix_apply tlrc.aff12.1D -source group_mask+tlrc \ -master subj_epi+orig -prefix subj_mask -final NN This program will also work in going from a coarse grid to a fine grid, but it isn't clear that this capability has any purpose. -- RWCox - February 1999 - October 1999: added -warp and -preserve options ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dFriedman
++ 3dFriedman: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program performs nonparametric Friedman test for randomized complete block design experiments. Usage: 3dFriedman -levels s s = number of treatments -dset 1 filename data set for treatment #1 . . . . . . -dset 1 filename data set for treatment #1 . . . . . . -dset s filename data set for treatment #s . . . . . . -dset s filename data set for treatment #s [-workmem mega] number of megabytes of RAM to use for statistical workspace [-voxel num] screen output for voxel # num -out prefixname Friedman statistics are written to file prefixname N.B.: For this program, the user must specify 1 and only 1 sub-brick with each -dset command. That is, if an input dataset contains more than 1 sub-brick, a sub-brick selector must be used, e.g.: -dset 2 'fred+orig[3]' INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dFWHMx
Usage: 3dFWHMx [options] dataset **** NOTICE **** You should use the '-acf' option (which is what afni_proc.py uses now). The 'Classic' method giving just a Gaussian FWHM can no longer be considered reliable for FMRI statistical analyses! **************** >>>>> 20 July 2017: Results from the 'Classic' method are no longer output! >>>>> If you want to see these values, you must give the >>>>> command line option '-ShowMeClassicFWHM'. >>>>> You no longer need to give the '-acf' option, as it >>>>> is now the default method of calculation (and >>>>> cannot be turned off). Note that if you need the >>>>> FWHM estimate, the '-acf' method gives a value >>>>> for that as its fourth output. >>>>> Options and comments that only apply to the 'Classic' FWHM estimation >>>>> method are now marked below with this '>>>>>' marker, to indicate that >>>>> they are obsolete, archaic, and endangered (as well as fattening). >>>>> Unlike the older 3dFWHM, this program computes FWHMs for all sub-bricks >>>>> in the input dataset, each one separately. The output for each one is >>>>> written to the file specified by '-out'. The mean (arithmetic or geometric) >>>>> of all the FWHMs along each axis is written to stdout. (A non-positive >>>>> output value indicates something bad happened; e.g., FWHM in z is meaningless >>>>> for a 2D dataset; the estimation method computed incoherent intermediate results.) (Classic) METHOD: <<<<< NO LONGER OUTPUT -- SEE ABOVE >>>>> - Calculate ratio of variance of first differences to data variance. - Should be the same as 3dFWHM for a 1-brick dataset. (But the output format is simpler to use in a script.) **----------------------------------------------------------------------------** ************* IMPORTANT NOTE [Dec 2015] **************************************** **----------------------------------------------------------------------------** A completely new method for estimating and using noise smoothness values is now available in 3dFWHMx and 3dClustSim. This method is implemented in the '-acf' options to both programs. 'ACF' stands for (spatial) AutoCorrelation Function, and it is estimated by calculating moments of differences out to a larger radius than before. Notably, real FMRI data does not actually have a Gaussian-shaped ACF, so the estimated ACF is then fit (in 3dFWHMx) to a mixed model (Gaussian plus mono-exponential) of the form ACF(r) = a * exp(-r*r/(2*b*b)) + (1-a)*exp(-r/c) where 'r' is the radius, and 'a', 'b', 'c' are the fitted parameters. The apparent FWHM from this model is usually somewhat larger in real data than the FWHM estimated from just the nearest-neighbor differences used in the 'classic' analysis. The longer tails provided by the mono-exponential are also significant. 3dClustSim has also been modified to use the ACF model given above to generate noise random fields. **----------------------------------------------------------------------------** ** The take-away (TL;DR or summary) message is that the 'classic' 3dFWHMx and ** ** 3dClustSim analysis, using a pure Gaussian ACF, is not very correct for ** ** FMRI data -- I cannot speak for PET or MEG data. ** **----------------------------------------------------------------------------** OPTIONS: -mask mmm = Use only voxels that are nonzero in dataset 'mmm'. -automask = Compute a mask from THIS dataset, a la 3dAutomask. [Default = use all voxels] -input ddd }= *OR* }= Use dataset 'ddd' as the input. -dset ddd }= -demed = If the input dataset has more than one sub-brick (e.g., has a time axis), then subtract the median of each voxel's time series before processing FWHM. This will tend to remove intrinsic spatial structure and leave behind the noise. [Default = don't do this] -unif = If the input dataset has more than one sub-brick, then normalize each voxel's time series to have the same MAD before processing FWHM. Implies -demed. [Default = don't do this] -detrend [q]= Instead of demed (0th order detrending), detrend to order 'q'. If q is not given, the program picks q=NT/30. -detrend disables -demed, and includes -unif. **N.B.: I recommend this option IF you are running 3dFWHMx on functional MRI time series that have NOT been processed to remove any activation and/or physiological artifacts. **** If you are running 3dFWHMx on the residual (errts) time series from afni_proc.py, you don't need -detrend. **N.B.: This is the same detrending as done in 3dDespike; using 2*q+3 basis functions for q > 0. ******* If you don't use '-detrend', the program checks if a large number of voxels are have significant nonzero means. If so, the program will print a warning message suggesting the use of '-detrend', since inherent spatial structure in the image will bias the estimation of the FWHM of the image time series NOISE (which is usually the point of using 3dFWHMx). -detprefix d= Save the detrended file into a dataset with prefix 'd'. Used mostly to figure out what the hell is going on, when strange results transpire. >>>>> -geom }= If the input dataset has more than one sub-brick, *OR* }= compute the final estimate as the geometric mean -arith }= or the arithmetic mean of the individual sub-brick FWHM estimates. [Default = -geom, for no good reason] >>>>> -combine = combine the final measurements along each axis into one result >>>>> -out ttt = Write output to file 'ttt' (3 columns of numbers). If not given, the sub-brick outputs are not written. Use '-out -' to write to stdout, if desired. Note that this option outputs the 'Classic' (which means simply Gaussian, *not* ACF) parameters for each sub-brick. >>>>> -compat = Be compatible with the older 3dFWHM, where if a voxel is in the mask, then its neighbors are used for differencing, even if they are not themselves in the mask. This was an error; now, neighbors must also be in the mask to be used in the differencing. Use '-compat' to use the older method. ** NOT RECOMMENDED except for comparison purposes! ** -ACF [anam] = ** new option Nov 2015 ** *or* The '-ACF' option computes the spatial autocorrelation -acf [anam] of the data as a function of radius, then fits that to a model of the form ACF(r) = a * exp(-r*r/(2*b*b)) + (1-a)*exp(-r/c) and outputs the 3 model parameters (a,b,c) to stdout. * The model fit assumes spherical symmetry in the ACF. * The results shown on stdout are in the format >>>>> The first 2 lines below will only be output <<<<< >>>>> if you use the option '-ShowMeClassicFWHM'. <<<<< >>>>> Otherwise, the 'old-style' FWHM values will <<<<< >>>>> show up as all zeros (0 0 0 0). <<<<< # old-style FWHM parameters 10.4069 10.3441 9.87341 10.2053 # ACF model parameters for a*exp(-r*r/(2*b*b))+(1-a)*exp(-r/c) plus effective FWHM 0.578615 6.37267 14.402 16.1453 The lines that start with '#' are comments. >>>>> The first numeric line contains the 'old style' FWHM estimates, >>>>> FWHM_x FWHM_y FHWM_z FWHM_combined The second numeric line contains the a,b,c parameters, plus the combined estimated FWHM from those parameters. In this example, the fit was about 58% Gaussian shape, 42% exponential shape, and the effective FWHM from this fit was 16.14mm, versus 10.21mm estimated in the 'old way'. * If you use '-acf' instead of '-ACF', then the comment #lines in the stdout information will be omitted. This might help in parsing the output inside a script. * The empirical ACF results are also written to the file 'anam' in 4 columns: radius ACF(r) model(r) gaussian_NEWmodel(r)(r) where 'gaussian_NEWmodel' is the Gaussian with the FWHM estimated from the ACF, NOT via the 'classic' (Forman 1995) method. * If 'anam' is not given (that is, another option starting with '-' immediately follows '-acf'), then '3dFWHMx.1D' will be used for this filename. If 'anam' is set to 'NULL', then the corresponding output files will not be saved. * By default, the ACF is computed out to a radius based on a multiple of the 'classic' FWHM estimate. If you want to specify that radius (in mm), you can put that value after the 'anam' parameter, as in '-acf something.1D 40.0'. * In addition, a graph of these functions will be saved into file 'anam'.png, for your pleasure and elucidation. * Note that the ACF calculations are slower than the 'classic' FWHM calculations. To reduce this sloth, 3dFWHMx now uses OpenMP to speed things up. * The ACF modeling is intended to enhance 3dClustSim, and may or may not be useful for any other purpose! >>>>> SAMPLE USAGE: (tcsh) >>>>> set zork = ( `3dFWHMx -automask -input junque+orig` ) >>>>> Captures the FWHM-x, FWHM-y, FWHM-z values into shell variable 'zork'. INPUT FILE RECOMMENDATIONS: * For FMRI statistical purposes, you DO NOT want the FWHM or ACF to reflect any spatial structure of the underlying anatomy. Rather, you want the FWHM/ACF to reflect the spatial structure of the NOISE. This means that the input dataset should not have anatomical (spatial) structure. * One good form of input is the output of '3dDeconvolve -errts', which is the dataset of residuals left over after the GLM fitted signal model is subtracted out from each voxel's time series. * If you don't want to go to that much trouble, use '-detrend' to approximately subtract out the anatomical spatial structure, OR use the output of 3dDetrend for the same purpose. * If you do not use '-detrend', the program attempts to find non-zero spatial structure in the input, and will print a warning message if it is detected. *** Do NOT use 3dFWHMx on the statistical results (e.g., '-bucket') from *** *** 3dDeconvolve or 3dREMLfit!!! The function of 3dFWHMx is to estimate *** *** the smoothness of the time series NOISE, not of the statistics. This *** *** proscription is especially true if you plan to use 3dClustSim next!! *** *** ------------------- *** *** NOTE FOR SPM USERS: *** *** ------------------- *** *** If you are using SPM for your analyses, and wish to use 3dFHWMX plus *** *** 3dClustSim for cluster-level thresholds, you need to understand the *** *** process that AFNI uses. Otherwise, you will likely make some simple *** *** mistake (such as using 3dFWHMx on the statistical maps from SPM) *** *** that will render your cluster-level thresholding completely wrong! *** >>>>> IF YOUR DATA HAS SMOOTH-ISH SPATIAL STRUCTURE YOU CAN'T GET RID OF: For example, you only have 1 volume, say from PET imaging. In this case, the standard estimate of the noise smoothness will be mixed in with the structure of the background. An approximate way to avoid this problem is provided with the semi-secret '-2difMAD' option, which uses a combination of first-neighbor and second-neighbor differences to estimate the smoothness, rather than just first-neighbor differences, and uses the MAD of the differences rather than the standard deviation. (If you must know the details, read the source code in mri_fwhm.c!) [For Jatin Vaidya, March 2010] ALSO SEE: * The older program 3dFWHM is now completely superseded by 3dFWHMx. * The program 3dClustSim takes as input the ACF estimates and then estimates the cluster sizes thresholds to help you get 'corrected' (for multiple comparisons) p-values. >>>>> * 3dLocalstat -stat FWHM will estimate the FWHM values at each voxel, using the same first-difference algorithm as this program, but applied only to a local neighborhood of each voxel in turn. * 3dLocalACF will estimate the 3 ACF parameters in a local neighborhood around each voxel. >>>>> * 3dBlurToFWHM will iteratively blur a dataset (inside a mask) to have a given global FWHM. This program may or may not be useful :) * 3dBlurInMask will blur a dataset inside a mask, but doesn't measure FWHM or ACF. -- Zhark, Ruler of the (Galactic) Cluster! ========================================================================= * This binary version of 3dFWHMx is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dGenFeatureDist
3dGenFeatureDist produces hives. -classes 'CLASS_STRING': CLASS_STRING is a semicolon delimited string of class labels. For example -classes 'CSF; WM; GM' -OTHER: Add histograms for an 'OTHER' class that has a uniform pdf. -no_OTHER: Opposite of -OTHER. -features 'FEATURES_STRING': FEATURES_STRING is a semicolon delimited string of features. For example -features 'MEAN.00_mm; median.19_mm; ...' -sig 'FEATURE_VOL1 FEATURE_VOL2 ...': Specify volumes that define the features. Each sub-brick is a feature and the sub-brick's name is used to name the feature. Multiple volumes get catenated. Each occurrence of -sig option must be paired with a -samp option. Think of each pair of '-sig, -samp' options as describing data on the same voxel grid; Think from the same subject. When specifying training data from K subjects, you will end up using K pairs of '-sig, -samp'. All volumes from the kth -sig instance should have the same voxel grid as each other and as that of the kth -samp datasets. -samp 'SAMPLE_VOX1 SAMPLE_VOX2 ...': Specify which voxels belong to each class of interest. Each of the volumes should contain voxel values (keys) that are defined in -labeltable. You can specify multiple volumes, they all get catenated. Any volume can contain voxels from 1 or more classes. Each occurrence of -samp option must be paired with a -sig option. Think of each pair of '-sig, -samp' options as describing data on the same voxel grid; Think from the same subject. When specifying training data from K subjects, you will end up using K pairs of '-sig, -samp'. All volumes from the kth -samp instance should have the same voxel grid as each other and as that of the kth -sig datasets. -hspec FEATURE MIN MAX NBINS: Set histogram parameters for feature FEATURE FEATURE: String label of feature MIN, MAX: Range of histogram NBINS: Number of bins Use this option to set the histogram parameters for the features for the automatic parameter selection was lousy. You can specify for multiple features by using multiple -hspec instances. The only condition is that all feature labels (FEATURE) must be part of the set named in -features. -prefix PREF: PREF is the prefix for all output volume that are not debugging related. default: GenFeatDist -ShowTheseHists HISTNAMES: Show histograms specified by HISTNAMES and quit. HISTNAMES can specify just one .niml.hist file or a bunch of them using a space, or comma separated list. List multiple names between quotes. -overwrite: An option common to almost all AFNI programs. It is automatically turned on if you provide no PREF. -debug: Debugging level default: 1 -labeltable LT: Specify the label table default: 1

AFNI program: 3dGenPriors
3dGenPriors produces classification priors based on voxel signatures. At this stage, its main purpose is to speed up the performance of 3dSignatures when using the probabilistic method as opposed to SVM. Example: 3dGenPriors -sig sigs+orig \ -tdist train.niml.td \ -pprefix anat.p \ -cprefix anat.c \ -labeltable DSC.niml.lt \ -do pc Options: -sig SIGS: Signatures dataset. A dataset with F features per voxel. -tdist TDIST: Training results. This file is generated by 3dSignatures. ONLY training files generated by 3dSignatures' method 'prob' can be used by this program. The number of features in this file should match the number of features (F) in SIGS This file also contains the names of the K classes that will be references in the output datasets -prefix PREF: Specify root prefix and let program suffix it for output Volumes. This way you need not use the -*prefix options below. -pprefix PPREF: Prefix for probability dset -cprefix CPREF: Prefix for class dset If you use -regroup_classes then you can also specify: -pgprefix PGPREF, and -cgprefix CGPREF -labeltable LTFILE: Labeltable to attach to output dset This labeltable should contain all the classes in TDIST -cmask CMASK: Provide cmask expression. Voxels where expression is 0 are excluded from computations -mask MASK: Provide mask dset To run the program on one voxel only, you can set MASK to the key word VOX_DEBUG. In this mode a mask is created with only the one voxel specified in -vox_debug set to 1. -mrange M0 M1: Consider MASK only for values between M0 and M1, inclusive -do WHAT: Specify the output that this program should create. Each character in WHAT specifies an output. a 'c' produces the most likely class a 'p' produces probability of belonging to a class a 'pc' produces both of the above and that is the default. You'd be deranged to use anything else at the moment. -debug DBG: Set debug level -vox_debug 1D_DBG_INDEX: 1D index of voxel to debug. OR -vox_debug I J K: where I, J, K are the 3D voxel indices (not RAI coordinates in mm) -vox_debug_file DBG_OUTPUT_FILE: File in which debug information is output use '-' for stdout, '+' for stderr. -uid UID : User identifier string. It is used to generate names for temporary files to speed up the process. You must use different UID for different subjects otherwise you will run the risk of using bad temporary files. By default, uid is set to a random string. -use_tmp: Use temporary storage to speed up the program (see -uid ) This is the default -no_tmp: Opposite of use_tmp -pset PSET: Reuse probability output from an earlier run. -cset CSET: Reuse classification output from an earlier run. -regroup_classes 'C1 C2 C3': Regroup classes into parent classes C1 C2 C3 For this to work, the original classes must be named something like C1.*, C2.*, etc. This option can be used to replace @RegroupLabels script. For example: 3dGenPriors -sig sigs+orig \ -tdist train.niml.td \ -pprefix anat.p \ -cprefix anat.c \ -labeltable DSC.niml.lt \ -do pc \ -regroup_classes 'CSF GM WM Out' or if you have the output already, you can do: 3dGenPriors -sig sigs+orig \ -tdist train.niml.td \ -pset anat.p \ -cset anat.c \ -labeltable DSC.niml.lt \ -do pc \ -regroup_classes 'CSF GM WM Out' -classes 'C1 C2 C3': Classify into these classes only. Alternative is to classify from all the classes in the training data -features 'F1 F2 F3 ...': Use these features only. Otherwise use all features in the signature file will be used. Note that partial matching is used to resolve which features to keep from training set. If you want exact feature name matching, use option -strict_feature_match -strict_feature_match: Use strict feature name matching when resolving which feature to keep from the training set. -featgroups 'G1 G2 G3 ...': TO BE WRITTEN Example: -featgroups 'MEDI MAD. P2S' -ShowThisDist DIST: Show information obtained from the training data about the distribution of DIST. For example: - -ShowThisDist 'd(mean.20_mm|PER02)' Set DIST to ALL to see them all. -fast: Use OpenMPized routines (default). Considerably faster than alternative. -slow: Not -fast. ========================================================================= * This binary version of 3dGenPriors is NOT compiled using OpenMP, a semi-automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * However, the source code is compatible with OpenMP, and can be compiled with an OpenMP-capable compiler, such as gcc 8.x+, Intel's icc, and Oracle Developer Studio. * If you wish to compile this program with OpenMP, see the man page for your C compiler, and (if needed) consult the AFNI message board, and https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * However, it would probably be simplest to download a pre-compiled AFNI binary set that uses OpenMP! https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/index.html

AFNI program: 3dGetrow
Program to extract 1 row from a dataset and write it as a .1D file Usage: 3dGetrow [options] dataset OPTIONS: ------- Exactly ONE of the following three options is required: -xrow j k = extract row along the x-direction at fixed y-index of j and fixed z-index of k. -yrow i k = similar for a row along the y-direction -zrow i j = similar for a row along the z-direction -input ddd = read input from dataset 'ddd' (instead of putting dataset name at end of command line) -output ff = filename for output .1D ASCII file will be 'ff' (if 'ff' is '-', then output is to stdout, the default) N.B.: if the input dataset has more than one sub-brick, each sub-brick will appear as a separate column in the output file. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dGLMM
================== Welcome to 3dGLMM ================== Program for Voxelwise Generalized Linear Mixed-Models (GLMMs) +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 0.0.3, Feb 18, 2025 Author: Gang Chen (gangchen@mail.nih.gov) SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Introduction ------ ### Generalized Linear Mixed-Models (GLMM) Overview Generalized Linear Mixed-Models (GLMMs) extend Linear Mixed-Models (LMMs) to handle non-normal response variables, such as binary, count, or categorical data. The response variable in GLMMs can follow distributions like binomial, Poisson, or other members of the exponential family. ### 3dGLMM: Extension of 3dLMEr The program **3dGLMM** builds on **3dLMEr**, adding support for Student's *t*-distribution for model residuals in addition to the standard normal distribution. This functionality requires the R packages **glmmTMB**, **car**, and **emmeans**. Like **3dLMEr**, 3dGLMM automatically provides outputs for all main effects and interactions. However, users must explicitly request marginal effects and their comparisons through the options `-level` or `-slope` in 3dGLMM instead of `-gltcode` or -glfCode in 3dLMEr. 1. **Random-Effects Specification**: Random-effects components must be directly incorporated into the model specification via the `-model` option. The `-ranEff` option used in 3dLMEr is no longer needed. Users are responsible for formulating appropriate model structures. For detailed guidance, refer to the blog post: [How to specify individual-level random effects in hierarchical modeling] (https://discuss.afni.nimh.nih.gov/t/how-to-specify-individual-level-random-effects-in-hierarchical-modeling/6462). 2. **Marginal Effects and Pairwise Comparisons**: Users can specify marginal effects and pairwise comparisons through the options `-level` and `-slope`. ### Input and Output Formats 3dGLMM accepts input files in various formats, including AFNI, NIfTI, surface (`niml.dset`), or 1D. To match the output format with the input, append an appropriate suffix to the output option `-prefix` (e.g., `.nii` for NIfTI, `.niml.dset` for surface, or `.1D` for 1D). ### Incorporation of Explanatory Variables 3dGLMM supports various types of explanatory variables and covariates: - **Categorical variables**: Between- and within-subject factors. - **Quantitative variables**: Continuous predictors like age or behavioral data. #### Declaring Quantitative Variables When including quantitative variables, you must explicitly declare them using the `-qVars` option. Additionally, consider the **centering** of these variables: - Global centering. - Within-group (or within-condition) centering. For further guidance on centering, see: [AFNI documentation on centering] (https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/center.html). ### Installation of Required R Packages Before running 3dGLMM, ensure the following R packages are installed: - `glmmTMB` - `car` - `emmeans` - `snow` You can install them via AFNI’s R installation script: rPkgsInstall -pkgs "glmmTMB,car,emmeans,snow" Alternatively, install them directly in R: ``` install.packages("glmmTMB") install.packages("car") install.packages("emmeans") install.packages("snow") ``` ### Example Scripts The following example scripts demonstrate 3dGLMM applications. More examples will be added as scenarios are crowdsourced from users. If one of the examples matches your data structure, use it as a template to build your own script. ### Running 3dGLMM Once you’ve constructed your command script, run it in the terminal. Save the script as a text file (e.g., `GLMM.txt`) and execute it with: ``` nohup tcsh -x GLMM.txt & ``` Alternatively, for progress tracking, redirect output to a log file: ``` nohup tcsh -x GLMM.txt > diary.txt & nohup tcsh -x GLMM.txt |& tee diary.txt & ``` This method saves output in `diary.txt`, allowing you to review progress and troubleshoot if needed. Here’s a revised version with improved clarity, grammar, and formatting: --- ### Example 1: one within-individual factor and a quantitiave predictor ------------------------------------------------------------------------- 3dGLMM -prefix glmm.student -jobs 12 \ -family student.t \ -model 'task*age+(1|Subj)' \ -qVars 'age' \ -qVarCenters 0 \ -level LAB task CAT task \ -level LAB pos.slp2 CAT 1 FIX task=pos,age=2 \ -slope LAB pos.age CAT 1 FIX task=pos QUANT age \ -slope LAB task.by.age CAT task QUANT age \ -dataTable \ Subj age task InputFile \ s1 3.03 pos data/pos_s1+tlrc. \ s1 0.82 neg data/neg_s1+tlrc. \ s2 2.67 pos data/pos_s2+tlrc. \ s2 0.24 neg data/neg_s2+tlrc. \ ... #### Data Structure Overview This example involves a **within-individual factor** (task with two levels: *pos* and *neg*) and a **between-individual quantitative variable** (*age*). The GLMM analysis is conducted using a **Student's t-distribution** for the model residuals. #### Reserved Keywords for Post-Hoc Estimations The following four reserved keywords should not be used in custom specifications for post-hoc estimations: - **LAB**: Used to define a label for the estimated effect. - **CAT**: Specifies a categorical variable for which effects are estimated each level, and all possible pairwise comparisons. Use *1* for the intercept or overall mean of the model. - **FIX**: Indicates variables fixed at specific levels or values. - **QUANT**: Specifies the estimation of a slope for a quantitative variable. --- #### Explanations for Post-Hoc Estimations 1. **`-level LAB task CAT task`** - Estimates the effects for both levels of the task (*pos* and *neg*) and their contrast (evaluated at *age = 0*). 2. **`-level LAB pos.slp2 CAT 1 FIX task=pos,age=2`** - Estimates the effect of the *pos* task at *age = 2* (relative to the centered value of age). The number *1* represents the intercept or grand mean of the model. 3. **`-slope LAB pos.age CAT 1 FIX task=pos QUANT age`** - Estimates the slope effect of *age* for the *pos* task. The number *1* represents the intercept or grand mean of the model. 4. **`-slope LAB task.by.age CAT task QUANT age`** - Estimates the slope effect of *age* for both *pos* and *neg* tasks and their contrast. Options in alphabetical order: ------------------------------ -bounds lb ub: This option is for outlier removal. Two numbers are expected from the user: the lower bound (lb) and the upper bound (ub). The input data will be confined within [lb, ub]: any values in the input data that are beyond the bounds will be removed and treated as missing. Make sure the first number is less than the second. The default (the absence of this option) is no outlier removal. **NOTE**: Using the -bounds option to remove outliers should be approached with caution due to its arbitrariness. A more principled alternative is to use the -family option with a Student's t-distribution. -cio: Use AFNI's C io functions, which is the default. Alternatively, -Rio can be used. -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last in the script; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The order of the columns should not matter except that the last column has to be the one for input files, 'InputFile'. Unlike 3dGLMM, the subject column (Subj in 3dGLMM) does not have to be the first column; and it does not have to include a subject ID column under some situations Each row should contain only one input file in the table of long format (cf. wide format) as defined in R. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) When the table is part of the script, a backslash is needed at the end of each line (except for the last line) to indicate the continuation to the next line. Alternatively, one can save the context of the table as a separate file, e.g., calling it table.txt, and then in the script specify the data with '-dataTable @table.txt'. However, when the table is provided as a separate file, do NOT put any quotes around the square brackets for each sub-brick, otherwise the program would not properly read the files, unlike the situation when quotes are required if the table is included as part of the script. Backslash is also not needed at the end of each line, but it would not cause any problem if present. This option of separating the table from the script is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset. -dbgArgs: This option will enable R to save the parameters in a file called .3dGLMM.dbg.AFNI.args in the current directory so that debugging can be performed. -family: This option specifies the distribution of model residuals. Currently two families are supported: "Gaussian" (default) and "student.t". -help: this help message -IF var_name: var_name is used to specify the column name that is designated for input files of effect estimate. The default (when this option is not invoked is 'InputFile', in which case the column header has to be exactly as 'InputFile' This input file for effect estimates has to be the last column. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -level LAB ... CAT ... BY ... FIX ...: Specify the label, categorical variable .... -mask MASK: Process voxels inside this mask only. Default is no masking. -model FORMULA: Specify the model structure for all the variables. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. In the GLMM context the simplest model is "1+(1|Subj)" in which the random effect from each of the two subjects in a pair is symmetrically incorporated in the model. Each random-effects factor is specified within parentheses per formula convention in R. Any effects of interest and confounding variables (quantitative or categorical variables) can be added as fixed effects without parentheses. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached (otherwise the output would be saved in AFNI format). -qVarCenters VALUES: Specify centering values for quantitative variables identified under -qVars. Multiple centers are separated by commas (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -qVarCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the values are fed into -dataTable. -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarsCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ substantially in the average value of the covariate. -R2: Enabling this option will prompt the program to provide both conditional and marginal coefficient of determination (R^2) values associated with the adopted model. Marginal R^2 indicates the proportion of variance explained by the fixed effects in the model, while conditional R^2 represents the proportion of variance explained by the entire model, encompassing both fixed and random effects. Two sub-bricks labeled 'R2m' and 'R2c' will be provided in the output. -resid PREFIX: Output file name for the residuals. For AFNI format, provide prefix only without view+suffix. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. The sub-brick labeled with the '(Intercept)', if present, should be interpreted as the effect with each factor at the reference level (alphabetically the lowest level) for each factor and with each quantitative covariate at the center value. -Rio: Use R's io functions. The alternative is -cio. -show_allowed_options: list of allowed options -slope LAB ... CAT ... BY ... FIX ... QUANT ...: Specify the label, categorical variable .... -SS_type NUMBER: Specify the type for sums of squares in the F-statistics. Three options are: sequential (1), hierarchical (2), and marginal (3). When this option is absent (default), marginal (3) is automatically set. Some discussion regarding their differences can be found here: https://sscc.nimh.nih.gov/sscc/gangc/SS.html -vVarCenters VALUES: Specify centering values for voxel-wise covariates identified under -vVars. Multiple centers are separated by commas (,) within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -vVarsCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable yourself first before the files are fed under -dataTable. -vVars variable_list: Identify voxel-wise covariates with this option. Currently one voxel-wise covariate is allowed only. By default mean centering is performed voxel-wise across all subjects. Alternatively centering can be specified through a global value under -vVarsCenters. If the voxel-wise covariates have already been centered, set the centers at 0 with -vVarsCenters.

AFNI program: 3dGrayplot
Make a grayplot from a 3D+time dataset, sort of like Jonathan Power: https://www.ncbi.nlm.nih.gov/pubmed/27510328 https://www.jonathanpower.net/2017-ni-the-plot.html Result is saved to a PNG image for your viewing delight. * This style of plot is also called a carpet plot, but REAL carpets are much more attractive, IMHO. * The horizontal axis of the grayplot is time, and the vertical axis is all 3 spatial dimensions collapsed into 1. * Also see AFNI script @grayplot, as well as the QC output generated by afni_proc.py. Usage: 3dGrayplot [options] inputdataset OPTIONS: [lots of them] -------- -mask mset = Name of mask dataset * Voxels that are 0 in mset will not be processed. * Dataset must be byte-valued (8 bits: 0..255); shorts (16 bits) are also acceptable, but only values from 1.255 will be processed. * Each distinct value from 1..255 will be processed separately, and the output image will be ordered with the mask=1 voxels on top, mask=2 voxels next, and so on down the image. * A partition (e.g., mask=3) with fewer than 9 voxels will not be processed at all. * If there is more than one partition, horizontal dashed lines will drawn between them. * If '-mask' is not given, then all voxels will be used, except those at the very edge of a volume. Doing this is usually not a good idea, as the non-brain tissue will take up a lot of useless space in the output grayplot. -input dataset = Alternative way to input the dataset to process. -prefix ppp.png = Name for output file. * Default is Grayplot.png (if you don't use this option) * If the filename ends in '.jpg', a JPEG file is output. * If the filename ends in '.pgm', a PGM file is output. [PGM files can be manipulated with the NETPBM package.] * If the filename does not end in '.jpg' OR in '.png' OR in '.pgm', then '.png' will be added at the end. -dimen X Y = Output size of image in pixels. * X = width = time axis direction * Y = height = voxel/space dimensions * Defaults are X=1024 Y=512 -- suitable for screen display. * For publication, you might want more pixels, as in -dimen 1800 1200 which would be 6 inches wide by 4 inches high, at the usual 300 dots-per-inch (dpi) of high resolution image printing. ** Note that there are usually many more voxels in the Y direction than there are pixels in the output image. This fact requires coarsening the Y output grid and resampling the data to match. See the next option for a little more information about how this resampling is implemented. -oldresam = The method for resampling the processed dataset to the final grayscale image size was changed/improved in a major way. If you want to use the original method, then give this option. * The only reason for using this option is for comparison with the new method. * The new resampling method uses minimum-sidelobe local averaging when coarsening the grid (vertical direction Y = voxels/space) -- whose purpose is to reduce aliasing artifacts * And uses cubic interpolation when refining the grid (usually horizontal direction = time) -- whose purpose is purely beauty -- compared to the older linear interpolation. * Note that the collapsing of multiple voxels into one pixel in the Y direction will tend to cancel out signals that change sign within neighbors in the voxel ordering method you choose. (See the 'order' options below.) -polort p = Order of polynomials for detrending. * Default value is 2 (mean, slope, quadratic curve). * Use '-1' if data is already detrended and de-meaned. (e.g., is an AFNI errts.* file or other residual dataset) -fwhm f = FWHM of blurring radius to use in the dataset before making the image. * Each partition (i.e., mask=1, mask=2, ...) is blurred independently, as in program 3dBlurInMask. * Default value is 0 mm = no blurring. [In the past, the default value was 6.] * If the dataset was NOT previously blurred, a little spatial blurring here will help bring out larger scale features in the times series, which might otherwise look very noisy. ** The following four options control the ordering of ** ** voxels in the grayplot, in the vertical direction. ** -pvorder = Within each mask partition, order the voxels (top to bottom) by how well they match the two leading principal components of that partition. The result is to make the top part of each partition be made up of voxels with similar time series, and the bottom part will be more 'random looking'. ++ The presence of a lot of temporal structure in a grayplot of a 'errts' residual dataset indicates that the 'removal' of unwanted time series components did not work well. ++ Using '-pvorder' to put all the structured time series close together will make such problems more visible. ++ IMHO, this is the most useful ordering. -LJorder = Within each mask partition, order the voxels (top to bottom) by their Ljung-Box statistics, which is a measure of temporal correlation. ++ Experimental; probably not useful. -peelorder = Within each mask partition, order the voxels by how many 'peel' steps are needed to get from the partition boundary to a given voxel. ++ This ordering puts voxels in 'similar' geometrical positions sort-of close together in the image. And is usually not very interesting, IMHO. -ijkorder = Set the intra-partition ordering to the default, by dataset 3D index ('ijk'). ++ In AFNI's +tlrc ordering, this ordering primarily will be from Inferior to Superior in the brain (from top to bottom in the grayplot image). ++ This is the default ordering method, but not the best. ** These options control the scaling from voxel value to gray level ** -range X = Set the range of the data to be plotted to be 'X'. Each time series is first normalized by its values to: Z[i] = (t[i] - mean_t)/stdev_t. When this option is used, then: * a value of 0 will be plotted as middle-gray * a value of +X (or above) will be plotted as white * a value of -X (or below) will be plotted as black Thus, this option should be used with data that is centered around zero -- or will be so after '-polort' detrending. * For example, if you are applying this option to an afni_proc.py 'errts' (residuals) dataset, a good value of X to use is 3 or 4, since those values are in percents. * The @grayplot script uses '-range 3.89' since that is the value at which a standard normal N(0,1) deviate has a 1e-4 two-sided tail probability. (If nothing else, this sounds cool.) If you do NOT use '-range', then the data will be automatically normalized so each voxel time series has RMS value 1, and then the grayscale plot will be black-to-white being the min-to-max, where the min and max computed over the entire detrended and normalized dataset. * This default automatic normalizing and scaling makes it almost impossible to directly compare grayplots from different datasets. This difficulty is why the '-range' and '-percent' options were added. -percent = Use this option on 'raw' time series datasets, to compute the mean of each voxel timeseries and then use that value to scale the values to percent differences from the mean. * NOT suitable for use with a residual 'errts' dataset! * Should be combined with '-range'. * Detrending will be applied while calculating the mean. By default, that will be quadratic detrending of each voxel time series, but that can be changed with the '-polort' option. -raw_with_bounds A B = Use this option on 'raw' time series datasets, map values <= A to black, those >= B to white, and intermediate values to grays. * Can be used with any kind of dataset, but probably makes most sense to use with scaled ones (errts, fitts or all_runs). * Should NOT be combined with '-range' or '-percent'. ** Quick hack for Cesar Caballero-Gaudes, April 2018, by @AFNIman. As such, this program may be modified in the future to be more useful, or at least more beautifully gorgeous. ** Applied to 'raw' EPI data, the results may not be very informative. It seems to be more useful to look at the grayplot calculated from pre-processed data (e.g., time series registered, filtered, etc.). ** See also the script @grayplot, which can process the results from afni_proc.py and produce an image with the grayplot combined with a graph of the motion magnitude, and with the GM, WM, and CSF in different partitions. ** afni_proc.py uses this program to create grayplots of the residuals from regression analysis, as part of its Quality Control (QC) output. -------- EXAMPLE: -------- The following commands first generate a time series dataset, then create grayplots using each of the ordering methods (so you can compare them). No mask is given. 3dcalc -a jRandomDataset:64:64:30:256 -datum float \ -prefix Qsc.nii -expr 'abs(.3+cos(0.1*i))*sin(0.1*t+0.1*i)+gran(0,3)' 3dGrayplot -pvorder -prefix QscPV.png -input Qsc.nii -fwhm 8 3dGrayplot -ijkorder -prefix QscIJK.png -input Qsc.nii -fwhm 8 3dGrayplot -peelorder -prefix QscPEEL.png -input Qsc.nii -fwhm 8

AFNI program: 3dGroupInCorr
Usage: 3dGroupInCorr [options] * Also see https://afni.nimh.nih.gov/pub/dist/edu/latest/afni_handouts/afni20_instastuff.pdf * This program operates as a server for AFNI or SUMA. It reads in dataset collections that have been prepared by 3dSetupGroupInCorr, and then connects to the AFNI or SUMA GUI program (via TCP/IP). Then it waits for a command to be sent from AFNI/SUMA before it actually does anything. * The command from AFNI is sent when the user (you) clicks the 'InstaCorr Set' * * button in the [A] controller image viewer right-mouse-click popup menu; or, * * when you hold down the Shift and Control (Ctrl) keys on the keyboard at the * * same time you left-mouse-click in the image viewer. * (-: However, the new [Feb 2011] '-batch' option, described far below, :-) (-: lets you run 3dGroupInCorr by itself, without AFNI or SUMA, writing :-) (-: results to disk instead of transmitting them to the client program. :-) * At the same time as you run 3dGroupInCorr, you also have to run the AFNI GUI program, with a command like 'afni -niml'. 3dGroupInCorr by itself will only do something when AFNI sends it a command, which you do by using the 'InstaCorr Set' button on the [A] image viewer right-click popup menu, after 3dGroupInCorr has connected to AFNI. * When AFNI sends a seed voxel command, 3dGroupInCorr will extract that voxel times series from each input dataset, will compute the correlation map of each dataset with the corresponding seed time series, then will compute the voxel-wise collection of t-tests of that bunch of correlation maps, and return the resulting 3D volumes to AFNI for display. ++ A lot of computing can be required if there are a lot of datasets in the input collections. 3dGroupInCorr is carefully written to be fast. For example, on a Mac Pro with 8 3GHz CPUs, running with 1.2 GBytes of data (100 datasets each with 69K voxels), each group correlation map takes about 0.3 seconds to calculate and transmit to AFNI -- this speed is why it's called 'Insta'. * You must start AFNI with the '-niml' option to allow it to accept incoming TCP/IP socket connections. ++ Or you can press the 'NIML+PO' button in the GUI, if you forgot to type the AFNI command line correctly. ++ If you are running 3dGroupInCorr and AFNI on separate computers, you also have to setup 'host trusting' correctly -- for details, see the description of the '-ah' option, far below. * In the AFNI 'A' controller, once 3dGroupInCorr is connected to AFNI, you don't have to switch to 'GrpInCorr' on the 'InstaCorr' menu to use the 'InstaCorr Set' controls -- unlike the individual subject InstaCorr, which requires setup inside AFNI. For Group InstaCorr, the setup is already done in 3dSetupGroupInCorr. The ONLY reason for using the 'GrpInCorr' setup controls in AFNI is to change the value of the '-seedrad' option' radius interactively. * More detailed outline of processing in 3dGroupInCorr: ++ For each 3D+time dataset in the input dataset collections: -- Extract the seed voxel time series (averaging locally per 'seedrad') [you could do this manually with 3dmaskave] -- Correlate it with all other voxel time series in the same dataset [you could do this manually with 3dDeconvolve or 3dfim] -- Result is one 3D correlation map per input dataset -- The standard processing uses Pearson correlation between time series vectors. You can also pre-process the data to use Spearman (rank) correlation instead. This alteration must be done in program 3dSetupGroupInCorr, or with program 3dTransformGroupInCorr. ++ Then carry out the t-test between/among these 3D correlation maps, possibly allowing for dataset-level covariates. -- Actually, between the arctanh() of these maps: cf. RA Fisher: https://en.wikipedia.org/wiki/Fisher_transformation [you could do the arctanh() conversion manually via 3dcalc;] [then do the t-tests manually with 3dttest++; then convert] [the t-statistics to Z-scores using yet another 3dcalc run.] -- To be overly precise, if the correlation is larger than 0.999329, then the arctanh is clipped to 4.0, to avoid singularities. If you consider this clipping to be a problem, please go away. ++ The dataset returned to AFNI converts the t-statistic maps to Z-scores, for various reasons of convenience. -- Conversion is done via the same mechanism used in program cdf -t2z fitt TSTAT DOF -- The individual correlation maps that were t-test-ed are discarded. -- Unless you use the new [Jan 2011] '-sendall' option :-) * When 3dGroupInCorr starts up, it has to 'page fault' all the data into memory. This can take several minutes, if it is reading (say) 10 Gbytes of data from a slow disk. After that, if your computer has enough RAM, then the program should run pretty quickly. ++ If your computer DOESN'T have enough RAM to hold all the data, then this program will be painfully slow -- buy more memory! ++ Note that the .data file(s) are mapped directly into memory (mmap), rather than being read with standard file input methods (read function). ++ This memory-mapping operation may not work well on network-mounted drives, in which case you will have to run 3dGroupInCorr on the same computer with the data files [Feb 2016 -- but see the new '-read' option]. ++ However, 3dGroupInCorr does NOT need to be run on the same computer as AFNI or SUMA: see the '-ah' option (described far below). * Once 3dGroupInCorr is connected to AFNI, you can 'drive' the selection of seed points via the AFNI driver commands (e.g., via the plugout_drive program). For details, see the README.driver document. * One reason this program is a server (rather than being built in to AFNI) is that it is compiled to use OpenMP, which will let it make use of multiple CPU cores on the computer system :-) ++ For more information, see the very end of this '-help' output. * If you have only the .niml and .data files, and not original datasets, you can partially reconstruct the datasets by using the program 3dExtractGroupInCorr. =================================================================== COMMAND LINE OPTIONS [Most options are not case sensitive -- e.g., '-apair' == '-Apair'] =================================================================== -----------------------*** Input Files ***------------------------- -setA AAA.grpincorr.niml = Give the setup file (from 3dSetupGroupInCorr) that describes the first dataset collection: ++ This 'option' is MANDATORY (you have to input SOMETHING). ++ Of course, 'AAA' should be replaced with the correct name of your input dataset collection file! ++ 3dGroupInCorr can use byte-valued or short-valued data as produced by the '-byte' or '-short' options to 3dSetupGroupInCorr. ++ You can also put the '.data' filename here, or leave off the '.niml'; the program will look for these cases and patch the filename as needed. -setB BBB.grpincorr.niml = Give the setup file that describes the second dataset collection: ++ This option IS optional. ++ If you use only -setA, then the program computes a one-sample t-test. ++ If you use also -setB, then the program computes a two-sample t-test. -- The exact form of the 2-sample t-test used is controlled by one of the three options described below (which are mutually exclusive). ++ The sign of a two sample t-test is 'A-B'; that is, a positive result means that the A set of correlations average larger than the B set. ++ The output t-statistics are converted to Z-scores for transmission to AFNI, using the same code as the 'fitt_t2z(t,d)' function in 3dcalc: -- e.g, the output of the command ccalc 'fitt_t2z(4,15)' is 3.248705, showing that a t-statistic of 4 with 15 degrees-of-freedom (DOF) has the same p-value as a Z-score [N(0,1) deviate] of 3.248705. -- One reason for using Z-scores is that the DOF parameter varies between voxels when you choose the -unpooled option for a 2-sample t-test. -Apair = Instead of using '-setB', this option tells the program to use the '-setA' collection in its place; however, the seed location for this second copy of setA is a different voxel/node. The result is to contrast (via a paired t-test) the correlation maps from the different seeds. ++ For Alex Martin and his horde of myrmidons. -->> You cannot use '-Apair' with '-setB' or with '-batch'. ++ To use this in the AFNI GUI, you first have to set the Apair seed using the 'GIC: Apair Set' button on the image viewer right-click popup menu. After that, the standard 'InstaCorr Set' button will pick the new seed to contrast with the Apair seed. ++ Or you can select 'GIC: Apair MirrorOFF' to switch it to 'MirrorON*'. In that case, selecting 'InstaCorr Set' will automatically also set the Apair seed to the left-right mirror image location (+x -> -x). ++ The resulting correlation maps will have a positive (red) hotspot near the InstaCorr seed and a negative (blue) hotspot near the Apair seed. If you don't understand why, then your understanding of resting state FMRI correlation analyses needs some work. -->> It is regions AWAY from the positive and negative seeds that are potentially interesting -- significant results at region Q indicate a difference in 'connectivity' between Q and the two seeds. ++ In the case of mirroring, Q is asymmetrically 'connected' to one side of brain vs. the other; e.g., I've found that the left Broca's area (BA 45) makes a good seed -- much of the left temporal lobe is asymmetrically connected with respect to this seed and its mirror, but not so much of the right temporal lobe. -labelA aaa = Label to attach (in AFNI) to sub-bricks corresponding to setA. If you don't give this option, the label used will be the prefix from the -setA filename. -labelB bbb = Label to attach (in AFNI) to sub-bricks corresponding to setB. ++ At most the first 11 characters of each label will be used! ++ In the case of '-Apair', you can still use '-labelB' to indicate the label for the negative (Apair) seed; otherwise, the -setA filename will be used with 'AP:' prepended. -----------------------*** Two-Sample Options ***----------------------- -pooled = For a two-sample un-paired t-test, use a pooled variance estimator -unpooled = For a two-sample un-paired t-test, use an unpooled variance estimator ++ Statistical power declines a little, and in return, the test becomes a little more robust. -paired = Use a two-sample paired t-test ++ Which is the same as subtracting the two sets of 3D correlation maps, then doing a one-sample t-test. ++ To use '-paired', the number of datasets in each collection must be the same, and the datasets must have been input to 3dSetupGroupInCorr in the same relative order when each collection was created. (Duh.) ++ '-paired' is automatically turned on when '-Apair' is used. -nosix = For a 2-sample situation, the program by default computes not only the t-test for the difference between the samples, but also the individual (setA and setB) 1-sample t-tests, giving 6 sub-bricks that are sent to AFNI. If you don't want these 4 extra 1-sample sub-bricks, use the '-nosix' option. ++ See the Covariates discussion, below, for an example of how '-nosix' affects which covariate sub-bricks are computed. ++ In the case of '-Apair', you may want to keep these extra sub-bricks so you can see the separate maps from the positive and negative seeds, to make sure your results make sense. **-->> None of these 'two-sample' options means anything for a 1-sample t-test (i.e., where you don't use -setB or -Apair). -----------------*** Dataset-Level Covariates [May 2010] ***----------------- -covariates cf = Read file 'cf' that contains covariates values for each dataset input (in both -setA and -setB; there can only at most one -covariates option). Format of the file FIRST LINE --> subject IQ age LATER LINES --> Elvis 143 42 Fred 85 59 Ethel 109 49 Lucy 133 32 This file format should be compatible with 3dMEMA. ++ The first column contains the labels that must match the dataset labels stored in the input *.grpincorr.niml files, which are either the dataset prefixes or whatever you supplied in the 3dSetupGroupInCorr program via '-labels'. -- If you ran 3dSetupGroupInCorr before this update, its output .grpincorr.niml file will NOT have dataset labels included. Such a file cannot be used with -covariates -- Sorry. ++ The later columns contain numbers: the covariate values for each input dataset. -- 3dGroupInCorr does not allow voxel-level covariates. If you need these, you will have to use 3dttest++ on the '-sendall' output (of individual dataset correlations), which might best be done using '-batch' mode (cf. far below). ++ The first line contains column headers. The header label for the first column isn't used for anything. The later header labels are used in the sub-brick labels sent to AFNI. ++ If you want to omit some columns in file 'cf' from the analysis, you can do so with the standard AFNI column selector '[...]'. However, you MUST include column #0 first (the dataset labels) and at least one more numeric column. For example: -covariates Cov.table'[0,2..4]' to skip column #1 but keep columns #2, #3, and #4. ++ At this time, only the -paired and -pooled options can be used with covariates. If you use -unpooled, it will be changed to -pooled. -unpooled still works with a pure t-test (no -covariates option). -- This restriction might be lifted in the future. Or it mightn't. ++ If you use -paired, then the covariates for -setB will be the same as those for -setA, even if the dataset labels are different! -- This also applies to the '-Apair' case, of course. ++ By default, each covariate column in the regression matrix will have its mean removed (centered). If there are 2 sets of subjects, each set's matrix will be centered separately. -- See the '-center' option (below) to alter this default. ++ For each covariate, 2 sub-bricks are produced: -- The estimated slope of arctanh(correlation) vs covariate -- The Z-score of the t-statistic of this slope ++ If there are 2 sets of subjects, then each pair of sub-bricks is produced for the setA-setB, setA, and setB cases, so that you'll get 6 sub-bricks per covariate (plus 6 more for the mean, which is treated as a special covariate whose values are all 1). -- At present, there is no way to tell 3dGroupInCorr not to send all this information back to AFNI/SUMA. ++ The '-donocov' option, described later, lets you get the results calculated without covariates in addition to the results with covariate regression included, for comparison fun. -- Thus adding to the number of output bricks, of course. ++ EXAMPLE: If there are 2 groups of datasets (with setA labeled 'Pat', and setB labeled 'Ctr'), and one covariate (labeled IQ), then the following sub-bricks will be produced: # 0: Pat-Ctr_mean = mean difference in arctanh(correlation) # 1: Pat-Ctr_Zscr = Z score of t-statistic for above difference # 2: Pat-Ctr_IQ = difference in slope of arctanh(correlation) vs IQ # 3: Pat-Ctr_IQ_Zscr = Z score of t-statistic for above difference # 4: Pat_mean = mean of arctanh(correlation) for setA # 5: Pat_Zscr = Z score of t-statistic for above mean # 6: Pat_IQ = slope of arctanh(correlation) vs IQ for setA # 7: Pat_IQ_Zscr = Z score of t-statistic for above slope # 8: Ctr_mean = mean of arctanh(correlation) for setB # 9: Ctr_Zscr = Z score of t-statistic for above mean #10: Ctr_IQ = slope of arctanh(correlation) vs IQ for setB #11: Ctr_IQ_Zscr = Z score of t-statistic for above slope ++ However, the single-set results (sub-bricks #4-11) will NOT be computed if the '-nosix' option is used. ++ If '-sendall' is used, the individual dataset arctanh(correlation) maps (labeled with '_zcorr' at the end) will be appended to this list. These setA sub-brick labels will start with 'A_' and these setB labels with 'B_'. ++ If you are having trouble getting the program to read your covariates table file, then set the environment variable AFNI_DEBUG_TABLE to YES and run the program -- the messages may help figure out the problem. For example: 3dGroupInCorr -DAFNI_DEBUG_TABLE=YES -covariates cfile.txt |& more -->>**++ A maximum of 31 covariates are allowed. If you need more, then please consider the possibility that you are completely deranged or demented. *** CENTERING *** Covariates are processed using linear regression. There is one column in the regression matrix for each covariate, plus a column of all 1s for the mean value. 'Centering' refers to the process of subtracting some value from each number in a covariate's column, so that the fitted model for the covariate's effect on the data is zero at this subtracted value; the model (1 covariate) is: data[i] = mean + slope * ( covariate[i] - value ) where i is the dataset index. The standard (default) operation is that 'value' is the mean of the covariate[i] numbers. -center NONE = Do not remove the mean of any covariate. -center DIFF = Each set will have the means removed separately [default]. -center SAME = The means across both sets will be computed and subtracted. * This option only applies to a 2-sample unpaired test. * You can attach '_MEDIAN' after 'DIFF' or 'SAME' to have the centering be done at the median of covariate values, rather than the mean, as in 'DIFF_MEDIAN' or 'SAME_MEDIAN'. (Why you would do this is up to you, as always.) -center VALS A.1D [B.1D] This option (for Gang Chen) allows you to specify the values that will be subtracted from each covariate before the regression analysis. If you use this option, then you must supply a 1D file that gives the values to be subtracted from the covariates; if there are 3 covariates, then the 1D file for the setA datasets should have 3 numbers, and the 1D file for the setB datasets (if present) should also have 3 numbers. * For example, to put these values directly on the command line, you could do something like this: -center VALS '1D: 3 7 9' '1D: 3.14159 2.71828 0.91597' * As a special case, if you want the same values used for the B.1D file as in the A.1D file, you can use the word 'DITTO' in place of repeating the A.1D filename. * Of course, you only have to give the B.1D filename if there is a setB collection of datasets, and you are not doing a paired t-test. Please see the discussion of CENTERING in the 3dttest++ help output. If you change away from the default 'DIFF', you should really understand what you are doing, or an elephant may sit on your head, which no one wants. ---------------------------*** Other Options ***--------------------------- -seedrad r = Before performing the correlations, average the seed voxel time series for a radius of 'r' millimeters. This is in addition to any blurring done prior to 3dSetupGroupInCorr. The default radius is 0, but the AFNI user can change this interactively. -sendall = Send all individual subject results to AFNI, as well as the various group statistics. ++ These extra sub-bricks will be labeled like 'xxx_zcorr', where 'xxx' indicates which dataset the results came from; 'zcorr' denotes that the values are the arctanh of the correlations. ++ If there are a lot of datasets, then the results will be VERY large and take up a lot of memory in AFNI. **++ Use this option with some judgment and wisdom, or bad things might happen! (e.g., your computer runs out of memory.) ++ This option is also known as the 'Tim Ellmore special'. -donocov = If covariates are used, this option tells 3dGroupInCorr to also compute the results without using covariates, and attach those to the output dataset -- presumably to facilitate comparison. ++ These extra output sub-bricks have 'NC' attached to their labels. ++ If covariates are NOT used, this option has no effect at all. -dospcov = If covariates are used, compute the Spearman (rank) correlation coefficient of the subject correlation results vs. each covariate. ++ These extra sub-bricks are in addition to the standard regression analysis with covariates, and are added here at the request of the IMoM (PK). ++ These sub-bricks will be labeled as 'lll_ccc_SP', where 'lll' is the group label (from -labelA or -labelB) 'ccc' is the covariate label (from the -covariates file) '_SP' is the signal that this is a Spearman correlation ++ There will be one sub-brick produced for each covariate, for each group (1 or 2 groups). -clust PP = This option lets you input the results from a 3dClustSim run, to be transmitted to AFNI to aid with the interactive Clusterize. 3dGroupInCorr will look for files named PP.NN1_1sided.niml PP.NN1_2sided.niml PP.NN1_bisided.niml (and similarly for NN2 and NN3 clustering), plus PP.mask and if at least one of these .niml files is found, will send it to AFNI to be incorporated into the dataset. For example, if the datasets' average smoothness is 8 mm, you could do 3dClustSim -fwhm 8 -mask Amask+orig -niml -prefix Gclus 3dGroupInCorr ... -clust Gclus -->> Presumably the mask would be the same as used when you ran 3dSetupGroupInCorr, and the smoothness you would have estimated via 3dFWHMx, via sacred divination, or via random guesswork. It is your responsibility to make sure that the 3dClustSim files correspond properly to the 3dGroupInCorr setup! -->>++ This option only applies to AFNI usage, not to SUMA. ++ See the Clusterize notes, far below, for more information on using the interactive clustering GUI in AFNI with 3dGroupInCorr. -read = Normally, the '.data' files are 'memory mapped' rather than read into memory. However, if your files are on a remotely mounted server (e.g., a remote RAID), then memory mapping may not work. Or worse, it may seem to work, but return 'data' that is all zero. Use this '-read' option to force the program to read the data into allocated memory. ++ Using read-only memory mapping is a way to avoid over-filling the system's swap file, when the .data files are huge. ++ You must give '-read' BEFORE '-setA' or '-setB', so that the program knows what to do when it reaches those options! -ztest = Test the input to see if it is all zero. This option is for debugging, not for general use all the time. -ah host = Connect to AFNI/SUMA on the computer named 'host', rather than on the current computer system 'localhost'. ++ This allows 3dGroupInCorr to run on a separate system than the AFNI GUI. -- e.g., If your desktop is weak and pitiful, but you have access to a strong and muscular multi-CPU server (and the network connection is fast). ++ Note that AFNI must be setup with the appropriate 'AFNI_TRUSTHOST_xx' environment variable, so that it will allow the external socket connection (for the sake of security): -- Example: AFNI running on computer 137.168.0.3 and 3dGroupInCorr running on computer 137.168.0.7 -- Start AFNI with a command like afni -DAFNI_TRUSTHOST_01=137.168.0.7 -niml ... -- Start 3dGroupInCorr with a command like 3dGroupInCorr -ah 137.168.0.3 ... -- You may use hostnames in place of IP addresses, but numerical IP addresses will work more reliably. -- If you are very trusting, you can set NIML_COMPLETE_TRUST to YES to allow NIML socket connections from anybody. (This only affects AFNI programs, not any other software on your computer.) -- You might also need to adjust your firewall settings to allow the reception of TCP/IP socket connections from outside computers. Firewalls are a separate issue from setting up AFNI host 'trusting', and the mechanics of how you can setup your firewall permissions is not something about which we can give you advice. -np PORT_OFFSET: Provide a port offset to allow multiple instances of AFNI <--> SUMA, AFNI <--> 3dGroupIncorr, or any other programs that communicate together to operate on the same machine. All ports are assigned numbers relative to PORT_OFFSET. The same PORT_OFFSET value must be used on all programs that are to talk together. PORT_OFFSET is an integer in the inclusive range [1025 to 65500]. When you want to use multiple instances of communicating programs, be sure the PORT_OFFSETS you use differ by about 50 or you may still have port conflicts. A BETTER approach is to use -npb below. -npq PORT_OFFSET: Like -np, but more quiet in the face of adversity. -npb PORT_OFFSET_BLOC: Similar to -np, except it is easier to use. PORT_OFFSET_BLOC is an integer between 0 and MAX_BLOC. MAX_BLOC is around 4000 for now, but it might decrease as we use up more ports in AFNI. You should be safe for the next 10 years if you stay under 2000. Using this function reduces your chances of causing port conflicts. See also afni and suma options: -list_ports and -port_number for information about port number assignments. You can also provide a port offset with the environment variable AFNI_PORT_OFFSET. Using -np overrides AFNI_PORT_OFFSET. -max_port_bloc: Print the current value of MAX_BLOC and exit. Remember this value can get smaller with future releases. Stay under 2000. -max_port_bloc_quiet: Spit MAX_BLOC value only and exit. -num_assigned_ports: Print the number of assigned ports used by AFNI then quit. -num_assigned_ports_quiet: Do it quietly. Port Handling Examples: ----------------------- Say you want to run three instances of AFNI <--> SUMA. For the first you just do: suma -niml -spec ... -sv ... & afni -niml & Then for the second instance pick an offset bloc, say 1 and run suma -niml -npb 1 -spec ... -sv ... & afni -niml -npb 1 & And for yet another instance: suma -niml -npb 2 -spec ... -sv ... & afni -niml -npb 2 & etc. Since you can launch many instances of communicating programs now, you need to know wich SUMA window, say, is talking to which AFNI. To sort this out, the titlebars now show the number of the bloc of ports they are using. When the bloc is set either via environment variables AFNI_PORT_OFFSET or AFNI_PORT_BLOC, or with one of the -np* options, window title bars change from [A] to [A#] with # being the resultant bloc number. In the examples above, both AFNI and SUMA windows will show [A2] when -npb is 2. -NOshm = Do NOT reconnect to AFNI using shared memory, rather than TCP/IP, when using 'localhost' (i.e., AFNI and 3dGroupInCorr are running on the same system). ++ The default is to use shared memory for communication when possible, since this method of transferring large amounts of data between programs on the same computer is much faster. ++ If you have a problem with the shared memory communication, use '-NOshm' to use TCP/IP for all communications. ++ If you use '-VERB', you will get a very detailed progress report from 3dGroupInCorr as it computes, including elapsed times for each stage of the process, including transmit time to AFNI. -suma = Talk to suma instead of afni, using surface-based i/o data. -sdset_TYPE = Set the output format in surface-based batch mode to TYPE. For allowed values of TYPE, search for option called -o_TYPE in ConvertDset -help. Typical values would be: -sdset_niml, -sdset_1D, or -sdset_gii -quiet = Turn off the 'fun fun fun in the sun sun sun' informational messages. -verb = Print out extra informational messages for more fun! -VERB = Print out even more informational messages for even more fun fun!! -debug = Do some internal testing (slows things down a little) ---------------*** Talairach (+trlc) vs. Original (+orig) ***--------------- Normally, AFNI assigns the dataset sent by 3dGroupInCorr to the +tlrc view. However, you can tell AFNI to assign it to the +orig view instead. To do this, set environment variable AFNI_GROUPINCORR_ORIG to YES when starting AFNI; for example: afni -DAFNI_GROUPINCORR_ORIG=YES -niml This feature might be useful to you if you are doing a longitudinal study on some subject, comparing resting state maps before and after some treatment. -----------*** Group InstaCorr and AFNI's Clusterize function ***----------- In the past, you could not use Clusterize in the AFNI A controller at the same time that 3dGroupInCorr was actively connected. ***** This situation is no longer the case: ***** ****** Clusterize is available with InstaCorr! ****** In particular, the 'Rpt' (report) button is very useful with 3dGroupInCorr. If you use '-covariates' AND '-sendall', 3dGroupInCorr will send to AFNI a set of 1D files containing the covariates. You can use one of these as a 'Scat.1D' file in the Clusterize GUI to plot the individual subject correlations (averaged across a cluster) vs. the covariate values -- this graph can be amusing and even useful. -- If you don't know how to use this feature in Clusterize, then learn! ---------------*** Dataset-Level Scale Factors [Sep 2012] ***--------------- -scale sf = Read file 'sf' that contains a scale factor value for each dataset The file format is essentially the same as that for covariates: * first line contains labels (which are ignored) * each later line contains a dataset identifying label and a number FIRST LINE --> subject factor LATER LINES --> Elvis 42.1 Fred 37.2 Ethel 2.71828 Lucy 3.14159 * The arctanh(correlation) values from dataset Elvis will be multiplied by 42.1 before being put into the t-test analysis. * All values reported and computed by 3dGroupInCorr will reflect this scaling (e.g., the results from '-sendall'). * This option is for the International Man Of Mystery, PK. -- And just for PK, if you use this option in the form '-SCALE', then each value X in the 'sf' file is replaced by sqrt(X-3). --------------------------*** BATCH MODE [Feb 2011] ***----------------------- * In batch mode, instead of connecting AFNI or SUMA to get commands on what to compute, 3dGroupInCorr computes correlations (etc.) based on commands from an input file. ++ Batch mode works to produce 3D (AFNI, or NIfTI) or 2D surface-based (SUMA or GIFTI format) datasets. * Each line in the command file specifies the prefix for the output dataset to create, and then the set of seed vectors to use. ++ Each command line produces a distinct dataset. ++ If you want to put results from multiple commands into one big dataset, you will have to do that with something like 3dbucket or 3dTcat after running this program. ++ If an error occurs with one command line (e.g., a bad seed location is given), the program will not produce an output dataset, but will try to continue with the next line in the command file. ++ Note that I say 'seed vectors', since a distinct one is needed for each dataset comprising the inputs -setA (and -setB, if used). * Batch mode is invoked with the following option: -batch METHOD COMMANDFILENAME where METHOD specifies how the seed vectors are to be computed, and where COMMANDFILENAME specifies the file with the commands. ++ As a special case, if COMMANDFILENAME contains a space character, then instead of being interpreted as a filename, it will be used as the contents of a single line command file; for example: -batch IJK 'something.nii 33 44 55' could be used to produce a single output dataset named 'something.nii'. ++ Only one METHOD can be used per batch mode run of 3dGroupInCorr! You can't mix up 'IJK' and 'XYZ' modes, for example. ++ Note that this program WILL overwrite existing datasets, unlike most AFNI programs, so be careful. * METHOD must be one of the following strings (not case sensitive): ++ IJK ==> the 3D voxel grid index triple (i,j,k) is given in FILENAME, or IJKAVE which tells the program to extract the time series from each input dataset at that voxel and use that as the seed vector for that dataset (if '-seedrad' is given, then the seed vector will be averaged as done in interactive mode). ** This is the same mode of operation as the interactive seed picking via AFNI's 'InstaCorr Set' menu item. -- FILE line format: prefix i j k ++ XYZ ==> very similar to 'IJK', but instead of voxel indexes being or XYZAVE given to specify the seed vectors, the RAI (DICOM) (x,y,z) coordinates are given ('-seedrad' also applies). ** If you insist on using LPI (neurological) coordinates, as Some other PrograMs (which are Fine Software tooLs) do, set environment variable AFNI_INSTACORR_XYZ_LPI to YES, before running this program. -- FILE line format: prefix x y z ++ NODE ==> the index of the surface node where the seed is located. A simple line would contain a prefix and a node number. The prefix sets the output name and the file format, if you include the extension. See also -sdset_TYPE option. for controlling output format. The node number specifies the seed node. Because you might have two surfaces (-LRpairs option in 3dSetupGroupInCorr) you can add 'L', or 'R' to the node index to specify its hemisphere. For example: OccipSeed1 L720 OccipSeed2 R2033 If you don't specify the side in instances where you are working with two hemispheres, the default is 'L'. ++ MASKAVE ==> each line on the command file specifies a mask dataset; the nonzero voxels in that dataset are used to define the list of seed voxels that will be averaged to give the set of seed vectors. ** You can use the usual '[..]' and '<..>' sub-brick and value range selectors to modify the dataset on input. Do not put these selectors inside quotes in the command file! -- FILE line format: prefix maskdatasetname ++ IJKPV ==> very similar to IJKAVE, XYZAVE, and MASKAVE (in that order), ++ XYZPV but instead of extracting the average over the region ++ MASKPV indicated, extracts the Principal Vector (in the SVD sense; cf. program 3dLocalPV). ** Note that IJKPV and XYZPV modes only work if seedrad > 0. ** In my limited tests, the differences between the AVE and PV methods are very small. YMMV. ++ VECTORS ==> each line on the command file specifies an ASCII .1D file which contains the set of seed vectors to use. There must be as many columns in the .1D file as there are input datasets in -setA and -setB combined. Each column must be as long as the maximum number of time points in the longest dataset in -setA and -setB. ** This mode is for those who want to construct their own set of reference vectors in some clever way. ** N.B.: This method has not yet been tested! -- FILE line format: prefix 1Dfilename -----------------------*** NEW BATCH MODES [Aug 2012] ***-------------------- * These new modes allow you to specify a LOT of output datasets directly on the command line with a single option. They are: -batchRAND n prefix ==> scatter n seeds around in space and compute the output dataset for each of these seed points, where 'n' is an integer greater than 1. -batchGRID d prefix ==> for every d-th point along each of the x,y,z axes, create an output dataset, where 'd' is an integer in the range 1..9. Note that setting d=1 will use every voxel as a seed, and presumably produce a vast armada of datasets through which you'll have to churn. * Each output dataset gets a filename of the form 'prefix_xxx_yyy_zzz', where 'prefix' is the second argument after the '-batchXXXX' option, and 'xxx' is the x-axis index of the seed voxel, 'yyy' is the y-axis index of the seed voxel, and 'zzz' is the z-axis index of the seed voxel. * These options are like using the 'IJK' batch mode of operation at each seed voxel. The only difference is that the set of seed points is generated by the program rather than being given by the user (i.e., you). These two options differ only in the way the seed points are chosen (pseudo-randomly or regularly). ** You should be prepared for a LONG run and filling up a ** ** LOT of disk space when you use either of these options! ** ========================================================================= * This binary version of 3dGroupInCorr is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Authors: Bob Cox and Ziad Saad ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dHist
3dHist computes histograms using functions for generating priors. If you are not sure you need this particular program, use 3dhistog instead. Example: 3dHist -input sigs+orig \n Options: -input DSET: Dset providing values for histogram. Exact 0s are not counted -dind SB: Use sub-brick SB from the input rather than 0 -mask MSET: Provide mask dataset to select subset of input. -mask_range BOT TOP: Specify the range of values to consider from MSET. Default is anything non-zero -cmask CMASK: Provide cmask expression. Voxels where expression is 0 are excluded from computations. For example: -cmask '-a T1.div.r+orig -b T1.uni.r+orig -expr step(a/b-10)' -thishist HIST.niml.hist: Read this previously created histogram instead of forming one from DSET. Obviously, DSET, or -mask options are not needed -prefix PREF: Write histogram to niml file called PREF.niml.hist -equalized PREF: Write a histogram equalized version of the input dataset Histogram Creation Parameters: By default, the program will select bin number, bin width, and range automatically. You can also set the parameters manually with the following options. -nbin K: Use K bins. -min MIN: Minimum intensity. -max MAX: Maximum intensity. -binwidth BW: Bin width -ignore_out: Do not count samples outside the user specified range. -rhist RHIST.niml.hist: Use previously created histogram to set range and binwidth parameters. -showhist: Display histogram to stdout You can also graph it with: 1dRplot HistOut.niml.hist Histogram Queries: -at VAL: Set the value at which you want histogram values -get 'PAR1,PAR2,PAR3..': Return the following PAR* properties at VAL Choose from: freq: Frequency (normalized count) count: Count bin: Continuous bin location estimate cdf: Cumulative count rcdf: Reverse cumulative count (from the top) ncdf: The normalized version of cdf nrcdf: The reverse version of ncdf outl: 1.0-(2*smallest tail area) 0 means VAL splits area in the middle 1 means VAL is at either end of the histogram ALL: All the above. You can select multiple ones with something like: -get 'freq, count, bin' You can also set one of the PAR* to 'upvol' to get the volume (liters) of voxels with values exceeding VAL The use of upvol usually requires option -voxvol too. -voxvol VOL_MM3: A voxel's volume in mm^3. To be used with upvol if no dataset is available or if you want to override it. -val_at PAR PARVAL: Return the value (magnitude) where histogram property PAR is equal to PARVAL PAR can only be one of: cdf, rcdf, ncdf, nrcdf, upvol For upvol, PARVAL is in Liters -quiet: Return a concise output to simplify parsing. For the moment, this option only affects output of option -val_at Examples: #A histogram a la 3dhistog: 3dHist -input T1+orig. #Getting parameters from previously created histogram: 3dHist -thishist HistOut.niml.hist -at 144.142700 #Or the reverse query: 3dHist -thishist HistOut.niml.hist -val_at ncdf 0.132564 #Compute histogram and find dataset threshold (approximate) #such that 1.5 liters of voxels remain above it. 3dHist -prefix toy -input flair_axial.nii.gz -val_at upvol 1.5 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dhistog
++ 3dhistog: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] Compute histogram of 3D Dataset Usage: 3dhistog [editing options] [histogram options] dataset The editing options are the same as in 3dmerge (i.e., the options starting with '-1'). The histogram options are: -nbin # Means to use '#' bins [default=100] -dind i Means to take data from sub-brick #i, rather than #0 -omit x Means to omit the value 'x' from the count; -omit can be used more than once to skip multiple values. -mask m Means to use dataset 'm' to determine which voxels to use -roi_mask r Means to create a histogram for each non-zero value in dataset 'r'. If -mask option is also used, dataset 'r' is masked by 'm' before creating the histograms. -doall Means to include all sub-bricks in the calculation; otherwise, only sub-brick #0 (or that from -dind) is used. -noempty Only output bins that are not empty. This does not apply to NIML output via -prefix. -notitle Means to leave the title line off the output. -log10 Output log10() of the counts, instead of the count values. This option cannot be used with -pdf or with -prefix -pdf Output the counts divided by the number of samples. This option is only valid with -prefix -min x Means specify minimum (inclusive) of histogram. -max x Means specify maximum (inclusive) of histogram. -igfac Means to ignore sub-brick scale factors and histogram-ize the 'raw' data in each volume. Output options for integer and floating point data By default, the program will determine if the data is integer or float even if the data is stored as shorts with a scale factor. Integer data will be binned by default to be 100 or the maximum number of integers in the range, whichever is less. For example, data with the range (0..20) gives 21 bins for each integer, and non-integral bin boundaries will be raised to the next integer (2.3 will be changed to 3, for instance). If the number of bins is higher than the number of integers in the range, the bins will be labeled with floating point values, and multiple bins may be zero between the integer values Float data will be binned by default to 100 bins with absolute limits for the min and max if these are specified as inclusive. For example, float data ranging from (0.0 to 20.0) will be binned into bins that are 0.2 large (0..0.199999, 0.2..0.399999,...,19.8..20.0) To have bins divided at 1.0 instead, specify the number of bins as 20 Bin 0 is 0..0.9999, Bin 1 is 1.0 to 1.9999, ..., Bin 20 is 19 to 20.0000 giving a slight bias to the last bin -int Treat data and output as integers -float Treat data and output as floats -unq U.1D Writes out the sorted unique values to file U.1D. This option is not allowed for float data If you have a problem with this, write Ziad S. Saad (saadz@mail.nih.gov) -prefix HOUT: Write a copy of the histogram into file HOUT.1D you can plot the file with: 1dplot -hist -sepscl -x HOUT.1D'[0]' HOUT.1D'[1,2]' or 1dRplot -input HOUT.1D Without -prefix, the histogram is written to stdout. Use redirection '>' if you want to save it to a file. The format is a title line, then three numbers printed per line: bottom-of-interval count-in-interval cumulative-count There is no 1dhistog program, for the simple reason that you can use this program for the same purpose, as in this example: 3dhistog -nbin 50 -notitle -min 0 -max .01 err.1D > ehist.1D 1dplot -hist -x ehist.1D'[0]' -xlabel 'err.1D' -ylabel 'histo' ehist.1D'[1]' -- by RW Cox, V Roopchansingh, and ZS Saad INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dICC
================== Welcome to 3dICC ================== AFNI Program for IntraClass Correlation (ICC) Analysis #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 1.0, Oct 4, 2023 Author: Gang Chen (gangchen@mail.nih.gov) Website - ATM SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Usage: ------ Intraclass correlation (ICC) measures the extent of consistency, agreement or reliability of an effect (e.g., BOLD respoonse) across two or more measures. 3dICC is a program that computes whole-brain voxel-wise ICC when each subject has two or more effect estimates (e.g., sessions, scanners, etc. ). All three typical types of ICC are available through proper model specification: ICC(1, 1), ICC(2,1) and ICC(3,1). The latter two types are popular in neuroimaging because ICC(1,1) is usually applicable for scenarios such as twins. The program can be applied to even wider situations (e.g., incorporation of confounding effects or more than two random-effects variables). The modeling approaches are laid out in the following paper: Chen, G., Taylor, P.A., Haller, S.P., Kircanski, K., Stoddard, J., Pine, D.S., Leibenluft, E., Brotman, M.A., Cox, R.W., 2018. Intraclass correlation: Improved modeling approaches and applications for neuroimaging. Human Brain Mapping 39, 1187–1206. https://doi.org/10.1002/hbm.23909 Currently it provides in the output the ICC value and the corresponding F-statistic at each voxel. In future, inferences for intercept and covariates may be added. Input files for 3dICC can be in AFNI, NIfTI, or surface (niml.dset) format. Two input scenarios are considered: 1) effect estimates only, and 2) effect estimates plus their t-statistic values which are used for weighting based on the precision contained in the t-statistic. In addition to R installation, the following R packages need to be installed in R first before running 3dICC: "lme4", "blme" and "metafor". In addition, the "snow" package is also needed if one wants to take advantage of parallel computing. To install these packages, run the following command at the terminal: rPkgsInstall -pkgs "blme,lme4,metafor,snow" Alternatively you may install them in R: install.packages("blme") install.packages("lme4") install.packages("metafor") install.packages("snow") Once the 3dICC command script is constructed, it can be run by copying and pasting to the terminal. Alternatively (and probably better) you save the script as a text file, for example, called ICC.txt, and execute it with the following (assuming on tc shell), nohup tcsh -x ICC.txt & or, nohup tcsh -x ICC.txt > diary.txt & nohup tcsh -x ICC.txt |& tee diary.txt & The advantage of the latter commands is that the progression is saved into the text file diary.txt and, if anything goes awry, can be examined later. Example 1 --- Compute ICC(2,1) values between two sessions. With the option -bounds, values beyond [-2, 2] will be treated as outliers and considered as missing. If you want to set a range, choose the bounds that make sense with your input data. ------------------------------------------------------------------------- 3dICC -prefix ICC2 -jobs 12 \ -mask myMask+tlrc \ -model '1+(1|session)+(1|Subj)' \ -bounds -2 2 \ -dataTable \ Subj session InputFile \ s1 one s1_1+tlrc'[pos#0_Coef]' \ s1 two s1_2+tlrc'[pos#0_Coef]' \ ... s21 two s21_2+tlrc'[pos#0_Coef]' \ ... Example 2 --- Compute ICC(3,1) values between two sessions. With the option -bounds, values beyond [-2, 2] will be treated as outliers and considered as missing. If you want to set a range, choose the bounds that make sense with your input data. ------------------------------------------------------------------------- 3dICC -prefix ICC3 -jobs 12 \ -mask myMask+tlrc \ -model '1+session+(1|Subj)' \ -bounds -2 2 \ -dataTable \ Subj session InputFile \ s1 one s1_1+tlrc'[pos#0_Coef]' \ s1 two s1_2+tlrc'[pos#0_Coef]' \ ... s21 two s21_2+tlrc'[pos#0_Coef]' \ ... Example 3 --- Compute ICC(3,1) values between two sessions with both effect estimates and their t-statistics as input. The subject column is explicitly declared because it is named differently from the default ('Subj'). ------------------------------------------------------------------------- 3dICC -prefix ICC3 -jobs 12 \ -mask myMask+tlrc \ -model '1+age+session+(1|Subj)' \ -bounds -2 2 \ -Subj 'subject' \ -tStat 'tFile' \ -dataTable \ subject age session tFile InputFile \ s1 21 one s1_1+tlrc'[pos#0_tstat]' s1_1+tlrc'[pos#0_Coef]' \ s1 21 two s1_2+tlrc'[pos#0_tstat]' s1_2+tlrc'[pos#0_Coef]' \ ... s21 28 two s21_2+tlrc'[pos#0_tstat]' s21_2+tlrc'[pos#0_Coef]' \ ... Example 4 --- Compute ICC(2,1) values between two sessions while controlling for age effect. With the option -bounds, values beyond [-2, 2] will be be treated as outliers and considered as missing. If you want to set a range, choose the bounds that make sense with your input data. ------------------------------------------------------------------------- 3dICC -prefix ICC2a -jobs 12 \ -mask myMask+tlrc \ -model '1+age+(1|session)+(1|Subj)' \ -bounds -2 2 \ -Subj 'subjct' \ -InputFile 'inputfile' \ -dataTable \ subject age session inputfile \ s1 21 one s1_1+tlrc'[pos#0_Coef]' \ s1 21 two s1_2+tlrc'[pos#0_Coef]' \ ... s21 28 two s21_2+tlrc'[pos#0_Coef]' \ ... Options in alphabetical order: ------------------------------ -bounds lb ub: This option is for outlier removal. Two numbers are expected from the user: the lower bound (lb) and the upper bound (ub). The input data will be confined within [lb, ub]: any values in the input data that are beyond the bounds will be removed and treated as missing. Make sure the first number less than the second. You do not have to use this option to censor your data! -cio: Use AFNI's C io functions, which is default. Alternatively -Rio can be used. -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The first column is fixed and reserved with label 'Subj', and the last is reserved for 'InputFile'. Each row should contain only one effect estimate in the table of long format (cf. wide format) as defined in R. The level labels of a factor should contain at least one character. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) The context of the table can be saved as a separate file, e.g., called table.txt. In the 3dICC script, specify the data with '-dataTable @table.txt'. Do NOT put any quotes around the square brackets for each sub-brick; Otherwise, the program cannot properly read the files. This option is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset. -dbgArgs: This option will enable R to save the parameters in a file called .3dICC.dbg.AFNI.args in the current directory so that debugging can be performed. -help: this help message -IF var_name: var_name is used to specify the last column name that is designated for input files of effect estimate. The default (when this option is not invoked is 'InputFile', in which case the column header has to be exactly as 'InputFile'. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -mask MASK: Process voxels inside this mask only. Default is no masking. -model FORMULA: Specify the model structure for all the variables. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. Suppose that each subject ('subj') has two sessions ('ses'), a model ICC(2,1) without any covariate is "1+(1|ses)+(1|subj)" while one for ICC(3,1) is "1+ses+(1|subj)". Each random-effects factor is specified within parentheses per formula convention in R. Any confounding effects (quantitative or categorical variables) can be added as fixed effects without parentheses. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. The sub-brick labeled with the '(Intercept)', if present, should be interpreted as the effect with each factor at the reference level (alphabetically the lowest level) for each factor and with each quantitative covariate at the center value. -qVarCenters VALUES: Specify centering values for quantitative variables identified under -qVars. Multiple centers are separated by commas (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -qVarsCetners) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the values are fed into -dataTable. -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarsCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ significantly in the average value of the covariate. 3) Within-subject covariates are better modeled with 3dICC. -Rio: Use R's io functions. The alternative is -cio. -show_allowed_options: list of allowed options -Subj var_name: var_name is used to specify the column name that is designated as as the measuring entity variable (usually subject). The default (when this option is not invoked) is 'Subj', in which case the column header has to be exactly as 'Subj'. -tStat col_name: col_name is used to specify the column name that is designated as as the t-statistic. The default (when this option is not invoked) is 'NA', in which case no t-stat is provided as part of the input; otherwise declare the t-stat column name with this option.

AFNI program: 3dinfill
A program to fill holes in a volumes. 3dinfill <-input DSET> Options: -input DSET: Fill volume DSET -prefix PREF: Use PREF for output prefix. -Niter NITER: Do not allow the fill function to do more than NITER passes. A -1 (default) lets the function go to a maximum of 500 iterations. You will be warned if you run our of iterations and holes persist. -blend METH: Sets method for assigning a value to a hole. MODE: Fill with most frequent neighbor value. Use MODE when filling integral valued data such as ROIs or atlases. AVG: Fill with average of neighboring values. AUTO: Use MODE if DSET is integral, AVG otherwise. SOLID: No blending, brutish fill. See also -minhits SOLID_CLEAN: SOLID, followed by removal of dangling chunks Dangling chunks are defined as non-zero regions that surround lesser holes, i.e. holes that have less than MH. The cleanup step is not iterative though, and you are most likely better off using option -ed to do the cleanup. -minhits MH: Crietrion for considering a zero voxel to be a hole MH refers to the total number of directions along which a zero voxel is considered surrounded by non zero values. a value of 1 is the least strict criterion, and a value of 3 is the strictest. This parameter can only be used with -blend SOLID -ed N V: Erode N times then dilate N times to get rid of hanging chunks. Values filled in by this process get value V. -mask MSET: Provide mask dataset to select subset of input. -mask_range BOT TOP: Specify the range of values to consider from MSET. Default is anything non-zero. -mrange BOT TOP: Same as option -mask_range -cmask CMASK: Provide cmask expression. Voxels where expression is 0 are excluded from computations. For example: -cmask '-a T1.div.r+orig -b T1.uni.r+orig -expr step(a/b-10)' NOTE: For the moment, masking is only implemented for the SOLID* fill method. Example 1: Starting from a whole head mask that has some big holes in it where CSF and cavities are. Fill the inside of the mask and remove dangling chunks in the end with -ed 3dinfill -blend SOLID -ed 3 1 -prefix filledmask \ -minhits 2 -input holymask+orig. This program will be slow for high res datasets with large holes. If you are trying to fill holes in masks, consider also: 3dmask_tool -fill_holes

AFNI program: 3dinfo
Prints out sort-of-useful information from a 3D dataset's header Usage: 3dinfo [-verb OR -short] dataset [dataset ...] ~1~ -verb means to print out lots of stuff -VERB means even more stuff [including slice time offsets] -short means to print out less stuff [now the default] -no_hist means to omit the HISTORY text -h: Mini help, at time, same as -help in many cases. -help: The entire help output -HELP: Extreme help, same as -help in majority of cases. -h_view: Open help in text editor. AFNI will try to find a GUI editor -hview : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_web: Open help in web browser. AFNI will try to find a browser. -hweb : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_find WORD: Look for lines in this programs's -help output that match (approximately) WORD. -h_raw: Help string unedited -h_spx: Help string in sphinx loveliness, but do not try to autoformat -h_aspx: Help string in sphinx with autoformatting of options, etc. -all_opts: Try to identify all options for the program from the output of its -help option. Some options might be missed and others misidentified. Use this output for hints only. ---------------------------------------------------------------------- Alternative Usage 1 (without either of the above options): ~1~ Output a large block of text per dataset. This has multiple options: -label2index label dataset : output index corresponding to label ~2~ example: 3dinfo -label2index aud#0_Coef stats.FT+tlrc Prints to stdout the index corresponding to the sub-brick with the name label, or a blank line if label not found. The ONLY output is this sub-brick index. This is intended for used in a script, as in this tcsh fragment: set face = `3dinfo -label2index Face#0 AA_Decon+orig` set hous = `3dinfo -label2index House#0 AA_Decon+orig` 3dcalc -a AA_Decon+orig"[$face]" -b AA_Decon+orig"[$hous]" ... * Added per the request and efforts of Colm Connolly. -niml_hdr dataset : output entire NIML-formatted header ~2~ example: 3dinfo -niml_hdr stats.FT+tlrc Prints to stdout the NIML-formatted equivalent of the .HEAD file. -subbrick_info dataset : output only sub-brick part of info ~2~ example: 3dinfo -subbrick_info stats.FT+tlrc Prints to stdout only the part of the full '3dinfo -VERB. output that includes sub-brick info. The first such line might look like: -- At sub-brick #0 'Full_Fstat' datum type is float: 0 to 971.2 ---------------------------------------------------------------------- Alternate Usage 2: ~1~ 3dinfo <OPTION> [OPTION ..] dataset [dataset ...] Outputs a specific piece of information depending on OPTION. This can form a table of outputs per dataset. ============================================================== Options producing one value (string) ~2~ ============================================================== -exists: 1 if dset is loadable, 0 otherwise This works on prefix also. -id: Idcodestring of dset -is_labeltable: 1 if dset has a labeltable attached. -is_atlas: 1 if dset is an atlas. -is_atlas_or_labeltable: 1 if dset has an atlas or has a labeltable. -is_nifti: 1 if dset is NIFTI format, 0 otherwise -is_slice_timing_nz: is there slice timing, and is it not uniformly 0 -dset_extension: show filename extension for valid dataset (e.g. .nii.gz) -storage_mode: show internal storage mode of dataset (e.g. NIFTI) -space: dataset's space -gen_space: datasets generic space -av_space: AFNI format's view extension for the space -nifti_code: what AFNI would use for an output NIFTI (q)sform_code -is_oblique: 1 if dset is oblique -handedness: L if orientation is Left handed, R if it is right handed -obliquity: Angle from plumb direction. Angles of 0 (or close) are for cardinal orientations -prefix: Return the prefix -prefix_noext: Return the prefix without extensions -ni: Return the number of voxels in i dimension -nj: Return the number of voxels in j dimension -nk: Return the number of voxels in k dimension -nijk: Return ni*nj*nk -nv: Return number of points in time or the number of sub-bricks -nt: same as -nv -n3: same as -ni -nj -nk -n4: same as -ni -nj -nk -nv -nvi: The maximum sub-brick index (= nv -1 ) -nti: same as -nvi -ntimes: Return number of sub-bricks points in time This is an option for debugging use, stay away from it. -max_node: For a surface-based dset, return the maximum node index -di: Signed displacement per voxel along i direction, aka dx -dj: Signed displacement per voxel along j direction, aka dy -dk: Signed displacement per voxel along k direction, aka dz -d3: same as -di -dj -dk -adi: Voxel size along i direction (abs(di)) -adj: Voxel size along j direction (abs(dj)) -adk: Voxel size along k direction (abs(dk)) -ad3: same as -adi -adj -adk -voxvol: Voxel volume in cubic millimeters -oi: Volume origin along the i direction -oj: Volume origin along the j direction -ok: Volume origin along the k direction -o3: same as -oi -oj -ok -dcx: volumetric center in x direction (DICOM coordinates) -dcy: volumetric center in y direction (DICOM coordinates) -dcz: volumetric center in z direction (DICOM coordinates) -dc3: same as -dcx -dcy -dcz -tr: The TR value in seconds. -dmin: The dataset's minimum value, scaled by fac -dmax: The dataset's maximum value, scaled by fac -dminus: The dataset's minimum value, unscaled. -dmaxus: The dataset's maximum value, unscaled. -smode: Dset storage mode string. -header_name: Value of dset structure (sub)field 'header_name' -brick_name: Value of dset structure (sub)field 'brick_name' -iname: Name of dset as input on the command line -orient: Value of orientation string. For example, LPI means: i direction grows from Left(negative) to Right(positive). j direction grows from Posterior (neg.) to Anterior (pos.) k direction grows from Inferior (neg.) to Superior (pos.) -extent: The spatial extent of the dataset along R, L, A, P, I and S -Rextent: Extent along R -Lextent: Extent along L -Aextent: Extent along P -Pextent: Extent along P -Iextent: Extent along I -Sextent: Extent along S -all_names: Value of various dset structures handling filenames. ============================================================== Options producing one value per sub-brick ~2~ ============================================================== -fac: Return the float scaling factor -label: The label of each sub-brick -datum: The data storage type -min: The minimum value, scaled by fac -max: The maximum value, scaled by fac -minus: The minimum value, unscaled. -maxus: The maximum value, unscaled. ============================================================== Options producing multiple values (strings of multiple lines) ~2~ ============================================================== You can specify the delimiter between sub-brick parameters with -sb_delim DELIM. Default DELIM is "|" -labeltable: Show label table, if any -labeltable_as_atlas_points: Show label table in atlas point format. -atlas_points: Show atlas points list, if any -history: History note. -slice_timing: Show slice timing. ============================================================== Options affecting output format ~2~ ============================================================== -header_line: Output as the first line the names of attributes in each field (column) -hdr: Same as -header_line -sb_delim SB_DELIM: Delimiter string between sub-brick values Default SB_DELIM is "|" -NA_flag NAFLAG: String to use when a field is not found or not applicable. Default is "NA" -atr_delim ATR_DELIM: Delimiter string between attributes Default ATR_DELIM is the tab character. ============================================================== Options for displaying ijk_to_xyz matrices ~2~ ============================================================== A set of functions for displaying the matrices that tell us where the data actually is in space! These 4x4---well 3x4, in practice, because the bottom row of the matrix *must* be (0, 0, 0, 1)--- can be related to the NIFTI sform and qform matrices (which are LPI native), but these aform_* matrices are RAI (DICOM) native. There are several types of matrices. Linear affine are the most general (containing translation, rotation, shear and scaling info), followed by orthogonal (no shear info; only translation, rotation and scale), followed by cardinal (no rotation info; only translation and scale). The 'scale' info is the voxel sizes. The 'translation' determines the origin location in space. The 'rotation' describes a, well, rotation relative to the scanner coords---this is the dreaded 'obliquity'. The 'shear'... well, that could also be present, but it is not common, at least to describe just-acquired data: it would tilt the axes away from being mutually 90 deg to each other (i.e., they wouldn't be orthogonal); this would likely just result from an alignment process. Note: the NIFTI sform can be linear affine, in general; in practice, it is often just orthogonal. The NIFTI qform is a quaternion representation of the orthogonalized sform; if sform is orthogonal, then they contain the same information (common, but not required). The aform_real matrix is AFNI's equivalent of the NIFTI sform; it *can* encode general linear affine mappings. (In practice, it rarely does so.) The aform_orth is the orthogonalized aform_real, and thus equivalent to the NIFTI qform. If aform_real is orthogonal (no shear info), then these two matrices are equal. The aform_card is the cardinalized form of the aform_orth; NIFTI does not have an equivalent. AFNI typically uses this matrix to display your data on a rectangle that is parallel to your computer screen, without any need to regrid/resample the data (hence, no blurring introduced). This can be though of displaying your dataset in a way that you *wish* your subject had been oriented. Note that if there is no obliquity in the acquired data (that is, aform_orth does not contain any rotation relative to the scanner coords), then aform_card == aform_orth. The aform_card is an AFNI convenience (ha!) matrix, it does not have an equivalent in the NIFTI stable of matrices. -aform_real: Display full 3x4 'aform_real' matrix (AFNI's RAI equivalent of the sform matrix in NIFTI, may contain obliquity info), with comment line first. -aform_real_oneline: Display full 'aform_real' matrix (see '-aform_real') as 1 row of 12 numbers. No additional comment. -aform_real_refit_ori XXX: Display full 3x4 'aform_real' matrix (see '-aform_real') *if* the dset were reoriented (via 3drefit) to new orient XXX. Includes comment line first. -is_aform_real_orth: if true, aform_real == aform_orth, which should be a very common occurrence. -aform_orth: Display full 3x4 'aform_orth' matrix (AFNI's RAI matrix equivalent of the NIFTI quaternion, which may contain obliquity info), with comment line first. This matrix is the orthogonalized form of aform_real, and veeery often AFNI-produced dsets, we will have: aform_orth == aform_real. -perm_to_orient YYY: Display 3x3 permutation matrix to go from the dset's current orientation to the YYY orient. ============================================================== Options requiring dataset pairing at input ~2~ ============================================================== 3dinfo allows you to make some comparisons between dataset pairs. The comparison is always done in both directions whether or not the answer can be different. For example: 3dinfo -same_grid dset1 dset2 will output two values, one comparing dset1 to dset2 and the second comparing dset2 to dset1. With -same_grid, the answers will always be identical, but this might be different for other queries. This behaviour allows you to mix options requiring dataset pairs with those that do not. For example: 3dinfo -header_line -prefix -n4 -same_grid \ DSET1+orig DSET2.nii DSET3.nii DSET4.nii -same_grid: Output 1 if the grid is identical between two dsets 0 otherwise. For -same_grid to be 1, all of -same_dim, -same_delta, -same_orient, -same_center, and -same_obl must return 1 -same_dim: 1 if dimensions (nx,ny,nz) are the same between dset pairs -same_delta: 1 if voxels sizes are the same between dset pairs -same_orient: 1 if orientation is the same between dset pairs -same_center: 1 if geometric center is the same between dset pairs -same_obl: 1 if obliquity is the same between dset pairs -same_all_grid: Equivalent to listing all of -same_dim -same_delta -same_orient, -same_center, and -same_obl on the command line. -val_diff: Output the sum of absolute differences of all voxels in the dataset pair. A -1.0 value indicates a grid mismatch between volume pairs. -sval_diff: Same as -val_diff, but the sum is divided (scaled) by the total number of voxels that are not zero in at least one of the two datasets. -monog_pairs: Instead of pairing each dset with the first, pair each couple separately. This requires you to have an even number of dsets on the command line Examples with csh syntax using datasets in your afni binaries directory ~1~ 0- First get some datasets with which we'll play set dsets = ( `apsearch -list_all_afni_P_dsets` ) 1- The classic 3dinfo $dsets[1] 2- Produce a table of results using 1-value-options for two datasets 3dinfo -echo_edu -prefix_noext -prefix -space -ni -nj -nk -nt \ $dsets[1-2] 3- Use some of the options that operate on pairs, mix with other options 3dinfo -echo_edu -header_line -prefix -n4 -same_grid $dsets[1-4] ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dIntracranial
++ 3dIntracranial: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. D. Ward [7m*+ WARNING:[0m This program (3dIntracranial) is old, obsolete, and not maintained! ++ 3dSkullStrip is almost always superior to 3dIntracranial :) 3dIntracranial - performs automatic segmentation of intracranial region. This program will strip the scalp and other non-brain tissue from a high-resolution T1 weighted anatomical dataset. ** Nota Bene: the newer program 3dSkullStrip should also be considered ** for this functionality -- it usually works better. ----------------------------------------------------------------------- Usage: ----- 3dIntracranial -anat filename => Filename of anat dataset to be segmented [-min_val a] => Minimum voxel intensity limit Default: Internal PDF estimate for lower bound [-max_val b] => Maximum voxel intensity limit Default: Internal PDF estimate for upper bound [-min_conn m] => Minimum voxel connectivity to enter Default: m=4 [-max_conn n] => Maximum voxel connectivity to leave Default: n=2 [-nosmooth] => Suppress spatial smoothing of segmentation mask [-mask] => Generate functional image mask (complement) Default: Generate anatomical image [-quiet] => Suppress output to screen -prefix pname => Prefix name for file to contain segmented image ** NOTE **: The newer program 3dSkullStrip will probably give better segmentation results than 3dIntracranial! ----------------------------------------------------------------------- Examples: -------- 3dIntracranial -anat elvis+orig -prefix elvis_strip 3dIntracranial -min_val 30 -max_val 350 -anat elvis+orig -prefix strip 3dIntracranial -nosmooth -quiet -anat elvis+orig -prefix elvis_strip ----------------------------------------------------------------------- ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dInvFMRI
Usage: 3dInvFMRI [options] Program to compute stimulus time series, given a 3D+time dataset and an activation map (the inverse of the usual FMRI analysis problem). ------------------------------------------------------------------- OPTIONS: -data yyy = *OR* = Defines input 3D+time dataset [a non-optional option]. -input yyy = -map aaa = Defines activation map; 'aaa' should be a bucket dataset, each sub-brick of which defines the beta weight map for an unknown stimulus time series [also non-optional]. -mapwt www = Defines a weighting factor to use for each element of the map. The dataset 'www' can have either 1 sub-brick, or the same number as in the -map dataset. In the first case, in each voxel, each sub-brick of the map gets the same weight in the least squares equations. [default: all weights are 1] -mask mmm = Defines a mask dataset, to restrict input voxels from -data and -map. [default: all voxels are used] -base fff = Each column of the 1D file 'fff' defines a baseline time series; these columns should be the same length as number of time points in 'yyy'. Multiple -base options can be given. -polort pp = Adds polynomials of order 'pp' to the baseline collection. The default baseline model is '-polort 0' (constant). To specify no baseline model at all, use '-polort -1'. -out vvv = Name of 1D output file will be 'vvv'. [default = '-', which is stdout; probably not good] -method M = Determines the method to use. 'M' is a single letter: -method C = least squares fit to data matrix Y [default] -method K = least squares fit to activation matrix A -alpha aa = Set the 'alpha' factor to 'aa'; alpha is used to penalize large values of the output vectors. Default is 0. A large-ish value for alpha would be 0.1. -fir5 = Smooth the results with a 5 point lowpass FIR filter. -median5 = Smooth the results with a 5 point median filter. [default: no smoothing; only 1 of these can be used] ------------------------------------------------------------------- METHODS: Formulate the problem as Y = V A' + F C' + errors where Y = data matrix (N x M) [from -data] V = stimulus (N x p) [to -out] A = map matrix (M x p) [from -map] F = baseline matrix (N x q) [from -base and -polort] C = baseline weights (M x q) [not computed] N = time series length = length of -data file M = number of voxels in mask p = number of stimulus time series to estimate = number of parameters in -map file q = number of baseline parameters and ' = matrix transpose operator Next, define matrix Z (Y detrended relative to columns of F) by -1 Z = [I - F(F'F) F'] Y ------------------------------------------------------------------- The method C solution is given by -1 V0 = Z A [A'A] This solution minimizes the sum of squares over the N*M elements of the matrix Y - V A' + F C' (N.B.: A' means A-transpose). ------------------------------------------------------------------- The method K solution is given by -1 -1 W = [Z Z'] Z A and then V = W [W'W] This solution minimizes the sum of squares of the difference between the A(V) predicted from V and the input A, where A(V) is given by -1 A(V) = Z' V [V'V] = Z'W ------------------------------------------------------------------- Technically, the solution is unidentfiable up to an arbitrary multiple of the columns of F (i.e., V = V0 + F G, where G is an arbitrary q x p matrix); the solution above is the solution that is orthogonal to the columns of F. -- RWCox - March 2006 - purely for experimental purposes! ===================== EXAMPLE USAGE ===================================== ** Step 1: From a training dataset, generate activation map. The input dataset has 4 runs, each 108 time points long. 3dDeconvolve is used on the first 3 runs (time points 0..323) to generate the activation map. There are two visual stimuli (Complex and Simple). 3dDeconvolve -x1D xout_short_two.1D -input rall_vr+orig'[0..323]' \ -num_stimts 2 \ -stim_file 1 hrf_complex.1D -stim_label 1 Complex \ -stim_file 2 hrf_simple.1D -stim_label 2 Simple \ -concat '1D:0,108,216' \ -full_first -fout -tout \ -bucket func_ht2_short_two -cbucket cbuc_ht2_short_two N.B.: You may want to de-spike, smooth, and register the 3D+time dataset prior to the analysis (as usual). These steps are not shown here -- I'm presuming you know how to use AFNI already. ** Step 2: Create a mask of highly activated voxels. The F statistic threshold is set to 30, corresponding to a voxel-wise p = 1e-12 = very significant. The mask is also lightly clustered, and restricted to brain voxels. 3dAutomask -prefix Amask rall_vr+orig 3dcalc -a 'func_ht2_short+orig[0]' -b Amask+orig -datum byte \ -nscale -expr 'step(a-30)*b' -prefix STmask300 3dmerge -dxyz=1 -1clust 1.1 5 -prefix STmask300c STmask300+orig ** Step 3: Run 3dInvFMRI to estimate the stimulus functions in run #4. Run #4 is time points 324..431 of the 3D+time dataset (the -data input below). The -map input is the beta weights extracted from the -cbucket output of 3dDeconvolve. 3dInvFMRI -mask STmask300c+orig \ -data rall_vr+orig'[324..431]' \ -map cbuc_ht2_short_two+orig'[6..7]' \ -polort 1 -alpha 0.01 -median5 -method K \ -out ii300K_short_two.1D 3dInvFMRI -mask STmask300c+orig \ -data rall_vr+orig'[324..431]' \ -map cbuc_ht2_short_two+orig'[6..7]' \ -polort 1 -alpha 0.01 -median5 -method C \ -out ii300C_short_two.1D ** Step 4: Plot the results, and get confused. 1dplot -ynames VV KK CC -xlabel Run#4 -ylabel ComplexStim \ hrf_complex.1D'{324..432}' \ ii300K_short_two.1D'[0]' \ ii300C_short_two.1D'[0]' 1dplot -ynames VV KK CC -xlabel Run#4 -ylabel SimpleStim \ hrf_simple.1D'{324..432}' \ ii300K_short_two.1D'[1]' \ ii300C_short_two.1D'[1]' N.B.: I've found that method K works better if MORE voxels are included in the mask (lower threshold) and method C if FEWER voxels are included. The above threshold gave 945 voxels being used to determine the 2 output time series. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dISC
================== Welcome to 3dISC ================== Program for Voxelwise Inter-Subject Correlation (ISC) Analysis #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 1.0.8, Feb 14, 2025 Author: Gang Chen (gangchen@mail.nih.gov) SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Introduction ------ Intersubject correlation (ISC) quantifies the similarity or synchronization of BOLD responses between two subjects experiencing the same stimulus, such as watching a movie or listening to music. The analysis is performed voxelwise using linear mixed-effects modeling, as detailed in the following paper: Chen, G., Taylor, P.A., Shin, Y.W., Reynolds, R.C., Cox, R.W., 2017. *Untangling the Relatedness among Correlations, Part II: Inter-Subject Correlation Group Analysis through Linear Mixed-Effects Modeling.* NeuroImage, 147, 825-840. **Input Requirements:** The input files for 3dISC consist of voxelwise correlation values from all subject pairs. If these correlations have not been Fisher-transformed, the `-r2z` option in 3dISC should be used to apply the transformation. When analyzing multiple groups, ISC values across groups must also be provided unless the groups are analyzed separately. Input files can be in AFNI, NIfTI, or surface (niml.dset) format. For *n* subjects, a total of *n(n-1)/2* input files should be supplied, ensuring no duplicate pairs. **Output:** 3dISC generates voxelwise effect estimates (e.g., ISC values) along with the corresponding t-statistics. **Preprocessing Recommendations:** For data preprocessing guidelines, refer to Appendix B of the above paper. To compute voxelwise ISC of time series between any two subjects, AFNI’s `3dTcorrelate` can be used. The LME platform supports a wide range of explanatory variables, including categorical variables (both between- and within-subject factors) and quantitative variables (e.g., age, behavioral data). However, the responsibility of correctly specifying the weights for each effect (e.g., contrasts) falls on the user. Determining the appropriate number and order of predictors can be particularly challenging, especially when dealing with more than two factor levels or interaction effects. To navigate this complexity, it is essential to understand two common factor coding strategies: **dummy coding** and **deviation coding**. A helpful resource on these coding systems can be found here: https://stats.idre.ucla.edu/r/library/r-library-contrast-coding-systems-for-categorical-variables/ ### Example Scripts The four example scripts provided below demonstrate various modeling scenarios. If any of them resemble your data structure, you can use them as templates to build your own script. More examples may be added in the future, and user- contributed scenarios (including yours) are welcome. ### Required R Packages Before running 3dISC, ensure that the following R packages are installed: To install via the AFNI command line: rPkgsInstall -pkgs "lme4,snow" Alternatively, you can install them directly in R: install.packages("lme4") install.packages("snow") Once the 3dISC command script is prepared, you can run it by copying and pasting it into the terminal. However, a more practical approach is to save the script as a text file (e.g., `ISC.txt`) and execute it using the following command (assuming you are using the **tcsh** shell): nohup tcsh -x ISC.txt & Alternatively, to capture the output for later review, use one of the following commands: nohup tcsh -x ISC.txt > diary.txt & or nohup tcsh -x ISC.txt |& tee diary.txt & or, The advantage of these latter commands is that they log the execution progress into diary.txt, allowing you to review the output and troubleshoot any issues if something goes wrong. Example 1 --- Simplest case: ISC analysis for one group of subjects without any explanatory variables. In other words, the effect of interest is the ISC at the populaton level. The output is the group ISC plus its t-statistic. The components within parentheses in the -model specifications are R notations for random effects. ------------------------------------------------------------------------- 3dISC -prefix ISC -jobs 12 \ -mask myMask+tlrc \ -model '1+(1|Subj1)+(1|Subj2) \ -dataTable \ Subj1 Subj2 InputFile \ s1 s2 s1_s2+tlrc \ s1 s3 s1_s3+tlrc \ s1 s4 s1_s4+tlrc \ s1 s5 s1_s5+tlrc \ s1 s6 s1_s6+tlrc \ s1 s7 s1_s7+tlrc \ ... s2 s3 s2_s3+tlrc \ s2 s4 s2_s4+tlrc \ s2 s5 s2_s5+tlrc \ ... Example 2 --- ISC analysis with two groups (G1 and G2). Three ISCs can be inferred at the population level, G11 (ISC among subjects within the first group G1), G22 (ISC among subjects within the second group G2), and G12 (ISC between subjects in the first group G1 and those in the second group G2). The research interest can be various comparisons among G11, G22 and G12, and this is the reason the group column 'grp' is coded with three types of population ISC: G11, G22 and G12. By default each factor (categorical variable) is internally quantified in the model using deviation coding with alphabetically the last level as the reference. Notice the semi-esoteric weights for those comparisons with -gltCode: the first weight corresponds to the intercept in the model, which is the average effect across all the factor levels (and corresponds to the zero value of a quantitative variable if present). If dummy coding is preferred, check out the next script below. The components within parentheses in the -model specifications are R notations for random effects. Here is a good reference about factor coding strategies: https://stats.idre.ucla.edu/r/library/r-library-contrast-coding-systems-for-categorical-variables/ ------------------------------------------------------------------------- 3dISC -prefix ISC2a -jobs 12 \ -mask myMask+tlrc \ -model 'grp+(1|Subj1)+(1|Subj2)' \ -gltCode ave '1 0 -0.5' \ -gltCode G11 '1 1 0' \ -gltCode G12 '1 0 1' \ -gltCode G22 '1 -1 -1' \ -gltCode G11vG22 '0 2 1' \ -gltCode G11vG12 '0 1 -2' \ -gltCode G12vG22 '0 1 2' \ -gltCode ave-G12 '0 0 -1.5' \ -dataTable \ Subj1 Subj2 grp InputFile \ s1 s2 G11 s1_2+tlrc \ s1 s3 G11 s1_3+tlrc \ s1 s4 G11 s1_4+tlrc \ ... s1 s25 G12 s1_25+tlr \ s1 s26 G12 s1_26+tlr \ s1 s27 G12 s1_26+tlr \ ... s25 s26 G22 s25_26+tlr \ s25 s27 G22 s25_27+tlr \ s25 s48 G22 s51_28+tlr \ ... The above script is equivalent to the one below. The only difference is that we force 3dISC to adopt dummy coding by adding a zero in the -model specification, which makes the weight coding much more intuitive. In this particular case, the three weights are associated with the three categories, G11, G12 and G22 (no intercept is assumed in the model as requested with the zero (0) in the model specifications). ** Alert ** This coding strategy, using no intercept, only works when there is a single explanatory variable (e.g., 'group' in this example). For cases with more than one explanatory variable, consider adopting other coding methods. ------------------------------------------------------------------------- 3dISC -prefix ISC2b -jobs 12 \ -model '0+grp+(1|Subj1)+(1|Subj2)' \ -gltCode ave '0.5 0 0.5' \ -gltCode G11 '1 0 0' \ -gltCode G12 '0 1 0' \ -gltCode G22 '0 0 1' \ -gltCode G11vG22 '1 0 -1' \ -gltCode G11vG12 '1 -1 0' \ -gltCode G12vG22 '0 1 -1' \ -gltCode ave-G12 '0.5 -1 0.5' \ -dataTable \ Subj1 Subj2 grp InputFile \ s1 s2 G11 s1_2+tlrc \ s1 s3 G11 s1_3+tlrc \ s1 s4 G11 s1_4+tlrc \ ... s1 s25 G12 s1_25+tlr \ s1 s26 G12 s1_26+tlr \ s1 s27 G12 s1_26+tlr \ ... s25 s26 G22 s25_26+tlr \ s25 s27 G22 s25_27+tlr \ s25 s48 G22 s51_28+tlr \ ... There is a third way to analyze this same dataset if we are NOT interested in the between-group ISC, G12. First, we adopt deviation coding for the two groups by replacing two groups G1 and G2 with 0.5 and -0.5. Then add up the two values for each row (each subject pair), resulting in three possible values of 1, -1 and 0. Put those three values in the group column in the data table. ------------------------------------------------------------------------- 3dISC -prefix ISC2c -jobs 12 \ -model 'grp+(1|Subj1)+(1|Subj2)' \ -qVars grp \ -gltCode ave '1 0' \ -gltCode G11vG22 '0 1' \ -gltCode G11 '1 0.5' \ -gltCode G22 '1 -0.5' \ -dataTable \ Subj1 Subj2 grp InputFile \ s1 s2 1 s1_2+tlrc \ s1 s3 1 s1_3+tlrc \ s1 s4 1 s1_4+tlrc \ ... s1 s25 0 s1_25+tlr \ s1 s26 0 s1_26+tlr \ s1 s27 0 s1_26+tlr \ ... s25 s26 -1 s25_26+tlr \ s25 s27 -1 s25_27+tlr \ s25 s48 -1 s51_28+tlr \ ... Example 3 --- ISC analysis for one group of subjects. The only difference from Example 1 is that we want to add an explanatory variable 'Age'. Before the age values are incorporated in the data table, do two things: 1) center the age by subtracting the cener (e.g., overall mean) from each subject's age, and 2) for each subject pair (each row in the data table) add up the two ages (after centering). The components within parentheses in the -model specifications are R notations for random effects. ------------------------------------------------------------------------- 3dISC -prefix ISC3 -jobs 12 \ -mask myMask+tlrc \ -model 'Age+(1|Subj1)+(1|Subj2)' \ -qVars Age \ -gltCode ave '1 0' \ -gltCode Age '0 1' \ -dataTable \ Subj1 Subj2 Age InputFile \ s1 s2 2 s1_s2+tlrc \ s1 s3 5 s1_s3+tlrc \ s1 s4 -4 s1_s4+tlrc \ s1 s5 3 s1_s5+tlrc \ s1 s6 -2 s1_s6+tlrc \ s1 s7 -1 s1_s7+tlrc \ ... s2 s3 2 s2_s3+tlrc \ s2 s4 4 s2_s4+tlrc \ s2 s5 -5 s2_s5+tlrc \ ... Example 4 --- ISC analysis with two groups of subject (Sex: females and males) plus a quantitative explanatory variable (Age). We are going to combine the modeling strategy in the third analysis of Example 2 with Example 3. In addition, we consider the interaction between Sex and Age by adding their product as another column (called 'SA' in the data table). The components within parentheses in the -model specifications are R notations for random effects. ------------------------------------------------------------------------- 3dISC -prefix ISC2c -jobs 12 \ -mask myMask+tlrc \ -model 'Sex+Age+SA+(1|Subj1)+(1|Subj2)' \ -qVars 'Sex,Age,SA' \ -gltCode ave '1 0 0 0' \ -gltCode G11vG22 '0 1 0 0' \ -gltCode G11 '1 0.5 0 0' \ -gltCode G22 '1 -0.5 0 0' \ -gltCode Age '0 0 1 0' \ -gltCode Age1vAge2 '0 0 0 1' \ -gltCode Age1 '0 0 1 0.5' \ -gltCode Age2 '0 0 1 -0.5' \ -dataTable \ Subj1 Subj2 Sex Age SA InputFile \ s1 s2 1 2 2 s1_2+tlrc \ s1 s3 1 5 5 s1_3+tlrc \ s1 s4 1 -4 -4 s1_4+tlrc \ ... s1 s25 0 -2 0 s1_25+tlr \ s1 s26 0 -1 0 s1_26+tlr \ s1 s27 0 3 0 s1_26+tlr \ ... s25 s26 -1 4 -4 s25_26+tlr \ s25 s27 -1 -5 5 s25_27+tlr \ s25 s48 -1 2 -2 s51_28+tlr \ ... Example 5 --- ISC analysis with two conditions (C1 and C2). The research interest is regarding the contrast of ISC between the two conditions. The basic strategy is to convert the data to the contrast between the conditions. In other words, obtain the contrast of ISC after the Fisher-transformation between the two conditions for each subject pair with a command like the following: 3dcalc -a subj1_subj2_cond1 -b subj1_subj2_cond2 -expr 'atanh(a)-atanh(b)' -prefix subj1_subj2 The function of inverse hyperbolic tangent 'atanh' is the same as the Fisher z-transform. Then follow Example 1 with the contrasts from the above 3dcalc output as input. Options in alphabetical order: ------------------------------ -cio: Use AFNI's C io functions, which is default. Alternatively -Rio can be used. -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last in the script; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The table should contain at least three columns, two of which are for the two subjects in each pair, 'Subj1' and 'Subj2'. These two columns code the labels of the two subjects involved for each ISC file that is listed in the column 'InputFile'. The order of the columns does not matter. Any subject-level explanatory variables (e.g., age, sex, etc.) can be specified as columns in the table. Each row should contain only one ISC file in the table of long format (cf. wide format) as defined in R. The level labels of a factor should contain at least one character. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) The context of the table can be saved as a separate file, e.g., called table.txt. Do not forget to include a backslash at the end of each row. In the script specify the data with '-dataTable @table.txt'. This option is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset. -dbgArgs: This option will enable R to save the parameters in a file called .3dISC.dbg.AFNI.args in the current directory so that debugging can be performed. -gltCode label weights: Specify the label and weights of interest. The weights should be surrounded with quotes. -help: this help message -IF var_name: var_name is used to specify the column name that is designated for input files of effect estimate. The default (when this option is not invoked is 'InputFile', in which case the column header has to be exactly as 'InputFile' This input file for effect estimates has to be the last column. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -mask MASK: Process voxels inside this mask only. Default is no masking. -model FORMULA: Specify the model structure for all the variables. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. In the ISC context the simplest model is "1+(1|Subj1)+(1|Subj2)"in while the random effect from each of the two subjects in a pair is symmetrically incorporated in the model. Each random-effects factor is specified within parentheses per formula convention in R. Any effects of intereste and confounding variables (quantitative or categorical variables) can be added as fixed effects without parentheses. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached (otherwise the output would be saved in AFNI format). -qVarCenters VALUES: Specify centering values for quantitative variables identified under -qVars. Multiple centers are separated by commas (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -qVarsCetners) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the values are fed into -dataTable. -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarsCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ substantially in the average value of the covariate. -r2z: This option performs Fisher transformation on the response variable (input files) if it is correlation value. Do not invoke the option if the transformation has already been applied. -Rio: Use R's io functions. The alternative is -cio. -show_allowed_options: list of allowed options -Subj1 var_name: var_name is used to specify the column name that is designated as as the first measuring entity variable (usually subject). This option, combined with the another option '-Subj2', forms a pair of two subjects; the order between the two subjects does not matter. The default (when the option is not invoked) is 'Subj1', in which case the column header has to be exactly as 'Subj1'. -Subj2 var_name: var_name is used to specify the column name that is designated as as the first measuring entity variable (usually subject). This option, combined with the another option '-Subj1', forms a pair of two subjects; the order between the two subjects does not matter. The default (when the option is not invoked) is 'Subj2', in which case the column header has to be exactly as 'Subj1'.

AFNI program: 3dkmeans
++ 3dkmeans: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: avovk 3d+t Clustering segmentation, command-line version. Based on The C clustering library. Copyright (C) 2002 Michiel Jan Laurens de Hoon. USAGE: 3dkmeans [options] options: -v, --version Version information -f filename: Input data to be clustered. You can specify multiple filenames in sequence and they will be catenated internally. e.g: -f F1+orig F2+orig F3+orig ... or -f F1+orig -f F2+orig -f F3+orig ... -input filename: Same as -f -mask mset Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be printed from 'dataset'. Note that the mask dataset and the input dataset must have the same number of voxels. -mrange a b Means to further restrict the voxels from 'mset' so that only those mask values between 'a' and 'b' (inclusive) will be used. If this option is not given, all nonzero values from 'mset' are used. Note that if a voxel is zero in 'mset', then it won't be included, even if a < 0 < b. -cmask 'opts' Means to execute the options enclosed in single quotes as a 3dcalc-like program, and produce produce a mask from the resulting 3D brick. Examples: -cmask '-a fred+orig[7] -b zork+orig[3] -expr step(a-b)' produces a mask that is nonzero only where the 7th sub-brick of fred+orig is larger than the 3rd sub-brick of zork+orig. -cmask '-a fred+orig -expr 1-bool(k-7)' produces a mask that is nonzero only in the 7th slice (k=7); combined with -mask, you could use this to extract just selected voxels from particular slice(s). Notes: * You can use both -mask and -cmask in the same run - in this case, only voxels present in both masks will be dumped. * Only single sub-brick calculations can be used in the 3dcalc-like calculations - if you input a multi-brick dataset here, without using a sub-brick index, then only its 0th sub-brick will be used. * Do not use quotes inside the 'opts' string! -u jobname Allows you to specify a different name for the output files. (default is derived from the input file name) -prefix PREFIX Allows you to specify a prefix for the output volumes. Default is the same as jobname There are two output volumes, one for the cluster membership and one with distance measures. The distance dataset, mostly for debugging purposes is formatted as follows: Sub-brick 0: Dc = 100*(1-Ci)+100*Di/(Dmax) with Ci the cluster number for voxel i, Di the distance of voxel i to the centroid of its assigned cluster, Dmax is the maximum distance in cluster Ci. Sub-bricks 1..k: Dc0k contains the distance of a voxel's data to the centroid of cluster k. Sub-brick k+1: Dc_norm = (1.0-Di/Ei)*100.0, where Ei is the smallest distance of voxel i to the remaining clusters that is larger than Di. -g [0..8] Specifies distance measure for clustering Note: Weight is a vector as long as the signatures and used when computing distances. However for the moment, all weights are set to 1 0: No clustering 1: Uncentered correlation distance Same as Pearson distance, except the means of v and s are not removed when computing correlation. 2: Pearson distance = (1-Weighted_Pearson_Correlation(v,s)) 3: Uncentered correlation distance, absolute value Same as abs(Pearson distance), except the means of v and s are not removed when computing correlation. 4: Pearson distance, absolute value = (1-abs(Weighted_Pearson_Correlation(v,s))) 5: Spearman's rank distance = (1-Spearman_Rank_Correlation(v,s)) No weighting is used 6: Kendall's distance = (1-Kendall_Tau(v,s)) No weighting is used 7: Euclidean distance between v and s = 1/sum(weight) * sum(weight[i]*(v[i]-s[i])^2) 8: City-block distance = 1/sum(weight) * sum(weight[i]*abs(v[i]-s[i])) (default for -g is 1, 7 if input has one value per voxel) -k number Specify number of clusters -remap METH Reassign clusters numbers based on METH: NONE: No remapping (default) COUNT: based on cluster size ascending iCOUNT: COUNT, descending MAG: based on ascending magnitude of centroid iMAG: MAG, descending -labeltable LTFILE: Attach labeltable LTFILE to clustering output. This labeltable will overwrite a table that is taken from CLUST_INIT should you use -clust_init option. -clabels LAB1 LAB2 ...: Provide a label for each cluster. Labels cannot start with '-'. -clust_init CLUST_INIT: Specify a dataset to initialize clustering. This option sets -r 0 . If CLUST_INIT has a labeltable and you do not specify one then CLUST_INIT's table is used for the output -r number For k-means clustering, the number of times the k-means clustering algorithm is run (default: 0 with -clust_init, 1 otherwise) -rsigs SIGS Calculate distances from each voxel's signature to the signatures in SIGS. SIGS is a multi-column 1D file with each column being a signature. The output is a dset the same size as the input with as many sub-bricks as there are columns in SIGS. With this option, no clustering is done. -verb verbose -write_dists Output text files containing various measures. FILE.kgg.1D : Cluster assignments FILE.dis.1D : Distance between clusters FILE.cen.1D : Cluster centroids FILE.info1.1D: Within cluster sum of distances FILE.info2.1D: Maximum distance within each cluster FILE.vcd.1D: Distance from voxel to its centroid -voxdbg I J K Output debugging info for voxel I J K -seed SEED Seed for the random number generator. Default is 1234567

AFNI program: 3dKruskalWallis
++ 3dKruskalWallis: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program performs nonparametric Kruskal-Wallis test for comparison of multiple treatments. Usage: 3dKruskalWallis -levels s s = number of treatments -dset 1 filename data set for treatment #1 . . . . . . -dset 1 filename data set for treatment #1 . . . . . . -dset s filename data set for treatment #s . . . . . . -dset s filename data set for treatment #s [-workmem mega] number of megabytes of RAM to use for statistical workspace [-voxel num] screen output for voxel # num -out prefixnamename Kruskal-Wallis statistics are written to file prefixname N.B.: For this program, the user must specify 1 and only 1 sub-brick with each -dset command. That is, if an input dataset contains more than 1 sub-brick, a sub-brick selector must be used, e.g.: -dset 2 'fred+orig[3]' INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLFCD
Usage: 3dLFCD [options] dset Computes voxelwise local functional connectivity density as defined in: Tomasi, D and Volkow, PNAS, May 2010, 107 (21) 9885-9890; DOI: 10.1073/pnas.1001414107 The results are stored in a new 3D bucket dataset as floats to preserve their values. Local functional connectivity density (LFCD; as opposed to global functional connectivity density, see 3dDegreeCentrality), reflects the extent of the correlation of a voxel within its locally connected cluster. Conceptually the process involves: 1. Calculating the correlation between voxel time series for every pair of voxels in the brain (as determined by masking) 2. Applying a threshold to the resulting correlations to exclude those that might have arisen by chance 3. Find the cluster of above-threshold voxels that are spatially connected to the target voxel. 4. Count the number of voxels in the local cluster. Practically the algorithm is ordered differently to optimize for computational time and memory usage. The procedure described in the paper defines a voxels neighborhood to be the 6 voxels with which it shares a face. This definition can be changed to include edge and corner voxels using the -neighborhood flags below. LFCD is a localized variant of binarized degree centrality, the weighted alternative is calculated by changing step 4 above to calculate the sum of the correlation coefficients between the seed region and the neighbors. 3dLFCD outputs both of these values (in separate briks), since they are so easy to calculate in tandem. You might prefer to calculate this on your data after spatial normalization, so that the range of values are consistent between datasets. Similarly the same brain mask should be used for all datasets that will be directly compared. The original paper used a correlation threshold = 0.6 and excluded all voxels with tSNR < 50. 3dLFCD does not discard voxels based on tSNR, this would need to be done beforehand. Options: -pearson = Correlation is the normal Pearson (product moment) correlation coefficient [default]. -spearman AND -quadrant are disabled at this time :-( -thresh r = exclude correlations <= r from calculations -faces = define neighborhood to include face touching edges (default) -faces_edges = define neighborhood to include face and edge touching voxels -faces_edges_corners = define neighborhood to include face, edge, and corner touching voxels -polort m = Remove polynomial trend of order 'm', for m=-1..3. [default is m=1; removal is by least squares]. Using m=-1 means no detrending; this is only useful for data/information that has been pre-processed. -autoclip = Clip off low-intensity regions in the dataset, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The mask is determined the same way that 3dAutomask works. This is done automatically if no mask is proveded. -mask mmm = Mask to define 'in-brain' voxels. Reducing the number the number of voxels included in the calculation will significantly speedup the calculation. Consider using a mask to constrain the calculations to the grey matter rather than the whole brain. This is also preferable to using -autoclip or -automask. -prefix p = Save output into dataset with prefix 'p', this file will contain bricks for both 'weighted' and 'binarized' lFCD [default prefix is 'LFCD']. Notes: * The output dataset is a bucket type of floats. * The program prints out an estimate of its memory used when it ends. It also prints out a progress 'meter' to keep you pacified. -- RWCox - 31 Jan 2002 and 16 Jul 2010 -- Cameron Craddock - 13 Nov 2015 ========================================================================= * This binary version of 3dLFCD is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLME
================== Welcome to 3dLME ================== AFNI Group Analysis Program with Linear Mixed-Effects Modeling Approach #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 2.1.5, March 15, 2024 Author: Gang Chen (gangchen@mail.nih.gov) Website - https://afni.nimh.nih.gov/sscc/gangc/lme.html SSCC/NIMH, National Institutes of Health, Bethesda MD 20892 #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Usage: ------ 3dLME is a group-analysis program that performs linear mixed-effects (LME) modeling analysis. One simple criterion to decide whether 3dLME is appropriate is that each subject has to have two or more measurements at each spatial location (except for a small portion of subjects with missing data). In other words, at least one within-subject (or repeated-measures) factor serves as explanatory variable. For complex random-effects structures, use 3dLMEr. F-statistics for main effects and interactions are automatically included in the output for all variables. In addition, Student t-tests for quantitative variables are also in the output. In addition, general linear tests (GLTs) can be requested via symbolic coding. If you want to cite the analysis approach, use the following: Chen, G., Saad, Z.S., Britton, J.C., Pine, D.S., Cox, R.W. (2013). Linear Mixed-Effects Modeling Approach to FMRI Group Analysis. NeuroImage 73:176-190. http://dx.doi.org/10.1016/j.neuroimage.2013.01.047 Input files for 3dLME can be in AFNI, NIfTI, or surface (niml.dset) format. In addition to R installation, the following two R packages need to be acquired in R first before running 3dLME: "nlme", "lme4" and "phia". In addition, the "snow" package is also needed if one wants to take advantage of parallel computing. To install these packages, run the following command at the terminal: rPkgsInstall -pkgs ALL Alternatively, you may install them in R: install.packages("nlme") install.packages("lme4") install.packages("phia") install.packages("snow") More details about 3dLME can be found at https://afni.nimh.nih.gov/sscc/gangc/LME.html Once the 3dLME command script is constructed, it can be run by copying and pasting to the terminal. Alternatively (and probably better) you save the script as a text file, for example, called LME.txt, and execute it with the following (assuming on tcsh shell), tcsh -x LME.txt & or, tcsh -x LME.txt > diary.txt & tcsh -x LME.txt |& tee diary.txt & The advantage of the latter command is that the progression is saved into the text file diary.txt and, if anything goes awry, can be examined later. Thanks to the R community, Henrik Singmann and Helios de Rosario for the strong technical support. Example 1 --- one condition modeled with 8 basis functions (e.g., TENT or TENTzero) for one group of 13 subjects. With the option -bounds, values beyond the range will be treated as outliers and considered as missing. If you want to set a range, choose the bounds that make sense with your input data. -------------------------------- 3dLME -prefix myOutput -jobs 4 \ -mask myMask+tlrc \ -model '0+Time' \ -bounds -2 2 \ -qVars order \ -qVarCenters 0 \ -ranEff '~1' \ -corStr 'order : AR1' \ -SS_type 3 \ -num_glf 1 \ -glfLabel 1 4TimePoints -glfCode 1 'Time : 1*Diff2 & 1*Diff3 & 1*Diff4 & 1*Diff5' \ -dataTable \ Subj Time order InputFile \ c101 Diff0 0 testData/c101time0+tlrc \ c101 Diff1 1 testData/c101time1+tlrc \ c101 Diff2 2 testData/c101time2+tlrc \ c101 Diff3 3 testData/c101time3+tlrc \ c101 Diff4 4 testData/c101time4+tlrc \ c101 Diff5 5 testData/c101time5+tlrc \ c101 Diff6 6 testData/c101time6+tlrc \ c101 Diff7 7 testData/c101time7+tlrc \ c103 Diff0 0 testData/c103time0+tlrc \ c103 Diff1 1 testData/c103time1+tlrc \ ... Example 2 --- one within-subject factor (conditions: House and Face), one within-subject quantitative variable (reaction time, RT) and one between- subjects covariate (age). RT values don't differ significantly between the two conditions, and thus are centered via grand mean. Random effects are intercept and RT effect whose correlation is estimated from the data. With the option -bounds, values beyond [-2, 2] will be treated as outliers and considered as missing. ------------------------------------------------------------------------- 3dLME -prefix Example2 -jobs 24 \ -model "cond*RT+age" \ -bounds -2 2 \ -qVars "RT,age" \ -qVarCenters "105.35,34.7" \ -ranEff '~1+RT' \ -SS_type 3 \ -num_glt 4 \ -gltLabel 1 'House' -gltCode 1 'cond : 1*House' \ -gltLabel 2 'Face-House' -gltCode 2 'cond : 1*Face -1*House' \ -gltLabel 3 'House-AgeEff' -gltCode 3 'cond : 1*House age :' \ -gltLabel 4 'House-Age2' -gltCode 4 'cond : 1*House age : 5.3' \ -num_glf 1 \ -glfLabel 1 'cond_age' -glfCode 1 'cond : 1*House & 1*Face age :' \ -dataTable \ Subj cond RT age InputFile \ s1 House 124 35 s1+tlrc'[House#0_Coef]' \ s2 House 97 51 s2+tlrc'[House#0_Coef]' \ s3 House 107 25 s3+tlrc'[House#0_Coef]' \ ... s1 Face 110 35 s1+tlrc'[Face#0_Coef]' \ s2 Face 95 51 s2+tlrc'[Face#0_Coef]' \ s3 Face 120 25 s3+tlrc'[Face#0_Coef]' \ ... Example 3 --- one within-subject factor (conditions: positive, negative, and neutral), and one between-subjects factors (groups: control and patients). Effect estimates for a few subjects are available for only one or two conditions. These subjects with missing data would have to be abandoned in the traditional ANOVA approach. All subjects can be included with 3dLME, and a random intercept is considered. ------------------------------------------------------------------------- 3dLME -prefix Example3 -jobs 24 \ -mask myMask+tlrc \ -model "cond*group" \ -bounds -2 2 \ -ranEff '~1' \ -SS_type 3 \ -num_glt 6 \ -gltLabel 1 'pos-neu' -gltCode 1 'cond : 1*pos -1*neu' \ -gltLabel 2 'neg' -gltCode 2 'cond : 1*neg ' \ -gltLabel 3 'pos+nue-neg' -gltCode 3 'cond : 1*pos +1*neu -1*neg' \ -gltLabel 4 'pat_pos-neu' -gltCode 4 'cond : 1*pos -1*neu group : 1*pat' \ -gltLabel 5 'pat_neg-neu' -gltCode 5 'cond : 1*neg -1*neu group : 1*pat' \ -gltLabel 6 'pat_pos-neg' -gltCode 6 'cond : 1*pos -1*neg group : 1*pat' \ -num_glf 1 \ -glfLabel 1 'pos-neu' -glfCode 1 'Group : 1*ctr & 1*pat cond : 1*pos -1*neu & 1*pos -1*neg' \ -dataTable \ Subj cond group InputFile \ s1 pos ctr s1+tlrc'[pos#0_Coef]' \ s1 neg ctr s1+tlrc'[neg#0_Coef]' \ s1 neu ctr s1+tlrc'[neu#0_Coef]' \ ... s21 pos pat s21+tlrc'[pos#0_Coef]' \ s21 neg pat s21+tlrc'[neg#0_Coef]' \ s21 neu pat s21+tlrc'[neu#0_Coef]' \ ... Example 4 --- Computing ICC values for two within-subject factor (Cond: positive, negative, and neutral; Scanner: one, and two) plus subjects (factor Subj). ------------------------------------------------------------------------- 3dLME -prefix Example4 -jobs 12 \ -mask myMask+tlrc \ -model "1" \ -bounds -2 2 \ -ranEff 'Cond+Scanner+Subj' \ -ICCb \ -dataTable \ Subj Cond Scanner InputFile \ s1 pos one s1_1+tlrc'[pos#0_Coef]' \ s1 neg one s1_1+tlrc'[neg#0_Coef]' \ s1 neu one s1_1+tlrc'[neu#0_Coef]' \ s1 pos two s1_2+tlrc'[pos#0_Coef]' \ s1 neg two s1_2+tlrc'[neg#0_Coef]' \ s1 neu two s1_2+tlrc'[neu#0_Coef]' \ ... s21 pos two s21_2+tlrc'[pos#0_Coef]' \ s21 neg two s21_2+tlrc'[neg#0_Coef]' \ s21 neu two s21_2+tlrc'[neu#0_Coef]' \ ... Options in alphabetical order: ------------------------------ -bounds lb ub: This option is for outlier removal. Two numbers are expected from the user: the lower bound (lb) and the upper bound (ub). The input data will be confined within [lb, ub]: any values in the input data that are beyond the bounds will be removed and treated as missing. Make sure the first number is less than the second. The default (the absence of this option) is no outlier removal. -cio: Use AFNI's C io functions, which is default. Alternatively -Rio can be used. -corStr FORMULA: Specify the correlation structure of the residuals. For example, when analyzing the effect estimates from multiple basis functions, one may consider account for the temporal structure of residuals with AR or ARMA. -cutoff threshold: Specify the cutoff value to obtain voxel-wise accuracy in logistic regression analysis. Default is 0 (no accuracy will be estimated). -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The first column is fixed and reserved with label 'Subj', and the last is reserved for 'InputFile'. Each row should contain only one effect estimate in the table of long format (cf. wide format) as defined in R. The level labels of a factor should contain at least one character. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) The context of the table can be saved as a separate file, e.g., called table.txt. In the script specify the information with '-dataTable @table.txt'. This option is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset. When the table is a stand-alone file, quotes should NOT be added around the sub-brick selector -- square brackets [...]. Also, there is no need to add a backslash at the end of each line. -dbgArgs: This option will enable R to save the parameters in a file called .3dLME.dbg.AFNI.args in the current directory so that debugging can be performed. -glfCode k CODING: Specify the k-th general linear F-test (GLF) through a weighted combination among factor levels. The symbolic coding has to be within (single or double) quotes. For example, the coding 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos' tests the main effect of Condition at the positive Emotion. Similarly, the coding 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos -1*neg' shows the interaction between the three levels of Condition and the two. levels of Emotion. NOTE: 1) The weights for a variable do not have to add up to 0. 2) When a quantitative variable is present, other effects are tested at the center value of the covariate unless the covariate value is specified as, for example, 'Group : 1*Old Age : 2', where the Old Group is tested at the Age of 2 above the center. 3) The absence of a categorical variable in a coding means the levels of that factor are averaged (or collapsed) for the GLF. 4) The appearance of a categorical variable has to be followed by the linear combination of its levels. -glfLabel k label: Specify the label for the k-th general linear F-test (GLF). A symbolic coding for the GLF is assumed to follow with each -glfLabel. -gltCode k CODING: Specify the k-th general linear test (GLT) through a weighted combination among factor levels. The symbolic coding has to be within (single or double) quotes. For example, the following 'Condition : 2*House -3*Face Emotion : 1*positive ' requests for a test of comparing 2 times House condition with 3 times Face condition while Emotion is held at positive valence. NOTE: 1) The weights for a variable do not have to add up to 0. 2) When a quantitative variable is present, other effects are tested at the center value of the covariate unless the covariate value is specified as, for example, 'Group : 1*Old Age : 2', where the Old Group is tested at the Age of 2 above the center. 3) The effect for a quantitative variable can be specified with, for example, 'Group : 1*Old Age : ', or 'Group : 1*Old - 1*Young Age : ' 4) The absence of a categorical variable in a coding means the levels of that factor are averaged (or collapsed) for the GLT. 5) The appearance of a categorial variable has to be followed by the linear combination of its levels. Only a quantitative is allowed to have a dangling coding as seen in 'Age :' -gltLabel k label: Specify the label for the k-th general linear test (GLT). A symbolic coding for the GLT is assumed to follow with each -gltLabel. -help: this help message -ICC: This option allows 3dLME to compute voxel-wise intra-class correlation for the variables specified through option -ranEff. See Example 4 in in the help. Consider using a more flexible program 3dICC. If trial- level data are available, a more accurate approach is to use the program TRR at the region level or use the program 3dLMEr at the level. Refer to the following paper for more detail: Chen, G., Pine, D.S., Brotman, M.A., Smith, A.R., Cox, R.W., Haller, S.P., 2021. Trial and error: A hierarchical modeling approach to test-retest reliability. NeuroImage 245, 118647. -ICCb: This option allows 3dLME to compute voxel-wise intra-class correlation through a Bayesian approach with Gamma priors for the variables specified through option -ranEff. The computation will take much longer due the sophistication involved. However, the Bayesian method is preferred to the old approach with -ICC for the typical FMRI data. R package 'blme' is required for this option. Consider using a more flexible program 3dICC -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -LOGIT: This option allows 3dLME to perform voxel-wise logistic modeling. Currently no random effects are allowed ('-ranEff NA'), but this limitation can be removed later if demand occurs. The InputFile column is expected to list subjects' responses in 0s and 1s. In addition, one voxel-wise covariate is currently allowed. Each regression coefficient (including the intercept) and its z-statistic are saved in the output. -logLik: Add this option if the voxel-wise log likelihood is wanted in the output. This option currently cannot be combined with -ICC, -ICCb, -LOGIT. -mask MASK: Process voxels inside this mask only. Default is no masking. -ML: Add this option if Maximum Likelihood is wanted instead of the default method, Restricted Maximum Likelihood (REML). -model FORMULA: Specify the terms of fixed effects for all explanatory, including quantitative, variables. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. A+B represents the additive effects of A and B, A:B is the interaction between A and B, and A*B = A+B+A:B. Subject should not occur in the model specification here. -num_glf NUMBER: Specify the number of general linear F-tests (GLFs). A glf involves the union of two or more simple tests. See details in -glfCode. -num_glt NUMBER: Specify the number of general linear t-tests (GLTs). A glt is a linear combination of a factor levels. See details in -gltCode. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. The sub-brick labeled with the '(Intercept)', if present, should be interpreted as the effect with each factor at the reference level (alphabetically the lowest level) for each factor and with each quantitative covariate at the center value. -qVarCenters VALUES: Specify centering values for quantitative variables identified under -qVars. Multiple centers are separated by commas (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -qVarsCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the values are fed into -dataTable. -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarsCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ significantly in the average value of the covariate. 3) Within-subject covariates are better modeled with 3dLME. -ranEff FORMULA: Specify the random effects. The simplest and most common one is random intercept, "~1", meaning that each subject deviates some amount (called random effect) from the group average. "~RT" or "~1+RT" means that each subject has a unique intercept as well as a slope, and the correlation between the two random effects are estimated, not assumed, from the data. "~0+RT" indicates that only a random effect of slope is desired. Compound symmetry for a variance-covariance metric across the levels of factor A can be specified through pdCompSymm(~0+A) The list of random terms should be separated by space within (single or double) quotes. Notice: In the case of computing ICC values, list all the factors with which the ICC is to be obtained. For example, with two factors "Scanner" and "Subj", set it as -ranEff "Scanner+Subj". See Example 4 in the the help. -RE: Specify the list of variables whose random effects are saved in the output. For example, "RE "Intercept"" requests for saving the random intercept for all subjects while "RE "Intercept,time"" asks for saving both the random intercept and random slope of time for all subjects The output filename is specified through -REprefix. All random effects are stored in the same file with each sub-brick named by the variable name plus the subject label. -REprefix: Specify the output filename for random effects. All random effects are stored in the same file with each sub-brick named by the variable name plus the subject label. -resid PREFIX: Output file name for the residuals. For AFNI format, provide prefix only without view+suffix. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. The sub-brick labeled with the '(Intercept)', if present, should be interpreted as the effect with each factor at the reference level (alphabetically the lowest level) for each factor and with each quantitative covariate at the center value. -Rio: Use R's io functions. The alternative is -cio. -show_allowed_options: list of allowed options -SS_type NUMBER: Specify the type for sums of squares in the F-statistics. Two options are currently supported: sequential (1) and marginal (3). -vVarCenters VALUES: Specify centering values for voxel-wise covariates identified under -vVars. Multiple centers are separated by commas (,) within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -vVarsCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the files are fed into -dataTable. -vVars variable_list: Identify voxel-wise covariates with this option. Currently one voxel-wise covariate is allowed only, but this may change if demand occurs... By default mean centering is performed voxel-wise across all subjects. Alternatively centering can be specified through a global value under -vVarsCenters. If the voxel-wise covariates have already been centered, set the centers at 0 with -vVarsCenters.

AFNI program: 3dLME2
================== Welcome to 3dLME2 ================== Program for Voxelwise Linear Mixed-Effects (LME) Analysis #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 1.0.0, Apr 23, 2024 Author: Gang Chen (gangchen@mail.nih.gov) SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Introduction ------ Linear Mixed-Effects (LME) analysis adopts the traditional approach that differentiates two types of effects: fixed effects capture the population- level components while random effects characterize the lower-level components such as individuals, families, scanning sites, etc. 3dLME2 is a revised version of its older counterpart 3dLME in the sense that 3dLME2 is more flexible in specifying the random-effects components and the variance-covariance structure than the latter. Like 3dLME, all main effects and interactions are automatically available in the output while simple effects that tease apart those main effects and interactions would have to be requested through options -gltCode or -glfCode. Input files can be in AFNI, NIfTI, surface (niml.dset) or 1D format. To obtain the output int the same format of the input, append a proper suffix to the output specification option -prefix (e.g., .nii, .niml.dset or .1D for NIfTI, surface or 1D). 3dLME2 allows for the incorporation of various types of explanatory variables including categorical (between- and within-subject factors) and quantitative variables (e.g., age, behavioral data). The burden of properly specifying the structure of lower-level effects is placed on the user's shoulder, so familiarize yourself with the following FAQ in case you want some clarifications: https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html Whenever a quantitative variable is involved, it is required to explicitly declare the variable through option -qVars. In addition, be mindful about the centering issue of each quantitative variable: you have to decide which makes more sense in the research context - global centering or within- condition (or within-group) centering? Here is some background and discussion about the issue: https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/center.html The following exemplifying scripts are good demonstrations. More examples will be added in the future if I could crowdsource more scenarios from the users (including you the reader). In case you find one example like your data structure, use the example(s) as a template and then build up your own script. In addition to R installation, the following R packages need to be installed first before running 3dLME2: "nlme", "phia" and "snow". To install these R packages, run the following command at the terminal: rPkgsInstall -pkgs "nlme,phia,snow" Alternatively, you may install them in R: install.packages("nlme") install.packages("phia") install.packages("snow") Once the 3dLME2 command script is constructed, it can be run by copying and pasting to the terminal. Alternatively (and probably better) you save the script as a text file, for example, called LME.txt, and execute it with the following (assuming on tc shell), nohup tcsh -x LME.txt & or, nohup tcsh -x LME.txt > diary.txt & or, nohup tcsh -x LME.txt |& tee diary.txt & The advantage of the latter commands is that the progression is saved into the text file diary.txt and, if anything goes awry, can be examined later. Example 1 --- Simplest case: LME analysis for one group of subjects each of which has three effects associated with three emotions (pos, neg and neu), and the effects of interest are the comparisons among the three emotions at the population level (missing data allowed). This data structure is usually considered as one-way repeated-measures (or within-subject) ANOVA if no missing data occurred. The LME model is typically formulated with a random intercept in this case. With the option -bounds, values beyond [-2, 2] will be treated as outliers and considered as missing. If you want to set a range, choose the bounds that make sense with your input data. ------------------------------------------------------------------------- 3dLME2 -prefix LME -jobs 12 \ -mask myMask+tlrc \ -fixef 'emotion' \ -ranef '~1|Aubj' \ -SS_type 3 \ -bounds -2 2 \ -gltCode pos 'emotion : 1*pos' \ -gltCode neg 'emotion : 1*neg' \ -gltCode neu 'emotion : 1*neu' \ -gltCode pos-neg 'emotion : 1*pos -1*neg' \ -gltCode pos-neu 'emotion : 1*pos -1*neu' \ -gltCode neg-neu 'emotion : 1*neg -1*neu' \ -gltCode em-eff1 'emotion : 0.5*pos +0.5*neg -1*neu' \ -glfCode em-eff2 'emotion : 1*pos -1*neg & 1*pos -1*neu' \ -dataTable \ Subj emotion InputFile \ s1 pos s1_pos+tlrc \ s1 neg s1_neg+tlrc \ s1 neu s1_neu+tlrc \ s2 pos s2_pos+tlrc \ s2 neg s2_neg+tlrc \ s2 pos s2_neu+tlrc \ ... s20 pos s20_pos+tlrc \ s20 neg s20_neg+tlrc \ s20 neu s20_neu+tlrc \ ... Example 2 --- LME analysis for one group of subjects each of which has three effects associated with three emotions (pos, neg and neu), and the effects of interest are the comparisons among the three emotions at the population level. In addition, reaction time (RT) is available per emotion from each subject. An LME model can be formulated to include both random intercept and random slope. Be careful about the centering issue about any quantitative variable: you have to decide which makes more sense - global centering or within-condition (or within-group) centering? ------------------------------------------------------------------------- 3dLME2 -prefix LME -jobs 12 \ -mask myMask+tlrc \ -fixef 'emotion*RT' \ -ranef '~RT|Subj' \ -corr corSymm '~1|Subj' \ -SS_type 3 \ -bounds -2 2 \ -qVars 'RT' \ -qVarCenters 0 \ -gltCode pos 'emotion : 1*pos' \ -gltCode neg 'emotion : 1*neg' \ -gltCode neu 'emotion : 1*neu' \ -gltCode pos-neg 'emotion : 1*pos -1*neg' \ -gltCode pos-neu 'emotion : 1*pos -1*neu' \ -gltCode neg-neu 'emotion : 1*neg -1*neu' \ -gltCode em-eff1 'emotion : 0.5*pos +0.5*neg -1*neu' \ -glfCode em-eff2 'emotion : 1*pos -1*neg & 1*pos -1*neu' \ -dataTable \ Subj emotion RT InputFile \ s1 pos 23 s1_pos+tlrc \ s1 neg 34 s1_neg+tlrc \ s1 neu 28 s1_neu+tlrc \ s2 pos 31 s2_pos+tlrc \ s2 neg 22 s2_neg+tlrc \ s2 pos 29 s2_neu+tlrc \ ... s20 pos 12 s20_pos+tlrc \ s20 neg 20 s20_neg+tlrc \ s20 neu 30 s20_neu+tlrc \ ... Options in alphabetical order: ------------------------------ -bounds lb ub: This option is for outlier removal. Two numbers are expected from the user: the lower bound (lb) and the upper bound (ub). The input data will be confined within [lb, ub]: any values in the input data that are beyond the bounds will be removed and treated as missing. Make sure the first number is less than the second. The default (the absence of this option) is no outlier removal. -cio: Use AFNI's C io functions, which is the default. Alternatively, -Rio can be used. -corr class FORMULA: correlation structure. -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last in the script; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The order of the columns should not matter except that the last column has to be the one for input files, 'InputFile'. Unlike 3dLME, the subject column (Subj in 3dLME) does not have to be the first column; and it does not have to include a subject ID column under some situations Each row should contain only one input file in the table of long format (cf. wide format) as defined in R. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) When the table is part of the script, a backslash is needed at the end of each line (except for the last line) to indicate the continuation to the next line. Alternatively, one can save the context of the table as a separate file, e.g., calling it table.txt, and then in the script specify the data with '-dataTable @table.txt'. However, when the table is provided as a separate file, do NOT put any quotes around the square brackets for each sub-brick, otherwise the program would not properly read the files, unlike the situation when quotes are required if the table is included as part of the script. Backslash is also not needed at the end of each line, but it would not cause any problem if present. This option of separating the table from the script is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset. -dbgArgs: This option will enable R to save the parameters in a file called .3dLME2.dbg.AFNI.args in the current directory so that debugging can be performed. -fixef FORMULA: Specify the model structure for all the variables. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. In the LME context the simplest model is "1+(1|Subj)" in which the random effect from each of the two subjects in a pair is symmetrically incorporated in the model. Each random-effects factor is specified within parentheses per formula convention in R. Any effects of interest and confounding variables (quantitative or categorical variables) can be added as fixed effects without parentheses. -glfCode label CODING: Specify a general linear F-style (GLF) formulation with the weights among factor levels in which two or more null relationships (e.g., A-B=0 and B-C=0) are involved. The symbolic coding has to be within (single or double) quotes. For example, the coding '-glfCode AvBvc 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos'' examines the main effect of Condition at the positive Emotion with the output labeled as AvBvC. Similarly the coding '-glfCode CondByEmo' 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos -1*neg' looks for the interaction between the three levels of Condition and the two levels of Emotion and the resulting sub-brick is labeled as 'CondByEmo'. NOTE: 1) The weights for a variable do not have to add up to 0. 2) When a quantitative variable is present, other effects are tested at the center value of the covariate unless the covariate value is specified as, for example, 'Group : 1*Old Age : 2', where the Old Group is tested at the Age of 2 above the center. 3) The absence of a categorical variable in a coding means the levels of that factor are averaged (or collapsed) for the GLF. 4) The appearance of a categorical variable has to be followed by the linear combination of its levels. -gltCode label weights: Specify the label and weights of interest in a general linear t-style (GLT) formulation in which only one null relationship is involved (cf. -glfCode). The weights should be surrounded with quotes. For example, the specification '-gltCode AvB 'Condition : 1*A -1*B' compares A and B with a label 'AvB' for the output sub-bricks. -help: this help message -IF var_name: var_name is used to specify the column name that is designated for input files of effect estimate. The default (when this option is not invoked is 'InputFile', in which case the column header has to be exactly as 'InputFile' This input file for effect estimates has to be the last column. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -mask MASK: Process voxels inside this mask only. Default is no masking. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached (otherwise the output would be saved in AFNI format). -qVarCenters VALUES: Specify centering values for quantitative variables identified under -qVars. Multiple centers are separated by commas (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -qVarCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the values are fed into -dataTable. -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarsCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ substantially in the average value of the covariate. -ranef FORMULA: Specify random effects. -resid PREFIX: Output file name for the residuals. For AFNI format, provide prefix only without view+suffix. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. The sub-brick labeled with the '(Intercept)', if present, should be interpreted as the effect with each factor at the reference level (alphabetically the lowest level) for each factor and with each quantitative covariate at the center value. -Rio: Use R's io functions. The alternative is -cio. -show_allowed_options: list of allowed options -SS_type NUMBER: Specify the type for sums of squares in the F-statistics. Three options are: sequential (1), hierarchical (2), and marginal (3). When this option is absent (default), marginal (3) is automatically set. Some discussion regarding their differences can be found here: https://sscc.nimh.nih.gov/sscc/gangc/SS.html -vVarCenters VALUES: Specify centering values for voxel-wise covariates identified under -vVars. Multiple centers are separated by commas (,) within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -vVarsCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable yourself first before the files are fed under -dataTable. -vVars variable_list: Identify voxel-wise covariates with this option. Currently one voxel-wise covariate is allowed only. By default mean centering is performed voxel-wise across all subjects. Alternatively centering can be specified through a global value under -vVarsCenters. If the voxel-wise covariates have already been centered, set the centers at 0 with -vVarsCenters. -wt class FORMULA: correlation structure.

AFNI program: 3dLMEr
================== Welcome to 3dLMEr ================== Program for Voxelwise Linear Mixed-Effects (LME) Analysis #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 1.1.1, Feb 18, 2025 Author: Gang Chen (gangchen@mail.nih.gov) SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Introduction ------ ### Overview of 3dLMEr Linear Mixed-Effects (LME) analysis follows a traditional framework that distinguishes between two types of effects: - Fixed effects capture population-level components. - Random effects account for lower-level variability, such as subjects, families, or scanning sites. 3dLMEr is an advanced and more flexible successor to 3dLME. It enhances model specification, particularly in handling random-effects components. While 3dLME was built on the nlme R package, 3dLMEr leverages lme4, allowing for greater flexibility. Additionally, statistical values for main effects and interactions are approximated using Satterthwaite’s method. ### Key Differences Between 3dLMEr and 3dLME 1. Random-effects specification: - In 3dLMEr, random effects are fully integrated into the model formula (via `-model ...`). - The `-ranEff` option from 3dLME is no longer needed. - Users must explicitly specify the model structure. See this blogpost for details: How to Specify Individual-Level Random Effects in Hierarchical Modeling https://discuss.afni.nimh.nih.gov/t/how-to-specify-individual-level-random-effects-in-hierarchical-modeling/6462 2. Simplified effect specification: - Labels for simple and composite effects are now part of `-gltCode` and `-glfCode`, eliminating the need for `-gltLabel`. 3. Output format for statistical values: - Main effects, interactions, and composite effects (generated automatically by 3dLMEr) are stored as chi-square statistics (with 2 degrees of freedom). - Simple effects (specified by the user) are stored as Z-statistics. - The fixed 2 degrees of freedom for chi-square statistics simplifies interpretation, as the Satterthwaite method produces varying degrees of freedom. ### Citing 3dLMEr If you use 3dLMEr in your analysis, cite: - General LME approach: Chen, G., Saad, Z.S., Britton, J.C., Pine, D.S., Cox, R.W. (2013). Linear Mixed-Effects Modeling Approach to FMRI Group Analysis. *NeuroImage, 73*, 176-190. [DOI: 10.1016/j.neuroimage.2013.01.047](http://dx.doi.org/10.1016/j.neuroimage.2013.01.047) - Test-retest reliability using trial-level effect estimates (`-TRR` option): Chen, G., Pine, D.S., Brotman, M.A., Smith, A.R., Cox, R.W., Haller, S.P. (2021). Trial and error: A hierarchical modeling approach to test-retest reliability. *NeuroImage, 245*, 118647. [DOI: 10.1016/j.neuroimage.2021.118647](https://doi.org/10.1016/j.neuroimage.2021.118647) ### Input & Output Formats Supported input formats: - AFNI - NIfTI - Surface (`niml.dset`) - 1D text files To match the output format to the input, append an appropriate suffix to `-prefix` (e.g., `.nii`, `.niml.dset`, or `.1D`). ### Model Specification & Considerations Explanatory variables: 3dLMEr supports: - Categorical variables (e.g., between- and within-subject factors) - Quantitative variables (e.g., age, behavioral measures) User responsibility: - The burden of specifying lower-level effects is on the user. - For clarifications, refer to this FAQ: [Mixed Models FAQ] (https://bbolker.github.io/mixedmodels-misc/glmmFAQ.html). Handling quantitative variables: - Declare them explicitly using `-qVars`. - Consider centering options: - Global centering (across all subjects) - Within-condition/group centering (depends on research context) - More details on centering: https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/center.html ### Example Scripts Check out example scripts below that demonstrate different data structures. If one matches your study, use it as a template. More examples will be added over time— contributions are welcome! ### Installation Requirements Before running 3dLMEr, install the following R packages: ``` install.packages("lmerTest") install.packages("phia") install.packages("snow") ``` Alternatively, use AFNI’s installer: ``` rPkgsInstall -pkgs "lmerTest,phia,snow" ``` ### Running 3dLMEr Once your script is ready, run it in the terminal: ``` nohup tcsh -x LME.txt & ``` or, to save the output log: ``` nohup tcsh -x LME.txt > diary.txt & ``` or, to display output live while saving it: ``` nohup tcsh -x LME.txt |& tee diary.txt & ``` Saving logs allows you to review output later if issues arise. Example 1 --- Simplest case: LME analysis for one group of subjects each of which has three effects associated with three emotions (pos, neg and neu), and the effects of interest are the comparisons among the three emotions at the population level (missing data allowed). This data structure is usually considered as one-way repeated-measures (or within-subject) ANOVA if no missing data occurred. The LME model is typically formulated with a random intercept in this case. With the option -bounds, values beyond [-2, 2] will be treated as outliers and considered as missing. If you want to set a range, choose the bounds that make sense with your input data. **NOTE**: Using the -bounds option to remove outliers should be approached with caution due to its arbitrariness. A more principled alternative is to use 3dGLMM with a Student's t-distribution. ------------------------------------------------------------------------- 3dLMEr -prefix LME -jobs 12 \ -mask myMask+tlrc \ -model 'emotion+(1|Subj)' \ -SS_type 3 \ -bounds -2 2 \ -gltCode mean 'emotion : 0.333*pos +0.333*neg + 0.333*neu' \ -gltCode pos 'emotion : 1*pos' \ -gltCode neg 'emotion : 1*neg' \ -gltCode neu 'emotion : 1*neu' \ -gltCode pos-neg 'emotion : 1*pos -1*neg' \ -gltCode pos-neu 'emotion : 1*pos -1*neu' \ -gltCode neg-neu 'emotion : 1*neg -1*neu' \ -gltCode em-eff1 'emotion : 0.5*pos +0.5*neg -1*neu' \ -glfCode em-eff2 'emotion : 1*pos -1*neg & 1*pos -1*neu' \ -dataTable \ Subj emotion InputFile \ s1 pos s1_pos+tlrc \ s1 neg s1_neg+tlrc \ s1 neu s1_neu+tlrc \ s2 pos s2_pos+tlrc \ s2 neg s2_neg+tlrc \ s2 pos s2_neu+tlrc \ ... s20 pos s20_pos+tlrc \ s20 neg s20_neg+tlrc \ s20 neu s20_neu+tlrc \ ... **Note:** `3dLMEr` does not explicitly output the model intercept (overall mean). However, you can extract it using the `-gltCode` option, as shown in the script above: -gltCode mean 'emotion : 0.333*pos +0.333*neg +0.333*neu' Example 2 --- LME analysis for one group of subjects each of which has three effects associated with three emotions (pos, neg and neu), and the effects of interest are the comparisons among the three emotions at the population level. In addition, reaction time (RT) is available per emotion from each subject. An LME model can be formulated to include both random intercept and random slope. Be careful about the centering issue about any quantitative variable: you have to decide which makes more sense - global centering or within-condition (or within-group) centering? **NOTE**: Using the -bounds option to remove outliers should be approached with caution due to its arbitrariness. A more principled alternative is to use 3dGLMM with a Student's t-distribution. ------------------------------------------------------------------------- 3dLMEr -prefix LME -jobs 12 \ -mask myMask+tlrc \ -model 'emotion*RT+(RT|Subj)' \ -SS_type 3 \ -bounds -2 2 \ -qVars 'RT' \ -qVarCenters 0 \ -gltCode pos 'emotion : 1*pos' \ -gltCode neg 'emotion : 1*neg' \ -gltCode neu 'emotion : 1*neu' \ -gltCode pos-neg 'emotion : 1*pos -1*neg' \ -gltCode pos-neu 'emotion : 1*pos -1*neu' \ -gltCode neg-neu 'emotion : 1*neg -1*neu' \ -gltCode em-eff1 'emotion : 0.5*pos +0.5*neg -1*neu' \ -glfCode em-eff2 'emotion : 1*pos -1*neg & 1*pos -1*neu' \ -dataTable \ Subj emotion RT InputFile \ s1 pos 23 s1_pos+tlrc \ s1 neg 34 s1_neg+tlrc \ s1 neu 28 s1_neu+tlrc \ s2 pos 31 s2_pos+tlrc \ s2 neg 22 s2_neg+tlrc \ s2 pos 29 s2_neu+tlrc \ ... s20 pos 12 s20_pos+tlrc \ s20 neg 20 s20_neg+tlrc \ s20 neu 30 s20_neu+tlrc \ ... Example 3 --- LME analysis for one group of subjects each of which has three effects associated with three emotions (pos, neg and neu), and the effects of interest are the comparisons among the three emotions at the population level. As the data were acquired across 12 scanning sites, we set up an LME model with a crossed random-effects structure, one for cross-subjects and one for cross-sites variability. **NOTE**: Using the -bounds option to remove outliers should be approached with caution due to its arbitrariness. A more principled alternative is to use 3dGLMM with a Student's t-distribution. ------------------------------------------------------------------------- 3dLMEr -prefix LME -jobs 12 \ -mask myMask+tlrc \ -model 'emotion+(1|Subj)+(1|site)' \ -SS_type 3 \ -bounds -2 2 \ -gltCode pos 'emotion : 1*pos' \ -gltCode neg 'emotion : 1*neg' \ -gltCode neu 'emotion : 1*neu' \ -gltCode pos-neg 'emotion : 1*pos -1*neg' \ -gltCode pos-neu 'emotion : 1*pos -1*neu' \ -gltCode neg-neu 'emotion : 1*neg -1*neu' \ -gltCode em-eff1 'emotion : 0.5*pos +0.5*neg -1*neu' \ -glfCode em-eff2 'emotion : 1*pos -1*neg & 1*pos -1*neu' \ -dataTable \ Subj emotion site InputFile \ s1 pos site1 s1_pos+tlrc \ s1 neg site1 s1_neg+tlrc \ s1 neu site2 s1_neu+tlrc \ s2 pos site1 s2_pos+tlrc \ s2 neg site2 s2_neg+tlrc \ s2 pos site3 s2_neu+tlrc \ ... s80 pos site12 s80_pos+tlrc \ s80 neg site12 s80_neg+tlrc \ s80 neu site10 s80_neu+tlrc \ ... Example 4 --- LME analysis with a between-subject factor (group: two groups of subjects -- control, patient), two within-subject factros (emotion: 3 levels -- pos, neg, neu; type: 2 levels -- face, word), one quantitative variable (age). **NOTE**: Using the -bounds option to remove outliers should be approached with caution due to its arbitrariness. A more principled alternative is to use 3dGLMM with a Student's t-distribution. ------------------------------------------------------------------------- 3dLMEr -prefix LME -jobs 12 \ -mask myMask+tlrc \ -model 'group*emotion*type+age+(1|Subj)+(1|Subj:emotion)+(1|Subj:type)' \ -SS_type 3 \ -bounds -2 2 \ -gltCode pat.pos 'gruop : 1*patient emotion : 1*pos' \ -gltCode pat.neg 'gruop : 1*patient emotion : 1*neg' \ -gltCode ctr.pos.age 'gruop : 1*control emotion : 1*pos age :' \ -dataTable \ Subj group emotion type age InputFile \ s1 control pos face 35 s1_pos+tlrc \ s1 control neg face 35 s1_neg+tlrc \ s1 control neu face 35 s1_neu+tlrc \ s2 control pos face 23 s2_pos+tlrc \ s2 control neg face 23 s2_neg+tlrc \ s2 control pos face 23 s2_neu+tlrc \ ... s80 patient pos word 28 s80_pos+tlrc \ s80 patient neg word 28 s80_neg+tlrc \ s80 patient neu word 28 s80_neu+tlrc \ ... Example 5 --- Test-retest reliability. LME model can be adopted for test- retest reliability analysis if trial-level effect estimates (e.g., using option -stim_times_IM in 3dDeconvolve/3dREMLfit) are available from each subjects. The following script demonstrates a situation where each subject performed same two tasks across two sessions. The goal is to obtain the test-retest reliability at the whole-brain voxel level for the contrast between the two tasks with the test-retest reliability for the average effect between the two tasks as a byproduct. WARNING: numerical failures may occur, especially for a contrast between two conditions. The failures manifest with a large portion of 0, 1 and -1 values in the output. In that case, use the program TRR to conduct region-level test-retest reliability analysis. **NOTE**: Using the -bounds option to remove outliers should be approached with caution due to its arbitrariness. A more principled alternative is to use 3dGLMM with a Student's t-distribution. ------------------------------------------------------------------------- 3dLMEr -prefix output -TRR -jobs 16 -qVars 'cond' -bounds -2 2 -model '0+sess+cond:sess+(0+sess|Subj)+(0+cond:sess|Subj)' -dataTable @data.tbl With many trials per condition, it is recommended that the data table is saved as a separate file in pure text of long format with condition (variable 'cond' in the script above) through dummy coding of -0.5 and 0.5 with the option -qVars 'cond'. Code subject and session as factor labels with labels. Below is an example of the data table. There is no need to add backslash at the end of each line. If sub-brick selector is used, do NOT use gzipped files (otherwise the file reading time would be too long) and do NOT add quotes around the square brackets [] for the sub-brick selector. Subj sess cond InputFile Subj1 s1 -0.5 Subj1s1c1_trial1.nii Subj1 s1 -0.5 Subj1s1c1_trial2.nii ... Subj1 s1 -0.5 Subj1s1c1_trial40.nii Subj1 s1 0.5 Subj1s1c2_trial1.nii Subj1 s1 0.5 Subj1s1c2_trial2.nii ... Subj1 s1 0.5 Subj1s1c2_trial40.nii Subj1 s2 -0.5 Subj1s2c1_trial1.nii Subj1 s2 -0.5 Subj1s2c1_trial2.nii ... Subj1 s2 -0.5 Subj1s2c1_trial40.nii Subj1 s2 0.5 Subj1s2c2_trial1.nii Subj1 s2 0.5 Subj1s2c2_trial2.nii ... Subj1 s2 0.5 Subj1s2c2_trial40.nii ... Options in alphabetical order: ------------------------------ -bounds lb ub: This option is for outlier removal. Two numbers are expected from the user: the lower bound (lb) and the upper bound (ub). The input data will be confined within [lb, ub]: any values in the input data that are beyond the bounds will be removed and treated as missing. Make sure the first number is less than the second. The default (the absence of this option) is no outlier removal. **NOTE**: Using the -bounds option to remove outliers should be approached with caution due to its arbitrariness. A more principled alternative is to use 3dGLMM with a Student's t-distribution. -cio: Use AFNI's C io functions, which is the default. Alternatively, -Rio can be used. -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last in the script; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The order of the columns should not matter except that the last column has to be the one for input files, 'InputFile'. Unlike 3dLME, the subject column (Subj in 3dLME) does not have to be the first column; and it does not have to include a subject ID column under some situations Each row should contain only one input file in the table of long format (cf. wide format) as defined in R. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) When the table is part of the script, a backslash is needed at the end of each line (except for the last line) to indicate the continuation to the next line. Alternatively, one can save the context of the table as a separate file, e.g., calling it table.txt, and then in the script specify the data with '-dataTable @table.txt'. However, when the table is provided as a separate file, do NOT put any quotes around the square brackets for each sub-brick, otherwise the program would not properly read the files, unlike the situation when quotes are required if the table is included as part of the script. Backslash is also not needed at the end of each line, but it would not cause any problem if present. This option of separating the table from the script is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset. -dbgArgs: This option will enable R to save the parameters in a file called .3dLMEr.dbg.AFNI.args in the current directory so that debugging can be performed. -glfCode label CODING: Specify a general linear F-style (GLF) formulation with the weights among factor levels in which two or more null relationships (e.g., A-B=0 and B-C=0) are involved. The symbolic coding has to be within (single or double) quotes. For example, the coding '-glfCode AvBvc 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos'' examines the main effect of Condition at the positive Emotion with the output labeled as AvBvC. Similarly the coding '-glfCode CondByEmo' 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos -1*neg' looks for the interaction between the three levels of Condition and the two levels of Emotion and the resulting sub-brick is labeled as 'CondByEmo'. NOTE: 1) The weights for a variable do not have to add up to 0. 2) When a quantitative variable is present, other effects are tested at the center value of the covariate unless the covariate value is specified as, for example, 'Group : 1*Old Age : 2', where the Old Group is tested at the Age of 2 above the center. 3) The absence of a categorical variable in a coding means the levels of that factor are averaged (or collapsed) for the GLF. 4) The appearance of a categorical variable has to be followed by the linear combination of its levels. -gltCode label weights: Specify the label and weights of interest in a general linear t-style (GLT) formulation in which only one null relationship is involved (cf. -glfCode). The weights should be surrounded with quotes. For example, the specification '-gltCode AvB 'Condition : 1*A -1*B' compares A and B with a label 'AvB' for the output sub-bricks. -help: this help message -IF var_name: var_name is used to specify the column name that is designated for input files of effect estimate. The default (when this option is not invoked is 'InputFile', in which case the column header has to be exactly as 'InputFile' This input file for effect estimates has to be the last column. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -mask MASK: Process voxels inside this mask only. Default is no masking. -model FORMULA: Specify the model structure for all the variables. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. In the LME context the simplest model is "1+(1|Subj)" in which the random effect from each of the two subjects in a pair is symmetrically incorporated in the model. Each random-effects factor is specified within parentheses per formula convention in R. Any effects of interest and confounding variables (quantitative or categorical variables) can be added as fixed effects without parentheses. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached (otherwise the output would be saved in AFNI format). -qVarCenters VALUES: Specify centering values for quantitative variables identified under -qVars. Multiple centers are separated by commas (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -qVarCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the values are fed into -dataTable. -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarsCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ substantially in the average value of the covariate. -R2: Enabling this option will prompt the program to provide both conditional and marginal coefficient of determination (R^2) values associated with the adopted model. Marginal R^2 indicates the proportion of variance explained by the fixed effects in the model, while conditional R^2 represents the proportion of variance explained by the entire model, encompassing both fixed and random effects. Two sub-bricks labeled 'R2m' and 'R2c' will be provided in the output. -resid PREFIX: Output file name for the residuals. For AFNI format, provide prefix only without view+suffix. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. The sub-brick labeled with the '(Intercept)', if present, should be interpreted as the effect with each factor at the reference level (alphabetically the lowest level) for each factor and with each quantitative covariate at the center value. -Rio: Use R's io functions. The alternative is -cio. -show_allowed_options: list of allowed options -SS_type NUMBER: Specify the type for sums of squares in the F-statistics. Three options are: sequential (1), hierarchical (2), and marginal (3). When this option is absent (default), marginal (3) is automatically set. Some discussion regarding their differences can be found here: https://sscc.nimh.nih.gov/sscc/gangc/SS.html -TRR: This option will allow the analyst to perform test-retest reliability analysis at the whole-brain voxel level. To be able to adopt this modeling approach, trial-level effect estimates have to be provided from each subject (e.g., using option -stim_times_IM in 3dDeconvolve/3dREMLfit). Currently it works with the situation with two conditions for a group of subjects that went two sessions. The analytical goal to assess test-retest reliability across the two sessions for the contrast between the two conditions. Check out Example 4 for model specification. It is possible that numerical failures may occur for a contrast between two conditions with values of 0, 1 or -1 in the output. Use program TRR for ROI-level test-retest reliability analysis. -vVarCenters VALUES: Specify centering values for voxel-wise covariates identified under -vVars. Multiple centers are separated by commas (,) within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -vVarsCenters) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable yourself first before the files are fed under -dataTable. -vVars variable_list: Identify voxel-wise covariates with this option. Currently one voxel-wise covariate is allowed only. By default mean centering is performed voxel-wise across all subjects. Alternatively centering can be specified through a global value under -vVarsCenters. If the voxel-wise covariates have already been centered, set the centers at 0 with -vVarsCenters.

AFNI program: 3dLocalACF
Usage: 3dLocalACF [options] inputdataset Options: -------- -prefix ppp -input inputdataset -nbhd nnn -mask maskdataset -automask Notes: ------ * This program estimates the spatial AutoCorrelation Function (ACF) locally in a neighborhood around each voxel, unlike '3FWHMx -acf', which produces an average over the whole volume. * The input dataset must be a time series dataset, and must have been detrended, despiked, etc. already. The 'errts' output from afni_proc.py is recommended! * A brain mask is highly recommended as well. * I typically use 'SPHERE(25)' for the neighborhood. YMMV. * This program is very slow. This copy of it uses multiple threads (OpenMP), so it is somewhat tolerable to use. ***** This program is experimental ***** ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLocalBistat
Usage: 3dLocalBistat [options] dataset1 dataset2 This program computes statistics between 2 datasets, at each voxel, based on a local neighborhood of that voxel. - The neighborhood is defined by the '-nbhd' option. - Statistics to be calculated are defined by the '-stat' option(s). - The 2 input datasets should have the same number of sub-bricks. - OR dataset1 should have 1 sub-brick and dataset2 can have more than 1: - In which case, the statistics of dataset2 against dataset1 are calculated for the #0 sub-brick of dataset1 against each sub-brick of dataset2. OPTIONS ------- -nbhd 'nnn' = The string 'nnn' defines the region around each voxel that will be extracted for the statistics calculation. The format of the 'nnn' string are: * 'SPHERE(r)' where 'r' is the radius in mm; the neighborhood is all voxels whose center-to- center distance is less than or equal to 'r'. ** A negative value for 'r' means that the region is calculated using voxel indexes rather than voxel dimensions; that is, the neighborhood region is a "sphere" in voxel indexes of "radius" abs(r). * 'RECT(a,b,c)' is a rectangular block which proceeds plus-or-minus 'a' mm in the x-direction, 'b' mm in the y-direction, and 'c' mm in the z-direction. The correspondence between the dataset xyz axes and the actual spatial orientation can be determined by using program 3dinfo. ** A negative value for 'a' means that the region extends plus-and-minus abs(a) voxels in the x-direction, rather than plus-and-minus a mm. Mutatis mutandum for negative 'b' and/or 'c'. * 'RHDD(r)' is a rhombic dodecahedron of 'radius' r. * 'TOHD(r)' is a truncated octahedron of 'radius' r. -stat sss = Compute the statistic named 'sss' on the values extracted from the region around each voxel: * pearson = Pearson correlation coefficient * spearman = Spearman correlation coefficient * quadrant = Quadrant correlation coefficient * mutinfo = Mutual Information * normuti = Normalized Mutual Information * jointent = Joint entropy * hellinger= Hellinger metric * crU = Correlation ratio (Unsymmetric) * crM = Correlation ratio (symmetrized by Multiplication) * crA = Correlation ratio (symmetrized by Addition) * L2slope = slope of least-squares (L2) linear regression of the data from dataset1 vs. the dataset2 (i.e., d2 = a + b*d1 ==> this is 'b') * L1slope = slope of least-absolute-sum (L1) linear regression of the data from dataset1 vs. the dataset2 * num = number of the values in the region: with the use of -mask or -automask, the size of the region around any given voxel will vary; this option lets you map that size. * ALL = all of the above, in that order More than one '-stat' option can be used. -mask mset = Read in dataset 'mset' and use the nonzero voxels therein as a mask. Voxels NOT in the mask will not be used in the neighborhood of any voxel. Also, a voxel NOT in the mask will have its statistic(s) computed as zero (0). -automask = Compute the mask as in program 3dAutomask. -mask and -automask are mutually exclusive: that is, you can only specify one mask. -weight ws = Use dataset 'ws' as a weight. Only applies to 'pearson'. -prefix ppp = Use string 'ppp' as the prefix for the output dataset. The output dataset is always stored as floats. ADVANCED OPTIONS ---------------- -histpow pp = By default, the number of bins in the histogram used for calculating the Hellinger, Mutual Information, and Correlation Ratio statistics is n^(1/3), where n is the number of data points in the -nbhd mask. You can change that exponent to 'pp' with this option. -histbin nn = Or you can just set the number of bins directly to 'nn'. -hclip1 a b = Clip dataset1 to lie between values 'a' and 'b'. If 'a' and 'b' end in '%', then these values are percentage points on the cumulative histogram. -hclip2 a b = Similar to '-hclip1' for dataset2. ----------------------------- Author: RWCox - October 2006. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLocalHistog
++ 3dLocalHistog: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: Thorin Oakenshield Usage: 3dLocalHistog [options] dataset ... This program computes, at each voxel, a count of how many times each unique value occurs in a neighbhood of that voxel, across all the input datasets. * The neighborhood is defined by the '-nbhd' option. * The input datasets should be in short or byte format, without scaling factors attached. * You can input float format datasets, but the values will be rounded to an integer between -32767 and 32767 before being used. * You can also output the overall histogram of the dataset collection, via the '-hsave' option (as a 1D file). This is simply the count of how many times each value occurs. * For histograms of continuously valued datasets see program 3dLocalstat with option -stat hist* OPTIONS ------- -nbhd 'nnn' = The string 'nnn' defines the region around each voxel that will be extracted for the statistics calculation. The format of the 'nnn' string is the same as in 3dLocalstat: * 'SPHERE(r)' * 'RECT(a,b,c)' * 'RHDD(a)' * 'TOHD(a)' * If no '-nbhd' option is given, then just the voxel itself is used -- in which case, the input dataset(s) must comprise a total of at least 2 sub-bricks! -prefix ppp = Use string 'ppp' as the prefix for the output dataset. -hsave sss = Save the overall histogram into file 'sss'. This file will have 2 columns: value count Values with zero count will not be shown in this file. -lab_file LL = Use file 'LL' as a label file. The first column contains the numbers, the second column the corresponding labels. * You can use a column selector to choose the columns you want. For example, if the first column has the labels and the second the values, use 'filename[1,0]'. -exclude a..b = Exclude values from 'a' to 'b' from the counting. * Zero (0) will never be excluded. * You can use '-exclude' more than once. -excNONLAB = If '-lab_file' is used, then exclude all values that are NOT in the label file (except for 0, of course). -mincount mm = Exclude values which appear in the overall histogram fewer than 'mm' times. * Excluded values will be treated as if they are zero (and so appear in the '0:Other' output sub-brick). * The overall histogram output by '-hsave' is NOT altered by the use of '-mincount' or '-exclude' or '-excNONLAB'. -prob = Normally, the output dataset is a set of counts. This option converts each count to a 'probability' by dividing by the total number of counts at each voxel. * The resulting dataset is stored as bytes, in units of 0.01, so that p=1 corresponds to 1/0.01=100. -quiet = Stop the highly informative progress reports. OUTPUT DATASET -------------- * For each distinct value a sub-brick is produced. * The zero value will be first; after that, the values will appear in increasing order. * If '-lab_file' is used, then the sub-brick label for a given value's count will be of the form 'value:label'; for example, '2013:rh.lingual'. * For values NOT in the '-lab_file', the label will just be of the form 'value:'. * For the first (value=0) sub-brick, the label will be '0:Other'. Author: RWCox - April 2013 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLocalPV
Usage: 3dLocalPV [options] inputdataset * You may want to use 3dDetrend before running this program, or at least use the '-polort' option. * This program is highly experimental. And slowish. Real slowish. * Computes the SVD of the time series from a neighborhood of each voxel. An inricate way of 'smoothing' 3D+time datasets, kind of, sort of. * This is like 3dLocalSVD, except that the '-vproj' option doesn't allow anything but 1 and 2 dimensional projection. This is because 3dLocalPV uses a special method to compute JUST the first 1 or 2 principal vectors -- faster than 3dLocalSVD, but less general. Options: -mask mset = restrict operations to this mask -automask = create a mask from time series dataset -prefix ppp = save SVD vector result into this new dataset [default = 'LocalPV'] -prefix2 qqq = save second principal vector into this new dataset [default = don't save it] -evprefix ppp = save singular value at each voxel into this dataset [default = don't save] -input inputdataset = input time series dataset -nbhd nnn = e.g., 'SPHERE(5)' 'TOHD(7)' etc. -despike = remove time series spikes from input dataset -polort p = detrending -vnorm = normalize data vectors [strongly recommended] -vproj [2] = project central data time series onto local SVD vector; if followed by '2', then the central data time series will be projected on the 2-dimensional subspace spanned by the first 2 principal SVD vectors. [default: just output principal singular vector] [for 'smoothing' purposes, '-vnorm -vproj' is an idea] Notes: * On my Mac Pro, about 30% faster than 3dLocalSVD computing the same thing. * If you're curious, the 'special method' used for the eigensolution is a variant of matrix power iteration, called 'simultaneous iteration'. * This method uses pseudo-random numbers to initialize the vector iterations. If you wish to control that seed, set environment variable AFNI_RANDOM_SEEDVAL to some nonzero number. Otherwise, a random seed will be selected from the time, which means otherwise identical runs will give slightly different results. * By contrast, 3dLocalSVD uses EISPACK functions for eigensolution-izing. ========================================================================= * This binary version of 3dLocalPV is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLocalstat
++ 3dLocalstat: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: Emperor Zhark Usage: 3dLocalstat [options] dataset This program computes statistics at each voxel, based on a local neighborhood of that voxel. - The neighborhood is defined by the '-nbhd' option. - Statistics to be calculated are defined by the '-stat' option(s). OPTIONS ------- -nbhd 'nnn' = The string 'nnn' defines the region around each voxel that will be extracted for the statistics calculation. The format of the 'nnn' string are: * 'SPHERE(r)' where 'r' is the radius in mm; the neighborhood is all voxels whose center-to- center distance is less than or equal to 'r'. ** The distances are computed in 3 dimensions, so a SPHERE(1) on a 1mm3 grid gives a 7 voxel- neighborhood - the center voxel and the six facing voxels, 4 in plane and 2 above and below. A SPHERE(1.42) contains 19 voxels, the center voxel with the 8 others in plane, and the 5 above and below (all voxels sharing an edge with the center) A SPHERE(1.74) contains 27 voxels, all voxels sharing a face, edge or corner with the center ** A negative value for 'r' means that the region is calculated using voxel indexes rather than voxel dimensions; that is, the neighborhood region is a "sphere" in voxel indexes of "radius" abs(r). * 'RECT(a,b,c)' is a rectangular block which proceeds plus-or-minus 'a' mm in the x-direction, 'b' mm in the y-direction, and 'c' mm in the z-direction. The correspondence between the dataset xyz axes and the actual spatial orientation can be determined by using program 3dinfo. ** Note the a,b,c are not the full dimensions of of the block. They are radially used - effectively half the dimension of a side. So if one wanted to compute a 5-slice projection on a 1mm3 volume, then a RECT(0,0,2) would be appropriate, and the program would report 5 voxels used in the mask Any dimension less than a voxel will avoid voxels in that direction. ** A negative value for 'a' means that the region extends plus-and-minus abs(a) voxels in the x-direction, rather than plus-and-minus a mm. Mutatis mutandum for negative 'b' and/or 'c'. * 'RHDD(a)' where 'a' is the size parameter in mm; this is Kepler's rhombic dodecahedron [volume=2*a^3]. * 'TOHD(a)' where 'a' is the size parameter in mm; this is a truncated octahedron. [volume=4*a^3] ** This is the polyhedral shape that tiles space and is the most 'sphere-like'. * If no '-nbhd' option is given, the region extracted will just be the voxel and its 6 nearest neighbors. * Voxels not in the mask (if any) or outside the dataset volume will not be used. This means that different output voxels will have different numbers of input voxels that went into calculating their statistics. The 'num' statistic can be used to get this count on a per-voxel basis, if you need it. -stat sss = Compute the statistic named 'sss' on the values extracted from the region around each voxel: * mean = average of the values * stdev = standard deviation * var = variance (stdev*stdev) * cvar = coefficient of variation = stdev/fabs(mean) * median = median of the values * osfilt = order statistics filter; similar to mean or median (also in AFNI GUI Image window -> Disp -> Project) * MAD = median absolute deviation * min = minimum * max = maximum * absmax = maximum of the absolute values * mconex = Michelson contrast of extrema: |A-B|/(|A|+|B|), where A=max and B=min * mode = mode * nzmode = non-zero mode * num = number of the values in the region: with the use of -mask or -automask, the size of the region around any given voxel will vary; this option lets you map that size. It may be useful if you plan to compute a t-statistic (say) from the mean and stdev outputs. * filled = 1 or fillvalue if all voxels in neighborhood are within mask * unfilled = 1 or unfillvalue if not all voxels in neighborhood are within mask * hasmask = unfillvalue if neighborhood contains a specified mask value * hasmask2 = unfillvalue if neighborhood contains an alternate mask value * sum = sum of the values in the region * FWHM = compute (like 3dFWHM) image smoothness inside each voxel's neighborhood. Results are in 3 sub-bricks: FWHMx, FWHMy, and FWHMz. Places where an output is -1 are locations where the FWHM value could not be computed (e.g., outside the mask). * FWHMbar= Compute just the average of the 3 FWHM values (normally would NOT do this with FWHM also). * perc:P0:P1:Pstep = Compute percentiles between P0 and P1 with a step of Pstep. Default P1 is equal to P0 and default P2 = 1 * rank = rank of the voxel's intensity * frank = rank / number of voxels in neighborhood * P2skew = Pearson's second skewness coefficient 3 * (mean - median) / stdev * ALL = all of the above, in that order (except for FWHMbar and perc). * mMP2s = Exactly the same output as: -stat median -stat MAD -stat P2skew but it a little faster * mmMP2s = Exactly the same output as: -stat mean -stat median -stat MAD -stat P2skew * diffs = Compute differences between central voxel and all neighbors. Values output are the average difference, followed by the min and max differences. * list = Just output the voxel values in the neighborhood The order in which the neighbors are listed depends on the neighborhood selected. Only SPHERE results in a neighborhood list sorted by the distance from the center. Regardless of the neighborhood however, the first value should always be that of the central voxel. * hist:MIN:MAX:N[:IGN] = Compute the histogram in the voxel's neighborhood. You must specify the min, max, and the number of bins in the histogram. You can also ignore values outside the [min max] range by setting IGN to 1. IGN = 0 by default. The histograms are scaled by the number of values that went into the histogram. That would be the number of non-masked voxels in the neighborhood if outliers are NOT ignored (default). For histograms of labeled datasets, use 3dLocalHistog More than one '-stat' option can be used. -mask mset = Read in dataset 'mset' and use the nonzero voxels therein as a mask. Voxels NOT in the mask will not be used in the neighborhood of any voxel. Also, a voxel NOT in the mask will have its statistic(s) computed as zero (0) -- usually (cf. supra). -automask = Compute the mask as in program 3dAutomask. -mask and -automask are mutually exclusive: that is, you can only specify one mask. -use_nonmask = Just above, I said that voxels NOT in the mask will not have their local statistics computed. This option will make it so that voxels not in the mask WILL have their local statistics computed from all voxels in their neighborhood that ARE in the mask. * You could use '-use_nonmask' to compute the average local white matter time series, for example, even at non-WM voxels. -prefix ppp = Use string 'ppp' as the prefix for the output dataset. The output dataset is normally stored as floats. -datum type = Coerce the output data to be stored as the given type, which may be byte, short, or float. Default is float -label_ext LABEXT = Append '.LABEXT' to each sub-brick label -reduce_grid Rx [Ry Rz] = Compute output on a grid that is reduced by a factor of Rx Ry Rz in the X, Y, and Z directions of the input dset. This option speeds up computations at the expense of resolution. You should only use it when the nbhd is quite large with respect to the input's resolution, and the resultant stats are expected to be smooth. You can either set Rx, or Rx Ry and Rz. If you only specify Rx the same value is applied to Ry and Rz. -reduce_restore_grid Rx [Ry Rz] = Like reduce_grid, but also resample output back to input grid. -reduce_max_vox MAX_VOX = Like -reduce_restore_grid, but automatically set Rx Ry Rz so that the computation grid is at a resolution of nbhd/MAX_VOX voxels. -grid_rmode RESAM = Interpolant to use when resampling the output with reduce_restore_grid option. The resampling method string RESAM should come from the set {'NN', 'Li', 'Cu', 'Bk'}. These stand for 'Nearest Neighbor', 'Linear', 'Cubic' and 'Blocky' interpolation, respectively. Default is Linear -quiet = Stop the highly informative progress reports. -verb = a little more verbose. -proceed_small_N = Do not crash if neighborhood is too small for certain estimates. -fillvalue x.xx = value used for filled statistic, default=1 -unfillvalue x.xx = value used for unfilled statistic, default=1 -maskvalue x.xx = value searched for with has_mask option -maskvalue2 x.xx = alternate value for has_mask2 option Author: RWCox - August 2005. Instigator: ZSSaad. ========================================================================= * This binary version of 3dLocalstat is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLocalSVD
Usage: 3dLocalSVD [options] inputdataset * You may want to use 3dDetrend before running this program, or at least use the '-polort' option. * This program is highly experimental. And slowish. * Computes the SVD of the time series from a neighborhood of each voxel. An inricate way of 'smoothing' 3D+time datasets, in some sense, maybe. * For most purposes, program 3dLocalPV does the same thing, but faster. The only reason to use 3dLocalSVD is if you are using -vproj with the projection dimension ndim > 2. Options: -mask mset = restrict operations to this mask -automask = create a mask from time series dataset -prefix ppp = save SVD vector result into this new dataset -input inputdataset = input time series dataset -nbhd nnn = e.g., 'SPHERE(5)' 'TOHD(7)' etc. -polort p [+] = detrending ['+' means to add trend back] -vnorm = normalize data vectors [strongly recommended] -vproj [ndim] = project central data time series onto local SVD subspace of dimension 'ndim' [default: just output principal singular vector] [for 'smoothing' purposes, '-vnorm -vproj 2' is a good idea] ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLocalUnifize
------------------------------------------------------------------------- OVERVIEW ~1~ This program takes an input and generates a simple "unifized" output volume. It estimates the median in the local neighborhood of each voxel, and uses that to scale each voxel's brightness. The result is a new dataset of brightness of order 1, which still has the interesting structure(s) present in the original. This program's output looks very useful to help with dataset alignment (esp. EPI-to-anatomical) in a wide array of cases. ver : 1.2 date : Jan 29, 2024 auth : PA Taylor (SSCC, NIMH, NIH) USAGE ~1~ This program is generally run as: 3dLocalUnifize [options] -prefix DSET_OUT -input DSET_IN where the following options exist: -input DSET_IN :(req) input dataset -prefix DSET_OUT :(req) output dataset name, including path -wdir_name WD :name of temporary working directory, which should not contain any path information---it will be created in the same directory as the final dataset is created (def: __wdir_LocalUni_, plus a random alphanumeric str) -echo :run this program very verbosely (def: don't do so) -no_clean :do not remove the working directory (def: remove it) ... and the following are 'tinkering' options, likely not needed in most cases: -local_rad LR :the spherical neighborhood's radius for the 3dLocalStat step (def: -3) -local_perc LP :the percentile used in the 3dLocalStat step, generating the scaling volume (def: 50) -local_mask LM :provide the masking option to be used in the 3dLocalStat step, which should be enclosed in quotes for passing along to the internal program call. So, to use a pre-existing mask, you might call this option like: -local_mask "-mask my_mask.nii.gz" To remove any masking, put the special keyword "None" as the option value. (def: "-automask") -filter_thr FT :put a ceiling on values in the final, scaled dataset, whose values should be of order 1; setting FT to be a value <=0 turns off this final filtering (def: 1.5) NOTES ~1~ This program is designed to not need a lot of tinkering with options, such as the '-local_* ..' ones. In most cases, the default scaling will be useful. EXAMPLES ~1~ 1. Basic local unifizing: 3dLocalUnifize \ -prefix vr_base_LU \ -input vr_base_min_outlier+orig.HEAD 1. Same as above, without masking: 3dLocalUnifize \ -prefix vr_base_LU_FOV \ -input vr_base_min_outlier+orig.HEAD \ -local_mask None

AFNI program: 3dLombScargle
++ Reading in options. Make a periodogram or amplitude-spectrum of a time series that has a non-constant sampling rate. The spectra output by this program are 'one-sided', so that they represent the half-amplitude or power associated with a frequency, and they would require a factor of 2 to account for both the the right- and left-traveling frequency solutions of the Fourier transform (see below 'OUTPUT' and 'NOTE'). Of particular interest is the application of this functionality to resting state time series that may have been censored. The theory behind the mathematics and algorithms of this is due to separate groups, mainly in the realm of astrophysical applications: Vaníček (1969, 1971), Lomb (1976), Scargle (1982), and Press & Rybicki (1989). Shoutout to them. This particular implementation is due to Press & Rybicki (1989), by essentially translating their published Fortran implementation into C, while using GSL for the FFT, instead of NR's realft(), and making several adjustments based on that. The Lomb-Scargle adaption was done with fairly minimal changes here by PA Taylor (v1.4, June, 2016). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + USAGE: Input a 4D volumetric time series (BRIK/HEAD or NIFTI data set) as well as an optional 1D file of 0s and 1s that defines which points to censor out (i.e., each 0 represents a point/volume to censor out); if no 1D file is input, the program will check for volumes that are uniformly zero and consider those to be censored. The output is a LS periodogram, describing spectral magnitudes up to some 'maximum frequency'-- the default max here is what the Nyquist frequency of the time series *would have been* without any censoring. (Interestingly, this analysis can actually be legitimately applied in cases to estimate frequency content >Nyquist. Wow!) The frequency spectrum will be in the range [df, f_N], where: df = 1/T, and T is the total duration of the uncensored time series; f_N = 1/dt, and dt is the sampling time (i.e., TR); and the interval of frequencies is also df. These ranges and step sizes should be *independent* of the censoring which is a nice property of the Lomb-Scargle-iness. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUT: 1) PREFIX_time.1D :a 1D file of the sampled time points (in units of seconds) of the analyzed (and possibly censored) data set. 2) PREFIX_freq.1D :a 1D file of the frequency sample points (in units of 1/seconds) of the output periodogram/spectrum data set. 3) PREFIX_amp+orig :volumetric data set containing a LS-derived or amplitude spectrum (by default, named 'amp') or a PREFIX_pow+orig power spectrum (see '-out_pow_spec', named 'pow') one per voxel. Please note that the output amplitude and power spectra are 'one-sided', to represent the *half* amplitude or power of a given frequency (see the following note). + A NOTE ABOUT Fourier+Parseval matters (please forgive the awkward formatting): In the formulation used here, for a time series x[n] of length N, the periodogram value S[k] is related to the amplitude value |X[k]|: (1) S[k] = (|X[k]|)**2, for each k-th harmonic. Parseval's theorem relates time fluctuations to spectral amplitudes, stating that (for real time series with zero mean): (2) sum_n{ x[n]**2 } = (1/N) * sum_k{ |X[k]|**2 }, = (1/N) * sum_k{ S[k] }, where n=0,1,..,N-1 and k=0,1,..,N-1 (NB: A[0]=0, for zero mean series). The LHS is essentially the variance of the time series (times N-1). The above is derived from Fourier transform maths, and the Lomb-Scargle spectra are approximations to Fourier, so the above can be expected to approximately hold, if all goes well. Another Fourier-related result is that for real, discrete time series, the spectral amplitudes/power values are symmetric and periodic in N. Therefore, |X[k]| = |X[-k]| = |X[N-k-1]| (in zero-base array counting); the distinction between positive- and negative-indexed frequencies can be thought of as signifying right- and left-traveling waves, which both contribute to the total power of a specific frequency. The upshot is that one could write the Parseval formula as: (3) sum_n{ x[n]**2 } = (2/N) * sum_l{ |X[l]|**2 }, = (2/N) * sum_l{ S[l] }, where n=0,1,..,N-1 and l=0,1,..,(N/2)-1 (note the factor of 2 now appearing on the RHS relations). These symmetries/considerations are the reason why ~N/2 frequency values are output here (we assume that only real-valued time series are input), without any loss of information. Additionally, with a view toward expressing the overall amplitude or power of a given frequency, which many people might want to use to estimate spectral 'functional connectivity' parameters such as ALFF, fALFF, RSFA, etc. (using, for example, 3dAmptoRSFC), we therefore note that the *total* amplitude or power of a given frequency would be: A[k] = 2*|X[k]| P[k] = 2*S[k] = 2*|X[k]|**2 = 0.5*A[k]**2 instead of just that of the left/right traveling part. These types of quantities (A and P) are also referred to as 'two-sided' spectra. The resulting Parseval relation could then be written: (4) sum_n{ x[n]**2 } = (1/(2N)) * sum_l{ A[l]**2 }, = (1/N) * sum_l{ P[l] }, where n=0,1,..,N-1 and l=0,1,..,(N/2)-1. Somehow, it just seems easier to output the one-sided values, X and S, so that the Parsevalian summation rules look more similar. With all of that in mind, the 3dLombScargle results are output as follows. For amplitudes, the following approx. Parsevellian relation should hold between the 'holey' time series x[m] of M points and the frequency series Y[l] of L~M/2 points (where {|Y[l]|} approaches the Fourier amplitudes {|X[l]|} as the number of censored points decreases and M->N): (5) sum_m{ x[m]**2 } = (1/L) * sum_l{ Y[l]**2 }, where m=0,1,..,M-1 and l=0,1,..,L-1. For the power spectrum T[l] of L~M/2 values, then: (6) sum_m{ x[m]**2 } = (1/L) * sum_l{ T[l] } for the same ranges of summations. So, please consider that when using the outputs of here. 3dAmpToRSFC is prepared for this when calculating spectral parameters (from amplitudes). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: 3dLombScargle -prefix PREFIX -inset FILE \ {-censor_1D C1D} {-censor_str CSTR} \ {-mask MASK} {-out_pow_spec} \ {-nyq_mult N2} {-nifti} * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + RUNNING: -prefix PREFIX :output prefix name for data volume, time point 1D file and frequency 1D file. -inset FILE :time series of volumes, a 4D volumetric data set. -censor_1D C1D :single row or column of 1s (keep) and 0s (censored) describing which volumes of FILE are kept in the sampling and which are censored out, respectively. The length of the list of numbers must be of the same length as the number of volumes in FILE. If not entered, then the program will look for subbricks of all-zeros and assume those are censored out. -censor_str CSTR :AFNI-style selector string of volumes to *keep* in the analysis. Such as: '[0..4,7,10..$]' Why we refer to it as a 'censor string' when it is really the list of volumes to keep... well, it made sense at the time. Future historians can duel with ink about it. -mask MASK :optional, mask of volume to analyze; additionally, any voxel with uniformly zero values across time will produce a zero-spectrum. -out_pow_spec :switch to output the amplitude spectrum of the freqs instead of the periodogram. In the formulation used here, for a time series of length N, the power spectral value S is related to the amplitude value X as: S = (X)**2. (Without this opt, default output is amplitude spectrum.) -nyq_mult N2 :L-S periodograms can include frequencies above what would typically be considered Nyquist (here defined as: f_N = 0.5*(number of samples)/(total time interval) By default, the maximum frequency will be what f_N *would* have been if no censoring of points had occurred. (This makes it easier to compare L-S spectra across a group with the same scan protocol, even if there are slight differences in censoring, per subject.) Acceptable values are >0. (For those reading the algorithm papers, this sets the 'hifac' parameter.) If you don't have a good reason for changing this, dooon't change it! -nifti :switch to output *.nii.gz volume file (default format is BRIK/HEAD). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dLombScargle -prefix LSout -inset TimeSeries.nii.gz \ -mask mask.nii.gz -censor_1D censor_list.txt * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ____________________________________________________________________________

AFNI program: 3dLRflip
Usage: 3dLRflip [-LR|-AP|-IS|-X|-Y|-Z] [-prefix ppp] dset dset dset ... Flips the rows of a dataset along one of the three axes. * This program is intended to be used in the case where you (or some other loser) constructed a dataset with one of the directions incorrectly labeled. * That is, it is to help you patch up a mistake in the dataset. It has no other purpose. Optional options: ----------------- -LR | -AP | -IS: Axis about which to flip the data Default is -LR. or -X | -Y | -Z: Flip about 1st, 2nd or 3rd directions, respectively. Note: Only one of these 6 options can be used at a time. -prefix ppp: Prefix to use for output. If you have multiple datasets as input, you are better off letting the program choose a prefix for each output. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dLSS
Usage: 3dLSS [options] ** Least-Squares-Sum (LSS) estimation from a -stim_times_IM matrix, as ** * described in the paper: * * JA Mumford et al. Deconvolving BOLD activation in event-related * * designs for multivoxel pattern classification analyses. * * NeuroImage (2011) http://dx.doi.org/10.1016/j.neuroimage.2011.08.076 * * LSS regression was first mentioned in this poster: * * B Turner. A comparison of methods for the use of pattern classification * * on rapid event-related fMRI data. Annual Meeting of the Society for * ** Neuroscience, San Diego, CA (2010). ** The method implemented here can be described (by me) as a 'pull one out' approach. That is, for a single trial in the list of trials, its individual regressor is pulled out and kept separate, and all the other trials are combined to give another regressor - so that if there are N trials, only 2 regressors (instead of N) are used for the response model. This 'pull out' approach is repeated for each single trial separately (thus doing N separate regressions), which gives a separate response amplitude (beta coefficient) for each trial. See the 'Caveats' section below for more information. ---------------------------------------- Options (the first 'option' is mandatory) ---------------------------------------- -matrix mmm = Read the matrix 'mmm', which should have been output from 3dDeconvolve via the '-x1D' option, and should have included exactly one '-stim_times_IM' option. -->> The 3dLSS algorithm requires that at least 2 different stimulus times be given in the -stim_times_IM option. If you have only 1 stim time, this program will not run. In such a case, the normal '-bucket' output from 3dDeconvolve (or '-Rbuck' output from 3dREMLfit) will have the single beta for the single stim time. -input ddd = Read time series dataset 'ddd' ** OR ** -nodata = Just compute the estimator matrix -- to be saved with '-save1D'. * The number of time points is taken from the matrix header. * If neither '-input' nor '-nodata' is given, '-nodata' is used. * If '-input' is used, the number of time points in the dataset must match the number of time points in the matrix. -mask MMM = Read dataset 'MMM' as a mask for the input; voxels outside the mask will not be fit by the regression model. -automask = If you don't know what this does by now, please don't use this program. * Neither of these options has any meaning for '-nodata'. * If '-input' is used and neither of these options is given, then all voxels will be processed. -prefix ppp = Prefix name for the output dataset; this dataset will contain ONLY the LSS estimates of the beta weights for the '-stim_times_IM' stimuli. * If you don't use '-prefix', then the prefix is 'LSSout'. -save1D qqq = Save the estimator vectors (cf. infra) to a 1D formatted file named 'qqq'. Each column of this file will be one estimator vector, the same length as the input dataset timeseries (after censoring, if any). * The j-th LSS beta estimate is the dot product of the j-th column of this file with the data time series (duly censored). * If you don't use '-save1D', then this file is not saved. -verb = Write out progress reports, for fun fun fun in the sun sun sun. ------------------- Method == EQUATIONS ------------------- 3dLSS is fast, since it uses a rank-1 bordering technique to pre-compute the estimator for each separate stimulus regressor from the fixed part of the matrix, then applies these estimators to each time series in the input dataset by a simple dot product. If you wish to peruse the equations, see https://afni.nimh.nih.gov/pub/dist/doc/misc/3dLSS/3dLSS_mathnotes.pdf The estimator for each separate beta (as described at '-save1D') is the N-vector which, when dotted into the N-vector of a voxel's time series, gives the LSS beta estimate for that voxel. --------------------- Caveats == READ THIS! --------------------- The LSS method produces estimates that tend to have smaller variance than the LSA method that 3dDeconvolve would produce, but the LSS estimates have greater bias -- in principle, the LSA method is unbiased if the noise is symmetrically distributed. For the purpose of using the beta estimates for MVPA (e.g., 3dsvm), the bias may not matter much and the variance reduction may help improve the classification, as illustrated in the Mumford paper. For other purposes, the trade-off might well go the other way -- for ANY application of LSS vs. LSA, you need to assess the situation before deciding -- probably by the judicious use of simulation (as in the Mumford paper). The bias in the estimate of any given beta is essentially due to the fact that for any given beta, LSS doesn't use an estimator vector that is orthogonal to the regressors for other coefficients -- that is what LSA does, using the pseudo-inverse. Typically, any given LSS-estimated beta will include a mixture of the betas from neighboring stimuli -- for example, beta8{LSS} = beta8{LSA} + 0.3*beta7{LSA} - 0.1*beta9{LSA} + smaller stuff where the weights of the neighbors are larger if the corresponding stimuli are closer (so the regressors overlap more). The LSS betas are NOT biased by including any betas that aren't from the -stim_times_IM regressors -- the LSS estimator vectors (what '-save1D' gives) are orthogonal to those 'nuisance' regression matrix columns. To investigate these weighting and orthogonality issues yourself, you can multiply the LSS estimator vectors into the 3dDeconvolve regression matrix and examine the result -- in the ideal world, the matrix would be all 0 except for 1s on diagonal corresponding to the -stim_times_IM betas. This calculation can be done in AFNI with commands something like the 'toy' example below, which has only 6 stimulus times: 3dDeconvolve -nodata 50 1.0 -polort 1 -x1D R.xmat.1D -x1D_stop -num_stimts 1 \ -stim_times_IM 1 '1D: 12.7 16.6 20.1 26.9 30.5 36.5' 'BLOCK(0.5,1)' 3dLSS -verb -nodata -matrix R.xmat.1D -save1D R.LSS.1D 1dmatcalc '&read(R.xmat.1D) &transp &read(R.LSS.1D) &mult &write(R.mult.1D)' 1dplot R.mult.1D & 1dgrayplot R.mult.1D & * 3dDeconvolve is used to setup the matrix into file R.xmat.1D * 3dLSS is used to compute the LSS estimator vectors into file R.LSS.1D * 1dmatcalc is used to multiply the '-save1D' matrix into the regression matrix: [R.mult.1D] = [R.xmat.1D]' [R.LSS.1D] where [x] = matrix made from columns of numbers in file x, and ' = transpose. * 1dplot and 1dgrayplot are used to display the results. * The j-th column in the R.mult.1D file is the set of weights of the true betas that influence the estimated j-th LSS beta. * e.g., Note that the 4th and 5th stimuli are close in time (3.6 s), and that the result is that the LSS estimator for the 4th and 5th beta weights mix up the 'true' 4th, 5th, and 6th betas. For example, looking at the 4th column of R.mult.1D, we see that beta4{LSS} = beta4{LSA} + 0.33*beta5{LSA} - 0.27*beta6{LSA} + small stuff * The sum of each column of R.mult.1D is 1 (e.g., run '1dsum R.mult.1D'), and the diagonal elements are also 1, showing that the j-th LSS beta is equal to the j-th LSA beta plus a weighted sum of the other LSA betas, where those other weights add up to zero. -------------------------------------------------------------------------- -- RWCox - Dec 2011 - Compute fast, abend early, leave a pretty dataset -- -------------------------------------------------------------------------- ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dMannWhitney
++ 3dMannWhitney: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program performs nonparametric Mann-Whitney two-sample test. Usage: 3dMannWhitney -dset 1 filename data set for X observations . . . . . . -dset 1 filename data set for X observations -dset 2 filename data set for Y observations . . . . . . -dset 2 filename data set for Y observations [-workmem mega] number of megabytes of RAM to use for statistical workspace [-voxel num] screen output for voxel # num -out prefixname estimated population delta and Wilcoxon-Mann-Whitney statistics written to file prefixname N.B.: For this program, the user must specify 1 and only 1 sub-brick with each -dset command. That is, if an input dataset contains more than 1 sub-brick, a sub-brick selector must be used, e.g.: -dset 2 'fred+orig[3]' INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dmaskave
++ 3dmaskave: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] Usage: 3dmaskave [options] inputdataset Computes average of all voxels in the input dataset which satisfy the criterion in the options list. If no options are given, then all voxels are included. ---------------------------------------------------------------- Examples: 1. compute the average timeseries in epi_r1+orig, over voxels that are set (any non-zero value) in the dataset, ROI+orig: 3dmaskave -mask ROI+orig epi_r1+orig 2. restrict the ROI to values of 3 or 4, and save (redirect) the output to the text file run1_roi_34.txt: 3dmaskave -mask ROI+orig -quiet -mrange 3 4 \ epi_r1+orig > run1_roi_34.txt 3. Extract the time series from a single voxel with given spatial indexes (e.g., for use with 3dTcorr1D): 3dmaskave -quiet -ibox 40 30 20 epi_r1+orig > r1_40_30_20.1D ---------------------------------------------------------------- Options: -mask mset Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be averaged from 'dataset'. Note that the mask dataset and the input dataset must have the same number of voxels. SPECIAL CASE: If 'mset' is the string 'SELF', then the input dataset will be used to mask itself. That is, only nonzero voxels from the #miv sub-brick will be used. -mindex miv Means to use sub-brick #'miv' from the mask dataset. If not given, miv=0. -mrange a b Means to further restrict the voxels from 'mset' so that only those mask values between 'a' and 'b' (inclusive) will be used. If this option is not given, all nonzero values from 'mset' are used. Note that if a voxel is zero in 'mset', then it won't be included, even if a < 0 < b. [-mindex and -mrange are old options that predate] [the introduction of the sub-brick selector '[]' ] [and the sub-range value selector '<>' to AFNI. ] -xbox x y z } These options are the same as in -dbox x y z } program 3dmaskdump: -nbox x y z } They create a mask by putting down boxes -ibox x y z } or balls (filled spheres) at the specified -xball x y z r } locations. See the output of -dball x y z r } 3dmaskdump -help -nball x y z r } for the gruesome and tedious details. https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dmaskdump.html -dindex div Means to use sub-brick #'div' from the inputdataset. If not given, all sub-bricks will be processed. -drange a b Means to only include voxels from the inputdataset whose values fall in the range 'a' to 'b' (inclusive). Otherwise, all voxel values are included. [-dindex and -drange are old options that predate] [the introduction of the sub-brick selector '[]' ] [and the sub-range value selector '<>' to AFNI. ] -slices p q Means to only included voxels from the inputdataset whose slice numbers are in the range 'p' to 'q' (inclusive). Slice numbers range from 0 to NZ-1, where NZ can be determined from the output of program 3dinfo. The default is to include data from all slices. [There is no provision for geometrical voxel] [selection except in the slice (z) direction] -sigma Means to compute the standard deviation in addition to the mean. -sum Means to compute the sum instead of the mean. -sumsq Means to compute the sum of squares instead of the mean. -enorm Means to compute the Euclidean norm instead of the mean. This is the sqrt() of the sumsq result. -median Means to compute the median instead of the mean. -max Means to compute the max instead of the mean. -min Means to compute the min instead of the mean. [-sigma is ignored with -sum, -median, -max, or -min.] [the last given of -sum, -median, -max, or -min wins.] -perc XX Means to compute the XX-th percentile value (min=0 max=100). XX should be an integer from 0 to 100. -dump Means to print out all the voxel values that go into the result. -udump Means to print out all the voxel values that go into the average, UNSCALED by any internal factors. N.B.: the scale factors for a sub-brick can be found using program 3dinfo. -indump Means to print out the voxel indexes (i,j,k) for each dumped voxel. Has no effect if -dump or -udump is not also used. N.B.: if nx,ny,nz are the number of voxels in each direction, then the array offset in the brick corresponding to (i,j,k) is i+j*nx+k*nx*ny. -q or -quiet Means to print only the minimal numerical result(s). This is useful if you want to create a *.1D file, without any extra text; for example: 533.814 [18908 voxels] == 'normal' output 533.814 == 'quiet' output The output is printed to stdout (the terminal), and can be saved to a file using the usual redirection operation '>'. Or you can do fun stuff like 3dmaskave -q -mask Mfile+orig timefile+orig | 1dplot -stdin -nopush to pipe the output of 3dmaskave into 1dplot for graphing. -- Author: RWCox INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dmaskdump
Usage: 3dmaskdump [options] dataset dataset ... Writes to an ASCII file values from the input datasets which satisfy the mask criteria given in the options. If no options are given, then all voxels are included. This might result in a GIGANTIC output file. Options: -mask mset Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be printed from 'dataset'. Note that the mask dataset and the input dataset must have the same number of voxels. -mrange a b Means to further restrict the voxels from 'mset' so that only those mask values between 'a' and 'b' (inclusive) will be used. If this option is not given, all nonzero values from 'mset' are used. Note that if a voxel is zero in 'mset', then it won't be included, even if a < 0 < b. -index Means to write out the dataset index values. -noijk Means not to write out the i,j,k values. -xyz Means to write the x,y,z coordinates from the 1st input dataset at the start of each output line. These coordinates are in the 'RAI' (DICOM) order. -o fname Means to write output to file 'fname'. [default = stdout, which you won't like] -cmask 'opts' Means to execute the options enclosed in single quotes as a 3dcalc-like program, and produce produce a mask from the resulting 3D brick. Examples: -cmask '-a fred+orig[7] -b zork+orig[3] -expr step(a-b)' produces a mask that is nonzero only where the 7th sub-brick of fred+orig is larger than the 3rd sub-brick of zork+orig. -cmask '-a fred+orig -expr 1-bool(k-7)' produces a mask that is nonzero only in the 7th slice (k=7); combined with -mask, you could use this to extract just selected voxels from particular slice(s). Notes: * You can use both -mask and -cmask in the same run - in this case, only voxels present in both masks will be dumped. * Only single sub-brick calculations can be used in the 3dcalc-like calculations - if you input a multi-brick dataset here, without using a sub-brick index, then only its 0th sub-brick will be used. * Do not use quotes inside the 'opts' string! -xbox x y z Means to put a 'mask' down at the dataset (not DICOM) coordinates of 'x y z' mm. Notes: * By default, this box is 1 voxel wide in each direction, rounding to the closest voxel center to the given single coordinate. Alternatively, one can specify a range of coordinates using colon ':' as a separator; for example: -xbox 22:27 31:33 44 means a box from (x,y,z)=(22,31,44) to (27,33,44). Use of the colon makes the range strict, meaning voxels outside the exact range will be omitted. Since 44 is not specified with a range, the closest z coordinate to 44 is used, while the x and y coordinates are strict. * Dataset coordinates are NOT the coordinates you typically see in AFNI's main controller top left corner. Those coordinates are typically in either RAI/DICOM order or in LPI/SPM order and should be used with -dbox and -nbox, respectively. -dbox x y z Means the same as -xbox, but the coordinates are in RAI/DICOM order (+x=Left, +y=Posterior, +z=Superior). If your AFNI environment variable AFNI_ORIENT is set to RAI, these coordinates correspond to those you'd enter into the 'Jump to (xyz)' control in AFNI, and to those output by 3dclust. NOTE: It is possible to make AFNI and/or 3dclust output coordinates in an order different from the one specified by AFNI_ORIENT, but you'd have to work hard on that. In any case, the order is almost always specified along with the coordinates. If you see RAI/DICOM, then use -dbox. If you see LPI/SPM then use -nbox. -nbox x y z Means the same as -xbox, but the coordinates are in LPI/SPM or 'neuroscience' order where the signs of the x and y coordinates are reversed relative to RAI/DICOM. (+x=Right, +y=Anterior, +z=Superior) -ibox i j k Means to put a 'mask' down at the voxel indexes given by 'i j k'. By default, this picks out just 1 voxel. Again, you can use a ':' to specify a range (now in voxels) of locations. Notes: * Boxes are cumulative; that is, if you specify more than 1 box, you'll get more than one region. * If a -mask and/or -cmask option is used, then the INTERSECTION of the boxes with these masks determines which voxels are output; that is, a voxel must be inside some box AND inside the mask in order to be selected for output. * If boxes select more than 1 voxel, the output lines are NOT necessarily in the order of the options on the command line. * Coordinates (for -xbox, -dbox, and -nbox) are relative to the first dataset on the command line. * It may be helpful to slightly pad boxes, to be sure they contain the desired voxel centers. -xball x y z r Means to put a ball (sphere) mask down at dataset coordinates (x,y,z) with radius r. -dball x y z r Same, but (x,y,z) are in RAI/DICOM order. -nball x y z r Same, but (x,y,z) are in LPI/SPM order. Notes: * The combined (set UNION) of all ball and/or box masks is created first. Then, if a -mask and/or -cmask option was used, then the ball+box mask will be INTERSECTED with the existing mask. * Balls not centered over voxels, or those applied to anisotropic volumes may not appear symmetric. * Consider slight padding to handle truncation. -nozero Means to skip output of any voxel where all the data values are zero. -n_rand N_RAND Means to keep only N_RAND randomly selected voxels from what would have been the output. -n_randseed SEED Seed the random number generator with SEED, instead of the default seed of 1234 -niml name Means to output data in the XML/NIML format that is compatible with input back to AFNI via the READ_NIML_FILE command. * 'name' is the 'target_name' for the NIML header field, which is the name that will be assigned to the dataset when it is sent into AFNI. * Also implies '-noijk' and '-xyz' and '-nozero'. -quiet Means not to print progress messages to stderr. Inputs after the last option are datasets whose values you want to be dumped out. These datasets (and the mask) can use the sub-brick selection mechanism (described in the output of '3dcalc -help') to choose which values you get. Each selected voxel gets one line of output: i j k val val val .... where (i,j,k) = 3D index of voxel in the dataset arrays, and val = the actual voxel value. Note that if you want the mask value to be output, you have to include that dataset in the dataset input list again, after you use it in the '-mask' option. * To eliminate the 'i j k' columns, use the '-noijk' option. * To add spatial coordinate columns, use the '-xyz' option. N.B.: This program doesn't work with complex-valued datasets! INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dmaskSVD
Usage: 3dmaskSVD [options] inputdataset Author: Zhark the Gloriously Singular * Computes the principal singular vector of the time series vectors extracted from the input dataset over the input mask. ++ You can use the '-sval' option to change which singular vectors are output. * The sign of the output vector is chosen so that the average of arctanh(correlation coefficient) over all input data vectors (from the mask) is positive. * The output vector is normalized: the sum of its components squared is 1. * You probably want to use 3dDetrend (or something similar) first, to get rid of annoying artifacts, such as motion, breathing, dark matter interactions with the brain, etc. ++ If you are lazy scum like Zhark, you might be able to get away with using the '-polort' option. ++ In particular, if your data time series has a nonzero mean, then you probably want at least '-polort 0' to remove the mean, otherwise you'll pretty much just get a constant time series as the principal singular vector! * An alternative to this program would be 3dmaskdump followed by 1dsvd, which could give you all the singular vectors you could ever want, and much more -- enough to confuse you for days. ++ In particular, although you COULD input a 1D file into 3dmaskSVD, the 1dsvd program would make much more sense. * This program will be pretty slow if there are over about 2000 voxels in the mask. It could be made more efficient for such cases, but you'll have to give Zhark some 'incentive'. * Result vector goes to stdout. Redirect per your pleasures and needs. * Also see program 3dLocalSVD if you want to compute the principal singular time series vector from a neighborhood of EACH voxel. ++ (Which is a pretty slow operation!) * http://en.wikipedia.org/wiki/Singular_value_decomposition ------- Options: ------- -vnorm = L2 normalize all time series before SVD [recommended!] -sval a = output singular vectors 0 .. a [default a=0 = first one only] -mask mset = define the mask [default is entire dataset == slow!] -automask = you'll have to guess what this option does -polort p = if you are lazy and didn't run 3dDetrend (like Zhark) -bpass L H = bandpass [mutually exclusive with -polort] -ort xx.1D = time series to remove from the data before SVD-ization ++ You can give more than 1 '-ort' option ++ 'xx.1D' can contain more than 1 column -input ddd = alternative way to give the input dataset name ------- Example: ------- You have a mask dataset with discrete values 1, 2, ... 77 indicating some ROIs; you want to get the SVD from each ROI's time series separately, and then put these into 1 big 77 column .1D file. You can do this using a csh shell script like the one below: # Compute the individual SVD vectors foreach mm ( `count_afni 1 77` ) 3dmaskSVD -vnorm -mask mymask+orig"<${mm}..${mm}>" epi+orig > qvec${mm}.1D end # Glue them together into 1 big file, then delete the individual files 1dcat qvec*.1D > allvec.1D /bin/rm -f qvec*.1D # Plot the results to a JPEG file, then compute their correlation matrix 1dplot -one -nopush -jpg allvec.jpg allvec.1D 1ddot -terse allvec.1D > allvec_COR.1D [[ If you use the bash shell, you'll have to figure out the syntax ]] [[ yourself. Zhark has no sympathy for you bash shell infidels, and ]] [[ considers you only slightly better than those lowly Emacs users. ]] [[ And do NOT ever even mention 'nedit' in Zhark's august presence! ]] ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dMaskToASCII
Usage: 3dMaskToASCII [-tobin] dataset > outputfile This program reads as input a byte-valued 0/1 dataset, such as produced by 3dAutomask, and turns it into an ASCII string. This string can be used to specify a mask in a few places in AFNI, and will be allowed in more as time goes on. the only OPTION: ---------------- -tobin = read 'dataset' as an ASCII string mask, expand it, and write the byte-valued mask to stdout. This file corresponds to the .BRIK file of an AFNI dataset. The information needed to create a .HEAD file isn't stored in the ASCII string. * Jul 2010: -STATmask options in 3dREMLfit and 3dDeconvolve accept a dataset mask or an ASCII string mask. SAMPLE OUTPUT: -------------- eNrlmU+u0zAQh21cySxQzZIFwld4S9gQjsJBEM7RepQeIcssrATp5WfHHnucRIBoSjefXtr8 ef5mxvZEiAf+vAe/LujnhXdwAEe30OPvKVK+cp41oUrZr3z9/W2laNPhsbqMIhLPNbn8OQfw Bvb4vfgi/u/PT4xL9CzheeEIenD1K4lHDU+BhqFebrOcl1Aut51xe0cYj1/Ad8t57orzs/v3 hDEOJ9CD4f+LcQGKz0/q28CzI/nMeJ6iZ0nyVaXjntDAF0e93C5SgRLE4zjC+QKaGsN1B+Z5 Qvz1oKAM8TCgToXxEYEv59beB+8dV7+zvBalb5nmaZKvinjUy2WXca1Qp5xw3oTrJQzfmxq5 61fiwqRxsBkPHv7HWAdJHLw9mXcN7xbeQd/l8yTyrjIfU99ZnQ756sGKR0WomeP0e0to9nAr DgYmDpJ5Q2XrmZGsf+L8ENYPHx7b/80Q7+Bks3VTX663uDyXqe/Ee8YZdXvlTKlAA9qdNCn3 +m/Ega76n4n/UAeKeaE7iX9DvNts/Ry831cqpr7TfCXeOf8Ze/jr4bU/4N8y9cEejANN/Gf7 kTgPeuK/2D88jX9ZW5dT/56v27Kd/4V/y/jvNrjl3+I57RH/Sd4z/t05/Q9mb92v1nsu//1K WasDE+t/3sr/Xf636oFfydWBbL9Q8Z/3NYL/UP9vZ/Ef1n1hvdft9Z9xLONAtub/hn8J6iQO WvW+O7gOsDv3BXrX/B/Wx97l+6fgv3/0+g//Q3do3X9n4mEk5P1nngtfyXFF2PRcOV+n+wZP 9p+N/SDtV+k0H4o+Yhi3gfgX9sH3fzaP26G97z+w/+PmA0X291l+VjxKhtw+T9fof9P/2id0 9byn3sO4nqUfEONgZ99vu/+jyDpBk/5es++TxIeszRt+5QXHr63r+LKv2PRe+ndv6t7dufJ9 8/Pxj/T7G/1fTeLBMP1eSuqdsMs4Ri7exvK+XB94n/c73d9fn+w9wDdwAot4yPsfZTwoEg/V +bQSH4qpH+T9T/4eYIDvLd4Jb9x7Qm5dJz6do6/31z7fwR+0TpB4IOMX9knzXF1X9mW80Dqi auvOtR/lmn55z13e/wz9EKH/3RD/AmrpJfk====65536 [The input binary mask is compressed (like 'gzip -9'), then the result] [is encoded in Base64, and the number of voxels is appended at the end.] ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dmask_tool
------------------------------------------------------------------------- 3dmask_tool - for combining/dilating/eroding/filling masks This program can be used to: 1. combine masks, with a specified overlap fraction 2. dilate and/or erode a mask or combination of masks 3. fill holes in masks The outline of operations is as follows. - read all input volumes - optionally dilate/erode inputs (with any needed zero-padding) - restrict voxels to the fraction of overlap - optionally dilate/erode combination (with zero-padding) - optionally fill any holes - write result Note : all volumes across inputs are combined into a single output volume Note : a hole is defined as a fully connected set of zero voxels that does not contain an edge voxel. For any voxel in such a set, it is not possible to find a path of voxels to reach an edge. Such paths are evaluated using 6 face neighbors, no diagonals. ---------------------------------------- examples: a. dilate a mask by 5 levels 3dmask_tool -input mask_anat.FT+tlrc -prefix ma.dilate \ -dilate_input 5 b. dilate and then erode, which connects areas that are close 3dmask_tool -input mask_anat.FT+tlrc -prefix ma.close.edges \ -dilate_input 5 -5 b2. dilate and erode after combining many masks 3dmask_tool -input mask_anat.*+tlrc.HEAD -prefix ma.close.result \ -dilate_result 5 -5 c1. compute an intersection mask, this time with EPI masks 3dmask_tool -input mask_epi_anat.*+tlrc.HEAD -prefix mask_inter \ -frac 1.0 c2. compute a mask of 70% overlap 3dmask_tool -input mask_epi_anat.*+tlrc.HEAD \ -prefix group_mask_olap.7 -frac 0.7 c3. simply count the voxels that overlap 3dmask_tool -input mask_epi_anat.*+tlrc.HEAD \ -prefix mask.counts -count d. fill holes 3dmask_tool -input mask_anat.FT+tlrc -prefix ma.filled \ -fill_holes e. fill holes per slice 3dmask_tool -input mask_anat.FT+tlrc -prefix ma.filled.xy \ -fill_holes -fill_dirs xy f. read many masks, dilate and erode, restrict to 70%, and fill holes 3dmask_tool -input mask_anat.*+tlrc.HEAD -prefix ma.fill.7 \ -dilate_input 5 -5 -frac 0.7 -fill_holes ---------------------------------------- informational command arguments (execute option and quit): -help : show this help -hist : show program history -ver : show program version ---------------------------------------- optional command arguments: -count : count the voxels that overlap Instead of created a binary 0/1 mask dataset, create one with. counts of voxel overlap, i.e each voxel will contain the number of masks that it is set in. -datum TYPE : specify data type for output e.g: -datum short default: -datum byte Valid TYPEs are 'byte', 'short' and 'float'. -dilate_inputs D1 D2 ... : dilate inputs at the given levels e.g. -dilate_inputs 3 e.g. -dilate_inputs -4 e.g. -dilate_inputs 8 -8 default: no dilation Use this option to dilate and/or erode datasets as they are read. Dilations are across the 18 voxel neighbors that share either a face or an edge (i.e. of the 26 neighbors in a 3x3x3 box, it is all but the outer 8 corners). An erosion is specified by a negative dilation. One can apply a list of dilations and erosions, though there should be no reason to apply more than one of each. Note: use -dilate_result for dilations on the combined masks. -dilate_result D1 D2 ... : dilate combined mask at the given levels e.g. -dilate_result 3 e.g. -dilate_result -4 e.g. -dilate_result 8 -8 default: no dilation Use this option to dilate and/or erode the result of combining masks that exceed the -frac cutoff. See -dilate_inputs for details of the operation. -frac LIMIT : specify required overlap threshold e.g. -frac 0 (same as -union) e.g. -frac 1.0 (same as -inter) e.g. -frac 0.6 e.g. -frac 17 default: union (-frac 0) When combining masks (across datasets and sub-bricks), use this option to restrict the result to a certain fraction of the set of volumes (or to a certain number of volumes if LIMIT > 1). For example, assume there are 7 volumes across 3 datasets. Then at each voxel, count the number of masks it is in over the 7 volumes of input. LIMIT = 0 : union, counts > 0 survive LIMIT = 1.0 : intersection, counts = 7 survive LIMIT = 0.6 : 60% fraction, counts >= 5 survive LIMIT = 5 : count limit, counts >= 5 survive See also -inter and -union. -inter : intersection, this means -frac 1.0 -union : union, this means -frac 0 -fill_holes : fill holes within the combined mask This option can be used to fill holes in the resulting mask, i.e. after all other processing has been done. A hole is defined as a connected set of voxels that is surrounded by non-zero voxels, and which contains no volume edge voxel, i.e. there is no connected voxels at a volume edge (edge of a volume meaning any part of any of the 6 volume faces). To put it one more way, a zero voxel is part of a hole if there is no path of zero voxels (in 3D space) to a volume face/edge. Such a path can be curved. Here, connections are via the 6 faces only, meaning a voxel could be consider to be part of a hole even if there were a diagonal path to an edge. Please pester me if that is not desirable. -fill_dirs DIRS : fill holes only in the given directions e.g. -fill_dirs xy e.g. -fill_dirs RA e.g. -fill_dirs XZ This option is for use with -fill holes. By default, a hole is a connected set of zero voxels that does not have a path to a volume edge. By specifying fill DIRS, the filling is done restricted to only those axis directions. For example, to fill holes once slice at a time (in a sagittal dataset say, with orientation ASL), one could use any one of the options: -fill_dirs xy -fill_dirs YX -fill_dirs AS -fill_dirs ip -fill_dirs APSI DIRS should be a single string that specifies 1-3 of the axes using {x,y,z} labels (i.e. dataset axis order), or using the labels in {R,L,A,P,I,S}. Such labels are case-insensitive. -input DSET1 ... : specify the set of inputs (taken as masks) : (-inputs is historically allowed) e.g. -input group_mask.nii e.g. -input mask_epi_anat.*+tlrc.HEAD e.g. -input amygdala_subj*+tlrc.HEAD e.g. -input ~/abin/MNI152_2009_template_SSW.nii.gz'[0]' Use this option to specify the input datasets to process. Any non-zero voxel will be consider part of that volume's mask. An input dataset is allowed to have multiple sub-bricks. All volumes across all input datasets are combined to create a single volume of output. -NN1 : specify NN connection level: 1, 2 or 3 -NN2 : specify NN connection level: 1, 2 or 3 -NN3 : specify NN connection level: 1, 2 or 3 e.g. -NN1 default: -NN2 Use this option to specify the nearest neighbor level, one of 1, 2 or 3. This defines which voxels are neighbors when dilating or eroding. The default is NN2. NN1 : face neighbors (6 first neighbors) NN2 : face or edge neighbors (+12 second neighbors) NN3 : face, edge or diagonal (+8 third neighbors (27-1)) -prefix PREFIX : specify a prefix for the output dataset e.g. -prefix intersect_mask default: -prefix combined_mask The resulting mask dataset will be named using the given prefix. -quiet : limit text output to errors Restrict text output. This option is equivalent to '-verb 0'. See also -verb. -verb LEVEL : specify verbosity level The default level is 1, while 0 is considered 'quiet'. The maximum level is currently 3, but most people don't care. ------------------------------- R. Reynolds April, 2012 ----------------------------------------------------------------------

AFNI program: 3dmatcalc
Usage: 3dmatcalc [options] Apply a matrix to a dataset, voxel-by-voxel, to produce a new dataset. * If the input dataset has 'N' sub-bricks, and the input matrix is 'MxN', then the output dataset will have 'M' sub-bricks; the results in each voxel will be the result of extracting the N values from the input at that voxel, multiplying the resulting N-vector by the matrix, and output the resulting M-vector. * If the input matrix has 'N+1' columns, then it will be applied to an (N+1)-vector whose first N elements are from the dataset and the last value is 1. This convention allows the addition of a constant vector (the last row of the matrix) to each voxel. * The output dataset is always stored in float format. * Useful applications are left to your imagination. The example below is pretty fracking hopeless. Something more useful might be to project a 3D+time dataset onto some subspace, then run 3dpc on the results. OPTIONS: ------- -input ddd = read in dataset 'ddd' [required option] -matrix eee = specify matrix, which can be done as a .1D file or as an expression in the syntax of 1dmatcalc [required option] -prefix ppp = write to dataset with prefix 'ppp' -mask mmm = only apply to voxels in the mask; other voxels will be set to all zeroes EXAMPLE: ------- Assume dataset 'v+orig' has 50 sub-bricks: 3dmatcalc -input v+orig -matrix '&read(1D:50@1,\,50@0.02) &transp' -prefix w The -matrix option computes a 2x50 matrix, whose first row is all 1's and whose second row is all 0.02's. Thus, the output dataset w+orig has 2 sub-bricks, the first of which is the voxel-wise sum of all 50 inputs, and the second is the voxel-wise average (since 0.02=1/50). -- Zhark, Emperor -- April 2006 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dMatch
++ Loading data. 3dMatch, written by PA Taylor (Nov., 2012), part of FATCAT (Taylor & Saad, 2013) in AFNI. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Find similar subbricks and rearrange order to ease comparison Comparison simply done by comparing (weighted) correlation maps of values, which may include thresholding of either refset or inset values. The weighting is done by squaring each voxel value (whilst maintaining its original sign). The Dice coefficient is also calculated to quantify overlap of regions. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMANDS: 3dMatch -inset FILE1 -refset FILE2 {-mask FILE3} {-in_min THR1} \ {-in_max THR2} {-ref_min THR3} {-ref_max THR4} -prefix FILE4 \ {-only_dice_thr} where: -inset FILE1 :file with M subbricks of data to match against another file. -refset FILE2 :file with N subbricks, serving as a reference for FILE1. N=M is *not* a requirement; matching is done based on squares of values (with signs preserved), and both best fit of in->ref and ref->in are calculated and output. -mask FILE3 :a mask of regions to include in the correlation of data sets; technically not necessary as relative correlation values shouldn't change, but the magnitudes would scale up without it. Dice coeff values should not be affected by absence or presence of wholebrain mask. -in_min THR1 :during the correlation/matching analysis, values below THR1 in the `-inset' will be zeroed (and during Dice coefficient calculation, excluded from comparison). (See `-only_dice_thr' option, below.) -in_max THR2 :during the correlation/matching analysis, values above THR2 in the `-inset' will be zeroed (and during Dice coefficient calculation, excluded from comparison). -ref_min THR3 :during the correlation/matching analysis, values below THR3 in the `-refset' will be zeroed (and during Dice coefficient calculation, excluded from comparison). (See `-only_dice_thr' option, below.) -ref_max THR4 :during the correlation/matching analysis, values above THR4 in the `-refset' will be zeroed (and during Dice coefficient calculation, excluded from comparison). -prefix FILE4 :prefix out output name for both *BRIK/HEAD files, as well as for the *_coeff.vals text files (see below). -only_dice_thr :if option is included in command line, the thresholding above is only applied during Dice evaluation, not during spatial correlation. + OUTPUTS, named using prefix; *_REF+orig :AFNI BRIK/HEAD file with the same number of subbricks as the `-refset' file, each one corresponding to a subbrick of the `-inset' file with highest weighted correlation. Any unmatched `-inset' subbricks are NOT appended at the end. (For example, you could underlay the -ref_set FILE2 and visually inspect the comparisons per slice.) *_REF_coeff.vals :simple text file with four columns, recording the original brick number slices which have been reordered in the output *_REF+orig file. Cols. 1&2- orig `-refset' and `-inset' indices, respectively; Col. 3- weighted correlation coefficient; Col 4.- simple Dice coefficient. *_IN+orig :AFNI BRIK/HEAD file with the same number of subbricks as the `-inset' file, each one corresponding to a subbrick of the `-refset' file with highest weighted correlation. Any unmatched `-refset' subbricks are NOT appended at the end. (For example, you could underlay the -inset FILE1 and visually inspect the comparisons per slice.) *_IN_coeff.vals :simple text file with four columns, recording the original brick number slices which have been reordered in the output *_IN+orig file. Cols. 1&2- orig `-inset' and `-refset' indices, respectively; Col. 3- weighted correlation coefficient; Col 4.- simple Dice coefficient. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dMatch \ -inset CORREL_DATA+orig \ -refset STANDARD_RSNs+orig \ -mask mask+orig \ -in_min 0.4 \ -ref_min 2.3 \ -prefix MATCHED \ -only_dice_thr * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________

AFNI program: 3dmatmult
------------------------------------------------------------------------- Multiply AFNI datasets slice-by-slice as matrices. If dataset A has Ra rows and Ca columns (per slice), and dataset B has Rb rows and Cb columns (per slice), multiply each slice pair as matrices to obtain a dataset with Ra rows and Cb columns. Here Ca must equal Rb and the number of slices must be equal. In practice the first dataset will probably be a transformation matrix (or a sequence of them) while the second dataset might just be an image. For this reason, the output dataset will be based on inputB. ---------------------------------------- examples: 3dmatmult -inputA matrix+orig -inputB image+orig -prefix transformed 3dmatmult -inputA matrix+orig -inputB image+orig \ -prefix transformed -datum float -verb 2 ---------------------------------------- informational command arguments (execute option and quit): -help : show this help -hist : show program history -ver : show program version ---------------------------------------- required command arguments: -inputA DSET_A : specify first (matrix) dataset The slices of this dataset might be transformation matrices. -inputB DSET_B : specify second (matrix) dataset This dataset might be any image. -prefix PREFIX : specify output dataset prefix This will be the name of the product (output) dataset. ---------------------------------------- optional command arguments: -datum TYPE : specify output data type Valid TYPEs are 'byte', 'short' and 'float'. The default is that of the inputB dataset. -verb LEVEL : specify verbosity level The default level is 1, while 0 is considered 'quiet'. ---------------------------------------- * If you need to re-orient a 3D dataset so that the rows, columns and slices are correct for 3dmatmult, you can use the one of the programs 3daxialize or 3dresample for this purpose. * To multiply a constant matrix into a vector at each voxel, the program 3dmatcalc is the proper tool. ---------------------------------------------------------------------- R. Reynolds (requested by W. Gaggl) 3dmatmult version 0.0, 29 September 2008 compiled: May 6 2025

AFNI program: 3dmaxdisp
++ 3dmaxdisp: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: Zhark the Displacer Program 3dmaxdisp! * Reads in a 3D dataset and a DICOM-based affine matrix * Outputs the average and maximum displacement that the matrix produces when applied to the edge voxels of the 3D dataset's automask. * The motivation for this program was to check if two affine transformation matrices are 'close' -- but of course, you can use this program for anything else you like. * Suppose you have two affine transformation matrices that transform a dataset XX.nii to MNI space, stored in files AA.aff12.1D and BB.aff12.1D and they aren't identical but they are close. How close? * If these matrices are from 3dAllineate (-1Dmatrix_save), then each matrix transforms DICOM-order coordinates in XX.nii to MNI-space. * So Inverse(AA) transforms MNI-space to XX-space * So Inverse(AA)*BB transforms MNI-space to MNI-space, going back to XX-space via matrix Inverse(AA) and then forward to MNI-space via BB. * This program (3dmaxdisp) can compute the average and maximum displacement of Inverse(AA)*BB over the edges of the MNI template, which will give you the answer to 'How close?' are the matrices. If these displacements are on the order of a voxel size (e.g., 1 mm), then the two matrices are for practical purposes 'close enough' (in Zhark's opinion). * How to do this? cat_matvec AA.aff12.1D -I BB.aff12.1D > AinvB.aff12.1D 3dmaxdisp -dset ~/abin/MNI152_2009_template_SSW.nii.gz'[0]' -matrix AinvB.aff12.1D * Results are sent to stdout, two numbers per row (average and maximum), one row of output for each matrix row given. Usually you will want to capture stdout to a file with '>' or '| tee', depending on your further plans. ------- OPTIONS: ------- -inset ddd }= The input dataset is 'ddd', which is used only to form *OR* }= the mask over which the displacements will be computed. -dset ddd }= -matrix mmm = File 'mmm' has 12 numbers per row, which are assembled into the 3x4 affine transformation matrix to be applied to the coordinates of the voxels in the dataset mask. * As a special case, you can use the word 'IDENTITY' for the matrix filename, which should result in a max displacement of 0 mm. * If there is more than 1 row in 'mmm', then each row is treated as a separate matrix, and the max displacement will be computed separately for each matrix. -verb = Print a few progress reports (to stderr). ------ Author: Zhark the Displacer (AKA Bob the Inverted) -- June 2021 ------

AFNI program: 3dmaxima
3dmaxima - used to locate extrema in a functional dataset. This program reads a functional dataset and locates any relative extrema (maximums or minimums, depending on the user option). A _relative_ maximum is a point that is greater than all neighbors (not necessarily greater than all other values in the sub-brick). The output from this process can be text based (sent to the terminal window) and it can be a mask (integral) dataset, where the locations of the extrema are set. When writing a dataset, it is often useful to set a sphere around each extrema, not to just set individual voxels. This makes viewing those locations much more reasonable. Also, if the 'Sphere Values' option is set to 'N to 1', the sphere around the most extreme voxel will get the value N, giving it the 'top' color in afni (and so on, down to 1). Notes : The only required option is the input dataset. Input datasets must be of type short. All distances are in voxel units. ---------------------------------------------------------------------- *** Options *** ----- Input Dset: ----- -input DSET : specify input dataset e.g. -input func+orig'[7]' Only one sub-brick may be specified. So if a dataset has multiple sub-bricks, the [] selector must be used. ----- Output Dset: ----- -prefix PREFIX : prefix for an output mask dataset e.g. -prefix maskNto1 This dataset may be viewed as a mask. It will have a value set at the location of any selected extrema. The -out_rad option can be used to change those points to 'spheres'. -spheres_1 : [flag] set all output values to 1 This is the default, which sets all values in the output dataset to 1. This is for the extreme points, and for the spheres centered around them. -spheres_1toN : [flag] output values will range from 1 to N In this case, the most extreme voxel will be set with a value of 1. The next most extreme voxel will get 2, and so on. -spheres_Nto1 : [flag] output values will range from N to 1 With this option, the highest extrema will be set to a value of N, where N equals the number of reported extrema. The advantage of this is that the most extreme point will get the highest color in afni. ----- Threshold: ----- -thresh CUTOFF : provides a cutoff value for extrema e.g. -thresh 17.4 Extrema not meeting this cutoff will not be considered. Note that if the '-neg_ext' option is applied, the user will generally want a negative threshold. ----- Separation: ----- -min_dist VOXELS : minimum acceptable distance between extrema e.g. -min_dist 4 Less significant extrema which are close to more significant extrema will be discounted in some way, depending on the 'neighbor style' options. See '-n_style_sort' and '-n_style_weight_ave' for more information. Note that the distance is in voxels, not mm. ----- Output Size: ----- -out_rad SIZE : set the output radius around extrema voxels e.g. -out_rad 9 If the user wants the output BRIK to consist of 'spheres' centered at extrema points, this option can be used to set the radius for those spheres. Note again that this is in voxel units. ----- Neighbor: ----- If extrema are not as far apart as is specified by the '-min_dist' option, the neighbor style options specify how to handle the points. -n_style_sort : [flag] use 'Sort-n-Remove' style (default) The extrema are sorted by magnitude. For each extrema (which has not previously removed), all less significant extrema neighbors within the separation radius (-min_dist) are removed. See '-min_dist' for more information. -n_style_weight_ave : [flag] use 'Weighted-Average' style Again, traverse the sorted list of extrema. Replace the current extrema with the center of mass of all extrema within the Separation radius of the current point, removing all others within this radius. This should not change the number of extrema, it should only shift the locations. ----- Params: ----- -neg_ext : [flag] search for negative extrema (minima) This will search for the minima of the dataset. Note that a negative threshold may be desired. -true_max : [flag] extrema may not have equal neighbors By default, points may be considered extrema even if they have a neighbor with the same value. This flag option requires extrema to be strictly greater than any of their neighbors. With this option, extrema locations that have neighbors at the same value are ignored. ----- Output Text: ----- -debug LEVEL : output extra information to the terminal e.g. -debug 2 -no_text : [flag] do not display the extrma points as text -coords_only : [flag] only output coordinates (no text or vals) ----- Output Coords: ----- -dset_coords : [flag] display output in the dataset orientation By default, the xyz-coordinates are displayed in DICOM orientation (RAI), i.e. right, anterior and inferior coordinates are negative, and they are printed in that order (RL, then AP, then IS). If this flag is set, the dataset orientation is used, whichever of the 48 it happens to be. Note that in either case, the output orientation is printed above the results in the terminal window, to remind the user. ----- Other : ----- -help : display this help -hist : display module history -ver : display version number Author: R Reynolds

AFNI program: 3dMean
Usage: 3dMean [options] dset dset ... Takes the voxel-by-voxel mean of all input datasets; the main reason is to be faster than 3dcalc. Options [see 3dcalc -help for more details on these]: -verbose = Print out some information along the way. -prefix ppp = Sets the prefix of the output dataset. -datum ddd = Sets the datum of the output dataset. -fscale = Force scaling of the output to the maximum integer range. -gscale = Same as '-fscale', but also forces each output sub-brick to to get the same scaling factor. -nscale = Don't do any scaling on output to byte or short datasets. ** Only use this option if you are sure you want the output dataset to be integer-valued! -non_zero = Use only non-zero values for calculation of mean,min,max,sum,squares -sd *OR* = Calculate the standard deviation, sqrt(variance), instead -stdev of the mean (cannot be used with -sqr, -sum or -non_zero). -sqr = Average the squares, instead of the values. -sum = Just take the sum (don't divide by number of datasets). -count = compute only the count of non-zero voxels. -max = find the maximum at each voxel -min = find the minimum at each voxel -absmax = find maximum absolute value at each voxel -signed_absmax = find extremes with maximum absolute value but preserve sign -mask_inter = Create a simple intersection mask. -mask_union = Create a simple union mask. The masks will be set by any non-zero voxels in the input datasets. -weightset WSET = Sum of N dsets will be weighted by N volume WSET. e.g. -weightset opt_comb_weights+tlrc This weight dataset must be of type float. N.B.: All input datasets must have the same number of voxels along each axis (x,y,z,t). * At least 2 input datasets are required. * Dataset sub-brick selectors [] are allowed. * The output dataset origin, time steps, etc., are taken from the first input dataset. * Both absmax and signed_absmax are not really appropriate for byte data because that format does not allow for negative values *** If you are trying to compute the mean (or some other statistic) across time for a 3D+time dataset (not across datasets), use 3dTstat instead. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dMedianFilter
Usage: 3dMedianFilter [options] dataset Computes the median in a spherical nbhd around each point in the input to produce the output. Options: -irad x = Radius in voxels of spherical regions -iter n = Iterate 'n' times [default=1] -verb = Be verbose during run -prefix pp = Use 'pp' for prefix of output dataset -automask = Create a mask (a la 3dAutomask) Output dataset is always stored in float format. If the input dataset has more than 1 sub-brick, only sub-brick #0 is processed. -- Feb 2005 - RWCox ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dMEMA
Usage: ------ 3dMEMA is a program for performing Mixed Effects Meta Analysis at group level that models both within- and across- subjects variability, thereby requiring both regression coefficients, or general linear contrasts among them, and the corresponding t-statistics from each subject as input. To get accurate t-statistics, 3dREMLfit should be used for the linear regression (a GLS regression program using an ARMA(1,1) model for the noise), rather than 3dDeconvolve. It's required to install R (https://www.r-project.org/), plus 'snow' package if parallel computing is desirable. Version 1.0.1, Dec 21, 2016. If you want to cite the analysis approach, use the following at this moment: Chen, G., Saad, Z.S., Nath, A.R., Beauchamp, M.S., Cox, R.W., 2012. FMRI group analysis combining effect estimates and their variances. NeuroImage 60, 747–765. https://doi.org/10.1016/j.neuroimage.2011.12.060 The basic usage of 3dMEMA is to derive group effects of a condition, contrast, or linear combination (GLT) of multiple conditions. It can be used to analyze data from one, two, or multiple groups. However, if there are more than two groups or more than one subject-grouping variables (e.g., sex, adolescent/adults, genotypes, etc.) involved in the analysis, dummy coding (zeros and ones) the variables as covariates is required, and extremely caution should be exercised in doing so because different coding strategy may lead to different interpretation. In addition, covariates (quantiative variables) can be incorporated in the model, but centering and potential interactions with other effects in the model should be considered. Basically, 3dMEMA can run one-sample, two-sample, and all types of BETWEEN-SUBJECTS ANOVA and ANCOVA. Within-subject variables mostly cannot be modeled, but there are a few exceptions. For instance, paired-test can be performed through feeding the contrast of the two conditions as input. Multi-way ANOVA can be analyzed under the following two scenarios: 1) all factors have only two levels (e.g., 2 X 2 repeated- measures ANOVA) can be analyzed; or 1) there is only one within-subject (or repeated-measures) factor and it contains two levels only. See more details at https://afni.nimh.nih.gov/sscc/gangc/MEMA.html Notice: When comparing two groups, option "-groups groupA groupB" has to be present, and the output includes the difference of groupB - groupA, which is consistent with most AFNI convention except for 3dttest++ where groupA - groupB is rendered. Example 1 --- One-sample type (one regression coefficient or general linear contrast from each subject in a group): -------------------------------- 3dMEMA -prefix ex1 \ -jobs 4 \ -set happy \ ac ac+tlrc'[14]' ac+tlrc'[15]' \ ejk ejk+tlrc'[14]' ejk+tlrc'[15]' \ ... ss ss+tlrc'[14]' ss+tlrc'[15]' \ -max_zeros 4 \ -model_outliers \ -residual_Z 3dMEMA -prefix ex1 \ -jobs 4 \ -set happy \ ac ac+tlrc'[happy#0_Coef]' ac+tlrc'[happy#0_Tstat]' \ ejk ejk+tlrc'[happy#0_Coef]' ejk+tlrc'[happy#0_Tstat]' \ ... ss ss+tlrc'[happy#0_Coef]' ss+tlrc'[happy#0_Tstat]' \ -missing_data 0 \ -HKtest \ -model_outliers \ -residual_Z Example 2 --- Two-sample type (one regression coefficient or general linear contrast from each subject in two groups with the contrast being the 2nd group subtracing the 1st one), heteroskedasticity (different cross-subjects variability between the two groups), outlier modeling, covariates centering, no payment no interest till Memorial Day next year. Notice that option -groups has to be present in this case, and the output includes the difference of the second group versus the first one. ------------------------------------------------------------------------- 3dMEMA -prefix ex3 \ -jobs 4 \ -groups horses goats \ -set healthy_horses \ ac ac_sad_B+tlrc.BRIK ac_sad_T+tlrc.BRIK \ ejk ejk_sad_B+tlrc.BRIK ejk_sad_T+tlrc.BRIK \ ... ss ss_sad_B+tlrc.BRIK ss_sad_T+tlrc.BRIK \ -set healthy_goats \ jp jp_sad_B+tlrc.BRIK jp_sad_T+tlrc.BRIK \ mb mb_sad_B+tlrc.BRIK mb_sad_T+tlrc.BRIK \ ... trr trr_sad_B+tlrc.BRIK trr_sad_T+tlrc.BRIK \ -n_nonzero 18 \ -HKtest \ -model_outliers \ -unequal_variance \ -residual_Z \ -covariates CovFile.txt \ -covariates_center age = 25 13 weight = 100 150 \ -covariates_model center=different slope=same where file CovFile.txt looks something like this: name age weight ejk 93 117 jcp 3 34 ss 12 200 ac 12 130 jp 65 130 mb 25 630 trr 18 187 delb 9 67 tony 12 4000 Example 3 --- Paired type (difference of two regression coefficients or general linear contrasts from each subject in a group). One scenario of general linear combinations is to test linear or higher order trend at individual level, and then take the trend information to group level. --------------------------------- 3dMEMA -prefix ex2 \ -jobs 4 \ -missing_data happyMiss+tlrc sadMiss+tlrc \ -set happy-sad \ ac ac_hap-sad_B+tlrc ac_hap-sad_T+tlrc \ ejk ejk_hap-sad_B+tlrc ejk_hap-sad_T+tlrc \ ... ss ss_hap-sad_B+tlrc ss_hap-sad_T+tlrc \ Options in alphabetical order: ------------------------------ -cio: Use AFNI's C io functions -conditions COND1 [COND2]: Name of 1 or 2 conditions, tasks, or GLTs. Default is one condition named 'c1' -contrast_name: (no help available) -covariates COVAR_FILE: Specify the name of a text file containing a table for the covariate(s). Each column in the file is treated as a separate covariate, and each row contains the values of these covariates for each subject. Option -unequal_variance may not be used in the presence of covariates with two groups. To avoid confusion, it is best you format COVAR_FILE in this manner with BOTH row and column names: subj age weight Jane 25 300 Joe 22 313 ... .. ... This way, there is no ambiguity as to which values are attributed to which subject, nor to the label of the covariate(s). The word 'subj' must be the first word of the first row. You can still get at the values of the columns of such a file with AFNI's 1dcat -ok_text, which will treat the first row, and first column, as all 0s. Alternate, but less recommended ways to specify the covariates: (column names only) age weight 25 300 22 313 .. ... or (no row and column names) 25 300 22 313 .. ... -covariates_center COV_1=CEN_1 [COV_2=CEN_2 ... ]: (for 1 group) -covariates_center COV_1=CEN_1.A CEN_1.B [COV_2=CEN_2.A CEN_2.B ... ]: (for 2 groups) where COV_K is the name assigned to the K-th covariate, either from the header of the covariates file, or from the option -covariates_name. This makes clear which center belongs to which covariate. When two groups are used, you need to specify a center for each of the groups (CEN_K.A, CEN_K.B). Example: If you had covariates age, and weight, you would use: -covariates_center age = 78 55 weight = 165 198 If you want all covariates centered about their own mean, just use -covariates_center mean. Be alert: Default is mean centering! If no centering is desired (e.g.,the covariate values have been pre-centered), set the center value as 0 with -covariates_center. -covariates_model center=different/same slope=different/same: Specify whether to use the same or different intercepts for each of the covariates. Similarly for the slope. -covariates_name COV_1 [... COV_N]: Specify the name of each of the N covariates. This is only needed if the covariates' file has no header. The default is to name the covariates cov1, cov2, ... -dbgArgs: This option will enable R to save the parameters in a file called .3dMEMA.dbg.AFNI.args in the current directory so that debugging can be performed. -equal_variance: Assume same cross-subjects variability between GROUP1 and GROUP2 (homoskedasticity). (Default) -groups GROUP1 [GROUP2]: Name of 1 or 2 groups. This option must be used when comparing two groups. Default is one group named 'G1'. The labels here are used to name the sub-bricks in the output. When there are two groups, the 1st and 2nd labels here are associated with the 1st and 2nd datasets specified respectively through option -set, and their group difference is the second group minus the first one, similar to 3dttest but different from 3dttest++. -help: this help message -HKtest: Perform Hartung-Knapp adjustment for the output t-statistic. This approach is more robust when the number of subjects is small, and is generally preferred. -KHtest is the default with t-statistic output. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -mask MASK: Process voxels inside this mask only. Default is no masking. -max_zeros MM: Do not compute statistics at any voxel that has more than MM zero beta coefficients or GLTs. Voxels around the edges of the group brain will not have data from some of the subjects. Therefore, some of their beta's or GLTs and t-stats are masked with 0. 3dMEMA can handle missing data at those voxels but obviously too much missing data is not good. Setting -max_zeros to 0.25 means process data only at voxels where no more than 1/4 of the data is missing. The default value is 0 (no missing values allowed). MM can be a positive integer less than the number of subjects, or a fraction between 0 and 1. Alternatively option -missing_data can be used to handle missing data. -missing_data: This option corrects for inflated statistics for the voxels where some subjects do not have any data available due to imperfect spatial alignment or other reasons. The absence of this option means no missing data will be assumed. Two formats of option setting exist as shown below. -missing_data 0: With this format the zero value at a voxel of each subject will be interpreted as missing data. -missing_data File1 [File2]: Information about missing data is specified with file of 1 or 2 groups (the number 1 or 2 and file order should be consistent with those in option -groups). The voxel value of each file indicates the number of sujects with missing data in that group. -model_outliers: Model outlier betas with a Laplace distribution of of subject-specific error. Default is -no_model_outliers -n_nonzero NN: Do not compute statistics at any voxel that has less than NN non-zero beta values. This options is complimentary to -max_zeroes, and matches an option in the interactive 3dMEMA mode. NN is basically (number of unique subjects - MM). Alternatively option -missing_data can be used to handle missing data. -no_HKtest: Do not make the Hartung-Knapp adjustment. -KHtest is the default with t-statistic output. -no_model_outliers: No modeling of outlier betas/GLTs (Default). -no_residual_Z: Do not output residuals and their Z values (Default). -prefix PREFIX: Output prefix (just prefix, no view+suffix needed) -residual_Z: Output residuals and their Z values used in identifying outliers at voxel level. Default is -no_residual_Z -Rio: Use R's io functions -set SETNAME \ SUBJ_1 BETA_DSET T_DSET \ SUBJ_2 BETA_DSET T_DSET \ ... ... ... \ SUBJ_N BETA_DSET T_DSET \ Specify the data for one of two test variables (either group, contrast/GLTs) A & B. SETNAME is the name assigned to the set, which is only for the user's information, and not used by the program. When there are two groups, the 1st and 2nd datasets are associated with the 1st and 2nd labels specified through option -set, and the group difference is the second group minus the first one, similar to 3dttest but different from 3dttest++. SUBJ_K is the label for the subject K whose datasets will be listed next BETA_DSET is the name of the dataset of the beta coefficient or GLT. T_DSET is the name of the dataset containing the Tstat corresponding to BETA_DSET. To specify BETA_DSET, and T_DSET, you can use the standard AFNI notation, which, in addition to sub-brick indices, now allows for the use of sub-brick labels as selectors e.g: -set Placebo Jane pb05.Jane.Regression+tlrc'[face#0_Beta]' \ pb05.Jane.Regression+tlrc'[face#0_Tstat]' \ -show_allowed_options: list of allowed options -unequal_variance: Model cross-subjects variability difference between GROUP1 and GROUP2 (heteroskedasticity). This option may NOT be invoked when covariate is present in the model. Default is -equal_variance (homoskedasticity). This option may not be useded when covariates are involved in the model. -verb VERB: VERB is an integer specifying verbosity level. 0 for quiet (Default). 1 or more: talkative. ####################################################################### Please consider citing the following if this program is useful for you: Chen, G., Saad, Z.S., Nath, A.R., Beauchamp, M.S., Cox, R.W., 2012. FMRI group analysis combining effect estimates and their variances. NeuroImage 60, 747–765. https://doi.org/10.1016/j.neuroimage.2011.12.060 #######################################################################

AFNI program: 3dMEPFM
Usage: 3dMEPFM [options] ------ Brief summary: ============== * 3dMEPFM is the equivalent program to 3dPFM for Multiecho fMRI data. This program performs the voxelwise deconvolution of ME-fMRI data to yield time-varying estimates of the changes in the transverse relaxation (DR2*) and, optionally, the net magnetization (DS0) assuming a mono-exponential decay model of the signal, i.e. linear dependence of the BOLD signal on the echo time (TE). * It is also recommended to read the help of 3dPFM to understand its functionality. * The ideas behind 3dMEPFM are described in the following papers: - For a comprehensive description of the algorithm, based on a model that only considers fluctuations in R2* (DR2*) and thus only estimates DR2* (i.e. this model is selected with option -R2only), see: C Caballero-Gaudes, S Moia, P. Panwar, PA Bandettini, J Gonzalez-Castillo A deconvolution algorithm for multiecho functional MRI: Multiecho Sparse Paradigm Free Mapping (submitted to Neuroimage) - For a model that considers both fluctuations in the net magnetization (DS0) and R2*, but only imposes a regularization term on DR2* (setting -rho 0 and without -R2only), see C Caballero-Gaudes, PA Bandettini, J Gonzalez-Castillo A temporal deconvolution algorithm for multiecho functional MRI 2018 IEEE 15th International Symposium on Biomedical Imaging (ISBI 2018) https://ieeexplore.ieee.org/document/8363649 - For a model that considers both fluctuations in the net magnetization (DS0) and R2*, and imposes regularization terms on DR2* and DS0 (i.e. setting rho > 0, and without -R2only), see The results of this paper were obtained with rho = 0.5 C Caballero-Gaudes, S. Moia, PA Bandettini, J Gonzalez-Castillo Quantitative deconvolution of fMRI data with Multi-echo Sparse Paradigm Free Mapping Medical Image Computing and Computer Assisted Intervention (MICCAI 2018) Lecture Notes in Computer Science, vol. 11072. Springer https://doi.org/10.1007/978-3-030-00931-1_36 * IMPORTANT. This program is written in R. Please follow the guidelines in http://afni.nimh.nih.gov/sscc/gangc/Rinstall.html to install R and make AFNI compatible with R. Particularly, the "snow" library must be installed for parallelization across CPU nodes. install.packages("snow",dependencies=TRUE) In addition, you need to install the following libraries with dependencies: install.packages("abind",dependencies=TRUE) install.packages("lars",dependencies=TRUE) install.packages("wavethresh",dependencies=TRUE) Also, if you want to run the program with the options "rho > 0", you must install the R package of the generalized lasso (https://projecteuclid.org/euclid.aos/1304514656) This package was removed from CRAN repository, but the source code is available in: https://github.com/glmgen/genlasso Example usage with a dataset with 3 echoes: ----------------------------------------------------------------------------- 3dMEPFM -input data_TE1.nii 0.015 -input data_TE2.nii 0.030 -input data_TE3.nii 0.045 -mask mask.nii -criteria bic -hrf SPMG1 -jobs 1 Options: -------- -input DSET TE DSET: Dataset to analyze with Multiecho Paradigm Free Mapping. and the corresponding TE. DSET can be any of the formats available in AFNI, e.g: -input Data+orig TE: echo time of dataset in seconds Also .1D files where each column is a voxel timecourse. If an .1D file is input, you MUST specify the TR with option -TR. -dbgArgs: This option will enable R to save the parameters in a file called .3dMEPFM.dbg.AFNI.args in the current directory so that debugging can be performed. -mask MASK: Process voxels inside this mask only. Default is no masking. -penalty PEN: Regularization term (a.k.a. penalty) for DR2 & DS0 * Available options for PEN are: lasso: LASSO (i.e. L1-norm) * If you are interested in other penalties (e.g. ridge regression, fused lasso, elastic net), contact c.caballero@bcbl.eu -criteria CRIT: Model selection of the regularization parameter. * Available options are: bic: Bayesian Information Criterion (default) aic: Akaike Information Criterion mad: Regularization parameter is selected as the iteration that makes the standard deviation of the residuals to be larger than factor_MAD * sigma_MAD, where sigma_MAD is the MAD estimate of the noise standard deviation (after wavelet decomposition of the echo signals) mad2: Regularization parameter is selected so that the standard deviation of the residuals is the closest to factor_MAD*sigma_MAD. * If you want other options, contact c.caballero@bcbl.eu -maxiterfactor MaxIterFactor (between 0 and 1): * Maximum number of iterations for the computation of the regularization path will be 2*MaxIerFactor*nscans * Default value is MaxIterFactor = 1 -TR tr: Repetition time or sampling period of the input data * It is required for the generation of the deconvolution HRF model. * If input datasets are .1D file, TR must be specified in seconds. If TR is not given, the program will STOP. * If input datasets are 3D+time volumes and TR is NOT given, the value of TR is taken from the dataset header. * If TR is specified and it is different from the TR in the header of the input datasets, the program will STOP. -hrf fhrf: haemodynamic response function used for deconvolution * fhrf can be any of the HRF models available in 3dDeconvolve. http://afni.nimh.nih.gov/pub/dist/doc/program_help/3dDeconvolve.html i.e. 3dMEPFM calls 3dDeconvolve with options -x1D_stop & -nodata to create the HRF with onset at 0 (i.e. -stim_time 1 '1D:0' fhrf ) * [Default] fhrf == 'GAM', the 1 parameter gamma variate (t/(p*q))^p * exp(p-t/q) with p=8.6 q=0.547 if only 'GAM' is used ** The peak of 'GAM(p,q)' is at time p*q after the stimulus. The FWHM is about 2.3*sqrt(p)*q. * Another option is fhrf == 'SPMG1', the SPM canonical HRF. * If fhrf is a .1D, the program will use it as the HRF model. ** It should be generated with the same TR as the input data to get sensible results (i.e. know what you are doing). ** fhrf must be column or row vector, i.e. only 1 hrf allowed. * The HRF is normalized to maximum absolute amplitude equal to 1. -R2only: * If this option is given, the model will only consider R2* changes and do not estimate S0 changes. -rho: 0 <= rho <= 1 (default 0): * Parameter that balances the penalization of the DS0 (rho) and DR2star (1-rho) coefficients. * Default is rho = 0, i.e. no penalization of DS0 coefficients. * It becomes irrelevant with -R2only option. -factor_min_lambda value >= 0 (default factor_min_lambda = 0.1): * Stop the computation of the regularization path when lambda <= factor_min_lambda*sigma_MAD, where sigma_MAD is the estimate of the standard deviation of the noise (computed after wavelet decomposition). It must be equal to or larger than 0. -factor_MAD (default factor_MAD = 1): * For criteria 'mad', select lambda so that the standard deviation of residuals is approximately equal to factor_MAD*sigma_MAD -debias_TEopt: 0 <= debias_TEopt <= number of input datasets * For debiasing, only consider the 'debias_TEopt' input dataset, i.e. if debias_TEopt=2, the dataset corresponding to the second TE will be used for debiasing. This option is available in case you really know that one of the echoes is the 'optimal' TE ... As if this information was easy to know and match :) * Default is debias_TEopt = 0, i.e. all echoes will be considered. * This option is not recommended unless you understand it, (i.e. use at your own risk) -do_prior_debias: * If this option is given, the algorithm will perform debiasing before the selection of the regularization parameter. * This option is not recommended unless you understand it, (i.e. use at your own risk) -n_selection_Nscans: * The equation for model selection for selection of regularization parameter with the 'bic' and 'aic' criteria depends on the number of observations (i.e. number of scans * number of echoes) * If -n_selection_Nscans is given, the formula will assume that the number of observations is the number of scans. This is mathematically wrong, but who cares if it gives better results!! * This option is not recommended unless you understand it, (i.e. use at your own risk) -prefix * The names of the output volumes will be generated automatically as outputname_prefix_input, e.g. if -input = TheEmperor+orig, and prefix is Zhark, the names of the DR2 output volumes is DR2_Zhark_TheEmperor+orig for volume whereas if prefix is not given, the output will be DR2_TheEmperor+orig. * The program will automatically save the following volumes: -DR2 Changes in R2* parameter, which is assumed to represent neuronal-related signal changes. -DR2fit Convolution of DR2 with HRF, i.e. neuronal-related haemodynamic signal. One volume per echo is created. -DS0 Changes in net magnetization (S0) (if estimated) -lambda Regularization parameter -sigmas_MAD Estimate of the noise standard deviation after wavelet decomposition for each input dataset -costs Cost function to select the regularization parameter (lambda) according to selection criterion * If you don't want to delete or rename anyone, you can always delete them later or rename them with 3dcopy. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer (DEFAULT). -nSeg XX: Divide into nSeg segments of voxels to report progress, e.g. nSeg 5 will report every 20% of processed voxels. Default = 10 -verb VERB: VERB is an integer specifying verbosity level. 0 for quiet, 1 (default) or more: talkative. -help: this help message -show_allowed_options: list of allowed options

AFNI program: 3dmerge
Program 3dmerge This program has 2 different functions: (1) To edit 3D datasets in various ways (threshold, blur, cluster, ...); (2) To merge multiple datasets in various ways (average, max, ...). Either or both of these can be applied. The 'editing' operations are controlled by options that start with '-1', which indicates that they apply to individual datasets (e.g., '-1blur_fwhm'). The 'merging' operations are controlled by options that start with '-g', which indicate that they apply to the entire group of input datasets (e.g., '-gmax'). ---------------------------------------------------------------------- Usage: 3dmerge [options] datasets ... Examples: 1. Apply a 4.0mm FWHM Gaussian blur to EPI run 7. 3dmerge -1blur_fwhm 4.0 -doall -prefix e1.run7_blur run7+orig * These examples are based on a data grid of 3.75 x 3.75 x 3.5, in mm. So a single voxel has a volume of ~49.22 mm^3 (mvul), and a 40 voxel cluster has a volume of ~1969 mm^3 (as used in some examples). 2. F-stat only: Cluster based on a threshold of F=10 (F-stats are in sub-brick #0), and require a volume of 40 voxels (1969 mm^3). The output will be the same F-stats as in the input, but subject to the threshold and clustering. 3dmerge -1clust 3.76 1969 -1thresh 10.0 \ -prefix e2.f10 stats+orig'[0]' 3. F-stat only: Perform the same clustering (as in #2), but apply the radius and cluster size in terms of cubic millimeter voxels (as if the voxels were 1x1x1). So add '-dxyz=1', and adjust rmm and mvul. 3dmerge -dxyz=1 -1clust 1 40 -1thresh 10.0 \ -prefix e3.f10 stats+orig'[0]' 4. t-stat and beta weight: For some condition, our beta weight is in sub-brick #4, with the corresponding t-stat in sub-brick #5. Cluster based on 40 voxels and a t-stat threshold of 3.25. Output the data from the beta weights, not the t-stats. 3dmerge -dxyz=1 -1clust 1 40 -1thresh 3.25 \ -1tindex 5 -1dindex 4 \ -prefix e4.t3.25 stats+orig 5. t-stat mask: Apply the same threshold and cluster as in #4, but output a mask. Since there are 5 clusters found in this example, the values in the mask will be from 1 to 5, representing the largest cluster to the smallest. Use -1clust_order on sub-brick 5. 3dmerge -dxyz=1 -1clust_order 1 40 -1thresh 3.25 \ -prefix e5.mask5 stats+orig'[5]' Note: this should match the 3dclust output from: 3dclust -1thresh 3.25 -dxyz=1 1 40 stats+orig'[5]' ---------------------------------------------------------------------- EDITING OPTIONS APPLIED TO EACH INPUT DATASET: -1thtoin = Copy threshold data over intensity data. This is only valid for datasets with some thresholding statistic attached. All subsequent operations apply to this substituted data. -2thtoin = The same as -1thtoin, but do NOT scale the threshold values from shorts to floats when processing. This option is only provided for compatibility with the earlier versions of the AFNI package '3d*' programs. -1noneg = Zero out voxels with negative intensities -1abs = Take absolute values of intensities -1clip val = Clip intensities in range (-val,val) to zero -2clip v1 v2 = Clip intensities in range (v1,v2) to zero -1uclip val = These options are like the above, but do not apply -2uclip v1 v2 any automatic scaling factor that may be attached to the data. These are for use only in special circumstances. (The 'u' means 'unscaled'. Program '3dinfo' can be used to find the scaling factors.) N.B.: Only one of these 'clip' options can be used; you cannot combine them to have multiple clipping executed. -1thresh thr = Use the threshold data to censor the intensities (only valid for 'fith', 'fico', or 'fitt' datasets) (or if the threshold sub-brick is set via -1tindex) N.B.: The value 'thr' is floating point, in the range 0.0 < thr < 1.0 for 'fith' and 'fico' datasets, and 0.0 < thr < 32.7 for 'fitt' datasets. -2thresh t1 t2 = Zero out voxels where the threshold sub-brick value lies between 't1' and 't2' (exclusive). If t1=-t2, is the same as '-1thresh t2'. -1blur_sigma bmm = Gaussian blur with sigma = bmm (in mm) -1blur_rms bmm = Gaussian blur with rms deviation = bmm -1blur_fwhm bmm = Gaussian blur with FWHM = bmm -1blur3D_fwhm bx by bz = Gaussian blur with FWHM (potentially) different in each of the 3 spatial dimensions. Note that these dimensions are in mm, and refer to the storage order of the dataset. (See the output of '3dinfo datasetname' if you don't know the storage order of your input dataset.) A blur amount of 0 in a direction means not to apply any blurring along that axis. For example: -1blur3D_fwhm 4 4 0 will do in-plane blurring only along the x-y dataset axes. -t1blur_sigma bmm= Gaussian blur of threshold with sigma = bmm(in mm) -t1blur_rms bmm = Gaussian blur of threshold with rms deviation = bmm -t1blur_fwhm bmm = Gaussian blur of threshold with FWHM = bmm -1zvol x1 x2 y1 y2 z1 z2 = Zero out entries inside the 3D volume defined by x1 <= x <= x2, y1 <= y <= y2, z1 <= z <= z2 ; N.B.: The ranges of x,y,z in a dataset can be found using the '3dinfo' program. Dimensions are in mm. N.B.: This option may not work correctly at this time, but I've not figured out why! CLUSTERING -dxyz=1 = In the cluster editing options, the spatial clusters are defined by connectivity in true 3D distance, using the voxel dimensions recorded in the dataset header. This option forces the cluster editing to behave as if all 3 voxel dimensions were set to 1 mm. In this case, 'rmm' is then the max number of grid cells apart voxels can be to be considered directly connected, and 'vmul' is the min number of voxels to keep in the cluster. N.B.: The '=1' is part of the option string, and can't be replaced by some other value. If you MUST have some other value for voxel dimensions, use program 3drefit. The following cluster options are mutually exclusive: -1clust rmm vmul = Form clusters with connection distance rmm and clip off data not in clusters of volume at least vmul microliters -1clust_mean rmm vmul = Same as -1clust, but all voxel intensities within a cluster are replaced by the average intensity of the cluster. -1clust_max rmm vmul = Same as -1clust, but all voxel intensities within a cluster are replaced by the maximum intensity of the cluster. -1clust_amax rmm vmul = Same as -1clust, but all voxel intensities within a cluster are replaced by the maximum absolute intensity of the cluster. -1clust_smax rmm vmul = Same as -1clust, but all voxel intensities within a cluster are replaced by the maximum signed intensity of the cluster. -1clust_size rmm vmul = Same as -1clust, but all voxel intensities within a cluster are replaced by the size of the cluster (in multiples of vmul). -1clust_order rmm vmul= Same as -1clust, but all voxel intensities within a cluster are replaced by the cluster size index (largest cluster=1, next=2, ...). -1clust_depth rmm vmul= Same as -1clust, but all voxel intensities are replaced by the number of peeling operations needed to remove them from the cluster. That number is an indication of how deep a voxel is inside a cluster -isovalue = Clusters will be formed only from contiguous (in the rmm sense) voxels that also have the same value. N.B.: The normal method is to cluster all contiguous nonzero voxels together. -isomerge = Clusters will be formed from each distinct value in the dataset; spatial contiguity will not be used (but you still have to supply rmm and vmul on the command line). N.B.: 'Clusters' formed this way may well have components that are widely separated! * If rmm is given as 0, this means to use the 6 nearest neighbors to form clusters of nonzero voxels. * If vmul is given as zero, then all cluster sizes will be accepted (probably not very useful!). * If vmul is given as negative, then abs(vmul) is the minimum number of voxels to keep. The following commands produce erosion and dilation of 3D clusters. These commands assume that one of the -1clust commands has been used. The purpose is to avoid forming strange clusters with 2 (or more) main bodies connected by thin 'necks'. Erosion can cut off the neck. Dilation will minimize erosion of the main bodies. Note: Manipulation of values inside a cluster (-1clust commands) occurs AFTER the following two commands have been executed. -1erode pv For each voxel, set the intensity to zero unless pv % of the voxels within radius rmm are nonzero. -1dilate Restore voxels that were removed by the previous command if there remains a nonzero voxel within rmm. The following filter options are mutually exclusive: -1filter_mean rmm = Set each voxel to the average intensity of the voxels within a radius of rmm. -1filter_nzmean rmm = Set each voxel to the average intensity of the non-zero voxels within a radius of rmm. -1filter_max rmm = Set each voxel to the maximum intensity of the voxels within a radius of rmm. -1filter_amax rmm = Set each voxel to the maximum absolute intensity of the voxels within a radius of rmm. -1filter_smax rmm = Set each voxel to the maximum signed intensity of the voxels within a radius of rmm. -1filter_aver rmm = Same idea as '_mean', but implemented using a new code that should be faster. The following threshold filter options are mutually exclusive: -t1filter_mean rmm = Set each correlation or threshold voxel to the average of the voxels within a radius of rmm. -t1filter_nzmean rmm = Set each correlation or threshold voxel to the average of the non-zero voxels within a radius of rmm. -t1filter_max rmm = Set each correlation or threshold voxel to the maximum of the voxels within a radius of rmm. -t1filter_amax rmm = Set each correlation or threshold voxel to the maximum absolute intensity of the voxels within a radius of rmm. -t1filter_smax rmm = Set each correlation or threshold voxel to the maximum signed intensity of the voxels within a radius of rmm. -t1filter_aver rmm = Same idea as '_mean', but implemented using a new code that should be faster. -1mult factor = Multiply intensities by the given factor -1zscore = If the sub-brick is labeled as a statistic from a known distribution, it will be converted to an equivalent N(0,1) deviate (or 'z score'). If the sub-brick is not so labeled, nothing will be done. The above '-1' options are carried out in the order given above, regardless of the order in which they are entered on the command line. N.B.: The 3 '-1blur' options just provide different ways of specifying the radius used for the blurring function. The relationships among these specifications are sigma = 0.57735027 * rms = 0.42466090 * fwhm The requisite convolutions are done using FFTs; this is by far the slowest operation among the editing options. OTHER OPTIONS: -nozero = Do NOT write the output dataset if it would be all zero. -datum type = Coerce the output data to be stored as the given type, which may be byte, short, or float. N.B.: Byte data cannot be negative. If this datum type is chosen, any negative values in the edited and/or merged dataset will be set to zero. -keepthr = When using 3dmerge to edit exactly one dataset of a functional type with a threshold statistic attached, normally the resulting dataset is of the 'fim' (intensity only) type. This option tells 3dmerge to copy the threshold data (unedited in any way) into the output dataset. N.B.: This option is ignored if 3dmerge is being used to combine 2 or more datasets. N.B.: The -datum option has no effect on the storage of the threshold data. Instead use '-thdatum type'. -doall = Apply editing and merging options to ALL sub-bricks uniformly in a dataset. N.B.: All input datasets must have the same number of sub-bricks when using the -doall option. N.B.: The threshold specific options (such as -1thresh, -keepthr, -tgfisher, etc.) are not compatible with the -doall command. Neither are the -1dindex or the -1tindex options. N.B.: All labels and statistical parameters for individual sub-bricks are copied from the first dataset. It is the responsibility of the user to verify that these are appropriate. Note that sub-brick auxiliary data can be modified using program 3drefit. -quiet = Reduce the number of messages shown -1dindex j = Uses sub-brick #j as the data source , and uses sub-brick -1tindex k = #k as the threshold source. With these, you can operate on any given sub-brick of the inputs dataset(s) to produce as output a 1 brick dataset. If desired, a collection of 1 brick datasets can later be assembled into a multi-brick bucket dataset using program '3dbucket' or into a 3D+time dataset using program '3dTcat'. N.B.: If these options aren't used, j=0 and k=1 are the defaults The following option allows you to specify a mask dataset that limits the action of the 'filter' options to voxels that are nonzero in the mask: -1fmask mset = Read dataset 'mset' (which can include a sub-brick specifier) and use the nonzero voxels as a mask for the filter options. Filtering calculations will not use voxels that are outside the mask. If an output voxel does not have ANY masked voxels inside the rmm radius, then that output voxel will be set to 0. N.B.: * Only the -1filter_* and -t1filter_* options are affected by -1fmask. * Voxels NOT in the fmask will be set to zero in the output when the filtering occurs. THIS IS NEW BEHAVIOR, as of 11 Oct 2007. Previously, voxels not in the fmask, but within 'rmm' of a voxel in the mask, would get a nonzero output value, as those nearby voxels would be combined (via whatever '-1f...' option was given). * If you wish to restore this old behavior, where non-fmask voxels can get nonzero output, then use the new option '-1fm_noclip' in addition to '-1fmask'. The two comments below apply to the case where '-1fm_noclip' is given! * In the linear averaging filters (_mean, _nzmean, and _expr), voxels not in the mask will not be used or counted in either the numerator or denominator. This can give unexpected results if you use '-1fm_noclip'. For example, if the mask is designed to exclude the volume outside the brain, then voxels exterior to the brain, but within 'rmm', will have a few voxels inside the brain included in the filtering. Since the sum of weights (the denominator) is only over those few intra-brain voxels, the effect will be to extend the significant part of the result outward by rmm from the surface of the brain. In contrast, without the mask, the many small-valued voxels outside the brain would be included in the numerator and denominator sums, which would barely change the numerator (since the voxel values are small outside the brain), but would increase the denominator greatly (by including many more weights). The effect in this case (no -1fmask) is to make the filtering taper off gradually in the rmm-thickness shell around the brain. * Thus, if the -1fmask is intended to clip off non-brain data from the filtering, its use should be followed by masking operation using 3dcalc: 3dmerge -1filter_aver 12 -1fm_noclip -1fmask mask+orig -prefix x input+orig 3dcalc -a x -b mask+orig -prefix y -expr 'a*step(b)' rm -f x+orig.* The desired result is y+orig - filtered using only brain voxels (as defined by mask+orig), and with the output confined to the brain voxels as well. The following option allows you to specify an almost arbitrary weighting function for 3D linear filtering: -1filter_expr rmm expr Defines a linear filter about each voxel of radius 'rmm' mm. The filter weights are proportional to the expression evaluated at each voxel offset in the rmm neighborhood. You can use only these symbols in the expression: r = radius from center x = dataset x-axis offset from center y = dataset y-axis offset from center z = dataset z-axis offset from center i = x-axis index offset from center j = y-axis index offset from center k = z-axis index offset from center Example: -1filter_expr 12.0 'exp(-r*r/36.067)' This does a Gaussian filter over a radius of 12 mm. In this example, the FWHM of the filter is 10 mm. [in general, the denominator in the exponent would be 0.36067 * FWHM * FWHM. This is one way to get a Gaussian blur combined with the -1fmask option. The radius rmm=12 is chosen where the weights get smallish.] Another example: -1filter_expr 20.0 'exp(-(x*x+16*y*y+z*z)/36.067)' which is a non-spherical Gaussian filter. ** For shorthand, you can also use the new option (11 Oct 2007) -1filter_blur fwhm which is equivalent to -1filter_expr 1.3*fwhm 'exp(-r*r/(.36067*fwhm*fwhm)' and will implement a Gaussian blur. The only reason to do Gaussian blurring this way is if you also want to use -1fmask! The following option lets you apply a 'Winsor' filter to the data: -1filter_winsor rmm nw The data values within the radius rmm of each voxel are sorted. Suppose there are 'N' voxels in this group. We index the sorted voxels as s[0] <= s[1] <= ... <= s[N-1], and we call the value of the central voxel 'v' (which is also in array s[]). If v < s[nw] , then v is replaced by s[nw] otherwise If v > s[N-1-nw], then v is replace by s[N-1-nw] otherwise v is unchanged The effect is to increase 'too small' values up to some middling range, and to decrease 'too large' values. If N is odd, and nw=(N-1)/2, this would be a median filter. In practice, I recommend that nw be about N/4; for example, -dxyz=1 -1filter_winsor 2.5 19 is a filter with N=81 that gives nice results. N.B.: This option is NOT affected by -1fmask N.B.: This option is slow! and experimental. The following option returns a rank value at each voxel in the input dataset. -1rank If the input voxels were, say, 12 45 9 0 9 12 0 the output would be 2 3 1 0 1 2 0 This option is handy for turning FreeSurfer's segmentation volumes to ROI volumes that can be easily colorized with AFNI. For example: 3dmerge -1rank -prefix aparc+aseg_rank aparc+aseg.nii To view aparc+aseg_rank+orig, use the ROI_128 colormap and set the colorbar range to 128. The -1rank option also outputs a 1D file that contains the mapping from the input dataset to the ranked output. Sub-brick float factors are ignored. This option only works on datasets of integral values or of integral data types. 'float' values are typecast to 'int' before being ranked. See also program 3dRank MERGING OPTIONS APPLIED TO FORM THE OUTPUT DATASET: [That is, different ways to combine results. The] [following '-g' options are mutually exclusive! ] -gmean = Combine datasets by averaging intensities (including zeros) -- this is the default -gnzmean = Combine datasets by averaging intensities (not counting zeros) -gmax = Combine datasets by taking max intensity (e.g., -7 and 2 combine to 2) -gamax = Combine datasets by taking max absolute intensity (e.g., -7 and 2 combine to 7) -gsmax = Combine datasets by taking max signed intensity (e.g., -7 and 2 combine to -7) -gcount = Combine datasets by counting number of 'hits' in each voxel (see below for definition of 'hit') -gorder = Combine datasets in order of input: * If a voxel is nonzero in dataset #1, then that value goes into the voxel. * If a voxel is zero in dataset #1 but nonzero in dataset #2, then the value from #2 is used. * And so forth: the first dataset with a nonzero entry in a given voxel 'wins' -gfisher = Takes the arctanh of each input, averages these, and outputs the tanh of the average. If the input datum is 'short', then input values are scaled by 0.0001 and output values by 10000. This option is for merging bricks of correlation coefficients. -nscale = If the output datum is shorts, don't do the scaling to the max range [similar to 3dcalc's -nscale option] MERGING OPERATIONS APPLIED TO THE THRESHOLD DATA: [That is, different ways to combine the thresholds. If none of these ] [are given, the thresholds will not be merged and the output dataset ] [will not have threshold data attached. Note that the following '-tg'] [command line options are mutually exclusive, but are independent of ] [the '-g' options given above for merging the intensity data values. ] -tgfisher = This option is only applicable if each input dataset is of the 'fico' or 'fith' types -- functional intensity plus correlation or plus threshold. (In the latter case, the threshold values are interpreted as correlation coefficients.) The correlation coefficients are averaged as described by -gfisher above, and the output dataset will be of the fico type if all inputs are fico type; otherwise, the output datasets will be of the fith type. N.B.: The difference between the -tgfisher and -gfisher methods is that -tgfisher applies to the threshold data stored with a dataset, while -gfisher applies to the intensity data. Thus, -gfisher would normally be applied to a dataset created from correlation coefficients directly, or from the application of the -1thtoin option to a fico or fith dataset. OPTIONAL WAYS TO POSTPROCESS THE COMBINED RESULTS: [May be combined with the above methods.] [Any combination of these options may be used.] -ghits count = Delete voxels that aren't !=0 in at least count datasets (!=0 is a 'hit') -gclust rmm vmul = Form clusters with connection distance rmm and clip off data not in clusters of volume at least vmul microliters The '-g' and '-tg' options apply to the entire group of input datasets. OPTIONS THAT CONTROL THE NAMES OF THE OUTPUT DATASET: -session dirname = write output into given directory (default=./) -prefix pname = use 'pname' for the output dataset prefix (default=mrg) NOTES: ** If only one dataset is read into this program, then the '-g' options do not apply, and the output dataset is simply the '-1' options applied to the input dataset (i.e., edited). ** A merged output dataset is ALWAYS of the intensity-only variety. ** You can combine the outputs of 3dmerge with other sub-bricks using the program 3dbucket. ** Complex-valued datasets cannot be merged. ** This program cannot handle time-dependent datasets without -doall. ** Note that the input datasets are specified by their .HEAD files, but that their .BRIK files must exist also! INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ** Input datasets using sub-brick selectors are treated as follows: - 3D+time if the dataset is 3D+time and more than 1 brick is chosen - otherwise, as bucket datasets (-abuc or -fbuc) (in particular, fico, fitt, etc. datasets are converted to fbuc) ** If you are NOT using -doall, and choose more than one sub-brick with the selector, then you may need to use -1dindex to further pick out the sub-brick on which to operate (why you would do this I cannot fathom). If you are also using a thresholding operation (e.g., -1thresh), then you also MUST use -1tindex to choose which sub-brick counts as the 'threshold' value. When used with sub-brick selection, 'index' refers the dataset AFTER it has been read in: -1dindex 1 -1tindex 3 'dset+orig[4..7]' means to use the #5 sub-brick of dset+orig as the data for merging and the #7 sub-brick of dset+orig as the threshold values. ** The above example would better be done with -1tindex 1 'dset+orig[5,7]' since the default data index is 0. (You would only use -1tindex if you are actually using a thresholding operation.) ** -1dindex and -1tindex apply to all input datasets. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dMSE
Usage: 3dMSE [options] dset Computes voxelwise multi-scale entropy. Options: -polort m = Remove polynomial trend of order 'm', for m=-1..3. [default is m=1; removal is by least squares]. Using m=-1 means no detrending; this is only useful for data/information that has been pre-processed. -autoclip = Clip off low-intensity regions in the dataset, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The mask is determined the same way that 3dAutomask works. -mask mmm = Mask to define 'in-brain' voxels. Reducing the number the number of voxels included in the calculation will significantly speedup the calculation. Consider using a mask to constrain the calculations to the grey matter rather than the whole brain. This is also preferable to using -autoclip or -automask. -prefix p = Save output into dataset with prefix 'p', this file will contain bricks for both 'weighted' or 'degree' centrality [default prefix is 'MSE']. -scales N = The number of scales to be used in the calculation. [default is 5]. -entwin w = The window size used in the calculation. [default is 2]. -rthresh r = The radius threshold for determining if values are the same in the SampleEn calculation, in fractions of the standard deviation. [default is .5]. Notes: * The output dataset is a bucket type of floats. -- RWCox - 31 Jan 2002 and 16 Jul 2010 -- Cameron Craddock - 26 Sept 2015 ========================================================================= * This binary version of 3dMSE is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dMSS
================== Welcome to 3dMSS ================== Program for Voxelwise Multilevel Smoothing Spline (MSS) Analysis #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 1.0.9, May 1, 2025 Author: Gang Chen (gangchen@mail.nih.gov) Website - https://afni.nimh.nih.gov/gangchen_homepage SSCC/NIMH, National Institutes of Health, Bethesda MD 20892, USA #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Introduction ------ Multilevel Smoothing-Spline (MSS) Modeling The linearity assumption surrounding a quantitative variable in common practice may be a reasonable approximation especially when the variable is confined within a narrow range, but can be inappropriate under some circumstances when the variable's effect is non-monotonic or tortuous. As a more flexible and adaptive approach, multilevel smoothing splines (MSS) offers a more powerful analytical tool for population-level neuroimaging data analysis that involves one or more quantitative predictors. More theoretical discussion can be found in Chen, G., Nash, T.A., Cole, K.M., Kohn, P.D., Wei, S.-M., Gregory, M.D., Eisenberg, D.P., Cox, R.W., Berman, K.F., Shane Kippenhan, J., 2021. Beyond linearity in neuroimaging: Capturing nonlinear relationships with application to longitudinal studies. NeuroImage 233, 117891. https://doi.org/10.1016/j.neuroimage.2021.117891 Chen, G., Taylor, P.A., Reynolds, R.C., Leibenluft, E., Pine, D.S., Brotman, M.A., Pagliaccio, D., Haller, S.P., 2023. BOLD Response is more than just magnitude: Improving detection sensitivity through capturing hemodynamic profiles. NeuroImage 277, 120224. https://doi.org/10.1016/j.neuroimage.2023.120224 To be able to run 3dMSS, one needs to have the following R packages installed: "gamm4" and "snow". To install these R packages, run the following command at the terminal: rPkgsInstall -pkgs "gamm4,snow" Alternatively you may install them in R: install.packages("gamm4") install.packages("snow") It is best to go through all the examples below to get hang of the MSS scripting interface. Once the 3dMSS script is constructed, it can be run by copying and pasting to the terminal. Alternatively (and probably better) you save the script as a text file, for example, called MSS.txt, and execute it with the following (assuming on tc shell), nohup tcsh -x MSS.txt & or, nohup tcsh -x MSS.txt > diary.txt & or, nohup tcsh -x MSS.txt |& tee diary.txt & The advantage of the latter commands is that the progression is saved into the text file diary.txt and, if anything goes awry, can be examined later. Example 1 --- simplest case: one group of subjects with a between-subject quantitative variable that does not vary within subject. MSS analysis is set up to model the trajectory or trend along age, and can be specified through the option -mrr, which is solved via a model formuation of ridge regression. Again, the following exemplary script assumes that 'age' is a between-subjects variable (not varying within subject): 3dMSS -prefix MSS -jobs 16 \ -mrr 's(age,k=10)' \ -qVars 'age' \ -mask myMask.nii \ -bounds -2 2 \ -prediction @pred.txt \ -dataTable @data.txt The part 's(age,k=10)' indicates that 'age' is modeled via a smooth curve. The minimum number of samples should be 6 or more. 'k=10' inside the model specification s() sets the number of knots. If the number of data samples (e.g., age) is less than 10, set k to the number of available samples (e.g., 8). No empty space is allowed in the model formulation. With the option -bounds, values beyond [-2, 2] will be treated as outliers and considered as missing. If you want to set a range, choose one that make sense with your specific input data. The file pred.txt lists all the expl1anatory variables (excluding lower-level variables such as subject) for prediction. The file should be in a data.frame format as below: label age time1 1 time2 2 time3 3 ... time8 8 time9 9 time10 10 ... The file data.txt stores the information for all the variables and input data in a data.frame format. For example: Subj age InputFile S1 1 ~/alex/MSS/S1.nii S2 2 ~/alex/MSS/S2.nii ... In the output the first sub-brick shows the statistical evidence in the form of chi-square distribution with 2 degrees of freedom (2 DFs do not mean anything, just for the convenience of information coding). This sub-brick is the statistical evidence for the trejectory of the group. If you want to estimate the trend at the population level, use the option -prediction with a table that codes the ages you would like to track the trend. In the output there is one predicted value for each age plus the associated uncertainty (standard error). For example, with 10 age values, there will be 10 predicted values plus 10 standard errors. The sub-bricks for prediction and standard errors are interleaved. Example 2 --- Largely same as Example 1, but with 'age' as a within-subject quantitative variable (varying within each subject). The model is better specified by replacing the line of -mrr in Example 1 with the following two lines: -mrr 's(age,k=10)+s(Subj,bs="re")' \ -vt Subj 's(Subj)' \ The part 's(age,k=10)' indicates that 'age' is modeled via a smooth curve. The minimum number of samples should be 6 or more. 'k=10' inside the model specification s() sets the number of knots. If the number of data samples (e.g., age) is less than 10, set k to the number of available samples (e.g., 8). The second term 's(Subj,bs="re")' in the model specification means that each subject is allowed to have a varying intercept or random effect ('re'). To estimate the smooth trajectory through the option -prediction, the option -vt has to be included in this case to indicate the varying term (usually subjects). That is, if prediction is desirable, one has to explicitly declare the variable (e.g., Subj) that is associated with the varying term (e.g., s(Subj)). No empty space is allowed in the model formulation and the the varying term. The full script version is 3dMSS -prefix MSS -jobs 16 \ -mrr 's(age,k=10)+s(Subj,bs="re")' \ -vt Subj 's(Subj)' \ -qVars 'age' \ -mask myMask.nii \ -bounds -2 2 \ -prediction @pred.txt \ -dataTable @data.txt All the rest remains the same as Example 1. Alternatively, this model with varying subject-level intercept can be specified with -lme 's(age,k=10)' \ -ranEff 'list(Subj=~1)' \ which is solved through the linear mixed-effect (lme) platform. The -vt is not needed when making prediction through the option -prediction. The two specifications, -mrr and -lme, would render similar results, but the runtime may differ depending on the amount of data and model complexity. Example 3 --- two groups and one quantitative variable (age). MSS analysis is set up to compare the trajectory or trend along age between the two groups, which are quantitatively coded as -1 and 1. For example, if the two groups are females and males, you can code females as -1 and males as 1. The following script applies to the situation when the quantitative variable does not vary within subject, 3dMSS -prefix MSS -jobs 16 \ -mrr 's(age,k=10)+s(age,k=10,by=grp)' \ -qVars 'age' \ -mask myMask.nii \ -bounds -2 2 \ -prediction @pred.txt \ -dataTable @data.txt The part 's(age,k=10)' indicates that 'age' is modeled via a smooth curve. The minimum number of samples should be 6 or more. 'k=10' inside the model specification s() sets the number of knots. If the number of data samples (e.g., age) is less than 10, set k to the number of available samples (e.g., 8). Use the script below when the quantitative variable varies within subject, 3dMSS -prefix MSS -jobs 16 \ -mrr 's(age,k=10)+s(age,k=10,by=grp)+s(Subj,bs="re")' \ -vt Subj 's(Subj)' \ -qVars 'age' \ -mask myMask.nii \ -bounds -2 2 \ -prediction @pred.txt \ -dataTable @data.txt or an LME version: 3dMSS -prefix MSS -jobs 16 \ -lme 's(age,k=10)+s(age,k=10,by=grp)' \ -ranEff 'list(Subj=~1)' \ -qVars 'age' \ -mask myMask.nii \ -bounds -2 2 \ -prediction @pred.txt \ -dataTable @data.txt Example 4 --- modeling hemodynamic response: this 3dMSS script is intended to (1) assess the presence of HRF for one group or (2) compare HRFs between two conditions for one group. For first case, each HRF at the indiividual level is characterized at 14 time points with a time resolution TR = 1.25s. In the second case, obtain the HRF contrast between the two conditions. For either case, each individual should have 14 input files. Two covariates are considered: sex and age. 3dMSS -prefix output -jobs 16 \ -lme 'sex+age+s(TR,k=10)' \ -ranEff 'list(subject=~1)' \ -qVars 'sex,age,TR' \ -prediction @HRF.table \ -dataTable @smooth-HRF.table The part 's(TR,k=10)' indicates that 'TR' is modeled via a smooth curve. The minimum number of samples should be 6 or more. 'k=10' inside the model specification s() sets the number of knots. If the number of data samples (e.g., TR) is less than 10, set k to the number of available samples (e.g., 8). The output filename and number of CPUs for parallelization are specified through -prefix and -jobs, respectively. The expression s() in the model specification indicator '-lme' represents the smooth function, and the term 's(TR)' codes the overall HRF profile groups. The term 'list(subject=~1)' under the option '-ranEff' indicates the random effects for the cross-individual variability in intercept. The number of thin plate spline bases was set to the default K = 10. The option '-qVars' identifies quantitative variables (TR and age in this case plus dummy-coded sex and group). The last two specifiers -prediction and -dataTable list one table for HRF prediction and another for input data information, respectively. The input file 'smooth-HRF.table' is structured in a long data frame format: subject age sex TR InputFile s1 29 1 0 s1.Inc.b0.nii s1 29 1 1 s1.Inc.b1.nii s1 29 1 2 s1.Inc.b2.nii s1 29 1 3 s1.Inc.b3.nii s1 29 1 4 s1.Inc.b4.nii ... The factor 'sex' is dummy-coded with 1s and -1s. The following table as the input file 'HRF.table' provides the specifications for predicted HRFs: label age sex TR time1 6.2 1 0.00 time2 6.2 1 0.25 time3 6.2 1 0.50 ... Example 5 --- modeling hemodynamic response: this 3dMSS script is intended to (1) compares HRFs under one task condition between the two groups of patients (PT) and healthy volunteer (HV) at the population level, or (2) assess the interaction between group and task condition (2 levels). For the second case, obtain the HRF contrast at each time point. In either case, if the HRF is represented with 14 time points with a time resolution TR = 1.25s, each individual should have 14 input files. Two covariates are considered: sex and age. 3dMSS -prefix output -jobs 16 \ -lme 'sex+age+s(TR,k=10)+s(TR,k=10,by=group)' \ -ranEff 'list(subject=~1)' \ -qVars 'sex,age,TR,group' \ -prediction @HRF.table \ -dataTable @smooth-HRF.table The part 's(age,k=10)' indicates that 'TR' is modeled via a smooth curve. The minimum number of samples should be 6 or more. 'k=10' inside the model specification s() sets the number of knots. If the number of data samples (e.g., TR) is less than 10, set k to the number of available samples (e.g., 8). The output filename and number of CPUs for parallelization are specified through -prefix and -jobs, respectively. The expression s() in the model specification indicator '-lme' represents the smooth function, and the two terms 's(TR)' and 's(TR,by=group)' code the overall HRF profile and the HRF difference between the two groups. The term 'list(subject=~1)' under the option '-ranEff' indicates the random effects for the cross-individual variability in intercept. The number of thin plate spline bases was set to the default K = 10. The option '-qVars' identifies quantitative variables (TR and age in this case plus dummy-coded sex and group). The last two specifiers -prediction and -dataTable list one table for HRF prediction and another for input data information, respectively. The input file 'smooth-HRF.table' is structured in a long data frame format: subject age sex group TR InputFile s1 29 1 1 0 s1.Inc.b0.nii s1 29 1 1 1 s1.Inc.b1.nii s1 29 1 1 2 s1.Inc.b2.nii s1 29 1 1 3 s1.Inc.b3.nii s1 29 1 1 4 s1.Inc.b4.nii ... Both 'group' and 'sex' are dummy-coded with 1s and -1s. The following table as the input file 'HRF.table' provides the specifications for predicted HRFs: label age sex group TR g1.t1 6.2 1 1 0.00 g1.t2 6.2 1 1 0.25 g1.t3 6.2 1 1 0.50 ... g2.t1 3.5 -1 -1 0.00 g2.t2 3.5 -1 -1 0.25 g2.t3 3.5 -1 -1 0.50 ... Options in alphabetical order: ------------------------------ -bounds lb ub: This option is for outlier removal. Two numbers are expected from the user: the lower bound (lb) and the upper bound (ub). The input data will be confined within [lb, ub]: any values in the input data that are beyond the bounds will be removed and treated as missing. Make sure the first number less than the second. You do not have to use this option to censor your data! -cio: Use AFNI's C io functions, which is default. Alternatively -Rio can be used. -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last in the script; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The order of the columns should not matter except that the last column has to be the one for input files, 'InputFile'. Each row should contain only one input file in the table of long format (cf. wide format) as defined in R. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) When the table is part of the script, a backslash is needed at the end of each line to indicate the continuation to the next line. Alternatively, one can save the context of the table as a separate file, e.g., calling it table.txt, and then in the script specify the data with '-dataTable @table.txt'. However, when the table is provided as a separate file, do NOT put any quotes around the square brackets for each sub-brick, otherwise the program would not properly read the files, unlike the situation when quotes are required if the table is included as part of the script. Backslash is also not needed at the end of each line, but it would not cause any problem if present. This option of separating the table from the script is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset. -dbgArgs: This option will enable R to save the parameters in a file called .3dMSS.dbg.AFNI.args in the current directory so that debugging can be performed. -help: this help message -IF var_name: var_name is used to specify the column name that is designated for input files of effect estimate. The default (when this option is not invoked is 'InputFile', in which case the column header has to be exactly as 'InputFile' This input file for effect estimates has to be the last column. -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -lme FORMULA: Specify the fixed effect components of the model. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. See examples in the help for details. -mask MASK: Process voxels inside this mask only. Default is no masking. -mrr FORMULA: Specify the model formulation through multilevel smoothing splines. Expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. The nonlinear trajectory is specified through the expression of s(x,k=?) where s() indicates a smooth function, x is a quantitative variable with which one would like to trace the trajectory and k is the number of smooth splines (knots). The default (when k is missing) for k is 10, which is good enough most of the time when there are more than 10 data points of x. When there are less than 10 data points of x, choose a value of k slightly less than the number of data points. -prediction TABLE: Provide a data table so that predicted values could be generated for graphical illustration. Usually the table should contain similar structure as the input file except that 1) reserve the first column for effect labels which will be used for sub-brick names in the output for those predicted values; 2) columns for those varying smoothing terms (e.g., subject) and response variable (i.e., Y) should not be includes. Try to specify equally-spaced values with a small for the quantitative variable of modeled trajectory (e.g., age) so that smooth curves could be plotted after the analysis. See Examples in the help for a couple of specific tables used for predictions. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached (otherwise the output would be saved in AFNI format). -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarsCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ substantially in the average value of the covariate. -ranEff FORMULA: Specify the random effect components of the model. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. In the MSS context the simplest model is "list(Subj=~1)" in which the varying or random effect from each subject is incorporated in the model. Each random-effects factor is specified within parentheses per formula convention in R. -Rio: Use R's io functions. The alternative is -cio. -sdiff variable_list: This option is used to specify a factor for group comparisons. For example, if one wants to compare age trajectory between two groups through "s(age,by=group)" in model specification, use "-sdiff 'group'" to generate the predicted trajectory of group differences through the values provided in the prediction table under the option -prediction. Currently it only allows for one group comparison. Perform separate analyses if more than one group comparison is desirable. " . -show_allowed_options: list of allowed options -vt var formulation: This option is for specifying varying smoothing terms. Two components are required: the first one 'var' indicates the variable (e.g., subject) around which the smoothing will vary while the second component specifies the smoothing formulation (e.g., s(age,subject)). When there is no varying smoothing terms (e.g., no within-subject variables), do not use this option.

AFNI program: 3dMultiThresh
Program to apply a multi-threshold (mthresh) dataset to an input dataset. Usage: 3dMultiThresh OPTIONS OPTIONS (in any order) ---------------------- -mthresh mmm = Multi-threshold dataset from 3dXClustSim (usually via running '3dttest++ -ETAC'). *OR* globalETAC.mthresh.*.niml threshold file -input ddd = Dataset to threshold. -1tindex iii = Index (sub-brick) on which to threshold. -signed +/- = If the .mthresh.nii file from 3dXClustSim was created using 1-sided thresholding, this option tells which sign to choose when doing voxel-wise thresholding: + or -. ++ If the .mthresh.nii file was created using 2-sided thresholding, this option is ignored. -pos = Same as '-signed +' -neg = Same as '-signed -' -prefix ppp = prefix for output dataset ++ Can be 'NULL' to get no output dataset -maskonly = Instead of outputting a thresholded version of the input dataset, just output a 0/1 mask dataset of voxels that survive the process. -allmask qqq = Write out a multi-volume dataset with prefix 'qqq' where each volume is the binary mask of voxels that pass ONE of the tests. This dataset can be used to see which tests mattered where in the brain. ++ To be more clear, there will be one sub-brick for each p-value threshold coded in the '-mthresh' dataset (e.g., p=0.0100 and p=0.0001). ++ In each sub-brick, the value will be between 0 and 7, and is the sum of these: 1 == hpow=0 was declared 'active' 2 == hpow=1 was declared 'active' 4 == hpow=2 was declared 'active' Of course, an hpow value will only be tested if it is so encoded in the '-mthresh' dataset. -nozero = This option prevents the output of a dataset if it would be all zero -quiet = Turn off progress report messages The number of surviving voxels will be written to stdout. It can be captured in a csh script by a command such as set nhits = `3dMultiThresh OPTIONS` Meant to be used in conjunction with program 3dXClustSim, which is in turn meant to be used with program 3dttest++ -- RWCox

AFNI program: 3dMVM
Welcome to 3dMVM ~1~ AFNI Group Analysis Program with Multi-Variate Modeling Approach #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Version 4.2.2, May 30, 2024 Author: Gang Chen (gangchen@mail.nih.gov) Website - https://afni.nimh.nih.gov/MVM SSCC/NIMH, National Institutes of Health, Bethesda MD 20892 #+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Usage: ~1~ ------ 3dMVM is a group-analysis program that performs traditional ANOVA- and ANCOVA- style computations. In addition, it can run multivariate modeling in the sense of multiple simultaneous response variables. For univariate analysis, no bound is imposed on the numbers of explanatory variables, and these variables can be either categorical (factor) or numerical/quantitative (covariate). F-statistics for all main effects and interactions are automatically included in the output. In addition, general linear tests (GLTs) can be requested via symbolic coding. Input files for 3dMVM can be in AFNI, NIfTI, or surface (niml.dset) format. Note that unequal number of subjects across groups are allowed, but scenarios with missing data for a within-subject factor are better modeled with 3dLME or 3dLMEr. Cases with quantitative variables (covariates) that vary across the levels of a within-subject variable are also better handled with 3dLME or 3dLMEr. Computational cost with 3dMVM is higher relative to 3dttest++ or 3dANOVAx, but it has the capability to correct for sphericity violations when within-subject factors with more than two levels are involved. Please cite: ~1~ If you want to cite the analysis approach for AN(C)OVA, use the following:~2~ Chen, G., Adleman, N.E., Saad, Z.S., Leibenluft, E., Cox, R.W. (2014). Applications of Multivariate Modeling to Neuroimaging Group Analysis: A Comprehensive Alternative to Univariate General Linear Model. NeuroImage 99, 571-588. 10.1016/j.neuroimage.2014.06.027 https://afni.nimh.nih.gov/pub/dist/HBM2014/Chen_in_press.pdf For group analysis with effect estimates from multiple basis functions, cite: ~2~ Chen, G., Saad, Z.S., Adleman, N.E., Leibenluft, E., Cox, R.W. (2015). Detecting the subtle shape differences in hemodynamic responses at the group level. Front. Neurosci., 26 October 2015. http://dx.doi.org/10.3389/fnins.2015.00375 Installation requirements: ~1~ In addition to R installation, the following two R packages need to be acquired in R first before running 3dMVM: "afex" and "phia". In addition, the "snow" package is also needed if one wants to take advantage of parallel computing. To install these packages, run the following command at the terminal: rPkgsInstall -pkgs ALL Alternatively, you may install them in R: install.packages("afex") install.packages("phia") install.packages("snow") More details about 3dMVM can be found at https://afni.nimh.nih.gov/MVM Running: ~1~ Once the 3dMVM command script is constructed, it can be run by copying and pasting to the terminal. Alternatively (and probably better) you save the script as a text file, for example, called MVM.txt, and execute it with the following (assuming on tcsh shell), tcsh -x MVM.txt & or, tcsh -x MVM.txt > diary.txt & tcsh -x MVM.txt |& tee diary.txt & The advantage of the latter command is that the progression is saved into the text file diary.txt and, if anything goes awry, can be examined later. Thanks to the R community, Henrik Singmann, and Helios de Rosario for the strong technical support. -------------------------------- Examples: ~1~ Example 1 --- 3 between-subjects and 2 within-subject variables: ~2~ Three between-subjects (genotype, sex, and scanner) and two within-subject (condition and emotion) variables. 3dMVM -prefix Example1 -jobs 4 \ -bsVars 'genotype*sex+scanner' \ -wsVars "condition*emotion" \ -mask myMask+tlrc \ -SS_type 2 \ -num_glt 14 \ -gltLabel 1 face_pos_vs_neg -gltCode 1 'condition : 1*face emotion : 1*pos -1*neg' \ -gltLabel 2 face_emot_vs_neu -gltCode 2 'condition : 1*face emotion : 1*pos +1*neg -2*neu' \ -gltLabel 3 sex_by_condition_interaction -gltCode 3 'sex : 1*male -1*female condition : 1*face -1*house' \ -gltLabel 4 3way_interaction -gltCode 4 'sex : 1*male -1*female condition : 1*face -1*house emotion : 1*pos -1*neg' \ ... -num_glf 3 \ -glfLabel 1 male_condXEmo -glfCode 1 'sex : 1*male condition : 1*face -1*house emotion : 1*pos -1*neg & 1*pos -1*neu' \ -glfLabel 2 face_sexXEmo -glfCode 2 'sex : 1*male -1*female condition : 1*face emotion : 1*pos -1*neg & 1*pos -1*neu' \ -glfLabel 3 face_sex2Emo -glfCode 3 'sex : 1*male & 1*female condition : 1*face emotion : 1*pos -1*neg & 1*pos -1*neu' \ -dataTable \ Subj genotype sex scanner condition emotion InputFile \ s1 TT male scan1 face pos s1+tlrc'[face_pos_beta]' \ s1 TT male scan1 face neg s1+tlrc'[face_neg_beta]' \ s1 TT male scan1 face neu s1+tlrc'[face_neu_beta]' \ s1 TT male scan1 house pos s1+tlrc'[house_pos_beta]' \ ... s68 TN female scan2 house pos s68+tlrc'[face_pos_beta]' \ s68 TN female scan2 house neg s68+tlrc'[face_neg_beta]' \ s68 TN female scan2 house neu s68+tlrc'[house_pos_beta]' NOTE: ~3~ 1) The 3rd GLT is for the 2-way 2 x 2 interaction between sex and condition, which is essentially a t-test (or one degree of freedom for the numerator of F-statistic). Multiple degrees of freedom for the numerator of F-statistic can be obtained through option -glfCode (see GLFs #1, #2, and #3). 2) Similarly, the 4th GLT is a 3-way 2 x 2 x 2 interaction, which is a partial (not full) interaction between the three factors because 'emotion' has three levels. The F-test for the full 2 x 2 x 3 interaction is automatically spilled out by 3dMVM. 3) The three GLFs show the user how to specify sub-interactions. 4) Option '-SS_type 2' specifies the hierarchical type for the sums of squares in the omnibus F-statistics in the output. See more details in the help. -------------------------------- Example 2 --- 2 between-subjects, 1 within-subject, 2 quantitative variables: ~2~ Two between-subjects (genotype and sex), one within-subject (emotion) factor, plus two quantitative variables (age and IQ). 3dMVM -prefix Example2 -jobs 24 \ -mask myMask+tlrc \ -bsVars "genotype*sex+age+IQ" \ -wsVars emotion \ -qVars "age,IQ" \ -qVarCenters '25,105' \ -num_glt 10 \ -gltLabel 1 pos_F_vs_M -gltCode 1 'sex : 1*female -1*male emotion : 1*pos' \ -gltLabel 2 age_pos_vs_neg -gltCode 2 'emotion : 1*pos -1*neg age :' \ -gltLabel 3 age_pos_vs_neg -gltCode 3 'emotion : 1*pos -1*neg age : 5' \ -gltLabel 4 genotype_by_sex -gltCode 4 'genotype : 1*TT -1*NN sex : 1*male -1*female' \ -gltLabel 5 genotype_by_sex_emotion -gltCode 5 'genotype : 1*TT -1*NN sex : 1*male -1*female emotion : 1*pos -1*neg' \ ... -dataTable \ Subj genotype sex age IQ emotion InputFile \ s1 TT male 24 107 pos s1+tlrc'[pos_beta]' \ s1 TT male 24 107 neg s1+tlrc'[neg_beta]' \ s1 TT male 24 107 neu s1+tlrc'[neu_beta]' \ ... s63 NN female 29 110 pos s63+tlrc'[pos_beta]' \ s63 NN female 29 110 neg s63+tlrc'[neg_beta]' \ s63 NN female 29 110 neu s63+tlrc'[neu_beta]' NOTE: ~3~ 1) The 2nd GLT shows the age effect (slope) while the 3rd GLT reveals the contrast between the emotions at the age of 30 (5 above the center). On the other hand, all the other GLTs (1st, 4th, and 5th) should be interpreted at the center Age value, 25 years old. 2) The 4th GLT is for the 2-way 2 x 2 interaction between genotype and sex, which is essentially a t-test (or one degree of freedom for the numerator of F-statistic). Multiple degrees of freedom for the numerator of F-statistic is currently unavailable. 3) Similarly, the 5th GLT is a 3-way 2 x 2 x 2 interaction, which is a partial (not full) interaction between the three factors because 'emotion' has three levels. The F-test for the full 2 x 2 x 3 interaction is automatically spilled out by 3dMVM. --------------------------------- Example 3 --- Getting more complicated: ~2~ BOLD response was modeled with multiple basis functions at individual subject level. In addition, there are one between-subjects (Group) and one within- subject (Condition) variable. Furthermore, the variable corresponding to the number of basis functions, Time, is also a within-subject variable. In the end, the F- statistics for the interactions of Group:Condition:Time, Group:Time, and Condition:Time are of specific interest. And these interactions can be further explored with GLTs in 3dMVM. 3dMVM -prefix Example3 -jobs 12 \ -mask myMask+tlrc \ -bsVars Group \ -wsVars 'Condition*Time' \ -num_glt 32 \ -gltLabel 1 old_t0 -gltCode 1 'Group : 1*old Time : 1*t0' \ -gltLabel 2 old_t1 -gltCode 2 'Group : 1*old Time : 1*t1' \ -gltLabel 3 old_t2 -gltCode 3 'Group : 1*old Time : 1*t2' \ -gltLabel 4 old_t3 -gltCode 4 'Group : 1*old Time : 1*t3' \ -gltLabel 5 yng_t0 -gltCode 5 'Group : 1*yng Time : 1*t0' \ -gltLabel 6 yng_t1 -gltCode 6 'Group : 1*yng Time : 1*t1' \ -gltLabel 7 yng_t2 -gltCode 7 'Group : 1*yng Time : 1*t2' \ -gltLabel 8 yng_t3 -gltCode 8 'Group : 1*yng Time : 1*t3' \ ... -gltLabel 17 old_face_t0 -gltCode 17 'Group : 1*old Condition : 1*face Time : 1*t0' \ -gltLabel 18 old_face_t1 -gltCode 18 'Group : 1*old Condition : 1*face Time : 1*t1' \ -gltLabel 19 old_face_t2 -gltCode 19 'Group : 1*old Condition : 1*face Time : 1*t2' \ -gltLabel 20 old_face_t3 -gltCode 20 'Group : 1*old Condition : 1*face Time : 1*t3' \ ... -dataTable \ Subj Group Condition Time InputFile \ s1 old face t0 s1+tlrc'[face#0_beta]' \ s1 old face t1 s1+tlrc'[face#1_beta]' \ s1 old face t2 s1+tlrc'[face#2_beta]' \ s1 old face t3 s1+tlrc'[face#3_beta]' \ ... s40 yng house t0 s40+tlrc'[house#0_beta]' \ s40 yng house t1 s40+tlrc'[house#1_beta]' \ s40 yng house t2 s40+tlrc'[house#2_beta]' \ s40 yng house t3 s40+tlrc'[house#3_beta]' NOTE: ~3~ The model for the analysis can also be set up as and is equivalent to 'Group*Condition*Time'. Options: ~1~ Options in alphabetical order: ------------------------------ -bsVars FORMULA: Specify the fixed effects for between-subjects factors and quantitative variables. When no between-subject factors are present, simply put 1 for FORMULA. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. No spaces are allowed in the FORMULA expression. Variable names in the formula should be consistent with the ones used in the header underneath -dataTable. A+B represents the additive effects of A and B, A:B is the interaction between A and B, and A*B = A+B+A:B. The effects of within-subject factors, if present under -wsVars are automatically assumed to interact with the ones specified here. Subject as a variable should not occur in the model specification here. -cio: Use AFNI's C io functions, which is default. Alternatively -Rio can be used. -dataTable TABLE: List the data structure with a header as the first line. NOTE: 1) This option has to occur last; that is, no other options are allowed thereafter. Each line should end with a backslash except for the last line. 2) The first column is fixed and reserved with label 'Subj', and the last is reserved for 'InputFile'. Each row should contain only one effect estimate in the table of long format (cf. wide format) as defined in R. The level labels of a factor should contain at least one character. Input files can be in AFNI, NIfTI or surface format. AFNI files can be specified with sub-brick selector (square brackets [] within quotes) specified with a number or label. Unequal number of subjects across groups are allowed, but situations with missing data for a within-subject factor are better handled with 3dLME or 3dLMEr. 3) It is fine to have variables (or columns) in the table that are not modeled in the analysis. 4) The context of the table can be saved as a separate file, e.g., called table.txt. Do not forget to include a backslash at the end of each row. In the script specify the data with '-dataTable @table.txt'. Do NOT put any quotes around the square brackets for each sub-brick! Otherwise, the program cannot properly read the files for some reason. This option is useful: (a) when there are many input files so that the program complains with an 'Arg list too long' error; (b) when you want to try different models with the same dataset (see 3) above). -dbgArgs: This option will enable R to save the parameters in a file called .3dMVM.dbg.AFNI.args in the current directory so that debugging can be performed. -GES: As an analog of the determination coefficient R^2 in multiple regression, generalized eta-squared (GES) provides a measure of effect size for each F-stat in ANOVA or general GLM, and renders a similar interpretation: proportion of variance in the response variable by the explanatory variable on hand. It ranges within [0, 1]. Notice that this option is only available with R version 3.2 and afex version 0.14 or later. -glfCode k CODING: Specify the k-th general linear F-test (GLF) through a weighted combination among factor levels. The symbolic coding has to be within (single or double) quotes. For example, the coding 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos' tests the main effect of Condition at the positive Emotion. Similarly, the coding 'Condition : 1*A -1*B & 1*A -1*C Emotion : 1*pos -1*neg' shows the interaction between the three levels of Condition and the two levels of Emotion. NOTE: 1) The weights for a variable do not have to add up to 0. 2) When a quantitative variable is present, other effects are tested at the center value of the covariate unless the covariate value is specified as, for example, 'Group : 1*Old Age : 2', where the Old Group is tested at the Age of 2 above the center. 3) The absence of a categorical variable in a coding means the levels of that factor are averaged (or collapsed) for the GLF. 4) The appearance of a categorical variable has to be followed by the linear combination of its levels. -glfLabel k label: Specify the label for the k-th general linear F-test (GLF). A symbolic coding for the GLF is assumed to follow with each -glfLabel. -gltCode k CODING: Specify the k-th general linear t-test (GLT) through a weighted combination among factor levels. The symbolic coding has to be within (single or double) quotes. For example, the following 'Condition : 2*House -3*Face Emotion : 1*positive ' requests for a test of comparing 2 times House condition with 3 times Face condition while Emotion is held at positive valence. NOTE: 1) The weights for a variable do not have to add up to 0. 2) When a quantitative covariate is involved in the model, the absence of the covariate in the GLT coding means that the test will be performed at the center value of the covariate. However, if the covariate value is specified with a value after the colon, for example, 'Group : 1*Old Age : 2', the effect of the Old Group would be tested at the value of 2 above the center. On the other hand, 'Group : 1*Old' tests for the effect of the Old Group at the center age. 3) The effect for a quantitative variable (or slope) can be specified by omitting the value after the colon. For example, 'Group : 1*Old Age : ', or 'Group : 1*Old - 1*Young Age : '. 4) The absence of a categorical variable in a coding means the levels of that factor are averaged (or collapsed) for the GLT. 5) The appearance of a categorical variable has to be followed by the linear combination of its levels. Only a quantitative variable is allowed to have a dangling coding as seen in 'Age :'. 6) Some special interaction effects can be tested under -gltCode when the numerical DF is 1. For example, 'Group : 1*Old -1*Young Condition : 1*House -1*Face Emotion : 1*positive'. Even though this is typically an F-test that can be coded under -glfCode, it can be tested under -gltCode as well. An extra bonus is that the t-test shows the directionality while F-test does not. -gltLabel k label: Specify the label for the k-th general linear t-test (GLT). A symbolic coding for the GLT is assumed to follow with each -gltLabel. -help: this help message -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer. -mask MASK: Process voxels inside this mask only. Default is no masking. -model FORMULA: This option will phase out at some point. So use -bsVars instead. Specify the fixed effects for between-subjects factors and quantitative variables. When no between-subject factors are present, simply put 1 for FORMULA. The expression FORMULA with more than one variable has to be surrounded within (single or double) quotes. Variable names in the formula should be consistent with the ones used in the header of -dataTable. A+B represents the additive effects of A and B, A:B is the interaction between A and B, and A*B = A+B+A:B. The effects of within-subject factors, if present under -wsVars, are automatically assumed to interact with the ones specified here. Subject as a variable should not occur in the model specification here. -mVar variable: With this option, the levels of the within-subject factor will be treated as simultaneous variables in a multivariate model. For example, when the hemodynamic response time course is modeled through multiple basis functions such as TENT, TENTzero, CSPLIN, CSPLINzero, SPMG2/3, etc., the effect estimates at the multiple time points can be treated as simultaneous response variables in a multivariate model. Only one within-subject variable is allowed currently under -mVar. In addition, in the presence of -mVar, no other within-subject factors should be included. If modeling extra within-subject factors with -mVar is desirable, consider flattening such factors; that is, perform multiple analyses at each level or their contrasts of the factor. The output for multivariate testing are labeled with -MV0- in the sub-brick names. -num_glf NUMBER: Specify the number of general linear F-tests (GLFs). A glf involves the union of two or more simple tests. See details in -glfCode. -num_glt NUMBER: Specify the number of general linear t-tests (GLTs). A glt is a linear combination of a factor levels. See details in -gltCode. -prefix PREFIX: Output file name. For AFNI format, provide prefix only, with no view+suffix needed. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. The sub-brick labeled with the '(Intercept)', if present, should be interpreted as the overall average across factor levels at the center value of each covariate. -qVarCenters VALUES: Specify centering values for quantitative variables identified under -qVars. Multiple centers are separated by commas (,) within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -qVarCetners) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the values are fed into -dataTable. -qVars variable_list: Identify quantitative variables (or covariates) with this option. The list with more than one variable has to be separated with comma (,) without any other characters such as spaces, and should be surrounded within (single or double) quotes. For example, -qVars "Age,IQ" WARNINGS: 1) Centering a quantitative variable through -qVarCenters is very critical when other fixed effects are of interest. 2) Between-subjects covariates are generally acceptable. However EXTREME caution should be taken when the groups differ significantly in the average value of the covariate. 3) Within-subject covariates vary across the levels of a within-subject factor, and can be analyzed with 3dLME or 3dLMEr, but not 3dMVM. -resid PREFIX: Output file name for the residuals. For AFNI format, provide prefix only without view+suffix. Filename for NIfTI format should have .nii attached, while file name for surface data is expected to end with .niml.dset. -Rio: Use R's io functions. The alternative is -cio. -robust: Robust regression is performed so that outliers can be reasonably handled through MM-estimation. Currently it only works without involving any within-subject factors. That is, anything that can be done with 3dttest++ could be analyzed through robust regression here (except for one-sample case which can be added later on if requested). Pairwise comparisons can be performed by providing contrast from each subject as input). Post hoc F-tests through option -glfCode are currently not available with robust regression. This option requires that the user install R package robustbase. -SC: If a within-subject factor with more than *two* levels is involved in the model, 3dMVM automatically provides the F-statistics for main and interaction effects with sphericity assumption. If the assumption is violated, the F-statistics could be inflated to some extent. This option, will enable 3dMVM to additionally output the F-statistics of sphericity correction for main and interaction effects, which are labeled with -SC- in the sub-brick names. NOTE: this option should be used only when at least one within-subject factor has more than TWO levels. -show_allowed_options: list of allowed options -SS_type 2/3: Specify the type for the sums of squares for the omnibus F-statistics. Type 2 is hierarchical or partially sequential while type 3 is marginal. Type 2 is more powerful if all the relevant higher-order interactions do not exist. The default is 3. The controversy surrounding the different types can be found at https://sscc.nimh.nih.gov/sscc/gangc/SS.html -verb VERB: Specify verbosity level. -vVarCenters VALUES: Specify centering values for voxel-wise covariates identified under -vVars. Multiple centers are separated by commas (,) within (single or double) quotes. The order of the values should match that of the quantitative variables in -qVars. Default (absence of option -vVarsCetners) means centering on the average of the variable across ALL subjects regardless their grouping. If within-group centering is desirable, center the variable YOURSELF first before the files are fed into -dataTable. -vVars variable_list: Identify voxel-wise covariates with this option. Currently one voxel-wise covariate is allowed only, but this may change if demand occurs... By default, mean centering is performed voxel-wise across all subjects. Alternatively centering can be specified through a global value under -vVarsCenters. If the voxel-wise covariates have already been centered, set the centers at 0 with -vVarsCenters. -wsE2: If at least one within-subject factor is involved in the model, any omnibus F-test associated with a within-subject factor is assessed with both univariate and within-subject multivariate tests. Use the option only if at least one within-subject factor has more than two levels. By default, 3dMVM provides an F-stat through the univariate testing (UVT) method for each effect that involves a within-subject factor. With option -wsE2 UVT is combined with the within-subject multivariate approach, and the merged result remains the same as UVT most of the time (or in most brain regions), but occasionally it may be more powerful. -wsMVT: By default, 3dMVM provides an F-stat through univariate testing (UVT) for each effect that involves a within-subject factor. If at least one within-subject factor is involved in the model, option -wsMVT provides within-subject multivariate testing for any effect associated with a within-subject variable. The testing strategy is different from the conventional univariate GLM, see more details in Chen et al. (2014), Applications of Multivariate Modeling to Neuroimaging Group Analysis: A Comprehensive Alternative to Univariate General Linear Model. NeuroImage 99, 571-588. If all the within-subject factors have two levels, the multivariate testing would render the same results as the univariate version. So, use the option only if at least one within-subject factor has more than two levels. The F-statistics from the multivariate testing are labeled with -wsMVT- in the sub-brick names. Note that the conventional univariate F-statistics are automatically included in the beginning of the output regardless the presence of this option. -wsVars FORMULA: Within-subject factors, if present, have to be listed here, otherwise the program will choke. If no within-subject exists, don't include this option in the script. Coding for additive effects and interactions is the same as in -bsVars. The FORMULA with more than one variable has to be surrounded within (single or double) quotes. Note that the within-subject variables are assumed to interact with those between-subjects variables specified under -bsVars. The hemodynamic response time courses are better modeled as simultaneous outcomes through option -mVar, and not as the levels of a within-subject factor. The variables under -wsVars and -mVar are exclusive from each other.

AFNI program: 3dMVM_validator
---------------------------------------------------------------------------- 3dMVM_validator Launch the 3dMVM model validation shiny app in a web browser. Input is a file containing a table formatted like the 3dMVM "-dataTable". See 3dMVM -help for the correct format. This will create a temporary folder in the current directory with a random name similar to: __8726_3dMVM_validator_temp_delete It will be deleted when you close the shiny app. If it is still there after you close the app, it is safe to delete. If you seem to be missing some R packages, you may need to run: @afni_R_package_install -shiny ----------------------------------------------------------------------------- options: -dataTable : A file containing a data table formatted like the 3dMVM "-dataTable". -ShinyFolder : Use a custom shiny folder (for testing purposes). -help : show this help ----------------------------------------------------------------------------- examples: 3dMVM_validator -dataTable ~/my_dataTable.csv ----------------------------------------------------------------------------- Justin Rajendra 11/2017

AFNI program: 3dNetCorr
Overview ~1~ Calculate correlation matrix of a set of ROIs (using mean time series of each). Several networks may be analyzed simultaneously, one per brick. Written by PA Taylor (March, 2013), part of FATCAT (Taylor & Saad, 2013) in AFNI. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Usage ~1~ Input a set of 4D data and a set of ROI masks (i.e., a bunch of ROIs in a brik each labelled with a distinct integer), and get a matrix of correlation values for it. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Output ~1~ Output will be a simple text file, first with the number N of ROIs in the set, then an empty line, then a list of the ROI labels in the file (i.e., col/row labels), empty line, and then an NxN matrix of correlation values (diagonals should be unity). One can also output the Fisher Z-transform of the matrix (with zeros along diag). If multiple subbricks are entered, one gets multiple files output, one per subbrick/network. Naming convention of outputs: PREFIX_???.netcc, where `???' represents a zero-padded version of the network number, based on the number of subbricks in the `in_rois' option (i.e., 000, 001,...). If the `-ts_out' option is used, the mean time series per ROI, one line, are output in PREFIX_???.netts files. Labeltables are now also supported; when an '-inset FILE' contains a labeltable, the labels will then be passed to the *.netcc file. These labels may then be referred to in plotting/output, such as using fat_mat_sel.py. +NEW+ (Dec. 2014): A PREFIX_???.niml.dset is now also output automatically. This NIML/SUMA-esque file is mainly for use in SUMA, for visualizing connectivity matrix info in a 3D brain. It can be opened via, for example: $ suma -vol ROI_FILE -gdset FILE.niml.dset It is now also possible to output whole brain correlation maps, generated from the average time series of each ROI, as either Pearson r or Fisher-transformed Z-scores (or both); see the '-ts_wb*' options below. [As of April, 2017] There is now more checking done for having any null time series in ROIs. They are bad to have around, esp. when they fill an ROI. A new file called 'PREFIX.roidat' is now output, whose columns contain information for each ROI in the used mask: [Nvox] [Nvox with non-null ts] [non-null frac] # [ROI number] [label] The program also won't run now by default if an ROI contains more than 10 percent null time series; one can use a '-push*' option (see below) to still calculate anyways, but it will definitely cease if any ROI is full of null time series. ... And the user can flag to output a binary mask of the non-null time series, called 'PREFIX_mask_nnull*', with the new option '-output_mask_nonnull'. This might be useful to check if your data are well-masked, if you haven't done so already (and you know who you are...). [As of April, 2017] On a minor note, one can also apply string labels to the WB correlation/Z-score output files; see the option '-ts_wb_strlabel', below. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Command ~1~ 3dNetCorr -prefix PREFIX {-mask MASK} {-fish_z} {-part_corr} \ -inset FILE -in_rois INROIS {-ts_out} {-ts_label} \ {-ts_indiv} {-ts_wb_corr} {-ts_wb_Z} {-nifti} \ {-push_thru_many_zeros} {-ts_wb_strlabel} \ {-output_mask_nonnull} {-weight_ts WTS} \ {-weight_corr WCORR} * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Running ~1~ -prefix PREFIX :(req) output file name part (see description below). -inset FILE :(req) time series file (4D data set). -in_rois INROIS :(req) can input a set of ROIs, each labelled with distinct integers. Multiple subbricks can be input, each will be treated as a separate network. -mask MASK :can include a whole brain mask within which to calculate correlation. If no mask is input, then the program will internally 'automask', based on when non-uniformly-zero time series are. If you want to neither put in a mask *nor* have the automasking occur, see '-automask_off', below. -fish_z :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. -part_corr :output the partial correlation matrix. It is calculated from the inverse of regular Pearson matrix, R, as follows: let M = R^{I} be in the inverse of the Pearson cc matrix. Then each element p_{ij} of the partial correlation (PC) matrix is given as: p_{ij} = -M_{ij}/sqrt( M_{ii} * M_{jj} ). This will also calculate the PC-beta (PCB) matrix, which is not symmetric, and whose values are given as: b_{ij} = -M_{ij}/M_{ii}. Use as you wish. For both PC and PCB, the diagonals should be uniformly (negative) unity. -ts_out :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. -ts_label :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. -ts_indiv :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. -ts_wb_corr :switch to perform 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. -ts_wb_Z :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; hope that's good enough). Files are labelled WB_Z_ROI_001+orig, etc. -weight_ts WTS :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]. -weight_corr WCORR :input a 1D file WTS of weights that will be applied to estimate a weighted Pearson Correlation. This is different than the '-weight_ts ..' weighting. -ts_wb_strlabel :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. -nifti :output any correlation map files as NIFTI files (default is BRIK/HEAD). Only useful if using '-ts_wb_corr' and/or '-ts_wb_Z'. -output_mask_nonnull :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. -push_thru_many_zeros :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. -allow_roi_zeros :by default, this program will end unhappily if any ROI contains only time series that are all zeros (which might occur if you applied a mask to your data that is smaller than your ROI map). This is because the correlation with an all-zero time series is undefined. However, if you want to allow ROIs to have all-zero time series, use this option; each row and column element in the Pearson and Fisher-Z transformed matrices for this ROI will be 0. NB: you cannot use -part_corr when this option is used, to avoid of mathematical badness. See the NOTE about this option, below -automask_off :if you do not enter a mask, this program will make an internal automask of where time series are not uniformly zero. However, if you don't want this done (e.g., you have a map of N ROIs that has greater extent than your masked EPI data, and you are using '-allow_roi_zeros' to get a full NxN matrix, even if some rows and columns are zero), then use this option. -ignore_LT :switch to ignore any label table labels in the '-in_rois' file, if there are any labels attached. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * NOTES ~1~ Re. Allowing zero-filled ROIs ('-allow_roi_zeros') ~2~ If you use the '-allow_roi_zeros' option, you can get rows and columns of all zeros in the output *.netcc matrices (indeed, you are probably using it specifically to have the 'full' NxN matrix from N input ROIs, even with ROIs that only contain all-zero time series). Note that, at present, you should NOT put *.netcc files that contain such rows/columns of zeros into the fat_proc* pipeline, because 0 is a valid correlation (or Fisher Z-transform) value, and the pipeline is not designed to filter these values out (like it would for *.grid files). Therefore, the zeros will be included as 'real' correlation values, which would not be correct. So, these matrices could be output into OTHER analyses fine, but for preparing to do fat_proc_* comparisons, you would want to run this program without '-allow_roi_zeros'. So, sometimes you might run it twice, with and without that option, which should be OK, because it is not a very time consuming program. Also note that if an average ROI time series is zero (which will occur when all voxel time series within it are zero and the '-allow_roi_zeros' is being utilized) and the user has asked for WB correlation maps with '-ts_wb_cor' and/or '-ts_wb_Z', no volume will be output for any ROI that is all-zeros. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Examples ~1~ 3dNetCorr \ -inset REST_in_DWI.nii.gz \ -in_rois ROI_ICMAP_GM+orig \ -fish_z \ -ts_wb_corr \ -mask mask_DWI+orig \ -prefix FMRI/REST_corr 3dNetCorr \ -inset REST_in_DWI.nii.gz \ -in_rois ROI_ICMAP_GM+orig \ -fish_z \ -ts_wb_corr \ -automask_off \ -all_roi_zeros \ -prefix FMRI/out * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________

AFNI program: 3dnewid
Assigns a new ID code to a dataset; this is useful when making a copy of a dataset, so that the internal ID codes remain unique. Usage: 3dnewid dataset [dataset ...] or 3dnewid -fun [n] to see what n randomly generated ID codes look like. (If the integer n is not present, 1 ID code is printed.) or 3dnewid -fun11 to get an 11 character ID code (for use in scripting). or 3dnewid -int to get a random positive integer. The values are usually between 1 million and 1 billion. Such a value could be used as a random seeds in various AFNI programs, such as 3dttest++ -seed. or 3dnewid -hash STR to get a unique hashcode of STR (Unlike the other ways of using 3dnewid, if STR is the) (same in 2 different runs, the output will be the same.) (The -hash algorithm begins at step 2 in the list below.) or 3dnewid -MD5 STR to get the MD5 hash of STR, should be same as -hash output without the prefix and without the + and / char substitutions. How ID codes are created (here and in other AFNI programs): ---------------------------------------------------------- The AFNI ID code generator attempts to create a globally unique string identifier, using the following steps. 1) A long string is created from the system identifier information ('uname -a'), the current epoch time in seconds and microseconds, the process ID, and the number of times the current process has called the ID code function. 2) This string is then hashed into a 128 bit code using the MD5 algorithm. (cf. file thd_md5.c) 3) This bit code is then converted to a 22 character string using Base64 encoding, replacing '/' with '-' and '+' with '_'. With these changes, the ID code can be used as a Unix filename or an XML name string. (cf. file thd_base64.c) 4) A 4 character prefix is attached at the beginning to produce the final ID code. If you set the environment variable IDCODE_PREFIX to something, then its first 3 characters and an underscore will be used for the prefix of the new ID code, provided that the first character is alphabetic and the other 2 alphanumeric; otherwise, the default prefix 'NIH_' will be used. The source code is function UNIQ_idcode() in file niml_uuid.c ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNLfim
++ 3dNLfim: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program calculates a nonlinear regression for each voxel of the input AFNI 3d+time data set. The nonlinear regression is calculated by means of a least squares fit to the signal plus noise models which are specified by the user. Usage with terminal options: 3dNLfim -help show this help -help_models show model help from any that have it (can come via AFNI_MODEL_HELP_ALL) One can get help for an individual model, *if* it exists, by setting a similar environment variable, and providing some non-trivial function option (like -load_models), e.g., 3dNLfim -DAFNI_MODEL_HELP_CONV_PRF_6=Y -load_models Indifidual help should be available for any model with help via -help_models. -load_models simply load all models and exit (this is for testing or getting model help) General usage: 3dNLfim -input fname fname = filename of 3d + time data file for input [-mask mset] Use the 0 sub-brick of dataset 'mset' as a mask to indicate which voxels to analyze (a sub-brick selector is allowed) [default = use all voxels] [-ignore num] num = skip this number of initial images in the time series for regression analysis; default = 0 ****N.B.: default ignore value changed from 3 to 0, on 04 Nov 2008 (BHO day). [-inTR] set delt = TR of the input 3d+time dataset [The default is to compute with delt = 1.0 ] [The model functions are calculated using a time grid of: 0, delt, 2*delt, 3*delt, ... ] [-TR delt] directly set the TR of the time series model; can be useful if the input file is a .1D file (transposed with the \' operator) [-time fname] fname = ASCII file containing each time point in the time series. Defaults to even spacing given by TR (this option overrides -inTR). -signal slabel slabel = name of (non-linear) signal model -noise nlabel nlabel = name of (linear) noise model -sconstr k c d constraints for kth signal parameter: c <= gs[k] <= d **N.B.: It is important to set the parameter constraints with care! **N.B.: -sconstr and -nconstr options must appear AFTER -signal and -noise on the command line -nconstr k c d constraints for kth noise parameter: c+b[k] <= gn[k] <= d+b[k] [-nabs] use absolute constraints for noise parameters: c <= gn[k] <= d [default=relative, as above] [-nrand n] n = number of random test points [default=19999] [-nbest b] b = use b best test points to start [default=9] [-rmsmin r] r = minimum rms error to reject reduced model [-fdisp fval] display (to screen) results for those voxels whose f-statistic is > fval [default=999.0] [-progress ival] display (to screen) results for those voxels every ival number of voxels [-voxel_count] display (to screen) the current voxel index --- These options choose the least-square minimization algorithm --- [-SIMPLEX] use Nelder-Mead simplex method [default] [-POWELL] use Powell's NEWUOA method instead of the Nelder-Mead simplex method to find the nonlinear least-squares solution [slower; usually more accurate, but not always!] [-BOTH] use both Powell's and Nelder-Mead method [slowest, but should be most accurate] --- These options generate individual AFNI 2 sub-brick datasets --- --- [All these options must be AFTER options -signal and -noise]--- [-freg fname] perform f-test for significance of the regression; output 'fift' is written to prefix filename fname [-frsqr fname] calculate R^2 (coef. of multiple determination); store along with f-test for regression; output 'fift' is written to prefix filename fname [-fsmax fname] estimate signed maximum of signal; store along with f-test for regression; output 'fift' is written to prefix filename fname [-ftmax fname] estimate time of signed maximum; store along with f-test for regression; output 'fift' is written to prefix filename fname [-fpsmax fname] calculate (signed) maximum percentage change of signal from baseline; output 'fift' is written to prefix filename fname [-farea fname] calculate area between signal and baseline; store with f-test for regression; output 'fift' is written to prefix filename fname [-fparea fname] percentage area of signal relative to baseline; store with f-test for regression; output 'fift' is written to prefix filename fname [-fscoef k fname] estimate kth signal parameter gs[k]; store along with f-test for regression; output 'fift' is written to prefix filename fname [-fncoef k fname] estimate kth noise parameter gn[k]; store along with f-test for regression; output 'fift' is written to prefix filename fname [-tscoef k fname] perform t-test for significance of the kth signal parameter gs[k]; output 'fitt' is written to prefix filename fname [-tncoef k fname] perform t-test for significance of the kth noise parameter gn[k]; output 'fitt' is written to prefix filename fname --- These options generate one AFNI 'bucket' type dataset --- [-bucket n prefixname] create one AFNI 'bucket' dataset containing n sub-bricks; n=0 creates default output; output 'bucket' is written to prefixname The mth sub-brick will contain: [-brick m scoef k label] kth signal parameter regression coefficient [-brick m ncoef k label] kth noise parameter regression coefficient [-brick m tmax label] time at max. abs. value of signal [-brick m smax label] signed max. value of signal [-brick m psmax label] signed max. value of signal as percent above baseline level [-brick m area label] area between signal and baseline [-brick m parea label] signed area between signal and baseline as percent of baseline area [-brick m tscoef k label] t-stat for kth signal parameter coefficient [-brick m tncoef k label] t-stat for kth noise parameter coefficient [-brick m resid label] std. dev. of the full model fit residuals [-brick m rsqr label] R^2 (coefficient of multiple determination) [-brick m fstat label] F-stat for significance of the regression [-noFDR] Don't write the FDR (q vs. threshold) curves into the output dataset. (Same as 'setenv AFNI_AUTOMATIC_FDR NO') --- These options write time series fit for --- --- each voxel to an AFNI 3d+time dataset --- [-sfit fname] fname = prefix for output 3d+time signal model fit [-snfit fname] fname = prefix for output 3d+time signal+noise fit -jobs J Run the program with 'J' jobs (sub-processes). On a multi-CPU machine, this can speed the program up considerably. On a single CPU machine, using this option is silly. J should be a number from 1 up to the number of CPU sharing memory on the system. J=1 is normal (single process) operation. The maximum allowed value of J is 32. * For more information on parallelizing, see https://sscc.nimh.nih.gov/afni/doc/misc/afni_parallelize/index_html/view * Use -mask to get more speed; cf. 3dAutomask. ---------------------------------------------------------------------- Signal Models (see the appropriate model_*.c file for exact details) : Null : No Signal (no parameters) see model_null.c SineWave_AP : Sinusoidal Response (amplitude, phase) see model_sinewave_ap.c SquareWave_AP : Square Wave Response (amplitude, phase) see model_squarewave_ap.c TrnglWave_AP : Triangular Wave Response (amplitude, phase) see model_trnglwave_ap.c SineWave_APF : Sinusoidal Wave Response (amplitude, phase, frequency) see model_sinewave_apf.c SquareWave_APF : Sinusoidal Wave Response (amplitude, phase, frequency) see model_squarewave_apf.c TrnglWave_APF : Sinusoidal Wave Response (amplitude, phase, frequency) see model_trnglwave_apf.c Exp : Exponential Function (a,b): a * exp(b * t) see model_exp.c DiffExp : Differential-Exponential Drug Response (t0, k, alpha1, alpha2) see model_diffexp.c GammaVar : Gamma-Variate Function Drug Response (t0, k, r, b) see model_gammavar.c Beta : Beta Distribution Model (t0, tf, k, alpha, beta) see model_beta.c * The following convolved functions are generally convolved with the time series in AFNI_CONVMODEL_REF, allowing one to specify multiple event onsets, varying durations and varying response magnitudes. ConvGamma : Gamma Vairate Response Model (t0, amp, r, b) see model_convgamma.c ConvGamma2a : Gamma Convolution with 2 Input Time Series (t0, r, b) see model_convgamma2a.c ConvDiffGam : Difference of 2 Gamma Variates (A0, T0, E0, D0, A1, T1, E1, D1) see model_conv_diffgamma.c for help : setenv AFNI_MODEL_HELP_CONVDIFFGAM YES 3dNLfim -signal ConvDiffGam demri_3 : Dynamic (contrast) Enhanced MRI (K_trans, Ve, k_ep) see model_demri_3.c for help : setenv AFNI_MODEL_HELP_DEMRI_3 YES 3dNLfim -signal demri_3 ADC : Diffusion Signal Model (So, D) see model_diffusion.c michaelis_menton : Michaelis/Menten Concentration Model (v, vmax, k12, k21, mag) see model_michaelis_menton.c Expr2 : generic (3dcalc-like) expression with exactly 2 'free' parameters and using symbol 't' as the time variable; see model_expr2.c for details. ConvCosine4 : 4-piece Cosine Convolution Model (A, C1, C2, M1, M2, M3, M4) see model_conv_cosine4.c for help : setenv AFNI_MODEL_HELP_CONV_COSINE4 YES 3dNLfim -signal ConvCosine4 Conv_PRF : 4-param Population Receptive Field Model (A, X, Y, sigma) see model_conv_PRF.c for help : setenv AFNI_MODEL_HELP_CONV_PRF YES 3dNLfim -signal bunnies Conv_PRF_6 : 6-param Population Receptive Field Model (A, X, Y, sigma, sigrat, theta) see model_conv_PRF_6.c for help : setenv AFNI_MODEL_HELP_CONV_PRF_6 YES 3dNLfim -signal bunnies Conv_PRF_DOG : 6-param 'Difference of Gaussians' PRF Model (as Conv_PRF, but with second A and sigma) (A, X, Y, sig, A2, sig2) see model_conv_PRF_DOG.c for help : setenv AFNI_MODEL_HELP_CONV_PRF_DOG YES 3dNLfim -signal bunnies ---------------------------------------- Noise Models (see the appropriate model_*.c file for exact details) : Zero : Zero Noise Model (no parameters) see model_zero.c Constant : Constant Noise Model (constant) see model_constant.c Linear : Linear Noise Model (constant, linear) see model_linear.c Linear+Ort : Linear+Ort Noise Model (constant, linear, Ort) see model_linplusort.c Quadratic : Quadratic Noise Model (constant, linear, quadratic) see model_quadratic.c ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNormalityTest
Program: 3dNormalityTest * This program tests the input values at each voxel for normality, using the Anderson-Darling method: http://en.wikipedia.org/wiki/Anderson-Darling_test * Each voxel must have at least 5 values (sub-bricks). * The resulting dataset has the Anderson-Darling statistic converted to an exponentially distributed variable, so it can be thresholded with the AFNI slider and display a nominal p-value below. If you want the A-D statistic un-converted, use the '-noexp' option. * Conversion of the A-D statistic to a p-value is done via simulation of the null distribution. OPTIONS: -------- -input dset = Specifies the input dataset. Alternatively, the input dataset can be given as the last argument on the command line, after all other options. -prefix ppp = Specifies the name for the output dataset. -noexp = Do not convert the A-D statistic to an exponentially distributed value -- just leave the raw A-D score in the output dataset. -pval = Output the results as a pure (estimated) p-value. EXAMPLES: --------- (1) Simulate a 2D square dataset with the values being normal on one edge and exponentially distributed on the other, and mixed in-between. 3dUndump -dimen 101 101 1 -prefix UUU 3dcalc -datum float -a UUU+orig -b '1D: 0 0 0 0 0 0 0 0 0 0' -prefix NNN \ -expr 'i*gran(0,1.4)+(100-i)*eran(4)' rm -f UUU+orig.* 3dNormalityTest -prefix Ntest -input NNN+orig afni -com 'OPEN_WINDOW axialimage' Ntest+orig In the above script, the UUU+orig dataset is created just to provide a spatial template for 3dcalc. The '1D: 0 ... 0' input to 3dcalc is a time template to create a dataset with 10 time points. The values are random deviates, ranging from pure Gaussian where i=100 to pure exponential at i=0. (2) Simulate a single logistic random variable into a 1D file and compute the A-D nominal p-value: 1deval -num 200 -expr 'lran(2)' > logg.1D 3dNormalityTest -input logg.1D\' -prefix stdout: -pval Note the necessity to transpose the logg.1D file (with the \' operator), since 3D programs interpret each 1D file row as a voxel time series. ++ March 2012 -- by The Ghost of Carl Friedrich Gauss ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNotes
Program: 3dNotes Author: T. Ross (c)1999 Medical College of Wisconsin 3dNotes - a program to add, delete and show notes for AFNI datasets. ----------------------------------------------------------------------- Usage: 3dNotes [-a "string"] [-h "string"][-d num] [-help] dataset Examples: 3dNotes -a "Subject sneezed in scanner, Aug 13 2004" elvis+orig 3dNotes -h "Subject likes fried PB & banana sandwiches" elvis+orig 3dNotes -HH "Subject has left the building" elvis+orig 3dNotes -d 2 -h "Subject sick of PB'n'banana sandwiches" elvis+orig ----------------------------------------------------------------------- Explanation of Options: ---------------------- dataset : AFNI compatible dataset [required]. -a "str" : Add the string "str" to the list of notes. Note that you can use the standard C escape codes, \n for newline \t for tab, etc. -h "str" : Append the string "str" to the dataset's history. This can only appear once on the command line. As this is added to the history, it cannot easily be deleted. But, history is propagated to the children of this dataset. -HH "str" : Replace any existing history note with "str". This line cannot be used with '-h'. -d num : deletes note number num. -ses : Print to stdout the expanded notes. -help : Displays this screen. The default action, with no options, is to display the notes for the dataset. If there are options, all deletions occur first and essentially simultaneously. Then, notes are added in the order listed on the command line. If you do something like -d 10 -d 10, it will delete both notes 10 and 11. Don't do that. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dnvals
Usage: 3dnvals [-all] [-verbose] dataset [dataset dataset ...] * Prints (to stdout) the number of sub-bricks in a 3D dataset. * If -all is specified, prints out all 4 dimensions: Nx, Ny, Nz, Nvals * If -verbose is used then the header name of the dataset is printed first. * The function of this simple program is to help in scripting. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNwarpAdjust
Usage: 3dNwarpAdjust [options] This program takes as input a bunch of 3D warps, averages them, and computes the inverse of this average warp. It then composes each input warp with this inverse average to 'adjust' the set of warps. Optionally, it can also read in a set of 1-brick datasets corresponding to the input warps, and warp each of them, and average those. Input warps: Wi(x) for i=1..N Average warp: Wbar(x) = mean of the displacements in Wi(x) Inverse average: Wbin(x) = inverse of Wbar(x) Adjusted warps: Ai(x) = Wi(Wbin(x)) Source datasets: Di(x) for i=1..N Output mean dataset: average of Di(Ai(x)) The logic behind this arcane necromancy is the following sophistry: We use 3dQwarp to warp each Di(x) to match a template T(x), giving warp Wi(x) such that Di(Wi(x)) matches T(x). Now we want to average these warped Di datasets to create a new template; say B(x) = average of Di(Wi(x)) But the warps might be biased (e.g., have net shrinkage of the volumes). So we compute the average warp Wbar(x), and its inverse Wbin(x), and then instead we want to use as the new template B(Wbin(x)), which will 'put back' each x to a bias-corrected location. So then we have B(Wbin(x)) = average of Di(Wi(Wbin(x))) which is where the 'adjusted warp' Ai(x) = Wi(Wbin(x)) comes from. All these calculations could be done with other programs and a script, but the goal of this program is to make them faster and simpler to combine. It is intended to be used in an incremental template-building script, and probably has no other utility (cf. the script @toMNI_Qwarpar). OPTIONS: -------- -nwarp w1 w2 ... = List of input 3D warp datasets (at least 5). The list ends when a command line argument starts with a '-' or the command line itself ends. * This 'option' is REQUIRED! -->>** Each input warp is adjusted, and the altered warp over-writes the input dataset. (Therefore, there is no reason to run 3dNwarpAdjust twice over the same collection of warp datasets!) * These input warps do not have to be defined on exactly the same grids, but the grids must be 'conformant' -- that is, they have to have the the same orientation and grid spacings. Warps will be extended to match the minimum containing 3D rectangular grid, as needed. -source d1 d2 ... = List of input 3D datasets to be warped by the adjusted warp datasets. There must be exactly as many of these datasets as there are input warps. * This option is NOT required. * These datasets will NOT be altered by this program. * These datasets DO have to be on the same 3D grid (so they can be averaged after warping). -prefix ppp = Use 'ppp' for the prefix of the output mean dataset. (Only needed if the '-source' option is also given.) The output dataset will be on the common grid shared by the source datasets. ========================================================================= * This binary version of 3dNwarpAdjust is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNwarpApply
Usage: 3dNwarpApply [options] Program to apply a nonlinear 3D warp saved from 3dQwarp (or 3dNwarpCat, etc.) to a 3D dataset, to produce a warped version of the source dataset. The '-nwarp' and '-source' options are MANDATORY. For both of these options, as well as '-prefix', the input arguments after the option name are applied up until an argument starts with the '-' character, or until the arguments run out. This program has been heavily modified [01 Dec 2014], including the following major improvements: (1) Allow catenation of warps with different grid spacings -- the functions that deal with the '-nwarp' option will automatically deal with the grids. (2) Allow input of affine warps with multiple time points, so that 3D+time datasets can be warped with a time dependent '-nwarp' list. (3) Allow input of multiple source datasets, so that several datasets can be warped the same way at once. This operation is more efficient than running 3dNwarpApply several times, since the auto-regridding and auto-catenation in '-nwarp' will only have to be done once. * Specification of the output dataset names can be done via multiple arguments to the '-prefix' option, or via the new '-suffix' option. New Feature [28 Mar 2018]: (4) If a source dataset contains complex numbers, then 3dNwarpApply will warp the real and imaginary parts separately, combine them, and produce a complex-valued dataset as output. * Previously, the program would have warped the magnitude of the input dataset and written out a float-valued dataset. * No special option is needed to warp complex-valued datasets. * If you WANT to warp the magnitude of a complex-valued dataset, you will have to convert the dataset to a float dataset via 3dcalc, then use 3dNwarpApply on THAT dataset instead. * You cannot use option '-short' with complex-valued source datasets! More precisely, you can try to use this option, but it will be ignored. * This ability is added for those of you who deal with complex-valued EPI datasets (I'm looking at YOU, O International Man of Mystery). OPTIONS: -------- -nwarp www = 'www' is the name of the 3D warp dataset (this is a mandatory option!) ++ Multiple warps can be catenated here. -->> Please see the lengthier discussion below on this feature! -->> Also see the help for 3dNwarpCat for some more information on the formats allowed for inputting warp fields; for example, warping in one direction only (e.g., 'AP') is possible. ++ NOTE WELL: The interpretation of this option has changed somewhat, as of 01 Dec 2014. In particular, this option is generalized from the version in other programs, including 3dNwarpCat, 3dNwarpFuncs, and 3dNwarpXYZ. The major change is that multi-line matrix files are allowed to be included in the 'www' mixture, so that the nonlinear warp being calculated can be time-dependent. In addition, the warps supplied need not all be on the same 3D grid -- this ability lets you catenate a warp defined on the EPI data grid with a warp defined on the structural data grid (e.g.). -iwarp = After the warp specified in '-nwarp' is computed, invert it. If the input warp would take a dataset from space A to B, then the inverted warp will do the reverse. ++ The combination "-iwarp -nwarp 'A B C'" is equivalent to "-nwarp 'INV(C) INV(B) INV(A)'" -- that is, inverting each warp/matrix in the list *and* reversing their order. ++ The '-iwarp' option is provided for convenience, and may prove to be very slow for time-dependent '-nwarp' inputs. -affter aaa = *** THIS OPTION IS NO LONGER AVAILABLE *** See the discussion of the new '-nwarp' option above to see how to do include time-dependent matrix transformations in this program. -source sss = 'sss' is the name of the source dataset. ++ That is, the dataset to be warped. ++ Multiple datasets can be supplied here; they MUST all be defined over the same 3D grid. -->>** You can no longer simply supply the source dataset as the last argument on the command line. -master mmm = 'mmm is the name of the master dataset. ++ Which defines the output grid. ++ If '-master' is not used, then output grid is the same as the source dataset grid. ++ It is often the case that it makes more sense to use the '-nwarp' dataset as the master, since that is the grid on which the transformation is defined, and is (usually) the grid to which the transformation 'pulls' the source data. ++ You can use '-master WARP' or '-master NWARP' for this purpose -- but ONLY if all the warps listed in the '-nwarp' option have the same 3D grid structure. ++ In particular, if the transformation includes a long-distance translation, then the source dataset grid may not have a lot of overlap with the source dataset after it is transformed -- in this case, you really want to use this '-master' option -- or you will end up cutting of a lot of the output dataset since it will not overlap with the source dataset. -newgrid dd = 'dd' is the new grid spacing (cubical voxels, in mm) *OR = ++ This lets you resize the master dataset grid spacing. -dxyz dd = for example, to bring EPI data to a 1 mm template, but at a coarser resolution, use '-dxyz 2'. ++ The same grid orientation as the source is used if the '-master' option is not given. -interp iii = 'iii' is the interpolation mode ++ Default interpolation mode is 'wsinc5' (slowest, bestest) ++ Available modes are the same as in 3dAllineate: NN linear cubic quintic wsinc5 ++ The same interpolation mode is used for the warp itself (if needed) and then for the data being warped. ++ The warp will be interpolated if the output dataset is not on the same 3D grid as the warp itself, or if a warp expression is used in the '-nwarp' option. Otherwise, it won't need to be interpolated. -ainterp jjj = This option lets you specify a different interpolation mode for the data than might be used for the warp. ++ In particular, '-ainterp NN' would be most logical for atlas datasets, where the data values being mapped are integer labels. -prefix ppp = 'ppp' is the name of the new output dataset ++ If more than 1 source dataset is supplied, then you should supply more than one prefix. Otherwise, the program will invent prefixes for each output, by attaching the suffix '_Nwarp' to each source dataset's prefix. -suffix sss = If the program generates prefixes, you can change the default '_Nwarp' suffix to whatever you want (within reason) by this option. ++ His Holiness Emperor Zhark defines 'within reason', of course. ++ By using '-suffix' and NOT using '-prefix', the program will generate prefix names for all output datasets in a systematic way -- this might be useful for some people. ++ Note that only ONE suffix can be supplied even if many source datasets are input -- unlike the case with '-prefix'. -short = Write output dataset using 16-bit short integers, rather than the usual 32-bit floats. ++ Intermediate values are rounded to the nearest integer. No scaling is performed. ++ This option is intended for use with '-ainterp' and for source datasets that contain integral values. ++ If the source dataset is complex-valued, this option will be ignored. -wprefix wp = If this option is used, then every warp generated in the process of application will be saved to a 3D dataset with prefix 'wp_XXXX', where XXXX is the index of the sub-brick being created. For example, '-wprefix Zork.nii' will create datasets with names 'Zork_0000.nii', et cetera. -quiet = Don't be verbose :-( -verb = Be extra verbose :-) SPECIFYING THE NONLINEAR WARP IN '-nwarp' [If you are catenating warps, read this carefully!] --------------------------------------------------- A single nonlinear warp (usually created by 3dQwarp) is an AFNI or NIfTI-1 dataset with 3 sub-bricks, holding the 3D displacements of each voxel. (All coordinates and displacements are expressed in DICOM order.) The '-nwarp' option is used to specify the nonlinear transformation used to create the output dataset from the source dataset. For many purposes, the only input needed here is the name of a single dataset holding the warp to be used. However, the '-nwarp' option also allows the catenation of a sequence of spatial transformations (in short, 'warps') that will be combined before being applied to the source dataset. Each warp is either a nonlinear warp dataset or a matrix warp (a linear transformation of space). A single affine (or linear) warp is a set of 12 numbers, defining a 3x4 matrix a11 a12 a13 a14 a21 a22 a23 a24 a31 a32 a33 a34 A matrix is stored on a single line, in a file with the extension '.1D' or '.txt', in this order a11 a12 a13 a14 a21 a22 a23 a24 a31 a32 a33 a34 For example, the identity matrix is given by 1 0 0 0 0 1 0 0 0 0 1 0 This format is output by the '-1Dmatrix_save' options in 3dvolreg and 3dAllineate, for example. If the argument 'www' following '-nwarp' is made up of more than one warp filename, separated by blanks, then the nonlinear warp to be used is composed on the fly as needed to transform the source dataset. For example, -nwarp 'AA_WARP.nii BB.aff12.1D CC_WARP.nii' specifies 3 spatial transformations, call them A(x), B(x), and C(x) -- where B(x) is just the 3-vector x multiplied into the matrix in the BB.aff12.1D file. The resulting nonlinear warp function N(x) is obtained by applying these transformations in the order given, A(x) first: N(x) = C( B( A(x) ) ) That is, the first warp A is applied to the output grid coordinate x, then the second warp B to that results, then the third warp C. The output coordinate y = C(B(A(x))) is the coordinate in the source dataset at which the output value will be interpolated (for the voxel at coordinate x). The Proper Order of Catenated Warps: .................................... To determine the correct order in which to input the warps, it is necessary to understand what a warp of the source dataset actually computes. Call the source image S(x) = (scalar) value of source image at voxel location x. For each x in the output grid, the warped result is S(N(x)) -- that is, N(x) tells where each output location x must be warped to in order to find the corresponding value of the source S. N(x) does *NOT* tell to where an x in the source image must be moved to in the output space -- which is what you might think if you mentally prioritize the idea of 'warping the source image' or 'pushing the source image' -- DO NOT THINK THIS WAY! It is better to think of N(x) as reaching out from x in the output space to a location in the source space and then the program will interpolate from the discrete source space grid at that location -- which is unlikely to be exactly on a grid node. Another way to think of this is that the warp 'pulls' the source image back to the coordinate system on which the warp is defined. Now suppose the sequence of operations on an EPI dataset is (1) Nonlinearly unwarp the dataset via warp AA_WARP.nii (perhaps from 3dQwarp -plusminus). (2) Perform linear volume registration on the result from (1) (with program 3dvolreg) to get affine matrix file BB.aff12.1D -- which will have 1 line per time point in the EPI dataset. (3) Linearly register the structural volume to the EPI dataset (via script align_epi_anat.py). Note that this step transforms the structural volume to match the EPI, not the EPI to match the structural volume, so this step does not affect the chain of transformations being applied to the EPI dataset. (4) Nonlinearly warp the structural image from (3) to MNI space via warp CC_WARP.nii (generated by 3dQwarp). Finally, the goal is to take the original EPI time series dataset, and warp it directly to MNI space, including the time series registration for each sub-brick in the dataset, with only one interplation being used -- rather than the 3 interpolations that would come by serially implementing steps (1), (2), and (4). This one-big-step transformation can be done with 3dNwarpApply using the '-nwarp' option: -nwarp 'CC_WARP.nii BB.aff12.1D AA_WARP.nii' that is, N(x) = A( B( C(x) ) ) -- the opposite order to the sample above, and with the transformations occurring in the opposite order to the sequence in which they were calculated. The reason for this apparent backwardness is that the 'x' being transformed is on the output grid -- in this case, in MNI-template space. So the warp C(x) transforms such an output grid 'x' to the EPI-aligned structural space. The warp B(x) then transforms THAT coordinate from aligned spaced back to the rotated head position of the subject. And the warp A(x) transforms THAT coordinate back to the original grid that had to be unwarped (e.g., from susceptibility and/or eddy current artifacts). Also note that in step (2), the matrix file BB.aff12.1D has one line for each time point. When transforming a source dataset, the i-th time point will be transformed by the warp computed using the i-th line from any multi-line matrix file in the '-nwarp' specification. (If there are more dataset time points than matrix lines, then the last line will be reused.) In this way, 3dNwarpApply can be used to carry out time-dependent warping of time-dependent datasets, provided that the time-dependence in the warp only occurs in the affine (matrix) parts of the transformation. Note that the now-obsolete option '-affter' is subsumed into the new way that '-nwarp' works. Formerly, the only time-dependent matrix had to be specified as being at the end of the warp chain, and was given via the '-affter' option. Now, a time-dependent matrix (or more than one) can appear anywhere in the warp chain, so there is no need for a special option. If you DID use '-affter', you will have to alter your script simply by putting the final matrix filename at the end of the '-nwarp' chain. (If this seems too hard, please consider another line of work.) The other 3dNwarp* programs that take the '-nwarp' option operate similarly, but do NOT allow time-dependent matrix files. Those programs are built to operate with one nonlinear warp, so allowing a time-dependent warp doesn't make sense for them. NOTE: If a matrix is NOT time-dependent (just a single set of 12 numbers), it can be input in the .Xat.1D format of 3 rows, each with 4 values: a11 a12 a13 a14 } 1 0 0 0 a21 a22 a23 a24 } e.g, identity matrix = 0 1 0 0 a31 a32 a33 a34 } 0 0 1 0 This option is just for convenience. Remember that the coordinates are DICOM order, and if your matrix comes from Some other PrograM or from a Fine Software Library, you probably have to change some signs in the matrix to get things to work correctly. RANDOM NOTES: ------------- * At present, this program doesn't work with 2D warps, only with 3D. (That is, each warp dataset must have 3 sub-bricks.) * At present, the output dataset is stored in float format, no matter what absurd data format the input dataset uses (but cf. the '-short' option). * As described above, 3dNwarpApply allows you to catenate warps directly on the command line, as if you used 3dNwarpCat before running 3dNwarpApply. For example: ++ You have aligned dataset Fred+orig to MNI-affine space using @auto_tlrc, giving matrix file Fred.Xaff12.1D ++ Then you further aligned from MNI-affine to MNI-qwarp via 3dQwarp, giving warp dataset Fred_WARP+tlrc ++ You can combine the transformations and interpolate Fred+orig directly to MNI-qwarp space using a command like 3dNwarpApply -prefix Fred_final \ -source Fred+orig \ -master NWARP \ -nwarp 'Fred_WARP+tlrc Fred.Xaff12.1D' Note the warps to be catenated are enclosed in quotes to make a single input argument passed to the program. The processing used for this purpose is the same as in 3dNwarpCat -- see the help output for that program for a little more information. ++ When you specify a nonlinear warp dataset, you can use the 'SQRT()' and 'INV()' and 'INVSQRT()' operators, as well as the various 1D-to-3D displacement prefixes ('AP:' 'RL:' 'IS:' 'VEC:', as well as 'FAC:') -- for example, the following is a legal (and even useful) definition of a warp herein: 'SQRT(AP:epi_BU_yWARP+orig)' where the 'AP:' transforms the y-displacements in epi_BU_ywarp+orig to a full 3D warp (with x- and z-displacments set to zero), then calculates the square root of that warp, then applies the result to some input dataset. + This is a real example, where the y-displacement-only warp is computed between blip-up and blip-down EPI datasets, and then the SQRT warp is applied to warp them into the 'intermediate location' which should be better aligned with the subject's anatomical datasets. -->+ However: see also the '-plusminus' option for 3dQwarp for another way to reach the same goal, as well as the unWarpEPI.py script. + See the output of 3dNwarpCat -help for a little more information on the 1D-to-3D warp prefixes ('AP:' 'RL:' 'IS:' 'VEC:'). ++ You can scale the displacements in a 3D warp file via the 'FAC:' prefix, as in FAC:0.6,0.4,-0.2:fred_WARP.nii which will scale the x-displacements by 0.6, the y-displacements by 0.4, and the z-displacments by -0.2. + So if you need to reverse the sign of x- and y-displacments, since in AFNI +x=Left and +y=Posterior while another package uses +x=Right and +y=Anterior, you could use 'FAC:-1,-1,1:Warpdatasetname' to apply a warp from that other software package. ++ You can also use 'IDENT(dataset)' to define a "nonlinear" 3D warp whose grid is defined by the dataset header -- nothing else from the dataset will be used. This warp will be filled with all zero displacements, which represents the identity warp. The purpose of such an object is to let you apply a pure affine warp -- since this program requires a '-nwarp' option, you can use -nwarp 'IDENT(dataset)' to define the 3D grid for the 'nonlinear' 3D warp and then catenate the affine warp. * PLEASE note that if you use the '-allineate' option in 3dQwarp, then the affine warp is already included in the output nonlinear warp from 3dQwarp, and so it does NOT need to be applied again in 3dNwarpApply! This mistake has been made in the past, and the results were not good. * When using '-allineate' in 3dQwarp, and when there is a large coordinate shift between the base and source datasets, then the _WARP dataset output by 3dQwarp will cover a huge grid to encompass both the base and source. In turn, this can cause 3dNwarpApply to need a lot of memory when it applies that warp. ++ Some changes were made [Jan 2019] to reduce the size of this problem, but it still exists. ++ We have seen this most often in source datasets which have the (0,0,0) point not in the middle of the volume, but at a corner of the volume. Since template datasets (such as MNI152_2009_template_SSW.nii.gz) have (0,0,0) inside the brain, a dataset with (0,0,0) at a corner of the 3D volume will need a giant coordinate shift to match the template dataset. And in turn, the encompassing grid that overlaps the source and template (base) datasets will be huge. ++ The simplest way to fix this problem is to do something like @Align_Centers -base MNI152_2009_template_SSW.nii.gz -dset Fred.nii which will produce dataset Fred_shft.nii, that will have its grid center approximately lined up with the template (base) dataset. And from then on, use Fred_shft.nii as your input dataset. ========================================================================= * This binary version of 3dNwarpApply is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNwarpCalc
******************************************************************* Program 3dNwarpCalc has been retired, and is no longer available :( *******************************************************************

AFNI program: 3dNwarpCat
Usage: 3dNwarpCat [options] warp1 warp2 ... ------ * This program catenates (composes) 3D warps defined on a grid, OR via a matrix. ++ All transformations are from DICOM xyz (in mm) to DICOM xyz. * Matrix warps are in files that end in '.1D' or in '.txt'. A matrix warp file should have 12 numbers in it, as output (for example), by '3dAllineate -1Dmatrix_save'. ++ The matrix (affine) warp can have either 12 numbers on one row, or be in the 3x4 format. ++ The 12-numbers-on-one-row format is preferred, and is the format output by the '-1Dmatrix_save' option in 3dvolreg and 3dAllineate. ++ The matrix warp is a transformation of coordinates, not voxels, and its use presumes the correctness of the voxel-to-coordinate transformation stored in the header of the datasets involved. * Nonlinear warps are in dataset files (AFNI .HEAD/.BRIK or NIfTI .nii) with 3 sub-bricks giving the DICOM order xyz grid displacements in mm. ++ Note that it is not required that the xyz order of voxel storage be in DICOM order, just that the displacements be in DICOM order (and sign). ++ However, it is important that the warp dataset coordinate order be properly specified in the dataset header, since warps are applied based on coordinates, not on voxels. ++ Also note again that displacements are in mm, NOT in voxel. ++ You can 'edit' the warp on the command line by using the 'FAC:' scaling prefix, described later. This input editing could be used to change the sign of the xyz displacements, if needed. * If all the input warps are matrices, then the output is a matrix and will be written to the file 'prefix.aff12.1D'. ++ Unless the prefix already contains the string '.1D', in which case the filename is just the prefix. ++ If 'prefix' is just 'stdout', then the output matrix is written to standard output. ++ In any of these cases, the output format is 12 numbers in one row. * If any of the input warps are datasets, they must all be defined on the same 3D grid! ++ And of course, then the output will be a dataset on the same grid. ++ However, you can expand the grid using the '-expad' option. * The order of operations in the final (output) warp is, for the case of 3 input warps: OUTPUT(x) = warp3( warp2( warp1(x) ) ) That is, warp1 is applied first, then warp2, et cetera. The 3D x coordinates are taken from each grid location in the first dataset defined on a grid. * For example, if you aligned a dataset to a template with @auto_tlrc, then further refined the alignment with 3dQwarp, you would do something like this: warp1 is the output of 3dQwarp warp2 is the matrix from @auto_tlrc This is the proper order, since the desired warp takes template xyz to original dataset xyz, and we have 3dQwarp warp: takes template xyz to affinely aligned xyz, and @auto_tlrc matrix: takes affinely aligned xyz to original xyz 3dNwarpCat -prefix Fred_total_WARP -warp1 Fred_WARP+tlrc.HEAD -warp2 Fred.Xat.1D The dataset Fred_total_WARP+tlrc.HEAD could then be used to transform original datasets directly to the final template space, as in 3dNwarpApply -prefix Wilma_warped \ -nwarp Fred_total_WARP+tlrc \ -source Wilma+orig \ -master Fred_total_WARP+tlrc * If you wish to invert a warp before it is used here, supply its input name in the form of INV(warpfilename) To produce the inverse of the warp in the example above: 3dNwarpCat -prefix Fred_total_WARPINV \ -warp2 'INV(Fred_WARP+tlrc.HEAD)' \ -warp1 'INV(Fred.Xat.1D)' Note the order of the warps is reversed, in addition to the use of 'INV()'. * The final warp may also be inverted simply by adding the '-iwarp' option, as in 3dNwarpCat -prefix Fred_total_WARPINV -iwarp -warp1 Fred_WARP+tlrc.HEAD -warp2 Fred.Xat.1D * Other functions you can apply to modify a 3D dataset warp are: SQRT(datasetname) to get the square root of a warp SQRTINV(datasetname) to get the inverse square root of a warp However, you can't do more complex expressions, such as 'SQRT(SQRT(warp))'. If you think you need something so rococo, use 3dNwarpCalc. Or think again. * You can also manufacture a 3D warp from a 1-brick dataset with displacements in a single direction. For example: AP:0.44:disp+tlrc.HEAD (note there are no blanks here!) means to take the 1-brick dataset disp+tlrc.HEAD, scale the values inside by 0.44, then load them into the y-direction displacements of a 3-brick 3D warp, and fill the other 2 directions with zeros. The prefixes you can use here for the 1-brick to 3-brick displacement trick are RL: for x-displacements (Right-to-Left) AP: for y-displacements (Anterior-to-Posterior) IS: for z-displacements (Inferior-to-Superior) VEC:a,b,c: for displacements in the vector direction (a,b,c), which vector will be scaled to be unit length. Following the prefix's colon, you can put in a scale factor followed by another colon (as in '0.44:' in the example above). Then the name of the dataset with the 1D displacements follows. * You might reasonably ask of what possible value is this peculiar format? This was implemented to use Bz fieldmaps for correction of EPI datasets, which are distorted only along the phase-encoding direction. This format for specifying the input dataset (the fieldmap) is built to make the scripting a little easier. Its principal use is in the program 3dNwarpApply. * You can scale the displacements in a 3D warp file via the 'FAC:' prefix, as in FAC:0.6,0.4,-0.2:fred_WARP.nii which will scale the x-displacements by 0.6, the y-displacements by 0.4, and the z-displacments by -0.2. * Finally, you can input a warp catenation string directly as in the '-nwarp' option of 3dNwarpApply, as in 3dNwarpCat -prefix Fred_total_WARP 'Fred_WARP+tlrc.HEAD Fred.Xat.1D' OPTIONS ------- -interp iii == 'iii' is the interpolation mode: ++ Modes allowed are a subset of those in 3dAllineate: linear quintic wsinc5 ++ The default interpolation mode is 'wsinc5'. ++ 'linear' is much faster but less accurate. ++ 'quintic' is between 'linear' and 'wsinc5', in both accuracy and speed. -verb == print (to stderr) various fun messages along the road. -prefix ppp == prefix name for the output dataset that holds the warp. -space sss == attach string 'sss' to the output dataset as its atlas space marker. -warp1 ww1 == alternative way to specify warp#1 -warp2 ww2 == alternative way to specify warp#2 (etc.) ++ If you use any '-warpX' option for X=1..99, then any addition warps specified after all command line options appear AFTER these enumerated warps. That is, '-warp1 A+tlrc -warp2 B+tlrc C+tlrc' is like using '-warp3 C+tlrc'. ++ At most 99 warps can be used. If you need more, PLEASE back away from the computer slowly, and get professional counseling. -iwarp == Invert the final warp before output. -expad PP == Pad the nonlinear warps by 'PP' voxels in all directions. The warp displacements are extended by linear extrapolation from the faces of the input grid. AUTHOR -- RWCox -- March 2013 ========================================================================= * This binary version of 3dNwarpCat is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNwarpFuncs
Usage: 3dNwarpFuncs [options] This program reads in a nonlinear 3D warp (from 3dQwarp, etc.) and computes some functions of the displacements. See the OPTIONS below for information on what can be computed. The NOTES sections describes the formulae of the functions that are available. -------- OPTIONS: -------- -nwarp www = 'www' is the name of the 3D warp dataset (this is a mandatory option!) ++ This can be computed on the fly, as in 3dNwarpApply. -prefix ppp = 'ppp' is the name of the new output dataset -bulk = Compute the (fractional) bulk volume change. ++ e.g., Jacobian determinant minus 1. ++ see 'MORE...' (below) for interpreting the sign of '-bulk'. -shear = Compute the shear energy. -vorticity = Compute the vorticity enerty. -all = Compute all 3 of these fun fun functions. If none of '-bulk', '-shear', or '-vorticity' are given, then '-bulk' will be assumed. ------ NOTES: ------ Denote the displacement vector field (warp) by [ p(x,y,z) , q(x,y,z) , r(x,y,z) ] Define the Jacobian matrix by [ 1+dp/dx dp/dy dp/dz ] [ Jxx Jxy Jxz ] J = [ dq/dx 1+dq/dy dq/dz ] = [ Jyx Jyy Jyz ] [ dr/dx dr/dy 1+dr/dz ] [ Jzx Jzy Jzz ] * The '-bulk' output is the determinant of this matrix (det[J]), minus 1. * It measures the fractional amount of volume distortion. * Negative means the warped coordinates are shrunken (closer together) than the input coordinates. Also see the 'MORE...' section below. * The '-shear' output is the sum of squares of the J matrix elements -- which equals the sum of squares of its eigenvalues -- divided by det[J]^(2/3), then minus 3. * It measures the amount of shearing distortion (normalized by the amount of volume distortion). * The '-vorticity' output is the sum of squares of the skew part of the J matrix = [ Jxy-Jyx , Jxz-Jzx , Jyz-Jzy ], divided by det[J]^(2/3). * It measures the amount of twisting distortion (also normalized). * All 3 of these functions are dimensionless. * The penalty used in 3dQwarp is a combination of the bulk, shear, and vorticity functions. ------------------------------ MORE about interpreting -bulk: ------------------------------ If the warp N(x,y,z) is the '_WARP' output from 3dQwarp, then N(x,y,z) maps the base dataset (x,y,z) coordinates to the source dataset (x,y,z) coordinates. If the source dataset has to expand in size to match the base dataset, then going from base coordinates to source must be a shrinkage. Thus, negative '-bulk' in this '_WARP' dataset corresponds to expansion going from source to base. Conversely, in this situation, positive '-bulk' will show up in the '_WARPINV' dataset from 3dQwarp as that is the map from source (x,y,z) to base (x,y,z). The situation above happens a lot when using one of the MNI152 human brain templates as the base dataset. This family of datasets is larger than the average human brain, due to the averaging process used to define the first MNI152 template back in the 1990s. I have no easy interpretation handy for the '-shear' and '-vorticity' outputs, alas. They are computed as part of the penalty function used to control weirdness in the 3dQwarp optimization process. --------------------------- AUTHOR -- RWCox == @AFNIman --------------------------- ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dNwarpXYZ
Usage: 3dNwarpXYZ [options] -nwarp 'warp specification' XYZfile.1D > Output.1D Transforms the DICOM xyz coordinates in the input XYZfile.1D (3 columns) based on the '-nwarp' specification -- which is as in 3dNwarpApply (e.g., allows inversion, catenation, et cetera). If this warp is the _WARP output from 3dQwarp, then it takes XYZ values from the base dataset and transforms them to the corresponding source dataset location. To do the reverse operation -- to take an XYZ in the source dataset and find out where it goes to in the base dataset -- do one of these: * use the _WARPINV output from 3dQwarp instead of the _WARP output; * use the 'INV(dataset)' form for '-nwarp' (will be slow); * use the '-iwarp' option described below. The first 2 choices should be equivalent. The third choice will give slightly different results, since the method used for warp inversion for just a few discrete points is very different than the full warp inversion algorithm -- this difference is for speed. The mean Euclidean error between '-iwarp' and _WARPINV is about 0.006 mm in one test. The largest error (using 1000 random points) in this test was about 0.05 mm. About 95% of points had 0.015 mm error or less. For any 3D brain MRI purpose that Zhark can envision, this level of concordance should be adequately good-iful. ---------------------------------------------------------------- CLARIFICATION about the confusing forward and inverse warp issue ---------------------------------------------------------------- If the following is the correct command to take a source dataset to the place that you want it to go: 3dNwarpApply -nwarp 'SOME_WARP' -source DATASET -prefix JUNK then the next command is the one to take coordinates in the source dataset to the same place 3dNwarpXYZ -nwarp 'SOME_WARP' -iwarp XYZsource.1D > XYZwarped.1D For example, a command like the above has been used to warp (x,y,z) coordinates for ECOG sensors that were picked out manually on a CT volume. An AFNI nonlinear warp stores the displacements (in DICOM mm) from the base dataset grid to the source dataset grid. For computing the source dataset warped to the base dataset grid, these displacements are needed, so that for each grid point in the output (warped) dataset, the corresponding location in the source dataset can be found. That is, this 'forward' warp is good for finding where a given point in the base dataset maps to in the source dataset. However, for finding where a given point in the source dataset maps to in the base dataset, the 'inverse' warp is needed, which is why the '-iwarp' option was added to 3dNwarpXYZ. Zhark knows the above is confusing, and hopes that your distraction by this issue will aid him in his ruthless quest for Galactic Domination! (And for warm cranberry scones with fresh clotted cream.) ------------- OTHER OPTIONS (i.e., besides the mandatory '-nwarp') ------------- -iwarp = Compute the inverse warp for each input (x,y,z) triple. ++ As mentioned above, this program does NOT compute the inverse warp over the full grid (unlike the 'INV()' method and the '-iwarp' options to other 3dNwarp* programs), but uses a different method that is designed to be fast when applied to a relatively few input points. ++ The upshot is that using '-iwarp' here will give slightly different results than using 'INV()', but for any practical application the differences should be negligible. July 2014 - Zhark the Coordinated ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dOverlap
Usage: 3dOverlap [options] dset1 dset2 ... Output = count of number of voxels that are nonzero in ALL of the input dataset sub-bricks The result is simply a number printed to stdout. (If a single brick was input, this is just the count of number of nonzero voxels in that brick.) Options: -save ppp = Save the count of overlaps at each voxel into a dataset with prefix 'ppp' (properly thresholded, this could be used as a mask dataset). Example: 3dOverlap -save abcnum a+orig b+orig c+orig 3dmaskave -mask 'abcnum+orig<3..3>' a+orig Also see program 3dABoverlap :) ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dPAR2AFNI.pl
Unknown option: e Unknown option: l Unknown option: p 3dPAR2ANFI Version: 2008/07/18 11:12 Command line Options: -h This help message. -v Be verbose in operation. -s Skip the outliers test when converting 4D files The default is to perform the outliers test. -n Output NIfTI files instead of HEAD/BRIK. The default is create HEAD/BRIK files. -a Output ANALYZE files instead of HEAD/BRIK. -o The name of the directory where the created files should be placed. If this directory does not exist the program exits without performing any conversion. The default is to place created files in the same directory as the PAR files. -g Gzip the files created. The default is not to gzip the files. -2 2-Byte-swap the files created. The default is not to 2 byte-swap. -4 4-Byte-swap the files created. The default is not to 4 byte-swap. Sample invocations: 3dPAR2AFNI subject1.PAR Converts the file subject1.PAR file to subject1+orig.{HEAD,BRIK} 3dPAR2AFNI -s subject1.PAR Same as above but skip the outlier test 3dPAR2AFNI -n subject1.PAR Converts the file subject1.PAR file to subject1.nii 3dPAR2AFNI -n -s subject1.PAR Same as above but skip the outlier test 3dPAR2AFNI -n -s -o ~/tmp subject1.PAR Same as above but skip the outlier test and place the created NIfTI files in ~/tmp 3dPAR2AFNI -n -s -o ~/tmp *.PAR Converts all the PAR/REC files in the current directory to NIfTI files, skip the outlier test and place the created NIfTI files in ~/tmp

AFNI program: 3dpc
Principal Component Analysis of 3D Datasets Usage: 3dpc [options] dataset dataset ... Each input dataset may have a sub-brick selector list. Otherwise, all sub-bricks from a dataset will be used. OPTIONS: -dmean = remove the mean from each input brick (across space) -vmean = remove the mean from each input voxel (across bricks) [N.B.: -dmean and -vmean are mutually exclusive] [default: don't remove either mean] -vnorm = L2 normalize each input voxel time series [occurs after the de-mean operations above,] [and before the brick normalization below. ] -normalize = L2 normalize each input brick (after mean subtraction) [default: don't normalize] -nscale = Scale the covariance matrix by the number of samples This is not done by default for backward compatibility. You probably want this option on. -pcsave sss = 'sss' is the number of components to save in the output; it can't be more than the number of input bricks [default = none of them] * To get all components, set 'sss' to a very large number (more than the time series length), like 99999 You can also use the key word ALL, as in -pcsave ALL to save all the components. -reduce r pp = Compute a 'dimensionally reduced' dataset with the top 'r' eigenvalues and write to disk in dataset 'pp' [default = don't compute this at all] * If '-vmean' is given, then each voxel's mean will be added back into the reduced time series. If you don't want this behaviour, you could remove the mean with 3dDetrend before running 3dpc. * On the other hand, the effects of '-vnorm' and '-dmean' and '-normalize' are not reversed in this output (at least at present -- send some cookies and we'll talk). -prefix pname = Name for output dataset (will be a bucket type); * Also, the eigen-timeseries will be in 'pname'_vec.1D (all of them) and in 'pnameNN.1D' for eigenvalue #NN individually (NN=00 .. 'sss'-1, corresponding to the brick index in the output dataset) * The eigenvalues will be printed to file 'pname'_eig.1D All eigenvalues are printed, regardless of '-pcsave'. [default value of pname = 'pc'] -1ddum ddd = Add 'ddd' dummy lines to the top of each *.1D file. These lines will have the value 999999, and can be used to align the files appropriately. [default value of ddd = 0] -verbose = Print progress reports during the computations -quiet = Don't print progress reports [the default] -eigonly = Only compute eigenvalues, then write them to 'pname'_eig.1D, and stop. -float = Save eigen-bricks as floats [default = shorts, scaled so that |max|=10000] -mask mset = Use the 0 sub-brick of dataset 'mset' as a mask to indicate which voxels to analyze (a sub-brick selector is allowed) [default = use all voxels] Example using 1D data a input, with each column being the equivalent of a sub-brick: 3dpc -prefix mmm -dmean -nscale -pcsave ALL datafile.1D ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dPeriodogram
Usage: 3dPeriodogram [options] dataset Computes the periodogram of each voxel time series. (Squared FFT = a crude estimate of the power spectrum) -------- Options: -------- -prefix p = use string 'p' for the prefix of the output dataset [DEFAULT = 'pgram'] -taper = fraction of data to taper [DEFAULT = 0.1] -nfft L = set FFT length to 'L' points (longer than the data ==> zero padding) (shorter than the data ==> data pruning) ------ Notes: ------ * Output is in float format; number of sub-bricks will be half the FFT length; sub-brick #0 = FFT bin #1, etc. * Grid spacing in the frequency (sub-brick) dimension will be 1/(nfft*TR) where nfft=FFT length, TR=dataset timestep. * There is no '-mask' option. The hyper-clever user could use something like '3dcalc( -a dset+orig -b mask+orig -expr a*b )' to apply a binary mask on the command line. * Data is not scaled exactly as in the AFNI Power plugin. * Each time series is linearly detrended prior to FFT-ization. * FFT length defaults to be the next legal length >= input dataset. * The program can only do FFT lengths that are positive even integers. ++ '-nfft' with an illegal value will cause the program to fail. * If you want to do smaller FFTs, then average the periodograms (to reduce random fluctuations), you can use 3dPeriodogram in a script with "[...]" sub-brick selectors, then average the results with 3dMean. * Or you could use the full-length FFT, then smooth that FFT in the frequency direction (e.g., with 3dTsmooth). * This is a really quick hack for DH and PB and SfN. * Author = RWCox -- who doesn't want any bribe at all for this! -- http://ethics.od.nih.gov/topics/gifts.htm --------------------------------------------------- More Details About What 3dPeriodogram Actually Does --------------------------------------------------- * Tapering is done with the Hamming window (if taper > 0): Define npts = number of time points analyzed (<= nfft) (i.e., the length of the input dataset) ntaper = taper * npts / 2 (0 < taper <= 1) = number of points to taper on each end ktop = npts - ntaper phi = PI / ntaper Then the k-th point (k=0..nfft-1) is tapered by w(k) = 0.54 - 0.46 * cos(k*phi) 0 <= k < ntaper w(k) = 0.54 + 0.46 * cos((k-ktop+1)*phi) ktop <= k < npts w(k) = 1.0 otherwise Also define P = sum{ w(k)*w(k) } from k=0..npts-1 (if ntaper = 0, then P = npts). * The result is the squared magnitude of the FFT of w(k)*data(k), divided by P. This division makes the result be the 'power', which is to say the data's sum-of-squares ('energy') per unit time (in units of 1/TR, not 1/sec) ascribed to each FFT bin. * Normalizing by P also means that the values output for different amounts of tapering or different lengths of data are comparable. * To be as clear as I can: this program does NOT do any averaging across multiple windows of the data (such as Welch's method does) to estimate the power spectrum. This program: ++ tapers the data, ++ zero-pads it to the FFT length, ++ FFTs it (in time), ++ squares it and divides by the P factor. * The number of output sub-bricks is nfft/2: sub-brick #0 = FFT bin #1 = frequency 1/(nfft*dt) #1 = FFT bin #2 = frequency 2/(nfft*dt) et cetera, et cetera, et cetera. * If you desire to implement Welch's method for spectrum estimation using 3dPeriodogram, you will have to run the program multiple times, using different subsets of the input data, then average the results with 3dMean. ++ https://en.wikipedia.org/wiki/Welch's_method ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dPFM
Usage: 3dPFM [options] ------ Brief summary: ============== * 3dPFM is a program that identifies brief BOLD events (order of sec) in fMRI time series without prior knowledge of their timing. 3dPFM deconvolves a hemodynamic response function for each fMRI voxel and estimates the neuronal-related signal that generates the BOLD events according to the linear haemodynamic model. In many ways, the neuronal-related signal could be understood as the stimulus signal defined by the experimental paradigm in a standard GLM approach, where the onsets and duration of the experimental conditions are known a-priori. Alternatively, 3dPFM does not assume such information and estimates the signal underlying the BOLD events with NO PARADIGM INFORMATION, i.e. PARADIGM FREE MAPPING (PFM). For instance, this algorithm can be useful to identify spontaneous BOLD events in resting-state fMRI data. * The ideas behind 3dPFM are described in C Caballero-Gaudes, N Petridou, ST Francis, IL Dryden, and PA Gowland. Paradigm Free Mapping with Sparse Regression Automatically detects Single-Trial Functional Magnetic Resonance Imaging Blood Oxygenation Level Dependent Responses. Human Brain Mapping, 34(3):501-18, 2013. http://dx.doi.org/10.1002/hbm.21452 * For the deconvolution, 3dPFM assumes a linear convolution model and that the neuronal-related signal is sparse in time, i.e. it has a non-zero amplitude in a relatively small number of time points. How relative depends on the number of time points of the signal, i.e. the length of the signal, a.k.a. scans, volumes. * In many ways, the rationale of 3dPFM is very similar to 3dTfitter with the -FALTUNG (deconvolution) option. Both programs differ in the manner the deconvolution is solved and several other relevant and interesting options. **** I would also recommend you to read 3dTfitter -help for useful tips ***** ************* !!! 3dPFM is neither for the casual user !!!! **************** * IMPORTANT. This program is written in R. Please follow the guidelines in https://afni.nimh.nih.gov/sscc/gangc/Rinstall.html to install R and make AFNI compatible with R. In addition, you need to install the following libraries with dependencies: install.packages("abind",dependencies=TRUE) install.packages("MASS",dependencies=TRUE) install.packages("lars",dependencies=TRUE) You can find a demo on how to run this program in @Install_3dPFM_Demo A brief in deconvolution and regularization =========================================== Only for the non-casual user !!!: =========================================== The basic idea of 3dPFM is to assume that the time series at each voxel y(t) is given by the linear convolution model (e.g., a linear haemodynamic model) y(t) = sum { h(j) * s(t-j) } + e(t) j>=0 where h(t) is an user-supplied kernel function (e.g., haemodynamic response function (HRF)), s(t) is the neuronal-related time series to be estimated, and e(t) is a noise term capturing all noisy components of the signal. In matrix notation, the convolution model can be "simply" written as y = H*s + e where y, s and e are the input voxel, the neuronal-related and the error time series, respectively, and H is a matrix with time-shifted versions of the kernel function across columns. The convolution model is defined such that the size of H is N x N, where N is the length of the input time series and, accordingly, the estimated neuronal-related time series has the same length as the input time series. Assuming that the noise is random and following a Gaussian distribution, a very sensible way to estimate the time series s would be to minimize the sum of squares of the residuals (RSS), a.k.a. L2fit, Least-Squares (LS) fit, and so forth, i.e. s* = min || y - H*s ||_2^2 s Unfortunately, in our problem the least squares solution tends to overfit the input time series (i.e. the input time series tend to produce a perfect fit of the input signal including the noise) since the number of variables to estimate is equal to the number of observations in the original time series. In addition, since the columns of the convolution matrix H are highly correlated, the LS estimates can become poorly determined and exhibit high variance. One solution to these drawbacks is to impose a regularization term on (or penalization of) the coefficient estimates based on prior information about the input signal. Typically, regularization terms based on the Lp-norm of the estimates are used, such that the estimate of s is computed by solving s* = min || y - H*s ||_2^2 subject to || s ||_p <= λ s or, similarly, s* = min || s ||_p subject to || y - H*s ||_2^2 <= λ s or, using Lagrangian multipliers, s* = min || y - H*s ||_2^2 + λ || s ||_p s The three optimization problems are relatively equivalent, where λ is a positive regularization parameter that balance the tradeoff between the term of the residuals sum of squares (RSS) and the regularization or penalty term. Note: The value of λ in the Lagrangian formulation is not equal (i.e. does not have one-to-one correspondence) to the value of λ in the constrained problems. The L1-norm (p = 1) is a convex, and widely studied, regularization term that promotes sparse estimates. Relevant for fMRI data analysis, if BOLD responses were generated by brief (on the fMRI time scale) bursts of neuronal activation, it could be assumed that the neuronal-related time series s is a sparse vector with few coefficients whose amplitude are significantly different from zero. In fact, this is typically assumed in event-related fMRI experiments where we assume that one voxel responds to brief stimuli in some, but not all, conditions. In 3dPFM, two regularized estimation problems are currently implemented based on the L1-norm: * LASSO: The least absolute shrinkage and selection operator (LASSO) [Tibshirani, 1996], which is equivalent to basis pursuit denoising (BPDN) [Chen et al., 1998]: s* = min || y - H*s ||_2^2 subject to || s ||_1 <= λ s * DS: The Dantzig Selector [Candes and Tao, 2007] s* = min || s ||_1 subject to || H^T (y - H*s) ||_infty <= λ s where the L_infty (infinity-norm) refers to the maximum absolute value of a vector. In practice, minimizing the error term subject to a constraint in the norm is often equivalent to minimizing the norm subject to a constraint in the error term, with a one-to-one correspondence between the regularization parameters of both problems. All in all, one can see that the main difference between the LASSO and the DS relates to the error term. The LASSO considers the residual sum of squares (RSS), whereas the DS considers the maximum correlation (in absolute value) of the residuals with the model. Very intelligent minds have shown that there are very strong links between the DS and the LASSO (see Bickel et al., 2009 http://projecteuclid.org/euclid.aos/1245332830; and James et al., 2009 http://dx.doi.org/10.1111/j.1467-9868.2008.00668.x for more information). For lesser mortals, it is enough to know that the L_infty norm term in the DS is equivalent to the differentiation of the RSS term with respect to s in the LASSO. Actually, in practice the results of 3dPFM with the DS are usually very similar to the ones obtained with the LASSO (and vice-versa). Algorithms for solving the LASSO and DS --------------------------------------- 3dPFM relies on homotopy continuation procedures to solve the above optimization problems. These procedures are very useful since they compute the complete set of solutions of the problem for all possible regularization parameters. This is known as the regularization path. In particular, 3dPFM employs an R-version of homotopy continuation algorithms for the DS (L1-homotopy) developed by Asif and Romberg (see http://dx.doi.org/10.1109/CISS.2010.5464890), and the R-package LARS for the LASSO. Choice of regularization parameter ---------------------------------- Once the regularization path with all solutions is computed, what is the optimal one? i.e., what is the optimal regularization parameter λ ??. This is a very difficult question. In fact, it is nearly impossible to select the optimal λ unless one is aware of the optimal solution in advance (i.e. be the ORACLE) (but then we would not need to estimate anymore!!!). In 3dPFM, the choice of the regularization parameter is done based on model selection criteria that balance the degrees of freedom (df) that are employed to fit the signal and the RSS relative to the number of observations. For instance, when we use the Least Squares estimator to fit a general linear model (GLM), as in 3dDeconvolve, the value of df is approximately equal to number of regressors that we define in the model. So, here is the key question in 3dPFM: If the convolution model used in 3dPFM (i.e. the matrix) has as many columns as the number of observations, is not the degrees of freedom equal or higher than the number of time points of the signal? The answer is NO for the L1-norm regularization problems as the LASSO. The trick is that an unbiased estimate of the degrees of freedom of the LASSO is the number of non-zero coefficients of the LASSO estimate (for demonstration see http://projecteuclid.org/euclid.aos/1194461726) if the matrix H is orthogonal. Unfortunately, the matrix H in 3dPFM is not orthogonal and this result is not completely accurate. Yet, we consider it valid as it works quite nicely in our application, i.e. counting the number of non-zero coefficients in the solution is a very good approximation of the degrees of freedom. Moreover, 3dPFM also uses this approximation for the Dantzig Selector due to the close link with the LASSO. Therefore, the unbiased estimate of the degrees of freedom can be used to construct model selection criteria to select the regularization parameter. Two different criteria are implemented in 3dPFM: * -bic: (Bayesian Information Criterion, equivalent to Minimum Description Length) λ* = min N*log(|| y - H*s(λ) ||_2^2) + log(N)*df(λ) λ * -aic: (Akaike Information Criterion) λ* = min N*log(|| y - H*s(λ) ||_2^2) + 2*df(λ) λ where s(λ) and df(λ) denote that the estimate and df depend on the regularization parameter λ. As shown in (Caballero-Gaudes et al. 2013), the bayesian information criterion (bic) typically gives better results than the akaike information crition (aic). If you want the 3dPFM ORACLE (i.e. the author of this program) to implement other criteria, such as AICc, MDLc, please write him an email. Option -nonzeros Q: Alternatively, one could also select the regularization parameter such that the estimate only includes Q coefficients with non-zero amplitude, where Q is an arbitrary number given as input. In statistics, the set of nonzero coefficients for a given regularization parameter is defined as the active (or support) set. A typical use of this option would be that we hypothesize that our signal only includes Q nonzero coefficients (i.e. haemodynamic events of TR duration) but we do not know when they ocurr. IMPORTANT: If two successive events are non-zero, do both coefficients represent one or two events? Intuitively, one could think that both coefficients model a single event that spans several coefficients and, thus, requires several non-zero coefficients to to be properly modelled. This case is NOT considered in the program. To deal with this situation, 3dPFM should have an option like "-nevents Q", where Q is the number of events or successive non-zero coefficients. Unfortunately, this cannot be easily defined. For instance, an estimate where all coefficients are non-zero would represent a SINGLE event!!! If you think of a sensible manner to implement this option, please contact THE ORACLE. VERY IMPORTANT: In practice, the regularization path could include 2 different solutions for 2 different regularization parameters but with equal number of non-zero coefficients!!! This occurs because in the process of computing the regularization path for decreasing values of the regularization parameter (i.e. λ1 > λ2 > λ3), the number of elements in the active set (i.e. the set of coefficients with non-zero amplitide) can increase or decrease. In fact, the knots of the regularization path are the points where one element of the active set changes (i.e. it is removed or added to the active set) as λ decreases to zero. Consequently, the active set could include Q non-zero elements for λ1, Q+1 for λ2 < λ1, and Q for λ3 < λ2. In that case, the estimate given by 3dPFM is the solution for the largest regularization parameter. CAREFUL!! use option -nonzeros at your own risk!! - Not all voxels show neuronal related BOLD events. - These options are appropriate for ROI or VOI analyses where there is a clear hypothesis that a given number of BOLD events should exist but we have no clue of their timing. ------------ References: ------------ If you find 3dPFM useful, the papers to cite are: C Caballero-Gaudes, N Petridou, ST Francis, IL Dryden, and PA Gowland. Paradigm Free Mapping with Sparse Regression Automatically detects Single-Trial Functional Magnetic Resonance Imaging Blood Oxygenation Level Dependent Responses. Human Brain Mapping, 34(3):501-18, 2013. http://dx.doi.org/10.1002/hbm.21452 C Caballero-Gaudes, N Petridou, IL Dryden, L Bai, ST Francis and PA Gowland. Detection and characterization of single-trial fMRI bold responses: Paradigm free mapping. Human Brain Mapping, 32(9):1400-18, 2011 http://dx.doi.org/10.1002/hbm.21116. If you find 3dPFM very useful for the analysis of resting state data and finding invisible sponteneous BOLD events, the paper to cite is: N Petridou, C Caballero-Gaudes, IL Dryden, ST Francis and PA Gowland Periods of rest in fMRI contain individual spontaneous events which are related to slowly fluctuating spontaneous activity. Human Brain Mapping, 34(6):1319-29, 2013. http://dx.doi.org/10.1002/hbm.21513 If you use the Dantzig Selector in 3dPFM and want to know more about the homotopy algorithm for solving it, the paper to read (and cite) is: M Salman Asif and J Romberg, On the LASSO and Dantzig selector equivalence, Conference on Information Sciences and Systems (CISS), Princeton, NJ, March 2010. http://dx.doi.org/10.1109/CISS.2010.5464890 Finally, additional references for the LASSO and the Dantzig Selector are: R Tibshirani. Regression Shrinkage and Selection via the Lasso. Journal of the Royal Statistical Society. Series B (Methodological), 58(1): 267-288, 1996. http://www.jstor.org/stable/2346178 H Zou, T Hastie, R Tibshirani. On the “degrees of freedom” of the lasso. Annals of Statistics 35(5): 2173--2192, 2007. http://projecteuclid.org/euclid.aos/1194461726. B Efron, T Hastie, I. Johnstone, R Tibshirani. Least Angle Regression. Annals of Statistics 32(2): 407–-499, 2004. http://projecteuclid.org/euclid.aos/1083178935 E Candes and T. Tao. The Dantzig selector: Statistical estimation when p is much larger than n. The Annals of Statistics 35(6):2313--2351, 2007. http://projecteuclid.org/euclid.aos/1201012958. M Salman Asif and J Romberg, On the LASSO and Dantzig selector equivalence, Conference on Information Sciences and Systems (CISS), Princeton, NJ, March 2010. http://dx.doi.org/10.1109/CISS.2010.5464890 --------------------------------------------------------------------------------------- Author: C. Caballero Gaudes, THE ORACLE (c.caballero@bcbl.eu) (May 1st, 2015) (many thanks to Z. Saad, R.W. Cox, J. Gonzalez-Castillo, G. Chen, and N. Petridou for neverending support) Example usage: ----------------------------------------------------------------------------- 3dPFM -input epi.nii -mask mask.nii -algorithm dantzig -criteria bic -LHS regparam.1D -hrf SPMG1 -jobs 1 -outALL yes Options: -------- -input DSET1 Specify the dataset to analyze with Paradigm Free Mapping (3dPFM). It can be any of the formats available in AFNI. e.g: -input Data+orig Also .1D files where each column is a voxel timecourse. If an .1D file is input, you MUST specify the TR with option -TR. -mask MASK: Process voxels inside this mask only. Default is no masking. -algorithm ALG: Regularization (a.k.a. penalty) function used for HRF deconvolution. * Available options for ALG are: dantzig: Dantzig Selector (default) lasso: LASSO * If you want other options, contact with the ORACLE (c.caballero@bcbl.eu). -criteria CRIT: Model selection criterion for HRF deconvolution. * Available options are: BIC: Bayesian Information Criterion AIC: Akaike Information Criterion * Default is BIC since it tends to produce more accurate deconvolution (see 3dPFM paper). * If you want other options, write to the ORACLE. * This option is incompatible with -nonzeros. -nonzeros XX: * Choose the estimate of the regularization path with XX nonzero coefficients as the output of the deconvolution. * Since the regularization path could have several estimates with identical number of nonzero coefficients, the program will choose the first one in the regularization path, i.e. the solution with the largest regularization parameter. * This option is incompatible with -criteria. * This option is not used by default. -maxiter MaxIter: * Maximum number of iterations in the homotopy procedure (absolute value). * Setting up MaxIter < 1 might be useful to speed up the program, e.g. with the option -nonzeros Q, MaxIter = 2*Q is reasonable (default) -maxiterfactor MaxIterFactor: * Maximum number of iterations in the homotopy procedure is relative to the number of volumes of the input time series, i.e. MaxIterFactor*nscans, * Default value is MaxIterFactor = 1 MaxIter OR MaxIterFactor -------------------------- * If both MaxIterFactor and MaxIter are given for any mistaken reason, the program will STOP. It only admits one of the two options. * If none of them is given, the number of iterations is equal to nscans. * The homotopy procedure adds or removes one coefficient from the active set of non-zero coefficients in the estimate in each iteration. * If you expect Q non-zero coefficients in the deconvolved time-series, a reasonable choice is MaxIter = 2*Q (default with -nonzero Q) * If you want to speed up the program, choose MaxIterfactor = 1 or 0.5. -TR tr: Repetition time or sampling period of the input data * It is required for the generation of the deconvolution HRF model. * If input dataset is .1D file, TR must be specified in seconds. If TR is not given, the program will STOP. * If input dataset is a 3D+time volume and tr is NOT given, the value of TR is taken from the dataset header. * If TR is specified and it is different from the TR in the header of the input dataset, the program will STOP. I am not sure know why you want to do that!!! but if you want, first change the TR of the input with 3drefit. -hrf fhrf: haemodynamic response function used for deconvolution * Since July 2015, fhrf can be any of the HRF models available in 3dDeconvolve. Check https://afni.nimh.nih.gov/pub/dist/doc/program_help/3dDeconvolve.html * I.e. 3dPFM calls 3dDeconvolve with the -x1D_stop and -nodata options to create the HRF with onset at 0 (i.e. -stim_time 1 '1D:0' fhrf ) * [Default] fhrf == 'GAM', the 1 parameter gamma variate (t/(p*q))^p * exp(p-t/q) with p=8.6 q=0.547 if only 'GAM' is used ** The peak of 'GAM(p,q)' is at time p*q after the stimulus. The FWHM is about 2.3*sqrt(p)*q. * Another option is fhrf == 'SPMG1', the SPM canonical HRF. * If fhrf is a .1D, the program will use it as the HRF model. ** It should be generated with the same TR as the input data to get sensible results (i.e. know what you are doing). ** fhrf must be column or row vector, i.e. only 1 hrf allowed. In future, this option might be changed to model the hrf as a linear combination of functions. * The HRF is normalized to maximum absolute amplitude equal to 1. -hrf_vol hrf_DSET: 3D+time dataset with voxel/nodes/vertex -dependent HRFs. * The grid and TR of hrf_DSET must be the same as the input dataset. * This dataset can be the output of -iresp option in 3dDeconvolve, which contains the estimated HRF (a.k.a. impulse responses) for a given stimuli. * In 3dPFM, the HRF response is assumed constant during the acquisition. * See also -idx_hrf, an interesting option to use voxel dependent HRFs. -idx_hrf idx_hrf_DSET: 3D dataset with voxel-dependent indexes that indicate which column of the .1D file in option -hrf should be used for each voxel. * Of course, the grid of idx_hrf_DSET must be the same as the input dataset. * The number of HRFs in option -hrf must be <= maximum index in idx_hrf_DSET. Otherwise, the program will STOP before starting any calculation. * Only positive integers > 0 are allowed in this option. * For instance, this dataset can be created by clustering (e.g. with 3dKmeans) the estimated HRF generated with option -iresp in 3dDeconvolve. * In 3dPFM, the HRF response is assumed constant during the acquisition * An index equal to 1 will select the first column of the .1D fhrf, which is usually column 0 in AFNI nomenclature. -LHS lset: Options: file.1D or functional dataset(s) * Additional regressors that will be fitted to the data after deconvolution. * Usually, these will be nuisance regressors that explain some variability of the data, e.g. the realignment parameters estimated with 3dVolreg. * More than one 'lset' can follow the '-LHS' option and it can be any of the AFNI formats. * Each 'lset' can be a 3D+time dataset or a 1D file with 1 or more columns. * A 3D+time dataset defines one column in the LHS matrix. ++ If input is a 1D file, then you cannot input a 3D+time dataset with '-LHS'. ++ If input is a 3D+time dataset, then the LHS 3D+time dataset(s) must have the same voxel grid as the input. * A 1D file will include all its columns in the LHS matrix. ++ For example, you could input the LHS matrix from the .xmat.1D file output by 3dDeconvolve, if you wanted to repeat the same linear regression using 3dPFM. * Columns are assembled in the order given on the command line, which means that LHS parameters will be output in that order! NOTE: These notes are ALMOST a copy of the -LHS option in 3dTfitter and they are replicated here for simplicity and because it is difficult to do it better !! -jobs NJOBS: On a multi-processor machine, parallel computing will speed up the program significantly. Choose 1 for a single-processor computer (DEFAULT). -nSeg XX: Divide into nSeg segments of voxels to report progress, e.g. nSeg 5 will report every 20% of processed voxels. Default = 10 -verb VERB: VERB is an integer specifying verbosity level. 0 for quiet, 1 (default) or more: talkative. -help: this help message -beta Prefix for the neuronal-related (i.e. deconvolved) time series. It wil have the same length as the input time series. This volume is always saved with default name 'PFM' if not given. ++ If you don't want this time series (why?), set it to NULL. This is another similarity with 3dTfitter. -betafitts Prefix of the convolved neuronal-related time series. It wil have the same length as the input time series Default = NULL, which means that the program will not save it. -fitts Prefix for the fitted time series. Default = NULL, although it's recommendable to save it to check the fit of the model to the data. -resid Prefix for the residuals of the fit to the data. Default = NULL. It could also be computed as input - ffitts with 3dcalc. -mean Prefix for the intercept of the model Default = NULL. -LHSest Prefix for the estimates of the LHS parameters. Default = NULL. -LHSfitts Prefix for the fitted time series of the LHS parameters. Default = NULL. -lambda Prefix for output volume with the regularization parameter of the deconvolution of each voxel. Default = NULL. -costs Prefix for output volume of the cost function used to select the regularization parameter according to the selected criteria. Default = NULL. Output volumes of T-stats, F-stats and Z-stats ============================================== -Tstats_beta Prefix for the T-statistics of beta at each time point according to a linear model including the nonzero coefficients of the deconvolved signal, plus LHS regressors and intercept It wil have the same length as the input time series Recommendation: Use -Tdf_beta too!! Default = NULL. -Tdf_beta Prefix for degrees of freedom of the T-statistics of beta. Useful if you want to check Tstats_beta since different voxels might have different degrees of freedom. Default = NULL. -Z_Tstats_beta Prefix for (normalized) z-scores of the T-statistics of beta. Recommendable option to visualize the results instead of Tstats_beta and Tdf_beta since (again) different voxels might be fitted with different degrees of freedom. Default = NULL. -Fstats_beta Prefix for the F-statistics of the deconvolved component. Recommendation: Use -Fdf_beta too!! for the very same reasons. Default = NULL. -Fdf_beta Prefix for degrees of freedom of Fstats_beta. Useful to check Fstats_beta for the very same reasons. Default = NULL. -Z_Fstats_beta Prefix for (normalized) z-scores of the Fstats_beta. Recomendable option instead of Fstats_beta and Fdf_beta. Default = NULL. -Tstats_LHS Prefix for T-statistics of LHS regressors at each time point. It wil have the same length as the total number of LHS regressors. Recommendation: Use -Tdf_LHS too!! Default = NULL. -Tdf_LHS Prefix for degrees of freedom of the Tstats_LHS. Useful if you want to check Tstats_LHS since different voxels might have different degrees of freedom. Default = NULL. -Z_Tstats_LHS Prefix for (normalized) z-scores of the Tstats_LHS. Recommendable option instead of Tstats_LHS and Tdf_LHS. Default = NULL. -Fstats_LHS Prefix for the F-statistics of the LHS regressors. Recommendation: Use -Fdf_LHS too!! Default = NULL. -Fdf_LHS Prefix for degrees of freedom of the Fstats_LHS. Default = NULL. -Z_Fstats_LHS Prefix for (normalized) z-scores of Fstats_LHS. Recommendable option instead of Fstats_LHS and Fdf_LHS. Default = NULL. -Fstats_full Prefix for the F-statistics of the full (deconvolved) model. Default = NULL. -Fdf_full Prefix for the degrees of freedom of the Fstats_full. Default = NULL. -Z_Fstats_full Prefix for (normalized) z-scores of Fstats_full. Default = NULL. -R2_full Prefix for R^2 (i.e. coefficient of determination) of the full model. Default = NULL. -R2adj_full Prefix for Adjusted R^2 coefficient of the full model. Default = NULL. -outALL suffix * If -outALL is used, the program will save ALL output volumes. * The names of the output volumes will be automatically generated as outputname_suffix_input, e.g. if -input = TheEmperor+orig, and suffix is Zhark, the names of the volumes will be beta_Zhark_TheEmperor+orig for -beta option, betafitts_Zhark_TheEmperor+orig for -betafitts option, and so forth. * If suffix = 'yes', then no suffix will be used and the names will be just outputname_input, i.e. beta_TheEmperor+orig. * If you want to specify a given name for an output volume, you must define the name of the output volume in the options above. The program will use it instead of the name automatically generated. Default = NULL. -outZAll suffix * If -outZAll is used, the program will save ALMOST ALL output volumes. * Similar to -outALL, but the program will only save the Z_Tstats_* and Z_Fstats_* volumes i.e. it will not save the Tstats_*, Tdf_*, Fstats_* and Fdf_* volumes. * This option is incompatible with -outALL. The program will STOP if both options are given. Default = NULL. -show_allowed_options: list of allowed options

AFNI program: 3dPolyfit
Usage: 3dPolyfit [options] dataset ~1~ * Fits a polynomial in space to the input dataset and outputs that fitted dataset. * You can also add your own basis datasets to the fitting mix, using the '-base' option. * You can get the fit coefficients using the '-1Dcoef' option. -------- Options: ~1~ -------- -nord n = Maximum polynomial order (0..9) [default order=3] [n=0 is the constant 1] [n=-1 means only use volumes from '-base'] -blur f = Gaussian blur input dataset (inside mask) with FWHM='f' (mm) -mrad r = Radius (voxels) of preliminary median filter of input [default is no blurring of either type; you can] [do both types (Gaussian and median), but why??] [N.B.: median blur is slower than Gaussian] -prefix pp = Use 'pp' for prefix of output dataset (the fit). [default prefix is 'Polyfit'; use NULL to skip this output] -resid rr = Use 'rr' for the prefix of the residual dataset. [default is not to output residuals] -1Dcoef cc = Save coefficients of fit into text file cc.1D. [default is not to save these coefficients] -automask = Create a mask (a la 3dAutomask) -mask mset = Create a mask from nonzero voxels in 'mset'. [default is not to use a mask, which is probably a bad idea] -mone = Scale the mean value of the fit (inside the mask) to 1. [probably this option is not useful for anything] -mclip = Clip fit values outside the rectilinear box containing the mask to the edge of that box, to avoid weird artifacts. -meth mm = Set 'mm' to 2 for least squares fit; set it to 1 for L1 fit [default method=2] [Note that L1 fitting is slower than L2 fitting!] -base bb = In addition to the polynomial fit, also use the volumes in dataset 'bb' as extra basis functions. [If you use a base dataset, then you can set nord] [to -1, to skip using any spatial polynomial fit.] -verb = Print fun and useful progress reports :-) ------ Notes: ~1~ ------ * Output dataset is always stored in float format. * If the input dataset has more than 1 sub-brick, only sub-brick #0 is processed. To fit more than one volume, you'll have to use a script to loop over the input sub-bricks, and then glue (3dTcat) the results together to get a final result. A simple example: #!/bin/tcsh set base = model.nii set dset = errts.nii set nval = `3dnvals $dset` @ vtop = $nval - 1 foreach vv ( `count_afni 0 $vtop` ) 3dPolyfit -base "$base" -nord 0 -mask "$base" -1Dcoef QQ.$vv -prefix QQ.$vv.nii $dset"[$vv]" end 3dTcat -prefix QQall.nii QQ.0*.nii 1dcat QQ.0*.1D > QQall.1D m QQ.0* exit 0 * If the '-base' dataset has multiple sub-bricks, all of them are used. * You can use the '-base' option more than once, if desired or needed. * The original motivation for this program was to fit a spatial model to a field map MRI, but that didn't turn out to be useful. Nevertheless, I make this program available to someone who might find it beguiling. * If you really want, I could allow you to put sign constraints on the fit coefficients (e.g., say that the coefficient for a given base volume should be non-negative). But you'll have to beg for this. -- Emitted by RWCox ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dPval
Usage: 3dPval [options] dataset * Converts a dataset's statistical sub-bricks to p-values. * Sub-bricks not internally marked as statistical volumes are unchanged. * However, all output volumes will be converted to float format! * If you wish to convert only sub-brick #3 (say) of a dataset, then something like this command should do the job: 3dPval -prefix Zork.nii InputDataset.nii'[3]' * Note that sub-bricks being marked as statistical volumes, and having value-to-FDR conversion curves attached, are AFNI-only ideas, and are not part of any standard, NIfTI or otherwise! In other words, this program will be useless for a random dataset which you download from some random non-AFNI-centric site :( * Also note that SMALLER p- and q-values are more 'significant', but that the AFNI GUI provides interactive thresholding for values ABOVE a user-chosen level, so using the GUI to threshold on a p-value or q-value volume will have the opposite result to what you might wish for. * Although the program now allows conversion of statistic values to z-scores or FDR q-values, instead of p-values, you can only do one type of conversion per run of 3dPval. If you want p-values AND q-values, you'll have to run this program twice. * Finally, 'sub-brick' is AFNI jargon for a single 3D volume inside a multi-volume dataset. Options: ======= -zscore = Convert statistic to a z-score instead, an N(0,1) deviate that represents the same p-value. -log2 = Convert statistic to -log2(p) -log10 = Convert statistic to -log10(p) -qval = Convert statistic to a q-value (FDR) instead: + This option only works with datasets that have FDR curves inserted in their headers, which most AFNI statistics programs will do. The program 3drefit can also do this, with the -addFDR option. -prefix p = Prefix name for output file (default name is 'Pval') AUTHOR: The Man With The Golden p < 0.000001 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dPVmap
3dPVmap [-prefix XXX] [-mask MMM] [-automask] inputdataset Computes the first 2 principal component vectors of a time series datasets, then outputs the R-squared coefficient of each voxel time series with these first 2 components. Each voxel times series from the input dataset is minimally pre-processed before the PCA is computed: Despiking Legendre polynomial detrending L2 normalizing (sum-of-squares = 1) If you want more impressive pre-processing, you'll have to do that before running 3dPVmap (e.g., use the errts dataset from afni_proc.py). Program also outputs the first 2 principal component time series vectors into a 1D file, for fun and profit. The fractions of total-sum-of-squares allocable to the first 2 principal components are written to stdout at the end of the program. along with a 3rd number that is a measure of the spatial concentration or dispersion of the PVmap. These values can be captured into a file by Unix shell redirection or into a shell variable by assignment: 3dPVmap -mask AUTO Fred.nii > Fred.sval.1D set sval = ( `3dPVmap -mask AUTO Fred.nii` ) # csh syntax If the first value is very large, for example, this might indicate the widespread presence of some artifact in the dataset. If the 3rd number is bigger than 1, it indicates that the PVmap is more concentrated in space; if it is less than one, it indicates that it is more dispersed in space (relative to a uniform density). 3dPVmap -mask AUTO Zork.nii ++ mask has 21300 voxels ++ Output dataset ./PVmap+orig.BRIK 0.095960 0.074847 1.356635 The first principal component accounted for 9.6% of the total sum-of-squares, the second component for 7.5%, and the PVmap is fairly concentrated in space. These % values are not very unusual, but the concentration is fairly high and the dataset should be further investigated. A concentration value below 1 indicates the PVmap is fairly dispersed; this often means the larger PVmap values are found near the edges of the brain and can be caused by motion or respiration artifacts. The goal is to visualize any widespread time series artifacts. For example, if a 'significant' part of the brain shows R-squared > 0.25, that could be a subject for concern -- look at your data! Author: Zhark the Unprincipaled

AFNI program: 3dQwarp
++ OpenMP thread count = 1 ++ 3dQwarp: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: Zhark the (Hermite) Cubically Warped Usage: 3dQwarp [OPTIONS] ~1~ * Computes a nonlinearly warped version of source_dataset to match base_dataset. ++ Written by Zhark the Warped, so take nothing here too seriously. ++ The detail allowed in the warping is set by the '-minpatch' option. ++ The discrete warp computed herein is a representation of an underlying piecewise polynomial C1 diffeomorphism. ++ See the OUTLINE OF WARP OPTIMIZATION METHOD section, far below, for details. * Other AFNI programs in this nonlinear warping collection include: ++ 3dNwarpAdjust = adjust a set of nonlinear warps to remove any mean warp ++ 3dNwarpApply = apply a nonlinear warp to transform a dataset ++ 3dNwarpCat = catenate/compose two or more warps to produce a new warp ++ 3dNwarpFuncs = compute some functions of a nonlinear warp ++ 3dNwarpXYZ = apply a nonlinear warp to discrete set of (x,y,z) triples ++ @SSwarper = Script that combines 3dQwarp and 3dSkullStrip (SS) to produce a brain volume warped to a template and with the non-brain tissue ('skull') removed. ++ auto_warp.py = Python program to run 3dQwarp for you ++ unWarpEPI.py = Python program to unwarp EPI datasets, using a reverse-blip reference volume ++ afni_proc.py = General AFNI pipeline for FMRI datasets, which can use auto_warp.py and unWarpEPI.py along the way. * 3dQwarp is where nonlinear warps come from (in AFNIland). ++ For the most part, the above programs either use warps from 3dQwarp, or they provide easier ways to run 3dQwarp. ** NEVER use the obsolete '-nwarp' option to 3dAllineate. It is not compatible with these other programs, and it does not produce useful results. * The simplest way to use 3dQwarp is via the @SSwarper script, for warping a T1-weighted dataset to the (human brain) MNI 2009 template dataset supplied with AFNI binaries (other templates also available). * The next simplest way to use 3dQwarp is via the auto_warp.py program. * You can use 3dQwarp directly if you want to control (or play with) the various options for setting up the warping process. * Input datasets must be on the same 3D grid (unlike program 3dAllineate)! ++ Or you will get a fatal error when the program checks the datasets! ++ However, you can use the '-allineate' option in 3dQwarp to do affine alignment before the nonlinear alignment, which will also resample the aligned source image to the base dataset grid. ++ OR, you can use the '-resample' option in 3dQwarp to resample the source dataset to the base grid before doing the nonlinear stuff, without doing any preliminary affine alignment. '-resample' is much faster than '-allineate', but of course doesn't do anything but make the spatial grids match. Normally, I would not recommend this! +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ++ UNLESS the base and source datasets are fairly close to each other ++ ++ already, the '-allineate' option will make the process better. For ++ ++ example, if the two datasets are rotated off 5 degrees, using ++ ++ 3dQwarp alone will be less effective than using '3dQwarp -allineate'. ++ +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ * 3dQwarp CAN be used on 2D images -- that is, datasets with a single slice. How well it works on such datasets has not been investigated much, but it DOES work (and quickly, since the amount of data is small). ++ You CAN input .jpg or .png files as the source and base images. ++ 3dQwarp will convert RGB images to grayscale and attempt to align those. The output will still be in dataset format (not image format) and will be in grayscale floating point (not color). To get the warped image output in .jpg or .png format, you can open the output dataset in the AFNI GUI and save the image -- after turning off crosshairs! + To get an RGB copy of a warped image, you have to apply the warp to each channel (R, G, B) separately and then fuse the results. Other approaches are possible, of course. ++ Applying this program to 2D images is entirely for fun; the actual utility of it in brain imaging is not clear to Emperor Zhark. (Which is why the process of getting a color warped image is so clumsy.) * Input datasets should be reasonably well aligned already (e.g., as from an affine warping via 3dAllineate). ++ The standard result from 3dAllineate will resample the affinely aligned dataset to the same 3D grid as the -base dataset, so this new dataset will be ready to run in 3dQwarp against the same base. ++ Again, the '-allineate' option can now do this for you, inside 3dQwarp. * Input datasets should be 'alike'. ++ For example, if the '-base' dataset is skull stripped, then the '-source' dataset should be skull stripped also -- e.g., via 3dSkullStrip. + Warping a skull-on dataset (source) to a skull-off dataset (base) will sometimes work OK, but sometimes will fail in weird-looking ways. ++ If the datasets have markedly different contrasts (e.g., T1 and T2), then using a non-standard matching function such as '-nmi' or '-hel' or '-lpa' might work better than the default Pearson correlation matching function. (This type of warping has not been tested much here at AFNI headquarters.) + Warping T2 to T1 would likely be best done by inverting the contrast of the T2 dataset, via '3dUnifize -T2 -T2', to make it look like a T1 volume. + These non-standard methods are slower than the Pearson correlation default. ****************************************************************************** * If the input datasets do NOT overlap reasonably well (please look at them * * them in AFNI), or when the source is in scanner space and the base is in a * * template space (e.g., MNI), then you need to use '-allineate', or you will * * probably get * * (a) a very bad result (or a program crash) * * (b) that takes a long time and a lot of memory to compute. * * 'Overlap well' means that the datasets match well in coordinate space. * * In some cases, datasets may match well voxel-wise, but the xyz coordinates * * defined in the dataset headers do not match -- in such a case, 3dQwarp * * will fail. This is why Zhark urges you to LOOK at the overlap in AFNI, * * which uses coordinates for display matching, not voxel indexes. Or use * * the '-allineate' option to get 3dAllineate to line up the dataset by * * brute force, just to be safe (at the cost of a some extra CPU time). * ****************************************************************************** * Outputs of 3dQwarp are the warped dataset and the warp that did it. ++ These datasets are stored in float format, no matter what the data type of the source dataset. ++ MANY other optional outputs are described later. * Simple example: 3dQwarp -allineate -blur 0 3 \ -base ~/abin/MNI152_2009_template_SSW.nii.gz \ -source sub637_T1.nii \ -prefix sub637_T1qw.nii which will produce a dataset warped to match the MNI152 T1 template at a 1 mm resolution. Since the MNI152 template is already somewhat blurry, the amount of blurring applied to it is set to zero, while the source dataset (presumably not blurry) will be Gaussian blurred with a FWHM of 3 mm. * Matching uses the 'clipped Pearson' method by default, and can be changed to 'pure Pearson' with the '-pear' option. ++ The purpose of 'clipping' is to reduce the impact of outlier values (small or large) on the correlation. ++ For the adventurous, you can also try these matching functions: '-hel' for Hellinger distance '-mi' for Mutual Information '-nmi' for Normalized Mutual Information These options have NOT been extensively tested for usefulness, and should be considered experimental at this infundibulum. ++ The 'local' correlation options are also now available: '-lpc' for Local Pearson minimization (i.e., EPI-T1 registration) '-lpa' for Local Pearson maximization (i.e., T1-FA registration) However, the '+ZZ' modifier is not available for these cost functions, unlike in program 3dAllineate :( These advanced cost options will slow 3dQwarp down significantly. ** For aligning EPI to T1, the '-lpc' option can be used; my advice would be to do something like the following: 3dSkullStrip -input SUBJ_anat+orig -prefix SUBJ_anatSS 3dbucket -prefix SUBJ_epiz SUBJ_epi+orig'[0]' align_epi_anat.py -anat SUBJ_anat+orig \ -epi SUBJ_epiz+orig -epi_base 0 -partial_axial \ -epi2anat -master_epi SUBJ_anat+orig \ -big_move 3dQwarp -source SUBJ_anatSS+orig.HEAD \ -base SUBJ_epiz_al+orig \ -prefix SUBJ_anatSSQ \ -lpc -maxlev 0 -verb -iwarp -blur 0 3 3dNwarpApply -nwarp SUBJ_anatSSQ_WARPINV+orig \ -source SUBJ_epiz_al+orig \ -prefix SUBJ_epiz_alQ * Zeroth, the T1 is prepared by skull stripping and the EPI is prepared by extracting just the 0th sub-brick for registration purposes. * First, the EPI is aligned to the T1 using the affine 3dAllineate, and at the same time resampled to the T1 grid (via align_epi_anat.py). * Second, it is nonlinearly aligned ONLY using the global warping -- it is futile to try to align such dissimilar image types precisely. * The EPI is used as the base in 3dQwarp so that it provides the weighting, and so partial brain coverage (as long as it covers MOST of the brain) should not cause a problem (fondly do we hope). * Third, 3dNwarpApply is used to take the inverse warp from 3dQwarp to transform the EPI to the T1 space, since 3dQwarp transformed the T1 to EPI space. This inverse warp was output by 3dQwarp using '-iwarp'. * Someday, this procedure may be incorporated into align_epi_anat.py :-) ** It is vitally important to visually look at the results of this process! ** * In humans, the central structures usually match a template very well, but smaller cortical gyri can match well in some places and not match in others. * In macaques, where there is less inter-animal variation, cortical matching will be better than humans (but not perfect). * For aligning T1-weighted anatomical volumes, Zhark recommends that you use the 3dUnifize program to (approximately) spatially uniformize and normalize their intensities -- this helps in the matching process, especially when using datasets from different scanners. ++ Skull stripping a la 3dSkullStrip is also a good idea (prior to 3dUnifize), even if you are registering datasets from the same subject; see the SAMPLE USAGE section below for an example. + But if you are matching to a skull-on template as the -base dataset, then keeping the skull on the -source dataset is necessary, since the goal of the program is to distort the source to 'look like' the base, and if major parts of the two datasets cannot be made to look like each other, the poor poor program will get lost in warp-land. ++ If you ultimately want a non-3dUnifize-d transformed dataset, you can use the output WARP dataset and 3dNwarpApply to transform the un-3dUnifize-d source dataset; again, see the SAMPLE USAGE section below. ++ Some people prefer to nonlinearly align datasets with the 'skull' left on. You are free to try this, of course, but we have not tested this method. + We give you tools; you build things with them (hopefully nice things). ++ Note again the script @SSwarper, which is for skull-stripping and warping a T1-weighted dataset to a template volume; AFNI provides such a template volume for the MNI152 space. * If for some deranged reason you have datasets with very non-cubical voxels, they should be resampled to a cubical grid before trying 3dQwarp. For example, if you have acquired 1x1x4 mm T1-weighted structural volumes (why?), then resample them to 1x1x1 mm before doing any other registration processing. For example: 3dAllineate -input anatT1_crude+orig -newgrid 1.0 \ -prefix anatT1_fine -final wsinc5 \ -1Dparam_apply '1D: 12@0'\' This operation will be done using the '-allineate' or '-resample' options to 3dQwarp, if the -base dataset has cubical voxels. ** Please note that this program is very CPU intensive, and is what computer scientists call a 'pig' (i.e., run time from 10s of minutes to hours). ------------ SAMPLE USAGE ~1~ ------------ * For registering a T1-weighted anat to a mildly blurry template at about a 1x1x1 mm resolution (note that the 3dAllineate step, to give the preliminary alignment, will also produce a dataset on the same 3D grid as the TEMPLATE+tlrc dataset, which 3dQwarp requires): 3dUnifize -prefix anatT1_U -input anatT1+orig 3dSkullStrip -input anatT1_U+orig -prefix anatT1_US -niter 400 -ld 40 3dAllineate -prefix anatT1_USA -base TEMPLATE+tlrc \ -source anatT1_US+orig -twopass -cost lpa \ -1Dmatrix_save anatT1_USA.aff12.1D \ -autoweight -fineblur 3 -cmass 3dQwarp -prefix anatT1_USAQ -blur 0 3 \ -base TEMPLATE+tlrc -source anatT1_USA+tlrc You can then use the anatT1_USAQ_WARP+tlrc dataset to transform other datasets (that were aligned with the input anatT1+orig) in the same way using program 3dNwarpApply, as in 3dNwarpApply -nwarp 'anatT1_USAQ_WARPtlrc anatT1_USA.aff12.1D' \ -source NEWSOURCE+orig -prefix NEWSOURCE_warped For example, if you want a warped copy of the original anatT1+orig dataset (without the 3dUnifize and 3dSkullStrip modifications), put 'anatT1' in place of 'NEWSOURCE' in the above command. Note that the '-nwarp' option to 3dNwarpApply has TWO filenames inside single quotes. This feature tells that program to compose (catenate) those 2 spatial transformations before applying the resulting warp. See the -help output of 3dNwarpApply for more sneaky/cunning ways to make the program warp datasets (and also see the example just below). ** PLEASE NOTE that if you use the '-allineate' option in 3dQwarp, to ** ** do the 3dAllineate step inside 3dQwarp, then you do NOT catenate ** ** the affine and nonlinear warps as in the 3dNwarpApply example above, ** ** since the output nonlinear warp will ALREADY have be catenated with ** ** the affine warp -- this output warp is the transformation directly ** ** between the '-source' and '-base' datasets (as is reasonable IZHO). ** If the NEWSOURCE+orig dataset is integer-valued (e.g., anatomical labels), then you would use the '-ainterp NN' with 3dNwarpApply, to keep the program from interpolating the voxel values. * If you use align_epi_anat.py to affinely transform several EPI datasets to match a T1 anat, and then want to nonlinearly warp the EPIs to the template, following the warp generated above, the procedure is something like this: align_epi_anat.py -anat anatT1+orig -epi epi_r1+orig \ -epi_base 3 -epi2anat -big_move \ -child_epi epi_r2+orig epi_r3+orig 3dNwarpApply -source epi_r1+orig \ -nwarp 'anatT1_USAQ_WARP+tlrc anatT1_USA.aff12.1D' \ -affter epi_r1_al_reg_mat.aff12.1D \ -master WARP -newgrid 2.0 \ -prefix epi_r1_AQ (mutatis mutandis for 'child' datasets epi_r2, epi_r3, etc.). The above procedure transforms the data directly from the un-registered original epi_r1+orig dataset, catenating the EPI volume registration transformations (epi_r1_al_reg_mat.aff12.1D) with the affine anat to template transformation (anatT1_USA.aff12.1D) and with the nonlinear anat to template transformation (anatT1_USAQ_WARP+tlrc). 3dNwarpApply will use the default 'wsinc5' interpolation method, which does not blur the results much -- an important issue for statistical analysis of the EPI time series. Various functions, such as volume change fraction (Jacobian determinant) can be calculated from the warp dataset via program 3dNwarpFuncs. -------------------- COMMAND LINE OPTIONS (too many of them) ~1~ -------------------- ++++++++++ Input and Outputs +++++++++++++ -base base_dataset = Alternative way to specify the base dataset. -source source_dataset = Alternative way to specify the source dataset. * You can either use both '-base' and '-source', OR you can put the base and source dataset names last on the command line. * But you cannot use just one of '-base' or '-source' and then put the other input dataset name at the end of the command line! *** Please note that if you are using 3dUnifize on one dataset (or the template was made with 3dUnifize-d datasets), then the other dataset should also be processed the same way for better results. This dictum applies in general: the source and base datasets should be pre-processed the same way, as far as practicable. -prefix ppp = Sets the prefix 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 '{prefix}_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 '{prefix}_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'. -->> (But: 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 '{prefix}_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 ... -nowarp = Do not save the _WARP file. * By default, the {prefix}_WARP dataset will be saved. -iwarp = Do compute and save the _WARPINV file. * By default, the {prefix}_WARPINV file is NOT saved. -nodset = Do not save the warped source dataset (i.e., if you only need the _WARP). * By default, the warped source dataset {prefix} is saved. -awarp = If '-allineate' is used, output the nonlinear warp that transforms from the 3dAllineate-d affine alignment of source-to-base to the base. This warp (output {prefix}_AWARP) combined with the affine transformation {prefix}.aff12.1D is the same as the final {prefix}_WARP nonlinear transformation directly from source-to-base. * The '-awarp' output is mostly useful when you need to have this incremental nonlinear warp for various purposes; for example, it is used in the @SSwarper script. * '-awarp' will not do anything unless '-allineate' is also used, because it doesn't have anything to do! * By default, this {prefix}_AWARP file is NOT saved. -inwarp = This option is for debugging, and is only documented here for completenes. * It causes an extra dataset to be written out whenever a warp is output. This dataset will have the string '_index' added to the warp dataset's prefix, as in 'Fred_AWARP_index.nii'. * This extra dataset contains the 'index warp', which is the internal form of the warp. * Instead of displacements between (x,y,z) coordinates, an index warp stores displacements between (i,j,k) 3D indexes. * An index warp dataset has no function outside of being something to look at when trying to figure out what the hell the program did. ++++++++++ Preliminary affine (linear transformation) alignment ++++++++++ -allineate = This option will make 3dQwarp run 3dAllineate first, to align *OR* the source dataset to the base with an affine transformation. -allin It will then use that alignment as a starting point for the *OR* nonlinear warping. -allinfast * With '-allineate', the source dataset does NOT have to be on the same 3D grid as the base, since the intermediate output of 3dAllineate (the substitute source) will be on the grid as the base. * If the datasets overlap reasonably already, you can use the option '-allinfast' (instead of '-allineate') to add the option '-onepass' to the 3dAllineate command line, to make it run faster (by avoiding the time-consuming coarse pass step of trying lots of shifts and rotations to find an idea of how to start). But you should KNOW that the datasets do overlap well before using '-allinfast'. (This fast option does include center-of-mass correction, so it will usually work well if the orientations of the two volumes are close -- say, within 10 degrees of each other.) -->>** The final output warp dataset is the warp directly between the original source dataset and the base (i.e., the catenation of the affine matrix from 3dAllineate and the nonlinear warp from the 'warpomatic' procedure in 3dQwarp). -->>** The above point means that you should NOT NOT NOT use the affine warp output by the '-allineate' option in combination with the nonlinear warp output by 3dQwarp (say, when using 3dNwarpApply), since the affine warp would then be applied twice -- which would be WRONG WRONG WRONG. -->>** The final output warped dataset is warped directly from the original source dataset, NOT from the substitute source. * The intermediate files from 3dAllineate (the substitute source dataset and the affine matrix) are saved, using 'prefix_Allin' in the filenames. *** The following 3dQwarp options CANNOT be used with -allineate: -plusminus -inilev -iniwarp * The '-awarp' option will output the computed warp from the intermediate 3dAllineate-d dataset to the base dataset, in case you want that for some reason. This option will only have meaning if '-allineate' or '-allinfast' is used. The prefix of the '-awarp' output will have the string '_AWARP' appended to the {prefix} for the output dataset. -allineate_opts '-opt ...' *OR* * This option lets you add extra options to the 3dAllineate -allopt command to be run by 3dQwarp. Normally, you won't need to do this. * Note that the default cost functional in 3dAllineate is the Hellinger metric ('-hel'); many people prefer '-lpa+ZZ', and so should use something like this: -allopt '-cost lpa+ZZ' to ensure 3dAllineate uses the desired cost functional. -> Note that if you use '-lpa' in 3dQwarp, then 3dAllineate will automatically be supplied with '-cost lpa+ZZ'. * If '-emask' is used in 3dQwarp, the same option will be passed to 3dAllineate automatically, so you don't have to do that yourself. *** Do NOT attempt to use the (obsolescent) '-nwarp' option in 3dAllineate from inside 3dQwarp -- bad things will probably happen, and you won't EVER get any birthday presents again! -resample = This option simply resamples the source dataset to match the *OR* base dataset grid. You can use this if the two datasets -resample mm overlap well (as seen in the AFNI GUI), but are not on the same 3D grid. * If they don't overlap very well, use '-allineate' instead. * As with -allineate, the final output dataset is warped directly from the source dataset, not from the resampled source dataset. * The reampling here (and with -allineate) 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 In particular, '-iniwarp' and '-resample' will work together if you need to re-start a warp job from the output of '-allsave'. * Unless you are in a hurry, '-allineate' is better. *** After '-resample', you can supply an affine transformation matrix to apply during the resampling. This feature is useful if you already have the affine transformation from source to base pre-computed by some other program -- for example, from 3dAllineate. The command line argument that follows '-resample', if it does not start with a '-', is taken to be a filename with 12 values in one row: the usual affine matrix representation from 3dAllineate and other AFNI programs (in DICOM order coordinates); for example '-resample ZharkRules.aff12.1D' You can also use the following form to supply the matrix directly on the command line: '1D: 1 2 3 4 5 6 7 8 9 10 11 12' where the numbers after the initial '1D: ' are to be replaced by the actual matrix entries! -aniso = Before aligning, do a little bit of anisotropic smoothing (see 3danisosmooth) on the source dataset. * Note that the final output dataset is warped directly from the input dataset, NOT this smoothed dataset. If you want the warped output dataset to be from the smoothed dataset, you'll have to use 3danisosmooth separately before 3dQwarp, and supply that result as the source dataset. * The purpose of '-aniso' is just to smooth out the noise a little before other processing, and maybe make things work a little betterer. * Anisotropic smoothing comes before 3dAllineate, if both are used together. ++++++++++ Computing the 'cost' functional = how datasets are matched ++++++++++ ** If '-allineate' is used, AND one of these options is given, then the ** ** corresponding option is also passed to 3dAllineate for its optimization. ** ** Otherwise, 3dAllineate will use its default optimization cost functional. ** -pcl = clipped Pearson correlation [default method]; clipping reduces the impact of outlier values. -pear = Use strict Pearson correlation for matching. * Not usually recommended, because without the clipping-ness used by '-pcl', then outliers can have more effect. * No partridges or trees are implied by this option. -hel = Hellinger metric -mi = Mutual information -nmi = Normalized mutual information -lpc = Local Pearson correlation (signed). -lpa = Local Pearson correlation (absolute value) * These options mirror those in 3dAllineate. * In particular, nonlinear warping of low resolution EPI data to T1 data is a difficult task, and can introduce more distortions to the result than it fixes. * If you use one of these 5 options, and also use '-allineate' or '-allinfast', then the corresponding option is passed to 3dAllineate: '-hel' => '-cost hel' '-mi' => '-cost mi' '-nmi' => '-cost nmi' '-lpc' => '-cost lpc+ZZ' '-lpa' => '-cost lpa+ZZ' '-pcl' or -pear' => '-cost ls' -noneg = Replace negative values in either input volume with 0. -zclip * 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. * Therefore, '-noneg' is recommended for most applications. -nopenalty = Don't use a penalty on the cost functional; the goal of the penalty is to reduce grid distortions. * If there penalty is turned off AND you warp down to a fine scale (e.g., '-minpatch 11'), you will probably get strange-looking results. -penfac ff = Use the number 'ff' to weight the penalty. The default value is 1. Larger values of 'ff' mean the penalty counts more, reducing grid distortions, insha'Allah; '-nopenalty' is the same as '-penfac 0'. -warpscale f = This option allows you to downsize the scale of the warp displacements for smaller patch sizes. In some applications, the amount of displacement allowed is overly aggressive at small patch sizes, but larger displacements at large patch sizes are needed to get the overall shapes of the base and template to match. The factor 'f' should be a number between 0.1 and 1.0 (inclusive), and indicates the amount the max displacement should shrink when the patch size shrinks by a factor of 10. I suggest '-warpscale 0.5' as a starting point for experimentation. * This option is currently [Feb 2020] for experimenting only, and in the future it may change! In particular, the equivalent of '-warpscale 0.5' may become the default. -useweight = With '-useweight', each voxel in the base automask is weighted by the intensity of the (blurred) base image. This makes white matter count more in T1-weighted volumes, for example. -->>* [24 Mar 2014] This option is is now the default. -wtgaus G = This option lets you define the amount of Gaussian smoothing applied to the base image when creating the weight volume. The default value of G is 4.5 (FWHM voxels). See the 'WEIGHT' section (far below) for details on how the automatic weight volume is calculated. Using '-wtgaus 0' means that no Gaussian blurring is applied in creating the weight. * [15 Jan 2020] This option is really just for fooling around. -noweight = If you want a binary weight (the old default), use this option. That is, each voxel in the base volume automask will be weighted the same in the computation of the cost functional. -weight www = 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 you want to emphasize or de-emphasize the matching functional. -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 (in mm)! * 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. -wmask ws f = 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. * You cannot use '-wball' and '-wmask' together! -wtprefix p = Saves auto-computed weight volume to a dataset with prefix 'p'. If you are sufficiently dedicated, you could manually edit this volume, in the AFNI GUI, in 3dcalc, et cetera. And then use it, instead of the auto-computed default weight, via the '-weight' option. * If you use the '-emask' option, the effects of the exclusion mask are NOT shown in this output dataset! -emask ee = Here, 'ee' is a dataset to specify a mask of voxels to EXCLUDE from the analysis -- all voxels in 'ee' that are NONZERO will not be used in the alignment. * The base image is always automasked -- the emask is extra, to indicate voxels you definitely DON'T want included in the matching process, even if they are inside the brain. -->>* Note that 3dAllineate has the same option. Since you usually have to use 3dAllineate before 3dQwarp, you will probably want to use -emask in both programs. [ Unless, of course, you are using '-allineate', which ] [ will automatically include '-emask' in the 3dAllineate ] [ phase if '-emask' is used here in 3dQwarp. ] * Applications: exclude a tumor or resected region (e.g., draw a mask in the AFNI Drawing plugin). -->>* Note that the emask applies to the base dataset, so if you are registering a pre- and post-surgery volume, you would probably use the post-surgery dataset as the base. If you eventually want the result back in the pre-surgery space, then you would use the inverse warp afterwards (in 3dNwarpApply). -inedge = Enhance interior edges in the base and source volumes, to make the cost functional give more weight to these edges. * This option MIGHT produce slightly better alignments, but its effect is usually small. * The output transformed source dataset will NOT have these enhanced edges; the enhancement is done internally on the volume image copies that are being matched. *** This option has been disabled, until problems with it can be resolved. Sorry .... 01 Apr 2021 [not a joke]. ++++++++++ Blurring the inputs (avoid trying to match TOO much detail) +++++++++ -blur bb = 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 might 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. -pblur = 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 be 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 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. -->>*** 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. -nopblur = Don't use '-pblur'; equivalent to '-pblur 0 0'. ++++++++++ Restricting the warp directions ++++++++++ -noXdis = These options let you specify that the warp should not -noYdis = displace in the given direction. For example, combining -noZdis = -noXdis and -noZdis would mean only warping along the y-direction would be allowed. * Here, 'x' refers to the first coordinate in the dataset, which is usually the Right-to-Left direction. Et cetera. * Note that the output WARP dataset(s) will have sub-bricks for the displacements which are all zero; every WARP dataset has 3 sub-bricks. ++++++++++ Controlling the warp calculation process in detail ++++++++++ -iniwarp ww = 'ww' is 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. * You can scale a 3D warp's displacements by prefixing the dataset name by 'FAC:a,b,c:Warpdatasetname' where a b c are numbers by which to scale the x- y- z-displacments. * As a special case, if you just input an affine matrix in a .1D file, that also works -- it is treated as giving the initial warp via the string "IDENT(base_dataset) matrix_file.aff12.1D". * -iniwarp is usually used with -inilev to re-start 3dQwarp from a previous stopping point, or from the output of '-allsave'. * In particular, '-iniwarp' and '-resample' will work together if you need to re-start a warp job from the output of '-allsave'. -inilev lv = 'lv' is the initial refinement 'level' at which to start. * The combination of -inilev and -iniwarp lets you take the results of a previous 3dQwarp run and refine them further: 3dQwarp -prefix Q25 -source SS+tlrc -base TEMPLATE+tlrc \ -minpatch 25 -blur 0 3 3dQwarp -prefix Q11 -source SS+tlrc -base TEMPLATE+tlrc \ -inilev 7 -iniwarp Q25_WARP+tlrc -blur 0 2 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. -->>** Also see the script @toMNI_Qwarpar for the use of this option in creating a template dataset from a collection of scans from different subjects. -minpatch mm = Set the minimum patch size for warp searching to 'mm' voxels. *OR* * The value of mm should be an odd integer. -patchmin mm * 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. * OpenMP parallelization becomes inefficient for patch sizes smaller than about 15x15x15 -- which is why running 3dQwarp down to the minimum patch level of 5 can be very slow. * 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, especially in the small foldings in the outer cerebral cortex. 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. ------------------- -maxlev lv = Here, 'lv' is the maximum refinement 'level' to use. This is an alternate way to specify when the program should stop. * To only do global polynomial warping, use '-maxlev 0'. * If you use both '-minpatch' and '-maxlev', then you are walking on the knife edge of danger. * Of course, I know that you LIVE for such thrills. -gridlist gl = 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. * You cannot use -gridlist with: -plusminus :( -allsave = This option lets you save the output warps from each level *OR* of the refinement process. Mostly used for experimenting. -saveall * Cannot be used with: -nopadWARP :( * You could use the saved warps to create different versions of the warped source datasets (using 3dNwarpApply), to help you visualize how the warping process makes progress. * The saved warps are written out at the end of each level, before the next level starts computation. Thus, they could be used to re-start the computation if the program crashed (by using options '-inilev' and '-iniwarp'). * If '-allsave' is used with '-plusminus', the intermediate saved warps are the "PLUS" half-warps (which are what the program is optimizing). -duplo = *** THIS OPTION IS NO LONGER AVAILABLE *** -workhard = 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. * Combined with '-lite', takes about the same amount of time as '-nolite' without '-workhard' :) * 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. -->>* 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. -Qfinal = 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. (((........... Also see the section 'The warp polynomials' below ...........))) -cubic12 = Use 12 parameter cubic polynomials, instead of 24 parameter polynomials (the current default patch warps are 24 parameter). * '-cubic12' will be faster than '-cubic24' and combining it with '-workhard' will make '-cubic12' run at about the same speed as the 24 parameter cubics. * Is it less accurate than '-cubic24'? That is very hard to say accurately without more work. In priniple, No. * This option is now the default. -cubic24 = Use 24 parameter cubic Hermite polynomials. * This is the older set of basis functions [pre-2019], and would normally be used only for backwards compatibility or for testing. -Qonly = Use Hermite quintic polynomials at all levels. * Very slow (about 4 times longer than cubic). * Will produce a (discrete representation of a) C2 warp. -Quint81 = When quintic polynomials are used, use the full 81 parameter set of basis functions. * This is the older set of basis functions [pre-2019], and would normally be used only for backwards compatibility or for testing. -Quint30 = Use the smaller 30 parameter set of quintic basis functions. * These options ('-Quint81' and '-Quint30') only change the operation if you also use some other option that implies the use of quintic polynomials for warping. -lite = Another way to specify the use of the 12 parameter cubics and the 30 parameter quintics. * This option now works with the '-plusminus' warping method :) * THIS OPTION IS NOW THE DEFAULT * [Jan 2019] -nolite = Turn off the '-lite' warp functions and use the 24 parameter cubics *and* the 81 parameter quintics. * This option is present for if you wish to have backwards warping compatibility with older versions of 3dQwarp. -nopad = Do NOT use zero-padding on the 3D base and source images. [Default == zero-pad as 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. ++ If the base dataset is closely cropped, so that the edges of its 3D grid come close to the significant part of the volume, using '-nopad' may cause poor fitting of the source to the base, as the distortions required near the grid edges will not be available in the restricted model. For this reason, Zhark recommends that you do NOT use '-nopad'. * 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 option '-nopadWARP', allowing zero- padding (i.e., the default operation) will make the output WARP dataset(s) be on a larger grid (also see '-expad' below). **** When grid centers of the base and source dataset are far apart in (x,y,z) coordinates, then a large amount of zero-padding is required to make the grid spaces overlap. This situation can cause problems, and most often arises when the (x,y,z)=(0,0,0) point in the source grid is in a corner of the volume instead of the middle. You can fix that problem by using a command like @Align_Centers \ -base MNI152_2009_template_SSW.nii.gz \ -dset Fred.nii and then using dataset Fred_shft.nii as your input file for all purposes (including afni_proc.py). ++ One problem that happens with very large spatial shifts (from 3dAllineate initial alignment) is that the warp dataset can be very huge. Not only does this cause a large file on output, it also uses a lot of memory in the 3dQwarp optimization - so much memory in some cases to cause the program to crash. * A warning message will be output to the screen if very large amounts of zero-padding are required. * Intermediate between large amounts of padding and no padding is the option below: -Xpad = Puts an upper limit on the amount of padding, to prevent huge warp datasets from being created. -nopadWARP = If you do NOT use '-nopad' (that is, you DO allow zero-padding during the warp computations), then the computed warp will often be bigger than the base volume. This situation is normally not an issue, but if for some reason you require the warp volume to match the base volume, then use '-nopadWARP' to have the output WARP dataset(s) truncated. * Note that 3dNwarpApply and 3dNwarpAdjust will deal with warps that are defined over grids that are larger than the datasets to which they are applied; this is why Zhark says above that a padded warp 'is normally not an issue'. * However, if you want to use an AFNI nonlinear warp in some external non-AFNI program, you might have to use this option :( -expad EE = 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 you might later catenate the nonlinear warp -- via 3dNwarpCat -- with an affine transformation that contains a large shift. Under that circumstance, the nonlinear warp might be shifted partially outside its original grid, so expanding that grid can avoid this problem. * Note that this option perforce turns off '-nopadWARP'. -ballopt = Normally, the incremental warp parameters are optimized inside a rectangular 'box' (e.g., 24 dimensional for cubic patches, 81 for quintic patches), which limits the amount of distortion allowed at each step. Using '-ballopt' switches these limits to be applied to a 'ball' (interior of a hypersphere), which can allow for larger incremental displacements. Use this option if you think things need to be able to move farther. * Note also that the '-lite' polynomial warps allow for larger incremental displacements than the '-nolite' warps. -boxopt = 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 optimization are alternated in the different iterations at each level, so these two options have no effect in that case. ++++++++++ Meet-in-the-middle warping - Also know as '-plusminus' +++++++++ -plusminus = 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))) *** Also see the '-pmBASE' option described below. -->>* Alas: -plusminus does not work with: -allineate :-( ++ If a prior linear alignment is needed, it will have to be done "manually" using 3dAllineate, and then use the output of that program as the '-source' dataset for 3dQwarp. ++ -plusminus works well if the base and source datasets are reasonably well-aligned to start with. By this, I mean that they overlap well, are not wildly rotated from each other, and need some 'wiggling' to make them aligned. -->>++ This option is basically meant for unwarping EPI data, as described above. * 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. * If you use '-iniwarp' with '-plusminus', the warp dataset to provide with '-iniwarp' is the '_PLUS' warp. That is, you can't use a "full base-to-source warp" for the initial warp (one reason '-allineate' doesn't work with '-plusminus'). -pmNAMES p m = This option lets you change the PLUS and MINUS prefix appendages alluded to directly above to something else that might be more easy for you to grok. For example, if you are warping EPI volumes with phase-encoding in the LR-direction with volumes that had phase-encoding in the RL-direction, you might do something like -base EPI_LR+orig -source EPI_RL+orig -plusminus -pmNAMES RL LR -prefix EPIuw recalling that the PLUS name goes with the source (RL) and the MINUS name goes with the base (RL). Then you'd end up with datasets EPIuw_LR+orig and EPIuw_LR_WARP+orig from the base EPIuw_RL+orig and EPIuw_RL_WARP+orig from the source The EPIuw_LR_WARP+orig file could then be used to unwarp (e.g., using 3dNwarpApply) other LR-encoded EPI datasets from the same scanning session. -pmBASE = With '-plusminus', computes the V(x) warp (source to base) from the plusminus half-warp, and writes it to disk. Also writes out the source dataset warped to base space, in addition to the Wp(x) '_PLUS' and Wm(x) '_MINUS' results * Sneaky aside: if you want potentially larger displacements than 'normal' 3dQwarp, use '-plusminus', since the meet-in-the- middle approach will allow the full-size displacements in EACH of the half-warps, so that the overall displacement between base and source can be larger. The use of '-pmBASE' will let you get the source-transformed-to-base result at the end. If you don't want the plusminus 'in-the-middle' outputs, just delete them later. ++++++++++ How 'LOUD' do you want this program to be? ++++++++++ -verb = Print out very verbose progress messages (to stderr) :-) -quiet = Cut out most of the fun fun fun progress messages :-( ----------------------------------- INTERRUPTING the program gracefully ~1~ ----------------------------------- If you want to stop the program AND have it write out the results up to the current point, you can do so with a Unix command like kill -s QUIT processID where 'processID' is the process identifier number (pid) for the 3dQwarp program you want to terminate. A command like ps aux | grep 3dQwarp will give you a list of all your processes with the string '3dQwarp' in the command line. For example, at the moment I wrote this text, I would get the response rwcox 62873 693.8 2.3 3274496 755284 p2 RN+ 12:36PM 380:25.26 3dQwarp -prefix ... rwcox 6421 0.0 0.0 2423356 184 p0 R+ 1:33PM 0:00.00 grep 3dQwarp rwcox 6418 0.0 0.0 2563664 7344 p4 S+ 1:31PM 0:00.15 vi 3dQwarp.c so the processID for the actual run of 3dQwarp was 62873. (Also, you can see that Zhark is a 'vi' acolyte, not an 'emacs' heretic.) The program will 'notice' the QUIT signal at the end of the optimization of the next patch, so it may be a moment or two before it actually saves the output dataset(s) and exits. Of course, if you just want to kill the process in a brute force way, with nothing left behind to examine, then 'kill processID' will work. Using 'kill -s QUIT' combined with '-allsave' might be useful in some circumstances. At least to get some idea of what happened before you were forced to stop 3dQwarp. --------------------------------------------------------------------- CLARIFICATION about the very confusing forward and inverse warp issue ~1~ --------------------------------------------------------------------- An AFNI nonlinear warp dataset stores the displacements (in DICOM mm) from the base dataset grid to the source dataset grid. For computing the source dataset warped to the base dataset grid, these displacements are needed, so that for each grid point in the output (warped) dataset, the corresponding location in the source dataset can be found, and then the value of the source at that point can be computed (interpolated). That is, this forward warp is good for finding where a given point in the base dataset maps to in the source dataset. However, for finding where a given point in the source dataset maps to in the base dataset, the inverse warp is needed. Or, if you wish to warp the base dataset to 'look like' the source dataset, then you use 3dNwarpApply with the input warp being the inverse warp from 3dQwarp. --------------------------- STORAGE of 3D warps in AFNI ~1~ --------------------------- AFNI stores a 3D warp as a 3-volume dataset (NiFTI or AFNI format), with the voxel values being the displacements in mm (32-bit floats) needed to 'reach out' and bring (interpolate) another dataset into alignment -- that is, 'pulling it back' to the grid defined in the warp dataset header. Thus, the identity warp is all zero. These 3 volumes I refer to as ‘xd’, ‘yd’, and ‘zd’ in the internal comments, and they store (delta-x,delta-y,delta-z) respectively (duh). There is no provision in the warping software for 2D-only warps; that is, warping one 2D image to another will still result in a 3D warp, with the zd brick being chock full of zeros. This happenstance rarely occurs, since Zhark believes he is the only person who actually has run the AFNI warping program on 2D images. In AFNI, (xd,yd,zd) are stored internally in DICOM order, in which +x=Left, +y=Posterior, +z=Superior (LPS+); thus, DICOM x and y are sign-reversed from the customary 'neuroscience order' RAS+. Note that the warp dataset grid need not be stored in this same DICOM (x,y,z) order, which is sometimes confusing. In the template datasets to which we nonlinearly warp data, we always use DICOM order for the grids, so in practice warps generated in AFNI are usually also physically ordered in the DICOM way -- but of course, someone can run our warping software any which way they like and so get a warp dataset whose grid order is not DICOM. But the (xd,yd,zd) entries will be in DICOM order. On occasion (for example, when composing warps), the math will want the displacement from a location outside of the warp dataset’s grid domain. Originally, AFNI just treated those ghost displacements as zero or as equal to the (xd,yd,zd) value at the closest edge grid point. However, this method sometimes led to unhappy edge effects, and so now the software linearly extrapolates the (xd,yd,zd) fields from each of the 6 faces of the domain box to allow computation of such displacements. These linear coefficients are computed from the warp displacement fields when the warp dataset is read in, and so are not stored in the warp dataset header. Inverse warps are computed when needed, and are not stored in the same dataset with the forward warp. At one time, I thought that I’d always keep them paired, but that idea fell by the wayside. AFNI does not make use of deformation fields stored in datasets; that is, it does not store or use datasets whose components are (x+xd,y+yd,z+zd). Such a dataset could easily be computed with 3dcalc, of course. There is no special header code in an AFNI warp dataset announcing that 'I am a warp!' By AFNI convention, 3D warp datasets have the substring '_WARP' in their name, and inverse warps '_WARPINV'. But this is just a convention, and no software depends on this being true. When AFNI warps 2 input datasets (A and B) together to 'meet in the middle' via the '-plusminus' option (vs. bringing dataset A to be aligned directly to B), two warp files are produced, one with the warp that brings A to the middle 'point' and one which brings 'B' to the middle point. These warps are labeled with '_PLUS_WARP' and '_MINUS_WARP' in their filenames, as in 'Fred_PLUS_WARP.nii'. ('PLUS' and 'MINUS' can be altered via the '-pmNAMES' option to 3dQwarp.) If one is dealing only with affine transformation of coordinates, these are stored (again referring to transformation of coordinates in DICOM order) in plain ASCII text files, either with 3 lines of 4 numbers each, (with the implicit last row of the matrix being 0 0 0 1, as usual). or as all 12 numbers catenated into a single line (first 4 numbers are the first row of the matrix, et cetera). This latter format is always used when dealing with time-dependent affine transformations, as from FMRI time series registration. A single matrix can be stored in either format. At present, there is no provision for storing time-dependent nonlinear warp datasets, since the use case has not arisen. When catenating a time-dependent affine transform and a nonlinear warp (e.g., for direct transformation from original EPI data to MNI space), the individual nonlinear warp for each time point is computed and applied on-the-fly. Similarly, the inverse warp can be computed on-the-fly, rather than being stored permanently. Such on-the-fly warp+apply calculations are done in program 3dNwarpApply. ----------------------------------- OUTLINE of warp optimization method ~1~ ----------------------------------- Repeated composition of incremental warps defined by Hermite cubic basis functions, first over the entire volume, then over steadily shrinking and overlapping patches at increasing 'levels': the patches shrink by a factor of 0.75 at each level. Patches at levels 1 and higher have a 50% overlap. NOTE: Internally, warps are stored as 'index warps', which are displacements between 3D (i,j,k) grid indexes rather than between (x,y,z) coordinates. The reason for this approach is that indexes are what is needed to find the location in a dataset that a warp maps to. On output and on input, the (x,y,z) displacements are converted from/to (i,j,k) displacements. The '-inwarp' option allows you to output an 'index warp' dataset, but this dataset has no function other than looking at it in order to understand what the program was working with internally. At 'level 0' (1 patch over the entire volume), Hermite quintic basis functions are also employed, but these are not used at the more refined levels -- unless one of the '-Qxxx' options is used. All basis functions herein are (at least) continuously differentiable, so the discrete warp computed can be thought of as a representation of an underlying C1 diffeomorphism. The basis functions go to zero at the edge of each patch, so the overall warp will decay to the identity warp (displacements=0) at the edge of the base volume. (However, use of '-allineate' can make the final output warp be nonzero at the edges; the programs that apply warps to datasets linearly extrapolate warp displacements outside the 3D box over which the warp is defined.) NOTE: * Option '-Qfinal' will use quintic polynomials at the final (smallest) patch level. * Option '-Qonly' will use quintic polynomials at all patch levels. * Option '-Workhard' will run optimization on each patch twice, first using cubic polynomials and later using quintic polynomials. For this procedure to work, the source and base datasets need to be reasonably well aligned already (e.g., via 3dAllineate, if necessary), as the nonlinear optimization can only deal with relatively small displacements -- fractions of a patch size.. Multiple warps can later be composed and applied via program 3dNwarpApply and/or 3dNwarpCat. Note that it is not correct to say that the resulting warp is a piecewise cubic (or quintic) polynomial. The first warp created (at level 0) is such a warp; call that W0(x). Then the incremental warp W1(x) applied at the next iteration is also a cubic polynomial warp (say), and the result is W0(W1(x)), which is more complicated than a cubic polynomial -- and so on. The incremental warps aren't added, but composed, so that the mathematical form of the final warp would be very unwieldy to express in polynomial form. Of course, the program just keeps track of the displacements, not the polynomial coefficients, so it doesn't 'care' much about the underlying polynomials at all One reason for incremental improvement by composition, rather than by addition, is the simple fact that if W0(x) is invertible and W1(x) is invertible, then W0(W1(x)) is also invertible -- but W0(x)+W1(x) might not be. The incremental polynomial warps are kept invertible by simple constraints on the magnitudes of their coefficients (i.e., the maximum size of incremental displacements). The penalty is a Neo-Hookean elastic energy function, based on a combination of bulk and shear distortions: cf. http://en.wikipedia.org/wiki/Neo-Hookean_solid The goal is to keep the warps from becoming too 'weird' (doesn't always work). By perusing the many options above, you can see that the user can control the warp optimization in various ways. All these options make using 3dQwarp seem pretty complicated. The reason there are so many options is that many different cases arise, and we are trying to make the program flexible enough to deal with them all. The SAMPLE USAGE section above is a good place to start for guidance. *OR* you can use the @SSwarper or auto_warp.py scripts. -------------- The warp polynomials: '-lite' and '-nolite' ---------------- ~1~ The '-nolite' cubics have 8 basis functions per spatial dimension, since they are the full tensor product of the 2 Hermite cubics H0 and H1: H0(x)*H0(y)*H0(z) H1(x)*H0(y)*H0(z) H0(x)*H1(y)*H0(z) H0(x)*H0(y)*H1(z) H1(x)*H1(y)*H0(z) H1(x)*H0(y)*H1(z) H0(x)*H1(y)*H1(z) H1(x)*H1(y)*H1(z) and then there are 3 sets of these for x, y, and z displacements, giving 24 total basis functions for a cubic 3D warp patch. The '-lite' cubics omit any of the tensor product functions whose indexes sum to more than 1, so there are only 4 basis functions per spatial dimension: H0(x)*H0(y)*H0(z) H1(x)*H0(y)*H0(z) H0(x)*H1(y)*H0(z) H0(x)*H0(y)*H1(z) yielding 12 total basis functions (again, 3 of each function above for each spatial dimension). The 2 1D basis functions, defined over the interval [-1,1], and scaled to have maximum magnitude 1, are H0(x) = (1-abs(x))^2 * (1+2*abs(x)) // H0(0) = 1 H0'(0) = 0 H1(x) = (1-abs(x))^2 * x * 6.75 // H1(0) = 0 H1'(0) = 6.75 H1(1/3) = 1 These functions and their first derivatives are 0 at x=+/-1, which is apparent from the '(1-abs(x))^2' factor they have in common. The functions are also continuous and differentiable at x=0; thus, they and their unit translates can serve as a basis for C1(R): the Banach space of continuously differentiable functions on the real line. One effect of using the '-lite' polynomial warps is that 3dQwarp runs faster, since there are fewer parameters to optimize for each patch. Accuracy should not be imparied,as the approximation quality (in the mathematical sense) of the '-lite' polynomials is the same order as the '-nolite' full tensor product. Another effect is that the upper limits on the displacements by any individual warp patch are somewhat larger than for the full basis set, which may be useful in some situations. Similarly, the '-nolite' quintics have 27 basis functions per spatial dimension, since they are the tensor products of the 3 Hermite quintics Q0, Q1, Q2. The '-lite' quintics omit any tensor product whose indexes sum to more than 2. Formulae for these 3 polynomials can be found in function HQwarp_eval_basis() in AFNI file mri_nwarp.c. For each monomial Qi(x), Qi(+/-1)=Qi'(+/-1)=Qi''(+/-1) = 0; these functions are twice continuously differentiable, and can serve as a basis for C2(R). --------- Why is it 'cost functional' and not 'cost function' ??? -------- ~1~ In mathematics, a 'functional' is a function that maps an object in an infinite dimensional space to a scalar. A typical example of a functional is a function of a function, such as I(f) = definite integral from -1 to 1 of f(x) dx. In this example, 'f' is a function, which is presumed to be integrable, and thus an element of the infinite dimensional linear space denoted by L1(-1,1). Thus, as Zhark was brutally trained in his mathematics bootcamp, the value being optimized, being a number (scalar) that is calculated from a function (warp), the 'machine' that calculates this value is a 'functional'. It also gets the word 'cost' attached as it is something the program is trying to reduce, and everyone wants to reduce the cost of what they are buying, right? (AFNI does not come with coupons :-) ------------------- WEIGHT construction ~1~ ------------------- The cost functional is computed giving (potentially) different weights to different voxels. The default weight 3D volume is constructed from the base dataset as follows (i.e., this is what '-useweight' does): (0) Take absolute value of each voxel value. (1) Zero out voxels within 4% of each edge (i.e., 10 voxels in a 256x256x256 dataset). (2) Define L by applying the '3dClipLevel -mfrac 0.5' algorithm and then multiplying the result by 3. Then, any values over this L 'large' value are reduced to L -- i.e., spikes are squashed. (3) A 3D median filter over a ball with radius 2.25 voxels is applied to further squash any weird stuff. (This radius is fixed.) (4) A Gaussian blur of FWHM '-wtgaus' is applied (default = 4.5 voxels). (5) Define L1 = 0.05 times the maximum of the result from (4). Define L2 = 0.33 times '3dClipLevel -mfrac 0.33' applied to (4). Define L = max(L1,L2). Create a binary mask of all voxels from (4) that are >= L. Find the largest contiguous cluster in that mask, erode it a little, and then again find the largest cluster in what remains. (The purpose of this to is guillotine off any small 'necks'.) Zero out all voxels in (4) that are NOT in this surviving cluster. (6) Scale the result from (5) to the range 0..1. This is the weight volume. (X) Remember you can save the computed weight volume to a dataset by using the '-wtprefix' option. Where did this scheme come from? A mixture of experimentation, intuition, and plain old SWAG. ------------------------------------------------------------------------------- ***** This program is experimental and subject to sudden horrific change! ***** ((((( OK, it's less experimental now, and so sudden changes will be mild. ))))) ------------------------------------------------------------------------------- ----- AUTHOR = Zhark the Grotesquely Warped -- Fall/Winter/Spring 2012-13 ----- ----- (but still strangely handsome) ----- ========================================================================= * This binary version of 3dQwarp is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. * Tests show that using more 12-16 CPUs with 3dQwarp doesn't help much. If you have more CPUs on one system, it's faster to run two or three separate registration jobs in parallel than to use all the CPUs on one 3dQwarp task at a time. =========================================================================

AFNI program: 3dRank
Usage: 3dRank [-prefix PREFIX] <-input DATASET1 [DATASET2 ...]> Replaces voxel values by their rank in the set of values collected over all voxels in all input datasets If you input one dataset, the output should be identical to the -1rank option in 3dmerge This program only works on datasets of integral storage type, and on integral valued data stored as floats. -input DATASET1 [DATASET2 ...]: Input datasets. Acceptable data types are: byte, short, and floats. -prefix PREFIX: Output prefix. If you have multiple datasets on input the prefix is preceded by r00., r01., etc. If no prefix is given, the default is rank.DATASET1, rank.DATASET2, etc. In addition to the ranked volume, a rank map 1D file is created. It shows the mapping from the rank (1st column) to the integral values (2nd column) in the input dataset. Sub-brick float factors are ignored. -ver = print author and version info -help = print this help screen INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dRankizer
++ 3dRankizer: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: Zhark of the Ineffable Rank Usage: 3dRankizer [options] dataset Output = Rank of each voxel as sorted into increasing value. - Ties get the average rank. - Not the same as 3dRank! - Only sub-brick #0 is processed at this time! - Ranks start at 1 and increase: Input = 0 3 4 4 7 9 Output = 1 2 3.5 3.5 5 6 Options: -brank bbb Set the 'base' rank to 'bbb' instead of 1. (You could also do this with 3dcalc.) -mask mset Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be used from 'dataset'. Voxels outside the mask will get rank 0. -prefix ppp Write results into float-format dataset 'ppp' Output is in float format to allow for non-integer ranks resulting from ties. -percentize : Divide rank by the number of voxels in the dataset x 100.0 -percentize_mask : Divide rank by the number of voxels in the mask x 100.0 Author: RW Cox [[a quick hack for his own purposes]] ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3drefit
++ 3drefit: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: RW Cox Changes some of the information inside a 3D dataset's header. ~1~ Note that this program does NOT change the .BRIK file at all; the main purpose of 3drefit is to fix up errors made when using to3d. To see the current values stored in a .HEAD file, use the command '3dinfo dataset'. Using 3dinfo both before and after 3drefit is a good idea to make sure the changes have been made correctly! 20 Jun 2006: 3drefit will now work on NIfTI datasets (but it will write out the entire dataset, into the current working directory) Usage: 3drefit [options] dataset ... ~1~ where the options are -quiet Turn off the verbose progress messages -orient code Sets the orientation of the 3D volume(s) in the .BRIK. The code must be 3 letters, one each from the pairs {R,L} {A,P} {I,S}. The first letter gives the orientation of the x-axis, the second the orientation of the y-axis, the third the z-axis: R = right-to-left L = left-to-right A = anterior-to-posterior P = posterior-to-anterior I = inferior-to-superior S = superior-to-inferior ** WARNING: when changing the orientation, you must be sure to check the origins as well, to make sure that the volume is positioned correctly in space. -xorigin distx Puts the center of the edge voxel off at the given -yorigin disty distance, for the given axis (x,y,z); distances in mm. -zorigin distz (x=first axis, y=second axis, z=third axis). Usually, only -zorigin makes sense. Note that this distance is in the direction given by the corresponding letter in the -orient code. For example, '-orient RAI' would mean that '-zorigin 30' sets the center of the first slice at 30 mm Inferior. See the to3d manual for more explanations of axes origins. ** SPECIAL CASE: you can use the string 'cen' in place of a distance to force that axis to be re-centered. -xorigin_raw xx Puts the center of the edge voxel at the given COORDINATE -yorigin_raw yy rather than the given DISTANCE. That is, these values -zorigin_raw zz directly replace the offsets in the dataset header, without any possible sign changes. -duporigin cset Copies the xorigin, yorigin, and zorigin values from the header of dataset 'cset'. -dxorigin dx Adds distance 'dx' (or 'dy', or 'dz') to the center -dyorigin dy coordinate of the edge voxel. Can be used with the -dzorigin dz values input to the 'Nudge xyz' plugin. ** WARNING: you can't use these options at the same time you use -orient. ** WARNING: consider -shift_tags if dataset has tags -xdel dimx Makes the size of the voxel the given dimension, -ydel dimy for the given axis (x,y,z); dimensions in mm. -zdel dimz ** WARNING: if you change a voxel dimension, you will probably have to change the origin as well. -keepcen When changing a voxel dimension with -xdel (etc.), also change the corresponding origin to keep the center of the dataset at the same coordinate location. -xyzscale fac Scale the size of the dataset voxels by the factor 'fac'. This is equivalent to using -xdel, -ydel, -zdel together. -keepcen is used on the first input dataset, and then any others will be shifted the same amount, to maintain their alignment with the first one. ** WARNING: -xyzscale can't be used with any of the other options that change the dataset grid coordinates! ** N.B.: 'fac' must be positive, and using fac=1.0 is stupid. -TR time Changes the TR time to a new value (see 'to3d -help'). ** You can also put the name of a dataset in for 'time', in which case the TR for that dataset will be used. ** N.B.: If the dataset has slice time offsets, these will be scaled by the factor newTR/oldTR. This scaling does not apply if you use '-Tslices' in the same 3drefit run. -notoff Removes the slice-dependent time-offsets. -Torg ttt Set the time origin of the dataset to value 'ttt'. (Time origins are set to 0 in to3d.) ** WARNING: These 3 options apply only to 3D+time datasets. **N.B.: Using '-TR' on a dataset without a time axis will add a time axis to the dataset. -Tslices a b c d ... Reset the slice time offsets to be 'a', 'b', 'c', ... (in seconds). The number of values following '-Tslices' should be the same as the number of slices in the dataset, but 3drefit does NOT check that this is true. ** If any offset time is < 0 or >= TR, a warning will be printed (to stderr), but this is not illegal even though it is a bad idea. ** If the dataset does not have a TR set, then '-Tslices' will fail. You can use '-TR' to set the inter-volume time spacing in the same 3drefit command. ** If you have the slices times stored (e.g., from DICOM) in some other units, you can scale them to be in seconds by putting a scale factor after the '-Tslices' option as follows: -Tslices '*0.001' 300 600 900 ... which would be used to scale from milliseconds to seconds. The format is to start the scale factor with a '*' to tell 3drefit that this number is not a slice offset but is to be used a a scale factor for the rest of the following values. Since '*' is a filename wildcard, it needs to be in quotes! ** The program stops looking for number values after '-Tslices' when it runs into something that does not look like a number. Here, 'look like a number' means a character string that: * starts with a digit 0..9 * starts with a decimal point '.' followed by a digit * starts with a minus sign '-' followed by a digit * starts with '-.' followed by a digit So if the input dataset name starts with a digit, and the last command line option '-Tslices', 3drefit will think the filename is actually a number for a slice offset time. To avoid this problem, you can do one of these things: * Put in an option that is just the single character '-' * Don't use '-Tslices' as the last option * Put a directory name before the dataset name, as in './Galacticon.nii' ** If you have the slice time offsets stored in a text file as a list of values, then you can input these values on the command line using the Unix backquote operator, as in -Tslices `cat SliceTimes.1D` ** For example, if the slice time offsets are in a JSON sidecar (a la BIDS), you might be able to something like the following to extract the timings into a file: abids_json_tool.py -json2txt -input sub-10506_task-pamenc_bold.json -prefix junk.txt grep SliceTiming junk.txt | sed -e 's/^SliceTiming *://' > SliceTimes.1D \rm junk.txt -newid Changes the ID code of this dataset as well. -nowarp Removes all warping information from dataset. -apar aset Set the dataset's anatomy parent dataset to 'aset' ** N.B.: The anatomy parent is the dataset from which the transformation from +orig to +acpc and +tlrc coordinates is taken. It is appropriate to use -apar when there is more than 1 anatomical dataset in a directory that has been transformed. In this way, you can be sure that AFNI will choose the correct transformation. You would use this option on all the +orig dataset that are aligned with 'aset' (i.e., that were acquired in the same scanning session). ** N.B.: Special cases of 'aset' aset = NULL --> remove the anat parent info from the dataset aset = SELF --> set the anat parent to be the dataset itself -wpar wset Set the warp parent (the +orig version of a +tlrc dset). This option is used by @auto_tlrc. Do not use it unless you know what you're doing. -clear_bstat Clears the statistics (min and max) stored for each sub-brick in the dataset. This is useful if you have done something to modify the contents of the .BRIK file associated with this dataset. -redo_bstat Re-computes the statistics for each sub-brick. Requires reading the .BRIK file, of course. Also does -clear_bstat before recomputing statistics, so that if the .BRIK read fails for some reason, then you'll be left without stats. -statpar v ... Changes the statistical parameters stored in this dataset. See 'to3d -help' for more details. -markers Adds an empty set of AC-PC markers to the dataset, if it can handle them (is anatomical, is in the +orig view, and isn't 3D+time). ** WARNING: this will erase any markers that already exist! -shift_tags Apply -dxorigin (and y and z) changes to tags. -dxtag dx Add dx to the coordinates of all tags. -dytag dy Add dy to the coordinates of all tags. -dztag dz Add dz to the coordinates of all tags. -view code Changes the 'view' to be 'code', where the string 'code' is one of 'orig', 'acpc', or 'tlrc'. ** WARNING: The program will also change the .HEAD and .BRIK filenames to match. If the dataset filenames already exist in the '+code' view, then this option will fail. You will have to rename the dataset files before trying to use '-view'. If you COPY the files and then use '-view', don't forget to use '-newid' as well! ** WARNING2: Changing the view without specifying the new might lead to conflicting information. Consider specifying the space along with -view -space spcname Associates the dataset with a specific template type, e.g. TLRC, MNI, ORIG. The default assumed for +tlrc datasets is 'TLRC'. One use for this attribute is to use MNI space coordinates and atlases instead of the default TLRC space. ** See WARNING2 for -view option. -cmap cmaptype Associate colormap type with dataset. Available choices are CONT_CMAP (the default), INT_CMAP (integer colormap display) and SPARSE_CMAP (for sparse integer colormaps). INT_CMAP is appropriate for showing ROI mask datasets or Atlas datasets where the continuous color scales are not useful. -label2 llll Set the 'label2' field in a dataset .HEAD file to the string 'llll'. (Can be used as in AFNI window titlebars.) -labeltable TTT Inset the label table TTT in the .HEAD file. The label table format is described in README.environment under the heading: 'Variable: AFNI_VALUE_LABEL_DTABLE' See also -copytables -denote Means to remove all possibly-identifying notes from the header. This includes the History Note, other text Notes, keywords, and labels. -deoblique Replace transformation matrix in header with cardinal matrix. This option DOES NOT deoblique the volume. To do so you should use 3dWarp -deoblique. This option is not to be used unless you really know what you're doing. -oblique_origin assume origin and orientation from oblique transformation matrix rather than traditional cardinal information -oblique_recenter Adjust the origin so that the cardinalized 0,0,0 is in the same brain location as that of the original (oblique?) (scanner?) coordinates. Round this to the nearest voxel center. * Even if cardinal, rounding might cause an origin shift (see -oblique_recenter_raw). -oblique_recenter_raw Like -oblique_recenter, but do not round. So coordinate 0,0,0 is in the exact same location, even if not at a voxel center. -byteorder bbb Sets the byte order string in the header. Allowable values for 'bbb' are: LSB_FIRST MSB_FIRST NATIVE_ORDER Note that this does not change the .BRIK file! This is done by programs 2swap and 4swap. -checkaxes Doesn't alter the input dataset; rather, this just checks the dataset axes orientation codes and the axes matrices for consistency. (This option was added primarily to check for bugs in various codes.) -appkey ll Appends the string 'll' to the keyword list for the whole dataset. -repkey ll Replaces the keyword list for the dataset with the string 'll'. -empkey Destroys the keyword list for the dataset. -atrcopy dd nn Copy AFNI header attribute named 'nn' from dataset 'dd' into the header of the dataset(s) being modified. For more information on AFNI header attributes, see documentation file README.attributes. More than one '-atrcopy' option can be used. **N.B.: This option is for those who know what they are doing! Without the -saveatr option, this option is meant to be used to alter attributes that are NOT directly mapped into dataset internal structures, since those structures are mapped back into attribute values as the dataset is being written to disk. If you want to change such an attribute, you have to use the corresponding 3drefit option directly or use the -saveatr option. If you are confused, try to understand this: Option -atrcopy was never intended to modify AFNI- specific attributes. Rather, it was meant to copy user-specific attributes that had been added to some dataset using -atrstring option. A cursed day came when it was convenient to use -atrcopy to copy an AFNI-specific attribute (BRICK_LABS to be exact) and for that to take effect in the output, the option -saveatr was added. Contact Daniel Glen and/or Rick Reynolds for further clarification and any other needs you may have. Do NOT use -atrcopy or -atrstring with other modification options. See also -copyaux -atrstring n 'x' Copy the string 'x' into the dataset(s) being modified, giving it the attribute name 'n'. To be safe, the 'x' string should be in quotes. **N.B.: You can store attributes with almost any name in the .HEAD file. AFNI will ignore those it doesn't know anything about. This technique can be a way of communicating information between programs. However, when most AFNI programs write a new dataset, they will not preserve any such non-standard attributes. **N.B.: Special case: if the string 'x' is of the form 'file:name', then the contents of the file 'name' will be read in as a single string and stored in the attribute. -atrfloat name 'values' -atrint name 'values' Create or modify floating point or integer attributes. The input values may be specified as a single string in quotes or as a 1D filename or string. For example, 3drefit -atrfloat IJK_TO_DICOM_REAL '1 0.2 0 0 -0.2 1 0 0 0 0 1 0' dset+orig 3drefit -atrfloat IJK_TO_DICOM_REAL flipZ.1D dset+orig 3drefit -atrfloat IJK_TO_DICOM_REAL \ '1D:1,0.2,2@0,-0.2,1,2@0,2@0,1,0' \ dset+orig Almost all afni attributes can be modified in this way -saveatr (default) Copy the attributes that are known to AFNI into the dset->dblk structure thereby forcing changes to known attributes to be present in the output. This option only makes sense with -atrcopy **N.B.: Don't do something like copy labels of a dataset with 30 sub-bricks to one that has only 10, or vice versa. This option is for those who would deservedly earn a hunting license. -nosaveatr Opposite of -saveatr Example: 3drefit -saveatr -atrcopy WithLabels+tlrc BRICK_LABS NeedsLabels+tlrc -'type' Changes the type of data that is declared for this dataset, where 'type' is chosen from the following: ANATOMICAL TYPES spgr == Spoiled GRASS fse == Fast Spin Echo epan == Echo Planar anat == MRI Anatomy ct == CT Scan spct == SPECT Anatomy pet == PET Anatomy mra == MR Angiography bmap == B-field Map diff == Diffusion Map omri == Other MRI abuc == Anat Bucket FUNCTIONAL TYPES fim == Intensity fith == Inten+Thr fico == Inten+Cor fitt == Inten+Ttest fift == Inten+Ftest fizt == Inten+Ztest fict == Inten+ChiSq fibt == Inten+Beta fibn == Inten+Binom figt == Inten+Gamma fipt == Inten+Poisson fbuc == Func-Bucket -copyaux auxset Copies the 'auxiliary' data from dataset 'auxset' over the auxiliary data for the dataset being modified. Auxiliary data comprises sub-brick labels, keywords, statistics codes, nodelists, and labeltables AND/OR atlas point lists. '-copyaux' occurs BEFORE the '-sub' operations below, so you can use those to alter the auxiliary data that is copied from auxset. -copytables tabset Copies labeltables AND/OR atlas point lists, if any, from tabset to the input dataset. '-copyaux' occurs BEFORE the '-sub' operations below, so you can use those to alter the auxiliary data that is copied from tabset. -relabel_all xx Reads the file 'xx', breaks it into strings, and puts these strings in as the sub-brick labels. Basically a batch way of doing '-sublabel' many times, for n=0, 1, ... ** This option is executed BEFORE '-sublabel', so any labels from '-sublabel' will over-ride labels from this file. ** Strings in the 'xx' file are separated by whitespace (blanks, tabs, new lines). -relabel_all_str 'lab0 lab1 ... lab_p': Just like -relabel_all but with labels all present in one string -sublabel_prefix PP: Prefix each sub-brick's label with PP -sublabel_suffix SS: Suffix each sub-brick's label with SS The options below attach auxiliary data to sub-bricks in the dataset. ~1~ Each option may be used more than once so that multiple sub-bricks can be modified in a single run of 3drefit. -sublabel n ll Attach to sub-brick #n the label string 'll'. -subappkey n ll Add to sub-brick #n the keyword string 'll'. -subrepkey n ll Replace sub-brick #n's keyword string with 'll'. -subempkey n Empty out sub-brick #n' keyword string -substatpar n type v ... Attach to sub-brick #n the statistical type and the auxiliary parameters given by values 'v ...', where 'type' is one of the following: Stat Types: ~2~ type Description PARAMETERS ---- ----------- ---------------------------------------- fico Cor SAMPLES FIT-PARAMETERS ORT-PARAMETERS fitt Ttest DEGREES-of-FREEDOM fift Ftest NUMERATOR and DENOMINATOR DEGREES-of-FREEDOM fizt Ztest N/A fict ChiSq DEGREES-of-FREEDOM fibt Beta A (numerator) and B (denominator) fibn Binom NUMBER-of-TRIALS and PROBABILITY-per-TRIAL figt Gamma SHAPE and SCALE fipt Poisson MEAN You can also use option '-unSTAT' to remove all statistical encodings from sub-bricks in the dataset. This operation would be desirable if you modified the values in the dataset (e.g., via 3dcalc). ['-unSTAT' is done BEFORE the '-substatpar' operations, so you can ] [combine these options to completely redo the sub-bricks, if needed.] [Option '-unSTAT' also implies that '-unFDR' will be carried out. ] The following options allow you to modify VOLREG fields: ~1~ -vr_mat val1 ... val12 Use these twelve values for VOLREG_MATVEC_index. -vr_mat_ind index Index of VOLREG_MATVEC_index field to be modified. Optional, default index is 0. NB: You can only modify one VOLREG_MATVEC_index at a time -vr_center_old x y z Use these 3 values for VOLREG_CENTER_OLD. -vr_center_base x y z Use these 3 values for VOLREG_CENTER_BASE. The following options let you modify the FDR curves stored in the header: ~1~ -addFDR = For each sub-brick marked with a statistical code, (re)compute the FDR curve of z(q) vs. statistic, and store in the dataset header * '-addFDR' runs as if '-new -pmask' were given to 3dFDR, so that stat values == 0 will be ignored in the FDR algorithm. -FDRmask mset = load dataset 'mset' and use it as a mask -STATmask mset for the '-addFDR' calculations. * This can be useful if you ran 3dDeconvolve/3dREMLFIT without a mask, and want to apply a mask to improve the FDR estimation procedure. * If '-addFDR' is NOT given, then '-FDRmask' does nothing. * 3drefit does not generate an automask for FDR purposes (unlike 3dREMLfit and 3dDeconvolve), since the input dataset may contain only statistics and no structural information about the brain. -unFDR = Remove all FDR curves from the header [you will want to do this if you have done something to ] [modify the values in the dataset statistical sub-bricks] ++ Last program update: 27 Mar 2009 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dRegAna
++ 3dRegAna: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program performs multiple linear regression analysis. Usage: 3dRegAna -rows n number of input datasets -cols m number of X variables -xydata X11 X12 ... X1m filename X variables and Y observations . . . . . . -xydata Xn1 Xn2 ... Xnm filename X variables and Y observations -model i1 ... iq : j1 ... jr definition of linear regression model; reduced model: Y = f(Xj1,...,Xjr) full model: Y = f(Xj1,...,Xjr,Xi1,...,Xiq) [-diskspace] print out disk space required for program execution [-workmem mega] number of megabytes of RAM to use for statistical workspace (default = 750 (was 12)) [-rmsmin r] r = minimum rms error to reject constant model [-fdisp fval] display (to screen) results for those voxels whose F-statistic is > fval [-flof alpha] alpha = minimum p value for F due to lack of fit The following commands generate individual AFNI 2 sub-brick datasets: [-fcoef k prefixname] estimate of kth regression coefficient along with F-test for the regression is written to AFNI `fift' dataset [-rcoef k prefixname] estimate of kth regression coefficient along with coef. of mult. deter. R^2 is written to AFNI `fith' dataset [-tcoef k prefixname] estimate of kth regression coefficient along with t-test for the coefficient is written to AFNI `fitt' dataset The following commands generate one AFNI 'bucket' type dataset: [-bucket n prefixname] create one AFNI 'bucket' dataset having n sub-bricks; n=0 creates default output; output 'bucket' is written to prefixname The mth sub-brick will contain: [-brick m coef k label] kth parameter regression coefficient [-brick m fstat label] F-stat for significance of regression [-brick m rstat label] coefficient of multiple determination R^2 [-brick m tstat k label] t-stat for kth regression coefficient [-datum DATUM] write the output in DATUM format. Choose from short (default) or float. N.B.: For this program, the user must specify 1 and only 1 sub-brick with each -xydata command. That is, if an input dataset contains more than 1 sub-brick, a sub-brick selector must be used, e.g.: -xydata 2.17 4.59 7.18 'fred+orig[3]' INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dReHo
REHO/Kendall W code, written by PA Taylor (July, 2012), part of FATCAT (Taylor & Saad, 2013) in AFNI. ReHo (regional homogeneity) is just a renaming of the Kendall's W (or Kendall's coefficient of concordance, KCC, (Kendall & Babington Smith, 1939)) for set of time series. Application to fMRI data was described in paper: <<Regional homogeneity approach to fMRI data analysis>> by Zang, Jiang, Lu, He, and Tiana (2004, NeuroImage), where it was applied to the study of both task and resting state functional connectivity (RSFC). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + USAGE: This program is made to read in data from 4D time series data set and to calculate Kendall's W per voxel using neighborhood voxels. Instead of the time series values themselves, Kendall's W uses the relative rank ordering of a 'hood over all time points to evaluate a parameter W in range 0-1, with 0 reflecting no trend of agreement between time series and 1 reflecting perfect agreement. From W, one can simply get Friedman's chi-square value (with degrees of freedom equal to `the length of the time series minus one'), so this can also be calculated here and returned in the second sub-brick: chi-sq = (N_n)*(N_t - 1)*W, with N_dof = N_t - 1, where N_n is the size of neighborhood; N_t is the number of time points; W is the ReHo or concordance value; and N_dof is the number of degrees of freedom. A switch is included to have the chi-sq value output as a subbrick of the ReHo/W. (In estimating W, tied values are taken into account by averaging appropriate rankings and adjusting other factors in W appropriately, which only makes a small difference in value, but the computational time still isn't that bad). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: 3dReHo -prefix PREFIX -inset FILE {-nneigh 7|19|27} \ {-chi_sq} {-mask MASK} {-in_rois INROIS} * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + RUNNING, need to provide: -prefix PREFIX :output file name part. -inset FILE :time series file. -chi_sq :switch to output Friedman chi-sq value per voxel as a subbrick. -mask MASK :can include a whole brain mask within which to calculate ReHo. Otherwise, data should be masked already. -nneigh NUMBER :number of voxels in neighborhood, inclusive; can be: 7 (for facewise neighbors, only), 19 (for face- and edge-wise neighbors), 27 (for face-, edge-, and node-wise neighbors). The default is: 27. -neigh_RAD R :for additional voxelwise neighborhood control, the radius R of a desired neighborhood can be put in; R is a floating point number, and must be >1. Examples of the numbers of voxels in a given radius are as follows (you can roughly approximate with the ol' 4*PI*(R^3)/3 thing): R=2.0 -> V=33, R=2.3 -> V=57, R=2.9 -> V=93, R=3.1 -> V=123, R=3.9 -> V=251, R=4.5 -> V=389, R=6.1 -> V=949, but you can choose most any value. -neigh_X A -neigh_Y B :as if *that* weren't enough freedom, you can even have -neigh_Z C ellipsoidal volumes of voxelwise neighbors. This is done by inputing the set of semi-radius lengths you want, again as floats/decimals. The 'hood is then made according to the following relation: (i/A)^2 + (j/B)^2 + (k/C)^2 <=1. which will have approx. V=4*PI*A*B*C/3. The impetus for this freedom was for use with data having anisotropic voxel edge lengths. -box_RAD BR :for additional voxelwise neighborhood control, the one can make a cubic box centered on a given voxel; BR specifies the number of voxels outward in a given cardinal direction, so the number of voxels in the volume would be as follows: BR=1 -> V=27, BR=2 -> V=125, BR=3 -> V=343, etc. In this case, BR should only be integer valued. -box_X BA -box_Y BB :as if that *still* weren't enough freedom, you can have -box_Z BC box volume neighborhoods of arbitrary dimension; these values put in get added in the +/- directions of each axis, so the volume in terms of number of voxels would be calculated: if BA = 1, BB = 2 and BC = 4, then V = (1+2*1)*(1+2*2)*(1+2*4) = 135. --> NB: you can't mix-n-match '-box_*' and '-neigh_*' settings. Mi dispiace (ma sol'un po). -in_rois INROIS :can input a set of ROIs, each labelled with distinct integers. ReHo will be calculated per ROI. The output for this info is in a file called PREFIX_ROI_reho.vals (or PREFIX_ROI_reho_000.vals, PREFIX_ROI_reho_001.vals, etc. if the INROIS has >1 subbrick); if `-chi_sq' values are being output, then those values for the ROIs will be output in an analogously formatted file called PREFIX_ROI_reho.chi (with similar zeropadded numbering for multibrick input). As of March, text format in the *.vals and *.chi files has changed: it will be 2 columns of numbers per file, with the first column being the ROI (integer) value and the second column being the ReHo or Chi-sq value. Voxelwise ReHo will still be calculated and output. + OUTPUT: [A] single file with name, e.g., PREFIX+orig.BRIK, which may have two subbricks (2nd subbrick if `-chi_sq' switch is used): [0] contains the ReHo (Kendall W) value per voxel; [1] contains Friedman chi-square of ReHo per voxel (optional); note that the number of degrees of freedom of this value is the length of time series minus 1. [B] can get list of ROI ReHo values, as well (optional). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dReHo \ -mask MASK+orig. \ -inset REST+orig \ -prefix REST_REHO \ -neigh_RAD 2.9 \ -chi_sq * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________

AFNI program: 3dREMLfit
Usage: 3dREMLfit [options] ~1~ **** Generalized least squares time series fit, with REML **** **** estimation of the temporal auto-correlation structure. **** --------------------------------------------------------------------- **** The recommended way to use 3dREMLfit is via afni_proc.py, **** **** which will pre-process the data, and also give some useful **** **** diagnostic tools/outputs for assessing the data's quality. **** **** [afni_proc.py will make your FMRI-analysis life happier!] **** --------------------------------------------------------------------- * This program provides a generalization of 3dDeconvolve: it allows for serial correlation in the time series noise. * It solves the linear equations for each voxel in the generalized (prewhitened) least squares sense, using the REML estimation method to find a best-fit ARMA(1,1) model for the time series noise correlation matrix in each voxel (i.e., each voxel gets a separate pair of ARMA parameters). ++ Note that the 2-parameter ARMA(1,1) correlation model is hard-coded into this program -- there is no way to use a more elaborate model, such as the 5-parameter ARMA(3,2), in 3dREMLfit. ++ A 'real' REML optimization of the autocorrelation model is made, not simply an adjustment based on the residuals from a preliminary OLSQ regression. ++ See the section 'What is ARMA(1,1)' (far below) for more fun details. ++ And the section 'What is REML' (even farther below). * You MUST run 3dDeconvolve first to generate the input matrix (.xmat.1D) file, which contains the hemodynamic regression model, censoring and catenation information, the GLTs, etc. See the output of '3dDeconvolve -help' for information on using that program to setup the analysis. ++ However, you can input a 'naked' (non-3dDeconvolve) matrix file using the '-matim' option, if you know what you are doing. * If you don't want the 3dDeconvolve analysis to run, you can prevent that by using 3dDeconvolve's '-x1D_stop' option. * 3dDeconvolve also prints out a cognate command line for running 3dREMLfit, which should get you going with relative ease. * The output datasets from 3dREMLfit are structured to resemble the corresponding results from 3dDeconvolve, to make it easy to adapt your scripts for further processing. * Is this type of analysis (generalized least squares) important? That depends on your point of view, your data, and your goals. If you really want to know the answer, you should run your analyses both ways (with 3dDeconvolve and 3dREMLfit), through to the final step (e.g., group analysis), and then decide if your neuroscience/brain conclusions depend strongly on the type of linear regression that was used. * If you are planning to use 3dMEMA for group analysis, then using 3dREMLfit instead of 3dDeconvolve is a good idea. 3dMEMA uses the t-statistic of the beta weight as well as the beta weight itself -- and the t-values from 3dREMLfit are probably more more accurate than those from 3dDeconvolve, since the underlying variance estimate should be more accurate (less biased). * When there is significant temporal correlation, and you are using 'IM' regression (estimated individual betas for each event), the REML GLSQ regression can be superior to OLSQ beta estimates -- in the sense that the resulting betas have somewhat less variance with GLSQ than with OLSQ. ------------------------------------------- Input Options (the first two are mandatory) ~1~ ------------------------------------------- -input ddd = Read time series dataset 'ddd'. * This is the dataset without censoring! * The '-matrix' file, on the other hand, encodes which time points are to be censored, and the matrix stored therein is already censored. * The doc below has a discussion of censoring in 3dREMLfit: https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/remlfit.html -matrix mmm = Read the matrix 'mmm', which should have been output from 3dDeconvolve via the '-x1D' option. ** N.B.: You can omit entirely defining the regression matrix, but then the program will fabricate a matrix consisting of a single column with all 1s. This option is mostly for the convenience of the author; for example, to have some fun with an AR(1) time series: 1deval -num 1001 -expr 'gran(0,1)+(i-i)+0.7*z' > g07.1D 3dREMLfit -input g07.1D'{1..$}'' -Rvar -.1D -grid 5 -MAXa 0.9 ** N.B.: 3dREMLfit now supports all zero columns, if you use the '-GOFORIT' option. [Ides of March, MMX A.D.] More Primitive Alternative Ways to Define the Regression Matrix -------------------------------------------------------------------------- -polort P = If no -matrix option is given, AND no -matim option, create a matrix with Legendre polynomial regressors up to order 'P'. The default value is P=0, which produces a matrix with a single column of all ones. (That is the default matrix described above.) -matim M = Read a standard .1D file as the matrix. * That is, an ASCII files of numbers layed out in a rectangular array. The number of rows must equal the number of time points in the input dataset. The number of columns is the number of regressors. * Advanced features, such as censoring, can only be implemented by providing a true .xmat.1D file via the '-matrix' option. ** However, censoring can still be applied (in a way) by including extra columns in the matrix. For example, to censor out time point #47, a column that is 1 at time point #47 and zero at all other time points can be used. ++ Remember that AFNI counting starts at 0, so this column would start with 47 0s, then a single 1, then the rest of the entries would be 0s. ++ 3dDeconvolve option '-x1D_regcensored' will create such a .xmat.1D file, with the censoring indicated by 0-1 columns rather than by the combination of 'GoodList' and omitted rows. That is, instead of shrinking the matrix (by rows) it will expand the matrix (by columns). ++ You can strip out the XML-ish header from the .xmat.1D file with a Unix command like this: grep -v '^#' Fred.xmat.1D > Fred.rawmat.1D ++ In cases with lots of censoring, expanding the matrix by lots of columns will make 3dREMLfit run more slowly. For most situations, this slowdown will not be horrific. * An advanced intelligence could reverse engineer the XML format used by the .xmat.1D files, to fully activate all the regression features of this software :) ** N.B.: You can use only 'Col' as a name in GLTs ('-gltsym') with these nonstandard matrix input methods, since the other column names come from the '-matrix' file. ** These mutually exclusive options are ignored if -matrix is used. ---------------------------------------------------------------------------- The matrix supplied is the censored matrix, if any time points are marked as to be removed from the analysis -- that is, if GoodList (infra) is NOT the entire list of time points from 0..(nrow-1). Information supplied in the .xmat.1D format XML header's attributes includes the following (but is not limited to): * ColumnLabels = a string label for each column in the matrix * ColumnGroups = groupings of columns into associated regressors (e.g., motion, baseline, task) * RowTR = TR in seconds * GoodList = list of time points to use (inverse of censor list) * NRowFull = size of full matrix (without censoring) * RunStart = time point indexes of start of the runs * Nstim = number of distinct stimuli * StimBots = column indexes for beginning of each stimulus's regressors * StimTops = column indexes for ending of each stimulus's regressors * StimLabels = names for each stimulus * CommandLine = string of command used to create the file See the doc below for a lengthier description of the matrix format: https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/remlfit.html ---------------------------------------------------------------------------- --------------- Masking options ~1~ --------------- -mask MMM = Read dataset 'MMM' as a mask for the input; voxels outside the mask will not be fit by the regression model. -automask = If you don't know what this does by now, I'm not telling. *** If you don't specify ANY mask, the program will build one automatically (from each voxel's RMS) and use this mask SOLELY for the purpose of computing the FDR curves in the bucket dataset's header. * If you DON'T want this to happen, then use '-noFDR' and later run '3drefit -addFDR' on the bucket dataset. * To be precise, the FDR automask is only built if the input dataset has at least 5 voxels along each of the x and y axes, to avoid applying it when you run 3dREMLfit on 1D timeseries inputs. -STATmask ss = Build a mask from file 'ss', and use this for the purpose of computing the FDR curves. * The actual results ARE not masked with this option (only with '-mask' or '-automask' options). * If you don't use '-STATmask', then the mask from '-mask' or '-automask' is used for the FDR work. If neither of those is given, then the automatically generated mask described just above is used for FDR. -------------------------------------------------------------------------- Options to Add Baseline (Null Hypothesis) Columns to the Regression Matrix ~1~ -------------------------------------------------------------------------- -addbase bb = You can add baseline model columns to the matrix with this option. Each column in the .1D file 'bb' will be appended to the matrix. This file must have at least as many rows as the matrix does. * Multiple -addbase options can be used, if needed. * More than 1 file can be specified, as in -addbase fred.1D ethel.1D elvis.1D * None of the .1D filename can start with the '-' character, since that is the signal for the next option. * If the matrix from 3dDeconvolve was censored, then this file (and '-slibase' files) can either be censored to match, OR 3dREMLfit will censor these .1D files for you. + If the column length (number of rows) of the .1D file is the same as the column length of the censored matrix, then the .1D file WILL NOT be censored. + If the column length of the .1D file is the same as the column length of the uncensored matrix, then the .1D file WILL be censored -- the same rows excised from the matrix in 3dDeconvolve will be resected from the .1D file before the .1D file's columns are appended to the matrix. + The censoring information from 3dDeconvolve is stored in the matrix file header, and you don't have to provide it again on the 3dREMLfit command line. -dsort dset = Similar to -addbase in concept, BUT the dataset 'dset' provides a different baseline regressor for every voxel. This dataset must have the same number of time points as the input dataset, and have the same number of voxels. [Added 22 Jul 2015] + The REML (a,b) estimation is done WITHOUT this extra voxel-wise regressor, and then the selected (a,b) ARMA parameters are used to do the final regression for the '-R...' output datasets. This method is not ideal, but the alternative of re-doing the (a,b) estimation with a different matrix for each voxel would be VERY slow. -- The -dsort estimation is thus different from the -addbase and/or -slibase estimations, in that the latter cases incorporate the extra regressors into the REML estimation of the ARMA (a,b) parameters. The practical difference between these two methods is usually very small ;-) + If any voxel time series from -dsort is constant through time, the program will print a warning message, and peculiar things might happen. Gleeble, fitzwilly, blorten, et cetera. -- Actually, if this event happens, the 'offending' -dsort voxel time series is replaced by the mean time series from that -dsort dataset. + The '-Rbeta' (and/or '-Obeta') option will include the fit coefficient for the -dsort regressor (last). + There is no way to include the -dsort regressor beta in a GLT. + You can use -dsort more than once. Please don't go crazy. + Using this option slows the program down in the GLSQ loop, since a new matrix and GLT set must be built up and torn down for each voxel separately. -- At this time, the GLSQ loop is not OpenMP-ized. +++ This voxel-wise regression capability is NOT implemented in 3dDeconvolve, so you'll have to use 3dREMLfit if you want to use this method, even if you only want ordinary least squares regression. + The motivation for -dsort is to apply ANATICOR to task-based FMRI analyses. You might be clever and have a better idea!? http://www.ncbi.nlm.nih.gov/pmc/articles/PMC2897154/ https://afni.nimh.nih.gov/pub/dist/doc/program_help/afni_proc.py.html -dsort_nods = If '-dsort' is used, the output datasets reflect the impact of the voxel-wise regressor(s). If you want to compare those results to the case where you did NOT give the '-dsort' option, then also use '-dsort_nods' (nods is short for 'no dsort'). The linear regressions will be repeated without the -dsort regressor(s) and the results put into datasets with the string '_nods' added to the prefix. -slibase bb = Similar to -addbase in concept, BUT each .1D file 'bb' must have an integer multiple of the number of slices in the input dataset; then, separate regression matrices are generated for each slice, with the [0] column of 'bb' appended to the matrix for the #0 slice of the dataset, the [1] column of 'bb' appended to the matrix for the #1 slice of the dataset, and so on. For example, if the dataset has 3 slices and file 'bb' has 6 columns, then the order of use is bb[0] --> slice #0 matrix bb[1] --> slice #1 matrix bb[2] --> slice #2 matrix bb[3] --> slice #0 matrix bb[4] --> slice #1 matrix bb[5] --> slice #2 matrix ** If this order is not correct, consider -slibase_sm. * 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. * Slices are the 3rd dimension in the dataset storage order -- 3dinfo can tell you what that direction is: Data Axes Orientation: first (x) = Right-to-Left second (y) = Anterior-to-Posterior third (z) = Inferior-to-Superior [-orient RAI] In the above example, the slice direction is from Inferior to Superior, so the columns in the '-slibase' input file should be ordered in that direction as well. * '-slibase' will slow the program down, and make it use a lot more memory (to hold all the matrix stuff). *** At this time, 3dSynthesize has no way of incorporating the extra baseline timeseries from -addbase or -slibase or -dsort. *** Also see option '-dsort' for how to include voxel-dependent regressors into the analysis. -slibase_sm bb = Similar to -slibase above, BUT each .1D file 'bb' must be in slice major order (i.e. all slice0 columns come first, then all slice1 columns, etc). For example, if the dataset has 3 slices and file 'bb' has 6 columns, then the order of use is bb[0] --> slice #0 matrix, regressor 0 bb[1] --> slice #0 matrix, regressor 1 bb[2] --> slice #1 matrix, regressor 0 bb[3] --> slice #1 matrix, regressor 1 bb[4] --> slice #2 matrix, regressor 0 bb[5] --> slice #2 matrix, regressor 1 ** If this order is not correct, consider -slibase. -usetemp = 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. * '-usetemp' can actually speed the program up, interestingly, even if you have enough RAM to hold all the intermediate matrices needed with '-slibase'. YMMV :) * '-usetemp' also writes temporary files to store dataset results, which can help if you are creating multiple large dataset (e.g., -Rfitts and -Rerrts in the same program run). * Temporary files are written to the directory given in environment variable TMPDIR, or in /tmp, or in ./ (preference is in that order). + If the program crashes, these files are named REML_somethingrandom, and you might have to delete them manually. + If the program ends normally, it will delete these temporary files before it exits. + Several gigabytes of disk space might be used for this temporary storage! + When running on a cluster, or some other system using networked storage, '-usetemp' will work MUCH better if the temporary storage directory is a local drive rather than a networked drive. You will have to figure out how to do this on your cluster, since configurations vary so much. * If you are at the NIH, then see this Web page: https://hpc.nih.gov/docs/userguide.html#local * If the program crashes with a 'malloc failure' type of message, then try '-usetemp' (malloc=memory allocator). *** NOTE THIS: If a Unix program stops suddenly with the mysterious one word message 'killed', then it almost certainly ran over some computer system limitations, and was immediately stopped without any recourse. Usually the resource it ran out of is memory. So if this happens to you when running 3dREMLfit, try using the '-usetemp' option! * '-usetemp' disables OpenMP multi-CPU usage. Only use this option if you need to, since OpenMP should speed the program up significantly on multi-CPU computers. -nodmbase = By default, baseline columns added to the matrix via '-addbase' or '-slibase' or '-dsort' will each have their mean removed (as is done in 3dDeconvolve). If you do NOT want this operation performed, use '-nodmbase'. * Using '-nodmbase' would make sense if you used '-polort -1' to set up the matrix in 3dDeconvolve, and/or you actually care about the fit coefficients of the extra baseline columns (in which case, don't use '-nobout'). ------------------------------------------------------------------------ Output Options (at least one must be given; 'ppp' = dataset prefix name) ~1~ ------------------------------------------------------------------------ -Rvar ppp = dataset for saving REML variance parameters * See the 'What is ARMA(1,1)' section, far below. * This dataset has 6 volumes: [0] = 'a' = ARMA parameter = decay rate of correlations with lag [1] = 'b' = ARMA parameter [2] = 'lam' = (b+a)(1+a*b)/(1+2*a*b+b*b) = correlation at lag=1 correlation at lag=k is lam * a^(k-1) (k>0) [3] = 'StDev' = standard deviation of prewhitened residuals (used in computing statistics in '-Rbuck' and in GLTs) [4] = '-LogLik' = negative of the REML log-likelihood function (see the math notes) [5] = 'LjungBox'= Ljung-Box statistic of the pre-whitened residuals, an indication of how much temporal correlation is left-over. + See the 'Other Commentary' section far below for a little more information on the LB statistic. * The main purpose of this dataset is to check when weird things happen in the calculations. Or just to have fun. -Rbeta ppp = dataset for beta weights from the REML estimation [similar to the -cbucket output from 3dDeconvolve] * 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. -Rbuck ppp = dataset for beta + statistics from the REML estimation; also contains the results of any GLT analysis requested in the 3dDeconvolve setup. [similar to the -bucket output from 3dDeconvolve] * This dataset does NOT get the betas (or statistics) of those regressors marked as 'baseline' in the matrix file. * If the matrix file from 3dDeconvolve does not contain 'Stim attributes' (which will happen if all inputs to 3dDeconvolve were labeled as '-stim_base'), then -Rbuck won't work, since it is designed to give the statistics for the 'stimuli' and there aren't any matrix columns labeled as being 'stimuli'. * In such a case, to get statistics on the coefficients, you'll have to use '-gltsym' and '-Rglt'; for example, to get t-statistics for all coefficients from #0 to #77: -tout -Rglt Colstats -gltsym 'SYM: Col[[0..77]]' ColGLT where 'Col[3]' is the generic label that refers to matrix column #3, et cetera. * FDR curves for so many statistics (78 in the example) might take a long time to generate! -Rglt ppp = dataset for beta + statistics from the REML estimation, but ONLY for the GLTs added on the 3dREMLfit command line itself via '-gltsym'; GLTs from 3dDeconvolve's command line will NOT be included. * Intended to give an easy way to get extra contrasts after an earlier 3dREMLfit run. * Use with '-ABfile vvv' to read the (a,b) parameters from the earlier run, where 'vvv' is the '-Rvar' dataset output from that run. [If you didn't save the '-Rvar' file, then it will] [be necessary to redo the REML loop, which is slow] -fout = put F-statistics into the bucket dataset -rout = put R^2 statistics into the bucket dataset -tout = put t-statistics into the bucket dataset [if you use -Rbuck and do not give any of -fout, -tout,] [or -rout, then the program assumes -fout is activated.] -noFDR = do NOT add FDR curve data to bucket datasets [FDR curves can take a long time if -tout is used] -nobout = do NOT add baseline (null hypothesis) regressor betas to the -Rbeta and/or -Obeta output datasets. ['stimulus' columns are marked in the .xmat.1D matrix ] [file; all other matrix columns are 'baseline' columns] -Rfitts ppp = dataset for REML fitted model [like 3dDeconvolve, a censored time point gets] [the actual data values from that time index!!] -Rerrts ppp = dataset for REML residuals = data - fitted model [like 3dDeconvolve, a censored time] [point gets its residual set to zero] -Rwherr ppp = dataset for REML residual, whitened using the estimated ARMA(1,1) correlation matrix of the noise [Note that the whitening matrix used is the inverse ] [of the Choleski factor of the correlation matrix C; ] [however, the whitening matrix isn't uniquely defined] [(any matrix W with C=inv(W'W) will work), so other ] [whitening schemes could be used and these would give] [different whitened residual time series datasets. ] -gltsym g h = read a symbolic GLT from file 'g' and label it with string 'h' * As in 3dDeconvolve, you can also use the 'SYM:' method to put the definition of the GLT directly on the command line. * The symbolic labels for the stimuli are as provided in the matrix file, from 3dDeconvolve. *** Unlike 3dDeconvolve, you supply the label 'h' for the output coefficients and statistics directly after the matrix specification 'g'. * Like 3dDeconvolve, the matrix generated by the symbolic expression will be printed to the screen unless environment variable AFNI_GLTSYM_PRINT is NO. * These GLTs are in addition to those stored in the matrix file, from 3dDeconvolve. * If you don't create a bucket dataset using one of -Rbuck or -Rglt (or -Obuck / -Oglt), using -gltsym is completely pointless and stupid! ** Besides the stimulus labels read from the matrix file (put there by 3dDeconvolve), you can refer to regressor columns in the matrix using the symbolic name 'Col', which collectively means all the columns in the matrix. 'Col' is a way to test '-addbase' and/or '-slibase' regressors for significance; for example, if you have a matrix with 10 columns from 3dDeconvolve and add 2 extra columns to it, then you could use -gltsym 'SYM: Col[[10..11]]' Addons -tout -fout to create a GLT to include both of the added columns (numbers 10 and 11). -- 'Col' cannot be used to test the '-dsort' regressor for significance! The options below let you get the Ordinary Least SQuares outputs (without adjustment for serial correlation), for comparisons. These datasets should be essentially identical to the results you would get by running 3dDeconvolve (with the '-float' option!): -Ovar ppp = dataset for OLSQ st.dev. parameter (kind of boring) -Obeta ppp = dataset for beta weights from the OLSQ estimation -Obuck ppp = dataset for beta + statistics from the OLSQ estimation -Oglt ppp = dataset for beta + statistics from '-gltsym' options -Ofitts ppp = dataset for OLSQ fitted model -Oerrts ppp = dataset for OLSQ residuals (data - fitted model) [there is no -Owherr option; if you don't] [see why, then think about it for a while] Note that you don't have to use any of the '-R' options; you could use 3dREMLfit just for the '-O' options if you want. In that case, the program will skip the time consuming ARMA(1,1) estimation for each voxel, by pretending you used the option '-ABfile =0,0'. ------------------------------------------------------------------- The following options control the ARMA(1,1) parameter estimation ~1~ for each voxel time series; normally, you do not need these options ------------------------------------------------------------------- -MAXa am = Set max allowed AR a parameter to 'am' (default=0.8). The range of a values scanned is 0 .. +am (-POScor) or is -am .. +am (-NEGcor). -MAXb bm = Set max allow MA b parameter to 'bm' (default=0.8). The range of b values scanned is -bm .. +bm. * The largest value allowed for am and bm is 0.9. * The smallest value allowed for am and bm is 0.1. * For a nearly pure AR(1) model, use '-MAXb 0.1' * For a nearly pure MA(1) model, use '-MAXa 0.1' -Grid pp = Set the number of grid divisions in the (a,b) grid to be 2^pp in each direction over the range 0..MAX. The default (and minimum) value for 'pp' is 3. Larger values will provide a finer resolution in a and b, but at the cost of some CPU time. * To be clear, the default settings use a grid with 8 divisions in the a direction and 16 in the b direction (since a is non-negative but b can be either sign). * If -NEGcor is used, then '-Grid 3' means 16 divisions in each direction, so that the grid spacing is 0.1 if MAX=0.8. Similarly, '-Grid 4' means 32 divisions in each direction, '-Grid 5' means 64 divisions, etc. * I see no reason why you would ever use a -Grid size greater than 5 (==> parameter resolution = 0.025). ++ However, if you like burning up CPU time, values up to '-Grid 7' are allowed :) * In the future, '-Grid 5' might become the default, since it is a little more accurate and computers are a lot faster than in the days when I was hunting brontosauri. * In my limited experiments, there was little appreciable difference in activation maps between '-Grid 3' and '-Grid 5', especially at the group analysis level. ++ To be fair, skipping prewhitening by using OLSQ (e.g., 3dDeconvolve) at the single subject level has little effect on the group analysis UNLESS you are going to use 3dMEMA, which relies on accurate single subject t-statistics, which in turn requires accurate temporal autocorrelation modeling. ++ If you are interested in the REML parameters themselves, or in getting the 'best' prewhitening possible, then '-Grid 5' makes sense. * The program is somewhat slower as the -Grid size expands. And uses more memory, to hold various matrices for each (a,b) case. -NEGcor = Allows negative correlations to be used; the default is that only positive correlations are searched. When this option is used, the range of a scanned is -am .. +am; otherwise, it is 0 .. +am. * Note that when -NEGcor is used, the number of grid points in the a direction doubles to cover the range -am .. 0; this will slow the program down. -POScor = Do not allow negative correlations. Since this is the default, you don't actually need this option. [FMRI data doesn't seem to need the modeling ] [of negative correlations, but you never know.] -WNplus = Do not allow negative correlations, AND only allow (a,b) parameter combinations that fit the model AR(1) + white noise: * a > 0 and -a < b < 0 * see 'What is ARMA(1,1)' far below * you should use '-Grid 5' with this option, since it restricts the number of possible ARMA(1,1) models -Mfilt mr = After finding the best fit parameters for each voxel in the mask, do a 3D median filter to smooth these parameters over a ball with radius 'mr' mm, and then use THOSE parameters to compute the final output. * If mr < 0, -mr is the ball radius in voxels, instead of millimeters. [No median filtering is done unless -Mfilt is used.] * This option is not recommended; it is just here for experimentation. -CORcut cc = The exact ARMA(1,1) correlation matrix (for a != 0) has no non-zero entries. The calculations in this program set correlations below a cutoff to zero. The default cutoff is 0.00010, but can be altered with this option. The usual reason to use this option is to test the sensitivity of the results to the cutoff. -ABfile ff = Instead of estimating the ARMA(a,b) parameters from the data, read them from dataset 'ff', which should have 2 float-valued sub-bricks. * Note that the (a,b) values read from this file will be mapped to the nearest ones on the (a,b) grid before being used to solve the generalized least squares problem. For this reason, you may want to use '-Grid 5' to make the (a,b) grid finer, if you are not using (a,b) values from a -Rvar file. * Using this option will skip the slowest part of the program, which is the scan for each voxel to find its optimal (a,b) parameters. * One possible application of -ABfile: + save (a,b) using -Rvar in 3dREMLfit + process them in some way (spatial smoothing?) + use these modified values for fitting in 3dREMLfit [you should use '-Grid 5' for such a case] * Another possible application of -ABfile: + use (a,b) from -Rvar to speed up a run with -Rglt when you want to run some more contrast tests. * Special case: -ABfile =0.7,-0.3 e.g., means to use a=0.7 and b=-0.3 for all voxels. The program detects this special case by looking for '=' as the first character of the string 'ff' and looking for a comma in the middle of the string. The values of a and b must be in the range -0.9..+0.9. * The purpose of this special case is to facilitate comparison with Software PrograMs that use the same temporal correlation structure for all voxels. -GOFORIT = 3dREMLfit checks the regression matrix for tiny singular values (as 3dDeconvolve does). If the matrix is too close to being rank-deficient, then the program will not proceed. You can use this option to force the program to continue past such a failed collinearity check, but you MUST check your results to see if they make sense! ** '-GOFORIT' is required if there are all zero columns in the regression matrix. However, at this time [15 Mar 2010], the all zero columns CANNOT come from the '-slibase' inputs. ** Nor from the '-dsort' inputs. ** If there are all zero columns in the matrix, a number of WARNING messages will be generated as the program pushes forward in the solution of the linear systems. --------------------- Miscellaneous Options ~1~ --------------------- -quiet = turn off most progress messages :( -verb = turn on more progress messages :) ========================================================================== =========== Various Notes (as if this help weren't long enough) ========= ========================================================================== ------------------ What is ARMA(1,1)? ~1~ ------------------ * The correlation coefficient r(k) of noise samples k units apart in time, for k >= 1, is given by r(k) = lam * a^(k-1) where lam = (b+a)(1+a*b)/(1+2*a*b+b*b) (N.B.: lam=a when b=0 -- AR(1) noise has r(k)=a^k for k >= 0) (N.B.: lam=b when a=0 -- MA(1) noise has r(k)=b for k=1, r(k)=0 for k>1) * lam can be bigger or smaller than a, depending on the sign of b: b > 0 means lam > a; b < 0 means lam < a. * What I call (a,b) here is sometimes called (p,q) in the ARMA literature. * For a noise model which is the sum of AR(1) and white noise, 0 < lam < a (i.e., a > 0 and -a < b < 0 ). Thus, the model 'AR(1)+white noise' is a proper subset of ARMA(1,1) -- and also a proper subset of the default -POScor setting (which also allows 0 < a < lam via b > 0). + This restricted model can be specified with the '-WNplus' option. With '-WNplus', you should use '-Grid 5', since you are restricting the number of available noise models fairly substantially. + If the variance of the white noise is T and the variance of the AR(1) noise is U, then lam = (a*U)/(U+T*(1-a^2)), and U/T = (lam*(1-a^2))/(a^2-lam). + In principal, one could estimate the fraction of the noise that is white vs. correlated using this U/T formula (e.g., via 3dcalc on the '-Rvar' output). + It is not clear that such an estimate is useful for any purpose, or indeed that the '-Rvar' outputs of the ARMA(1,1) parameters are useful for more than code testing reasons. YMMV :) * The natural range of a and b is -1..+1. However, unless -NEGcor is given, only non-negative values of a will be used, and only values of b that give lam > 0 will be allowed. Also, the program doesn't allow values of a or b to be outside the range -0.9..+0.9. * The program sets up the correlation matrix using the censoring and run start information saved in the header of the .xmat.1D matrix file, so that the actual correlation matrix used will not always be Toeplitz. For details of how time series with such gaps are analyzed, see the math notes. * The 'Rvar' dataset has 5 sub-bricks with variance parameter estimates: #0 = a = factor by which correlations decay from lag k to lag k+1 #1 = b parameter #2 = lam (see the formula above) = correlation at lag 1 #3 = standard deviation of ARMA(1,1) noise in that voxel #4 = -log(REML likelihood function) = optimized function at (a,b) For details about this, see the math notes. * The 'Rbeta' dataset has the beta (model fit) parameters estimates computed from the prewhitened time series data in each voxel, as in 3dDeconvolve's '-cbucket' output, in the order in which they occur in the matrix. -addbase and -slibase and -dsort beta values come last in this file. [The '-nobout' option will disable output of baseline parameters.] * The 'Rbuck' dataset has the beta parameters and their statistics mixed together, as in 3dDeconvolve's '-bucket' output. ------------------------------------------------------------------- What is REML = REsidual (or REstricted) Maximum Likelihood, anyway? ~1~ ------------------------------------------------------------------- * Ordinary Least SQuares (which assumes the noise correlation matrix is the identity) is consistent for estimating regression parameters, but is NOT consistent for estimating the noise variance if the noise is significantly correlated in time - 'serial correlation' or 'temporal correlation'. * Maximum likelihood estimation (ML) of the regression parameters and variance/correlation together is asymptotically consistent as the number of samples goes to infinity, but the variance estimates might still have significant bias at a 'reasonable' number of data points. * REML estimates the variance/correlation parameters in a space of residuals -- the part of the data left after the model fit is subtracted. The amusing/cunning part is that the model fit used to define the residuals is itself the generalized least squares fit where the variance/correlation matrix is the one found by the REML fit itself. This feature makes REML estimation nonlinear, and the REML equations are usually solved iteratively, to maximize the log-likelihood in the restricted space. In this program, the REML function is instead simply optimized over a finite grid of the correlation matrix parameters a and b. The matrices for each (a,b) pair are pre-calculated in the setup phase, and then are reused in the voxel loop. The purpose of this grid-based method is speed -- optimizing iteratively to a highly accurate (a,b) estimation for each voxel would be very time consuming, and pretty pointless. If you are concerned about the sensitivity of the results to the resolution of the (a,b) grid, you can use the '-Grid 5' option to increase this resolution and see if your activation maps change significantly. In test cases, the resulting betas and statistics have not changed appreciably between '-Grid 3' and '-Grid 5'; however, you might want to test this on your own data (just for fun, because who doesn't want more fun?). * REML estimates of the variance/correlation parameters are still biased, but are generally significantly less biased than ML estimates. Also, the regression parameters (betas) should be estimated somewhat more accurately (i.e., with smaller variance than OLSQ). However, this effect is generally small in FMRI data, and probably won't affect your group results noticeably (if you don't carry parameter variance estimates to the inter-subject analysis, as is done in 3dMEMA). * After the (a,b) parameters are estimated, then the solution to the linear system is available via Generalized Least SQuares; that is, via prewhitening using the Choleski factor of the estimated variance/covariance matrix. * In the case with b=0 (that is, AR(1) correlations), and if there are no time gaps (no censoring, no run breaks), then it is possible to directly estimate the a parameter without using REML. This program does not implement such a method (e.g., the Yule-Walker equation). The reasons why should be obvious. * If you like linear algebra, see my scanned math notes about 3dREMLfit: https://afni.nimh.nih.gov/pub/dist/doc/misc/3dREMLfit/3dREMLfit_mathnotes.pdf https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/remlfit.html * I have been asked if 3dREMLfit prewhitens the design matrix as well as the data. The short answer to this somewhat uninformed question is YES. The long answer follows (warning: math ahead!): * Mathematically, the GLSQ solution is expressed as f = inv[ X' inv(R) X] X' inv(R) y where X = model matrix, R = symmetric correlation matrix of noise (R depends on the a,b parameters), f = parameter estimates, and y = data vector. Notation: ' = transpose, inv() = inverse matrix. A symmetric matrix S such that SS = R is called a square root of R (there are many such matrices). The matrix inv(S) is a prewhitening matrix. That is, if the noise vector q is such that E(q q') = R (here E = expected value), and vector t = inv(S) q, then E(t t') = E[ inv(S)q q'inv(S) ] = inv(S) S S inv(S) = I. Note that inv(R) = inv(S) inv(S), and we can rewrite the GLSQ solution as f = inv[ X' inv(S) inv(S) X ] X' inv(S) inv(S) y = inv[ (inv(S)X)' (inv(S)X) ] (inv(S)X)' (inv(S)y) so the GLSQ solution is equivalent to the OLSQ solution, with the model matrix X replaced by inv(S)X and the data vector y replaced by inv(S)y; that is, we prewhiten both of them. In 3dREMLfit, this is done implicitly in the solution method outlined in the 7-step procedure on the fourth page of my math notes -- a procedure designed for efficient implementation with banded R. The prewhitened X matrix is never explicitly computed: it is not needed, since the goal is to compute vector f, not inv(S)X. * The idea of pre-whitening the data but NOT the matrix is a very bad plan. (This also was a suggestion by a not-well-informed user.) If you work through the linear algebra, you'll see that the resulting estimate for f is not statistically consistent with the underlying model! In other words, prewhitening only the data but not the matrix is WRONG. * Someone asking the question above might actually be asking if the residuals are whitened. The answer is YES and NO. The output of -Rerrts is not whitened; in the above notation, -Rerrts gives y-Xf = data - model fit. The output of -Rwherr is whitened; -Rwherr gives S[y-Xf], which is the residual (eps) vector for the pre-whitened linear system Sf = SXf + eps. * The estimation method for (a,b) is nonlinear; that is, these parameters are NOT estimated by doing an initial OLSQ (or any other one-shot initial calculation), then fitting (a,b) to the resulting residuals. Rather, a number of different (a,b) values are tried out to find the parameter pair where the log-likelihood of the Gaussian model is optimized. To be precise, the function that is minimized in each voxel (over the discrete a,b grid) is L(a,b) = log(det(R(a,b))) + log(det(X' inv(R(a,b)) X)) + (n-m)log(y'P(a,b)y) - log(det(X'X')) where R(a,b) = ARMA(1,1) correlation matrix (symmetric n X n) n = dimension of data vector = number of rows in X m = number of columns in X = number of regressors y = data vector for a given voxel P(a,b) = prewhitening projection matrix (symmetric n X n) = inv(R) - inv(R)X inv(X' inv(R) X) X' inv(R) The first 2 terms in L only depend on the (a,b) parameters, and can be thought of as a penalty that favors some (a,b) values over others, independent of the data -- for ARMA(1,1), the a=b=0 white noise model is penalized somewhat relative to the non-white noise cases. The 3rd term uses the 2-norm of the prewhitened residuals. The 4th term depends only on X, and is not actually used herein, since we don't include a model for varying X as well as R. * The method for estimating (a,b) does not require the time series data to be perfectly uniform in time. Gaps due to censoring and run break are allowed for properly. * Again, see the math notes for more fun fun algorithmic details: https://afni.nimh.nih.gov/pub/dist/doc/misc/3dREMLfit/3dREMLfit_mathnotes.pdf https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/statistics/remlfit.html ---------------- Other Commentary ~1~ ---------------- * Again: the ARMA(1,1) parameters 'a' (AR) and 'b' (MA) are estimated only on a discrete grid, for the sake of CPU time. * Each voxel gets a separate pair of 'a' and 'b' parameters. There is no option to estimate global values for 'a' and 'b' and use those for all voxels. Such an approach might be called 'kindergarten statistics' by the promulgators of Some People's Methods. * OLSQ = Ordinary Least SQuares; these outputs can be used to compare the REML/GLSQ estimations with the simpler OLSQ results (and to test this program vs. 3dDeconvolve). * GLSQ = Generalized Least SQuares = estimated linear system solution taking into account the variance/covariance matrix of the noise. * The '-matrix' file must be from 3dDeconvolve; besides the regression matrix itself, the header contains the stimulus labels, the GLTs, the censoring information, etc. + Although you can put in a 'raw' matrix using the '-matim' option, described earlier. * If you don't actually want the OLSQ results from 3dDeconvolve, you can make that program stop after the X matrix file is written out by using the '-x1D_stop' option, and then running 3dREMLfit; something like this: 3dDeconvolve -bucket Fred -nodata 800 2.5 -x1D_stop ... 3dREMLfit -matrix Fred.xmat.1D -input ... In the above example, no 3D dataset is input to 3dDeconvolve, so as to avoid the overhead of having to read it in for no reason. Instead, the '-nodata 800 2.5' option is used to setup the time series of the desired length (corresponding to the real data's length, here 800 points), and the appropriate TR (here, 2.5 seconds). This will properly establish the size and timing of the matrix file. * The bucket output datasets are structured to mirror the output from 3dDeconvolve with the default options below: -nobout -full_first Note that you CANNOT use options like '-bout', '-nocout', and '-nofull_first' with 3dREMLfit -- the bucket datasets are ordered the way they are and you'll just have to live with it. * If the 3dDeconvolve matrix generation step did NOT have any non-base stimuli (i.e., everything was '-stim_base'), then there are no 'stimuli' in the matrix file. In that case, since by default 3dREMLfit doesn't compute statistics of baseline parameters, to get statistics you will have to use the '-gltsym' option here, specifying the desired column indexes with the 'Col[]' notation, and then use '-Rglt' to get these values saved somewhere (since '-Rbuck' won't work if there are no 'Stim attributes'). * All output datasets are in float format [i.e., no '-short' option]. Internal calculations are done in double precision. * If the regression matrix (including any added columns from '-addbase' or '-slibase') is rank-deficient (e.g., has collinear columns), then the program will print a message something like ** ERROR: X matrix has 1 tiny singular value -- collinearity The program will NOT continue past this type of error, unless the '-GOFORIT' option is used. You should examine your results carefully to make sure they are reasonable (e.g., look at the fitted model overlay on the input time series). * The Ljung-Box (LB) statistic computed via the '-Rvar' option is a measure of how correlated the ARMA(1,1) pre-whitened residuals are in time. A 'small' value indicates that the pre-whitening was reasonably successful (e.g., small LB = 'good'). + The LB volume will be marked as a chi-squared statistic with h-2 degrees of freedom, where 'h' is the semi-arbitrarily chosen maximum lag used. A large LB value indicates noticeable temporal correlation in the pre-whitened residuals (e.g., that the ARMA(1,1) model wasn't adequate). + If a voxel has LB statistic = 0, this means that the LB value could not be computed for some reason (e.g., residuals are all zero). + For yet more information, see this article: On a measure of lack of fit in time series models. GM Ljung, GEP Box. Biometrika, 1978. https://www.jstor.org/stable/2335207 https://academic.oup.com/biomet/article/65/2/297/236869 + The calculation of the LB statistic is adjusted to allow for gaps in the time series (e.g., censoring, run gaps). + Note that the LB statistic is computed if and only if you give the '-Rvar' option. You don't have to give the '-Rwherr' option, which is used to save the pre-whitened residuals to a dataset. + If you want to test the LB statistic calculation under the null hypothesis (i.e., that the ARMA(1,1) model is correct), then you can use program 3dSimARMA11 to create a time series dataset, then run that through 3dREMLfit, then peruse the histogram of the resulting LB statistic. Have fun! * Depending on the matrix and the options, you might expect CPU time to be about 2..4 times that of the corresponding 3dDeconvolve run. + A careful choice of algorithms for solving the multiple linear systems required (e.g., QR method, sparse matrix operations, bordering, etc.) and some other code optimizations make running 3dREMLfit tolerable. + Especially on modern fast CPUs. Kids these days have NO idea about how we used to suffer waiting for computer runs, and how we passed the time by walking uphill through the snow. --------------------------------------------------------------- How 3dREMLfit handles all zero columns in the regression matrix --------------------------------------------------------------- * One salient (to the user) difference from 3dDeconvolve is how 3dREMLfit deals with the beta weight from an all zero column when computing a statistic (e.g., a GLT). The beta weight will simply be ignored, and its entry in the GLT matrix will be set to zero. Any all zero rows in the GLT matrix are then removed. For example, the 'Full_Fstat' for a model with 3 beta weights is computed from the GLT matrix [ 1 0 0 ] [ 0 1 0 ] [ 0 0 1 ]. If the last beta weight corresponds to an all zero column, then the matrix becomes [ 1 0 0 ] [ 0 1 0 ] [ 0 0 0 ], and then then last row is omitted. This excision reduces the number of numerator degrees of freedom in this test from 3 to 2. The net effect is that the F-statistic will be larger than in 3dDeconvolve, which does not modify the GLT matrix (or its equivalent). * A similar adjustment is made to denominator degrees of freedom, which is usually n-m, where n=# of data points and m=# of regressors. 3dDeconvolve counts all zero regressors in with m, but 3dREMLfit does not. The net effect is again to (slightly) increase F-statistic values over the equivalent 3dDeconvolve computation. ----------------------------------------------------------- To Dream the Impossible Dream, to Write the Uncodeable Code ----------------------------------------------------------- * Add options for -iresp/-sresp for -stim_times. * Prevent Daniel Glen from referring to this program as 3dARMAgeddon. * Establish incontrovertibly the nature of quantum mechanical observation. * Create an iPad version of the AFNI software suite. * Get people to stop asking me 'quick questions'! ---------------------------------------------------------- * For more information, please see the contents of https://afni.nimh.nih.gov/pub/dist/doc/misc/3dREMLfit/3dREMLfit_mathnotes.pdf which includes comparisons of 3dDeconvolve and 3dREMLfit activations (individual subject and group maps), and an outline of the mathematics implemented in this program. ---------------------------------------------------------- ============================ == RWCox - July-Sept 2008 == ============================ ========================================================================= * This binary version of 3dREMLfit is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. * The REML matrix setup and REML voxel ARMA(1,1) estimation loops are parallelized, across (a,b) parameter sets and across voxels, respectively. * The GLSQ and OLSQ loops are not parallelized. They are usually much faster than the REML voxel loop, and so I made no effort to speed these up (now and forever, two and inseparable). * '-usetemp' disables OpenMP multi-CPU usage, since the file I/O for saving and restoring various matrices and results is not easily parallelized. To get OpenMP speedup for large problems (just where you want it), you'll need a lot of RAM. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3drename
++ 3drename: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] Usage 1: 3drename old_prefix new_prefix Will rename all datasets using the old_prefix to use the new_prefix; 3drename fred ethel will change fred+orig.HEAD to ethel+orig.HEAD fred+orig.BRIK to ethel+orig.BRIK fred+tlrc.HEAD to ethel+tlrc.HEAD fred+tlrc.BRIK.gz to ethel+tlrc.BRIK.gz Usage 2: 3drename old_prefix+view new_prefix Will rename only the dataset with the given view (orig, acpc, tlrc). You cannot have paths in the old or the new prefix ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dresample
3dresample - reorient and/or resample a dataset This program can be used to change the orientation of a dataset (via the -orient option), or the dx,dy,dz grid spacing (via the -dxyz option), or change them both to match that of a master dataset (via the -master option). Note: if both -master and -dxyz are used, the dxyz values will override those from the master dataset. ** It is important to note that once a dataset of a certain grid is created (i.e. orientation, dxyz, field of view), if other datasets are going to be resampled to match that first one, then using -master should be used, instead of -dxyz. That will guarantee that all grids match. Otherwise, even using both -orient and -dxyz, one may not be sure that the fields of view will identical, for example. ** Warning: this program is not meant to transform datasets between view types (such as '+orig' and '+tlrc'). For that purpose, please see '3dfractionize -help' or 'adwarp -help'. ------------------------------------------------------------ usage: 3dresample [options] -prefix OUT_DSET -input IN_DSET examples: 3dresample -orient asl -rmode NN -prefix asl.dset -input in+orig 3dresample -dxyz 1.0 1.0 0.9 -prefix 119.dset -input in+tlrc 3dresample -master master+orig -prefix new.dset -input old+orig note: Information about a dataset's voxel size and orientation can be found in the output of program 3dinfo ------------------------------------------------------------ options: -help : show this help information -hist : output the history of program changes -debug LEVEL : print debug info along the way e.g. -debug 1 default level is 0, max is 2 -version : show version information -bound_type TYPE : specify which boundary is preserved e.g. -bound_type SLAB default is FOV (field of view) The default and original use preserves the field of of view when resampling, allowing the extents (SLABs) to grow or shrink by half of the difference in the dimension size (big voxels to small will cause the extents to expand, for example, while small to big will cause them to shrink). Using -bound_type SLAB will have the opposite effect. The extents should be unchanged, while the FOV will grow or shrink in the opposite way as above). Note that when using SLAB, edge voxels should be mostly unaffected by the interpolation. -dxyz DX DY DZ : resample to new dx, dy and dz e.g. -dxyz 1.0 1.0 0.9 default is to leave unchanged Each of DX,DY,DZ must be a positive real number, and will be used for a voxel delta in the new dataset (according to any new orientation). -orient OR_CODE : reorient to new axis order. e.g. -orient asl default is to leave unchanged The orientation code is a 3 character string, where the characters come from the respective sets {A,P}, {I,S}, {L,R}. For example OR_CODE = LPI is the standard 'neuroscience' orientation, where the x-axis is Left-to-Right, the y-axis is Posterior-to-Anterior, and the z-axis is Inferior-to-Superior. -rmode RESAM : use this resampling method e.g. -rmode Linear default is NN (nearest neighbor) The resampling method string RESAM should come from the set {'NN', 'Li', 'Cu', 'Bk'}. These are for 'Nearest Neighbor', 'Linear', 'Cubic' and 'Blocky' interpolation, respectively. For details, go to the 'Define Datamode' panel of the afni GUI, click BHelp and then the 'ULay resam mode' menu. -master MAST_DSET: align dataset grid to that of MAST_DSET e.g. -master master.dset+orig Get dxyz and orient from a master dataset. The resulting grid will match that of the master. This option can be used with -dxyz, but not with -orient. -prefix OUT_DSET : required prefix for output dataset e.g. -prefix reori.asl.pickle -input IN_DSET : required input dataset to reorient e.g. -input old.dset+orig -inset IN_DSET : alternative to -input ------------------------------------------------------------ Author: R. Reynolds - Version 1.10 <June 26, 2014>

AFNI program: 3dRetinoPhase
Usage: 3dRetinoPhase [-prefix ppp] dataset where dataset is a time series from a retinotpy stimulus -exp EXP: These four options specify the type of retinotpy -con CON: stimulus. EXP and CON are for expanding and -clw CLW : contracting rings, respectively. CLW and CCW are -ccw CCW: for clockwise and counter clockwise moving polar polar angle mapping stimuli. You can specify one, or all stimuli in one command. When all are specified polar angle stimuli, and eccentricity stimuli of opposite directions are combined. -prefix PREF: Prefix of output datasets. PREF is suffixed with the following: .ecc+ for positive (expanding) eccentricity (EXP) .ecc- for negative (contracting) eccentricity (CON) .pol+ for clockwise polar angle mapping (CLW) .pol- for counterclockwise polar angle mapping (CCW) At a minimum each input gets a phase dataset output. It contains response phase (or delay) in degrees. If both directions are given for polar and/or eccentricity then a visual field angle data set is created. The visual field angle is obtained by averaging phases of opposite direction stimuli. The hemodynamic offset is half the phase difference. Each output also contains a thresholding sub-brick. Its type depends on the phase estimation method (-phase_estimate). Note on the thresholding sub-bricks ----------------------------------- Both FFT and DELAY values of -phase_estimate produce thresholding sub-bricks with the phase estimates. Those thresholds have associated significance levels, but they should be taken with a grain of salt. There is no correction for autocorrelation, so the DOFs are generous. The program also attaches a thresholding sub-brick to the visual field angle datasets which are estimated by averaging the phase estimates in order to remove the hemodynamic offset. This composite thresholding sub-brick contains at each voxel/node, the maximum threshold from the datasets of stimli of opposite direction. This thresholding sub-brick is for convenience, allowing you to threshold with a mask that is the union of the individual thresholded maps. Significance levels are purposefully not attached. I don't know how to compute them properly. -spectra: Output amplitude and phase spectra datasets. -Tstim T: Period of stimulus in seconds. This parameter does not depend on the number of wedges or rings (Nr/Nw). It is the duration of a full cycle of the stimulus. Use -Tpol TPOL, and -Tecc TECC, to specify periods for each stimulus type separately. -Tstim sets both periods to T. -nrings Nr: Nr is the number of rings in the stimulus. The default is 1. -nwedges Nw: Nw is the number of wedges in the stimulus. The default is 1. -ort_adjust: Number of DOF lost in detrending outside of this program. -pre_stim PRE: Blank period, in seconds, before stimulus began -sum_adjust y/n: Adjust sum of angles for wrapping based on the angle difference. Default is 'y' -phase_estimate METH: Select method of phase estimation METH == FFT uses the phase of the fundamental frequency. METH == DELAY uses the 3ddelay approach for estimating the phase. This requires the use of option -ref_ts . See references [3] and [4] below. The DELAY option appears to be good as the FFT for high SNR and high duty cycle. See results produced by @Proc.PK.All_D in the demo archive AfniRetinoDemo.tgz. However,the DELAY option seems much better for low duty cycle stimuli. It is not set as the default for backward compatibility. Positive and negative feedback about this option are welcome. Thanks to Ikuko Mukai and Masaki Fukunaga for making the case for DELAY's addition; they were right. -ref_ts REF_TS: 0 lag reference time series of response. This is needed for the DELAY phase estimation method. With the DELAY method, the phase results are comparable to what you'd get with the following 3ddelay command: For illustration, say you have stimuli of 32 second periods with the polar stimuli having two wedges. After creating the reference time series with waver (32 sec. block period eccentricity, 32/2=16 sec. block period for polar), run 4 3ddelay commands as such: for an expanding ring of 32 second period: 3ddelay -input exp.niml.dset \ -ideal_file ECC.1D \ -fs 0.5 -T 32 \ -uD -nodsamp \ -phzreverse -phzscale 1.0 \ -prefix ecc+.del.niml.dset\n Repeat for contracting ring, remove -phzreverse for clockwise two wedge of 32 second period: 3ddelay -input clw.niml.dset \ -ideal_file POL.1D \ -fs 0.5 -T 16 \ -uD -nodsamp \ -phzreverse -phzscale 0.5 \ -prefix pol+.del.niml.dset\n Repeat for counterclockwise remove -phzreverse Instead of the 3ddelay mess, all you do is run 3dRetinoPhase with the following extra options: -phase_estimate DELAY -ref_ts ECC.1D or -phase_estimate DELAY -ref_ts POL.1D If you are not familiar with the use of program 'waver' for creating reference time series, take a look at demo script @Proc.PK.All_D in AfniRetinoDemo.tgz. -multi_ref_ts MULTI_REF_TS: Multiple 0 lag reference time series. This allows you to test multiple regressors. The program will run a separate analysis for each regressor (column), and combine the results in the output dataset this way: ([.] denotes output sub-brick) [0]: Phase from regressor that yields the highest correlation coeff. [1]: Maximum correlation coefficient. [2]: Number of regressor that yields the highest correlation coeff. Counting begins at 1 (not 0) [3]: Phase from regressor 1 [4]: Correlation coefficient from regressor 1 [5]: Phase from regressor 2 [6]: Correlation coefficient from regressor 2 ... etc. In general, for regressor k (k starts at 1) [2*k+1] contains the Phase and [2*k+2] the Correlation coefficient N.B: If MULTI_REF_TS has only one timeseries, -multi_ref_ts produces an output identical to that of -ref_ts. See usage in @RetinoProc and demo data in https://afni.nimh.nih.gov/pub/dist/tgz/AfniRetinoDemo.tgz References for this program: [1] RW Cox. AFNI: Software for analysis and visualization of functional magnetic resonance neuroimages. Computers and Biomedical Research, 29: 162-173, 1996. [2] Saad Z.S., et al. SUMA: An Interface For Surface-Based Intra- And Inter-Subject Analysis With AFNI. Proc. 2004 IEEE International Symposium on Biomedical Imaging, 1510-1513 If you use the DELAY method: [3] Saad, Z.S., et al. Analysis and use of FMRI response delays. Hum Brain Mapp, 2001. 13(2): p. 74-93. [4] Saad, Z.S., E.A. DeYoe, and K.M. Ropella, Estimation of FMRI Response Delays. Neuroimage, 2003. 18(2): p. 494-504. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dretroicor
Usage: 3dretroicor [options] dataset Performs Retrospective Image Correction for physiological motion effects, using a slightly modified version of the RETROICOR algorithm described in: Glover, G. H., Li, T., & Ress, D. (2000). Image-based method for retrospective correction of physiological motion effects in fMRI: RETROICOR. Magnetic Resonance in Medicine, 44, 162-167. Options (defaults in []'s): -ignore = The number of initial timepoints to ignore in the input (These points will be passed through uncorrected) [0] -prefix = Prefix for new, corrected dataset [retroicor] -card = 1D cardiac data file for cardiac correction -cardphase = Filename for 1D cardiac phase output -threshold = Threshold for detection of R-wave peaks in input (Make sure it's above the background noise level; Try 3/4 or 4/5 times range plus minimum) [1] -resp = 1D respiratory waveform data for correction -respphase = Filename for 1D resp phase output -order = The order of the correction (2 is typical; higher-order terms yield little improvement according to Glover et al.) [2] -help = Display this message and stop (must be first arg) Dataset: 3D+time dataset to process ** The input dataset and at least one of -card and -resp are required. NOTES ----- 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). Author -- Fred Tam, August 2002 INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'.

AFNI program: 3dROIMaker
ROIMaker, written by PA Taylor (Nov, 2012), part of FATCAT (Taylor & Saad, 2013) in AFNI. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * THE GENERAL PURPOSE of this code is to create a labelled set of ROIs from input data. It was predominantly written with a view of aiding the process of combining functional and tractographic/structural data. Thus, one might input a brain map (or several, as subbricks) of functional parameters (e.g., correlation coefficients or ICA maps of Z-scores), set a value threshold and/or a cluster-volume threshold, and this program will find distinct ROIs in the data and return a map of them, each labelled with an integer. One can also provide a reference map so that, for example, in group studies, each subject would have the same number label for a given region (i.e., the L motor cortex is always labelled with a `2'). In order to be prepared for tractographic application, one can also enlarge the gray matter ROIs so that they intersect with neighboring white matter. One can either specify a number of voxels with which to pad each ROI, and/or input a white matter skeleton (such as could be defined from a segmented T1 image or an FA map) and use this as an additional guide for inflating the GM ROIs. The output of this program can be used directly for guiding tractography, such as with 3dTrackID. If an input dataset ('-inset INSET') already contains integer delineation, such as using a parcellation method, then you can preserve these integers *even if the ROIs are contiguous* by using the same set as the reference set (-> '-refset INSET', as well). Otherwise, contiguous blobs defined will likely be given a single integer value in the program. Labeltable functionality is now available. If an input '-refset REFSET' has a labeltable attached, it will also be attached to the output GM and inflated GMI datasets by default (if you don't want to do this, you can use the '-dump_no_labtab' to turn off this functionality). If either no REFSET is input or it doesn't have a labeltable, one will be made from zeropadding the GM and GMI map integer values-- this may not add a lot of information, but it might make for more useful output. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * OUTPUTS: + `GM' map of ROIs :based on value- and volume-thresholding, would correspond most closely to gray matter regions of activation. The values of each voxel are an integer, distinct per ROI. + `GMI' map of ROIs :map of inflated GM ROIs, based on GM map, with the ROIs inflated either by a user-designed number of voxels, or also possibly including information of the WM skeleton (so that inflation is halted after encountering WM). The values of each voxel are the same integers as in the GM map. + RUNNING, need to provide: -inset INSET :3D volume(s) of values, esp. of functionally-derived quantities like correlation values or ICA Z-scores. -thresh MINTHR :threshold for values in INSET, used to great ROI islands from the 3D volume's sea of values. -prefix PREFIX :prefix of output name, with output files being: PREFIX_GM* and PREFIX_GMI* (see `Outputs', above). and can provide: -refset REFSET :3D (or multi-subbrick) volume containing integer values with which to label specific GM ROIs after thresholding. This can be useful to assist in having similar ROIs across a group labelled with the same integer in the output GM and GMI maps. If an INSET ROI has no corresponding REFSET label, then the former is marked with an integer greater than the max refset label. If an INSET ROI overlaps with multiple REFSET ROIs, then the former is split amongst the latter-- overlap regions get labelled first, and then REFSET labels grow to cover the INSET ROI in question. NB: it is possible to utilize negative-valued ROIs (voxels =-1) to represent NOT- regions for tracking, for example. -volthr MINVOL :integer number representing minimum size a cluster of voxels must have in order to remain a GM ROI after the values have been thresholded. Number might be estimated with 3dAlphaSim, or otherwise, to reduce number of `noisy' clusters. -only_some_top N :after '-volthr' but before any ref-matching or inflating, one can restrict each found region to keep only N voxels with the highest inset values. (If an ROI has <N voxels, then all would be kept.) This option can result in unconnected pieces. -only_conn_top N :similar-ish to preceding option, but instead of just selecting only N max voxels, do the following algorithm: start the ROI with the peak voxel; search the ROI's neighbors for the highest value; add that voxel to the ROI; continue until either the ROI has reached N voxels or whole region has been added. The returned ROI is contiguous and 'locally' maximal but not necessarily globally so within the original volume. -inflate N_INFL :number of voxels which with to pad each found ROI in order to turn GM ROIs into inflated (GMI) ROIs. ROIs won't overlap with each other, and a WM skeleton can also be input to keep ROIs from expanding through a large amount of WM ~artificially (see below). -trim_off_wm :switch to trim the INSET to exclude voxels in WM, by excluding those which overlap an input WM skeleton, SKEL (see `-wm_skel', below; to trim off CSF, see separate `-csf_skel'). NB: trimming is done before volume thresholding the ROIs, so fewer ROIs might pass, or some input regions might be split apart creating a greater number of regions. -wm_skel SKEL :3D volume containing info of WM, as might be defined from an FA map or anatomical segmentation. Can be to guide ROI inflation with `-skel_stop'. -skel_thr THR :if the skeleton is not a mask, one can put in a threshold value for it, such as having THR=0.2 if SKEL were a FA map. -skel_stop :switch to stop inflation at locations which are already on WM skeleton (default: off; and need `-wm_skel' to be able to use). -skel_stop_strict :similar to '-skel_stop', but this also does not allow any inflation *into* the skel-region. The '-skel_stop' let's the inflation go one layer *into* the skel-region, so this is stricter. This option might be my preference these days. -csf_skel CSF_SK :similar to SKEL, a 3D volume containing info of CSF. NB: however, with CSF_SK, info must just be a binary mask already, and it will only be applied in trimming procedure (no affect on inflation); if input, INSET is automatically trimmed of CSF, independent of using `-trim_off_wm'. Again, trimming done before volume thresholding, so may decrease/separate regions (though, that may be useful/more physiological). -mask MASK :can include a mask within which to apply threshold. Otherwise, data should be masked already. Guess this would be useful if the MINTHR were a negative value. It's also useful to ensure that the output *_GMI* ROI masks stay within the brain-- this probably won't often matter too much. For an N-brick inset, one can input an N- or 1-brick mask. -neigh_face_only : **DEPRECATED SWITCH** -> it's now default behavior to have facewise-only neighbors, in order to be consistent with the default usage of the clusterize function in the AFNI window. -neigh_face_edge :can loosen the definition of neighbors, so that voxels can share a face or an edge in order to be grouped into same ROI (AFNI default is that neighbors share at least one edge). -neigh_upto_vert :can loosen the definition of neighbors, so that voxels can be grouped into the same ROI if they share at least one vertex (see above for default). -nifti :switch to output *.nii.gz GM and GMI files (default format is BRIK/HEAD). -preinfl_inset PSET :as a possible use, one might want to start with a WM ROI, inflate it to find the nearest GM, then expand that GM, and subtract away the WM+CSF parts. Requires use of a '-wm_skel' and '-skel_stop', and replaces using '-inset'. The size of initial expansion through WM is entered using the option below; then WM+CSF is subtracted. The *_GM+orig* set is returned. In the *_GMI+orig* set, the number of voxels expanded in GM is set using the '-inflate' value (WM+CSF is subtracted again before output). -preinfl_inflate PN :number of voxels for initial inflation of PSET. -dump_no_labtab :switch for turning off labeltable attachment to the output GM and GMI files (from either from a '-refset REFSET' or from automatic generation from integer labels. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dROIMaker \ -inset CORR_VALUES+orig. \ -thresh 0.6 \ -prefix ROI_MAP \ -volthr 100 \ -inflate 2 \ -wm_skel WM_T1+orig. \ -skel_stop_strict * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________

AFNI program: 3dROIstats
Usage: 3dROIstats -mask[n] mset [options] datasets Display statistics over masked regions. The default statistic is the mean. There will be one line of output for every sub-brick of every input dataset. Across each line will be every statistic for every mask value. For instance, if there 3 mask values (1,2,3), then the columns Mean_1, Mean_2 and Mean_3 will refer to the means across each mask value, respectively. If 4 statistics are requested, then there will be 12 stats displayed on each line (4 for each mask region), besides the file and sub-brick number. Examples: 3dROIstats -mask mask+orig. 'func_slim+orig[1,3,5]' 3dROIstats -minmax -sigma -mask mask+orig. 'func_slim+orig[1,3,5]' Options: -mask[n] mset Means to use the dataset 'mset' as a mask: If n is present, it specifies which sub-brick in mset to use a la 3dcalc. Note: do not include the brackets if specifying a sub-brick, they are there to indicate that they are optional. If not present, 0 is assumed Voxels with the same nonzero values in 'mset' will be statisticized from 'dataset'. This will be repeated for all the different values in mset. I.e. all of the 1s in mset are one ROI, as are all of the 2s, etc. Note that the mask dataset and the input dataset must have the same number of voxels and that mset must be BYTE or SHORT (i.e., float masks won't work without the -mask_f2short option). -mask_f2short Tells the program to convert a float mask to short integers, by simple rounding. This option is needed when the mask dataset is a 1D file, for instance (since 1D files are read as floats). Be careful with this, it may not be appropriate to do! -numROI n 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. Confused? Then don't use this option! -zerofill ZF For ROI labels not found, use 'ZF' instead of a blank in the output file. This option is useless without -numROI. The option -zerofill defaults to '0'. -roisel SEL.1D Only considers ROIs denoted by values found in SEL.1D Note that the order of the ROIs as specified in SEL.1D is not preserved. So an SEL.1D of '2 8 20' produces the same output as '8 20 2' -debug Print out debugging information -quiet Do not print out labels for columns or rows -nomeanout Do not print out the mean column. Default is to always start with the mean value. This option cannot be used with -summary -longnames Prints the entire name of the sub-bricks -nobriklab Do not print the sub-brick label next to its index -1Dformat Output results in a 1D format that includes commented labels -1DRformat Output results in a 1D format that includes uncommented labels. This format does not work well with typical 1D programs, but it is useful for R functions. -float_format FORM output floats using an alternate format: float : the default, (%f) pretty : prettier format, (%g) sci : scientific notation (%e) OTHER : C-style format string, as with ccalc : e.g. '%7.3f' -float_format_sep SEP specify alternate float separator string: The default is '\t'. Consider ', ' for CSV. The following options specify what stats are computed. By default the mean is always computed. -nzmean Compute the mean using only non_zero voxels. Implies the opposite for the normal mean computed -nzsum Compute the sum using only non_zero voxels. -nzvoxels Compute the number of non_zero voxels -nzvolume Compute the volume of non-zero voxels -minmax Compute the min/max of all voxels -nzminmax Compute the min/max of non_zero voxels -sigma Compute the standard deviation of all voxels -nzsigma Compute the standard deviation of all non_zero voxels -median Compute the median of all voxels. -nzmedian Compute the median of non_zero 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. -mode Compute the mode of all voxels. (integral valued sets only) -nzmode Compute the mode of non_zero voxels. -pcxyz Compute the principal direction of the voxels in the ROI including the three eigen values. You'll get 12 values out per ROI, per sub-brick, with this option. pc0x pc0y pc0z pc1x pc1y pc1z pc2x pc2y pc2z eig0 eig1 eig2 -nzpcxyz Same as -pcxyz, but exclude zero valued voxels. -pcxyz+ Same as -pcxyz, but also with FA, MD, Cl, Cp, and Cs computed from the three eigen values. You will get 17 values out per ROI, per sub-brick, beginning with all the values from -pcxyz and -nzpcxyz then followed by FA MD Cl Cp Cs -nzpcxyz+ Same as -nzpcxyz, but also with FA, MD, Cl, Cp, and Cs. -key Output the integer key for the ROI in question The output is printed to stdout (the terminal), and can be saved to a file using the usual redirection operation '>'. N.B.: The input datasets and the mask dataset can use sub-brick selectors, as detailed in the output of 3dcalc -help. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3drotate
Usage: 3drotate [options] dataset Rotates and/or translates all bricks from an AFNI dataset. 'dataset' may contain a sub-brick selector list. GENERIC OPTIONS: -prefix fname = Sets the output dataset prefix name to be 'fname' -verbose = Prints out progress reports (to stderr) OPTIONS TO SPECIFY THE ROTATION/TRANSLATION: ------------------------------------------- *** METHOD 1 = direct specification: At most one of these shift options can be used: -ashift dx dy dz = Shifts the dataset 'dx' mm in the x-direction, etc., AFTER rotation. -bshift dx dy dz = Shifts the dataset 'dx' mm in the x-direction, etc., BEFORE rotation. The shift distances by default are along the (x,y,z) axes of the dataset storage directions (see the output of '3dinfo dataset'). To specify them anatomically, you can suffix a distance with one of the symbols 'R', 'L', 'A', 'P', 'I', and 'S', meaning 'Right', 'Left', 'Anterior', 'Posterior', 'Inferior', and 'Superior', respectively. -rotate th1 th2 th3 Specifies the 3D rotation to be composed of 3 planar rotations: 1) 'th1' degrees about the 1st axis, followed by 2) 'th2' degrees about the (rotated) 2nd axis, followed by 3) 'th3' degrees about the (doubly rotated) 3rd axis. Which axes are used for these rotations is specified by placing one of the symbols 'R', 'L', 'A', 'P', 'I', and 'S' at the end of each angle (e.g., '10.7A'). These symbols denote rotation about the 'Right-to-Left', 'Left-to-Right', 'Anterior-to-Posterior', 'Posterior-to-Anterior', 'Inferior-to-Superior', and 'Superior-to-Inferior' axes, respectively. A positive rotation is defined by the right-hand rule. *** METHOD 2 = copy from output of 3dvolreg: -rotparent rset Specifies that the rotation and translation should be taken from the first 3dvolreg transformation found in the header of dataset 'rset'. -gridparent gset Specifies that the output dataset of 3drotate should be shifted to match the grid of dataset 'gset'. Can only be used with -rotparent. This dataset should be one this is properly aligned with 'rset' when overlaid in AFNI. * If -rotparent is used, then don't use -matvec, -rotate, or -[ab]shift. * If 'gset' has a different number of slices than the input dataset, then the output dataset will be zero-padded in the slice direction to match 'gset'. * These options are intended to be used to align datasets between sessions: S1 = SPGR from session 1 E1 = EPI from session 1 S2 = SPGR from session 2 E2 = EPI from session 2 3dvolreg -twopass -twodup -base S1+orig -prefix S2reg S2+orig 3drotate -rotparent S2reg+orig -gridparent E1+orig -prefix E2reg E2+orig The result will have E2reg rotated from E2 in the same way that S2reg was from S2, and also shifted/padded (as needed) to overlap with E1. *** METHOD 3 = give the transformation matrix/vector directly: -matvec_dicom mfile -matvec_order mfile Specifies that the rotation and translation should be read from file 'mfile', which should be in the format u11 u12 u13 v1 u21 u22 u23 v2 u31 u32 u33 u3 where each 'uij' and 'vi' is a number. The 3x3 matrix [uij] is the orthogonal matrix of the rotation, and the 3-vector [vi] is the -ashift vector of the translation. *** METHOD 4 = copy the transformation from 3dTagalign: -matvec_dset mset Specifies that the rotation and translation should be read from the .HEAD file of dataset 'mset', which was created by program 3dTagalign. * If -matvec_dicom is used, the matrix and vector are given in Dicom coordinate order (+x=L, +y=P, +z=S). This is the option to use if mfile is generated using 3dTagalign -matvec mfile. * If -matvec_order is used, the matrix and vector are given in the coordinate order of the dataset axes, whatever they may be. * You can't mix -matvec_* options with -rotate and -*shift. *** METHOD 5 = input rotation+shift parameters from an ASCII file: -dfile dname *OR* -1Dfile dname With these methods, the movement parameters for each sub-brick of the input dataset are read from the file 'dname'. This file should consist of columns of numbers in ASCII format. Six (6) numbers are read from each line of the input file. If the '-dfile' option is used, each line of the input should be at least 7 numbers, and be of the form ignored roll pitch yaw dS dL dP If the '-1Dfile' option is used, then each line of the input should be at least 6 numbers, and be of the form roll pitch yaw dS dL dP (These are the forms output by the '-dfile' and '-1Dfile' options of program 3dvolreg; see that program's -help output for the hideous details.) The n-th sub-brick of the input dataset will be transformed using the parameters from the n-th line of the dname file. If the dname file doesn't contain as many lines as the input dataset has sub-bricks, then the last dname line will be used for all subsequent sub-bricks. Excess columns or rows will be ignored. N.B.: Rotation is always about the center of the volume. If the parameters are derived from a 3dvolreg run on a dataset with a different center in xyz-space, the results may not be what you want! N.B.: You can't use -dfile/-1Dfile with -points (infra). POINTS OPTIONS (instead of datasets): ------------------------------------ -points -origin xo yo zo These options specify that instead of rotating a dataset, you will be rotating a set of (x,y,z) points. The points are read from stdin. * If -origin is given, the point (xo,yo,zo) is used as the center for the rotation. * If -origin is NOT given, and a dataset is given at the end of the command line, then the center of the dataset brick is used as (xo,yo,zo). The dataset will NOT be rotated if -points is given. * If -origin is NOT given, and NO dataset is given at the end of the command line, then xo=yo=zo=0 is assumed. You probably don't want this. * (x,y,z) points are read from stdin as 3 ASCII-formatted numbers per line, as in 3dUndump. Any succeeding numbers on input lines will be copied to the output, which will be written to stdout. * The input (x,y,z) coordinates are taken in the same order as the axes of the input dataset. If there is no input dataset, then negative x = R positive x = L } negative y = A positive y = P } e.g., the DICOM order negative z = I positive z = S } One way to dump some (x,y,z) coordinates from a dataset is: 3dmaskdump -mask something+tlrc -o xyzfilename -noijk '3dcalc( -a dset+tlrc -expr x -datum float )' '3dcalc( -a dset+tlrc -expr y -datum float )' '3dcalc( -a dset+tlrc -expr z -datum float )' (All of this should be on one command line.) ============================================================================ Example: 3drotate -prefix Elvis -bshift 10S 0 0 -rotate 30R 0 0 Sinatra+orig This will shift the input 10 mm in the superior direction, followed by a 30 degree rotation about the Right-to-Left axis (i.e., nod the head forward). ============================================================================ Algorithm: The rotation+shift is decomposed into 4 1D shearing operations (a 3D generalization of Paeth's algorithm). The interpolation (i.e., resampling) method used for these shears can be controlled by the following options: -Fourier = Use a Fourier method (the default: most accurate; slowest). -NN = Use the nearest neighbor method. -linear = Use linear (1st order polynomial) interpolation (least accurate). -cubic = Use the cubic (3rd order) Lagrange polynomial method. -quintic = Use the quintic (5th order) Lagrange polynomial method. -heptic = Use the heptic (7th order) Lagrange polynomial method. -Fourier_nopad = Use the Fourier method WITHOUT padding * If you don't mind - or even want - the wraparound effect * Works best if dataset grid size is a power of 2, possibly times powers of 3 and 5, in all directions being altered. * The main use would seem to be to un-wraparound poorly reconstructed images, by using a shift; for example: 3drotate -ashift 30A 0 0 -Fourier_nopad -prefix Anew A+orig * This option is also available in the Nudge Dataset plugin. -clipit = Clip results to input brick range [now the default]. -noclip = Don't clip results to input brick range. -zpad n = Zeropad around the edges by 'n' voxels during rotations (these edge values will be stripped off in the output) N.B.: Unlike to3d, in this program '-zpad' adds zeros in all directions. N.B.: The environment variable AFNI_ROTA_ZPAD can be used to set a nonzero default value for this parameter. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dRowFillin
Usage: 3dRowFillin [options] dataset Extracts 1D rows in the given direction from a 3D dataset, searches for blank (zero) regions, and fills them in if the blank region isn't too large and it is flanked by the same value on either edge. For example: input row = 0 1 2 0 0 2 3 0 3 0 0 4 0 output row = 0 1 2 2 2 2 3 3 3 0 0 4 0 OPTIONS: -maxgap N = set the maximum length of a blank region that will be filled in to 'N' [default=9]. -dir D = set the direction of fill to 'D', which can be one of the following: A-P, P-A, I-S, S-I, L-R, R-L, x, y, z, XYZ.OR, XYZ.AND The first 6 are anatomical directions; x,y, and z, are reference to the dataset internal axes. XYZ.OR means do the fillin in x, followed by y, followed by z directions. XYZ.AND is like XYZ.OR but only accept voxels that would have been filled in each of the three fill calls. Note that with XYZ* options, the fill value depends on on the axis orientation. So you're better off sticking to single valued dsets when using them. See also -binary option below -binary: Turn input dataset to 0 and 1 before filling in. Output will also be a binary valued dataset. -prefix P = set the prefix to 'P' for the output dataset. N.B.: If the input dataset has more than one sub-brick, only the first one will be processed. * The intention of this program is to let you fill in slice gaps made when drawing ROIs with the 'Draw Dataset' plugin. If you draw every 5th coronal slice, say, then you could fill in using 3dRowFillin -maxgap 4 -dir A-P -prefix fredfill fred+orig * This program is moderately obsolescent, since I later added the 'Linear Fillin' controls to the 'Draw Dataset' plugin. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dRprogDemo
Usage: ------ 3dRprogDemo is a template program to help users write their own R processing routines on MRI volumes without having to deal with things like volume I/O or command line argument parsing. This template program shows rudimentary command line option parsing, volume reading, calling a silly processing function on each voxel time series, and writing the output. This 3dRprogDemo.R file is paired with the script 3dRprogDemo which allows users to run R programs directlt from the shell. To create your own 3dSOMETHING program you would do at least the following: cp 3dRprogDemo.R 3dSOMETHING.R cp 3dRprogDemo 3dSOMETHING Modify the variable ExecName in 3dSOMETHING.R to reflect your program name Replace the function RprogDemo.Scale() with your own function Unfortunately at this stage, there is little help for the AFNI R API beyond this sample code. If you find yourself using this and need to ask questions about other dataset utility functions contact the author for help. The AFNIio.R file in the AFNI distribution contains most of the IO functions. Below are some notable ones, grep for them in the .R files for usage examples. dset.attr() for getting and setting attributes, such as the TR in seconds e.g. dset$NI_head <- dset.attr(dset$NI_head, "TR", val = 1.5) read.AFNI() write.AFNI() show.dset.attr() dset.index3Dto1D() dset.index1Dto3D() dset.dimBRKarray() dset.3DBRKarrayto1D() dset.1DBRKarrayto3D() parse.AFNI.name() for parsing a filename into AFNI relevant parameters exists.AFNI.name() note.AFNI(), err.AFNI(), warn.AFNI(), exit.AFNI() Debugging Note: =============== When running the program from the shell prompt, you cannot use R's browser() function to halt execution and step through the code. However, the utility function load.debug.AFNI.args() makes it very easy for you to run the command line equivalent from the R prompt. Doing so would make available the browser() functionality. To use load.debug.AFNI.args() follow these steps: 1- Run the program from the shell command line. The program will automatically create a hidden file called .YOUR_PROGRAM_NAME.dbg.AFNI.args 2- Start R from the same directory or change to the directory where you ran the program if you started R elesewhere 3- Run the function: load.debug.AFNI.args() and follow the prompts. The function will look for possible debug files, prompt you to pick the one you want, and start the execution from the R shell. Example 1 --- Read a dataset, scale it, then write the results: ----------------------------------------------------------------------------- 3dRprogDemo -input epi.nii -mask mask.nii -scale 7 -prefix toy.nii Options in alphabetical order: ------------------------------ -h_aspx: like -h_spx, with autolabeling -h_raw: this help message, as is in the code. -h_spx: this help message, in sphinx format -h_txt: this help message, in simple text -help: this help message, in simple text. -input DSET1 \ Specify the dataset to be scaled. Note that you can use the various sub-brick selectors used by AFNI e.g: -input pb05.Regression+tlrc'[face#0_Beta]' \ You can use multiple instances of -input in one command line to process multiple datasets in the same manner. -mask MASK: Process voxels inside this mask only. Default is no masking. -prefix PREFIX: Output prefix (just prefix, no view+suffix needed) -scale SS: Multiply each voxel by SS -show_allowed_options: list of allowed options -verb VERB: VERB is an integer specifying verbosity level. 0 for quiet (Default). 1 or more: talkative.

AFNI program: 3dRSFC
Program to calculate common resting state functional connectivity (RSFC) parameters (ALFF, mALFF, fALFF, RSFA, etc.) for resting state time series. This program is **heavily** based on the existing 3dBandPass by RW Cox, with the amendments to calculate RSFC parameters written by PA Taylor (July, 2012). This program is part of FATCAT (Taylor & Saad, 2013) in AFNI. Importantly, its functionality can be included in the `afni_proc.py' processing-script generator; see that program's help file for an example including RSFC and spectral parameter calculation via the `-regress_RSFC' option. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * All options of 3dBandPass may be used here (with a couple other parameter options, as well): essentially, the motivation of this program is to produce ALFF, etc. values of the actual RSFC time series that you calculate. Therefore, all the 3dBandPass processing you normally do en route to making your final `resting state time series' is done here to generate your LFFs, from which the amplitudes in the LFF band are calculated at the end. In order to calculate fALFF, the same initial time series are put through the same processing steps which you have chosen but *without* the bandpass part; the spectrum of this second time series is used to calculate the fALFF denominator. For more information about each RSFC parameter, see, e.g.: ALFF/mALFF -- Zang et al. (2007), fALFF -- Zou et al. (2008), RSFA -- Kannurpatti & Biswal (2008). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + USAGE: 3dRSFC [options] fbot ftop dataset * One function of this program is to prepare datasets for input to 3dSetupGroupInCorr. Other uses are left to your imagination. * 'dataset' is a 3D+time sequence of volumes ++ This must be a single imaging run -- that is, no discontinuities in time from 3dTcat-ing multiple datasets together. * fbot = lowest frequency in the passband, in Hz ++ fbot can be 0 if you want to do a lowpass filter only; HOWEVER, the mean and Nyquist freq are always removed. * ftop = highest frequency in the passband (must be > fbot) ++ if ftop > Nyquist freq, then it's a highpass filter only. * Set fbot=0 and ftop=99999 to do an 'allpass' filter. ++ Except for removal of the 0 and Nyquist frequencies, that is. * You cannot construct a 'notch' filter with this program! ++ You could use 3dRSFC followed by 3dcalc to get the same effect. ++ If you are understand what you are doing, that is. ++ Of course, that is the AFNI way -- if you don't want to understand what you are doing, use Some other PrograM, and you can still get Fine StatisticaL maps. * 3dRSFC will fail if fbot and ftop are too close for comfort. ++ Which means closer than one frequency grid step df, where df = 1 / (nfft * dt) [of course] * The actual FFT length used will be printed, and may be larger than the input time series length for the sake of efficiency. ++ The program will use a power-of-2, possibly multiplied by a power of 3 and/or 5 (up to and including the 3rd power of each of these: 3, 9, 27, and 5, 25, 125). * Note that the results of combining 3dDetrend and 3dRSFC will depend on the order in which you run these programs. That's why 3dRSFC has the '-ort' and '-dsort' options, so that the time series filtering can be done properly, in one place. * The output dataset is stored in float format. * The order of processing steps is the following (most are optional), and for the LFFs, the bandpass is done between the specified fbot and ftop, while for the `whole spectrum' (i.e., fALFF denominator) the bandpass is: done only to exclude the time series mean and the Nyquist frequency: (0) Check time series for initial transients [does not alter data] (1) Despiking of each time series (2) Removal of a constant+linear+quadratic trend in each time series (3) Bandpass of data time series (4) Bandpass of -ort time series, then detrending of data with respect to the -ort time series (5) Bandpass and de-orting of the -dsort dataset, then detrending of the data with respect to -dsort (6) Blurring inside the mask [might be slow] (7) Local PV calculation [WILL be slow!] (8) L2 normalization [will be fast.] (9) Calculate spectrum and amplitudes, for RSFC parameters. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * -------- OPTIONS: -------- -despike = Despike each time series before other processing. ++ Hopefully, you don't actually need to do this, which is why it is optional. -ort f.1D = Also orthogonalize input to columns in f.1D ++ Multiple '-ort' options are allowed. -dsort fset = 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. -nodetrend = 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. -dt dd = set time step to 'dd' sec [default=from dataset header] -nfft N = set the FFT length to 'N' [must be a legal value] -norm = Make all output time series have L2 norm = 1 ++ i.e., sum of squares = 1 -mask mset = Mask dataset -automask = Create a mask from the input dataset -blur fff = Blur (inside the mask only) with a filter width (FWHM) of 'fff' millimeters. -localPV rrr = 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. -input dataset = Alternative way to specify input dataset. -band fbot ftop = Alternative way to specify passband frequencies. -prefix ppp = Set prefix name of output dataset. Name of filtered time series would be, e.g., ppp_LFF+orig.*, and the parameter outputs are named with obvious suffices. -quiet = Turn off the fun and informative messages. (Why?) -no_rs_out = Don't output processed time series-- just output parameters (not recommended, since the point of calculating RSFC params here is to have them be quite related to the time series themselves which are used for further analysis). -un_bp_out = Output the un-bandpassed series as well (default is not to). Name would be, e.g., ppp_unBP+orig.* . with suffix `_unBP'. -no_rsfa = If you don't want RSFA output (default is to do so). -bp_at_end = A (probably unnecessary) switch to have bandpassing be the very last processing step that is done in the sequence of steps listed above; at Step 3 above, only the time series mean and nyquist are BP'ed out, and then the LFF series is created only after Step 9. NB: this probably makes only very small changes for most processing sequences (but maybe not, depending usage). -notrans = Don't check for initial positive transients in the data: *OR* ++ The test is a little slow, so skipping it is OK, -nosat if you KNOW the data time series are transient-free. ++ Or set AFNI_SKIP_SATCHECK to YES. ++ Initial transients won't be handled well by the bandpassing algorithm, and in addition may seriously contaminate any further processing, such as inter- voxel correlations via InstaCorr. ++ No other tests are made [yet] for non-stationary behavior in the time series data. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________ ========================================================================= * This binary version of 3dRSFC is NOT compiled using OpenMP, a semi-automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * However, the source code is compatible with OpenMP, and can be compiled with an OpenMP-capable compiler, such as gcc 8.x+, Intel's icc, and Oracle Developer Studio. * If you wish to compile this program with OpenMP, see the man page for your C compiler, and (if needed) consult the AFNI message board, and https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * However, it would probably be simplest to download a pre-compiled AFNI binary set that uses OpenMP! https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/index.html ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 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. I do not recommend you use this program for quantitative segmentation, at least not yet. I have a lot of emotional baggage to overcome on that front. Example 1: Segmenting a skull-stripped T1 volume with: Brain mask, No prior volumes, Uniform mixing fraction 3dSeg -anat anat.nii -mask AUTO \ -classes 'CSF ; GM ; WM' -bias_classes 'GM ; WM' \ -bias_fwhm 25 -mixfrac UNI -main_N 5 \ -blur_meth BFT Options: -anat ANAT: ANAT is the volume to segment -mask MASK: MASK only non-zero voxels in MASK are analyzed. MASK is useful when no voxelwise priors are available. MASK can either be a dataset or the string 'AUTO' which would use AFNI's automask function to create the mask. -blur_meth BMETH: Set the blurring method for bias field estimation. -blur_meth takes one of: BFT, BIM, BFT: Use Fourier smoothing, masks be damned. BIM: Blur in mask, slower, more accurate, not necessarily better bias field estimates. BNN: A crude blurring in mask. Faster than BIM but it does not result in accurate FWHM. This option is for impatient testing. Do not use it. LSB: Localstat moving average smoothing. Debugging only. Do not use. default: BFT -bias_fwhm BIAS_FWHM: The amount of blurring used when estimating the field bias with the Wells method. [Wells et. al. IEEE TMI 15, 4, 1997]. Use 0.0 to turn off bias field estimation. default: 25.0 -classes 'CLASS_STRING': CLASS_STRING is a semicolon delimited string of class labels. At the moment CLASS_STRING can only be 'CSF; GM; WM' default: CSF; GM; WM -Bmrf BMRF: Weighting factor controlling spatial homogeneity of the classifications. The larger BMRF, the more homogeneous the classifications will be. See Berthod et al. Image and Vision Computing 14 (1996), MRFs are also used in FSL's FAST program. BMRF = 0.0 means no MRF, 1.0 is a start. Use this option if you have noisy data and no good voxelwise priors. default: 0.0 -bias_classes 'BIAS_CLASS_STRING': A semcolon demlimited string of classes that contribute to the estimation of the bias field. default: 'GM; WM' -prefix PREF: PREF is the prefix for all output volume that are not debugging related. default: Segsy -overwrite: An option common to almost all AFNI programs. It is automatically turned on if you provide no PREF. -debug LEVEL: Set debug level to 0(default), 1, or 2 -mixfrac 'MIXFRAC': MIXFRAC sets up the volume-wide (within mask) tissue fractions while initializing the segmentation (see IGNORE for exception). You can specify the mixing fractions directly such as with '0.1 0.45 0.45', or with the following special flags: 'UNI': Equal mixing fractions 'AVG152_BRAIN_MASK': Mixing fractions reflecting AVG152 template. 'IGNORE': Ignore mixing fraction while computing posterior probabilities for all the iterations, not just at the initialization as for the preceding variants default: UNI -mixfloor 'FLOOR': Set the minimum value for any class's mixing fraction. The value should be between 0 and 1 and not to exceed 1/(number of classes). This parameter should be kept to a small value. default: 0.0001 -gold GOLD: A goldstandard segmentation volume should you wish to compare 3dSeg's results to it. -gold_bias GOLD: A goldstandard bias volume should you wish to compare 3dSeg's bias estimate to it. -main_N Niter: Number of iterations to perform. default: 5 -cset CSET: Initial classification. If CSET is not given, initialization is carried out with 3dkmean's engine. -labeltable LT: Label table containing integer keys and corresponding labels. -vox_debug 1D_DBG_INDEX: 1D index of voxel to debug. OR -vox_debug I J K: where I, J, K are the 3D voxel indices (not RAI coordinates in mm). -vox_debug_file DBG_OUTPUT_FILE: File in which debug information is output use '-' for stdout, '+' for stderr.

AFNI program: 3dSetupGroupInCorr
++ 3dSetupGroupInCorr: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: RW Cox Usage: 3dSetupGroupInCorr [options] dataset dataset ... This program is used to pre-process a collection of AFNI 3D+time datasets for use with Group InstaCorr (3dGroupInCorr). * By itself, this program just collects all its input datasets together for convenient processing later. Pre-processing (e.g., detrending, bandpassing, despiking) must be done BEFORE running 3dSetupGroupInCorr -- for example, with 3dBandpass. The actual calculations of group t-tests of correlations is done AFTER running 3dSetupGroupInCorr, in program 3dGroupInCorr. * All the datasets input here will be treated as one sample for the t-test performed in 3dGroupInCorr. If you are going to do a 2-sample t-test, then you will need to run this program twice, once for each collection of datasets (e.g., once for 'control subjects' and once for 'patients'). * All datasets must have the same grid layout, since 3dGroupInCorr will do voxel-by-voxel comparisons. Usually, this means that the datasets have been transformed to a standard space; for example, using the @auto_tlrc script. * All the datasets use the same mask -- only voxels inside this mask will be stored and processed. If you do not give the '-mask' option, then all voxels will be processed -- not usually a good idea, since non-brain voxels will use up a LOT of memory and CPU time in 3dGroupInCorr. ++ If you use '-mask', you MUST use the same mask dataset in all runs of 3dSetupGroupInCorr that will be input at the same time to 3dGroupInCorr -- otherwise, the computations in that program will make no sense AT ALL! ++ This requirement is why there is no '-automask' option. * However, the datasets do NOT all have to have the same number of time points or time spacing. But each dataset must have at least 9 points along the time axis! * The ONLY pre-processing herein for each time series is to L2 normalize it (sum of squares = 1) and scale it to 8-bit bytes (or to 16-bit shorts). ++ You almost certainly want to use 3dBandpass and/or some other code to pre-process the datasets BEFORE input to this program. ++ See the SAMPLE SCRIPT below for a semi-reasonable way to pre-process a collection of datasets for 3dGroupInCorr. ++ [10 May 2012] The '-prep' option now allows for some limited pre-processing operations. * The outputs from this program are 2 files: ++ PREFIX.grpincorr.niml is a text file containing the header information that describes the data file. This file is input to 3dGroupInCorr to define one sample in the t-test. ++ PREFIX.grpincorr.data is the data file, which contains all the time series (in the mask) from all the datasets. ++ The data file will usually be huge (gigabytes, perhaps). You need to be sure you have enough disk space and RAM. ++ If the output files already exist when you run this program, then 3dSetupGroupInCorr will exit without processing the datasets! * See the help for 3dGroupInCorr for information on running that program. * The PDF file https://afni.nimh.nih.gov/pub/dist/edu/latest/afni_handouts/afni20_instastuff.pdf also has some information on the Group InstaCorr process (as well as all the other 'Insta' functions added to AFNI). * The program 3dExtractGroupInCorr can be used to reconstruct the input datasets from the .niml and .data files, if needed. ------- OPTIONS ------- -mask mset = Mask dataset [highly recommended for volumetric e data!] -prefix PREFIX = Set prefix name of output dataset -short = Store data as 16-bit shorts [used to be the default] ++ This will double the amount of disk space and RAM needed. ++ For most GroupInCorr purposes, you don't need this option, since there is so much averaging going on that truncation noise is washed away. -byte = Store data as 8-bit bytes rather than 16-bit shorts. ++ This will save memory in 3dGroupInCorr (and disk space), which can be important when using large collections of datasets. Results will be very slightly less accurate than with '-short', but you'll have a hard time finding any place where this matters. ++ This option is now the default [08 Feb 2010]. ++ The amount of data stored is (# of voxels in the mask) * (# of time points per subject) * (# of subjects) For a 3x3x3 mm^3 grid in MNI space, there are typically about 70,000 voxels in the brain. If you have an average of 200 time points per scan, then one subject's scan will take up 7e4*2e2 = 14 MB of space; 100 subjects would thus require about 1.4 GB of space. -labels fff = File 'fff' should be a list of labels, a unique one for each dataset input. These labels can be used in 3dGroupInCorr to select a subset of datasets to be processed therein. ++ If you don't use this option, then the list of labels will comprise the list of prefixes from the input datasets. ++ Labels cannot contain a space character, a comma, or a semicolon. ++ When using the -LRpairs option, you should specify only one label for eah pair. If you don't use the -labels option with -LRpairs the labels are taken from the 'L' only dataset names, that would be the first name of each LRpair. -DELETE = Delete input datasets from disk after processing them one at a time into the output data file -- this very highly destructive option is intended to let you save disk space, if absolutely necessary. *** BE CAREFUL OUT THERE! *** ++ If you are setting up for 3dGroupInCorr in a script that first uses 3dBandpass to filter the datasets, and then uses this program to finish the setup, then you COULD use '-DELETE' to remove the temporary 3dBandpass outputs as soon as they are no longer needed. -prep XXX = Prepare (or preprocess) each data time series in some fashion before L2 normalization and storing, where 'XXX' is one of these: ++ SPEARMAN ==> convert data to ranks, so that the resulting individual subject correlations in 3dGroupInCorr are Spearman correlations. ++ DEMEAN ==> remove the mean Variations for surface-based data: ---------------------------------- If you are working with one surface, no special options are needed. However, it is often the case that you want to perform correlations on both hemispheres. So in that case, you'll want to provide volume pairs (Left Hemi data, Right Hemi data). To help reduce the risk of user errors (the only kind we know of), you should also provide the domain parents for each of the hemispheres. -LRpairs L_SURF R_SURF: This option sets the domains for the left and right hemisphere surfaces, and indicates that the datasets to follow are arranged in (Left, Right) pairs. ------------- SAMPLE SCRIPT (tcsh syntax) ------------- * Assume datasets are named in the following scheme (sub01, sub02, ...) ++ T1-weighted anatomical = sub01_anat+orig ++ Resting state EPI = sub01_rest+orig ++ Standard space template = ~/abin/MNI_avg152T1+tlrc #!/bin/tcsh # MNI-ize each subject's anat, then EPIs (at 2 mm resolution) cp -f ~/abin/MNI_avg152T1+tlrc.* . foreach fred ( sub*_anat+orig.HEAD ) set sub = `basename $fred _anat+orig.HEAD` @auto_tlrc -base MNI_avg152T1+tlrc.HEAD -input $fred adwarp -apar ${sub}_anat+tlrc.HEAD -dpar ${sub}_rest+orig.HEAD \ -resam Cu -dxyz 2.0 3dAutomask -dilate 1 -prefix ${sub}_amask ${sub}_rest+tlrc.HEAD end # Combine individual EPI automasks into a group mask 3dMean -datum float -prefix ALL_amaskFULL *_amask+tlrc.HEAD 3dcalc -datum byte -prefix ALL_amask5050 -a ALL_amaskFULL+tlrc -expr 'step(a-0.499)' /bin/rm -f *_amask+tlrc.* # Bandpass and blur each dataset inside the group mask # * Skip first 4 time points. # * If you want to remove the global mean signal, you would use the '-ort' # option for 3dBandpass -- but we recommend that you do NOT do this: # http://dx.doi.org/10.1089/brain.2012.0080 foreach fred ( sub*_rest+tlrc.HEAD ) set sub = `basename $fred _rest+tlrc.HEAD` 3dBandpass -mask ALL_amask5050+tlrc -blur 6.0 -band 0.01 0.10 -prefix ${sub}_BP\ -input $fred'[4..$]' end # Extract data for 3dGroupInCorr 3dSetupGroupInCorr -mask ALL_amask5050 -prefix ALLshort -short *_BP+tlrc.HEAD # OR 3dSetupGroupInCorr -mask ALL_amask5050 -prefix ALLbyte -byte *_BP+tlrc.HEAD /bin/rm -f *_BP+tlrc.* ### At this point you could run (in 2 separate terminal windows) ### afni -niml MNI_avg152T1+tlrc ### 3dGroupInCorr -setA ALLbyte.grpincorr.niml -verb ### And away we go .... ------------------ CREDITS (or blame) ------------------ * Written by RWCox, 31 December 2009. * With a little help from my friends: Alex Martin, Steve Gotts, Ziad Saad. * With encouragement from MMK. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dSharpen
Usage: 3dSharpen [options] dataset Applies a simple 3D sharpening filter to the POSITIVE values in the #0 volume of the input dataset, and writes out a new dataset. Only operates on positive valued voxels in the dataset. Non-positive values will not be altered. Options: -------- -phi fff = Sharpening factor, between 0.1 and 0.9 (inclusive). Larger means more sharpening. Default is 0.4. -input dataset = An option to input the dataset anywhere, not just at the end of the command line. -prefix pref = Select the name of the output dataset (it will be in floating point format). * A quick hack for experimental purposes. * e.g., Cleaning up the results of brain template construction. * RWCox - Feb 2017.

AFNI program: 3dSignatures
Loading required package: fitdistrplus Loading required package: MASS Warning message: In library(package, lib.loc = lib.loc, character.only = TRUE, logical.return = TRUE, : there is no package called ‘fitdistrplus’ Error in library(fitdistrplus) : there is no package called ‘fitdistrplus’ Calls: source -> withVisible -> eval -> eval -> library Execution halted

AFNI program: 3dSkullStrip
Usage: A program to extract the brain from surrounding. tissue from MRI T1-weighted images. The simplest command would be: 3dSkullStrip <-input DSET> Also consider the script @SSwarper, which combines the use of 3dSkullStrip and nonlinear warping to an MNI template to produce a skull-stripped dataset in MNI space, plus the nonlinear warp that can used to transform other datasets from the same subject (e.g., EPI) to MNI space. (This script only applies to human brain images.) The fully automated process consists of three steps: 1- Preprocessing of volume to remove gross spatial image non-uniformity artifacts and reposition the brain in a reasonable manner for convenience. ** Note that in many cases, using 3dUnifize before ** ** using 3dSkullStrip will give better results. ** 2- Expand a spherical surface iteratively until it envelopes the brain. This is a modified version of the BET algorithm: Fast robust automated brain extraction, by Stephen M. Smith, HBM 2002 v 17:3 pp 143-155 Modifications include the use of: . outer brain surface . expansion driven by data inside and outside the surface . avoidance of eyes and ventricles . a set of operations to avoid the clipping of certain brain areas and reduce leakage into the skull in heavily shaded data . two additional processing stages to ensure convergence and reduction of clipped areas. . use of 3d edge detection, see Deriche and Monga references in 3dedge3 -help. 3- The creation of various masks and surfaces modeling brain and portions of the skull Common examples of usage: ------------------------- o 3dSkullStrip -input VOL -prefix VOL_PREFIX Vanilla mode, should work for most datasets. o 3dSkullStrip -input VOL -prefix VOL_PREFIX -push_to_edge Adds an aggressive push to brain edges. Use this option when the chunks of gray matter are not included. This option might cause the mask to leak into non-brain areas. o 3dSkullStrip -input VOL -surface_coil -prefix VOL_PREFIX -monkey Vanilla mode, for use with monkey data. o 3dSkullStrip -input VOL -prefix VOL_PREFIX -ld 30 Use a denser mesh, in the cases where you have lots of csf between gyri. Also helps when some of the brain is clipped close to regions of high curvature. Tips: ----- I ran the program with the default parameters on 200+ datasets. The results were quite good in all but a couple of instances, here are some tips on fixing trouble spots: Clipping in frontal areas, close to the eye balls: + Try -push_to_edge option first. Can also try -no_avoid_eyes option. Clipping in general: + Try -push_to_edge option first. Can also use lower -shrink_fac, start with 0.5 then 0.4 Problems down below: + Piece of cerebellum missing, reduce -shrink_fac_bot_lim from default value. + Leakage in lower areas, increase -shrink_fac_bot_lim from default value. Some lobules are not included: + Use a denser mesh. Start with -ld 30. If that still fails, try even higher density (like -ld 50) and increase iterations (say to -niter 750). Expect the program to take much longer in that case. + Instead of using denser meshes, you could try blurring the data before skull stripping. Something like -blur_fwhm 2 did wonders for some of my data with the default options of 3dSkullStrip Blurring is a lot faster than increasing mesh density. + Use also a smaller -shrink_fac is you have lots of CSF between gyri. Massive chunks missing: + If brain has very large ventricles and lots of CSF between gyri, the ventricles will keep attracting the surface inwards. This often happens with older brains. In such cases, use the -visual option to see what is happening. For example, the options below did the trick in various instances. -blur_fwhm 2 -use_skull or for more stubborn cases increase csf avoidance with this cocktail -blur_fwhm 2 -use_skull -avoid_vent -avoid_vent -init_radius 75 + Too much neck in the volume might throw off the initialization step. You can fix this by clipping tissue below the brain with @clip_volume -below ZZZ -input INPUT where ZZZ is a Z coordinate somewhere below the brain. Large regions outside brain included: + Usually because noise level is high. Try @NoisySkullStrip. Make sure that brain orientation is correct. This means the image in AFNI's axial slice viewer should be close to the brain's axial plane. The same goes for the other planes. Otherwise, the program might do a lousy job removing the skull. Eye Candy Mode: --------------- You can run 3dSkullStrip and have it send successive iterations to SUMA and AFNI. This is very helpful in following the progression of the algorithm and determining the source of trouble, if any. Example: afni -niml -yesplugouts & suma -niml & 3dSkullStrip -input Anat+orig -o_ply anat_brain -visual Help section for the intrepid: ------------------------------ 3dSkullStrip < -input VOL > [< -o_TYPE PREFIX >] [< -prefix VOL_PREFIX >] [< -spatnorm >] [< -no_spatnorm >] [< -write_spatnorm >] [< -niter N_ITER >] [< -ld LD >] [< -shrink_fac SF >] [< -var_shrink_fac >] [< -no_var_shrink_fac >] [< -shrink_fac_bot_lim SFBL >] [< -pushout >] [< -no_pushout >] [< -exp_frac FRAC] [< -touchup >] [< -no_touchup >] [< -fill_hole R >] [< -NN_smooth NN_SM >] [< -smooth_final SM >] [< -avoid_vent >] [< -no_avoid_vent >] [< -use_skull >] [< -no_use_skull >] [< -avoid_eyes >] [< -no_avoid_eyes >] [< -use_edge >] [< -no_use_edge >] [< -push_to_edge >] [<-no_push_to_edge>] [< -perc_int PERC_INT >] [< -max_inter_iter MII >] [-mask_vol | -orig_vol | -norm_vol] [< -debug DBG >] [< -node_debug NODE_DBG >] [< -demo_pause >] [< -monkey >] [< -marmoset >] [<-rat>] NOTE: Please report bugs and strange failures to saadz@mail.nih.gov Mandatory parameters: -input VOL: Input AFNI (or AFNI readable) volume. Optional Parameters: -monkey: the brain of a monkey. -marmoset: the brain of a marmoset. this one was tested on one dataset and may not work with non default options. Check your results! -rat: the brain of a rat. By default, no_touchup is used with the rat. -surface_coil: Data acquired with a surface coil. -o_TYPE PREFIX: prefix of output surface. where TYPE specifies the format of the surface and PREFIX is, well, the prefix. TYPE is one of: fs, 1d (or vec), sf, ply. More on that below. -skulls: Output surface models of the skull. -4Tom: The output surfaces are named based on PREFIX following -o_TYPE option below. -prefix VOL_PREFIX: prefix of output volume. If not specified, the prefix is the same as the one used with -o_TYPE. The output volume is skull stripped version of the input volume. In the earlier version of the program, a mask volume was written out. You can still get that mask volume instead of the skull-stripped volume with the option -mask_vol . NOTE: In the default setting, the output volume does not have values identical to those in the input. In particular, the range might be larger and some low-intensity values are set to 0. If you insist on having the same range of values as in the input, then either use option -orig_vol, or run: 3dcalc -nscale -a VOL+VIEW -b VOL_PREFIX+VIEW \ -expr 'a*step(b)' -prefix VOL_SAME_RANGE With the command above, you can preserve the range of values of the input but some low-intensity voxels would still be masked. If you want to preserve them, then use -mask_vol in the 3dSkullStrip command that would produce VOL_MASK_PREFIX+VIEW. Then run 3dcalc masking with voxels inside the brain surface envelope: 3dcalc -nscale -a VOL+VIEW -b VOL_MASK_PREFIX+VIEW \ -expr 'a*step(b-3.01)' -prefix VOL_SAME_RANGE_KEEP_LOW -norm_vol: Output a masked and somewhat intensity normalized and thresholded version of the input. This is the default, and you can use -orig_vol to override it. -orig_vol: Output a masked version of the input AND do not modify the values inside the brain as -norm_vol would. -mask_vol: Output a mask volume instead of a skull-stripped volume. The mask volume contains: 0: Voxel outside surface 1: Voxel just outside the surface. This means the voxel center is outside the surface but inside the bounding box of a triangle in the mesh. 2: Voxel intersects the surface (a triangle), but center lies outside. 3: Voxel contains a surface node. 4: Voxel intersects the surface (a triangle), center lies inside surface. 5: Voxel just inside the surface. This means the voxel center is inside the surface and inside the bounding box of a triangle in the mesh. 6: Voxel inside the surface. -spat_norm: (Default) Perform spatial normalization first. This is a necessary step unless the volume has been 'spatnormed' already. -no_spatnorm: Do not perform spatial normalization. Use this option only when the volume has been run through the 'spatnorm' process -spatnorm_dxyz DXYZ: Use DXY for the spatial resolution of the spatially normalized volume. The default is the lowest of all three dimensions. For human brains, use DXYZ of 1.0, for primate brain, use the default setting. -write_spatnorm: Write the 'spatnormed' volume to disk. -niter N_ITER: Number of iterations. Default is 250 For denser meshes, you need more iterations N_ITER of 750 works for LD of 50. -ld LD: Parameter to control the density of the surface. Default is 20 if -no_use_edge is used, 30 with -use_edge. See CreateIcosahedron -help for details on this option. -shrink_fac SF: Parameter controlling the brain vs non-brain intensity threshold (tb). Default is 0.6. tb = (Imax - t2) SF + t2 where t2 is the 2 percentile value and Imax is the local maximum, limited to the median intensity value. For more information on tb, t2, etc. read the BET paper mentioned above. Note that in 3dSkullStrip, SF can vary across iterations and might be automatically clipped in certain areas. SF can vary between 0 and 1. 0: Intensities < median inensity are considered non-brain 1: Intensities < t2 are considered non-brain -var_shrink_fac: Vary the shrink factor with the number of iterations. This reduces the likelihood of a surface getting stuck on large pools of CSF before reaching the outer surface of the brain. (Default) -no_var_shrink_fac: Do not use var_shrink_fac. -shrink_fac_bot_lim SFBL: Do not allow the varying SF to go below SFBL . Default 0.65, 0.4 when edge detection is used. This option helps reduce potential for leakage below the cerebellum. In certain cases where you have severe non-uniformity resulting in low signal towards the bottom of the brain, you will need to reduce this parameter. -pushout: Consider values above each node in addition to values below the node when deciding on expansion. (Default) -no_pushout: Do not use -pushout. -exp_frac FRAC: Speed of expansion (see BET paper). Default is 0.1. -touchup: Perform touchup operations at end to include areas not covered by surface expansion. Use -touchup -touchup for aggressive makeup. (Default is -touchup) -no_touchup: Do not use -touchup -fill_hole R: Fill small holes that can result from small surface intersections caused by the touchup operation. R is the maximum number of pixels on the side of a hole that can be filled. Big holes are not filled. If you use -touchup, the default R is 10. Otherwise the default is 0. This is a less than elegant solution to the small intersections which are usually eliminated automatically. -NN_smooth NN_SM: Perform Nearest Neighbor coordinate interpolation every few iterations. Default is 72 -smooth_final SM: Perform final surface smoothing after all iterations. Default is 20 smoothing iterations. Smoothing is done using Taubin's method, see SurfSmooth -help for detail. -avoid_vent: avoid ventricles. Default. Use this option twice to make the avoidance more aggressive. That is at times needed with old brains. -no_avoid_vent: Do not use -avoid_vent. -init_radius RAD: Use RAD for the initial sphere radius. For the automatic setting, there is an upper limit of 100mm for humans. For older brains with lots of CSF, you might benefit from forcing the radius to something like 75mm -avoid_eyes: avoid eyes. Default -no_avoid_eyes: Do not use -avoid_eyes. -use_edge: Use edge detection to reduce leakage into meninges and eyes. Default. -no_use_edge: Do no use edges. -push_to_edge: Perform aggressive push to edge at the end. This option might cause leakage. -no_push_to_edge: (Default). -use_skull: Use outer skull to limit expansion of surface into the skull due to very strong shading artifacts. This option is buggy at the moment, use it only if you have leakage into skull. -no_use_skull: Do not use -use_skull (Default). -send_no_skull: Do not send the skull surface to SUMA if you are using -talk_suma -perc_int PERC_INT: Percentage of segments allowed to intersect surface. Ideally this should be 0 (Default). However, few surfaces might have small stubborn intersections that produce a few holes. PERC_INT should be a small number, typically between 0 and 0.1. A -1 means do not do any testing for intersection. -max_inter_iter N_II: Number of iteration to remove intersection problems. With each iteration, the program automatically increases the amount of smoothing to get rid of intersections. Default is 4 -blur_fwhm FWHM: Blur dset after spatial normalization. Recommended when you have lots of CSF in brain and when you have protruding gyri (finger like) Recommended value is 2..4. -interactive: Make the program stop at various stages in the segmentation process for a prompt from the user to continue or skip that stage of processing. This option is best used in conjunction with options -talk_suma and -feed_afni -demo_pause: Pause at various step in the process to facilitate interactive demo while 3dSkullStrip is communicating with AFNI and SUMA. See 'Eye Candy' mode below and -talk_suma option. -fac FAC: Multiply input dataset by FAC if range of values is too small. Specifying output surfaces using -o or -o_TYPE options: -o_TYPE outSurf specifies the output surface, TYPE is one of the following: fs: FreeSurfer ascii surface. fsp: FeeSurfer ascii patch surface. In addition to outSurf, you need to specify the name of the parent surface for the patch. using the -ipar_TYPE option. This option is only for ConvertSurface sf: SureFit surface. For most programs, you are expected to specify prefix: i.e. -o_sf brain. In some programs, you are allowed to specify both .coord and .topo file names: i.e. -o_sf XYZ.coord TRI.topo The program will determine your choice by examining the first character of the second parameter following -o_sf. If that character is a '-' then you have supplied a prefix and the program will generate the coord and topo names. vec (or 1D): Simple ascii matrix format. For most programs, you are expected to specify prefix: i.e. -o_1D brain. In some programs, you are allowed to specify both coord and topo file names: i.e. -o_1D brain.1D.coord brain.1D.topo coord contains 3 floats per line, representing X Y Z vertex coordinates. topo contains 3 ints per line, representing v1 v2 v3 triangle vertices. ply: PLY format, ascii or binary. stl: STL format, ascii or binary (see also STL under option -i_TYPE). byu: BYU format, ascii or binary. mni: MNI obj format, ascii only. gii: GIFTI format, ascii. You can also enforce the encoding of data arrays by using gii_asc, gii_b64, or gii_b64gz for ASCII, Base64, or Base64 Gzipped. If AFNI_NIML_TEXT_DATA environment variable is set to YES, the the default encoding is ASCII, otherwise it is Base64. obj: No support for writing OBJ format exists yet. Note that if the surface filename has the proper extension, it is enough to use the -o option and let the programs guess the type from the extension. SUMA communication options: -talk_suma: Send progress with each iteration to SUMA. -refresh_rate rps: Maximum number of updates to SUMA per second. The default is the maximum speed. -send_kth kth: Send the kth element to SUMA (default is 1). This allows you to cut down on the number of elements being sent to SUMA. -sh <SumaHost>: Name (or IP address) of the computer running SUMA. This parameter is optional, the default is 127.0.0.1 -ni_text: Use NI_TEXT_MODE for data transmission. -ni_binary: Use NI_BINARY_MODE for data transmission. (default is ni_binary). -feed_afni: Send updates to AFNI via SUMA's talk. -np PORT_OFFSET: Provide a port offset to allow multiple instances of AFNI <--> SUMA, AFNI <--> 3dGroupIncorr, or any other programs that communicate together to operate on the same machine. All ports are assigned numbers relative to PORT_OFFSET. The same PORT_OFFSET value must be used on all programs that are to talk together. PORT_OFFSET is an integer in the inclusive range [1025 to 65500]. When you want to use multiple instances of communicating programs, be sure the PORT_OFFSETS you use differ by about 50 or you may still have port conflicts. A BETTER approach is to use -npb below. -npq PORT_OFFSET: Like -np, but more quiet in the face of adversity. -npb PORT_OFFSET_BLOC: Similar to -np, except it is easier to use. PORT_OFFSET_BLOC is an integer between 0 and MAX_BLOC. MAX_BLOC is around 4000 for now, but it might decrease as we use up more ports in AFNI. You should be safe for the next 10 years if you stay under 2000. Using this function reduces your chances of causing port conflicts. See also afni and suma options: -list_ports and -port_number for information about port number assignments. You can also provide a port offset with the environment variable AFNI_PORT_OFFSET. Using -np overrides AFNI_PORT_OFFSET. -max_port_bloc: Print the current value of MAX_BLOC and exit. Remember this value can get smaller with future releases. Stay under 2000. -max_port_bloc_quiet: Spit MAX_BLOC value only and exit. -num_assigned_ports: Print the number of assigned ports used by AFNI then quit. -num_assigned_ports_quiet: Do it quietly. Port Handling Examples: ----------------------- Say you want to run three instances of AFNI <--> SUMA. For the first you just do: suma -niml -spec ... -sv ... & afni -niml & Then for the second instance pick an offset bloc, say 1 and run suma -niml -npb 1 -spec ... -sv ... & afni -niml -npb 1 & And for yet another instance: suma -niml -npb 2 -spec ... -sv ... & afni -niml -npb 2 & etc. Since you can launch many instances of communicating programs now, you need to know wich SUMA window, say, is talking to which AFNI. To sort this out, the titlebars now show the number of the bloc of ports they are using. When the bloc is set either via environment variables AFNI_PORT_OFFSET or AFNI_PORT_BLOC, or with one of the -np* options, window title bars change from [A] to [A#] with # being the resultant bloc number. In the examples above, both AFNI and SUMA windows will show [A2] when -npb is 2. -visual: Equivalent to using -talk_suma -feed_afni -send_kth 5 -debug DBG: debug levels of 0 (default), 1, 2, 3. This is no Rick Reynolds debug, which is oft nicer than the results, but it will do. -node_debug NODE_DBG: Output lots of parameters for node NODE_DBG for each iteration. The next 3 options are for specifying surface coordinates to keep the program from having to recompute them. The options are only useful for saving time during debugging. -brain_contour_xyz_file BRAIN_CONTOUR_XYZ.1D -brain_hull_xyz_file BRAIN_HULL_XYZ.1D -skull_outer_xyz_file SKULL_OUTER_XYZ.1D -help: The help you need [-novolreg]: Ignore any Rotate, Volreg, Tagalign, or WarpDrive transformations present in the Surface Volume. [-noxform]: Same as -novolreg [-setenv "'ENVname=ENVvalue'"]: Set environment variable ENVname to be ENVvalue. Quotes are necessary. Example: suma -setenv "'SUMA_BackgroundColor = 1 0 1'" See also options -update_env, -environment, etc in the output of 'suma -help' Common Debugging Options: [-trace]: Turns on In/Out debug and Memory tracing. For speeding up the tracing log, I recommend you redirect stdout to a file when using this option. For example, if you were running suma you would use: suma -spec lh.spec -sv ... > TraceFile This option replaces the old -iodbg and -memdbg. [-TRACE]: Turns on extreme tracing. [-nomall]: Turn off memory tracing. [-yesmall]: Turn on memory tracing (default). NOTE: For programs that output results to stdout (that is to your shell/screen), the debugging info might get mixed up with your results. Global Options (available to all AFNI/SUMA programs) -h: Mini help, at time, same as -help in many cases. -help: The entire help output -HELP: Extreme help, same as -help in majority of cases. -h_view: Open help in text editor. AFNI will try to find a GUI editor -hview : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_web: Open help in web browser. AFNI will try to find a browser. -hweb : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_find WORD: Look for lines in this programs's -help output that match (approximately) WORD. -h_raw: Help string unedited -h_spx: Help string in sphinx loveliness, but do not try to autoformat -h_aspx: Help string in sphinx with autoformatting of options, etc. -all_opts: Try to identify all options for the program from the output of its -help option. Some options might be missed and others misidentified. Use this output for hints only. Compile Date: May 6 2025 Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov

AFNI program: 3dSliceNDice
OVERVIEW ~1~ This program is for calculating the Dice coefficient between two volumes on a slice-by-slice basis. The user enters two volumes on the same grid, and Dice coefficients along each axis are calculated; three separate text (*.1D) files are output. The Dice coefficient (Dice, 1945) is known by many names and in many applications. In the present context it is defined as follows. Consider two sets voxels (i.e., masks), A and B. The Dice coefficient D is the ratio of their intersection to their union. Let N(x) be a function that calculates the number of voxels in a set x. Then: D = 2*N(intersection of A and B)/(N(A) + N(B)). The range of D is 0 (no overlap of A and B at all) to 1 (perfect overlap of A and B), inclusively. This program calculates D in a slicewise manner across all 3 major axes of a dset; other programs of interest for a volumewise Dice coefficient or more general overlap calculations include 3dABoverlap, for example. Nonzero values in a dset are considered part of the mask. 3dcalc might be useful in creating a mask from a dset if things like thresholding are required. written by PA Taylor (NIMH, NIH). USAGE ~1~ Input: + two single-volume datasets Output: + three text files, each a *.1D file of columns of numbers (and note that the executed 3dSliceNDice command is echoed into a comment in the top line of each 1D file by output). File name indicates along which axis the particular results were calculated, such as ending in '0_RL.1D', '1_AP.1D', '2_IS.1D', etc. For each file, there are currently 5 columns of data output, in the following order: [index] the i, j, or k index of the slice (starting from 0). [coord] the x, y, or z coordinate of the slice. [size of A ROI] the number of voxels in set A's ROI in the slice. [size of B ROI] the number of voxels in set B's ROI in the slice. [Dice coef] the Dice coefficient of that slice. 1dplot can be useful for viewing output results quickly. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * COMMAND ~1~ 3dSliceNDice \ -insetA AA \ -insetB BB \ -prefix PP \ {-out_range all|AorB|AandB} where -insetA AA :name of an input set to make a mask from; mask will be made from nonzero values in AA; -insetB BB :name of an input set to make a mask from; mask will be made from nonzero values in BB; -prefix PP :prefix of output files. Three output text files will be named according to the orientation of the input AA and BB files. So, outputs might look like: PP_0_RL.1D or PP_0_RL.1D, PP_1_AP.1D or PP_0_PA.1D, PP_2_IS.1D or PP_0_SI.1D. -out_domain all|AorB|AandB :optional specification of the slices over which to output Dice coefficient results along each axis, via keyword. Argument options at present: 'all': report Dice values for all slices (default); 'AorB': report values only in slices where sets A or B (or both) have at least one nonzero voxel; 'AandB': report values only in slices where both sets A and B have at least one nonzero voxel; 'Amask': report values only in slices where set A has at least one nonzero voxel; 'Bmask': report values only in slices where set B has at least one nonzero voxel; -no_cmd_echo :turn OFF recording the command line call to 3dSliceNDice in the output *.1D files (default is to do the recording). * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * EXAMPLES ~1~ 1. Report slicewise overlap of two masks through full FOV along each axis. 3dSliceNDice \ -insetA mask_1.nii.gz \ -insetB mask_2.nii.gz \ -prefix mask_olap_all 2. Report slicewise overlap of two masks only for slices where both dsets have >0 voxels in their masks 3dSliceNDice \ -insetA mask_1.nii.gz \ -insetB mask_2.nii.gz \ -out_domain AandB \ -prefix mask_olap_AandB To view the SliceNDice results: NB, you can use 1dplot for viewing either of the about output results, choosing slice number or DICOM coordinate value for the abscissa (x-axis) value. # use integer index values along x-axis of the plot, for one # encoding direction of the volume: 1dplot -x mask_olap_all_1_PA.1D'[0]' mask_olap_all_1_PA.1D'[4]' # use DICOM coordinate values along x-axis of the plot: 1dplot -x mask_olap_all_1_PA.1D'[1]' mask_olap_all_1_PA.1D'[4]' # ----------------------------------------------------------------------

AFNI program: 3dSpaceTimeCorr
3dSpaceTimeCorr v1.2 (PA Taylor, Aug. 2019) This program is for calculating something *similar* to the (Pearson) correlation coefficient between corresponding voxels between two data sets, which is what 3dTcorrelate does. However, this is program operates differently. Here, two data sets are loaded in, and for each voxel in the brain: + for each data set, an ijk-th voxel is used as a seed to generate a correlation map within a user-defined mask (e.g., whole brain, excluding the seed location where r==1, by definition); + that correlation map is Fisher Z transformed; + the Z-correlation maps are (Pearson) correlated with each other, generating a single correlation coefficient; + the correlation coefficient is stored at the same ijk-th voxel location in the output data set; and the process is repeated. Thus, the output is a whole brain map of r-correlation coefficients for corresponding voxels from the two data sets, generated by temporal and spatial patterns (-> space+time correlation!). This could be useful when someone *wishes* that s/he could use 3dTcorrelate on something like resting state FMRI data. Maybe. Note that this program could take several minutes or more to run, depending on the size of the data set and mask. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + USAGE: Load in 2 data sets and a mask. This computation can get pretty time consuming-- it depends on the number of voxels N like N**2. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: two 4D data sets need to be put in (order doesn't matter), and a mask also *should* be. 3dSpaceTimeCorr -insetA FILEA -insetB FILEB -prefix PREFIX \ {-mask MASK} {-out_Zcorr} {-freeze_insetA_ijk II JJ KK} {-freeze_insetA_xyz XX YY ZZ} where: -insetA FILEA :one 4D data set. -insetB FILEB :another 4D data set; must have same spatial dimensions as FILEA, as well as same number of time points. -mask MASK :optional mask. Highly recommended to use for speed of calcs (and probably for interpretability, too). -prefix PREFIX :output filename/base. -out_Zcorr :switch to output Fisher Z transform of spatial map correlation (default is Pearson r values). -freeze_insetA_ijk II JJ KK :instead of correlating the spatial correlation maps of A and B that have matching seed locations, with this option you can 'freeze' the seed voxel location in the input A dset, while the seed location in B moves throughout the volume or mask as normal. Here, one inputs three values, the ijk indices in the dataset. (See next opt for freezing at xyz location.) -freeze_insetA_xyz XX YY ZZ :same behavior as using '-freeze_insetA_ijk ..', but here one inputs the xyz (physical coordinate) indices. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUT: A data set with one value at each voxel, representing the space-time correlation of the two input data sets within the input mask. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dSpaceTimeCorr \ -insetA SUB_01.nii.gz \ -insetB SUB_02.nii.gz \ -mask mask_GM.nii.gz \ -prefix stcorr_01_02 \ ____________________________________________________________________________

AFNI program: 3dStatClust
++ 3dStatClust: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward Perform agglomerative hierarchical clustering for user specified parameter sub-bricks, for all voxels whose threshold statistic is above a user specified value. Usage: 3dStatClust options datasets where the options are: -prefix pname = Use 'pname' for the output dataset prefix name. OR [default='SC'] -output pname -session dir = Use 'dir' for the output dataset session directory. [default='./'=current working directory] -verb = Print out verbose output as the program proceeds. Options for calculating distance between parameter vectors: -dist_euc = Calculate Euclidean distance between parameters -dist_ind = Statistical distance for independent parameters -dist_cor = Statistical distance for correlated parameters The default option is: Euclidean distance. -thresh t tname = Use threshold statistic from file tname. Only voxels whose threshold statistic is greater than t in absolute value will be considered. [If file tname contains more than 1 sub-brick, the threshold stat. sub-brick must be specified!] -nclust n = This specifies the maximum number of clusters for output (= number of sub-bricks in output dataset). Command line arguments after the above are taken as parameter datasets. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dSurf2Vol
3dSurf2Vol - map data from a surface domain to an AFNI volume domain usage: 3dSurf2Vol [options] -spec SPEC_FILE -surf_A SURF_NAME \ -grid_parent AFNI_DSET -sv SURF_VOL \ -map_func MAP_FUNC -prefix OUTPUT_DSET This program is meant to take as input a pair of surfaces, optionally including surface data, and an AFNI grid parent dataset, and to output a new AFNI dataset consisting of the surface data mapped to the dataset grid space. The mapping function determines how to map the surface values from many nodes to a single voxel. Surfaces (from the spec file) are specified using '-surf_A' (and '-surf_B', if a second surface is input). If two surfaces are input, then the computed segments over node pairs will be in the direction from surface A to surface B. The basic form of the algorithm is: o for each node pair (or single node) o form a segment based on the xyz node coordinates, adjusted by any '-f_pX_XX' options o divide the segment up into N steps, according to the '-f_steps' option o for each segment point o if the point is outside the space of the output dataset, skip it o locate the voxel in the output dataset which corresponds to this segment point o if the '-cmask' option was given, and the voxel is outside the implied mask, skip it o if the '-f_index' option is by voxel, and this voxel has already been considered, skip it o insert the surface node value, according to the user-specified '-map_func' option Surface Coordinates: Surface coordinates are assumed to be in the Dicom orientation. This information may come from the option pair of '-spec' and '-sv', with which the user provides the name of the SPEC FILE and the SURFACE VOLUME, along with '-surf_A' and optionally '-surf_B', used to specify actual surfaces by name. Alternatively, the surface coordinates may come from the '-surf_xyz_1D' option. See these option descriptions below. Note that the user must provide either the three options '-spec', '-sv' and '-surf_A', or the single option, '-surf_xyz_1D'. Surface Data: Surface domain data can be input via the '-sdata_1D' or '-sdata' option. In such a case, the data is with respect to the input surface. Note: With -sdata_1D, the first column of the file should contain a node's index, and following columns are that node's data. See the '-sdata_1D' option for more info. Option -sdata takes NIML or GIFTI input which contain node index information in their headers. If the surfaces have V values per node (pair), then the resulting AFNI dataset will have V sub-bricks (unless the user applies the '-data_expr' option). Mapping Functions: Mapping functions exist because a single volume voxel may be occupied by multiple surface nodes or segment points. Depending on how dense the surface mesh is, the number of steps provided by the '-f_steps' option, and the indexing type from '-f_index', even a voxel which is only 1 cubic mm in volume may have quite a few contributing points. The mapping function defines how multiple surface values are combined to get a single result in each voxel. For example, the 'max' function will take the maximum of all surface values contributing to each given voxel. Current mapping functions are listed under the '-map_func' option, below. ------------------------------------------------------------ examples: 1. Map a single surface to an anatomical volume domain, creating a simple mask of the surface. The output dataset will be fred_surf+orig, and the orientation and grid spacing will follow that of the grid parent. The output voxels will be 1 where the surface exists, and 0 elsewhere. 3dSurf2Vol \ -spec fred.spec \ -surf_A pial \ -sv fred_anat+orig \ -grid_parent fred_anat+orig \ -map_func mask \ -prefix fred_surf 2. Map the cortical grey ribbon (between the white matter surface and the pial surface) to an AFNI volume, where the resulting volume is restricted to the mask implied by the -cmask option. Surface data will come from the file sdata_10.1D, which has 10 values per node, and lists only a portion of the entire set of surface nodes. Each node pair will be form a segment of 15 equally spaced points, the values from which will be applied to the output dataset according to the 'ave' filter. Since the index is over points, each of the 15 points will have its value applied to the appropriate voxel, even multiple times. This weights the resulting average by the fraction of each segment that occupies a given voxel. The output dataset will have 10 sub-bricks, according to the 10 values per node index in sdata_10.1D. 3dSurf2Vol \ -spec fred.spec \ -surf_A smoothwm \ -surf_B pial \ -sv fred_anat+orig \ -grid_parent 'fred_func+orig[0]' \ -cmask '-a fred_func+orig[2] -expr step(a-0.6)' \ -sdata_1D sdata_10.1D \ -map_func ave \ -f_steps 15 \ -f_index points \ -prefix fred_surf_ave 3. The inputs in this example are identical to those in example 2, including the surface dataset, sdata_10.1D. Again, the output dataset will have 10 sub-bricks. The surface values will be applied via the 'max_abs' filter, with the intention of assigning to each voxel the node value with the most significance. Here, the index method does not matter, so it is left as the default, 'voxel'. In this example, each node pair segment will be extended by 20% into the white matter, and by 10% outside of the grey matter, generating a "thicker" result. 3dSurf2Vol \ -spec fred.spec \ -surf_A smoothwm \ -surf_B pial \ -sv fred_anat+orig \ -grid_parent 'fred_func+orig[0]' \ -cmask '-a fred_func+orig[2] -expr step(a-0.6)' \ -sdata_1D sdata_10.1D \ -map_func max_abs \ -f_steps 15 \ -f_p1_fr -0.2 \ -f_pn_fr 0.1 \ -prefix fred_surf_max_abs 4. This is similar to example 2. Here, the surface nodes (coordinates) come from 'surf_coords_2.1D'. But these coordinates do not happen to be in Dicom orientation, they are in the same orientation as the grid parent, so the '-sxyz_orient_as_gpar' option is applied. Even though the data comes from 'sdata_10.1D', the output AFNI dataset will only have 1 sub-brick. That is because of the '-data_expr' option. Here, each applied surface value will be the average of the sines of the first 3 data values (columns of sdata_10.1D). 3dSurf2Vol \ -surf_xyz_1D surf_coords_2.1D \ -sxyz_orient_as_gpar \ -grid_parent 'fred_func+orig[0]' \ -sdata_1D sdata_10.1D \ -data_expr '(sin(a)+sin(b)+sin(c))/3' \ -map_func ave \ -f_steps 15 \ -f_index points \ -prefix fred_surf_ave_sine 5. In this example, voxels will get the maximum value from column 3 of sdata_10.1D (as usual, column 0 is used for node indices). The output dataset will have 1 sub-brick. Here, the output dataset is forced to be of type 'short', regardless of what the grid parent is. Also, there will be no scaling factor applied. To track the numbers for surface node #1234, the '-dnode' option has been used, along with '-debug'. Additionally, '-dvoxel' is used to track the results for voxel #6789. 3dSurf2Vol \ -spec fred.spec \ -surf_A smoothwm \ -surf_B pial \ -sv fred_anat+orig \ -grid_parent 'fred_func+orig[0]' \ -sdata_1D sdata_10.1D'[0,3]' \ -map_func max \ -f_steps 15 \ -datum short \ -noscale \ -debug 2 \ -dnode 1234 \ -dvoxel 6789 \ -prefix fred_surf_max 6. Draw some surface ROIs, and map them to the volume. Some voxels may contain nodes from multiple ROIs, so take the most common one (the mode), as suggested by R Mruczek. ROIs are left in 1D format for the -sdata_1D option. setenv AFNI_NIML_TEXT_DATA YES ROI2dataset -prefix rois.1D.dset -input rois.niml.roi 3dSurf2Vol \ -spec fred.spec \ -surf_A smoothwm \ -surf_B pial \ -sv fred_anat+orig \ -grid_parent 'fred_func+orig[0]' \ -sdata_1D rois.1D.dset \ -map_func mode \ -f_steps 10 \ -prefix rois.from.surf ------------------------------------------------------------ REQUIRED COMMAND ARGUMENTS: -spec SPEC_FILE : SUMA spec file e.g. -spec fred.spec The surface specification file contains the list of mappable surfaces that are used. See @SUMA_Make_Spec_FS and @SUMA_Make_Spec_SF. Note: this option, along with '-sv', may be replaced by the '-surf_xyz_1D' option. -surf_A SURF_NAME : specify surface A (from spec file) -surf_B SURF_NAME : specify surface B (from spec file) e.g. -surf_A smoothwm e.g. -surf_A lh.smoothwm e.g. -surf_B lh.pial This parameter is used to tell the program with surfaces to use. The '-surf_A' parameter is required, but the '-surf_B' parameter is an option. The surface names must uniquely match those in the spec file, though a sub-string match is good enough. The surface names are compared with the names of the surface node coordinate files. For instance, given a spec file that has only the left hemisphere in it, 'pial' should produce a unique match with lh.pial.asc. But if both hemispheres are included, then 'pial' would not be unique (matching rh.pial.asc, also). In that case, 'lh.pial' would be better. -sv SURFACE_VOLUME : AFNI dataset e.g. -sv fred_anat+orig This is the AFNI dataset that the surface is mapped to. This dataset is used for the initial surface node to xyz coordinate mapping, in the Dicom orientation. Note: this option, along with '-spec', may be replaced by the '-surf_xyz_1D' option. -surf_xyz_1D SXYZ_NODE_FILE : 1D coordinate file e.g. -surf_xyz_1D my_surf_coords.1D This ascii file contains a list of xyz coordinates to be considered as a surface, or 2 sets of xyz coordinates to considered as a surface pair. As usual, these points are assumed to be in Dicom orientation. Another option for coordinate orientation is to use that of the grid parent dataset. See '-sxyz_orient_as_gpar' for details. This option is an alternative to the pair of options, '-spec' and '-sv'. The number of rows of the file should equal the number of nodes on each surface. The number of columns should be either 3 for a single surface, or 6 for two surfaces. sample line of an input file (one surface): 11.970287 2.850751 90.896111 sample line of an input file (two surfaces): 11.97 2.85 90.90 12.97 2.63 91.45 -grid_parent AFNI_DSET : AFNI dataset e.g. -grid_parent fred_function+orig This dataset is used as a grid and orientation master for the output AFNI dataset. -map_func MAP_FUNC : surface to dataset function e.g. -map_func max e.g. -map_func mask -f_steps 20 This function applies to the case where multiple data points get mapped to a single voxel, which is expected since surfaces tend to have a much higher resolution than AFNI volumes. In the general case data points come from each point on each partitioned line segment, with one segment per node pair. Note that these segments may have length zero, such as when only a single surface is input. See "Mapping Functions" above, for more information. The current mapping function for one surface is: mask : For each xyz location, set the corresponding voxel to 1. The current mapping functions for two surfaces are as follows. These descriptions are per output voxel, and over the values of all points mapped to a given voxel. mask2 : if any points are mapped to the voxel, set the voxel value to 1 ave : average all values nzave : ave, but ignoring any zero values count : count the number of mapped data points min : find the minimum value from all mapped points max : find the maximum value from all mapped points max_abs: find the number with maximum absolute value (the resulting value will retain its sign) median : median of all mapped values nzmedian: median, but ignoring any zero values mode : apply the most common value per voxel (minimum mode, if they are not unique) (appropriate where surf ROIs overlap) nzmode : mode, but ignoring any zero values -prefix OUTPUT_PREFIX : prefix for the output dataset e.g. -prefix anat_surf_mask This is used to specify the prefix of the resulting AFNI dataset. ------------------------------ SUB-SURFACE DATA FILE OPTIONS: -sdata_1D SURF_DATA.1D : 1D sub-surface file, with data e.g. -sdata_1D roi3.1D This is used to specify a 1D file, which contains surface indices and data. The indices refer to the surface(s) read from the spec file. The format of this data file is a surface index and a list of data values on each row. To be a valid 1D file, each row must have the same number of columns. -sdata SURF_DATA_DSET: NIML, or GIFTI formatted dataset. ------------------------------ OPTIONS SPECIFIC TO SEGMENT SELECTION: (see "The basic form of the algorithm" for more details) -f_steps NUM_STEPS : partition segments e.g. -f_steps 10 default: -f_steps 2 (or 1, the number of surfaces) This option specifies the number of points to divide each line segment into, before mapping the points to the AFNI volume domain. The default is the number of input surfaces (usually, 2). The default operation is to have the segment endpoints be the actual surface nodes, unless they are altered with the -f_pX_XX options. -f_index TYPE : index by points or voxels e.g. -f_index points e.g. -f_index voxels default: -f_index voxels Along a single segment, the default operation is to apply only those points mapping to a new voxel. The effect of the default is that a given voxel will have at most one value applied per voxel pair. If the user applies this option with 'points' or 'nodes' as the argument, then every point along the segment will be applied. This may be preferred if, for example, the user wishes to have the average weighted by the number of points occupying a voxel, not just the number of node pair segments. Note: the following -f_pX_XX options are used to alter the locations of the segment endpoints, per node pair. The segments are directed, from the node on the first surface to the node on the second surface. To modify the first endpoint, use a -f_p1_XX option, and use -f_pn_XX to modify the second. -f_p1_fr FRACTION : offset p1 by a length fraction e.g. -f_p1_fr -0.2 e.g. -f_p1_fr -0.2 -f_pn_fr 0.2 This option moves the first endpoint, p1, by a distance of the FRACTION times the original segment length. If the FRACTION is positive, it moves in the direction of the second endpoint, pn. In the example, p1 is moved by 20% away from pn, which will increase the length of each segment. -f_pn_fr FRACTION : offset pn by a length fraction e.g. -f_pn_fr 0.2 e.g. -f_p1_fr -0.2 -f_pn_fr 0.2 This option moves pn by a distance of the FRACTION times the original segment length, in the direction from p1 to pn. So a positive fraction extends the segment, and a negative fraction reduces it. In the example above, using 0.2 adds 20% to the segment length past the original pn. -f_p1_mm DISTANCE : offset p1 by a distance in mm. e.g. -f_p1_mm -1.0 e.g. -f_p1_mm -1.0 -f_pn_fr 1.0 This option moves p1 by DISTANCE mm., in the direction of pn. If the DISTANCE is positive, the segment gets shorter. If DISTANCE is negative, the segment will get longer. In the example, p1 is moved away from pn, extending the segment by 1 millimeter. -f_pn_mm DISTANCE : offset pn by a distance in mm. e.g. -f_pn_mm 1.0 e.g. -f_p1_mm -1.0 -f_pn_fr 1.0 This option moves pn by DISTANCE mm., in the direction from the first point to the second. So if DISTANCE is positive, the segment will get longer. If DISTANCE is negative, the segment will get shorter. In the example, pn is moved 1 millimeter farther from p1, extending the segment by that distance. -stop_gap : stop when a zero gap has been hit This limits segment processing such that once a non-zero mask value has been encountered, the segment will be terminated on any subsequent zero mask value. The goal is to prevent mixing masked cortex regions. ------------------------------ GENERAL OPTIONS: -cmask MASK_COMMAND : command for dataset mask e.g. -cmask '-a fred_func+orig[2] -expr step(a-0.8)' This option will produce a mask to be applied to the output dataset. Note that this mask should form a single sub-brick. This option follows the style of 3dmaskdump (since the code for it was, uh, borrowed from there (thanks Bob!)). See '3dmaskdump -help' for more information. -data_expr EXPRESSION : apply expression to surface input e.g. -data_expr 17 e.g. -data_expr '(a+b+c+d)/4' e.g. -data_expr '(sin(a)+sin(b))/2' This expression is applied to the list of data values from the surface data file input via '-sdata_1D'. The expression is applied for each node or node pair, to the list of data values corresponding to that node. The letters 'a' through 'z' may be used as input, and refer to columns 1 through 26 of the data file (where column 0 is a surface node index). The data file must have enough columns to support the expression. It is valid to have a constant expression without a data file. -datum DTYPE : set data type in output dataset e.g. -datum short default: based on the map function (was grid_parent, but that made little sense) This option specifies the data type for the output data volume. Valid choices are byte, short and float, which are 1, 2 and 4 bytes for each data point, respectively. The default is based on the map function, generally implying float, unless using mask or mask2 (byte), or count or mode (short). -debug LEVEL : verbose output e.g. -debug 2 This option is used to print out status information during the execution of the program. Current levels are from 0 to 5. -dnode DEBUG_NODE : extra output for that node e.g. -dnode 123456 This option requests additional debug output for the given surface node. This index is with respect to the input surface (included in the spec file, or through the '-surf_xyz_1D' option). This will have no effect without the '-debug' option. -dvoxel DEBUG_VOXEL : extra output for that voxel e.g. -dvoxel 234567 This option requests additional debug output for the given volume voxel. This 1-D index is with respect to the output data volume. One good way to find a voxel index to supply is from output via the '-dnode' option. This will have no effect without the '-debug' option. -hist : show revision history Display module history over time. -help : show this help If you can't get help here, please get help somewhere. -noscale : no scale factor in output dataset If the output dataset is an integer type (byte, shorts or ints), then the output dataset may end up with a scale factor attached (see 3dcalc -help). With this option, the output dataset will not be scaled. -sxyz_orient_as_gpar : assume gpar orientation for sxyz This option specifies that the surface coordinate points in the '-surf_xyz_1D' option file have the orientation of the grid parent dataset. When the '-surf_xyz_1D' option is applied the surface coordinates are assumed to be in Dicom orientation, by default. This '-sxyz_orient_as_gpar' option overrides the Dicom default, specifying that the node coordinates are in the same orientation as the grid parent dataset. See the '-surf_xyz_1D' option for more information. -version : show version information Show version and compile date. ------------------------------------------------------------ Author: R. Reynolds - version 3.10 (June 22, 2021) (many thanks to Z. Saad and R.W. Cox)

AFNI program: 3dSurfMask
Usage: 3dSurfMask <-i_TYPE SURFACE> <-prefix PREFIX> [<-fill_method METH>] <-grid_parent GRID_VOL> [-sv SURF_VOL] [-mask_only] Creates 2 volumetric datasets that mark voxel based on their location relative to the surface. Voxels in the first volume (named PREFIX.m) label voxel positions relative to the surface. With -fill_method set to FAST, you get a a CRUDE mask with voxel values set to the following: 0: Voxel outside surface 1: Voxel just outside the surface. This means the voxel center is outside the surface but inside the bounding box of a triangle in the mesh. 2: Voxel intersects the surface (a triangle), but center lies outside. 3: Voxel contains a surface node. 4: Voxel intersects the surface (a triangle), center lies inside surface. 5: Voxel just inside the surface. This means the voxel center is inside the surface and inside the bounding box of a triangle in the mesh. 6: Voxel inside the surface. Masks obtained with -fill_method FAST could have holes in them. To decide on whether a voxel lies inside or outside the surface you should use the signed distances in PREFIX.d below, or use -fill_method slow. With -fill_method set to SLOW you get a better mask with voxels set to the following: 0: Voxel outside surface 1: Voxel outside the surface but in its bounding box 2: Voxel inside the surface Voxels values in the second volume (named PREFIX.d) reflect the shortest distance of voxels in PREFIX.m to the surface. The distances are signed to reflect whether a voxel is inside or outsider the surface. Voxels inside the surface have positive distances, voxels outside have a negative distance. If the signs appear reversed, use option -flip_orientation. Mandatory Parameters: -i_TYPE SURFACE: Specify input surface. You can also use -t* and -spec and -surf methods to input surfaces. See below for more details. -prefix PREFIX: Prefix of output dataset. -grid_parent GRID_VOL: Specifies the grid for the output volume. Other parameters: -mask_only: Produce an output dataset where voxels are 1 inside the surface and 0 outside, instead of the more nuanced output above. -flip_orientation: Flip triangle winding of surface mesh. Use this option when the sign of the distances in PREFIX.m comes out wrong. Voxels inside the surface have a positive distance. This can happen when the winding of the triangles is reversed. -fill_method METH: METH can take two values; SLOW, and FAST[default]. FAST can produce holes under certain conditions. -no_dist: Do not compute the distances, just the mask from the first step. Example: (tcsh syntax) 1- Find distance of voxels around and inside of toy surface: echo 'Create toy data' @auto_tlrc -base TT_N27+tlrc -base_copy ToyVolume CreateIcosahedron -rad 50 -ld 1 sed 's/Anatomical = N/Anatomical = Y/' CreateIco.spec > __ttt mv __ttt CreateIco.spec echo 'Do computations' 3dSurfMask -i_fs CreateIco.asc -sv ToyVolume+tlrc \ -prefix ToyMasks -flip_orientation \ -grid_parent ToyVolume+tlrc echo 'Cut and paste commands below to show you the results' suma -npb 70 -niml -spec CreateIco.spec -sv ToyVolume+tlrc & afni -npb 70 -niml -yesplugouts & DriveSuma -npb 70 -com viewer_cont -key 't' plugout_drive -npb 70 -com 'SET_OVERLAY A ToyMasks.d' \ -com 'SET_THRESHOLD A.0' \ -com 'SET_PBAR_NUMBER A.10' \ -quit See also examples in SurfPatch -help Specifying input surfaces using -i or -i_TYPE options: -i_TYPE inSurf specifies the input surface, TYPE is one of the following: fs: FreeSurfer surface. If surface name has .asc it is assumed to be in ASCII format. Otherwise it is assumed to be in BINARY_BE (Big Endian) format. Patches in Binary format cannot be read at the moment. sf: SureFit surface. You must specify the .coord followed by the .topo file. vec (or 1D): Simple ascii matrix format. You must specify the coord (NodeList) file followed by the topo (FaceSetList) file. coord contains 3 floats per line, representing X Y Z vertex coordinates. topo contains 3 ints per line, representing v1 v2 v3 triangle vertices. ply: PLY format, ascii or binary. Only vertex and triangulation info is preserved. stl: STL format, ascii or binary. This format of no use for much of the surface-based analyses. Objects are defined as a soup of triangles with no information about which edges they share. STL is only useful for taking surface models to some 3D printing software. mni: MNI .obj format, ascii only. Only vertex, triangulation, and node normals info is preserved. byu: BYU format, ascii. Polygons with more than 3 edges are turned into triangles. bv: BrainVoyager format. Only vertex and triangulation info is preserved. dx: OpenDX ascii mesh format. Only vertex and triangulation info is preserved. Requires presence of 3 objects, the one of class 'field' should contain 2 components 'positions' and 'connections' that point to the two objects containing node coordinates and topology, respectively. gii: GIFTI XML surface format. obj: OBJ file format for triangular meshes only. The following primitives are preserved: v (vertices), f (faces, triangles only), and p (points) Note that if the surface filename has the proper extension, it is enough to use the -i option and let the programs guess the type from the extension. You can also specify multiple surfaces after -i option. This makes it possible to use wildcards on the command line for reading in a bunch of surfaces at once. -onestate: Make all -i_* surfaces have the same state, i.e. they all appear at the same time in the viewer. By default, each -i_* surface has its own state. For -onestate to take effect, it must precede all -i options with on the command line. -anatomical: Label all -i surfaces as anatomically correct. Again, this option should precede the -i_* options. More variants for option -i: ----------------------------- You can also load standard-mesh spheres that are formed in memory with the following notation -i ldNUM: Where NUM is the parameter controlling the mesh density exactly as the parameter -ld linDepth does in CreateIcosahedron. For example: suma -i ld60 create on the fly a surface that is identical to the one produced by: CreateIcosahedron -ld 60 -tosphere -i rdNUM: Same as -i ldNUM but with NUM specifying the equivalent of parameter -rd recDepth in CreateIcosahedron. To keep the option confusing enough, you can also use -i to load template surfaces. For example: suma -i lh:MNI_N27:ld60:smoothwm will load the left hemisphere smoothwm surface for template MNI_N27 at standard mesh density ld60. The string following -i is formatted thusly: HEMI:TEMPLATE:DENSITY:SURF where: HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh' or 'rh'. You must specify a hemisphere with option -i because it is supposed to load one surface at a time. You can load multiple surfaces with -spec which also supports these features. TEMPLATE: Specify the template name. For now, choose from MNI_N27 if you want to use the FreeSurfer reconstructed surfaces from the MNI_N27 volume, or TT_N27 Those templates must be installed under this directory: /home/afniHQ/.afni/data/ If you have no surface templates there, download https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz and/or https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz and/or https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI152_2009.tgz and untar them under directory /home/afniHQ/.afni/data/ DENSITY: Use if you want to load standard-mesh versions of the template surfaces. Note that only ld20, ld60, ld120, and ld141 are in the current distributed templates. You can create other densities if you wish with MapIcosahedron, but follow the same naming convention to enable SUMA to find them. SURF: Which surface do you want. The string matching is partial, as long as the match is unique. So for example something like: suma -i l:MNI_N27:ld60:smooth is more than enough to get you the ld60 MNI_N27 left hemisphere smoothwm surface. The order in which you specify HEMI, TEMPLATE, DENSITY, and SURF, does not matter. For template surfaces, the -sv option is provided automatically, so you can have SUMA talking to AFNI with something like: suma -i l:MNI_N27:ld60:smooth & afni -niml /home/afniHQ/.afni/data/suma_MNI_N27 Specifying surfaces using -t* options: -tn TYPE NAME: specify surface type and name. See below for help on the parameters. -tsn TYPE STATE NAME: specify surface type state and name. TYPE: Choose from the following (case sensitive): 1D: 1D format FS: FreeSurfer ascii format PLY: ply format MNI: MNI obj ascii format BYU: byu format SF: Caret/SureFit format BV: BrainVoyager format GII: GIFTI format NAME: Name of surface file. For SF and 1D formats, NAME is composed of two names the coord file followed by the topo file STATE: State of the surface. Default is S1, S2.... for each surface. Specifying a Surface Volume: -sv SurfaceVolume [VolParam for sf surfaces] If you supply a surface volume, the coordinates of the input surface. are modified to SUMA's convention and aligned with SurfaceVolume. You must also specify a VolParam file for SureFit surfaces. Specifying a surface specification (spec) file: -spec SPEC: specify the name of the SPEC file. As with option -i, you can load template spec files with symbolic notation trickery as in: suma -spec MNI_N27 which will load the all the surfaces from template MNI_N27 at the original FreeSurfer mesh density. The string following -spec is formatted in the following manner: HEMI:TEMPLATE:DENSITY where: HEMI specifies a hemisphere. Choose from 'l', 'r', 'lh', 'rh', 'lr', or 'both' which is the default if you do not specify a hemisphere. TEMPLATE: Specify the template name. For now, choose from MNI_N27 if you want surfaces from the MNI_N27 volume, or TT_N27 for the Talairach version. Those templates must be installed under this directory: /home/afniHQ/.afni/data/ If you have no surface templates there, download one of: https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI_N27.tgz https://afni.nimh.nih.gov/pub/dist/tgz/suma_TT_N27.tgz https://afni.nimh.nih.gov/pub/dist/tgz/suma_MNI152_2009.tgz and untar them under directory /home/afniHQ/.afni/data/ DENSITY: Use if you want to load standard-mesh versions of the template surfaces. Note that only ld20, ld60, ld120, and ld141 are in the current distributed templates. You can create other densities if you wish with MapIcosahedron, but follow the same naming convention to enable SUMA to find them. This parameter is optional. The order in which you specify HEMI, TEMPLATE, and DENSITY, does not matter. For template surfaces, the -sv option is provided automatically, so you can have SUMA talking to AFNI with something like: suma -spec MNI_N27:ld60 & afni -niml /home/afniHQ/.afni/data/suma_MNI_N27 Specifying a surface using -surf_? method: -surf_A SURFACE: specify the name of the first surface to load. If the program requires or allows multiple surfaces, use -surf_B ... -surf_Z . You need not use _A if only one surface is expected. SURFACE is the name of the surface as specified in the SPEC file. The use of -surf_ option requires the use of -spec option. Ziad S. Saad SSCC/NIMH/NIH saadz@mail.nih.gov

AFNI program: 3dsvm
Program: 3dsvm +++++++++++ 3dsvm: support vector machine analysis of brain data +++++++++++ 3dsvm - temporally predictive modeling with the support vector machine This program provides the ability to perform support vector machine (SVM) learning on AFNI datasets using the SVM-light package (version 5) developed by Thorsten Joachims (http://svmlight.joachims.org/). ----------------------------------------------------------------------------- Usage: ------ 3dsvm [options] Examples: --------- 1. Training: basic options require a training run, category (class) labels for each timepoint, and an output model. In general, it usually makes sense to include a mask file to exclude at least non-brain voxels 3dsvm -trainvol run1+orig \ -trainlabels run1_categories.1D \ -mask mask+orig \ -model model_run1 2. Training: obtain model alphas (a_run1.1D) and model weights (fim: run1_fim+orig) 3dsvm -alpha a_run1 \ -trainvol run1+orig \ -trainlabels run1_categories.1D \ -mask mask+orig \ -model model_run1 -bucket run1_fim 3. Training: exclude some time points using a censor file 3dsvm -alpha a_run1 \ -trainvol run1+orig \ -trainlabels run1_categories.1D \ -censor censor.1D \ -mask mask+orig \ -model model_run1 -bucket run1_fim 4. Training: control svm model complexity (C value) 3dsvm -c 100.0 \ -alpha a_run1 \ -trainvol run1+orig \ -trainlabels run1_categories.1D \ -censor censor.1D \ -mask mask+orig \ -model model_run1 -bucket run1_fim 5. Training: using a kernel 3dsvm -c 100.0 \ -kernel polynomial -d 2 \ -alpha a_run1 \ -trainvol run1+orig \ -trainlabels run1_categories.1D \ -censor censor.1D \ -mask mask+orig \ -model model_run1 6. Training: using regression 3dsvm -type regression \ -c 100.0 \ -e 0.001 \ -alpha a_run1 \ -trainvol run1+orig \ -trainlabels run1_categories.1D \ -censor censor.1D \ -mask mask+orig \ -model model_run1 7. Testing: basic options require a testing run, a model, and an output predictions file 3dsvm -testvol run2+orig \ -model model_run1+orig \ -predictions pred2_model1 8. Testing: compare predictions with 'truth' 3dsvm -testvol run2+orig \ -model model_run1+orig \ -testlabels run2_categories.1D \ -predictions pred2_model1 9. Testing: use -classout to output integer thresholded class predictions (rather than continuous valued output) 3dsvm -classout \ -testvol run2+orig \ -model model_run1+orig \ -testlabels run2_categories.1D \ -predictions pred2_model1 options: -------- ------------------- TRAINING OPTIONS ------------------------------------------- -type tname Specify tname: classification [default] regression to select between classification or regression. -trainvol trnname A 3D+t AFNI brik dataset to be used for training. -mask mname Specify a mask dataset to only perform the analysis on non-zero mask voxels. ++ If '-mask' is not used '-nomodelmask must be specified. For example, a mask of the whole brain can be generated by using 3dAutomask, or more specific ROIs could be generated with the Draw Dataset plugin or converted from a thresholded functional dataset. The mask is specified during training but is also considered part of the model output and is automatically applied to test data. -nomodelmask Flag to enable the omission of a mask file. This is required if '-mask' is not used. -trainlabels lname lname = filename of class category .1D labels corresponding to the stimulus paradigm for the training data set. The number of labels in the selected file must be equal to the number of time points in the training dataset. The labels must be arranged in a single column, and they can be any of the following values: 0 - class 0 1 - class 1 n - class n (where n is a positive integer) 9999 - censor this point See also -censor. -censor cname Specify a .1D censor file that allows the user to ignore certain samples in the training data. To ignore a specific sample, put a 0 in the row corresponding to the time sample - i.e., to ignore sample t, place a 0 in row t of the file. All samples that are to be included for training must have a 1 in the corresponding row. If no censor file is specified, all samples will be used for training. Note the lname file specified by trainlabels can also be used to censor time points (see -trainlabels). -kernel kfunc kfunc = string specifying type of kernel function: linear : <u,v> [default] polynomial : (s<u,v> + r)^d rbf : radial basis function exp(-gamma ||u-v||^2) sigmoid : tanh(s <u,v> + r)) note: kernel parameters use SVM-light syntax: -d int : d parameter in polyniomial kernel 3 [default] -g float : gamma parameter in rbf kernel 1.0 [default] -s float : s parameter in sigmoid/poly kernel 1.0 [default] -r float : r parameter in sigmoid/poly kernel 1.0 [default] -max_iterations int Specify the maximum number of iterations for the optimization. 1 million [default]. -alpha aname Write the alphas to aname.1D -wout Flag to output sum of weighted linear support vectors to the bucket file. This is one means of generating an "activation map" from linear kernel SVMs see (LaConte et al., 2005). NOTE: this is currently not required since it is the only output option. -bucket bprefix Currently only outputs the sum of weighted linear support vectors written out to a functional (fim) brik file. This is one means of generating an "activation map" from linear kernel SVMS (see LaConte et al, 2005). ------------------- TRAINING AND TESTING MUST SPECIFY MODNAME ------------------ -model modname modname = basename for the model brik. Training: modname is the basename for the output brik containing the SVM model 3dsvm -trainvol run1+orig \ -trainlabels run1_categories.1D \ -mask mask+orig \ -model model_run1 Testing: modname is the name for the input brik containing the SVM model. 3dsvm -testvol run2+orig \ -model model_run1+orig \ -predictions pred2_model1 -nomodelfile Flag to enable the omission of a model file. This is required if '-model' is not used during training. ** Be careful, you might not be able to perform testing! ------------------- TESTING OPTIONS -------------------------------------------- -testvol tstname A 3D or 3D+t AFNI brik dataset to be used for testing. A major assumption is that the training and testing volumes are aligned, and that voxels are of same number, volume, etc. -predictions pname pname = basename for .1D prediction file(s). Prediction files contain a single column, where each line holds the predicted value for the corresponding volume in the test dataset. By default, the predicted values take on a continuous range; to output integer-valued class decision values use the -classout flag. For classification: Values below 0.5 correspond to (class A) and values above 0.5 to (class B), where A < B. For more than two classes a separate prediction file for each possible pair of training classes and one additional "overall" file containing the predicted (integer-valued) class membership is generated. For regression: Each value is the predicted parametric rate for the corresponding volume in the test dataset. -classout Flag to specify that pname files should be integer- valued, corresponding to class category decisions. -nopredcensored Do not write predicted values for censored time-points to predictions file. -nodetrend Flag to specify that pname files should NOT be linearly detrended (detrending is performed by default). ** Set this options if you are using GLM beta maps as input for example. Temporal detrending only makes sense if you are using time-dependent data (chronological order!) as input. -nopredscale Do not scale predictions. If used, values below 0.0 correspond to (class A) and values above 0.0 to (class B). -testlabels tlname tlname = filename of 'true' class category .1D labels for the test dataset. It is used to calculate the prediction accuracy performance of SVM classification. If this option is not specified, then performance calculations are not made. Format is the same as lname specified for -trainlabels. -multiclass mctype mctype specifies the multiclass algorithm for classification. Current implementations use 1-vs-1 two-class SVM models. mctype must be one of the following: DAG : Directed Acyclic Graph [default] vote : Max Wins from votes of all 1-vs-1 models see https://lacontelab.org/3dsvm.htm for details and references. ------------------- INFORMATION OPTIONS --------------------------------------- -help this help -version print version history including rough description of changes -------------------- SVM-light learn help ----------------------------- SVM-light V5.00: Support Vector Machine, learning module 30.06.02stim Copyright: Thorsten Joachims, thorsten@ls8.cs.uni-dortmund.de This software is available for non-commercial use only. It must not be modified and distributed without prior permission of the author. The author is not responsible for implications from the use of this software. usage: svm_learn [options] example_file model_file Arguments: example_file-> file with training data model_file -> file to store learned decision rule in General options: -? -> this help -v [0..3] -> level (default 1) Learning options: -z {c,r,p} -> select between classification (c), regression (r), and preference ranking (p) (default classification) -c float -> C: trade-off between training error and margin (default [avg. x*x]^-1) -w [0..] -> epsilon width of tube for regression (default 0.1) -j float -> Cost: cost-factor, by which training errors on positive examples outweigh errors on negative examples (default 1) (see [4]) -b [0,1] -> use biased hyperplane (i.e. x*w+b>0) instead of unbiased hyperplane (i.e. x*w>0) (default 1) -i [0,1] -> remove inconsistent training examples and retrain (default 0) Performance estimation options: -x [0,1] -> compute leave-one-out estimates (default 0) (see [5]) -o ]0..2] -> value of rho for XiAlpha-estimator and for pruning leave-one-out computation (default 1.0) (see [2]) -k [0..100] -> search depth for extended XiAlpha-estimator (default 0) Transduction options (see [3]): -p [0..1] -> fraction of unlabeled examples to be classified into the positive class (default is the ratio of positive and negative examples in the training data) Kernel options: -t int -> type of kernel function: 0: linear (default) 1: polynomial (s a*b+c)^d 2: radial basis function exp(-gamma ||a-b||^2) 3: sigmoid tanh(s a*b + c) 4: user defined kernel from kernel.h -d int -> parameter d in polynomial kernel -g float -> parameter gamma in rbf kernel -s float -> parameter s in sigmoid/poly kernel -r float -> parameter c in sigmoid/poly kernel -u string -> parameter of user defined kernel Optimization options (see [1]): -q [2..] -> maximum size of QP-subproblems (default 10) -n [2..q] -> number of new variables entering the working set in each iteration (default n = q). Set n<q to prevent zig-zagging. -m [5..] -> size of cache for kernel evaluations in MB (default 40) The larger the faster... -e float -> eps: Allow that error for termination criterion [y [w*x+b] - 1] >= eps (default 0.001) -h [5..] -> number of iterations a variable needs to be optimal before considered for shrinking (default 100) -f [0,1] -> do final optimality check for variables removed by shrinking. Although this test is usually positive, there is no guarantee that the optimum was found if the test is omitted. (default 1) Output options: -l string -> file to write predicted labels of unlabeled examples into after transductive learning -a string -> write all alphas to this file after learning (in the same order as in the training set) More details in: [1] T. Joachims, Making Large-Scale SVM Learning Practical. Advances in Kernel Methods - Support Vector Learning, B. Schoelkopf and C. Burges and A. Smola (ed.), MIT Press, 1999. [2] T. Joachims, Estimating the Generalization performance of an SVM Efficiently. International Conference on Machine Learning (ICML), 2000. [3] T. Joachims, Transductive Inference for Text Classification using Support Vector Machines. International Conference on Machine Learning (ICML), 1999. [4] K. Morik, P. Brockhausen, and T. Joachims, Combining statistical learning with a knowledge-based approach - A case study in intensive care monitoring. International Conference on Machine Learning (ICML), 1999. [5] T. Joachims, Learning to Classify Text Using Support Vector Machines: Methods, Theory, and Algorithms. Dissertation, Kluwer, 2002. -------------------- SVM-light classify help ----------------------------- SVM-light V5.00: Support Vector Machine, classification module 30.06.02 Copyright: Thorsten Joachims, thorsten@ls8.cs.uni-dortmund.de This software is available for non-commercial use only. It must not be modified and distributed without prior permission of the author. The author is not responsible for implications from the use of this software. usage: svm_classify [options] example_file model_file output_file options: -h -> this help -v [0..3] -> verbosity level (default 2) -f [0,1] -> 0: old output format of V1.0 -> 1: output the value of decision function (default) -------------------------------------------------------------------------- Significant programming contributions by: Jeff W. Prescott, William A. Curtis, Ziad Saad, Rick Reynolds, R. Cameron Craddock, Jonathan M. Lisinski, and Stephen M. LaConte Original version written by JP and SL, August 2006 Released to general public, July 2007 Questions/Comments/Bugs - email slaconte@vtc.vt.edu Reference: LaConte, S., Strother, S., Cherkassky, V. and Hu, X. 2005. Support vector machines for temporal classification of block design fMRI data. NeuroImage, 26, 317-329. Specific to real-time fMRI: S. M. LaConte. (2011). Decoding fMRI brain states in real-time. NeuroImage, 56:440-54. S. M. LaConte, S. J. Peltier, and X. P. Hu. (2007). Real-time fMRI using brain-state classification. Hum Brain Mapp, 208:1033–1044. Please also consider to reference: T. Joachims, Making Large-Scale SVM Learning Practical. Advances in Kernel Methods - Support Vector Learning, B. Schoelkopf and C. Burges and A. Smola (ed.), MIT Press, 1999. RW Cox. AFNI: Software for analysis and visualization of functional magnetic resonance neuroimages. Computers and Biomedical Research, 29:162-173, 1996.

AFNI program: 3dsvm_linpredict
Usage: 3ddot [options] w dset Output = linear prediction for w from 3dsvm - you can use sub-brick selectors on the dsets - the result is a number printed to stdout Options: -mask mset Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be averaged from 'dataset'. Note that the mask dataset and the input dataset must have the same number of voxels. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dSynthesize
Usage: 3dSynthesize options Reads a '-cbucket' dataset and a '.xmat.1D' matrix from 3dDeconvolve, and synthesizes a fit dataset using selected sub-bricks and matrix columns. Options (actually, the first 3 are mandatory) --------------------------------------------- -cbucket ccc = Read the dataset 'ccc', which should have been output from 3dDeconvolve via the '-cbucket' option. -matrix mmm = Read the matrix 'mmm', which should have been output from 3dDeconvolve via the '-x1D' option. -select sss = Selects specific columns from the matrix (and the corresponding coefficient sub-bricks from the cbucket). The string 'sss' can be of the forms: baseline = All baseline coefficients. polort = All polynomial baseline coefficients (skipping -stim_base coefficients). allfunc = All coefficients that are NOT marked (in the -matrix file) as being in the baseline (i.e., all -stim_xxx values except those with -stim_base) allstim = All -stim_xxx coefficients, including those with -stim_base. all = All coefficients (should give results equivalent to '3dDeconvolve -fitts'). something = All columns/coefficients that match this -stim_label from 3dDeconvolve [to be precise, all columns whose ] [-stim_label starts with 'something'] [will be selected for inclusion. ] digits = Columns can also be selected by numbers (starting at 0), or number ranges of the form 3..7 and 3-7. [A string is a number range if it] [comprises only digits and the ] [characters '.' and/or '-'. ] [Otherwise, it is used to match ] [a -stim_label. ] More than one '-select sss' option can be used, or you can put more than one string after the '-select', as in this example: 3dSynthesize -matrix fred.xmat.1D -cbucket fred+orig \ -select baseline FaceStim -prefix FS which synthesizes the baseline and 'FaceStim' responses together, ignoring any other stimuli in the dataset and matrix. -dry = Don't compute the output, just check the inputs. -TR dt = Set TR in the output to 'dt'. The default value of TR is read from the header of the matrix file. -prefix ppp = Output result into dataset with name 'ppp'. -cenfill xxx = Determines how censored time points from the 3dDeconvolve run will be filled. 'xxx' is one of: zero = 0s will be put in at all censored times nbhr = average of non-censored neighboring times none = don't put the censored times in at all (in which case the created dataset is) (shorter than the input to 3dDeconvolve) If you don't give some -cenfill option, the default operation is 'zero'. This default is different than previous versions of this program, which did 'none'. **N.B.: You might like the program to compute the model fit at the censored times, like it does at all others. This CAN be done if you input the matrix file saved by the '-x1D_uncensored' option in 3dDeconvolve. NOTES: -- You could do the same thing in 3dcalc, but this way is simpler and faster. But less flexible, of course. -- The output dataset is always stored as floats. -- The -cbucket dataset must have the same number of sub-bricks as the input matrix has columns. -- Each column in the matrix file is a time series, used to model some component of the data time series at each voxel. -- The sub-bricks of the -cbucket dataset give the weighting coefficients for these model time series, at each voxel. -- If you want to calculate a time series dataset wherein the original time series data has the baseline subtracted, then you could use 3dSynthesize to compute the baseline time series dataset, and then use 3dcalc to subtract that dataset from the original dataset. -- Other similar applications are left to your imagination. -- To see the column labels stored in matrix file 'fred.xmat.1D', type the Unix command 'grep ColumnLabels fred.xmat.1D'; sample output: # ColumnLabels = "Run#1Pol#0 ; Run#1Pol#1 ; Run#2Pol#0 ; Run#2Pol#1 ; FaceStim#0 ; FaceStim#1 ; HouseStim#0 ; HouseStim#1" which shows the 4 '-polort 1' baseline parameters from 2 separate imaging runs, and then 2 parameters each for 'FaceStim' and 'HouseStim'. -- The matrix file written by 3dDeconvolve has an XML-ish header before the columns of numbers, stored in '#' comment lines. If you want to generate your own 'raw' matrix file, without this header, you can still use 3dSynthesize, but then you can only use numeric '-select' options (or 'all'). -- When using a 'raw' matrix, you'll probably also want the '-TR' option. -- When putting more than one string after '-select', do NOT combine these separate strings together in quotes. If you do, they will be seen as a single string, which almost surely won't match anything. -- Author: RWCox -- March 2007 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTagalign
Usage: 3dTagalign [options] dset Rotates/translates dataset 'dset' to be aligned with the master, using the tagsets embedded in their .HEAD files. Options: -master mset = Use dataset 'mset' as the master dataset [this is a nonoptional option] -tagset tfile = Use the tagset in the .tag file instead of dset. -nokeeptags = Don't put transformed locations of dset's tags into the output dataset [default = keep tags] -matvec mfile = Write the matrix+vector of the transformation to file 'mfile'. This can be used as input to the '-matvec_in2out' option of 3dWarp, if you want to align other datasets in the same way (e.g., functional datasets). -rotate = Compute the best transformation as a rotation + shift. This is the default. -affine = Compute the best transformation as a general affine map rather than just a rotation + shift. In all cases, the transformation from input to output coordinates is of the form [out] = [R] [in] + [V] where [R] is a 3x3 matrix and [V] is a 3-vector. By default, [R] is computed as a proper (det=1) rotation matrix (3 parameters). The '-affine' option says to fit [R] as a general matrix (9 parameters). N.B.: An affine transformation can rotate, rescale, and shear the volume. Be sure to look at the dataset before and after to make sure things are OK. -rotscl = Compute transformation as a rotation times an isotropic scaling; that is, [R] is an orthogonal matrix times a scalar. N.B.: '-affine' and '-rotscl' do unweighted least squares. -prefix pp = Use 'pp' as the prefix for the output dataset. [default = 'tagalign'] -verb = Print progress reports -dummy = Don't actually rotate the dataset, just compute the transformation matrix and vector. If '-matvec' is used, the mfile will be written. -linear } -cubic } = Chooses spatial interpolation method. -NN } = [default = cubic] -quintic } Nota Bene: * The transformation is carried out using the same methods as program 3dWarp. Author: RWCox - 16 Jul 2000, etc. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTcat
Concatenate sub-bricks from input datasets into one big 3D+time dataset. Usage: 3dTcat options where the options are: -prefix pname = Use 'pname' for the output dataset prefix name. OR -output pname [default='tcat'] -session dir = Use 'dir' for the output dataset session directory. [default='./'=current working directory] -glueto fname = Append bricks to the end of the 'fname' dataset. This command is an alternative to the -prefix and -session commands. -dry = Execute a 'dry run'; that is, only print out what would be done. This is useful when combining sub-bricks from multiple inputs. -verb = Print out some verbose output as the program proceeds (-dry implies -verb). Using -verb twice results in quite lengthy output. -rlt = Remove linear trends in each voxel time series loaded from each input dataset, SEPARATELY. That is, the data from each dataset is detrended separately. At least 3 sub-bricks from a dataset must be input for this option to apply. Notes: (1) -rlt removes the least squares fit of 'a+b*t' to each voxel time series; this means that the mean is removed as well as the trend. This effect makes it impractical to compute the % Change using AFNI's internal FIM. (2) To have the mean of each dataset time series added back in, use this option in the form '-rlt+'. In this case, only the slope 'b*t' is removed. (3) To have the overall mean of all dataset time series added back in, use this option in the form '-rlt++'. In this case, 'a+b*t' is removed from each input dataset separately, and the mean of all input datasets is added back in at the end. (This option will work properly only if all input datasets use at least 3 sub-bricks!) (4) -rlt can be used on datasets that contain shorts or floats, but not on complex- or byte-valued datasets. -relabel = Replace any sub-brick labels in an input dataset with the input dataset name -- this might help identify the sub-bricks in the output dataset. -tpattern PATTERN = Specify the timing pattern for the output dataset, using patterns described in the 'to3d -help' output (alt+z, seq, alt-z2, etc). -tr TR = Specify the TR (in seconds) for the output dataset. -DAFNI_GLOB_SELECTORS=YES Setting the environment variable AFNI_GLOB_SELECTORS to YES (as done temporarily with this option) means that sub-brick selectors '[..]' will not be used as wildcards. For example: 3dTcat -DAFNI_GLOB_SELECTORS=YES -relabel -prefix EPIzero 'rest_*+tlrc.HEAD[0]' will work to make a dataset with the #0 sub-brick from each of a number of 3D+time datasets. ** Note that the entire dataset specification is in quotes to prevent the shell from doing the '*' wildcard expansion -- it will be done inside the program itself, after the sub-brick selector is temporarily detached from the string -- and then a copy of the selector is re-attached to each expanded filename. ** Very few other AFNI '3d' programs do internal wildcard expansion -- most of them rely on the shell. Command line arguments after the above are taken as input datasets. A dataset is specified using one of these forms: prefix+view prefix+view.HEAD prefix+view.BRIK prefix.nii prefix.nii.gz SUB-BRICK SELECTION: -------------------- You can also add a sub-brick selection list after the end of the dataset name. This allows only a subset of the sub-bricks to be included into the output (by default, all of the input dataset is copied into the output). A sub-brick selection list looks like one of the following forms: fred+orig[5] ==> use only sub-brick #5 fred+orig[5,9,17] ==> use #5, #9, and #17 fred+orig[5..8] or [5-8] ==> use #5, #6, #7, and #8 fred+orig[5..13(2)] or [5-13(2)] ==> use #5, #7, #9, #11, and #13 Sub-brick indexes start at 0. You can use the character '$' to indicate the last sub-brick in a dataset; for example, you can select every third sub-brick by using the selection list fred+orig[0..$(3)] You can reverse the order of sub-bricks with a list like fred+origh[$..0(-1)] (Exactly WHY you might want to time-reverse a dataset is a mystery.) You can also use a syntax based on the usage of the program count. This would be most useful when randomizing (shuffling) the order of the sub-bricks. Example: fred+orig[count -seed 2 5 11 s] is equivalent to something like: fred+orig[ 6, 5, 11, 10, 9, 8, 7] You could also do: fred+orig[`count_afni -seed 2 -digits 1 -suffix ',' 5 11 s`] but if you have lots of numbers, the command line would get too long for the shell to process it properly. Omit the seed option if you want the code to generate a seed automatically. You cannot mix and match count syntax with other selection gimmicks. If you have a lot of bricks to select in a particular order, you will also run into name length problems. One solution is to put the indices in a .1D file then use the following syntax. For example, say you have the selection in file reorder.1D. You can extract the sub-bricks with: fred+orig'[1dcat reorder.1D]' As with count, you cannot mix and match 1dcat syntax with other selection gimmicks. NOTES: ------ You can also add a sub-brick selection list after the end of the * The TR and other time-axis properties are taken from the first input dataset that is itself 3D+time. If no input datasets contain such information, then TR is set to 1.0. This can be altered later using the 3drefit program. * The sub-bricks are output in the order specified, which may not be the order in the original datasets. For example, using fred+orig[0..$(2),1..$(2)] will cause the sub-bricks in fred+orig to be output into the new dataset in an interleaved fashion. Using fred+orig[$..0] will reverse the order of the sub-bricks in the output. If the -rlt option is used, the sub-bricks selected from each input dataset will be re-ordered into the output dataset, and then this sequence will be detrended. * You can use the '3dinfo' program to see how many sub-bricks a 3D+time or a bucket dataset contains. * The '$', '(', ')', '[', and ']' characters are special to the shell, so you will have to escape them. This is most easily done by putting the entire dataset plus selection list inside single quotes, as in 'fred+orig[5..7,9]'. * You may wish/need to use the 3drefit program on the output dataset to modify some of the .HEAD file parameters. * The program does internal wildcard expansion on the filenames provided to define the datasets. The software first strips the sub-brick selector string '[...]' off the end of each filename BEFORE wildcard expansion, then re-appends it to the results AFTER the expansion; for example, '*+orig.HEAD[4..7]' might expand to 'fred+orig.HEAD[4..7]' and 'wilma+orig.HEAD[4..7]'. ++ However, the '[...]' construct is also a shell wildcard, It is not practicable to use this feature for filename selection with 3dTcat if you are also using sub-brick selectors. ++ Since wildcard expansion looks for whole filenames, you must use wildcard expansion in the form (e.g.) of '*+orig.HEAD', NOT '*+orig' -- since the latter form doesn't match filenames. ++ Don't use '*+orig.*' since that will match both the .BRIK and .HEAD files, and each dataset will end up being read in twice! ++ If you want to see the filename expansion results, run 3dTcat with the option '-DAFNI_GLOB_DEBUG=YES' ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTcorr1D
Usage: 3dTcorr1D [options] xset y1D ~1~ Computes the correlation coefficient between each voxel time series in the input 3D+time dataset 'xset' and each column in the 1D time series file 'y1D', and stores the output values in a new dataset. -------- OPTIONS: ~1~ -------- -pearson = Correlation is the normal Pearson (product moment) correlation coefficient [this is the default method]. -spearman = Correlation is the Spearman (rank) correlation coefficient. -quadrant = Correlation is the quadrant correlation coefficient. -ktaub = Correlation is Kendall's tau_b coefficient. ++ For 'continuous' or finely-discretized data, tau_b and rank correlation are nearly equivalent (but not equal). -dot = Doesn't actually compute a correlation coefficient; just calculates the dot product between the y1D vector(s) and the dataset time series. -Fisher = Apply the 'Fisher' (inverse hyperbolic tangent = arctanh) transformation to the results. ++ It does NOT make sense to use this with '-ktaub', but if you want to do it, the program will not stop you. ++ Cannot be used with '-dot'! -prefix p = Save output into dataset with prefix 'p' [default prefix is 'Tcorr1D']. -mask mmm = Only process voxels from 'xset' that are nonzero in the 3D mask dataset 'mmm'. ++ Other voxels in the output will be set to zero. -float = Save results in float format [the default format]. -short = Save results in scaled short format [to save disk space]. ++ Cannot be used with '-dot'! ------ NOTES: ~1~ ------ * The output dataset is functional bucket type, with one sub-brick per column of the input y1D file. * No detrending, blurring, or other pre-processing options are available; if you want these things, see 3dDetrend or 3dTproject or 3dcalc. [In other words, this program presumes you know what you are doing!] * Also see 3dTcorrelate to do voxel-by-voxel correlation of TWO 3D+time datasets' time series, with similar options. * You can extract the time series from a single voxel with given spatial indexes using 3dmaskave, and then run it with 3dTcorr1D: 3dmaskave -quiet -ibox 40 30 20 epi_r1+orig > r1_40_30_20.1D 3dTcorr1D -pearson -Fisher -prefix c_40_30_20 epi_r1+orig r1_40_30_20.1D * http://en.wikipedia.org/wiki/Correlation * http://en.wikipedia.org/wiki/Pearson_product-moment_correlation_coefficient * http://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient * http://en.wikipedia.org/wiki/Kendall_tau_rank_correlation_coefficient -- RWCox - Apr 2010 - Jun 2010: Multiple y1D columns; OpenMP; -short; -mask. ========================================================================= * This binary version of 3dTcorr1D is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTcorrelate
++ 3dTcorrelate: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] Usage: 3dTcorrelate [options] xset yset ~1~ Computes the correlation coefficient between corresponding voxel time series in two input 3D+time datasets 'xset' and 'yset', and stores the output in a new 1 sub-brick dataset. -------- Options: ~1~ -------- -pearson = Correlation is the normal Pearson (product moment) correlation coefficient [this is the default method]. -spearman = Correlation is the Spearman (rank) correlation coefficient. -quadrant = Correlation is the quadrant correlation coefficient. -ktaub = Correlation is Kendall's tau_b coefficient. ++ For 'continuous' or finely-discretized data, tau_b and rank correlation are nearly equivalent. -covariance = Covariance instead of correlation. That would be the Pearson correlation without scaling by the product of the standard deviations. -partial z = Partial Pearson's Correlation of X & Y, adjusting for Z Supply dataset z to be taken into account after '-partial'. ** EXPERIMENTAL ** -ycoef = Least squares coefficient that best fits y(t) to x(t), after detrending. That is, if yd(t) is the detrended y(t) and xd(t) is the detrended x(t), then the ycoef value is from the OLSQ fit to xd(t) = ycoef * y(t) + error. -Fisher = Apply the 'Fisher' (inverse hyperbolic tangent = arctanh) transformation to (correlation) results. ++ It does NOT make sense to use this with '-ktaub', but if you want to do it, the program will not stop you. ++ This option does not apply to '-covariance' or '-ycoef'. -polort m = Remove polynomial trend of order 'm', for m=-1..9. [default is m=1; removal is by least squares]. Using m=-1 means no detrending; this is only useful for data/information that has been pre-processed. -ort r.1D = Also detrend using the columns of the 1D file 'r.1D'. Only one -ort option can be given. If you want to use more than one, create a temporary file using 1dcat. -autoclip = Clip off low-intensity regions in the two datasets, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The intensity level is determined the same way that 3dClipLevel works. ** At present, this program does not have a '-mask' option. Maybe someday? -zcensor = Omit (censor out) any time points where the xset volume is all zero OR where the yset volume is all zero (in mask). Please note that using -zcensor with any detrending is unlikely to be useful. ** That is, you should use '-polort -1' with this option, and NOT use '-ort'. * In fact, using '-zcensor' will set polort = -1, and if you insist on using detrending, you will have to put the '-polort' option AFTER '-zcensor. ** Since correlation is calculated from the sum of the point-by-point products xset(t)*yset(t), why censor out points where xset or yset is 0? Because the denominator of correlation is from the sum of xset(t)*xset(t) and yset(t)*yset(t) and unless the t-points where the datasets are censored are BOTH zero at the same time, the denominator will be incorrect. ** [RWCox - Dec 2019, day of Our Lady of Guadalupe] [for P Molfese and E Finn] -prefix p = Save output into dataset with prefix 'p' [default prefix is 'Tcorr']. ------ Notes: ~1~ ------ * The output dataset is functional bucket type, with just one sub-brick, stored in floating point format. * Because both time series are detrended prior to correlation, the results will not be identical to using FIM or FIM+ to calculate correlations (whose ideal vector is not detrended). * Also see 3dTcorr1D if you want to correlate each voxel time series in a dataset xset with a single 1D time series file, instead of separately with time series from another 3D+time dataset. * https://en.wikipedia.org/wiki/Correlation * https://en.wikipedia.org/wiki/Pearson_product-moment_correlation_coefficient * https://en.wikipedia.org/wiki/Spearman%27s_rank_correlation_coefficient * https://en.wikipedia.org/wiki/Kendall_tau_rank_correlation_coefficient * https://en.wikipedia.org/wiki/Partial_correlation -- RWCox - Aug 2001++ ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTcorrMap
Usage: 3dTcorrMap [options] 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. Supposed to give a measure of how 'connected' each voxel is to the rest of the brain. [[As if life were that simple.]] --------- WARNINGS: --------- ** This program takes a LONG time to run. ** This program will use a LOT of memory. ** Don't say I didn't warn you about these facts, and don't whine. -------------- Input Options: -------------- -input dd = Read 3D+time dataset 'dd' (a mandatory option). This provides the time series to be correlated en masse. ** This is a non-optional 'option': you MUST supply and input dataset! -seed bb = Read 3D+time dataset 'bb'. ** If you use this option, for each voxel in the -seed dataset, its time series is correlated with every voxel in the -input dataset, and then that collection of correlations is processed to produce the output for that voxel. ** If you don't use -seed, then the -input dataset is the -seed dataset [i.e., the normal usage]. ** The -seed and -input datasets must have the same number of time points and the same number of voxels! ** Unlike the -input dataset, the -seed dataset is not preprocessed (i.e., no detrending/bandpass or blur). (The main purpose of this -seed option is to) (allow you to preprocess the seed voxel time) (series in some personalized and unique way.) -mask mmm = Read dataset 'mmm' as a voxel mask. -automask = Create a mask from the input dataset. ** -mask and -automask are mutually exclusive! ** If you don't use one of these masking options, then all voxels will be processed, and the program will probably run for a VERY long time. ** Voxels with constant time series will be automatically excluded. ---------------------------------- Time Series Preprocessing Options: (applied only to -input, not to -seed) [[[[ In general, it would be better to pre-process with afni_proc.py ]]]] ---------------------------------- TEMPORAL FILTERING: ------------------- -polort m = Remove polynomial trend of order 'm', for m=-1..19. [default is m=1; removal is by least squares]. ** Using m=-1 means no detrending; this is only useful for data/information that has been pre-processed (e.g., using the 3dBandpass program). -bpass L H = Bandpass the data between frequencies L and H (in Hz). ** If the input dataset does not have a time step defined, then TR = 1 s will be assumed for this purpose. **** -bpass and -polort are mutually exclusive! -ort ref = 1D file with other time series to be removed from -input (via least squares regression) before correlation. ** Each column in 'ref' will be regressed out of each -input voxel time series. ** -ort can be used with -polort and/or -bandpass. ** You can use programs like 3dmaskave and 3dmaskSVD to create reference files from regions of the input dataset (e.g., white matter, CSF). SPATIAL FILTERING: (only for volumetric input datasets) ----------------- -Gblur ff = Gaussian blur the -input dataset (inside the mask) using a kernel width of 'ff' mm. ** Uses the same approach as program 3dBlurInMask. -Mseed rr = When extracting the seed voxel time series from the (preprocessed) -input dataset, average it over a radius of 'rr' mm prior to doing the correlations with all the voxel time series from the -input dataset. ** This extra smoothing is said by some mystics to improve and enhance the results. YMMV. ** Only voxels inside the mask will be used. ** A negative value for 'rr' means to treat the voxel dimensions as all equal to 1.0 mm; thus, '-Mseed -1.0' means to average a voxel with its 6 nearest neighbors in the -input dataset 3D grid. ** -Mseed and -seed are mutually exclusive! (It makes NO sense to use both options.) --------------- Output Options: (at least one of these must be given!) --------------- -Mean pp = Save average correlations into dataset prefix 'pp' ** As pointed out to me by CC, '-Mean' is the same as computing the correlation map with the 1D file that is the mean of all the normalized time series in the mask -- that is, a form of the global signal. Such a calculation could be done much faster with program 3dTcorr1D. ** Nonlinear combinations of the correlations, as done by the options below, can't be done in such a simple way. -Zmean pp = Save tanh of mean arctanh(correlation) into 'pp' -Qmean pp = Save RMS(correlation) into 'pp' -Pmean pp = Save average of squared positive correlations into 'pp' (negative correlations don't count in this calculation) -Thresh tt pp = Save the COUNT of how many voxels survived thresholding at level abs(correlation) >= tt (for some tt > 0). -VarThresh t0 t1 dt pp = Save the COUNT of how many voxels survive thresholding at several levels abs(correlation) >= tt, for tt = t0, t0+dt, ..., t1. This option produces a multi-volume dataset, with prefix 'pp'. -VarThreshN t0 t1 dt pp = Like '-VarThresh', but the output counts are 'Normalized' (divided) by the expected number of such supra-threshold voxels that would occur from white noise timeseries. ** N.B.: You can't use '-VarThresh' and '-VarThreshN' in the same run of the program! -CorrMap pp Output at each voxel the entire correlation map, into a dataset with prefix 'pp'. ** Essentially this does what 3dAutoTcorrelate would, with some of the additional options offered here. ** N.B.: Output dataset will be HUGE and BIG in most cases. -CorrMask By default, -CorrMap outputs a sub-brick for EACH input dataset voxel, even those that are NOT in the mask (such sub-bricks will be all zero). If you want to eliminate these sub-bricks, use this option. ** N.B.: The label for the sub-brick that was seeded from voxel (i,j,k) will be of the form v032.021.003 (when i=32, j=21, k=3). --** The following 3 options let you create a customized **-- --** method of combining the correlations, if the above **-- --** techniques do not meet your needs. (Of course, you **-- --** could also use '-CorrMap' and then process the big **-- --** output dataset yourself later, in some clever way.) **-- -Aexpr expr ppp = For each correlation 'r', compute the calc-style expression 'expr', and average these values to get the output that goes into dataset 'ppp'. -Cexpr expr ppp = As in '-Aexpr', but only average together nonzero values computed by 'expr'. Example: -Cexpr 'step(r-0.3)*r' TCa03 would compute (for each voxel) the average of all correlation coefficients larger than 0.3. -Sexpr expr ppp = As above, but the sum of the expressions is computed rather than the average. Example: -Sexpr 'step(r-0.3)' TCn03 would compute the number of voxels with correlation coefficients larger than 0.3. ** N.B.: At most one '-?expr' option can be used in the same run of the program! ** N.B.: Only the symbols 'r' and 'z' [=atanh(r)] have any meaning in the expression; all other symbols will be treated as zeroes. -Hist N ppp = For each voxel, save a histogram of the correlation coefficients into dataset ppp. ** N values will be saved per voxel, with the i'th sub-brick containing the count for the range -1+i*D <= r < -1+(i+1)*D with D=2/N and i=0..N-1 ** N must be at least 20, and at most 1000. * N=200 is good; then D=0.01, yielding a decent resolution. ** The output dataset is short format; thus, the maximum count in any bin will be 32767. ** The output from this option will probably require further processing before it can be useful -- but it is fun to surf through these histograms in AFNI's graph viewer. ---------------- Random Thoughts: ---------------- -- In all output calculations, the correlation of a voxel with itself is ignored. If you don't understand why, step away from the keyboard. -- This purely experimental program is somewhat time consuming. (Of course, it's doing a LOT of calculations.) -- For Kyle, AKA the new Pat (assuming such a thing were possible). -- For Steve, AKA the new Kyle (which makes him the newest Pat). -- RWCox - August 2008 et cetera. ========================================================================= * This binary version of 3dTcorrMap is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTfilter
3dTfilter takes as input a dataset, filters the time series in each voxel as ordered by the user, and outputs a new dataset. The data in each voxel is processed separately. The user (you?) specifies the filter functions to apply. They are applied in the order given on the command line: -filter rank -filter adaptive:7 means to do the following operations (1) turn the data into ranks (2) apply the adaptive mean filter to the ranks Notes: ------ ** This program is a work in progress, and more capabilities will be added as time allows, as the need arises, and as the author's whims bubble to the surface of his febrile brain. ** This program is for people who have Sisu. Options: -------- -input inputdataset -prefix outputdataset -filter FunctionName At least one '-filter' option is required! The FunctionName values that you can give are: rank = smallest value is replaced by 0, next smallest value by 1, and so forth. ** This filter is pretty useless. adaptive:H = adaptive mean filter with half-width of 'H' time points (H > 0). ** At most one 'adaptive' filter can be used! ** The filter 'footprint' is 2*H+1 points. ** This filter does local smoothing over the 'footprint', with values far away from the local median being weighted less. adetrend:H = apply adaptive mean filter with half-width of 'H' time points to get a local baseline, then subtract this baseline from the actual data, to provide an adaptive detrending. ** At most one 'adaptive' OR 'adetrend' filter can be used. despike = apply the 'NEW25' despiking algorithm, as in program 3dDespike. despike:H = apply the despiking algorithm over a window of half-with 'H' time points (667 > H > 3). ** H=12 is the same as 'despike'. ** At most one 'despike' filter can be used. detrend:P = (least squares) detrend with polynomials of up order 'P' for P=0, 1, 2, .... ** At most one 'detrend' filter can be used! ** You can use both '-adetrend' and '-detrend', but I don't know why you would try this. Example: -------- 3dTfilter -input fred.nii -prefix fred.af.nii -filter adaptive:7 ------- Author: The Programmer with No Name -------

AFNI program: 3dTfitter
Usage: 3dTfitter [options] * At each voxel, assembles and solves a set of linear equations. ++ The matrix at each voxel may be the same or may be different. ++ This flexibility (for voxel-wise regressors) is one feature that makes 3dTfitter different from 3dDeconvolve. ++ Another distinguishing feature is that 3dTfitter allows for L2, L1, and L2+L1 (LASSO) regression solvers, and allows you to impose sign constraints on the solution parameters. * Output is a bucket dataset with the beta parameters at each voxel. * You can also get output of fitted time series at each voxel, and the error sum of squares (e.g., for generating statistics). * You can also deconvolve with a known kernel function (e.g., an HRF model in FMRI, or an arterial input function in DSC-MRI, et cetera), in which case the output dataset is a new time series dataset, containing the estimate of the source function that, when convolved with your input kernel function, fits the data (in each voxel). * The basic idea is to compute the beta_i so that the following is approximately true: RHS(t) = sum { beta_i * LHS_i(t) } i>=1 With the '-FALTUNG' (deconvolution) option, the model expands to be RHS(t) = sum { K(j)*S(t-j) } + sum { beta_i * LHS_i(t) } j>=0 i>=1 where K() is the user-supplied causal kernel function, and S() is the source time series to be estimated along with the betas (which can be thought of as the 'baseline' fit). * The model basis functions LHS_i(t) and the kernel function K(t) can be .1D files (fixed for all voxels) and/or 3D+time datasets (different for each voxel). * The fitting approximation can be done in 4 different ways, minimizing the errors (differences between RHS(t) and the fitted equation) in the following ways: ++ L2 [-l2fit option] = least sum of squares of errors ++ L1 [-l1fit option] = least sum of absolute values of errors ++ L2 LASSO = least sum of squares of errors, with an added [-l2lasso option] L1 penalty on the size of the solution parameters ++ L2 Square Root LASSO = least square root of the sum of squared errors [-l2sqrtlasso option] with an added L1 penalty on the solution parameters ***** Which fitting method is better? The answer to that question depends strongly on what you are going to use the results for! And on the quality of the data. ************************************************* ***** 3dTfitter is not for the casual user! ***** ***** It has a lot of options which let you ***** ***** control the complex solution process. ***** ************************************************* ---------------------------------- SPECIFYING THE EQUATIONS AND DATA: ---------------------------------- -RHS rset = Specifies the right-hand-side 3D+time dataset. ('rset' can also be a 1D file with 1 column) * Exactly one '-RHS' option must be given to 3dTfitter. -LHS lset = Specifies a column (or columns) of the left-hand-side matrix. * More than one 'lset' can follow the '-LHS' option, but each input filename must NOT start with the '-' character! * Or you can use multiple '-LHS' options, if you prefer. * Each 'lset' can be a 3D+time dataset, or a 1D file with 1 or more columns. * A 3D+time dataset defines one column in the LHS matrix. ++ If 'rset' is a 1D file, then you cannot input a 3D+time dataset with '-LHS'. ++ If 'rset' is a 3D+time dataset, then the 3D+time dataset(s) input with '-LHS' must have the same voxel grid as 'rset'. * A 1D file defines as many columns in the LHS matrix as are in the file. ++ For example, you could input the LHS matrix from the .xmat.1D matrix file output by 3dDeconvolve, if you wanted to repeat the same linear regression using 3dTfitter, for some bizarre unfathomable twisted psychotic reason. (See https://shorturl.at/boxU9 for more details.) ** If you have a problem where some LHS vectors might be tiny, causing stability problems, you can choose to omit them by using the '-vthr' option. By default, only all-zero vectors will be omitted from the regression. ** Note that if the scales of the LHS vectors are grossly different (e.g., 0 < vector#1 < 0.01 and 0 < vector#2 < 1000), then numerical errors in the calculations might cause the results to be unreliable. To avoid this problem, you can scale the vectors (before running 3dTfitter) so that they have similar magnitudes. ** Note that if you are fitting a time series dataset that has nonzero mean, then at least some of your basis vectors should have nonzero mean, or you won't be able to get a good fit. If necessary, use '-polort 0' to fit the mean value of the dataset, so that the zero-mean LHS vectors can do their work in fitting the fluctuations in the data! [This means you, HJJ!] *** Columns are assembled in the order given on the command line, which means that LHS parameters will be output in that order! *** If all LHS inputs are 1D vectors AND you are using least squares fitting without constraints, then 3dDeconvolve would be more efficient, since each voxel would have the same set of equations -- a fact that 3dDeconvolve exploits for speed. ++ But who cares about CPU time? Come on baby, light my fire! -polort p = Add 'p+1' Legendre polynomial columns to the LHS matrix. * These columns are added to the LHS matrix AFTER all other columns specified by the '-LHS' option, even if the '-polort' option appears before '-LHS' on the command line. ** By default, NO polynomial columns will be used. -vthr v = The value 'v' (between 0.0 and 0.09, inclusive) defines the threshold below which LHS vectors will be omitted from the regression analysis. Each vector's L1 norm (sum of absolute values) is computed. Any vector whose L1 norm is less than or equal to 'v' times the largest L1 norm will not be used in the analysis, and will get 0 weight in the output. The purpose of this option is to let you have tiny inputs and have them be ignored. * By default, 'v' is zero ==> only exactly zero LHS columns will be ignored in this case. ** Prior to 18 May 2010, the built-in (and fixed) value of 'v' was 0.000333. Thus, to get the old results, you should use option '-vthr 0.000333' -- this means YOU, Rasmus Birn! * Note that '-vthr' column censoring is done separately for each voxel's regression problem, so if '-LHS' had any dataset components (i.e., voxelwise regressors), a different set of omitted columns could be used betwixt different voxels. -------------- DECONVOLUTION: -------------- -FALTUNG fset fpre pen fac = Specifies a convolution (German: Faltung) model to be added to the LHS matrix. Four arguments follow the option: -->** 'fset' is a 3D+time dataset or a 1D file that specifies the known kernel of the convolution. * fset's time point [0] is the 0-lag point in the kernel, [1] is the 1-lag into the past point, etc. ++ Call the data Z(t), the unknown signal S(t), and the known kernel H(t). The equations being solved for the set of all S(t) values are of the form Z(t) = H(0)S(t) + H(1)S(t-1) + ... + H(L)S(t-L) + noise where L is the last index in the kernel function. ++++ N.B.: The TR of 'fset' (the source of H) and the TR of the RHS dataset (the source of Z) MUST be the same, or the deconvolution results will be revoltingly meaningless drivel (or worse)! -->** 'fpre' is the prefix for the output time series S(t) to be created -- it will have the same length as the input 'rset' time series. ++ If you don't want this time series (why?), set 'fpre' to be the string 'NULL'. ++ If you want to see the fit of the model to the data (a very good idea), use the '-fitts' option, which is described later. -->** 'pen' selects the type of penalty function to be applied to constrain the deconvolved time series: ++ The following penalty functions are available: P0[s] = f^q * sum{ |S(t)|^q } P1[s] = f^q * sum{ |S(t)-S(t-1)|^q } P2[s] = f^q * sum{ |2*S(t)-S(t-1)-S(t+1)|^q } P3[s] = f^q * sum{ |3*S(t)-3*S(t-1)-S(t+1)+S(t-2)|^q } where S(t) is the deconvolved time series; where q=1 for L1 fitting, q=2 for L2 fitting; where f is the value of 'fac' (defined below). P0 tries to keep S(t) itself small P1 tries to keep point-to-point fluctuations in S(t) small (1st derivative) P2 tries to keep 3 point fluctuations in S(t) small (2nd derivative) P3 tries to keep 4 point fluctuations in S(t) small (3nd derivative) ++ Higher digits try to make the result function S(t) smoother. If a smooth result makes sense, then use the string '012' or '0123' for 'pen'. ++ In L2 regression, these penalties are analogous to Wiener (frequency space) deconvolution, with noise spectra proportional to P0 ==> fac^2 * 1 (constant in frequency) P1 ==> fac^2 * freq^2 P2 ==> fac^2 * freq^4 P3 ==> fac^2 * freq^6 However, 3dTfitter does deconvolution in the time domain, not the frequency domain, and you can choose to use L2, L1, or LASSO (L2+L1) regression. ++ The value of 'pen' is a combination of the digits '0', '1', '2', and/or '3'; for example: 0 = use P0 only 1 = use P1 only 2 = use P2 only 3 = use P3 only 01 = use P0+P1 (the sum of these two functions) 02 = use P0+P2 12 = use P1+P2 012 = use P0+P1+P2 (sum of three penalty functions) 0123 = use P0+P1+P2+P3 (et cetera) If 'pen' does not contain any of the digits 0..3, then '01' will be used. -->** 'fac' is the positive weight 'f' for the penalty function: ++ if fac < 0, then the program chooses a penalty factor for each voxel separately and then scales that by -fac. ++ use fac = -1 to get this voxel-dependent factor unscaled. (this is a very reasonable place to start, by the way :-) ++ fac = 0 is a special case: the program chooses a range of penalty factors, does the deconvolution regression for each one, and then chooses the fit it likes best (as a tradeoff between fit error and solution size). ++ fac = 0 will be MUCH slower since it solves about 20 problems for each voxel and then chooses what it likes. setenv AFNI_TFITTER_VERBOSE YES to get some progress reports, if you want to see what it is doing. ++ Instead of using fac = 0, a useful alternative is to do some test runs with several negative values of fac, [e.g., -1, -2, and -3] and then look at the results to determine which one is most suitable for your purposes. ++ It is a good idea to experiment with different fac values, so you can see how the solution varies, and so you can get some idea of what penalty level to use for YOUR problems. ++ SOME penalty has to be applied, since otherwise the set of linear equations for S(t) is under-determined and/or ill-conditioned! ** If '-LHS' is used with '-FALTUNG', those basis vectors can be thought of as a baseline to be regressed out at the same time the convolution model is fitted. ++ When '-LHS' supplies a baseline, it is important that penalty type 'pen' include '0', so that the collinearity between convolution with a constant S(t) and a constant baseline can be resolved! ++ Instead of using a baseline here, you could project the baseline out of a dataset or 1D file using 3dDetrend, before using 3dTfitter. *** At most one '-FALTUNG' option can be used!!! *** Consider the time series model Z(t) = K(t)*S(t) + baseline + noise, where Z(t) = data time series (in each voxel) K(t) = kernel (e.g., hemodynamic response function) S(t) = stimulus time series baseline = constant, drift, etc. and * = convolution in time Then program 3dDeconvolve solves for K(t) given S(t), whereas 3dTfitter -FALTUNG solves for S(t) given K(t). The difference between the two cases is that K(t) is presumed to be causal and have limited support, while S(t) is a full-length time series. *** Presumably you know this already, but deconvolution in the Fourier domain -1 S(t) = F { F[Z] / F[K] } (where F[] is the Fourier transform) is a bad idea, since division by small values F[K] will grotesquely amplify the noise. 3dTfitter does NOT even try to do such a silly thing. ****** Deconvolution is a tricky business, so be careful out there! ++ e.g., Experiment with the different parameters to make sure the results in your type of problems make sense. -->>++ Look at the results and the fits with AFNI (or 1dplot)! Do not blindly assume that the results are accurate. ++ Also, do not blindly assume that a paper promoting a new deconvolution method that always works is actually a good thing! ++ There is no guarantee that the automatic selection of of the penalty factor herein will give usable results for your problem! ++ You should probably use a mask dataset with -FALTUNG, since deconvolution can often fail on pure noise time series. ++ Unconstrained (no '-cons' options) least squares ('-lsqfit') is normally the fastest solution method for deconvolution. This, however, may only matter if you have a very long input time series dataset (e.g., more than 1000 time points). ++ For unconstrained least squares deconvolution, a special sparse matrix algorithm is used for speed. If you wish to disable this for some reason, set environment variable AFNI_FITTER_RCMAT to NO before running the program. ++ Nevertheless, a FALTUNG problem with more than 1000 time points will probably take a LONG time to run, especially if 'fac' is chosen to be 0. ---------------- SOLUTION METHOD: ---------------- -lsqfit = Solve equations via least squares [the default method]. * This is sometimes called L2 regression by mathematicians. * '-l2fit' and '-L2' are synonyms for this option. -l1fit = Solve equations via least sum of absolute residuals. * This is sometimes called L1 regression by mathematicians. * '-L1' is a synonym for this option. * L1 fitting is usually slower than L2 fitting, but is perhaps less sensitive to outliers in the data. ++ L1 deconvolution might give nicer looking results when you expect the deconvolved signal S(t) to have large-ish sections where S(t) = 0. [The LASSO solution methods can also have this property.] * L2 fitting is statistically more efficient when the noise is KNOWN to be normally (Gaussian) distributed (and a bunch of other assumptions are also made). ++ Where such KNOWLEDGE comes from is an interesting question. -l2lasso lam [i j k ...] = Solve equations via least squares with a LASSO (L1) penalty on the coefficients. * The positive value 'lam' after the option name is the weight given to the penalty. ++ As a rule of thumb, you can try lam = 2 * sigma, where sigma = standard deviation of noise, but that requires you to have some idea what the noise level is. ++ If you enter 'lam' as a negative number, then the code will CRUDELY estimate sigma and then scale abs(lam) by that value -- in which case, you can try lam = -2 (or so) and see if that works well for you. ++ Or you can use the Square Root LASSO option (next), which (in theory) does not need to know sigma when setting lam. ++ If you do not provide lam, or give a value of 0, then a default value will be used. * Optionally, you can supply a list of parameter indexes (after 'lam') that should NOT be penalized in the the fitting process (e.g., traditionally, the mean value is not included in the L1 penalty.) Indexes start at 1, as in 'consign' (below). ++ If this un-penalized integer list has long stretches of contiguous entries, you can specify ranges of integers, as in '1:9' instead of '1 2 3 4 5 6 7 8 9'. **-->>++ If you want to supply the list of indexes that GET a L1 penalty, instead of the list that does NOT, you can put an 'X' character first, as in -LASSO 0 X 12:41 to indicate that variables 12..41 (inclusive) get the penalty applied, and the other variables do not. This inversion might be more useful to you in some cases. ++ If you also want the indexes to have 1 added to them and be inverted -- because they came from a 0-based program -- then use 'X1', as in '-LASSO 0 X1 12:41'. ++ If you want the indexes to have 1 added to them but NOT to be inverted, use 'Y1', as in '-LASSO 0 Y1 13:42'. ++ Note that if you supply an integer list, you MUST supply a value for lam first, even if that value is 0. ++ In deconvolution ('-FALTUNG'), all baseline parameters (from '-LHS' and/or '-polort') are automatically non-penalized, so there is usually no point to using this un-penalizing feature. ++ If you are NOT doing deconvolution, then you'll need this option to un-penalize any '-polort' parameters (if desired). ** LASSO-ing herein should be considered experimental, and its implementation is subject to change! You should definitely play with different 'lam' values to see how well they work for your particular types of problems. Algorithm is here: ++ TT Wu and K Lange. Coordinate descent algorithms for LASSO penalized regression. Annals of Applied Statistics, 2: 224-244 (2008). http://arxiv.org/abs/0803.3876 * '-LASSO' is a synonym for this option. -lasso_centro_block i j k ... = Defines a block of coefficients that will be penalized together with ABS( beta[i] - centromean( beta[i], beta[j] , ... ) ) where the centromean(a,b,...) is computed by sorting the arguments (a,b,...) and then averaging the central 50% values. * The goal is to use LASSO to shrink these coefficients towards a common value to suppress outliers, rather than the default LASSO method of shrinking coefficients towards 0, where the penalty on coefficient beta[i] is just ABS( beta[i] ). * For example: -lasso_centro_block 12:26 -lasso_centro_block 27:41 These options define two blocks of coefficients. -->>*** The intended application of this option is to regularize (reduce fluctuations) in the 'IM' regression method from 3dDeconvolve, where each task instance gets a separate beta fit parameter. *** That is, the idea is that you run 3dTfitter to get the 'IM' betas as an alternative to 3dDeconvolve or 3dREMLfit, since the centromean regularization will damp down wild fluctuations in the individual task betas. *** In this example, the two blocks of coefficients correspond to the beta values for each of two separate tasks. *** The input '-LHS' matrix is available from 3dDeconvolve's '-x1D' option. *** Further details on 'blocks' can be found in this Google Doc https://shorturl.at/boxU9 including shell commands on how to extract the block indexes from the header of the matrix file. *** A 'lam' value for the '-LASSO' option that makes sense is a value between -1 and -2, but as usual, you'll have to experiment with your particular data and application. * If you have more than one block, do NOT let them overlap, because the program doesn't check for this kind of stoopidity and then peculiar/bad things will probably happen! * A block defined here must have at least 5 entries. In practice, I would recommend at least 12 entries for a block, or the whole idea of 'shrinking to the centromean' is silly. * This option can be abbreviated as '-LCB', since typing '-lasso_centro_block' correctly is a nontrivial challenge :-) *** This option is NOT implemented for -l2sqrtlasso :-( * [New option - 10 Aug 2021 - RWCox] -l2sqrtlasso lam [i j k ...] = Similar to above option, but uses 'Square Root LASSO' instead: * Approximately speaking, LASSO minimizes E = Q2+lam*L1, where Q2=sum of squares of residuals and L1=sum of absolute values of all fit parameters, while Square Root LASSO minimizes sqrt(Q2)+lam*L1; the method and motivation is described here: ++ A Belloni, V Chernozhukov, and L Wang. Square-root LASSO: Pivotal recovery of sparse signals via conic programming (2010). http://arxiv.org/abs/1009.5689 ++ A coordinate descent algorithm is also used for this optimization (unlike in the paper above). ** A reasonable range of 'lam' to use is from 1 to 10 (or so); I suggest you start with 2 and see how well that works. ++ Unlike the pure LASSO option above, you do not need to give give a negative value for lam here -- there is no need for scaling by sigma -- or so they say. * The theoretical advantange of Square Root LASSO over standard LASSO is that a good choice of 'lam' does not depend on knowing the noise level in the data (that is what 'Pivotal' means in the paper's title). * '-SQRTLASSO' is a synonym for this option. --------->>**** GENERAL NOTES ABOUT LASSO and SQUARE ROOT LASSO ****<<-------- * LASSO methods are the only way to solve a under-determined system with 3dTfitter -- one with more vectors on the RHS than time points. However, a 'solution' to such a problem doesn't necessarily mean anything -- be careful out there! * LASSO methods will tend to push small coefficients down to zero. This feature can be useful when doing deconvolution, if you expect the result to be zero over large-ish intervals. ++ L1 regression ('-l1fit') has a similar property, of course. ++ This difficult-to-estimate bias in the LASSO-computed coefficients makes it nearly impossible to provide reliable estimates of statistical significance for the fit (e.g., R^2, F, ...). * The actual penalty factor lambda used for a given coefficient is lam scaled by the L2 norm of the corresponding regression column. The purpose of this is to keep the penalties scale-free: if a regression column were doubled, then the corresponding fit coefficient would be cut in half; thus, to keep the same penalty level, lambda should also be doubled. * For '-l2lasso', a negative lam additionally means to scale by the estimate of sigma, as described earlier. This feature does not apply to Square Root LASSO, however (if you give a negative lam to '-l2sqrtlasso', its absolute value is used). -->>** There is no 'best' value of lam; if you are lucky, there is is a range of lam values that give reasonable results. A good procedure to follow would be to use several different values of lam and see how the results vary; for example, the list lam = -1, -2, -4, -7, -10 might be a good starting point. * If you don't give ANY numeric value after the LASSO option (i.e., the next argument on the command line is another option), then the program will use '-3.1415926536' for the value of lam. * A tiny value of lam (say 0.01) should give almost the same results as pure L2 regression. * Data with a smaller signal-to-noise ratio will probably need larger values of lam -- you'll have to experiment. * The number of iterations used for the LASSO solution will be printed out for the first voxel solved, and for ever 10,000th one following -- this is mostly for my personal edification. -->>** Recall: "3dTfitter is not for the casual user!" This statement especially applies when using LASSO, which is a powerful tool -- and as such, can be dangerous if not used wisely. --------------------- SOLUTION CONSTRAINTS: --------------------- -consign = Follow this option with a list of LHS parameter indexes to indicate that the sign of some output LHS parameters should be constrained in the solution; for example: -consign +1 -3 which indicates that LHS parameter #1 (from the first -LHS) must be non-negative, and that parameter #3 must be non-positive. Parameter #2 is unconstrained (e.g., the output can be positive or negative). * Parameter counting starts with 1, and corresponds to the order in which the LHS columns are specified. * Unlike '-LHS or '-label', only one '-consign' option can be used. * Do NOT give the same index more than once after '-consign' -- you can't specify that an coefficient is both non-negative and non-positive, for example! *** Constraints can be used with any of the 4 fitting methods. *** '-consign' constraints only apply to the '-LHS' fit parameters. To constrain the '-FALTUNG' output, use the option below. * If '-consign' is not used, the signs of the fitted LHS parameters are not constrained. -consFAL c= Constrain the deconvolution time series from '-FALTUNG' to be positive if 'c' is '+' or to be negative if 'c' is '-'. * There is no way at present to constrain the deconvolved time series S(t) to be positive in some regions and negative in others. * If '-consFAL' is not used, the sign of the deconvolved time series is not constrained. --------------- OUTPUT OPTIONS: --------------- -prefix p = Prefix for the output dataset (LHS parameters) filename. * Output datasets from 3dTfitter are always in float format. * If you don't give this option, 'Tfitter' is the prefix. * If you don't want this dataset, use 'NULL' as the prefix. * If you are doing deconvolution and do not also give any '-LHS' options, then this file will not be output, since it comprises the fit parameters for the '-LHS' vectors. -->>** If the input '-RHS' file is a .1D file, normally the output files are written in the AFNI .3D ASCII format, where each row contains the time series data for one voxel. If you want to have these files written in the .1D format, with time represented down the column direction, be sure to put '.1D' on the end of the prefix, as in '-prefix Elvis.1D'. If you use '-' or 'stdout' as the prefix, the resulting 1D file will be written to the terminal. (See the fun fun fun examples, below.) -label lb = Specifies sub-brick labels in the output LHS parameter dataset. * More than one 'lb' can follow the '-label' option; however, each label must NOT start with the '-' character! * Labels are applied in the order given. * Normally, you would provide exactly as many labels as LHS columns. If not, the program invents some labels. -fitts ff = Prefix filename for the output fitted time series dataset. * Which is always in float format. * Which will not be written if this option isn't given! *** If you want the residuals, subtract this time series from the '-RHS' input using 3dcalc (or 1deval). -errsum e = Prefix filename for the error sums dataset, which is calculated from the difference between the input time series and the fitted time series (in each voxel): * Sub-brick #0 is the sum of squares of differences (L2 sum) * Sub-brick #1 is the sum of absolute differences (L1 sum) * The L2 sum value, in particular, can be used to produce a statistic to measure the significance of a fit model; cf. the 'Correlation Coefficient Example' far below. -------------- OTHER OPTIONS: -------------- -mask ms = Read in dataset 'ms' as a mask; only voxels with nonzero values in the mask will be processed. Voxels falling outside the mask will be set to all zeros in the output. * Voxels whose time series are all zeros will not be processed, even if they are inside the mask! -quiet = Don't print the fun fun fun progress report messages. * Why would you want to hide these delightful missives? ---------------------- ENVIRONMENT VARIABLES: ---------------------- AFNI_TFITTER_VERBOSE = YES means to print out information during the fitting calculations. ++ Automatically turned on for 1 voxel -RHS inputs. AFNI_TFITTER_P1SCALE = number > 0 will scale the P1 penalty by this value (e.g., to count it more) AFNI_TFITTER_P2SCALE = number > 0 will scale the P2 penalty by this value AFNI_TFITTER_P3SCALE = number > 0 will scale the P3 penalty by this value You could set these values on the command line using the AFNI standard '-Dvariablename=value' command line option. ------------ NON-Options: ------------ * There is no option to produce statistical estimates of the significance of the parameter estimates. ++ 3dTcorrelate might be useful, to compute the correlation between the '-fitts' time series and the '-RHS' input data. ++ You can use the '-errsum' option to get around this limitation, with enough cleverness. * There are no options for censoring or baseline generation (except '-polort'). ++ You could generate some baseline 1D files using 1deval, perhaps. * There is no option to constrain the range of the output parameters, except the semi-infinite ranges provided by '-consign' and/or '-consFAL'. * This program is NOW parallelized via OpenMP :-) [17 Aug 2021 - RWCox] ------------------ Contrived Example: ------------------ The datasets 'atm' and 'btm' are assumed to have 99 time points each. We use 3dcalc to create a synthetic combination of these plus a constant plus Gaussian noise, then use 3dTfitter to fit the weights of these 3 functions to each voxel, using 4 different methods. Note the use of the input 1D time series '1D: 99@1' to provide the constant term. 3dcalc -a atm+orig -b btm+orig -expr '-2*a+b+gran(100,20)' -prefix 21 -float 3dTfitter -RHS 21+orig -LHS atm+orig btm+orig '1D: 99@1' -prefix F2u -l2fit 3dTfitter -RHS 21+orig -LHS atm+orig btm+orig '1D: 99@1' -prefix F1u -l1fit 3dTfitter -RHS 21+orig -LHS atm+orig btm+orig '1D: 99@1' -prefix F1c -l1fit \ -consign -1 +3 3dTfitter -RHS 21+orig -LHS atm+orig btm+orig '1D: 99@1' -prefix F2c -l2fit \ -consign -1 +3 In the absence of noise and error, the output datasets should be #0 sub-brick = -2.0 in all voxels #1 sub-brick = +1.0 in all voxels #2 sub-brick = +100.0 in all voxels ---------------------- Yet More Contrivances: ---------------------- You can input a 1D file for the RHS dataset, as in the example below, to fit a single time series to a weighted sum of other time series: 1deval -num 30 -expr 'cos(t)' > Fcos.1D 1deval -num 30 -expr 'sin(t)' > Fsin.1D 1deval -num 30 -expr 'cos(t)*exp(-t/20)' > Fexp.1D 3dTfitter -quiet -RHS Fexp.1D -LHS Fcos.1D Fsin.1D -prefix - * Note the use of the '-' as a prefix to write the results (just 2 numbers) to stdout, and the use of '-quiet' to hide the divertingly funny and informative progress messages. * For the Jedi AFNI Masters out there, the above example can be carried out on using single complicated command line: 3dTfitter -quiet -RHS `1deval -1D: -num 30 -expr 'cos(t)*exp(-t/20)'` \ -LHS `1deval -1D: -num 30 -expr 'cos(t)'` \ `1deval -1D: -num 30 -expr 'sin(t)'` \ -prefix - resulting in the single output line below: 0.535479 0.000236338 which are respectively the fit coefficients of 'cos(t)' and 'sin(t)'. -------------------------------- Contrived Deconvolution Example: -------------------------------- (1) Create a 101 point 1D file that is a block of 'activation' between points 40..50, convolved with a triangle wave kernel (the '-iresp' input below): 3dConvolve -input1D -polort -1 -num_stimts 1 \ -stim_file 1 '1D: 40@0 10@1 950@0' \ -stim_minlag 1 0 -stim_maxlag 1 5 \ -iresp 1 '1D: 0 1 2 3 2 1' -nlast 100 \ | grep -v Result | grep -v '^$' > F101.1D (2) Create a 3D+time dataset with this time series in each voxel, plus noise that increases with voxel 'i' index: 3dUndump -prefix Fjunk -dimen 100 100 1 3dcalc -a Fjunk+orig -b F101.1D \ -expr 'b+gran(0,0.04*(i+1))' \ -float -prefix F101d /bin/rm -f Fjunk+orig.* (3) Deconvolve, then look what you get by running AFNI: 3dTfitter -RHS F101d+orig -l1fit \ -FALTUNG '1D: 0 1 2 3 2 1' F101d_fal1 012 0.0 3dTfitter -RHS F101d+orig -l2fit \ -FALTUNG '1D: 0 1 2 3 2 1' F101d_fal2 012 0.0 (4) View F101d_fal1+orig, F101d_fal2+orig, and F101d+orig in AFNI, (in Axial image and graph viewers) and see how the fit quality varies with the noise level and the regression type -- L1 or L2 regression. Note that the default 'fac' level of 0.0 was selected in the commands above, which means the program selects the penalty factor for each voxel, based on the size of the data time series fluctuations and the quality of the fit. (5) Add logistic noise (long tails) to the noise-free 1D time series, then deconvolve and plot the results directly to the screen, using L1 and L2 and the two LASSO fitting methods: 1deval -a F101.1D -expr 'a+lran(.5)' > F101n.1D 3dTfitter -RHS F101n.1D -l1fit \ -FALTUNG '1D: 0 1 2 3 2 1' stdout 01 -2 | 1dplot -stdin -THICK & 3dTfitter -RHS F101n.1D -l2fit \ -FALTUNG '1D: 0 1 2 3 2 1' stdout 01 -2 | 1dplot -stdin -THICK & 3dTfitter -RHS F101n.1D -l2sqrtlasso 2 \ -FALTUNG '1D: 0 1 2 3 2 1' stdout 01 -2 | 1dplot -stdin -THICK & 3dTfitter -RHS F101n.1D -l2lasso -2 \ -FALTUNG '1D: 0 1 2 3 2 1' stdout 01 -2 | 1dplot -stdin -THICK & For even more fun, add the '-consfal +' option to the above commands, to force the deconvolution results to be positive. ***N.B.: You can only use 'stdout' as an output filename when the output will be written as a 1D file (as above)! -------------------------------- Correlation Coefficient Example: -------------------------------- Suppose your initials are HJJ and you want to compute the partial correlation coefficient of time series Seed.1D with every voxel in a dataset Rest+orig once a spatially dependent 'artifact' time series Art+orig has been projected out. You can do this with TWO 3dTfitter runs, plus 3dcalc: (1) Run 3dTfitter with ONLY the artifact time series and get the error sum dataset 3dTfitter -RHS Rest+orig -LHS Art+orig -polort 2 -errsum Ebase (2) Run 3dTfitter again with the artifact PLUS the seed time series and get the error sum dataset and also the beta coefficients 3dTfitter -RHS Rest+orig -LHS Seed.1D Art+orig -polort 2 \ -errsum Eseed -prefix Bseed (3) Compute the correlation coefficient from the amount of variance reduction between cases 1 and 2, times the sign of the beta 3dcalc -a Eseed+orig'[0]' -b Ebase+orig'[0]' -c Bseed+orig'[0]' \ -prefix CorrSeed -expr '(2*step(c)-1)*sqrt(1-a/b)' 3drefit -fbuc -sublabel 0 'SeedCorrelation' CorrSeed+orig More cleverness could be used to compute t- or F-statistics in a similar fashion, using the error sum of squares between 2 different fits. (Of course, these are assuming you use the default '-lsqfit' method.) -------------------------------- PPI (psycho-physiological interaction) Example: -------------------------------- Suppose you are running a PPI analysis and want to deconvolve a GAM signal from the seed time series, hoping (very optimistically) to convert from the BOLD time series (typical FMRI signal) to a neurological time series (an impulse signal, say). If the BOLD signal at the seed is seed_BOLD.1D and the GAM signal is GAM.1D, then consider this example for the deconvolution, in order to create the neuro signal, seed_neuro.1D: 3dTfitter -RHS seed_BOLD.1D \ -FALTUNG GAM.1D seed_neuro.1D 012 -2 \ -l2lasso -6 ************************************************************************* ** RWCox - Feb 2008, et seq. ** ** Created for the glorious purposes of John A Butman, MD, PhD, Poobah ** ** But might be useful for some other well-meaning souls out there ** ************************************************************************* ========================================================================= * This binary version of 3dTfitter is compiled using OpenMP, a semi- automatic parallelizer software toolkit, which splits the work across multiple CPUs/cores on the same shared memory computer. * OpenMP is NOT like MPI -- it does not work with CPUs connected only by a network (e.g., OpenMP doesn't work across cluster nodes). * For some implementation and compilation details, please see https://afni.nimh.nih.gov/pub/dist/doc/misc/OpenMP.html * The number of CPU threads used will default to the maximum number on your system. You can control this value by setting environment variable OMP_NUM_THREADS to some smaller value (including 1). * Un-setting OMP_NUM_THREADS resets OpenMP back to its default state of using all CPUs available. ++ However, on some systems, it seems to be necessary to set variable OMP_NUM_THREADS explicitly, or you only get one CPU. ++ On other systems with many CPUS, you probably want to limit the CPU count, since using more than (say) 16 threads is probably useless. * You must set OMP_NUM_THREADS in the shell BEFORE running the program, since OpenMP queries this variable BEFORE the program actually starts. ++ You can't usefully set this variable in your ~/.afnirc file or on the command line with the '-D' option. * How many threads are useful? That varies with the program, and how well it was coded. You'll have to experiment on your own systems! * The number of CPUs on this particular computer system is ...... 1. * The maximum number of CPUs that will be used is now set to .... 1. ========================================================================= ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dThreetoRGB
Usage #1: 3dThreetoRGB [options] dataset Usage #2: 3dThreetoRGB [options] dataset1 dataset2 dataset3 Converts 3 sub-bricks of input to an RGB-valued dataset. * If you have 1 input dataset, then sub-bricks [0..2] are used to form the RGB components of the output. * If you have 3 input datasets, then the [0] sub-brick of each is used to form the RGB components, respectively. * RGB datasets have 3 bytes per voxel, with values ranging from 0..255. Options: -prefix ppp = Write output into dataset with prefix 'ppp'. [default='rgb'] -scale fac = Multiply input values by 'fac' before using as RGB [default=1]. If you have floating point inputs in range 0..1, then using '-scale 255' would make a lot of sense. -mask mset = Only output nonzero values where the mask dataset 'mset' is nonzero. -fim = Write result as a 'fim' type dataset. [this is the default] -anat = Write result as a anatomical type dataset. Notes: * Input datasets must be byte-, short-, or float-valued. * You might calculate the component datasets using 3dcalc. * You can also create RGB-valued datasets in to3d, using 2D raw PPM image files as input, or the 3Dr: format. * RGB fim overlays are transparent in AFNI in voxels where all 3 bytes are zero - that is, it won't overlay solid black. * At present, there is limited support for RGB datasets. About the only thing you can do is display them in 2D slice windows in AFNI. -- RWCox - April 2002 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTnorm
Usage: 3dTnorm [options] dataset Takes each voxel time series and normalizes it (by multiplicative scaling) -- in some sense. Options: -prefix p = use string 'p' for the prefix of the output dataset [DEFAULT = 'tnorm'] -norm2 = L2 normalize (sum of squares = 1) [DEFAULT] -normR = normalize so sum of squares = number of time points * e.g., so RMS = 1. -norm1 = L1 normalize (sum of absolute values = 1) -normx = Scale so max absolute value = 1 (L_infinity norm) -polort p = Detrend with polynomials of order p before normalizing [DEFAULT = don't do this] * Use '-polort 0' to remove the mean, for example -L1fit = Detrend with L1 regression (L2 is the default) * This option is here just for the hell of it Notes: * Each voxel is processed separately * A voxel that is all zero will be unchanged (duh) * Output dataset is in float format, no matter what the input format * This program is for producing regressors to use in 3dTfitter * Also see programs 1dnorm and 3dcalc ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTORTOISEtoHere
Convert standard TORTOISE DTs (diagonal-first format) to standard AFNI (lower triangular, row-wise) format. NB: Starting from TORTOISE v2.0.1, there is an 'AFNI output' format as well, which would not need to be converted. Part of FATCAT (Taylor & Saad, 2013) in AFNI. *** NB: this program is likely no longer necessary if using 'AFNI *** export' from TORTOISE! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + COMMAND: 3dTORTOISEtoHere -dt_tort DTFILE {-scale_fac X } \ {-flip_x | -flip_y | -flip_z} -prefix PREFIX * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + OUTPUT: 1) An AFNI-style DT file with the following ordering of the 6 bricks: Dxx,Dxy,Dyy,Dxz,Dyz,Dzz. In case it is useful, one can apply 'flips' to the eventual (or underlying, depending how you look at it) eigenvector directions, as well as rescale the associated eigenvalues. + RUNNING: -dt_tort DTFILE :diffusion tensor file, which should have six bricks of DT components ordered in the TORTOISE manner, i.e., diagonals first: Dxx,Dyy,Dzz,Dxy,Dxz,Dyz. -prefix PREFIX :output file name prefix. Will have N+1 bricks when GRADFILE has N rows of gradients. -flip_x :change sign of first element of (inner) eigenvectors. -flip_y :change sign of second element of (inner) eigenvectors. -flip_z :change sign of third element of (inner) eigenvectors. -> Only a single flip would ever be necessary; the combination of any two flips is mathematically equivalent to the sole application of the remaining one. Normally, it is the *gradients* that are flipped, not the DT, but if, for example, necessary files are missing, then one can apply the requisite changes here. -scale_fac X :optional switch to rescale the DT elements, dividing by a number X>0. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + EXAMPLE: 3dTORTOISEtoHere \ -dt_tort DTI/DT_DT+orig \ -scale_fac 1000 \ -prefix AFNI_DT * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * If you use this program, please reference the introductory/description paper for the FATCAT toolbox: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity 3(5):523-535. ____________________________________________________________________________

AFNI program: 3dToutcount
Usage: 3dToutcount [options] dataset Calculates number of 'outliers' a 3D+time dataset, at each time point, and writes the results to stdout. Options: -mask mset = Only count voxels in the mask dataset. -qthr q = Use 'q' instead of 0.001 in the calculation of alpha (below): 0 < q < 1. -autoclip }= Clip off 'small' voxels (as in 3dClipLevel); -automask }= you can't use this with -mask! -fraction = Output the fraction of (masked) voxels which are outliers at each time point, instead of the count. -range = Print out median+3.5*MAD of outlier count with each time point; use with 1dplot as in 3dToutcount -range fred+orig | 1dplot -stdin -one -save ppp = Make a new dataset, and save the outlier Q in each voxel, where Q is calculated from voxel value v by Q = -log10(qg(abs((v-median)/(sqrt(PI/2)*MAD)))) or Q = 0 if v is 'close' to the median (not an outlier). That is, 10**(-Q) is roughly the p-value of value v under the hypothesis that the v's are iid normal. The prefix of the new dataset (float format) is 'ppp'. -polort nn = Detrend each voxel time series with polynomials of order 'nn' prior to outlier estimation. Default value of nn=0, which means just remove the median. Detrending is done with L1 regression, not L2. -legendre = Use Legendre polynomials (also allows -polort > 3). OUTLIERS are defined as follows: * The trend and MAD of each time series are calculated. - MAD = median absolute deviation = median absolute value of time series minus trend. * In each time series, points that are 'far away' from the trend are called outliers, where 'far' is defined by alpha * sqrt(PI/2) * MAD alpha = qginv(0.001/N) (inverse of reversed Gaussian CDF) N = length of time series * Some outliers are to be expected, but if a large fraction of the voxels in a volume are called outliers, you should investigate the dataset more fully. Since the results are written to stdout, you probably want to redirect them to a file or another program, as in this example: 3dToutcount -automask v1+orig | 1dplot -stdin NOTE: also see program 3dTqual for a similar quality check. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dtoXdataset
Convert input datasets to the format needed for 3dClustSimX. Usage: 3dtoXdataset -prefix PPP maskdataset inputdataset ... The output file 'PPP.sdat' will be created, if it does not exist. If it already exists, the input dataset value (inside the mask) will be appended to this output file.

AFNI program: 3dToyProg
Usage: 3dToyProg [-prefix PREF] [-mask MSET] [-datum DATUM] [-h|-help] <-input ISET> A program to illustrate dataset creation, and manipulation in C using AFNI's API. Comments in the code (should) explain it all. -input ISET: reference dataset -prefix PREF: Prefix of output datasets. -mask MSET: Restrict analysis to non-zero voxels in MSET -datum DATUM: Output datum type for one of the datasets. Choose from 'float' or 'short'. Default is 'float' -h: Mini help, at time, same as -help in many cases. -help: The entire help output -HELP: Extreme help, same as -help in majority of cases. -h_view: Open help in text editor. AFNI will try to find a GUI editor -hview : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_web: Open help in web browser. AFNI will try to find a browser. -hweb : on your machine. You can control which it should use by setting environment variable AFNI_GUI_EDITOR. -h_find WORD: Look for lines in this programs's -help output that match (approximately) WORD. -h_raw: Help string unedited -h_spx: Help string in sphinx loveliness, but do not try to autoformat -h_aspx: Help string in sphinx with autoformatting of options, etc. -all_opts: Try to identify all options for the program from the output of its -help option. Some options might be missed and others misidentified. Use this output for hints only. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTproject
Usage: 3dTproject [options] 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). -------- OPTIONS: -------- -input dataset = Specifies the input dataset. -prefix ppp = Specifies the output dataset, as usual. -censor cname = As in 3dDeconvolve. -CENSORTR clist = As in 3dDeconvolve. -cenmode mode = 'mode' 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 !!! -concat ccc.1D = 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. -noblock = 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. -ort f.1D = Remove each column in f.1D ++ Multiple -ort options are allowed. ++ Each column will have its mean removed. -polort pp = 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. -dsort fset = 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. -passband fbot ftop = Remove all frequencies EXCEPT those in the range *OR* -bandpass fbot..ftop. ++ Only one -passband option is allowed. -stopband sbot stop = Remove all frequencies in the range sbot..stop. ++ More than one -stopband option is allowed. ++ For example, '-passband 0.01 0.10' is equivalent to '-stopband 0 0.0099 -stopband 0.1001 9999' -dt dd = Use time step dd for the frequency calculations, *OR* -TR rather than the value stored in the dataset header. -mask mset = Only operate on voxels nonzero in the mset dataset. *OR* ++ Use '-mask AUTO' to have the program generate the -automask mask automatically (or use '-automask') ++ Voxels outside the mask will be filled with zeros. ++ If no masking option is given, then all voxels will be processed. -blur fff = 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. -norm = Normalize each output time series to have sum of squares = 1. This is the LAST operation. -quiet = Hide the super-fun and thrilling progress messages. -verb = The program will save the fixed ort matrix and its singular values into .1D files, for post-mortems. It will also print out more progress messages, which might help with figuring out what's happening when problems occur. ------ NOTES: ------ * The output dataset is in floating point format. * Removal of the various undesired components is via linear regression. In particular, this method allows for bandpassing of censored time series. * If you like technical math jargon (and who doesn't?), this program performs orthogonal projection onto the null space of the set of 'ort' vectors assembled from the various options '-polort', '-ort', '-passband', '-stopband', and '-dsort'. * If A is a matrix whose column comprise the vectors to be projected out, define the projection matrix Q(A) by Q(A) = I - A psinv(A) where psinv(A) is the pseudo-inverse of A [e.g., inv(A'A)A' -- but the pseudo-inverse is actually calculated here via the SVD algorithm.] * If option '-dsort' is used, each voxel has a different matrix of regressors -- encode this extra set of regressors in matrix B (i.e., each column of B is a vector to be removed from its voxel's time series). Then the projection for the compound matrix [A B] is Q( Q(A)B ) Q(A) that is, A is projected out of B, then the projector for that reduced B is formed, and applied to the projector for the voxel-independent A. Since the number of columns in B is usually many fewer than the number of columns in A, this technique can be much faster than constructing the full Q([A B]) for each voxel. (Since Q(A) only need to be constructed once for all voxels.) A little fun linear algebra will show you that Q(Q(A)B)Q(A) = Q([A B]). * A similar regression could be done via the slower 3dTfitter program: 3dTfitter -RHS inputdataset+orig \ -LHS ort1.1D dsort2+orig \ -polort 2 -prefix NULL \ -fitts Tfit 3dcalc -a inputdataset+orig -b Tfit+orig -expr 'a-b' \ -datum float -prefix Tresidual 3dTproject should be MUCH more efficient, especially when using voxel-specific regressors (i.e., '-dsort'), and of course, it also offers internal generation of the bandpass/stopband regressors, as well as censoring, blurring, and L2-norming. * This version of the program is compiled using OpenMP for speed. * Authored by RWCox in a fit of excessive linear algebra [summer 2013]. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTqual
Usage: 3dTqual [options] dataset 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. Note that small values of the index are 'good', indicating that the sub-brick is not very different from the norm. The purpose of this program is to provide a crude way of screening FMRI time series for sporadic abnormal images, such as might be caused by large subject head motion or scanner glitches. Do not take the results of this program too literally. It is intended as a GUIDE to help you find data problems, and no more. It is not an assurance that the dataset is good, and it may indicate problems where nothing is wrong. Sub-bricks with index values much higher than others should be examined for problems. How you determine what 'much higher' means is mostly up to you. I suggest graphical inspection of the indexes (cf. EXAMPLE, infra). As a guide, the program will print (stderr) the median quality index and the range median-3.5*MAD .. median+3.5*MAD (MAD=Median Absolute Deviation). Values well outside this range might be considered suspect; if the quality index were normally distributed, then values outside this range would occur only about 1% of the time. OPTIONS: -spearman = Quality index is 1 minus the Spearman (rank) correlation coefficient of each sub-brick with the median sub-brick. [This is the default method.] -quadrant = Similar to -spearman, but using 1 minus the quadrant correlation coefficient as the quality index. -autoclip = Clip off low-intensity regions in the median sub-brick, -automask = so that the correlation is only computed between high-intensity (presumably brain) voxels. The intensity level is determined the same way that 3dClipLevel works. This prevents the vast number of nearly 0 voxels outside the brain from biasing the correlation coefficient calculations. -clip val = Clip off values below 'val' in the median sub-brick. -mask MSET = Compute correlation only across masked voxels. -range = Print the median-3.5*MAD and median+3.5*MAD values out with EACH quality index, so that they can be plotted (cf. Example, infra). Notes: * These values are printed to stderr in any case. * This is only useful for plotting with 1dplot. * The lower value median-3.5*MAD is never allowed to go below 0. EXAMPLE: 3dTqual -range -automask fred+orig | 1dplot -one -stdin will calculate the time series of quality indexes and plot them to an X11 window, along with the median+/-3.5*MAD bands. NOTE: cf. program 3dToutcount for a somewhat different quality check. -- RWCox - Aug 2001 ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTrackID
FACTID-based tractography code, from Taylor, Cho, Lin and Biswal (2012), and part of FATCAT (Taylor & Saad, 2013) in AFNI. Version 2.1 (Jan. 2014), written by PA Taylor and ZS Saad. Estimate locations of WM associated with target ROIs, particularly between pairs of GM in a network; can process several networks in a given run. Now does both single tract propagation per voxel (as per DTI) and multi-directional tracking (as in HARDI-type models). Many extra files can be loaded in for getting quantitative stats in WM-ROIs, mostly done via search from entered prefixes. Many more switches and options are available to the user to control the tracking (yay!). Track display capabilities in SUMA have been boosted and continue to rise quickly (all courtesy of ZS Saad). **************************************************************************** + NOTE that this program runs in three separate modes, each with its own subset of commandline options and outputs: $ 3dTrackID -mode {DET | MINIP | PROB} ... where DET -> deterministic tracking, MINIP -> mini-probabilistic tracking, PROB -> (full) probabilistic tracking. So, for example, DET and MINIP produce pretty track-image output, while PROB only provides volumes; MINIP and PROB make use of tensor uncertainty to produce more robust results than DET; all produce quantitative statistical output of WM-ROIs; etc. In some cases, using a combination of all three might even be variously useful in a particular study. **************************************************************************** For DTI, this program reads in tensor-related data from, e.g., 3dDWItoDT, and also uses results from 3dDWUncert for uncertainty measures when necessary. For HARDI, this program reads in the direction vectors and WM-proxy map (such as the diffusion anisotropy coefficient, GFA) created by any source- right now, there's no HARDI modeler in AFNI. Currently known sources which are reasonably straightforward to use include DSI-Studio (Yeh et al., 2010) and Diffusion Toolkit (Wang et al., 2007). An example script of outputting Qball model data as NIFTI output from the former software is included in the FATCAT demo set. ...And on that note, it is highly recommended for users to check out the FATCAT demo set, which can be downloaded and unwrapped simply from the commandline: $ @Install_FATCAT_Demo In that demo are data, a number of scripts, and more detailed descriptions for using 3dTrackID, as well as other programs in the FATCAT litter. Recommended to always check that one has the most up-to-date version. **************************************************************************** + INPUT NOTES: NETWORK MAPS, for any '-mode' of track, given as a single- or multi-brik file via '-netrois': Each target ROI is defined by the set of voxels with a given integer >0. Target ROI labels do not have to be purely consecutive. Note on vocabulary, dual usage of 'ROI': an (input) network is made up of *target ROIs*, between/among which one wants to find WM connections; so, 3dTrackID outputs locations and stats on those calculated *WM-ROIs*. **************************************************************************** + OUTPUTS, all named using '-prefix INPREF'; somewhat dependent on tracking mode being utilized ('-mode {DET | MINIP | PROB}'). Because multiple networks can be input simultaneously as a multi- brik '-netrois ROIS' file, the output prefix will also have a numerical designation of its network, matching to the brik of the ROIS file: thus, INPREF_000* goes with ROIS[0], INPREF_001* with ROIS[1] (if present), etc. This applies with all types of output files, now described: 1) *INDIMAP* BRIK files (output in ALL modes). For each network with N_ROI target ROIs, this is a N_ROI+1 brik file. 0th brick contains the number of tracts per voxel which passed through at least one target ROI in that network (and in '-mode PROB', this number has been thresholded-- see 'alg_Thresh_Frac' below). If the target ROIs are consecutively labelled from 1 to N_ROI, then: Each i-th brick (i running from 1 to N_ROI) contains the voxels through which tracks hitting that i-th target passed; the value of each voxel is the number of tracks passing through that location. Else, then: Each i-th brick contains the voxels through which the tracks hitting the j-th target passed (where j may or may not equal i; the value of j is recorded in the brick label: OR_roi_'j'). The target ROI connectivity is recorded increasing order of 'j'. For single-ROI inputs (such as a single wholebrain ROI), only the [0] brick is output (because [1] would be redundant). 2) *PAIRMAP* BRIK files (output in ALL modes). (-> This has altered slightly at the end of June, 2014! No longer using 2^i notation-- made simpler for reading, assuming individual connection information for calculations was likely obtained more easily with '-dump_rois {AFNI | BOTH | AFNI_MAP}...) For each network with N_ROI target ROIs, this is a N_ROI+1 brik file. 0th brick contains a binary mask of voxels through which passed a supra-threshold number of tracks (more than 0 for '-mode {DET | MINIP}' and more than the user-defined threshold for '-mode PROB') between any pair of target ROIs in that network (by default, these tracks have been trimmed to only run between ROIs, cutting off parts than dangle outside of the connection). If the target ROIs are consecutively labelled from 1 to N_ROI, then: Each i-th brick (i running from 1 to N_ROI) contains the voxels through which tracks hitting that i-th target AND any other target passed; voxels connecting i- and j-th target ROIs have value j, and the values are summed if a given voxel is in multiple WM ROIs (i.e., for a voxel connecting both target ROIs 2 and 1 as well as 2 and 4, then the value there in brick [2] would be 1 + 4 = 5). Else, then: Each i-th brick contains the voxels through which the tracks hitting the j-th target AND any other target passed (where j may or may not equal i; the value of j is recorded in the brick label: AND_roi_'j'). The same voxel labelling and summing rules described above also apply here. For single-ROI inputs (such as a single wholebrain ROI), no PAIRMAP file is output (because it would necessarily be empty). 3) *.grid ASCII-text file (output in ALL modes). Simple text file of output stats of WM-ROIs. It outputs the means and standard deviations of parameter quantities (such as FA, MD, L1, etc.) as well as counts of tracks and volumes of WM-ROIs. Each matrix is square, with dimension N_ROI by N_ROI. Like the locations in a standard correlation matrix, each element reflects associativity with target ROIs. A value at element (1,3) is the same as that at (3,1) and tells about the property of a WM-ROI connecting target ROIs 1 and 3 (consider upper left corner as (1,1)); diagonal elements provide info of tracks through (at minimum) that single target ROI-- like OR logic connection. Format of *.grid file is: Line 1: number of ROIs in network (padded with #-signs) Line 2: number of output matrices of stats info (padded with #-signs) Line 3: list of N_ROI labels for that network Lines following: first line, label of a property (padded with #), and then N_ROI lines of the N_ROI-by-N_ROI matrix of that property; /repeat/ The first *five* matrices are currently (this may change over time): NT = number of tracks in that WM-ROI fNT = fractional number of tracks in that WM-ROI, defined as NT divided by total number of tracts found (may not be relevant) PV = physical volume of tracks, in mm^3 fNV = fractional volume of tracks compared to masked (internally or '-mask'edly) total volume; would perhaps be useful if said mask represents the whole brain volume well. NV = number of voxels in that WM-ROI. BL = average length (in mm) of a bundle of tracts. sBL = stdev of the length (in mm) of a bundle of tracts. Then, there can be a great variety in the remaining matrices, depending on whether one is in DTI or HARDI mode and how many scalar parameter files get input (max is 10). For each scalar file there are two matrices: first a label (e.g., 'FA') and then an N_ROI-by-N_ROI matrix of the means of that parameter in each WM-ROI; then a label (here, would be 'sFA') and then an N_ROI-by-N_ROI matrix of the standard deviations of that parameter in each WM-ROI. 4) *niml.tract NIML/SUMA-esque file (output in '-mode {DET | MINIP}') File for viewing track-like output in SUMA, with, e.g.: $ suma -tract FILE.niml.tract 5) *niml.dset NIML/SUMA-esque file (output in '-mode {DET | MINIP}') File accompanying the *.niml.tract file-- also for use in SUMA, for including GRID-file like information with the tract info. $ suma -tract FILE.niml.tract -gdset FILE.niml.dset 6) *.trk TrackVis-esque file (output in '-mode {DET | MINIP}') File for viewing track-like output in TrackVis (separate install from AFNI/SUMA); things mainly done via GUI interface; this format of output is off by default (see '-do_trk_out' below to enable it). **************************************************************************** + LABELTABLE LABELLING (Sept 2014). The ability to use label tables in tracking result output has been included. Default behavior will be to *construct* a labeltable from zero-padded ints in the '-netrois' file which define target ROIs. Thus, the ROI of '3's will be given a label '003'. This will be used in INDIMAP and PAIRMAP brick labels (which is useful if the targets are not consecutively numbered from 1), PAIRMAP connections in bricks >0, and output *.niml.tract files. The PAIRMAP labeltable will be created and output as 'PREFIX_PAIRMAP.niml.lt', and will be useful for the user in (some- what efficiently) resolving multiple tracts passing through voxels. These labels are also used in the naming of '-dump_rois AFNI' output. At the moment, in a given PAIRMAP brick of index >0, labels can only describe up to two connections through a given voxel. In brick 1, if voxel is intersected by tracts connection ROIs 1 and 3 as well as ROIs 1 and 6, then the label there would be '003<->006'; if another voxel in that brick had those connections as well as one between ROIs 1 and 4, then the label might be '_M_<->003<->006', or '_M_<->003<->004', or any two of the connections plus the leading '_M_' that stands for 'multiple others' (NB: which two are shown is not controlled, but I figured it was better to show at least some, rather than just the less informative '_M_' alone). In all of these things, the PAIRMAP map is a useful, fairly efficient guide-check, but the overlaps are difficult to represent fully and efficiently, given the possibly complexity of patterns. For more definite, unique, and scriptable information of where estimated WM connections are, use the '-dump_rois AFNI' or '-dump_rois AFNI_MAP' option. If the '-netrois' input has a labeltable, then this program will program will read it in, use it in PAIRMAP and INDIMAP bricklabels, PAIRMAP subbricks with index >0, *niml.tract outputs and, by default, in the naming of '-dump_rois AFNI' output. The examples and descriptions directly above still hold, but in cases where the ROI number has an explicit label, then the former is replaced by the latter's string. In cases where an input label table does not cover all ROI values, there is no need to panic-- the explicit input labels will be used wherever possible, and the zero-padded numbers will be used for the remaining cases. Thus, one might see PAIRMAP labels such as: '003<->Right-Amygdala', '_M_<->ctx-lh-insula<->006', etc. **************************************************************************** + RUNNING AND COMMANDLINE OPTIONS: pick a MODEL and a MODE. There are now two types of models, DTI and HARDI, that can be tracked. In HARDI, one may have multiple directions per voxel along which tracts may propagate; in DTI, there can be only one. Each MODEL has some required, and some optional, inputs. Additionally, tracking is run in one of three modes, as described near the top of this document, '-mode {DET | MINIP | PROB}', for deterministic mini-probabilistic, or full probabilistic tracking, respectively. Each MODE has some required, and some optional, inputs. Some options find work in multiple modes. To run '3dTrackID', one needs to have both a model and a mode in mind (and in data...). Below is a table to show the various options available for the user to perform tracking. The required options for a given model or mode are marked with a single asterisk (*); the options under the /ALL/ column are necessary in any mode. Thus, to run deterministic tracking with DTI data, one *NEEDS* to select, at a minimum: '-mode DET', '-netrois', '-prefix', '-logic'; and then there is a choice of loading DTI data, with either: '-dti_in' or '-dti_list', and then one can also use '-dti_extra', '-mask', '-alg_Nseed_Y', et al. from the /ALL/ and DET columns; one canNOT specify '-unc_min_FA' here -> the option is in an unmatched mode column. Exact usages of each option, plus formats for any arguments, are listed below. Default values for optional arguments are also described. +-----------------------------------------------------------------+ | COMMAND OPTIONS FOR TRACKING MODES AND MODELS | +-----------------------------------------------------------------+ | /ALL/ | DET | MINIP | PROB | +--------+-------------------+-------------+-------------+-----------------+ |{dti_in, dti_list}*| | | | DTI | dti_extra | | | | | dti_search_NO | | | | +-~or~---+-------------------+-------------+-------------+-----------------+ | hardi_gfa* | | | | HARDI | hardi_dirs* | | | | | hardi_pars | | | | ==~and~==+===================+=============+=============+=================+ | mode* | | | | OPTIONS | netrois* | | | | | prefix* | | | | | mask | | | | | thru_mask | | | | | targ_surf_stop | | | | | targ_surf_twixt | | | | | | logic* | logic* | | | | | mini_num* | | | | | uncert* | uncert* | | | | unc_min_FA | unc_min_FA | | | | unc_min_V | unc_min_V | | algopt | | | | | alg_Thresh_FA | | | | | alg_Thresh_ANG | | | | | alg_Thresh_Len | | | | | | alg_Nseed_X | alg_Nseed_X | | | | alg_Nseed_Y | alg_Nseed_Y | | | | alg_Nseed_Z | alg_Nseed_Z | | | | | | alg_Thresh_Frac | | | | | alg_Nseed_Vox | | | | | alg_Nmonte | | uncut_at_rois | | | | | do_trk_out | | | | | trk_opp_orient | | | | | dump_rois | | | | | dump_no_labtab | | | | | dump_lab_consec | | | | | posteriori | | | | | rec_orig | | | | | tract_out_mode | | | | | write_opts | | | | | write_rois | | | | | pair_out_power | | | | +--------+-------------------+-------------+-------------+-----------------+ *above, asterisked options are REQUIRED for running the given '-mode'. With DTI data, one must use either '-dti_in' *or* '-dti_list' for input. FOR MODEL DTI: -dti_in INPREF :basename of DTI volumes output by, e.g., 3dDWItoDT. NB- following volumes are *required* to be present: INPREF_FA, INPREF_MD, INPREF_L1, INPREF_V1, INPREF_V2, INPREF_V3, and (now) INPREF_RD (**now output by 3dTrackID**). Additionally, the program will search for all other scalar (=single brik) files with name INPREF* and will load these in as additional quantities for WM-ROI stats; this could be useful if, for example, you have PD or anatomical measures and want mean/stdev values in the WM-ROIs (to turn this feature off, see below, 'dti_search_NO'); all the INPREF* files must be in same DWI space. Sidenote: including/omitting a '_' at the end of INPREF makes no difference in the hunt for files. -dti_extra SET :if you want to use a non-FA derived definition for the WM skeleton in which tracts run, you can input one, and then the threshold in the -algopt file (or, via the '-alg_Thresh_FA' option) will be applied to thresholding this SET; similarly for the minimum uncertainty by default will be set to 0.015 times the max value of SET, or can be set with '-unc_min_FA'. If the SET name is formatted as INPREF*, then it will probably be included twice in stats, but that's not the worst thing. In grid files, name of this quantity will be 'XF' (stands for 'extra file'). -dti_search_NO :turn off the feature to search for more scalar (=single brik) files with INPREF*, for including stats in output GRID file. Will only go for FA, MD, L1 and RD scalars with INPREF. -dti_list FILE :an alternative way to specify DTI input files, where FILE is a NIML-formatted text file that lists the explicit/specific files for DTI input. This option is used in place of '-dti_in' and '-dti_extra' for loading data sets of FA, MD, L1, etc. An 'extra' set (XF) can be loaded in the file, as well as supplementary scalar data sets for extra WM-ROI statistics. See below for a 'DTI LIST FILE EXAMPLE'. FOR MODEL HARDI: -hardi_gfa GFA :single brik data set with generalized FA (GFA) info. In reality, it doesn't *have* to be a literal GFA, esp. if you are using some HARDI variety that doesn't have a specific GFA value-- in such a case, use whatever could be thresholded as your proxy for WM. The default threshold is still 0.2, so you will likely need to set a new one in the '-algopt ALG_FILE' file or from the commandline with '-alg_Thresh_FA', which does apply to the GFA in the HARDI case as well. Stats in GRID file are output under name 'GFA'. -hardi_dirs DIRS :For tracking if X>1 propagation directions per voxel are given, for example if HARDI data is input. DIRS would then be a file with 3*X briks of (x,y,z) ordered, unit magnitude vector components; i.e., brik [0] contains V1_x, [1] V1_y, [2] V1_z, [3] V2_x, etc. (NB: even if X=1, this option works, but that would seem to take the HAR out of HARDI...) -hardi_pars PREF :search for scalar (=single brik) files of naming format PREF*. These will be read in for WM-ROI stats output in the GRID file. For example, if there are some files PREF_PD.nii.gz, PREF_CAT.nii.gz and PREF_DOG.nii.gz, they will be labelled in the GRID file as 'PD', 'CAT' and 'DOG' (that '_' will be cut out). MODEL-INDEPENDENT OPTIONS: -mode MODUS :this necessary option is used to define whether one is performing deterministic, mini-probabilistic or full- probabilistic tractography, by selecting one of three respective modes: DET, MINIP, or PROB. -netrois ROIS :mask(s) of target ROIs- single file can have multiple briks, one per network. The target ROIs through which tracks will be kept should have index values >0. It is also possible to define anti-targets (exclusionary regions) which stop a propagating track... in its tracks. These are defined per network (i.e., per brik) by voxels with values <0. -prefix PREFIX :output file name part. -mask MASK :can include a brainmask within which to calculate things. Otherwise, data should be masked already. -thru_mask TM :optional extra restrictor mask, through which paths are (strictly) required to pass in order to be included when passing through or connecting targets. It doesn't discriminate based on target ROI number, so it's probably mostly useful in examining specific pairwise connections. It is also not like one of the target '-netrois' in that no statistics are calculated for it. Must be same number of briks as '-netrois' set. -targ_surf_stop :make the final tracts and tracked regions stop at the outer surface of the target ROIs, rather than being able to journey arbitrarily far into them (latter being the default behavior. Might be useful when you want meaningful distances *between* targets. Tracts stop after going *into* the outer layer of a target. This can be applied to DET, MINIP, or PROB modes. NB: this only affects the connections between pairs of targets (= AND-logic, off-diagonal elements in output matrices), not the single-target tracts (= OR-logic, on-diagonal elements in output matrices); see also a related option, below. -targ_surf_twixt :quite similar to '-targ_surf_stop', above, but the tracts stop *before* entering the target surfaces, so that they are only between (or betwixt) the targets. Again, only affects tracts between pairs of targets. -logic {OR|AND} :when in one of '-mode {DET | MINIP}', one will look for either OR- or AND-logic connections among target ROIs per network (multiple networks can be entered as separate briks in '-netrois ROIS'): i.e., one keeps either any track going through at least one network ROI or only those tracks which join a pair of ROIs. When using AND here, default behavior is to only keep voxels in tracks between the ROIs they connect (i.e., cut off track bits which run beyond ROIs). -mini_num NUM :will run a small number NUM of whole brain Monte Carlo iterations perturbing relevant tensor values in accord with their uncertainty values (hence, the need for also using `-uncert' with this option). This might be useful for giving a flavor of a broader range of connections while still seeing estimated tracks themselves. NB: if NUM is large, you might be *big* output track files; e.g., perhaps try NUM = 5 or 9 or so to start. Requires '-mode MINIP' in commandline. -bundle_thr V :the number of tracts for a given connection is called a bundle. For '-mode {DET | MINIP}', one can choose to NOT output tracts, matrix info, etc. for any bundle with fewer than V tracts. This might be useful to weed out ugly/false tracts (default: V=1). -uncert U_FILE :when in one of '-mode {MINIP | PROB}', uncertainty values for eigenvector and WM skeleton (FA, GFA, etc.) maps are necessary. When using DTI ('-dti_*'), then use the 6-brik file from 3dDWUncert; format of the file given below. When using HARDI ('-hardi_*') with up to X directions per voxel, one needs U_FILE to have X+1 briks, where U_FILE[0] is the uncertainty for the GFAfile, and the other briks are ordered for directions given with '-hardi_dirs'. Whatever the values in the U_FILE, this program asserts a minimum uncertainty of stdevs, with defaults: for FA it is 0.015, and for GFA or -dti_extra sets it is 0.015 times the max value present (set with option '-unc_min_FA'); for each eigenvector or dir, it is 0.06rad (~3.4deg) (set with option '-unc_min_V') -unc_min_FA VAL1 :when using '-uncert', one can control the minimum stdev for perturbing FA (in '-dti_in'), or the EXTRA- file also in DTI ('-dti_extra'), or GFA (in '-hardi_*). Default value is: 0.015 for FA, and 0.015 times the max value in the EXTRA-file or in the GFA file. -unc_min_V VAL2 :when using '-uncert', one can control the minimum stdev for perturbing eigen-/direction-vectors. In DTI, this is for tipping e_1 separately toward e2 and e3, and in HARDI, this is for defining a single degree of freedom uncertainty cone. Default values are 0.06rad (~3.4deg) for any eigenvector/direction. User assigns values in degrees. -algopt A_FILE :simple ASCII file with six numbers defining tracking parameter quantities (see list below); note the differences whether running in '-mode {DET | MINIP}' or in '-mode PROB': the first three parameters in each mode are the same, but the next three differ. The file can be in the more understandable html-type format with labels per quantity, or just as a column of the numbers, necessarily in the correct order. NB: each quantity can also be changed individually using a commandline option (see immediately following). If A_FILE ends with '.niml.opts' (such as would be produced using the '-write_opts' option), then it is expected that it is in nice labelled NIML format; otherwise, the file should just be a column of numbers in the right order. Examples of A_FILEs are given at the end of the option section. -alg_Thresh_FA A :set threshold for DTI FA map, '-dti_extra' FILE, or HARDI GFA map (default = 0.2). -alg_Thresh_ANG B :set max angle (in deg) for turning when going to a new voxel during propagation (default = 60). -alg_Thresh_Len C :min physical length (in mm) of tracts to keep (default = 20). -alg_Nseed_X D :Number of seeds per vox in x-direc (default = 2). -alg_Nseed_Y E :Number of seeds per vox in y-direc (default = 2). -alg_Nseed_Z F :Number of seeds per vox in z-direc (default = 2). +-------> NB: in summation, for example the alg_Nseed_* options for '-mode {DET | MINIP} place 2x2x2=8 seed points, equally spread in a 3D cube, in each voxel when tracking. -alg_Thresh_Frac G :value for thresholding how many tracks must pass through a voxel for a given connection before it is included in the final WM-ROI of that connection. It is a decimal value <=1, which will multiply the number of 'starting seeds' per voxel, Nseed_Vox*Nmonte (see just below for those). (efault = 0.001; for higher specificity, a value of 0.01-0.05 could be used). -alg_Nseed_Vox H :number of seeds per voxel per Monte Carlo iteration; seeds will be placed randomly (default = 5). -alg_Nmonte I :number of Monte Carlo iterations (default = 1000). +-------> NB: in summation, the preceding three options for the '-mode PROB' will mean that 'I' Monte Carlo iterations will be run, each time using 'H' track seeds per relevant voxel, and that a voxel will need 'G*H*I' tracks of a given connection through it to be included in that WM-ROI. Default example: 1000 iterations with 5 seeds/voxel, and therefore a candidate voxel needs at least 0.001*5*1000 = 5 tracks/connection. -extra_tr_par :run three extra track parameter scalings for each target pair, output in the *.grid file. The NT value of each connection is scaled in the following manners for each subsequent matrix label: NTpTarVol :div. by average target volume; NTpTarSA :div. by average target surface area; NTpTarSAFA :div. by average target surface area bordering suprathreshold FA (or equi- valent WM proxy definition). NB: the volume and surface area numbers are given in terms of voxel counts and not using physical units (consistent: NT values themselves are just numbers.) -uncut_at_rois :when looking for pairwise connections, keep entire length of any track passing through multiple targets, even when part ~overshoots a target (i.e., it's not between them). When using OR tracking, this is automatically applied. For probabilistic tracking, not recommended to use (are untrimmed ends meaningful?). The default behavior is to trim the tracts that AND- wise connect targets to only include sections that are between the targets, and not parts that run beyond one. (Not sure why one would want to use this option, to be honest; see '-targ_surf_stop' for really useful tract control.) -dump_rois TYPE :can output individual masks of ROI connections. Options for TYPE are: {DUMP | AFNI | BOTH | AFNI_MAP}. Using DUMP gives a set of 4-column ASCII files, each formatted like a 3dmaskdump data set; it can be recon- stituted using 3dUndump. Using AFNI gives a set of BRIK/HEAD (byte) files in a directory called PREFIX; using AFNI_MAP is like using AFNI, but it gives non- binarized *maps* of ROI connections. Using BOTH produces AFNI and DUMP formats of outputs. -dump_no_labtab :if the ROIS file has a label table, the default is to use it in naming a '-dump_rois' output (if being used); using this switch turn that off-- output file names will be the same as if no label table were present. -dump_lab_consec :if using `-dump_rois', then DON'T apply the numerical labels of the original ROIs input to the output names. This would only matter if input ROI labels aren't consecutive and starting with one (e.g., if instead they were 1,2,3,5,8,..). ---> This is the opposite from previous default behavior, where the option '-lab_orig_rois' was used to switch away from consecutive-izing the labels in the output. -posteriori :switch to have a bunch of individual files output, with the value in each being the number of tracks per voxel for that pair; works with '-dump_rois {AFNI | BOTH }', where you get track-path maps instead of masks; makes threshold for number of tracks between ROIs to keep to be one automatically, regardless of setting in algopt. -rec_orig :record dataset origin in the header of the *.trk file. As of Sept. 2012, TrackVis doesn't use this info so it wasn't included, but if you might want to map your *.trk file later, then use the switch as the datasets's Origin is necessary info for the mapping (the default image in TrackVis might not pop up in the center of the viewing window, though, just be aware). NB: including the origin might become default at some point in time. -do_trk_out :Switch ON outputting *.trk files, which are mainly to be viewed in TrackVis (Wang et al., 2007). (Feb, 2015): Default is to NOT output *.trk files. -trk_opp_orient :If outputting *.trk files, you can choose to oppositize the voxel_order parameter for the TRK file (only). Thus, when inputting AFNI files with orient RAI, the *.trk file would have voxel_order LPS; this is so that files can be viewed in some other software, such as DTK. -nifti :output the PAIRMAP, INDIMAP, and any '-dump_rois' in *.nii.gz format (default is BRIK/HEAD). -no_indipair_out :Switch off outputting *INDIMAP* and *PAIRMAP* volumes. This is probably just if you want to save file space; also, for connectome-y studies with many (>100) target regions, the output INDI and PAIR maps can be quite large and/or difficult to write out. In some cases, it might be better to just use '-dump_rois AFNI' instead. Default is to output the INDI and PAIR map files. -write_rois :write out a file (PREFIX.roi.labs) of all the ROI (re-)labels, for example if the input ROIs aren't simply consecutive and starting from 1. File has 3cols: Input_ROI Condensed_form_ROI Power_of_2_label -write_opts :write out all the option values into PREFIX.niml.opts. -pair_out_power :switch to affect output of *PAIRMAP* output files. Now, the default format is to output the >0 bricks with tracks labelled by the target integers themselves. This is not a unique labelling system, but it *is* far easier to view and understand what's going on than using a purely unique system based on using powers of two of the ROIs (with integer summation for overlaps). Using the switch '-pair_out_power' will change the output of bricks [1] and higher to contain information on connections stored as powers of two, so that there is a unique decomposition in terms of overlapped connections. However, it's *far* easier to use '-dump_rois {AFNI | BOTH }' to get individual mask files of the ROIs clearly (as well as annoying to need to calculate powers of two simply to visualize the connections. -----> when considering this option, see the 'LABELTABLE' description up above for how the labels work, with or without an explicit table being entered. -verb VERB :verbosity level, default is 0. **************************************************************************** + ALGOPT FILE EXAMPLES (note that different MODES have some different opts): For '-mode {DET | MINIP}, the nicely readable NIML format of algopt file would have a file name ending '.niml.opts' and contain something like the: following seven lines: <TRACK_opts Thresh_FA="0.2" Thresh_ANG="60.000000" Thresh_Len="20.000000" Nseed_X="2" Nseed_Y="2" Nseed_Z="2" /> The values above are actually all default values, and such a file would be output using the '-write_opts' flag. For the same modes, one could get the same result using a plain column of numbers, whose meaning is defined by their order, contained in a file NOT ending in .niml.opts, such as exemplified in the next six lines: 0.2 60 20 2 2 2 For '-mode PROB', the nice NIML format algopt file would contain something like the next seven lines (again requiring the file name to end in '.niml.opts'): <TRACK_opts Thresh_FA="0.2" Thresh_ANG="60.0" Thresh_Len="20.0" Thresh_Frac="0.001" Nseed_Vox="5" Nmonte="1000" /> Again, those represent the default values, and could be given as a plain column of numbers, in that order. * * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** * ** + DTI LIST FILE EXAMPLE: Consider, for example, if you hadn't used the '-sep_dsets' option when outputting all the tensor information from 3dDWItoDT. Then one could specify the DTI inputs for this program with a file called, e.g., FILE_DTI_IN.niml.opts (the name *must* end with '.niml.opts'): <DTIFILE_opts dti_V1="SINGLEDT+orig[9..11]" dti_V2="SINGLEDT+orig[12..14]" dti_V3="SINGLEDT+orig[15..17]" dti_FA="SINGLEDT+orig[18]" dti_MD="SINGLEDT+orig[19]" dti_L1="SINGLEDT+orig[6]" dti_RD="SINGLEDT+orig[20]" /> This represents the *minimum* set of input files needed when running 3dTrackID. (Oct. 2016: RD now output by 3dDWItoDT, and not calc'ed internally by 3dTrackID.) One could also input extra data: an 'extra file' (XF) to take the place of an FA map for determining where tracks can propagate; and up to four other data sets (P1, P2, P3 and P4, standing for 'plus one' etc.) for calculating mean/stdev properties in the obtained WM-ROIs: <DTIFILE_opts dti_V1="SINGLEDT+orig[9..11]" dti_V2="SINGLEDT+orig[12..14]" dti_V3="SINGLEDT+orig[15..17]" dti_XF="Segmented_WM.nii.gz" dti_FA="SINGLEDT+orig[18]" dti_MD="SINGLEDT+orig[19]" dti_L1="SINGLEDT+orig[6]" dti_RD="SINGLEDT+orig[20]" dti_P1="SINGLEDT+orig[7]" dti_P2="SINGLEDT+orig[8]" dti_P3="T1_map.nii.gz" dti_P4="PD_map.nii.gz" /> **************************************************************************** + EXAMPLES: Here are just a few scenarios-- please see the Demo data set for *maaany* more, as well as for fuller descriptions. To obtain the Demo, type the following into a commandline: $ @Install_FATCAT_demo This will also unzip the archive, which contains required data (so it's pretty big, currently >200MB), a README.txt file, and several premade scripts that are ~heavily commented. A) Deterministic whole-brain tracking; set of targets is just the volume mask. This can be useful for diagnostic purposes, sanity check for gradients+data, for interactively selecting interesting subsets later, etc. This uses most of the default algopts, but sets a higher minimum length for keeping tracks: $ 3dTrackID -mode DET \ -dti_in DTI/DT \ -netrois mask_DWI+orig \ -logic OR \ -alg_Thresh_Len 30 \ -prefix DTI/o.WB B) Mini-probabilistic tracking through a multi-brik network file using a DTI model and AND-logic. Instead of using the thresholded FA map to guide tracking, an extra data set (e.g., a mapped anatomical segmentation image) is input as the WM proxy; as such, what used to be a threshold for adult parenchyma FA is now changed to an appropriate value for the segmentation percentages; and this would most likely also assume that 3dDWUncert had been used to calculate tensor value uncertainties: $ 3dTrackID -mode MINIP \ -dti_in DTI/DT \ -dti_extra T1_WM_in_DWI.nii.gz \ -netrois ROI_ICMAP_GMI+orig \ -logic AND \ -mini_num 7 \ -uncert DTI/o.UNCERT_UNC+orig. \ -alg_Thresh_FA 0.95 \ -prefix DTI/o.MP_AND_WM C) Full probabilistic tracking through a multi-brik network file using HARDI-Qball reconstruction. The designated GFA file is used to guide the tracking, with an appropriate threshold set and a smaller minimum uncertainty of that GFA value (from this and example B, note how generically the '-alg_Thresh_FA' functions, always setting a value for the WM proxy map, whether it be literally FA, GFA or the dti_extra file). Since HARDI-value uncertainty isn't yet calculable in AFNI, brain-wide uniform values were assigned to the GFA and directions: $ 3dTrackID -mode PROB \ -hardi_gfa QBALL/GFA.nii.gz \ -hardi_dirs QBALL/dirs.nii.gz \ -netrois ROI_ICMAP_GMI+orig \ -uncert QBALL/UNIFORM_UNC+orig. \ -mask mask_DWI+orig \ -alg_Thresh_FA 0.04 \ -unc_min_FA 0.003 \ -prefix QBALL/o.PR_QB **************************************************************************** If you use this program, please reference the workhorse FACTID tractography algorithm: Taylor PA, Cho K-H, Lin C-P, Biswal BB (2012). Improving DTI Tractography by including Diagonal Tract Propagation. PLoS ONE 7(9): e43415. and the introductory/description paper for FATCAT: Taylor PA, Saad ZS (2013). FATCAT: (An Efficient) Functional And Tractographic Connectivity Analysis Toolbox. Brain Connectivity.

AFNI program: 3dTRfix
Usage: 3dTRfix [options] This program will read in a dataset that was sampled on an irregular time grid and re-sample it via linear interpolation to a regular time grid. NOTES: ------ The re-sampling will include the effects of slice time offsets (similarly to program 3dTshift), if these time offsets are encoded in the input dataset's header. No other processing is performed -- in particular, there is no allowance (at present) for T1 artifacts resulting from variable TR. If the first 1 or 2 time points are abnormally bright due to the NMR pre-steady-state effect, then their influence might be spread farther into the output dataset by the interpolation process. You can avoid this effect by excising these values from the input using the '[2..$]' notation in the input dataset syntax. If the input dataset is catenated from multiple non-contiguous imaging runs, the program will happily interpolate across the time breaks between the runs. For this reason, you should not give such a file (e.g., from 3dTcat) to this program -- you should use 3dTRfix on each run separately, and only later catenate the runs. The output dataset is stored in float format, regardless of the input format. ** Basically, this program is a hack for the Mad Spaniard. ** When are we going out for tapas y cerveza (sangria es bueno, tambien)? OPTIONS: -------- -input iii = Input dataset 'iii'. [MANDATORY] -TRlist rrr = 1D columnar file of time gaps between sub-bricks in 'iii'; If the input dataset has N time points, this file must have at least N-1 (positive) values. * Please note that these time steps (or the time values in '-TIMElist') should be in seconds, NOT in milliseconds! * AFNI time units are seconds!!! -TIMElist ttt = Alternative to '-TRlist', where you give the N values of the times at each sub-brick; these values must be monotonic increasing and non-negative. * You must give exactly one of '-TIMElist' or '-TRlist'. * The TR value given in the input dataset header is ignored. -prefix ppp = Prefix name for the output dataset. -TRout ddd = 'ddd' gives the value for the output dataset's TR (in sec). If '-TRout' is not given, then the average TR of the input dataset will be used. November 2014 -- Zhark the Fixer

AFNI program: 3dTSgen
++ 3dTSgen: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: B. Douglas Ward This program generates an AFNI 3d+time data set. The time series for each voxel is generated according to a user specified signal + noise model. Usage: 3dTSgen -input fname fname = filename of prototype 3d + time data file [-inTR] set the TR of the created timeseries to be the TR of the prototype dataset [The default is to compute with TR = 1.] [The model functions are called for a ] [time grid of 0, TR, 2*TR, 3*TR, .... ] -signal slabel slabel = name of (non-linear) signal model -noise nlabel nlabel = name of (linear) noise model -sconstr k c d constraints for kth signal parameter: c <= gs[k] <= d -nconstr k c d constraints for kth noise parameter: c+b[k] <= gn[k] <= d+b[k] -sigma s s = std. dev. of additive Gaussian noise [-voxel num] screen output for voxel #num -output fname fname = filename of output 3d + time data file The following commands generate individual AFNI 1 sub-brick datasets: [-scoef k fname] write kth signal parameter gs[k]; output 'fim' is written to prefix filename fname [-ncoef k fname] write kth noise parameter gn[k]; output 'fim' is written to prefix filename fname The following commands generate one AFNI 'bucket' type dataset: [-bucket n prefixname] create one AFNI 'bucket' dataset containing n sub-bricks; n=0 creates default output; output 'bucket' is written to prefixname The mth sub-brick will contain: [-brick m scoef k label] kth signal parameter regression coefficient [-brick m ncoef k label] kth noise parameter regression coefficient ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTshift
Usage: 3dTshift [options] dataset * Shifts voxel time series from the input dataset so that the separate slices are aligned to the same temporal origin. By default, uses the slicewise shifting information in the dataset header (from the 'tpattern' input to program to3d). Method: detrend -> interpolate -> retrend (optionally) * The input dataset can have a sub-brick selector attached, as documented in '3dcalc -help'. * The output dataset time series will be interpolated from the input to the new temporal grid. This may not be the best way to analyze your data, but it can be convenient. * Slices where significant time interpolation happens will have extra temporal autocorrelation introduced by the interpolation. The amount of extra correlation along the time axis depends on the type of interpolation used. Higher order interpolation will produce smaller such 'extra' correlation; in order, from lowest (most extra correlation) to highest (least extra correlation): -linear -cubic -quintic -heptic -wsinc5 -wsinc9 -Fourier * The last two methods do not add much correlation in time. However, they have the widest interpolation 'footprint' and so the output data values will have contributions from data points further away in time. * To properly account for these extra correlations, which vary in space, we advise you to analyze the time series using 3dREMLfit, which uses a voxel-dependent prewhitening (de-correlating) linear regression method, unlike most other FMRI time series regression software. ++ Or else use '-wsinc9' interpolation, which has a footprint of 18 time points: 9 before and 9 after the intermediate time at which the value is output. WARNINGS: -------- * Please recall the phenomenon of 'aliasing': frequencies above 1/(2*TR) can't be properly interpolated. For most 3D FMRI data, this means that cardiac and respiratory effects will not be treated properly by this program. * The images at the beginning of a high-speed FMRI imaging run are usually of a different quality than the later images, due to transient effects before the longitudinal magnetization settles into a steady-state value. These images should not be included in the interpolation! For example, if you wish to exclude the first 4 images, then the input dataset should be specified in the form 'prefix+orig[4..$]'. Alternatively, you can use the '-ignore ii' option. * It seems to be best to use 3dTshift before using 3dvolreg. (But this statement is controversial.) * If the input dataset does not have any slice timing information, and '-tpattern' is not given, then this program just copies the input to the output. [02 Nov 2011 -- formerly, it failed] * Please consider the potential impact of 3dTshift on any subsequent linear regression model. While the temporal resampling of 3dTshift is not exact, it is attempting to interpolate the slice timing so that it is as if each volume were acquired at time 'tzero' + k*TR. So with -tzero 0, it becomes akin to each entire volume being acquired at the very beginning of its TR. By default, the offset is the average offset across the slices, which for alt+z or seq is: (nslices-1)/nslices * TR/2 That average approaches TR/2 as the number of slices increases. The new slice/volume timing is intended to be the real timing from the start of the run. How might this affect stimulus timing in 3dDeconvolve? 3dDeconvolve creates regressors based on volume times of k*TR, matching tzero=0. So an event at run time t=0 would start at the time of volume #0. However using -tzero 1 (or the default, in the case of TR~=2s), an event at run time t=0 would then be 1s *before* the first volume. Note that this matches reality. An event at time t=0 happens before all but the first acquired slice. In particular, a slice acquired at TR offset 1s might be unaffected by 3dTshift. And an event at run time t=0 seems to happen at time t=-1s from the perspective of that slice. To align stimulus times with the applied tzero of 3dTshift, tzero should be subtracted from each stimulus event time (3dDeconvolve effectively subtracts tzero from the EPI timing, so that should be applied to the event times as well). OPTIONS: ------- -verbose = print lots of messages while program runs -TR ddd = use 'ddd' as the TR, rather than the value stored in the dataset header using to3d. You may attach the suffix 's' for seconds, or 'ms' for milliseconds. -tzero zzz = align each slice to time offset 'zzz'; the value of 'zzz' must be between the minimum and maximum slice temporal offsets. N.B.: The default alignment time is the average of the 'tpattern' values (either from the dataset header or from the -tpattern option) -slice nnn = align each slice to the time offset of slice number 'nnn' - only one of the -tzero and -slice options can be used. -prefix ppp = use 'ppp' for the prefix of the output file; the default is 'tshift'. -ignore ii = Ignore the first 'ii' points. (Default is ii=0.) The first ii values will be unchanged in the output (regardless of the -rlt option). They also will not be used in the detrending or time shifting. -rlt = Before shifting, the mean and linear trend -rlt+ = of each time series is removed. The default action is to add these back in after shifting. -rlt means to leave both of these out of the output -rlt+ means to add only the mean back into the output (cf. '3dTcat -help') -no_detrend = Do not remove or restore linear trend. Heptic becomes the default interpolation method. ** Options to choose the temporal interpolation method: ** -Fourier = Use a Fourier method (the default: most accurate; slowest). -linear = Use linear (1st order polynomial) interpolation (least accurate). -cubic = Use the cubic (3rd order) Lagrange polynomial interpolation. -quintic = Use the quintic (5th order) Lagrange polynomial interpolation. -heptic = Use the heptic (7th order) Lagrange polynomial interpolation. -wsinc5 = Use weighted sinc interpolation - plus/minus 5 [Aug 2019]. -wsinc9 = Use weighted sinc interpolation - plus/minus 9. -tpattern ttt = use 'ttt' as the slice time pattern, rather than the pattern in the input dataset header; 'ttt' can have any of the values that would go in the 'tpattern' input to to3d, described below: alt+z = altplus = alternating in the plus direction alt+z2 = alternating, starting at slice #1 instead of #0 alt-z = altminus = alternating in the minus direction alt-z2 = alternating, starting at slice #nz-2 instead of #nz-1 seq+z = seqplus = sequential in the plus direction seq-z = seqminus = sequential in the minus direction @filename = read temporal offsets from 'filename' (the filename time units should match those of the dataset * Originally, times were given in units of ms (with 'ms' being stored as the TR unit in the dataset). Generally, time is now specified in units of s (with that unit store in the dataset). Here the original 'to3d' example has be converted to seconds. For example if nz = 5 and TR = 1.0 (with dataset TR in units of s), then the inter-slice time is taken to be dt = TR/nz = 0.2. In this case, the slices are offset in time by the following amounts: S L I C E N U M B E R tpattern 0 1 2 3 4 Comment --------- --- --- --- --- --- ------------------------------- altplus 0 0.6 0.2 0.8 0.4 Alternating in the +z direction alt+z2 0.4 0 0.6 0.2 0.8 Alternating, but starting at #1 altminus 0.4 0.8 0.2 0.6 0 Alternating in the -z direction alt-z2 0.8 0.2 0.6 0 0.4 Alternating, starting at #nz-2 seqplus 0 0.2 0.4 0.6 0.8 Sequential in the +z direction seqminus 0.8 0.6 0.4 0.2 0 Sequential in the -z direction If @filename is used for tpattern, then nz ASCII-formatted numbers are read from the file. These indicate the time offsets for each slice. For example, if 'filename' contains 0 0.6 0.2 0.8 0.4 then this is equivalent to 'altplus' in the above example. (nz = number of slices in the input dataset) Note that 1D format can be used with @filename. For example, to shift a single voxel time series given TR=2.0, and adjusting the old toffset from 0.5 s to 0 s, consider: 3dTshift -prefix new.1D -TR 2 -tzero 0 -tpattern '@1D: 0.5' old.1D\' For a conceptual test of 3dTshift, consider a sequence of commands: 1deval -num 25 -expr t+10 > t0.1D 3dTshift -linear -no_detrend -TR 1 -tzero 0 -tpattern '@1D: 0.5' \ -prefix t.shift.1D t0.1D\' 1dplot -one t0.1D t.shift.1D Recall from your memorization of the -help that 3dTshift performs the shift on a detrended time series. Hence the '--linear -no_detrend' options are included (otherwise, the line would be unaltered). Also, be aware that since we are asking to interpolate the data so that it is as if it were acquired 0.5 seconds earlier, that is moving the time window to the left, and therefore the plot seems to move to the right. N.B.: if you are using -tpattern, make sure that the units supplied match the units of TR in the dataset header, or provide a new TR using the -TR option. As a test of how well 3dTshift interpolates, you can take a dataset that was created with '-tpattern alt+z', run 3dTshift on it, and then run 3dTshift on the new dataset with '-tpattern alt-z' -- the effect will be to reshift the dataset back to the original time grid. Comparing the original dataset to the shifted-then-reshifted output will show where 3dTshift does a good job and where it does a bad job. ******* Voxel-Wise Shifting -- New Option [Sep 2011] ******* -voxshift fset = Read in dataset 'fset' and use the values in there to shift each input dataset's voxel's time series a different amount. The values in 'fset' are NOT in units of time, but rather are fractions of a TR to shift -- a positive value means to shift backwards. * To compute an fset-style dataset that matches the time pattern of an existing dataset, try set TR = 2.5 3dcalc -a 'dset+orig[0..1]' -datum float -prefix Toff -expr "t/${TR}-l" where you first set the shell variable TR to the true TR of the dataset, then create a dataset Toff+orig with the fractional shift of each slice stored in each voxel. Then the two commands below should give identical outputs: 3dTshift -ignore 2 -tzero 0 -prefix Dold -heptic dset+orig 3dTshift -ignore 2 -voxshift Toff+orig -prefix Dnew -heptic dset+orig Use of '-voxshift' means that options such as '-tzero' and '-tpattern' are ignored -- the burden is on you to encode all the shifts into the 'fset' dataset somehow. (3dcalc can be your friend here.) -- RWCox - 31 October 1999, et cetera INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTsmooth
Usage: 3dTsmooth [options] dataset 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). *** Also see program 3dBandpass *** General Options: -prefix ppp = Sets the prefix of the output dataset to be 'ppp'. [default = 'smooth'] -datum type = Coerce output dataset to be stored as the given type. [default = input data type] Three Point Filtering Options [07 July 1999] -------------------------------------------- The following options define the smoothing filter to be used. All these filters use 3 input points to compute one output point: Let a = input value before the current point b = input value at the current point c = input value after the current point [at the left end, a=b; at the right end, c=b] -lin = 3 point linear filter: 0.15*a + 0.70*b + 0.15*c [This is the default smoother] -med = 3 point median filter: median(a,b,c) -osf = 3 point order statistics filter: 0.15*min(a,b,c) + 0.70*median(a,b,c) + 0.15*max(a,b,c) -3lin m = 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. General Linear Filtering Options [03 Mar 2001] ---------------------------------------------- -hamming N = Use N point Hamming or Blackman windows. -blackman N (N must be odd and bigger than 1.) -custom coeff_filename.1D (odd # of coefficients must be in a single column in ASCII file) (-custom added Jan 2003) WARNING: If you use long filters, you do NOT want to include the large early images in the program. Do something like 3dTsmooth -hamming 13 'fred+orig[4..$]' to eliminate the first 4 images (say). The following options determine how the general filters treat time points before the beginning and after the end: -EXTEND = BEFORE: use the first value; AFTER: use the last value -ZERO = BEFORE and AFTER: use zero -TREND = compute a linear trend, and extrapolate BEFORE and AFTER The default is -EXTEND. These options do NOT affect the operation of the 3 point filters described above, which always use -EXTEND. Adaptive Mean Filtering option [03 Oct 2014] -------------------------------------------- -adaptive N = use adaptive mean filtering of width N (where N must be odd and bigger than 3). * This filter is similar to the 'AdptMean9' 1D filter in the AFNI GUI, except that the end points are treated differently. INPUT DATASET NAMES ------------------- This program accepts datasets that are modified on input according to the following schemes: 'r1+orig[3..5]' {sub-brick selector} 'r1+orig<100..200>' {sub-range selector} 'r1+orig[3..5]<100..200>' {both selectors} '3dcalc( -a r1+orig -b r2+orig -expr 0.5*(a+b) )' {calculation} For the gruesome details, see the output of 'afni -help'. ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTsort
Usage: 3dTsort [options] dataset Sorts each voxel and produces a new dataset. Options: -prefix p = use string 'p' for the prefix of the output dataset [DEFAULT = 'tsort'] -inc = sort into increasing order [default] -dec = sort into decreasing order -rank = output rank instead of sorted values ranks range from 1 to Nvals -ind = output sorting index. (0 to Nvals -1) See example below. -val = output sorted values (default) -random = randomly shuffle (permute) the time points in each voxel * Each voxel is permuted independently! * Why is this here? Someone asked for it :) -ranFFT = randomize each time series by scrambling the FFT phase * Each voxel is treated separately! * Why is this here? cf. Matthew 7:7-8 :) -ranDFT = Almost the same as above, but: * In '-ranFFT', the FFT length is taken to be the next integer >= data length for which the FFT algorithm is efficient. This will result in data padding unless the data length is exactly 'nice' for FFT. * In '-ranDFT', the DFT length is exactly the data length. If the data length is a large-ish prime number (say 997), this operation can be slow. * The DFT/FFT algorithm is reasonably fast when the data length prime factors contain only 2s, 3s, and/or 5s. * Using '-ranDFT' can preserve the spectral (temporal correlation) structure of the original data a little better than '-ranFFT'. * The only reason to use '-ranFFT' instead of '-ranDFT' is for speed. For example, with 997 time points, '-ranFFT' was about 13 times faster (FFT length=1000) than '-ranDFT'. -datum D = Coerce the output data to be stored as the given type D, which may be byte, short, or float (default). Notes: * Each voxel is sorted (or processed) separately. * Sub-brick labels are not rearranged! * This program is useful only in limited cases. It was written to sort the -stim_times_IM beta weights output by 3dDeconvolve. * Also see program 1dTsort, for sorting text files of numbers. Examples: setenv AFNI_1D_TIME YES echo '8 6 3 9 2 7' > test.1D 3dTsort -overwrite test.1D 1dcat tsort.1D 3dTsort -overwrite -rank test.1D 1dcat tsort.1D 3dTsort -overwrite -ind test.1D 1dcat tsort.1D 3dTsort -overwrite -dec test.1D 1dcat tsort.1D ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTsplit4D
USAGE: 3dTsplit4D [options] dataset This program converts a 3D+time dataset into multiple 3D single-brick files. The main purpose of this is to accelerate the process of export AFNI/NIFTI datasets if you have the unfortunate need to work with Some other PrograM that doesn't like datasets in the pseudo-4D nature that AFNI knows and loves. examples: 1. Write the 152 time point dataset, epi_r1+orig, to 152 single volume datasets, out/epi.000+orig ... epi.151+orig. mkdir out 3dTsplit4D -prefix out/epi epi_r1+orig 2. Do the same thing, but write to 152 NIFTI volume datasets, out/epi.000.nii ... out/epi.151.nii. Include .nii in -prefix. mkdir out 3dTsplit4D -prefix out/epi.nii epi_r1+orig 3. Convert an AFNI stats dataset (betas, t-stats, F-stats) into a set of NIFTI volume datasets, including the volume labels in the file names. 3dTsplit4D -prefix stats.FT.nii -label_prefix stats.FT+tlrc -prefix PREFIX : Prefix of the output datasets Numbers will be added after the prefix to denote prior sub-brick. -digits DIGITS : number of digits to use for output filenames -keep_datum : output uses original datum (no conversion to float) -label_prefix : include volume label in each output prefix -bids_deriv : format string for BIDS-Derivative-style naming Authored by: Peter Molfese, UConn ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dTstat
++ 3dTstat: AFNI version=AFNI_25.1.08 (May 6 2025) [64-bit] ++ Authored by: KR Hammett & RW Cox Usage: 3dTstat [options] dataset Computes one or more voxel-wise statistics for a 3D+time dataset and stores them in a bucket dataset. If no statistic option is given, computes just the mean of each voxel time series. Multiple statistics options may be given, and will result in a multi-volume dataset. Statistics Options (note where detrending does/does not occur): -sum = compute sum of input voxels -abssum = compute absolute sum of input voxels -sos = compute sum of squares -l2norm = compute L2 norm (sqrt(sum squares)) -mean = compute mean of input voxels -slope = compute the slope of input voxels vs. time -stdev = compute standard deviation of input voxels NB: input is detrended by first removing mean+slope -stdevNOD = like '-stdev', but no initial detrending -cvar = compute coefficient of variation of input: voxels = stdev/fabs(mean) NB: in stdev calc, input is detrended by removing mean+slope -cvarNOD = like '-cvar', but no initial detrending in stdev calc -cvarinv = 1.0/cvar = 'signal to noise ratio' [for Vinai] NB: in stdev calc, input is detrended by removing mean+slope -cvarinvNOD = like '-cvarinv', but no detrending in stdev calc -tsnr = compute temporal signal to noise ratio fabs(mean)/stdev NOT DETRENDED (same as -cvarinvNOD) -MAD = compute MAD (median absolute deviation) of input voxels = median(|voxel-median(voxel)|) [N.B.: the trend is NOT removed for this] -DW = compute Durbin-Watson Statistic of input voxels [N.B.: the trend IS removed for this] -median = compute median of input voxels [undetrended] -nzmedian = compute median of non-zero input voxels [undetrended] -nzstdev = standard deviation of non-zero input voxel [undetrended] -bmv = compute biweight midvariance of input voxels [undetrended] [actually is 0.989*sqrt(biweight midvariance), to make] [the value comparable to the standard deviation output] -MSSD = Von Neumann's Mean of Successive Squared Differences = average of sum of squares of first time difference -MSSDsqrt = Sqrt(MSSD) -MASDx = Median of absolute values of first time differences times 1.4826 (to scale it like standard deviation) = a robust alternative to MSSDsqrt -min = compute minimum of input voxels [undetrended] -max = compute maximum of input voxels [undetrended] -absmax = compute absolute maximum of input voxels [undetrended] -signed_absmax = (signed) value with absolute maximum [undetrended] -percentile P = the P-th percentile point (0=min, 50=median, 100=max) of the data in each voxel time series. [this option can only be used once!] -argmin = index of minimum of input voxels [undetrended] -argmin1 = index + 1 of minimum of input voxels [undetrended] -argmax = index of maximum of input voxels [undetrended] -argmax1 = index + 1 of maximum of input voxels [undetrended] -argabsmax = index of absolute maximum of input voxels [undetrended] -argabsmax1= index +1 of absolute maximum of input voxels [undetrended] -duration = compute number of points around max above a threshold Use basepercent option to set limits -onset = beginning of duration around max where value exceeds basepercent -offset = end of duration around max where value exceeds basepercent -centroid = compute centroid of data time curves (sum(i*f(i)) / sum(f(i))) -centduration = compute duration using centroid's index as center -nzmean = compute mean of non-zero voxels -zcount = count number of zero values at each voxel -nzcount = count number of non zero values at each voxel -autocorr n = compute autocorrelation function and return first n coefficients -autoreg n = compute autoregression coefficients and return first n coefficients [N.B.: -autocorr 0 and/or -autoreg 0 will return number coefficients equal to the length of the input data] -accumulate = accumulate time series values (partial sums) val[i] = sum old_val[t] over t = 0..i (output length = input length) -centromean = compute mean of middle 50% of voxel values [undetrended] -skewness = measure of asymmetry in distribution - based on Pearson's moment, coefficient of skewness. -kurtosis = measure of the 'tailedness' of the probability distribution - the fourth standardized moment. Never negative. -firstvalue = first value in dataset - typically just placeholder ** If no statistic option is given, then '-mean' is assumed ** Other Options: -tdiff = Means to take the first difference of each time series before further processing. -prefix p = Use string 'p' for the prefix of the output dataset [DEFAULT = 'stat'] -datum d = use data type 'd' for the type of storage of the output, where 'd' is one of 'byte', 'short', or 'float' [DEFAULT=float] -nscale = Do not scale output values when datum is byte or short. Scaling is done by default. -basepercent nn = Percentage of maximum for duration calculation -mask mset Means to use the dataset 'mset' as a mask: Only voxels with nonzero values in 'mset' will be printed from 'dataset'. Note that the mask dataset and the input dataset must have the same number of voxels. -mrange a b Means to further restrict the voxels from 'mset' so that only those mask values between 'a' and 'b' (inclusive) will be used. If this option is not given, all nonzero values from 'mset' are used. Note that if a voxel is zero in 'mset', then it won't be included, even if a < 0 < b. -cmask 'opts' Means to execute the options enclosed in single quotes as a 3dcalc-like program, and produce produce a mask from the resulting 3D brick. Examples: -cmask '-a fred+orig[7] -b zork+orig[3] -expr step(a-b)' produces a mask that is nonzero only where the 7th sub-brick of fred+orig is larger than the 3rd sub-brick of zork+orig. -cmask '-a fred+orig -expr 1-bool(k-7)' produces a mask that is nonzero only in the 7th slice (k=7); combined with -mask, you could use this to extract just selected voxels from particular slice(s). Notes: * You can use both -mask and -cmask in the same run - in this case, only voxels present in both masks will be dumped. * Only single sub-brick calculations can be used in the 3dcalc-like calculations - if you input a multi-brick dataset here, without using a sub-brick index, then only its 0th sub-brick will be used. * Do not use quotes inside the 'opts' string! If you want statistics on a detrended dataset and the option doesn't allow that, you can use program 3dDetrend first. The output is a bucket dataset. The input dataset may use a sub-brick selection list, as in program 3dcalc. *** If you are trying to compute the mean or std.dev. of multiple datasets (not across time), use 3dMean or 3dmerge instead. ----------------- Processing 1D files with 3dTstat ----------------- To analyze a 1D file and get statistics on each of its columns, you can do something like this: 3dTstat -stdev -bmv -prefix stdout: file.1D\' where the \' means to transpose the file on input, since 1D files read into 3dXXX programs are interpreted as having the time direction along the rows rather than down the columns. In this example, the output is written to the screen, which could be captured with '>' redirection. Note that if you don't give the '-prefix stdout:' option, then the output will be written into a NIML-formatted 1D dataset, which you might find slightly confusing (but still usable). ++ Compile date = May 6 2025 {AFNI_25.1.08:linux_ubuntu_24_64}

AFNI program: 3dttest++
Gosset (Student) t-test of sets of 3D datasets. ~1~ [* Also consider program 3dMEMA, which can carry out a *] [* more sophisticated type of 't-test' that also takes *] [* into account the variance map of each input dataset. *] [* When constructing 3dttest++ commands consider using *] [* gen_group_command.py to build your command FOR you, *] [* which can simplify the syntax/process. *] * Usage can be similar (not identical) to the old 3dttest; for example [SHORT form of dataset input]: 3dttest++ -setA a+tlrc'[3]' b+tlrc'[3]' ... * OR, usage can be similar to 3dMEMA; for example [LONG form]: 3dttest++ -setA Green sub001 a+tlrc'[3]' \ sub002 b+tlrc'[3]' \ sub003 c+tlrc'[3]' \ ... \ -covariates Cfile * Please note that in the second ('LONG') form of the '-setA' option, the first value after '-setA' is a label for the set (here, 'Green'). ++ After that, pairs of values are given; in each pair, the first entry is a label for the dataset that is the second entry. ++ This dataset label is used as a key into the covariates file. ++ If you want to have a label for the set, but do not wish (or need) to have a label for each dataset in the set, then you can use the SHORT form (first example above), and then provide the overall label for the set with the '-labelA' option. ++ The set label is used to create sub-brick labels in the output dataset, to make it simpler for a user to select volumes for display in the AFNI GUI. Example: -labelA Nor -label Pat then the difference between the setA and setB means will get the label 'Nor-Pat_mean', and the corresponding t-statistic will get the label 'Nor-Pat_Tstat'. ++ See the section 'STRUCTURE OF THE OUTPUT DATASET' (far below) for more information on how the results are formatted. ** NOTES on the labels above: ++ The '-setX' label (above: 'Green') will be limited to 12 characters -- this label is used in the sub-brick labels in the output files, which are shown in the AFNI GUI 'Define Overlay' buttons for choosing the volumes (sub-bricks) you want to look at. ++ However, the dataset labels (above: 'sub001', etc) are only limited to 256 characters. These labels are used to pick values out of the covariates table. ++ In the 'LONG' form input illustrated above, the set label and the dataset labels are given explicitly. ++ In the 'SHORT' form input, the set label must be given separately, using option '-labelA' and/or '-labelB'. The dataset labels are taken from the dataset input filenames -- to be precise, the 'prefix' part of the filename, as in: 'Ethel/Fred.nii' -> 'Fred' and 'Lucy/Ricky+tlrc.HEAD' -> 'Lucy' If you are using covariates and are using the 'SHORT' form of input (the most common usage), the prefixes of the dataset filename must be unique within their first 256 characters, or trouble will happen. ++ I added this note [15 Dec 2021] because failing to distinguish between these labels and their limits was causing some confusion and angst. * You can input 1 or 2 sets of data (labeled 'A' and 'B' by default). * With 1 set ('-setA'), the mean across input datasets (usually subjects) is tested against 0. * With 2 sets, the difference in means across each set is tested against 0. The 1 sample results for each set are also provided, since these are often of interest to the investigator (e.g., YOU). ++ With 2 sets, the default is to produce the difference as setA - setB. ++ You can use the option '-BminusA' to get the signs reversed. * Covariates can be per-dataset (input=1 number) and/or per-voxel/per-dataset (input=1 dataset sub-brick). ++ Note that voxel-level covariates will slow the program down, since the regression matrix for the covariates must be re-inverted for each voxel separately. For most purposes, the program is so fast that this slower operation won't be important. * The new-ish options '-Clustsim' and '-ETAC' will use randomization and permutation simulation to produce cluster-level threshold values that can be used to control the false positive rate (FPR) globally. These options are slow, since they will run 1000s of simulated 3D t-tests in order to get cluster-level statistics about the 1 actual test. * You can input plain text files of numbers, provided their filenames end in the AFNI standard '.1D'. If you have two columns of numbers in files AA.1D and BB.1D, you could test their means for equality with a command like 3dttest++ -prefix stdout: -no1sam setA AA.1D\' -setB BB.1D\' Here, the \' at the end of the filename tells the program to transpose the column files to row files, since AFNI treats a single row of numbers as the multiple values for a single 'voxel'. The output (on stdout) from such a command will be one row of numbers: the first value is the difference in the means between the 2 samples, and the second value is the t-statistic for this difference. (There will also be a bunch of text on stderr, with various messages.) * This program is meant (for most uses) to replace the original 3dttest, which was written in 1994, "When grass was green and grain was yellow". ++ And when the program's author still had hair on the top of his head /:( ------------------ SET INPUT OPTIONS ~1~ ------------------ * At least the '-setA' option must be given. * '-setB' is optional, and if it isn't used, then the mean of the dataset values from '-setA' is t-tested against 0 (1 sample t-test). * Two forms for the '-setX' (X='A' or 'B') options are allowed. The first (short) form is similar to the original 3dttest program, where the option is just followed by a list of datasets to use. * The second (long) form is similar to the 3dMEMA program, where you specify a distinct label for each input dataset sub-brick (a difference between this option and the version in 3dMEMA is only that you do not give a second dataset ('T_DSET') with each sample in this program). ***** SHORT FORM ***** -setA BETA_DSET BETA_DSET ... [-setB] * In this form of input, you specify the datasets for each set directly following the '-setX' option. ++ Unlike 3dttest, you can specify multiple sub-bricks in a dataset: -setA a+tlrc'[1..13(2)]' which inputs 7 sub-bricks at once (1,3,5,7,9,11,13). *** See the '-brickwise' option (far below) for more information *** *** on how multiple sub-brick datasets will be processed herein. *** ++ If multiple sub-bricks are input from a single dataset, then covariates cannot be used (sorry, Charlie). ++ In the short form input, the 'prefix' for each dataset is its label if '-covariates' is used. The prefix is the dataset file name with any leading directory name removed, and everything at and after '+' or '.nii' cut off: Zork/Fred.nii -> Fred *OR* Zork/Fred+tlrc.HEAD -> Fred ++ In the long form input (described below), you provide each dataset with a label on the command line directly. ++ For some limited compatibility with 3dttest, you can use '-set2' in place of '-setA', and '-set1' in place of '-setB'. ++ [19 Jun 2012, from Beijing Normal University, during AFNI Bootcamp] For the SHORT FORM only, you can use the wildcards '*' and/or '?' in the BETA_DSET filenames, along with sub-brick selectors, to make it easier to create the command line. To protect the wildcards from the shell, the entire filename should be inside single ' or double " quote marks. For example: 3dttest++ -setA '*.beta+tlrc.HEAD[Vrel#0_Coef]' \ -setB '*.beta+tlrc.HEAD[Arel#0_Coef]' -prefix VAtest -paired will do a paired 2-sample test between the symbolically selected sub-bricks from a collection of single-subject datasets (here, 2 different tasks). ***** LONG FORM ***** -setA SETNAME \ [-setB] LABL_1 BETA_DSET \ LABL_2 BETA_DSET \ ... ... \ LABL_N BETA_DSET * In this form of input, you specify an overall name for the set of datasets, and a label to be associated with each separate input dataset. (This label is used with the '-covariates' option, described later.) SETNAME is the name assigned to the set (used in the output labels). LABL_K is the label for the Kth input dataset name, whose name follows. BETA_DSET is the name of the dataset of the beta coefficient or GLT. ++ only 1 sub-brick can be specified here! ** Note that the label 'SETNAME' is limited to 12 characters, and the dataset labels 'LABL_K' are limited to 256 characters. -- Any more will be thrown away without warning. -- This limit also applies to the dataset labels taken from the dataset filenames in the short form input. ** Only the first 12 characters of the covariate labels can be used in the sub-brick labels, due to limitations in the AFNI dataset structure and AFNI GUI. Any covariate labels longer than this will be truncated when put into the output dataset :( ** The program determines if you are using the short form or long ** ** form to specify the input datasets based on the first argument ** ** after the '-setX' option. If this argument can be opened as a ** ** dataset, the short form is used. If instead, the next argument ** ** cannot be opened as a dataset, then the long form is assumed. ** -labelA SETNAME = for the short form of '-setX', this option allows you [-labelB] to attach a label to the set, which will be used in the sub-brick labels in the output dataset. If you don't give a SETNAME, then '-setA' will be named 'SetA', etc. ***** NOTE WELL: The sign of a two sample test is A - B. ***** *** Thus, '-setB' corresponds to '-set1' in 3dttest, *** *** and '-setA' corresponds to '-set2' in 3dttest. *** ***** This ordering of A and B matches 3dGroupInCorr. ***** *****-------------------------------------------------------------***** ***** ALSO NOTE: You can reverse this sign by using the option ***** *** '-BminusA', in which case the test is B - A. *** *** The option '-AminusB' can be used to explicitly *** ***** specify the standard subtraction order. ***** ------------ Dataset (e.g., Subject) level weights [Mar 2020] ------------ These options let you mark some datasets (that is, some subjects) as weighing more in the analysis. A larger weight means a subject's data will count more in the analysis. -setweightA wname = Name of a file with the weights for the -setA *and/or* datasets. This is a .1D (numbers as text) file -setweightB that should have 1 positive value for each volume being processed. * A larger weight value means the voxel values for that volume counts more in the test. * In the least squares world, these weights would typically be the reciprocal of that subject's (or volume's) standard deviation -- in other words, a measure of the perceived reliability of the data in that volume. * For -setweightA, there should be the same number of weight values in the 'wname' file as there are volumes in -setA. ++ Fewer weight values cause a fatal ERROR. ++ Extra weight values will print a WARNING message and then be ignored. ++ Non-positive weight values cause a fatal ERROR. * You can provide the weights directly on the the command line with an option of the form -setweightA '1D: 3 2 1 4 1 2' when -setA has 6 input volumes. * You can use -covariates and -setweight together. --LIMITATIONS-- ** At this time, there is no way to set voxel-wise weights. ** -setweight will turn off -unpooled (if it was used). ** -paired will turn off -setweightB (if used), since a paired t-test requires equal weights (and equal covariates) in both samples. ** -singletonA will turn off -setweightA. ** Using -setweight with -rankize is not allowed. Implementation of weights is by use of the regression method used for implementing covariates. For convenience in the program, the provided weights are normalized to average 1, separately for -setA and -setB (if present). This means that the total weight actually used for each set is the number of volumes present in that set. The t-statistic for setA-setB is testing whether the weighted means of the two samples are equal. Similar remarks apply to the individual sample means (e.g., weighted mean of setA tested versus 0). Dataset weights are conceptually different than dataset covariates: * Weights measure the reliability of the input dataset values - larger weight for a dataset means its values are more reliable. * Covariates are measures that might directly affect the input dataset values. In a different language, weights are about the variance of the input dataset values, whereas covariates are about the size of the input dataset values. As with covariates, where you get the weights from is your business. Be careful out there, and don't go crazy. --------------------------------------------------------------- TESTING A SINGLE DATASET VERSUS THE MEAN OF A GROUP OF DATASETS ~1~ --------------------------------------------------------------- This new [Mar 2015] option allows you to test a single value versus a group of datasets. To do this, replace the '-setA' option with the '-singletonA' option described below, and input '-setB' normally (that is, '-setB' must have more than 1 dataset). The '-singletonA' option comes in 3 different forms: -singletonA dataset_A *OR* -singletonA LABL_A dataset_A *OR* -singletonA FIXED_NUMBER * In the first form, just give the 1 sub-brick dataset name after the option. * In the second form, you can provide a dataset 'label' to be used for covariates extraction. As in the case of the long forms for '-setA' and '-setB', the 'LABL_A' argument cannot be the name of an existing dataset; otherwise, the program will assume you are using the first form. * In the third form, instead of giving a dataset, you give a fixed number (e.g., '0.5'), to test the -setB collection against this 1 number. ++ In this form, '-singleton_variance_ratio' is set to a very small number, since you presumably aren't testing against an instance of a random variable. ++ Also, '-BminusA' is turned on when FIXED_NUMBER is used, to give the effect of a 1-sample test against a constant. For example, -singletonA 0.0 -set B x y z is equivalent to the 1-sample test with '-setA x y z'. The only advantage of using '-singletonA FIXED_NUMBER' is that you can test against a nonzero constant this way. ++ You cannot use covariates with this FIXED_NUMBER form of '-singletonA' /:( * The output dataset will have 2 sub-bricks: ++ The difference (at each voxel) between the dataset_A value and the mean of the setB dataset values. ++ (In the form where 'dataset_A' is replaced by a fixed) (number, the output is instead the difference between) (the mean of the setB values and the fixed number. ) ++ The t-statistic corresponding to this difference. * If covariates are used, at each voxel the slopes of the setB data values with respect to the covariates are estimated (as usual). ++ These slopes are then used to project the covariates out of the mean of the setB values, and are also applied similarly to the single value from the singleton dataset_A (using its respective covariate value). ++ That is, the covariate slopes from setB are applied to the covariate values for dataset_A in order to subtract the covariate effects from dataset_A, as well as from the setB mean. ++ Since it impossible to independently estimate the covariate slopes for dataset_A, this procedure seems (to me) like the only reasonable way to use covariates with a singleton dataset. * The t-statistic is computed assuming that the variance of dataset_A is the same as the variance of the setB datasets. ++ Of course, it is impossible to estimate the variance of dataset_A at each voxel from its single number! ++ In this way, the t-statistic differs from testing the setB mean against a (voxel-dependent) constant, which would not have any variance. ++ In particular, the t-statistic will be smaller than in the more usual 'test-against-constant' case, since the test here allows for the variance of the dataset_A value. ++ As a special case, you can use the option -singleton_variance_ratio RRR to set the (assumed) variance of dataset_A to be RRR times the variance of set B. Here, 'RRR' must be a positive number -- it cannot be zero, so if you really want to test against a voxel-wise constant, use something like 0.000001 for RRR (this is the setting automatically made when 'dataset_A' is replaced by a fixed number, in the third form above). * Statistical inference on a single sample (dataset_A values) isn't really possible. The purpose of '-singletonA' is to give you some guidance when a voxel value in dataset_A is markedly different from the distribution of values in setB. ++ However, a statistician would caution you that when an elephant walks into the room, it might be a 500,000 standard deviation mouse, so you can't validly conclude it is a different species until you get some more data. * At present, '-singletonA' cannot be used with '-brickwise'. ++ Various other options don't make sense with '-singletonA', including '-paired' and '-center SAME'. * Note that there is no '-singletonB' option -- the only reason this is labeled as '-singletonA' is to remind the user (you) that this option replaces the '-setA' option. -------------------------------------- COVARIATES - per dataset and per voxel ~1~ -------------------------------------- -covariates COVAR_FILE * COVAR_FILE is the name of a text file with a table for the covariate(s). Each column in the file is treated as a separate covariate, and each row contains the values of these covariates for one sample (dataset). Note that you can use '-covariates' only ONCE -- the COVAR_FILE should contain the covariates for ALL input samples from both sets. * Rows in COVAR_FILE whose first column don't match a dataset label are ignored (silently). ++ This feature allows you to analyze subsets of data collections while using the covariates file for a large group of subjects -- some of whom might not be in a given subset analysis. * An input dataset label that doesn't match a row in COVAR_FILE, on the other hand, is a fatal error. ++ The program doesn't know how to get the covariate values for such a dataset, so it can't continue. * There is no provision for missing values -- the entire table must be filled! * The format of COVAR_FILE is similar to the format used in 3dMEMA and 3dGroupInCorr (generalized to allow for voxel-wise covariates): FIRST LINE --> subject IQ age GMfrac LATER LINES --> Elvis 143 42 Elvis_GM+tlrc[8] Fred 85 59 Fred_GM+tlrc[8] Ethel 109 49 Ethel_GM+tlrc[8] Lucy 133 32 Lucy_GM+tlrc[8] Ricky 121 37 Ricky_GM+tlrc[8] * The first line of COVAR_FILE contains column headers. The header label for the first column (#0) isn't used for anything. The later header labels are used in the sub-brick labels stored in the output dataset. * The first column contains the dataset labels that must match the dataset LABL_K labels given in the '-setX' option(s). * If you used a short form '-setX' option, each dataset label is the dataset's prefix name (truncated to 12 characters). ++ e.g., Klaatu+tlrc'[3]' ==> Klaatu ++ e.g., Elvis.nii.gz ==> Elvis * '-covariates' can only be used with the short form '-setX' option when each input dataset has only 1 sub-brick (so that each label refers to exactly 1 volume of data). ++ Duplicate labels in the dataset list or in the covariates file will not work well! * The later columns in COVAR_FILE contain numbers (e.g., 'IQ' and 'age', above), OR dataset names. In the latter case, you are specifying a voxel-wise covariate (e.g., 'GMfrac'). ++ Do NOT put the dataset names or labels in this file in quotes. * A column can contain numbers only, OR datasets names only. But one column CANNOT contain a mix of numbers and dataset names! ++ In the second line of the file (after the header line), a column entry that is purely numeric indicates that column will be all numbers. ++ A column entry that is not numeric indicates that column will be dataset names. ++ You are not required to make the columns and rows line up neatly, (separating entries in the same row with 1 or more blanks is OK), but your life will be much nicer if you DO make them well organized. * You cannot enter covariates as pure labels (e.g., 'Male' and 'Female'). To assign such categorical covariates, you must use numeric values. A column in the covariates file that contains strings rather than numbers is assumed to be a list of dataset names, not category labels! * If you want to omit some columns in COVAR_FILE from the analysis, you can do so with the standard AFNI column selector '[...]'. However, you MUST include column #0 first (the dataset labels) and at least one more column. For example: -covariates Cov.table'[0,2..4]' to skip column #1 but keep columns #2, #3, and #4. * Only the -paired and -pooled options can be used with covariates. ++ If you use -unpooled, it will be changed to -pooled. ++ The same limitation on -unpooled applies to -setweight. * If you use -paired, then the covariate values for setB will be the same as those for setA, even if the dataset labels are different! ++ If you want to use different covariates for setA and setB in the paired test, then you'll have to subtract the setA and setB datasets (with 3dcalc), and then do a 1-sample test, using the differences of the original covariates as the covariates for this 1-sample test. ++ This subtraction technique works because a paired t-test is really the same as subtracting the paired samples and then doing a 1-sample t-test on these differences. ++ For example, you do FMRI scans on a group of subjects, then train them on some task for a week, then re-scan them, and you want to use their behavioral scores on the task, pre- and post-training, as the covariates. * See the section 'STRUCTURE OF THE OUTPUT DATASET' for details of what is calculated and stored by 3dttest++. * If you are having trouble getting the program to read your covariates table file, then set the environment variable AFNI_DEBUG_TABLE to YES and run the program. A lot of progress reports will be printed out, which may help pinpoint the problem; for example: 3dttest++ -DAFNI_DEBUG_TABLE=YES -covariates cfile.txt |& more * A maximum of 31 covariates are allowed. If you have more, then seriously consider the likelihood that you are completely deranged. * N.B.: The simpler forms of the COVAR_FILE that 3dMEMA allows are NOT supported here! Only the format described above will work. * N.B.: IF you are entering multiple sub-bricks from the same dataset in one of the '-setX' options, AND you are using covariates, then you must use the 'LONG FORM' of input for the '-setX' option, and give each sub-brick a distinct label that matches something in the covariates file. Otherwise, the program will not know which covariate to use with which input sub-brick, and bad things will happen. * N.B.: Please be careful in setting up the covariates file and dataset labels, as the program only does some simple error checking. ++ If you REALLY want to see the regression matrices used with covariates, use the '-debug' option. ++ Which you give you a LOT of output (to stderr), so redirect: 3dttest++ .... |& tee debug.out ***** CENTERING (this subject is very important -- read and think!) ******* ++ This term refers to how the mean across subjects of a covariate will be processed. There are 3 possibilities: -center NONE = Do not remove the mean of any covariate. -center DIFF = Each set will have the means removed separately. -center SAME = The means across both sets will be computed and removed. (This option only applies to a 2-sample test, obviously.) ++ These operations (DIFF or SAME) can be altered slightly by the following: -cmeth MEAN = When centering, subtract the mean. -cmeth MEDIAN = When centering, subtract the median. (Per the request of the Musical Neuroscientist, AKA Steve Gotts.) ++ If you use a voxel-wise (dataset) covariate, then the centering method is applied to each voxel's collection of covariate values separately. ++ The default operation is '-center DIFF'. ++ '-center NONE' is for the case where you have pre-processed the covariate values to meet your needs; otherwise, it is not recommended! ++ Centering can be important. For example, suppose that the mean IQ in setA is significantly higher than in setB, and that the beta values are positively correlated with IQ IN THE SAME WAY IN THE TWO GROUPS. Then the mean beta value in setA will be higher than in setB simply from the IQ effect. -- To attempt to allow for this type of inter-group mean differences, in order to detect other difference between the two groups (e.g., from disease status), you would have to center the two groups together, rather than separately (i.e., use '-center SAME'). -- However, if the beta values are correlated significantly differently with IQ in the two groups, then '-center DIFF' would perhaps be a better choice. Please read on: ++ How to choose between '-center SAME' or '-center DIFF'? You have to understand what your model is and what effect the covariates are likely to have on the data. You shouldn't just blindly use covariates 'just in case'. That way lies statistical madness. -- If the two samples don't differ much in the mean values of their covariates, then the results with '-center SAME' and '-center DIFF' should be nearly the same. -- For fixed covariates (not those taken from datasets), the program prints out the results of a t-test of the between-group mean covariate values. This test is purely informative; no action is taken if the t-test shows that the two groups are significantly different in some covariate. -- If the two samples DO differ much in the mean values of their covariates, then you should read the next point VERY CAREFULLY. ++ The principal purpose of including covariates in an analysis (ANCOVA) is to reduce the variance of the beta values due to extraneous causes. Some investigators also wish to use covariates to 'factor out' significant differences between groups. However, there are those who argue (convincingly) that if your two groups differ markedly in their mean covariate values, then there is NO statistical test that can tell if their mean beta values (dependent variable) would be the same or different if their covariate values were all the same instead: Miller GM and Chapman JP. Misunderstanding analysis of covariance. J Abnormal Psych 110: 40-48 (2001). http://dx.doi.org/10.1037/0021-843X.110.1.40 http://psycnet.apa.org/journals/abn/110/1/40.pdf -- For example, if all your control subjects have high IQs and all your patient subjects have normal IQs, group differences in activation can be due to either cause (IQ or disease status) and you can't turn the results from a set of high IQ controls into the results you would have gotten from a set of normal IQ controls (so you can compare them to the patients) just by linear regression and then pretending the IQ issue goes away. -- The decision as to whether a mean covariate difference between groups makes the t-test of the mean beta difference invalid or valid isn't purely a statistical question; it's also a question of interpretation of the scientific issues of the study. See the Miller & Chapman paper (above) for a lengthy discussion of this issue. -- It is not clear how much difference in covariate levels is acceptable. You could carry out a t-test on the covariate values between the 2 groups and if the difference in means is not significant at some level (i.e., if p > 0.05?), then accept the two groups as being 'identical' in that variable. But this is just a suggestion. (In fact, the program now carries out this t-test for you; cf supra.) -- Thanks to Andy Mayer for pointing out this article to me. ++ At this time, there is no option to force the SLOPES of the regression vs. covariate values to be the same in the two-sample analysis. [Adding this feature would be too much like work.] ------------- OTHER OPTIONS ~1~ ------------- -paired = Specifies the use of a paired-sample t-test to compare setA and setB. If this option is used, setA and setB must have the same cardinality (duh). ++ Recall that if '-paired' is used with '-covariates', the covariates for setB will be the same as for setA. ++ If you don't understand the difference between a paired and unpaired t-test, I'm not going to teach you in this help file. But please consult someone or you will undoubtedly come to grief! -unpooled = Specifies that the variance estimates for setA and setB be computed separately (not pooled together). ++ This only makes sense if -paired is NOT given. ++ '-unpooled' cannot be used with '-covariates'. ++ Unpooled variance estimates are supposed to provide some protection against heteroscedasticty (significantly different inter-subject variance between the two different collections of datasets). ++ Our experience is that for most FMRI data, using '-unpooled' is not needed; the option is here for those who like to experiment or who are very cautious. -toz = Convert output t-statistics to z-scores ++ -unpooled implies -toz, since t-statistics won't be comparable between voxels as the number of degrees of freedom will vary between voxels. -->>++ -toz is automatically turned on with the -Clustsim option. The reason for this is that -Clustsim (and -ETAC) work by specifying voxel-wise thresholds via p-values -- z-statistics are simpler to compute in the external clustering programs (3dClustSim and 3dXClustSim) than t-statistics, since converting a z=N(0,1) value to a p-value doesn't require knowing any extra parameters (such as the t DOF). -- In other words, I did this to make my life simpler. ++ If for some bizarre reason you want to convert a z-statistic to a t-statistic, you can use 3dcalc with a clumsy expression of the form 'cdf2stat(stat2cdf(x,5,0,0,0),3,DOF,0,0)' where 'DOF' is replaced with the number of degrees of freedom. The following command will show the effect of such a conversion: 1deval -xzero -4 -del 0.01 -num 801 \ -expr 'cdf2stat(stat2cdf(x,5,0,0,0),3,10,0,0)' | \ 1dplot -xzero -4 -del 0.01 -stdin -xlabel z -ylabel 't(10)' -zskip [n]= Do not include voxel values that are zero in the analysis. ++ This option can be used when not all subjects' datasets overlap perfectly. ++ -zskip implies -toz, since the number of samples per voxel will now vary, so the number of degrees of freedom will be spatially variable. ++ If you follow '-zskip' with a positive integer (> 1), then that is the minimum number of nonzero values (in each of setA and setB, separately) that must be present before the t-test is carried out. If you don't give this value, but DO use '-zskip', then its default is 5 (for no good reason). ++ At this time, you can't use -zskip with -covariates, because that would require more extensive re-thinking and then serious re-programming. ++ You CAN use -zskip with -paired, but it works slightly differently than with a non-paired test [06 May 2021]: -- In a non-paired test, setA and setB are pruned of zero values separately; e.g., setA could lose 3 values at a given voxel, while setB loses 5 there. -- In a paired test, if EITHER setA or setB has a zero value at a given voxel, both paired values are discarded. This choice is necessary, since a paired t-test requires subtracting the setA/setB values pairwise and if one element of a pair is invalid, then the other element has nothing to be paired with. ++ You can also put a decimal fraction between 0 and 1 in place of 'n' (e.g., '0.9', or '90%'). Such a value indicates that at least 90% (e.g.) of the values in each set must be nonzero for the t-test to proceed. [08 Nov 2010] -- In no case will the number of values tested fall below 3! -- You can use '100%' for 'n', to indicate that all data values must be nonzero for the test to proceed. -rankize = Convert the data (and covariates, if any) into ranks before doing the 2-sample analyses. This option is intended to make the statistics more 'robust', and is inspired by the paper WJ Conover and RL Iman. Analysis of Covariance Using the Rank Transformation, Biometrics 38: 715-724 (1982). http://www.jstor.org/stable/2530051 Also see http://www.jstor.org/stable/2683975 ++ Using '-rankize' also implies '-no1sam' (infra), since it doesn't make sense to do 1-sample t-tests on ranks. ++ Don't use this option unless you understand what it does! The use of ranks herein should be considered very experimental or speculative!! -no1sam = When you input two samples (setA and setB), normally the program outputs the 1-sample test results for each set (comparing to zero), as well as the 2-sample test results for differences between the sets. With '-no1sam', these 1-sample test results will NOT be calculated or saved. -nomeans = You can also turn off output of the 'mean' sub-bricks, OR -notests = of the 'test' sub-bricks if you want, to reduce the size of the output dataset. For example, '-nomeans -no1sam' will result in only getting the t-statistics for the 2-sample tests. These options are intended for use with '-brickwise', where the amount of output sub-bricks can become overwhelming. ++ You CANNOT use both '-nomeans' and '-notests', because then you would be asking for no outputs at all! -nocov = Do not output the '-covariates' results. This option is intended only for internal testing, and it's hard to see why the ordinary user would want it. -mask mmm = Only compute results for voxels in the specified mask. ++ Voxels not in the mask will be set to 0 in the output. ++ If '-mask' is not used, all voxels will be tested. -->>++ It is VERY important to use '-mask' when you use '-ClustSim' or '-ETAC' to computed cluster-level thresholds. ++ NOTE: voxels whose input data is constant (in either set) will NOT be processed and will get all zero outputs. This inaction happens because the variance of a constant set of data is zero, and division by zero is forbidden by the Deities of Mathematics -- cf., http://www.math.ucla.edu/~tao/ -exblur b = Before doing the t-test, apply some extra blurring to the input datasets; parameter 'b' is the Gaussian FWHM of the smoothing kernel (in mm). ++ This option is how '-ETAC_blur' is implemented, so it isn't usually needed by itself. ++ The blurring is done inside the mask; that is, voxels outside the mask won't be used in the blurring process. Such blurring is done the same way as in program 3dBlurInMask (using a finite difference evolution with Neumann boundary conditions). ++ Gaussian blurring is NOT additive in the FWHM parameter. If the inputs to 3dttest++ were blurred by FWHM=4 mm (e.g., via afni_proc.py), then giving an extra blur of FWHM=6 mm is more-or-less equivalent to applying a single blur of sqrt(4*4+6*6)=7.2 mm, NOT to 4+6=10 mm! ++ '-exblur' does not work with '-brickwise'. ++ '-exblur' only works with 3D datasets. ++ If any covariates are datasets, you should be aware that the covariate datasets are NOT blurred by the '-exblur' process. -brickwise = This option alters the way this program works with input datasets that have multiple sub-bricks (cf. the SHORT FORM). ++ If you use this option, it must appear BEFORE either '-set' option (so the program knows how to do the bookkeeping for the input datasets). ++ WITHOUT '-brickwise', all the input sub-bricks from all datasets in '-setA' are gathered together to form the setA sample (similarly for setB, of course). In this case, there is no requirement that all input datasets have the same number of sub-bricks. ++ WITH '-brickwise', all input datasets (in both sets) MUST have the same number of sub-bricks. The t-tests are then carried out sub-brick by sub-brick; that is, if you input a collection of datasets with 10 sub-bricks in each dataset, then you will get 10 t-test results. ++ Each t-test result will be made up of more than 1 sub-brick in the output dataset. If you are doing a 2-sample test, you might want to use '-no1sam' to reduce the number of volumes in the output dataset. In addition, if you are only interested in the statistical tests and not the means (or slopes for covariates), then the option '-nomeans' will reduce the dataset to just the t (or z) statistics -- e.g., the combination '-no1sam -nomeans' will give you one statistical sub-brick per input sub-brick. ++ If you input a LOT of sub-bricks, you might want to set environment variable AFNI_AUTOMATIC_FDR to NO, in order to suppress the automatic calculation of FDR curves for each t-statistic sub-brick -- this FDR calculation can be time consuming when done en masse. -->>++ The intended application of this option is to make it easy to take a collection of time-dependent datasets (e.g., from MEG or from moving-window RS-FMRI analyses), and get time-dependent t-test results. It is possible to do the same thing with a scripted loop, but that way is painful. ++ You CAN use '-covariates' with '-brickwise'. You should note that each t-test will reuse the same covariates -- that is, there is no provision for time-dependent covariate values -- for that, you'd have to use scripting to run 3dttest++ multiple times. ++ EXAMPLE: Each input dataset (meg*.nii) has 100 time points; the 'X' datasets are for one test condition and the 'Y' datasets are for another. In this example, the subjects are the same in both conditions, so the '-paired' option makes sense. 3dttest++ -brickwise -prefix megXY.nii -no1sam -paired\ -setA meg01X.nii meg02X.nii meg03X.nii ... \ -setB meg01Y.nii meg02Y.nii meg03Y.nii ... * The output dataset will have 200 sub-bricks: 100 differences of the means between 'X' and 'Y', and 100 t-statistics. * You could extract the output dataset t-statistics (say) into a single dataset with a command like 3dTcat -prefix megXY_tstat.nii megXY.nii'[1..$(2)]' (Or you could have used the '-nomeans' option.) This dataset could then be used to plot the t-statistic versus time, make a movie, or otherwise do lots of fun things. * If '-brickwise' were NOT used, the output dataset would just get 2 sub-bricks, as all the inputs in setA would be lumped together into one super-sized sample (and similarly for setB). * Remember that with the SHORT FORM input (needed for option '-brickwise') you can use wildcards '*' and '?' together with '[...]' sub-brick selectors. -prefix p = Gives the name of the output dataset file. ++ For surface-based datasets, use something like: -prefix p.niml.dset or -prefix p.gii.dset Otherwise you may end up files containing numbers but not a full set of header information. -resid q = Output the residuals into a dataset with prefix 'q'. ++ The residuals are the difference between the data values and their prediction from the set mean (and set covariates). ++ For use in further analysis of the results (e.g., 3dFWHMx). ++ Cannot be used with '-brickwise' (sorry). ++ If used with '-zskip', values which were skipped in the analysis will get residuals set to zero. -ACF = If residuals are saved, also compute the ACF parameters from them using program 3dFHWMx -- for further use in 3dClustSim (which must be run separately). ++ HOWEVER, the '-Clustsim' option below provides a resampling alternative to using the parametric '-ACF' method in program 3dClustSim. -dupe_ok = Duplicate dataset labels are OK. Do not generate warnings for dataset pairs. ** This option must precede the corresponding -setX options. ** Such warnings are issued only when '-covariates' is used -- when the labels are used to extract covariate values from the covariate table. -debug = Prints out information about the analysis, which can be VERY lengthy -- not for general usage (or even for colonels). ++ Two copies of '-debug' will give even MORE output! ----------------------------------------------------------------------------- ClustSim Options -- for global cluster-level thresholding and FPR control ~1~ ----------------------------------------------------------------------------- The following options are for using randomization/permutation to simulate noise-only generated t-tests, and then run those results through the cluster-size threshold simulation program 3dClustSim. The goal is to compute cluster-size thresholds that are not based on a fixed model for the spatial autocorrelation function (ACF) of the noise. ETAC (infra) and ClustSim are parallelized. The randomized t-test steps are done by spawning multiple 3dttest++ jobs using the residuals as input. Then the 3dClustSim program (for -Clustsim) and 3dXClustSim program (for -ETAC) use multi-threaded processing to carry out their clusterization statistics. If your computer does NOT have multiple CPU cores, then these options will run very very slowly. You can use both -ETAC and -Clustsim in the same run. The main reason for doing this is to compare the results of the two methods. Using both methods in one 3dttest++ run will be super slow. ++ In such a dual-use case, and if '-ETAC_blur' is also given, note that 3dClustSim will be run once for each blur level, giving a set of cluster- size threshold tables for each blur case. This process is necessary since 3dClustSim does not have a multi-blur thresholding capability, unlike ETAC (via program 3dXClustSim). ++ The resulting 3dClustSim tables are to be applied to each of the auxiliary t-test files produced, one for each blur case. Unless one of those blur cases is '0.0', the 3dClustSim tables do NOT apply to the main output dataset produced by this program. ++ These auxiliary blur case t-test results get names of the form PREFIX.B8.0.nii where PREFIX was given in the '-prefix' option, and in this example, the amount of extra blurring was 8.0 mm. These files are the result of re-running the commanded t-tests using blurred input datasets. -Clustsim = With this option, after the commanded t-tests are done, then: (a) the residuals from '-resid' are used with '-randomsign' to simulate about 10000 null 3D results, and then (b) 3dClustSim is run with those to generate cluster-threshold tables, and then (c) 3drefit is used to pack those tables into the main output dataset, and then (d) the temporary files created in this process are deleted. The goal is to provide a method for cluster-level statistical inference in the output dataset, to be used with the AFNI GUI Clusterize controls. ++ If you want to keep ALL the temporary files, use '-CLUSTSIM'. They will include the z-scores from all the simulations. ** Normally, the permutation/randomization z-scores are saved in specially compressed files with suffix '.sdat'. If you want these files in the '.nii' format, use the options '-DAFNI_TTEST_NIICSIM=YES -CLUSTSIM'. ** However, if '-ETAC' is also used, the '.sdat' format will be used instead of the '.nii' format, as the program that implements ETAC (3dXClustSim) requires that format. ** You can change the number of simulations using an option such as '-DAFNI_TTEST_NUMCSIM=20000' if you like. ++ Since the simulations are done with '-toz' active, the program also turns on the '-toz' option for your output dataset. This means that the output statistics will be z-scores, not t-values. ++ If you have less than 14 datasets total (setA & setB combined), this option will not work! (There aren't enough random subsets.) ** And it will not work with '-singletonA'. -->>++ '-Clustsim' runs step (a) in multiple jobs, for speed. By default, it tries to auto-detect the number of CPUs on the system and uses that many separate jobs. If you put a positive integer immediately following the option, as in '-Clustsim 12', it will instead use that many jobs (e.g., 12). This capability is to be used when the CPU count is not auto-detected correctly. ** You can also set the number of CPUs to be used via the Unix environment variable OMP_NUM_THREADS. ** This program does not use OpenMP (OMP), but since many other AFNI programs do, setting OMP_NUM_THREADS is a common way to set the amount of parallel computation to use. -->>++ It is important to use a proper '-mask' option with '-Clustsim'. Otherwise, the statistics of the clustering will be skewed. -->>++ You can change the number of simulations from the default 10000 by setting Unix environment variable AFNI_TTEST_NUMCSIM to a different value (in the range 1000..1000000). Note that the 3dClustSim tables go down to a cluster-corrected false positive rate of 0.01, so that reducing the number of simulations below 10000 will produce notably less accurate results for such small FPR (alpha) values. **-->>++ The primary reason for reducing AFNI_TTEST_NUMCSIM below its default value is testing '-Clustsim' and/or '-ETAC' more quickly -->>++ The clever scripter can pick out a particular value from a particular 3dClustSim output .1D file using the '{row}[col]' syntax of AFNI, as in the tcsh command set csize = `1dcat Fred.NN1_1sided.1D"{10}[6]"` to pick out the number in the #10 row, #6 column (counting from #0), which is the p=0.010 FPR=0.05 entry in the table. -->++ Or even *better* now for extracting a table value: a clever person added command line options to 1d_tool.py to extract a value from the table having a voxelwise p-value ('-csim_pthr ..') and an FDR alpha level ('-csim_alpha ..'). Be sure to check out those options in 1d_tool.py's help! **-->>++ NOTE: The default operation of 3dClustSim when used from 3dttest++ is with the '-LOTS' option controlling the thresholds used for the tabular output. You can change that to the '-MEGA' option = a larger table, by setting Unix environment variable AFNI_CLUSTSIM_MEGA to YES. You can do that in several ways, including on the command line with the option '-DAFNI_CLUSTSIM_MEGA=YES'. [15 Dec 2021 - RWCox] ---==>>> PLEASE NOTE: This option has been tested for 1- and 2-sample ---==>>> unpaired and paired tests vs. resting state data -- to see if the ---==>>> false positive rate (FPR) was near the nominal 5% level (it was). ---==>>> The FPR for the covariate effects (as opposed to the main effect) ---==>>> is still somewhat biased away from the 5% level /:( ****** The following options affect both '-Clustsim' and '-ETAC' ****** -prefix_clustsim cc = Use 'cc' for the prefix for the '-Clustsim' temporary files, rather than a randomly generated prefix. You might find this useful if scripting. ++ By default, the Clustsim (and ETAC) prefix will be the same as that given by '-prefix'. -->>++ If you use option '-Clustsim', then the simulations keep track of the maximum (in mask) voxelwise z-statistic, compute the threshold for 5% global FPR, and write those values (for 1-sided and 2-sided thresholding) to a file named 'cc'.5percent.txt -- where 'cc' is the prefix given here. Using such a threshold in the AFNI GUI will (presumably) give you a map with a 5% chance of false positive WITHOUT clustering. Of course, these thresholds generally come with a VERY stringent per-voxel p-value. ** In one analysis, the 5% 2-sided test FPR p-value was about 7e-6 for a mask of 43000 voxels, which is bigger (less strict) than the 1.2e-6 one would get from the Bonferroni correction, but is still very stringent for many purposes. This threshold value was also close to the threshold at which the FDR q=1/43000, which may not be a coincidence. -->>++ This file has been updated to give the voxel-wise statistic threshold for global FPRs from 1% to 9%. However, the name is still '.5percent.txt' for the sake of nostalgia. -no5percent = Don't output the 'cc'.5percent.txt file that comes for free with '-Clustsim' and/or '-ETAC'. ++ But whyyy? Don't you like free things? -tempdir ttt = Store temporary files for '-Clustsim' in this directory, rather than in the current working directory. -->>++ This option is for use when you have access to a fast local disk (e.g., SSD) compared to general storage on a rotating disk, RAID, or network storage. ++ Using '-tempdir' can make a significant difference in '-Clustsim' and '-ETAC' runtime, if you have a local solid state drive available! [NOTE: with '-CLUSTSIM', these files aren't deleted!] -seed X [Y] = This option is used to set the random number seed for '-randomsign' to the positive integer 'X'. If a second integer 'Y' follows, then that value is used for the random number seed for '-permute'. ++ The purpose of setting seeds (rather than letting the program pick them) is for reproducibility. It is not usually needed by the ordinary user. ++ Option '-seed' is used by the multi-blur analysis possible with '-ETAC', so that the different blur levels use the same randomizations, to make their results compatible for multi- threshold combination. ++ Example: -seed 3217343 1830201 ***** These options (below) are not usually directly used, but ***** ***** are described here for completeness and for reference. ***** ***** They are invoked by options '-Clustsim' and '-ETAC'. ***** -randomsign = Randomize the signs of the datasets. Intended to be used with the output of '-resid' to generate null hypothesis statistics in a second run of the program (probably using '-nomeans' and '-toz'). Cannot be used with '-singletonA' or with '-brickwise'. ++ You will never get an 'all positive' or 'all negative' sign flipping case -- each sign will be present at least 15% of the time. ++ There must be at least 4 samples in each input set to use this option, and at least a total of 14 samples in setA and setB combined. ++ If you following '-randomsign' with a number (e.g., '-randomsign 1000'), then you will get 1000 iterations of random sign flipping, so you will get 1000 times the as many output sub-bricks as usual. This is intended for for use with simulations such as '3dClustSim -inset'. -->>++ This option is usually not used directly, but will be invoked by the use of '-Clustsim' and/or '-ETAC'. It is documented here for the sake of telling the Galaxy how the program works. -permute = With '-randomsign', and when both '-setA' and '-setB' are used, this option will add inter-set permutation to the randomization. ++ If only '-setA' is used (1-sample test), there is no permutation. (Neither will there be permutation with '-singletonA'.) ++ If '-randomsign' is NOT given, but '-Clustsim' is used, then '-permute' will be passed for use with the '-Clustsim' tests (again, only if '-setA' and '-setB' are both used). ++ If '-randomsign' is given and if the following conditions are ALL true, then '-permute' is assumed (without the option needed on the command line): (a) You have a 2-sample test. And, you are not using '-singletonA'. [Permutation is meaningless without 2 samples!] (b) And, you are not using '-unpooled'. (c) And, you are not using '-paired'. -->>++ You only NEED to use '-permute' if you want inter-set permutation used AND you the '-unpooled' option. + Permutation with '-unpooled' is a little weird. + Permutation with '-paired' is very weird and is NOT allowed. + Permutation with '-covariates' may not work the way you wish. In the past [pre-March 2020], covariates were NOT permuted along with their data. Now, covariate ARE permuted along with their data. This latter method seems more logical to me [RWCox]. ++ There is no option to do permutation WITHOUT sign randomization.

All AFNI program -help files

All AFNI program `-help` files