All AFNI program `-help` files

This page auto-generated on Fri Sep 29 12:58:23 EDT 2023

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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 -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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_64}

AFNI program: 1dDW_Grad_o_Mat
Fatal Signal 11 (SIGSEGV) received 1dDW_Grad_o_Mat Bottom of Debug Stack ** AFNI version = AFNI_23.2.12 Compile date = Sep 29 2023 ** [[Precompiled binary linux_ubuntu_16_64: Sep 29 2023]] ** Program Death ** ** If you report this crash to the AFNI message board, ** please copy the error messages EXACTLY, and give ** the command line you used to run the program, and ** any other information needed to repeat the problem. ** You may later be asked to upload data to help debug. ** Crash log is appended to file /home/afniHQ/.afni.crashlog

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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_64}

AFNI program: 1dplot
++ 1dplot: AFNI version=AFNI_23.2.12 (Sep 29 2023) [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 re-used. ** 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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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. -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; 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. -rowcol.name NAME1 [NAME2 ...]: Names of rows, same as name of columns. For the moment, this is only used with -matplot. -row.name NAME1 [NAME2 ...]: Name of each row in -input. 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/mplayer ===>> 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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 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 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)]' -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_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. 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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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_23.2.12 (Sep 29 2023) [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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_64}

AFNI program: 3dAFNItoMINC
[7m*+ WARNING:[0m This program (3dAFNItoMINC) is old, not maintained, and probably useless! Usage: 3dAFNItoMINC [options] dataset Reads in an AFNI dataset, and writes it out as a MINC file. OPTIONS: -prefix ppp = Write result into file ppp.mnc; default prefix is same as AFNI dataset's. -floatize = Write MINC file in float format. -swap = Swap bytes when passing data to rawtominc NOTES: * Multi-brick datasets are written as 4D (x,y,z,t) MINC files. * If the dataset has complex-valued sub-bricks, then this program won't write the MINC file. * If any of the sub-bricks have floating point scale factors attached, then the output will be in float format (regardless of the presence of -floatize). * This program uses the MNI program 'rawtominc' to create the MINC file; rawtominc must be in your path. If you don't have rawtominc, you must install the MINC tools software package from MNI. (But if you don't have the MINC tools already, why do you want to convert to MINC format anyway?) * At this time, you can find the MINC tools at ftp://ftp.bic.mni.mcgill.ca/pub/minc/ You need the latest version of minc-*.tar.gz and also of netcdf-*.tar.gz. -- RWCox - April 2002 ++ Compile date = Aug 4 2020 {AFNI_20.2.10:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 re-use 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 ...... 2. * The maximum number of CPUs that will be used is now set to .... 2. * 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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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: 3dANALYZEtoAFNI
** DON'T USE THIS PROGRAM! REALLY! USE 3dcopy OR to3d INSTEAD. IF YOU CHOOSE TO USE IT ANYWAY, PERHAPS BECAUSE IT WORKS BETTER ON YOUR 12th CENTURY PLANTAGENET ANALYZE FILES, ADD THE OPTION -OK TO YOUR COMMAND LINE. Usage: 3dANALYZEtoAFNI [options] file1.hdr file2.hdr ... This program constructs a 'volumes' stored AFNI dataset from the ANALYZE-75 files file1.img file2.img .... In this type of dataset, there is only a .HEAD file; the .BRIK file is replaced by the collection of .img files. - Other AFNI programs can read (but not write) this type of dataset. - The advantage of using this type of dataset vs. one created with to3d is that you don't have to duplicate the image data into a .BRIK file, thus saving disk space. - The disadvantage of using 'volumes' for a multi-brick dataset is that all the .img files must be kept with the .HEAD file if you move the dataset around. - The .img files must be in the same directory as the .HEAD file. - Note that you put the .hdr files on the command line, but it is the .img files that will be named in the .HEAD file. - After this program is run, you must keep the .img files with the output .HEAD file. AFNI doesn't need the .hdr files, but other programs (e.g., FSL, SPM) will want them as well. Options: -prefix ppp = Save the dataset with the prefix name 'ppp'. [default='a2a'] -view vvv = Save the dataset in the 'vvv' view, where 'vvv' is one of 'orig', 'acpc', or 'tlrc'. [default='orig'] -TR ttt = For multi-volume datasets, create it as a 3D+time dataset with TR set to 'ttt'. -fbuc = For multi-volume datasets, create it as a functional bucket dataset. -abuc = For multi-volume datasets, create it as an anatomical bucket dataset. ** If more than one ANALYZE file is input, and none of the above options is given, the default is as if '-TR 1s' was used. ** For single volume datasets (1 ANALYZE file input), the default is '-abuc'. -geomparent g = Use the .HEAD file from dataset 'g' to set the geometry of this dataset. ** If you don't use -geomparent, then the following options can be used to specify the geometry of this dataset: -orient code = Tells the orientation of the 3D volumes. 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 -zorigin dz = Puts the center of the 1st slice off at the given distance ('dz' in mm). This distance is in the direction given by the corresponding letter in the -orient code. For example, -orient RAI -zorigin 30 would set the center of the first slice at 30 mm Inferior. ** If the above options are NOT used to specify the geometry of the dataset, then the default is '-orient RAI', and the z origin is set to center the slices about z=0. It is likely that you will want to patch up the .HEAD file using program 3drefit. -- RWCox - June 2002. ** DON'T USE THIS PROGRAM! REALLY! USE 3dcopy OR to3d INSTEAD. IF YOU CHOOSE TO USE IT ANYWAY, PERHAPS BECAUSE IT WORKS BETTER ON YOUR 12th CENTURY PLANTAGENET ANALYZE FILES, ADD THE OPTION -OK TO YOUR COMMAND LINE.-- KRH - April 2005.

AFNI program: 3dAnatNudge
[7m*+ WARNING:[0m This program (3dAnatNudge) is old, obsolete, and not maintained! Usage: 3dAnatNudge [options] Moves the anat dataset around to best overlap the epi dataset. OPTIONS: -anat aaa = aaa is an 'scalped' (3dIntracranial) high-resolution anatomical dataset [a mandatory option] -epi eee = eee is an EPI dataset [a mandatory option] The first [0] sub-brick from each dataset is used, unless otherwise specified on the command line. -prefix ppp = ppp is the prefix of the output dataset; this dataset will differ from the input only in its name and its xyz-axes origin [default=don't write new dataset] -step sss = set the step size to be sss times the voxel size in the anat dataset [default=1.0] -x nx = search plus and minus nx steps along the EPI -y ny dataset's x-axis; similarly for ny and the -z nz y-axis, and for nz and the z-axis [default: nx=1 ny=5 nz=0] -verb = print progress reports (this is a slow program) NOTES *Systematically moves the anat dataset around and find the shift that maximizes overlap between the anat dataset and the EPI dataset. No rotations are done. *Note that if you use -prefix, a new dataset will be created that is a copy of the anat, except that it's origin will be shifted and it will have a different ID code than the anat. If you want to use this new dataset as the anatomy parent for the EPI datasets, you'll have to use 3drefit -apar ppp+orig eee1+orig eee2+orig ... *If no new dataset is written (no -prefix option), then you can use the 3drefit command emitted at the end to modify the origin of the anat dataset. (Assuming you trust the results - visual inspection is recommended!) *The reason the default search grid is mostly along the EPI y-axis is that axis is usually the phase-encoding direction, which is most subject to displacement due to off-resonance effects. *Note that the time this program takes will be proportional to (2*nx+1)*(2*ny+1)*(2*nz+1), so using a very large search grid will result in a very large usage of CPU time. *Recommended usage: + Make a 1-brick function volume from a typical EPI dataset: 3dbucket -fbuc -prefix epi_fb epi+orig + Use 3dIntracranial to scalp a T1-weighted volume: 3dIntracranial -anat spgr+orig -prefix spgr_st + Use 3dAnatNudge to produce a shifted anat dataset 3dAnatNudge -anat spgr_st+orig -epi epi_fb+orig -prefix spgr_nudge + Start AFNI and look at epi_fb overlaid in color on the anat datasets spgr_st+orig and spgr_nudge+orig, to see if the nudged dataset seems like a better fit. + Delete the nudged dataset spgr_nudge. + If the nudged dataset DOES look better, then apply the 3drefit command output by 3dAnatNudge to spgr+orig. *Note that the x-, y-, and z-axes for the epi and anat datasets may point in different directions (e.g., axial SPGR and coronal EPI). The 3drefit command applies to the anat dataset, NOT to the EPI dataset. *If the program runs successfully, the only thing set to stdout will be the 3drefit command string; all other messages go to stderr. This can be useful if you want to capture the command to a shell variable and then execute it, as in the following csh fragment: set cvar = `3dAnatNudge ...` if( $cvar[1] == "3drefit" ) $cvar The test on the first sub-string in cvar allows for the possibility that the program fails, or that the optimal nudge is zero. ++ Compile date = Aug 21 2020 {AFNI_20.2.14:linux_ubuntu_16_64}

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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_64}

AFNI program: 3dANOVA
++ 3dANOVA: AFNI version=AFNI_23.2.12 (Sep 29 2023) [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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_64}

AFNI program: 3dANOVA2
++ 3dANOVA: AFNI version=AFNI_23.2.12 (Sep 29 2023) [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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_64}

AFNI program: 3dAutobox
++ 3dAutobox: AFNI version=AFNI_23.2.12 (Sep 29 2023) [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_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 ...... 2. * The maximum number of CPUs that will be used is now set to .... 2. ========================================================================= ++ Compile date = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 -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 -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 ...... 2. * The maximum number of CPUs that will be used is now set to .... 2. * At present, the only part of 3dBandpass that is parallelized is the '-blur' option, which processes each sub-brick independently. ========================================================================= ++ Compile date = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 ...... 2. * The maximum number of CPUs that will be used is now set to .... 2. ========================================================================= ++ Compile date = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 = Sep 29 2023 {AFNI_23.2.12:linux_ubuntu_16_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 e

All AFNI program -help files

All AFNI program `-help` files