1\documentstyle[12pt,art12cox,epsf]{article} 2 3\newcommand{\afni}{{\it AFNI\,}} 4\newcommand{\afnit}{{\it AFNI\/}\ } 5\newcommand{\tothreed}{{\sf to3d\,}} 6\newcommand{\tothreedit}{{\sf to3d\/}\ } 7\newcommand{\MCW}{{\sf MCW}} 8 9\setlength{\topmargin}{0.0in} 10\setlength{\textheight}{9.02in} 11\setlength{\textwidth}{6.5in} 12\setlength{\oddsidemargin}{0.25in} 13\setlength{\evensidemargin}{0.25in} 14 15\hyphenpenalty=200 16 17\def\mypleft{\footnotesize \MCW$\!$ \afnit 2.00} 18\def\mypright{\scriptsize Dec 30, 1996} 19\dashpage 20 21\raggedbottom 22 23\newcommand{\seeme}[1]% 24{\marginpar{\raggedright% 25$\star\star\star$\hspace*{0pt plus 1fill}$\longrightarrow$\\{}% 26\scriptsize\bf#1}} 27 28\newcommand{\blob}{\hspace*{1em}} 29 30\setlength{\fboxsep}{1.3pt} 31\setlength{\fboxrule}{0.6pt} 32\newcommand{\button}[1]{\fbox{\tt #1}} 33 34\newcommand{\mysec}[1]{% 35\vspace{1.1in}\goodbreak\vspace{-1.09in}\section{#1}} 36 37\newcommand{\mysubsec}[1]{% 38\vspace{0.9in}\goodbreak\vspace{-0.89in}\subsection{#1}} 39 40\newcommand{\mysubsubsec}[1]{% 41\vspace{0.8in}\goodbreak\vspace{-0.8in}\subsubsection{#1}} 42 43%--------------------------------------------------------------------- 44\begin{document} 45\thispagestyle{empty} 46 47\vspace*{-0.2in} 48\centerline{\LARGE\bf \MCW$\!$ \afnit --- User Manual}\vspace{1.8ex} 49\centerline{\Large\bf Medical College of Wisconsin}\vspace{1ex} 50\centerline{\Large\bf Analysis of Functional NeuroImages}\vspace{1ex} 51\centerline{\large\bf Version 2.00, December 1996}\vspace{1.5ex} 52\centerline{\bf Robert W. Cox, Ph.D.}\vspace{0.5ex} 53\centerline{Biophysics Research Institute} 54\centerline{Medical College of Wisconsin} 55\centerline{8701 Watertown Plank Road} 56\centerline{Milwaukee, WI 53226}\vspace{1ex} 57 58\centerline{\copyright\ 1996 Medical College of Wisconsin} 59 60\vspace{1.1ex} 61\noindent 62{\it Summary\/}: 63\MCW$\!$ \afnit displays three dimensional functional 64neuroimages overlaid onto anatomical reference scans. 65Data may be transformed to the Talairach-Tournoux (stereotaxic) 66proportional grid system. 67Images may be generated in each of the three cardinal orthogonal planes, 68and switched among multiple functional/anatomical data volumes. 69Auxiliary programs are provided to manipulate and combine 3D image sets. 70Time-dependent 3D image sets may also be stored, displayed, and manipulated. 71An application programmer interface is provided to allow users to extend 72the functionality of \afnit (via `plugins'). 73 74\vspace{1.1ex} 75\noindent 76{\it Document\/}: 77This manual describes the use of the \afnit program, version 2.00. 78Earlier versions (1.xx) are superseded by this version; 79bugs in the earlier programs will no longer be fixed. 80Separate manuals are provided for the auxiliary programs, and for the 81programming of plugins. 82 83\vspace{1.1ex} 84\noindent 85{\it Disclaimer\/}: 86This software and its associated manuals are provided AS IS, and no warranty for 87their usefulness or correctness for any purpose is made or implied by the 88Medical College of Wisconsin or by the author. 89This software has not been approved or evaluated by the United States 90Food and Drug Administration for any clinical application. 91 92\vspace{1.1ex} 93\noindent 94{\it Ownership and License to Use\/}: 95This software and its associated manuals are Copyright 1994-96 96by the Medical College of Wisconsin. Permission is granted to make use of 97and to make copies 98of this software and its manuals for non-commercial research purposes only. 99Use of the software or its manuals by for-profit organizations is 100prohibited without prior written permission. 101Redistribution of this work, or any derived work, outside 102of the licensed organization is prohibited without prior 103written permission. Copies may be made within the licensed organization 104without separate permission from the Medical College of Wisconsin. 105 106\vspace{1.1ex} 107\noindent 108{\it Distribution and Registration\/}: 109\MCW$\!$ \afnit is available free for research purposes, but users 110must register with the Medical College of Wisconsin. 111For information, send an e-mail request to the author at 112{\tt rwcox@mcw.edu}, write to the address above, or see the 113final page of this manual. 114 115\vspace{1.1ex} 116\noindent 117{\it Acknowledgement\/}: 118This work was developed with internal MCW funds 119and was also partly supported by the United States NIH through 120grants MH51358 and NS34798. 121 122%%%\vspace*{0pt plus 1fill} 123%%%\noindent 124%%%{\scriptsize \hspace*{0pt plus 1fill}Manual last updated Dec 30 1996.} 125 126%--------------------------------------------------------------------------- 127\newpage 128\setlength{\columnsep}{1.1em} 129\setlength{\columnseprule}{0.5pt} 130\twocolumn[\centerline{\Large\bf Contents}\vspace*{6ex}] 131{%\small 132\renewcommand\contentsname{\vspace*{-25pt}} 133\tableofcontents 134} 135\onecolumn 136 137%=========================================================================== 138\newpage 139\mysec{Introduction} 140\afnit is an interactive program 141for viewing the results of 3D functional neuroimaging. 142It can overlay the (usually) low resolution results of functional brain 143scans onto higher resolution structural volume data sets. By marking fiducial 144points, you may transform the data to the proportional grid 145(stereotaxic coordinates) of Talairach and Tournoux~\cite{Talairach}. 146Time-dependent 3D volume data sets can also be created and viewed. 147Auxiliary programs are provided for combining and editing 3D and 1483D+time functional data sets. 149 150With this new version of \MCW$\!$ \afni, my intention is to add many new 151analytical capabilities to the software system. Some of these are 152found in the auxiliary programs. Others are found in the \afnit program 153itself; in particular, the interactive ability to compute functional activation 154using the correlation method~\cite{Bandettini}. The 155new plugins capability offers C-literate users the ability 156to integrate their own analytical tools into \afni. It is my hope 157that other sites will develop \afnit plugins and share them with 158the FMRI community. 159 160This document has been extensively rewritten from the version 1.0x 161manuals. Major new\seeme{Whats New?} 162facilities in \afnit are outlined in the next section. 163 164The\seeme{Computer requisites} 165program runs on Unix workstations, using the X11 windowing 166system and the Motif 1.2 toolkit for its graphical interface. Minimum system 167requirements to use \afnit are 32 MB RAM (64-128 MB will work much better), X11R5 with 168Motif 1.2, an ANSI~C compiler, 169and enough disk space to hold the 3D data volumes required. 170\afnit is designed to work with 8- or 12-bit PseudoColor X11 visuals. 171A~visual of this type must be the default visual on the system used to display \afni. 172The program has been tested on the following systems: 173\begin{itemize} 174 \item SGI Indigo workstations (R4400 and R10000 CPUs) running IRIX~5.3 175 and IRIX~6.2. 176 \item HP 9000/735 workstations running HP-UX 9.05. 177 \item Intel-based Linux 1.2.13 systems. 178 \item Sun SPARCstations running Solaris 2.5. 179\end{itemize} 180It has not been tested on other platforms. 181It {\it will not\/} work with X11R4 or Motif~1.1 182(in particular, it does not work under SGI IRIX~4.x). 183There are no plans to port it to radically different platforms such as 184Microsoft Windows or the Apple Macintosh. 185 186\afnit is a powerful program for display and manipulation 187of functional neuroimages, with many options. Study of this 188manual and experience with the program are both required to make full 189use of \afni. Some experience with using X11 is also very useful, 190and will be assumed in this manual. 191 192\displayline{Nomenclature} 193In general, I refer to ``\MCW$\!$ \afni'' as the whole software package. 194The particular program ``\afni'' is at the heart of the package, and 195is the subject of this manual. The package includes a number of other 196programs and the programming interface for 197creating plugins, both of which are documented elsewhere. 198 199If you find \MCW$\!$ \afnit useful and wish to refer to it in 200a publication, the appropriate citation is~\cite{Cox-AFNI}. 201 202%======================================================================= 203\mysec{What's New?} 204\begin{description}\vspace*{-2.2ex} 205 \item[\blob 1. Atomic Datum Types] \blob\\ 206 Previously, the data stored in an \afnit dataset had to be 16 bit 207 signed integers ({\tt short} datum). 208 The new dataset format allows for 209 8 bit unsigned integers ({\tt byte} datum), 210 32 bit floating points numbers ({\tt float} datum), 211 and 64 bit complex numbers ({\tt complex} datum). 212 The purpose of the 213 {\tt byte} datum is to allow for compact storage of datasets 214 where the 0--255 range has sufficient precision. 215 The purpose of the {\tt float} datum is to allow for more natural storage 216 of statistical quantities, without the need for rescaling to the 217 limited range of values allowed with {\tt short}s. 218 (But see item~2 below.) 219 The purpose of the 220 {\tt complex} datum is to eventually allow for unprocessed reconstructed 221 images to be directly imported into \afni. 222 223 \item[\blob 2. Scale Factors] \blob\\ 224 Each 3D sub-brick in a dataset can now have a floating point scale 225 factor attached to it. The purpose of this is to allow data to be 226 stored in the more compact {\tt byte} or {\tt short} formats, but always to 227 be automatically scaled to the correct units when accessed by an 228 \MCW$\!$ \afnit program. For example, correlation coefficients 229 can still be stored as {\tt short}s ${\in} [-10000,10000]$, but will 230 be scaled by $0.0001$ to their true range $\in [-1.0,1.0]$ 231 before being displayed or processed. (The new interactive {\tt FIM} 232 utility in \afnit does this --- see item~6 below.) The new {\sf to3d} can 233 take as input floating point volumes and scale them to produce 234 {\tt short} or {\tt byte} datasets, with the appropriate scale 235 factor(s) attached. 236 237 \item[\blob 3. Auxiliary Statistical Data] \blob\\ 238 There are three new types of datasets: the {\tt fico}, {\tt fitt}, and {\tt fift} 239 functions. {\tt fico} means ``functional intensity with correlation''; 240 {\tt fitt} means ``functional intensity with $t$-test''; 241 {\tt fift} means ``functional intensity with $F$-test''. 242 These are similar in concept to the {\tt fith} images, but the 243 threshold data now has the statistical parameters ({\it e.g.},~degrees 244 of freedom) attached that 245 allow calculation of the significance ($p$) level. With 246 such a dataset, \afnit will interactively display the $p$-value 247 associated with the chosen threshold. 248 At present, only \afnit and {\sf 3dfim} generated {\tt fico}, 249 {\sf 3dttest} generated {\tt fitt}, 250 and {\sf 3dANOVA} generated {\tt fift} datasets have the 251 statistical parameters automatically attached. Using the new 252 {\sf to3d}, it is possible to create your own datasets of these types 253 if you provide the needed auxiliary statistical parameters. 254 255 \item[\blob 4. Demise of Dataset `Name' and `Short Label'] \blob\\ 256 These values are no longer used in {\sf to3d} or \afni. 257 The filename of a dataset is now used for display in the \afnit window 258 titlebars and selection choosers. 259 260 The original purpose of the name and short label values was 261 to assign descriptions to a dataset that did not depend on the 262 filename. This is needed when one dataset refers to another, 263 which happens during the warp-on-demand procedure. 264 If you renamed a dataset, and if filenames 265 were used as the internal method of keeping track of such references, 266 \afnit would get confused. To solve this problem, I~have instead 267 put inside each dataset's {\tt .HEAD} file an internally generated 268 identifier code. This is designed to be unique, and independent 269 of filenames. When you run an \afnit program on an old dataset, 270 you will see a message that it is generating a `new ID code'. 271 These ID codes are pseudorandomly generated using the current time and 272 machine name as seeds. For more information, see the plugins manual. 273 274 If you use the Unix command {\tt cp} to copy a dataset, then 275 the new dataset will have the same ID code as the original. 276 \afnit will not run correctly if two such datasets are read 277 into the program. To fix this, you can use the auxiliary 278 program {\sf 3dnewid} to attach a new ID code to a dataset. 279 280 \item[\blob 5. 3D+time Datasets] \blob\\ 281 \afnit now supports time-dependent 3D datasets, 282 which I refer to as `3D+time datasets'. At present, only 283 anatomical datasets may be usefully set up to be time-dependent. 284 3D+time datasets are created with {\sf to3d}, using the 285 new {\tt -time:zt} or {\tt -time:tz} command line switches. 286 287 3D+time datasets can be viewed in the image viewing windows in 288 the usual orthogonal slices. (Scrolling in time 289 through these views is a good way to check for subject movement.) 290 They can also be graphed vs.\ time (similar to the program {\sf FD2}). 291 292 \item[\blob 6. Interactive Functional Activation Analysis] \blob\\ 293 \afnit now has the ability to run the equivalent of the 294 {\sf fim2} program on a 3D+time dataset, producing as output 295 a new 3D {\tt fico} dataset. 296 297 \item[\blob 7. Image Montage] \blob\\ 298 One of the most visible changes to \afnit itself is the addition of 299 the `montage' (display of an array of slices) 300 feature to the image viewing windows. 301 This is accessed using the new \button{Mont} button. 302 303 \item[\blob 8. Big Talairach Box]\blob\\ 304 The size of the default Talairach coordinates brick has been extended down 305 (inferior) by 10~mm. This is to make sure that the brick includes the entire 306 cerebellum, which is not the case using the old brick dimensions (taken 307 from the Atlas). 308 309 \item[\blob 9. Threshold Resampling]\blob\\ 310 The type of interpolation used for functional dataset resampling is controlled by 311 the \button{Resam mode} button in the {\tt Datamode} control panel. 312 In \afnit 1.0x, both the functional intensity (`{\tt fim}') and the threshold 313 data were resampled using the chosen method. In this version of \afni, 314 the threshold data ({\it e.g.},~correlation coefficient) is always 315 resampled using the {\tt NN} method. This is because thresholding with 316 an interpolated nonlinear statistic is a somewhat dubious procedure. 317 318 \item[\blob 10. Multiple \afnit Controllers]\blob\\ 319 Using the \button{New} button, you can open up multiple controller windows 320 in a single run of \afni. This allows you to view more than one dataset 321 at a time. Using the \button{Lock} menu, you can force the coordinates 322 of the different viewing windows to be locked together. This feature 323 allows you to scroll in unison through multiple datasets. 324 325\goodbreak 326 327 \item[\blob 11. Session Directories]\blob\\ 328 If you don't specify any directories on the command line, 329 then \afnit acts as if you had typed~`{\tt ./}' --- that is, 330 it will try to read datasets from the current directory. 331 The new `{\tt -R}' switch will tell \afnit to read from 332 all subdirectories of the given session directories, recursively. 333 Using the {\tt Rescan} buttons, you can re-read sessions. 334 This is useful if you use an auxiliary program ({\it e.g.},~{\sf 3dmerge}) 335 to create a dataset, and then want to import it into \afni. 336 337 \item[\blob 12. Writing Many Datasets to Disk at Once]\blob\\ 338 A new button allows you to select many datasets at once for output to disk. 339 This makes it possible to start a long Talairach output session, and 340 then leave the computer unattended while it computes each output {\tt .BRIK}. 341 342%%% \item[\blob 13. Plugins]\blob\\ 343%%% A programming interface has been defined that allows the 344%%% addition of new routines to \afni. These are called `plugins', 345%%% and have a separate manual. 346 347\end{description} 348 349%====================================================================================== 350\mysec{Fundamentals} 351This section explains how data is organized in the \MCW$\!$ \afnit package. 352The two indispensable concepts are {\it datasets} and {\it sessions}. 353 354%------------------------------------------------------------------------------ 355\mysubsec{Datasets} 356The\seeme{Crucial information} 357fundamental unit of data in \afnit is the {\it dataset\/}: one or more 3D bricks of 358imaging data, together with some auxiliary information ({\it e.g.},~axes orientation, 359coordinates of marked fiducial points,~\ldots). There are two classes of 360datasets: {\it anatomical\/} and {\it functional\/}. An example of the former 361would be a Spoiled GRASS MRI scan. An example of the latter would be 362the results of cross-correlating a functional MRI (FMRI) time course of 363images~\cite{Bandettini}. When you create a dataset (using the 364\tothreedit program), you must specify whether it is anatomical or functional 365in nature. When you are using \afni, at any given time you will be displaying 366one anatomical dataset as the grayscale underlay, and (possibly) 367one functional dataset as the false color overlay. 368 369Within the class of anatomical datasets, \tothreedit provides you with a list 370of possible types ({\it e.g.}, Spoiled GRASS, Echo-Planar, MR Angiogram,~\ldots). At present, 371all anatomical types of datasets are treated identically. The only reason 372for choosing a particular anatomical type is to remind yourself of the 373dataset's origin. 374 375Anatomical\seeme{3D+time} 376datasets may be in the `3D' or the `3D+time' format. 377The 3D format stores one value per voxel. The 3D+time format stores 378a series of values per voxel. This can be used to stored all the data 379from a 3D FMRI imaging run. The auxiliary program {\sf 3dfim} or 380the internal \afnit {\tt FIM} capability can be used to produce 381functional activation datasets from 3D+time datasets. 382 383Within the class of functional datasets, there are presently 384five types. 385\begin{tabbing} 386 XXXX \= {\bf FFFFF} \= \kill 387 \> {\tt fim} \> Functional Intensity \\* 388 \> \> $\bullet$ one value is stored per voxel \\[1ex] 389% 390 \> {\tt fith} \> Functional Intensity + Threshold\\* 391 \> \> $\bullet$ two values are stored per voxel: \\* 392 \> \> $\bullet$ the first is `intensity' (defined arbitrarily); \\* 393 \> \> $\bullet$ \parbox[t]{4.5in}{ 394 the second is `threshold', 395 which is a either a floating point number between $-1.0$ and $1.0$ 396 or a 2 byte integer between $-10000$ and $10000$, 397 which can be used to select which 398 voxels are considered `active'.} \\[1ex] 399% 400 \> {\tt fico} \> Functional Intensity + Correlation\\* 401 \> \> $\bullet$ two values are stored per voxel:\\* 402 \> \> $\bullet$ the first is `intensity'; \\* 403 \> \> $\bullet$ \parbox[t]{4.5in}{ 404 the second is a correlation coefficient 405 (between $-1.0$ and $1.0$), 406 which can be used to select `active' voxels 407 at a given significance ($p$) value.}\\[1ex] 408% 409 \> {\tt fitt} \> Functional Intensity + $t$-test\\* 410 \> \> $\bullet$ two values are stored per voxel:\\* 411 \> \> $\bullet$ the first is `intensity'; \\* 412 \> \> $\bullet$ \parbox[t]{4.5in}{ 413 the second is a $t$-statistic, which 414 can be used to select `active' voxels 415 at a given significance.}\\[1ex] 416% 417 \> {\tt fift} \> Functional Intensity + $F$-test\\* 418 \> \> $\bullet$ two values are stored per voxel:\\* 419 \> \> $\bullet$ the first is `intensity'; \\* 420 \> \> $\bullet$ \parbox[t]{4.5in}{ 421 the second is an $F$-statistic, which 422 can be used to select `active' voxels 423 at a given significance.} 424\end{tabbing} 425By {\it intensity}, I mean a signed 426number indicating the level of functional activity in each voxel. 427 428I consider the {\tt fith} dataset type to be obsolete. It is retained 429for compatibility with \afnit version 1.0x. The latter three functional 430types differ from the {\tt fith} type in that \afnit knows how to 431statistically interpret the second value attached to each voxel. 432 433The\seeme{Atomic datum} 434values stored at each voxel can be any of the following: 435\begin{tabbing} 436 \blob\blob COMPL \= \kill 437 \blob\blob{\tt byte} \> = a~{\tt typedef} for {\tt unsigned char} \\ 438 \blob\blob{\tt short} \> = 2 byte signed {\tt int} \\ 439 \blob\blob{\tt float} \> = single precision; 4 bytes \\ 440 \blob\blob{\tt complex} \> = a~{\tt struct} containing two {\tt float}s; 8 bytes 441\end{tabbing} 442I~refer to these types as the `atomic' datum types of a dataset. 443{\tt Float} and {\tt complex} datasets may not be portable 444between CPU architectures. Also, {\tt short} datasets may need to be 445byte-swapped if the files are moved to a different computer. 446(Specifically, 447Intel CPUs are reversed from most other Unix systems, so that 448{\tt short} brick files created on an SGI system would have to be 449byte-reversed before they could be used on an Intel based system.) 450The auxiliary program {\sf 2swap} can perform this function. 451 452For most purposes, the {\tt short} atomic datum is the most useful. 453Each 3D brick within a {\tt short} (or {\tt byte}) dataset 454can have a floating point scaling factor attached, so that the 455\afnit programs will interpret the value stored as 456${\hbox{\it factor} * \hbox{\it voxel value}}$. 457 458Datasets are stored in two files: the {\it header\/} and {\it brick\/} files. 459The header file contains all the auxiliary information about a dataset, 460stored in an ASCII format. 461The brick file contains only the actual 3D volume data. 462For details on the storage, see the \afnit plugins manual. 463 464The\seeme{File names} 465files in a dataset have highly structured names, and these names should 466not be casually altered, or \afnit will not be able to read them. 467The general form of the dataset filenames is 468`{\tt prefix+view.NAME}', 469where `{\tt prefix}' is to be supplied by the user (you), and presumably 470would be used to indicate the type of data stored in the file 471({\it e.g.},~{\tt spgr} for Spoiled GRASS, {\tt func}~for functional intensity,~etc.) 472The `{\tt +view}' code 473indicates the origin of the data and is assigned by \afni; 474the possibilities are: 475\begin{description} 476 \item[\blob{\tt +orig}] for original data (untransformed by \afnit) 477 \item[\blob{\tt +acpc}] for datasets which have been aligned to the AC--PC line 478 \item[\blob{\tt +tlrc}] for datasets which have been transformed to the Talairach-Tournoux grid 479\end{description} 480Datasets in the {\tt +acpc} and {\tt +tlrc} views would normally be 481created by \afni; {\tt +orig} files would be created by \tothreed. 482The `{\tt .NAME}' suffix is 483{\tt .HEAD} for the header file, and is {\tt .BRIK} for the brick file. 484 485One reason for splitting the auxiliary information from the volume data 486in each dataset is for efficiency of access to the brick file. Another 487reason is that in an emergency, the auxiliary information is stored in 488ASCII form and so can be edited manually (this requires extreme care!). 489A~third reason is that when transformed datasets ({\tt +acpc} and {\tt +tlrc}) 490are created, their 491brick files may be deleted later to save disk space --- as long as the 492transformed header files and the {\tt +orig} brick files exist, \afnit 493can recreate the transformed data. 494 495Once raw images have been put into the \afnit dataset format, they are 496no longer needed for any of the programs described herein. 497It is always possible (using \afnit or {\sf from3d}) to extract images out of the 3D 498data brick, although you may then have to convert them into whatever 499format you desire. 500 501If you choose to rename the pair of files that make up a dataset, the 502only part you should touch is the prefix. If you alter the {\tt +view} 503or {\tt .NAME} parts, \afnit will probably refuse to read the files at all. 504 505Not\seeme{Warp-on-demand} 506all datasets will have a {\tt .BRIK} file. \afnit is capable of 507transforming data from a `parent' dataset as needed for image display. 508If the necessary transformation ({\it e.g.},~from {\tt +orig} to {\tt +tlrc}) 509is available, then the `child' dataset ({\it e.g.}~the {\tt +tlrc} dataset) 510need not have a {\tt .BRIK} file---it can be ``warped-on-demand'' for display. 511Normally, {\tt +orig} datasets do not have a warp parent dataset, so they 512must have a {\tt .BRIK} file. (An exception to this rule can be 513created with the auxiliary program {\sf 3ddup}.) 514 515At this time, no program but \afnit itself can deal with warp-on-demand 516datasets. That is, all the auxiliary programs (and plugins) must 517deal with actual dataset {\tt .BRIK}s. 518 519%-------------------------------------------------------------------------------- 520\mysubsec{Sessions} 521All\seeme{Crucial information} 522of the dataset files that `go together' should be gathered into 523a single directory. 524By `go together', I~specifically mean those datasets gathered during the same 525scanning session on a single subject. After their positions and orientations 526are set up (in \tothreed), all these datasets are presumed to be aligned to 527one another. {\it If this is not the case, then the images making up the 528datasets should be registered before entry into \tothreed.} 529The auxiliary program {\sf imreg} may be useful for this purpose. 530Alternatively, the program {\sf AIR} from UCLA might be needed. {\tt AIR} 531is available at {\verb=http://bishopw.loni.ucla.edu/AIR/index.html=}. 532 533\vspace{1in}\goodbreak\vspace{-1in} 534A directory containing datasets is called a {\tt session}. 535The hierarchy of files that make up a session 536is pictured below: 537\begin{samepage}\begin{verbatim} 538 session <-- top-level directory 539 / | \ 540 / | \ 541 / | \ 542 ... header header header ... <-- actual data files 543 brick brick brick 544 header header header 545 brick brick 546\end{verbatim}\end{samepage} 547 548It is permissible to save other files ({\it e.g.},~the original image files) 549in the session directory --- these files will simply be ignored by \afni. 550 551\afnit takes as input a collection of sessions (specified by their directory 552names), and allows you to switch 553between them and between their constituent anatomical and functional datasets. 554It is important to understand the dataset concepts, 555file structure, and directory hierarchy described and depicted above. 556 557Sessions\seeme{Command line names for sessions, datasets} 558are referred to 559by the top-level directory name under which 560all their datasets reside. An individual dataset is referred to (on auxiliary 561program command lines) by 562the name of its header file, the name of its brick file, or just 563by the {\tt prefix+view} part of the filenames; for example,\\*[.5ex] 564\centerline{\tt 12dec94/func03+acpc.HEAD \blob 565 12dec94/func03+acpc.BRIK \blob 12dec94/func03+acpc}\vspace{.5ex} 566would all refer to the same dataset residing in a given session 567directory. 568 569By moving to the directory {\it above\/} the session directory, 570you can save and compress all the files in a session using the command\\*[.5ex] 571\centerline{\tt tar cvf - session\_directory | gzip -9v > session.tgz}\vspace{0.5ex} 572This presumes that you have the {\tt GNU gzip} compression utility installed 573on your system. The command to uncompress and restore from the compressed 574archive would be\\*[.5ex] 575\centerline{\tt gzip -dc session.tgz | tar xvf -} 576 577%============================================================================ 578\newpage 579\mysec{A Tour of \afni} 580The best way to learn the program is to 581read this tour through, and then sit down with the program 582and try it out. 583 584%--------------------------------------------------------------------- 585\mysubsec{Starting Up} 586The command line to run \afnit is quite simple:\\*[.5ex] 587\centerline{\tt afni session1 session2 ...}\vspace{0.5ex} 588Here, {\tt session*} is the name of a session directory to 589read in. All the 3D datasets under each named session directory 590will be read in. If no sessions are specified on the command line, 591the current working directory will be used. 592(Command line options for \afnit will be discussed in a later section.) 593 594For \afnit to be able to use a session, it must 595contain at least one anatomical dataset (3D or 3D+time). If none are 596available, the auxiliary program {\sf 3ddup} can be 597used to create a warp-on-demand copy of a functional dataset. 598Alternatively, you could use 599the first image from the FMRI time course in each slice to form 600an anatomical dataset, but a separate higher-resolution scan will 601be more useful and look better. 602At any given moment in \afni, 603you are viewing one given anatomical dataset and (possibly) one given 604functional dataset. Controls are supplied to let you switch among 605sessions and among datasets within sessions. 606 607\goodbreak 608 609A useful model is to think of each session as being organized in a 610two dimensional layout: 611\goodbreak\begin{samepage}\begin{verbatim} 612 --------- View Type -------- 613 +orig +acpc +tlrc 614 615 | anat : X X 616 prefix | angio : X O 617 | func1 : X O 618 | func2 : X O 619\end{verbatim}\end{samepage} 620Across the top is the view type (Original, AC--PC aligned, or Talairach). 621Down is the dataset prefix. {\tt X}'s mark datasets that 622actually exist on disk. In the sample above, the {\tt anat} 623original data has also been transformed to the AC--PC aligned 624view (using the marker driven transformation described later). 625 626When \afnit starts, all the other datasets in this session 627will also have AC--PC aligned view versions made internally 628in the program --- these are indicated by {\tt O}'s in the 629table above. (No {\tt .HEAD} files will be written for these 630datasets at this time. These datasets will be warp-on-demand 631until and unless you write out the {\tt .BRIK} files using 632one of the {\tt Write} buttons described later.) 633The transformation from {\tt +orig} to {\tt +acpc} 634in the {\tt anat} dataset (stored in the {\tt .HEAD} file) will 635be applied to the other datasets in the {\tt +orig} view. These 636`follower' datasets are what makes \afnit work and easy to use. When the 637{\tt anat} transformation from {\tt +acpc} to {\tt +tlrc} is defined 638--- when the {\tt X} is placed at the top of the third column --- 639then all the other datasets in this session will again 640follow along --- {\tt O}'s will fill in the rest of the third column. 641 642For this to be possible, it is necessary that the correct 643geometrical relationship 644between the datasets comprising a session be established when 645\tothreedit is run --- that is the import of getting the axes 646orientations and origins correct in \tothreed. 647 648\afnit is\seeme{{\tt afni -im}} 649also capable of directly reading in and displaying 650a set of image files. Use the command `{\tt afni~-help}' for 651detailed instructions on how to do this. In this mode, none 652of the controls for dataset transformation, functional overlay, 653etc\@., are available. 654 655\goodbreak\begin{samepage} 656After you start \afni, a control window opens on the X11 screen:\\*[2ex] 657\centerline{\epsfysize=3.2in\epsffile{afni200_panel1.eps}\blob 658 \epsfysize=3.2in\epsffile{afni200_image1.eps}}\vspace{1ex} 659\centerline{\sf \afnit controller and image viewing windows} 660\end{samepage}\goodbreak 661 662%----------------------------------------------------------------------------- 663\mysubsec{Program Control} 664At the lower left of the control panel are four buttons which 665control various `global' program functions: 666\begin{description} 667 \item[\blob\button{New}] 668 This button will open up a new \afnit controller window. 669 In this way, it is possible to open up image viewers 670 on more than one dataset (or session) at a time. 671 (A~maximum of 5 controller windows can be open at once.) 672 The first controller window and its children are 673 marked with {\tt [A]} in their titlebars; the second 674 is marked with {\tt [B]}, and so forth. 675 676 \item[\blob\button{Views}] 677 This button will open and close the control panels to the 678 right of the first column of the controller window 679 (the first such control panel starts with {\tt Original~View} 680 in the figure above). 681 This function allows you to save some screen space without 682 iconifying the controller window. 683 684 \item[\blob\button{BHelp}] 685 This button allows you to popup a help window for 686 most controls within \afni. Pressing \button{BHelp} 687 will cause the mouse cursor to change to a small hand shape. 688 Pressing mouse Button~1 while the hand is over an \afnit control 689 will popup a help window for that control. Clicking Button~1 inside the help 690 window will dismiss it. 691 692 Button help is implemented as a {\tt help callback} in Motif. If your terminal 693 keyboard is appropriately set up, then pressing the Motif `{\tt Help}' key 694 (often~{\tt F1}) while the mouse cursor is over a button or other widget 695 will also cause the help window for that widget to popup. 696 697 \item[\blob\button{done}] 698 This button will close the controller window when pressed 699 twice within 5 seconds. If this is the 700 only controller window running, \afnit will also exit. 701 (For more details, try using \button{BHelp} on \button{done}.) 702\end{description} 703The \MCW\ logo will appear in the empty space just 704to the right of these four buttons when the program is doing 705some operation that is potentially time consuming. At the 706same time, the mouse cursor will change to a watch shape. 707When the time consuming operation is over, the logo will 708be removed and the cursor will change back to its usual arrow shape. 709 710A trick I sometime use to visually grab attention when a lengthy task 711is underway is to click the \button{Swap} button in an image window. 712This will turn the images to reverse video when the program catches 713up with you. Then \button{Swap} again, and proceed. 714 715%----------------------------------------------------------------------------- 716\mysubsec{Image Display} 717The first column of the controller window contains the controls 718that enable you to open the image viewing windows: the three \button{Image} 719buttons. The windows open separately on the X11 display screen, and 720may be positioned and resized independently. A~little practice is 721needed to decide upon a good layout scheme for these windows. The reason 722\afnit does not define their locations and sizes is that it is often 723desirable expand one window to look at some details, and temporarily 724cover up the other windows. 725 726When an \button{Image} button is highlighted in inverted colors, this 727means that its window is already open. Pressing the button again 728will bring that window to the top of the display --- this is useful 729if the image viewing window is hidden beneath some other window, or 730is iconified. 731 732An image viewing window can be closed by using the \button{Done} 733button along its bottom edge. Alternatively, the window manager 734{\tt Close} or {\tt Delete} function may be used. 735 736\mysubsubsec{Crosshairs and the Viewpoint} 737You can have up to three image viewing windows open at any given time: 738one axial, one sagittal, and one coronal. (In the axial and coronal windows, 739images are displayed with the subject's left\seeme{Left is Right!} 740on the screen right --- the 741usual radiological convention.) These windows are orthogonal slices 742through the 3D dataset. The colored crosshairs that overlay each image 743mark the slices that are visible in the other image windows. The point 744at which the crosshairs intersect is called the {\tt viewpoint}. 745 746In the upper left hand corner of the \afnit controller 747window are displayed the coordinates of the current viewpoint. 748These coordinates are presented in the DICOM 3.0 standard order: 749\begin{description} 750 \item[\blob $x$-axis] is Right (negative) to Left (positive) 751 \item[\blob $y$-axis] is Anterior (negative) to Posterior (positive) 752 \item[\blob $z$-axis] is Inferior (negative) to Superior (positive) 753\end{description} 754Internally, \afnit uses DICOM coordinates to keep track of everything. 755(However, \afnit cannot read DICOM files!) 756 757The button \button{Xhairs} just under the coordinate display 758allows you to switch between 3 modes for crosshair display: 759\begin{description} 760 \item[\blob\button{Off}] Crosshairs are not displayed. 761 \item[\blob\button{Single}] A single crosshair is displayed at the 762 $(x,y,z)$ coordinates of the `viewpoint' 763 ({\it i.e.},~the point whose coordinates 764 are given in the upper left corner). 765 \item[\blob\button{Multi}] If a montage of slices is displayed in an image 766 viewing window, then the orthogonal slices will 767 have crosshairs indicated for all the montaged 768 slices. This is useful for indicating the 769 anatomical location of the montage layout. 770\end{description} 771You may change the crosshair color and central gap 772with the selectors just underneath the \button{Xhairs} button. 773The colors available for the various overlays are built into \afni, 774but can be altered by appropriate changes to your {\tt .Xdefaults} 775file. 776 777If you click the left mouse button while the cursor is in an image 778window, then the crosshairs will immediately jump to that location. 779This will usually mean that the other two windows will display new 780slices. The image windows are always `linked' in this fashion. 781 782The \button{Index} control on the \afnit controller window is 783used to control the time index of the viewpoint. This control 784is only active if the current anatomical dataset is in the 7853D+time format. (The time index can also be controlled in 786a graph viewer.) 787 788\mysubsubsec{Colormap Controls} 789At the right of each image window is a set of buttons that are used 790to control the X11 colormap assigned to the windows. From top to 791bottom, these controls 792\begin{description} 793 \item[\blob\button{Colr}] Change from grayscale to a colorscale, and back. 794 \item[\blob\button{Swap}] Invert the grayscale or colorscale (swap it end-for-end). 795 \item[\blob\button{Norm}] Return the colormap to its initial state (after you 796 mess it up). 797 \item[\blob\button{c}] Change the contrast of the grayscale (a multiplicative 798 change to the intensity of each pixel). 799 \item[\blob\button{b}] Change the brightness of the grayscale (an additive change 800 to the intensity of each pixel). 801 \item[\blob\button{r}] Rotate the grayscale or colorscale. 802 \item[\blob\button{g}] Change the $\gamma$ correction factor for the grayscale. 803 \item[\blob\button{i}] Change the fraction of the viewing window taken up 804 by the image. 805\end{description} 806You may have to drag 807the viewing windows to be larger than their initial 808sizes so that these and the other controls don't obscure each other. 809Changing the colormap in one viewing window affects all the 810other windows from the same \afnit process. 811 812\mysubsubsec{Position Controls} 813Below each image is a slider that indicates the image number in the 814current sequence. By dragging this slider, you can move through the 815slices to any given slice number. In doing so, you will also move the 816crosshairs in the other two image windows. 817 818At the lower right of the image window is an `arrowpad' of four arrows 819arranged in a N--E--W--S pattern, plus a central button. Clicking 820on one of the arrows will cause the crosshair viewpoint to move one 821voxel in the direction pointed by the arrow {\it in that window}. 822Clicking on the central (unlabeled) button causes the crosshair gap 823to close; clicking this button again causes the gap to open up again. 824This is very useful when positioning the crosshairs prior to setting 825an anatomical marker. 826 827\vspace{1ex} 828 829\goodbreak\begin{samepage} 830\centerline{\epsfysize=3.9in\epsffile{afni200_image2.eps}\blob\blob 831 \epsfxsize=1.9in\epsffile{afni200_image3.eps}}\vspace{1ex} 832\centerline{\sf Image viewer \button{Disp} and \button{Mont} control panels} 833\end{samepage}\goodbreak 834 835\mysubsubsec{\button{Disp} Control} 836This button opens up a control panel (pictured above) that lets you change how the 837images will be displayed in this window. 838The \button{Rotation} and \button{Mirror} items control the orientation 839of the image in the window. The \button{No~Overlay} item allows 840you to turn off all color overlay items ({\it i.e.},~crosshairs, 841anatomical markers, and function). 842The \button{Min-to-Max} and \button{2\%-to-98\%} items choose how the 843values in the image array are mapped to grayscale levels on 844the screen. The former choice maps the minimum image value 845to black and the maximum to white; the latter choice computes 846the cumulative histogram of the image and maps the 2\% point to black and 847the 98\% point to white. 848 849The \button{Free Aspect} control lets you resize the image window to 850any bizarre aspect ratio. Normally, the program restricts the 851image window resizing so as to keep the data-voxel to display-pixel 852geometric relationship correct (assuming that display pixels are square!). 853 854The \button{Save} controls actually have nothing to do with image display. 855They are just here because it was a convenient place to put them. 856They control the operation of the \button{Save:} button on the image 857viewing window (next to the \button{Disp} button) --- this is discussed 858below. 859 860The {\tt Tran} menus allow you to pick from a list of image 861transformations. 862The \button{Tran~0D} transformations are all `pointwise'; that is, the 863image intensity output at a given pixel is a function of the 864image intensity input at that given pixel only. The built-in 865\button{Tran~0D} functions are \button{Log10} and \button{SSqrt}, which 866take the common logarithm ($\log_{10}$) of each pixel, and 867take the `signed square root' ($\hbox{sgn}\,(x) |x|^{1/2}$) of each pixel, 868respectively. 869 870\button{Tran~2D} functions are more global image transformations, 871where the image intensity output at a given pixel can be a function 872of other pixels. The only built-in \button{Tran~2D} function is 873\button{Median9}, which replaces each pixel by the median overs 874its $3\times3$ neighborhood. 875 876\afnit plugin authors can add functions 877to these {\tt Tran} menus --- hopefully, they will be documented. 878At the bottom of the \button{Disp} panel are 3 other built-in image processing 879functions: 880\begin{description} 881 \item[\blob\button{Flatten}] Histogram `flattening' (or equalization) is 882 performed on the image prior to display. 883 \item[\blob\button{Sharpen}] High-emphasis `sharpening' is performed on 884 the image prior to display. When printing images 885 on printers with relatively few colors available 886 per pixel, 887 the combination of \button{Median9} and \button{Sharpen} 888 gives nice results. 889 \item[\blob\button{Edge Detect}] Sobel edge detection is performed on 890 the image prior to display. 891\end{description} 892If more than one of these are selected, they are performed in the 893top-to-bottom order, as displayed; also, these operations are performed 894after any {\tt Tran} functions. 895 896\mysubsubsec{\button{Save:} Control} 897This button takes one of three forms, depending on the choices 898made in the \button{Disp} panel: 899\begin{description} 900 \item[\blob\button{Save:one}] 901 This form of the {\tt Save} function 902 is selected by toggling on the \button{Save One} option on the \button{Disp} 903 control panel. 904 In this form, the action is to save the current image to disk. {\it This is 905 the only way provided by \afnit to save a montage layout.} 906 907 This button pops up a little `chooser' window which asks you to input 908 the filename prefix for the output image. The image will be saved 909 in the `raw PNM' format, with the name `{\tt prefix.pnm}'. 910 Images in this format can be converted to other formats (such as {\tt TIFF}) 911 with command line utilities\seeme{{\sf netpbm} and~{\sf xv}} 912 in the {\sf netpbm} package, or the {\sf xv} shareware program. 913 (Images which contain no color will be saved in the PGM format; images 914 with colored pixels will be saved in the PPM format.) 915 916 \item[\blob\button{Save:pnm}] 917 This form of the {\tt Save} function 918 is selected by toggling on the \button{PNM Save} option on the \button{Disp} 919 control panel. 920 In this form, the action is to save a collection of slice images (underlay 921 and color overlay) to disk in 922 the raw PNM format. Even if a montage is being displayed, only 923 single slices will be saved with this function. 924 925 This button also pops up a chooser window which asks you to input the 926 filename prefix for the slice data. If you enter `{\tt fred}' for the prefix, 927 then the $238^{\rm th}$ slice would be named {\tt fred.0238.pnm}. 928 After you type in the desired prefix, you click the \button{Set} button, 929 and then must choose the first and last slice indexes for the save operation 930 from the new choosers that will popup. 931 When you \button{Set} the last slice index, the write-to-disk operation starts. 932 933 \item[\blob\button{Save:bkg}] 934 This form of the {\tt Save} function 935 is selected by toggling off the \button{PNM Save} and 936 \button{Save One} options on the \button{Disp} control panel. 937 In this form, the action is to save the background image 938 pixel values. This does {\it not\/} mean the grayscale intensities displayed in 939 the window. It means that the actual values stored in the dataset {\tt .BRIK} 940 file will be written to disk. 941 942 This button operates similarly to the \button{Save:pnm} function: 943 you must choose a filename prefix, and the first and last slice 944 indexes for the save operation. 945 If \button{Nsize Save} is selected on the \button{Disp} control panel, 946 then the saved images will be expanded to the next largest power of 947 two. 948 949 Using the {\tt Function} controls, you can 950 switch to have the function displayed as the background. 951 In that way, the functional dataset voxel values may be written to 952 disk in slice format. Alternatively, the auxiliary program {\sf from3d} 953 can be used to write slice image files out of a dataset. 954\end{description} 955For all {\tt Save} options, the actual size of the displayed 956window doesn't matter --- 957the images saved to disk will reflect the voxel dimensions of 958the dataset. In particular, if the dataset voxels are not square 959in the plane of view, then the saved image aspect ratio will be 960distorted. The only way to rectify this in \afnit is to switch 961the dataset to be warp-on-demand (using the {\tt Datamode} controls), 962which always interpolates to square pixels. 963 964To actually save the pixels 965as displayed on the screen, some sort of `snapshot' or `window grab' 966utility is needed. If none other is available, the shareware program 967{\sf xv} has a window grab function. Or the {\sf xwd} command line 968program can be used, with appropriate conversion using the {\sf netpbm} 969utilities. For example, the images displayed in this manual were 970captured with variants of the following command line:\\*[.5ex] 971\centerline{\tt 972 xwd -frame|xwdtopnm|pnmdepth 255|ppmtopgm|pgmnorm|pnmtops -noturn>name.eps} 973 974\mysubsubsec{\button{Mont} control} 975This button allows you to make a montage of more than one slice 976in the image window. It pops up a control panel (pictured earlier and below). 977For convenience in programming, only one of the \button{Disp} and \button{Mont} 978control panels can be open at a time (per image viewer). This restriction 979may be lifted in some later version of \afnit (but no guarantees).\\[2ex] 980\goodbreak\begin{samepage} 981\centerline{\epsfxsize=5in\epsffile{afni200_image4.eps}}\vspace{2ex} 982\centerline{\sf Example of slice montage, with \button{Mont} control panel}\vspace{1ex} 983\end{samepage}\goodbreak 984 985\noindent 986The five montage menu controls from top to bottom are: 987\begin{description} 988 \item[\blob\button{Across:}] 989 This controls the number of slices to be displayed horizontally 990 across the window. In the example above, {\tt Across} and {\tt Down} 991 are both set to~3. 992 993 \item[\blob\button{Down:}] 994 This controls the number of slices to be displayed vertically down the window. 995 996 \item[\blob\button{Spacing:}] 997 This controls the frequency with which slices are displayed. {\tt Spacing} 998 of 1 means that adjacent slices will be displayed; 2~means that every other 999 slice will be displayed, etc. The units of this selector are slices, 1000 not millimeters; thus, changing the resolution of a warp-on-demand 1001 dataset (using {\tt Datamode} controls) will change the inter-slice 1002 distance as displayed here. In the example above, the images 1003 are 10 slices apart. Since this is in the Talairach view (which can 1004 be seen from the dataset names in the image viewer titlebar), and 1005 the default voxel size of 1~mm was used, these sagittal slices 1006 are 10~mm apart (center-to-center). 1007 1008 \item[\blob\button{Border:}] 1009 This controls the thickness (in dataset pixels, not screen pixels) 1010 of the border to draw between slice images. In the above example, 1011 this is set to~3. 1012 1013 \item[\blob\button{Color:}] 1014 This controls the color of the border drawn between slice images. 1015 In the above example, this is set to a gray color (under the presumption 1016 that you do not have a color PostScript printer with which to output this manual). 1017\end{description} 1018Across the bottom of the \button{Mont} control panel are four 1019action buttons. Their functions are: 1020\begin{description} 1021 \item[\blob\button{Quit}] 1022 This will close the \button{Mont} control panel, and leave 1023 the current montage layout unchanged. 1024 1025 \item[\blob\button{1x1}] 1026 This will reset the \button{Across:} and \button{Down:} 1027 controls to each be~1. This is simply a convenience, for 1028 when you wish to go back to displaying a single slice. 1029 1030 \item[\blob\button{Draw}] 1031 This will instruct the image viewing window to redraw itself 1032 as currently commanded. (This button will display in inverted 1033 colors until the redraw operation is complete. If the dataset 1034 is warp-on-demand, and many slices are requested, this operation 1035 may take several seconds.) 1036 1037 \item[\blob\button{Set}] 1038 This combines the functions of \button{Draw} and \button{Quit}: 1039 it will redraw the window as commanded, and also close the 1040 \button{Mont} control panel. 1041\end{description} 1042Slices are displayed starting in the 1043upper left corner, then from left-to-right, then top-to-bottom. 1044If the \button{Disp} controls are used to rotate or mirror the images, 1045these operations apply to each slice individually, not to the montage 1046as a whole. 1047 1048If the number of slices displayed ({\tt Across}$\,\times\,${\tt Down}) 1049is large, and {\tt Spacing} is large, then the extreme slices requested 1050may be outside the dataset. In such a case, 1051the toggle \button{Wrap} on the \afnit controller window (next to the 1052\button{Gap} menu) controls what happens. If \button{Wrap} is turned 1053on, then slices requested past the edge of the dataset will be wrapped 1054back to the opposite edge. If \button{Wrap} is turned off, then 1055slices requested past the edge of the dataset will be filled with zeros. 1056 1057The only slice image which will have crosshairs displayed is the one 1058containing the current viewpoint. Clicking mouse Button~1 in 1059any slice image will cause the current viewpoint to jump to that 1060location in that slice. This will also cause that slice to jump 1061to the center position in the montage layout. 1062 1063If the \button{Xhairs} button is set to \button{Multi}, then orthogonal 1064image viewing windows will show crosshairs for each slice drawn 1065in the montaged window. 1066 1067The only way that \afnit provides to save a montage display to 1068disk is the \button{Save:one} function, described earlier. 1069This function (as all {\tt Save} functions) saves the 1070image at its `natural' size --- one output pixel per dataset pixel, 1071regardless of any window resizing you may have imposed. 1072 1073\mysubsubsec{Popup Menu} 1074If you click-and-hold mouse Button~3 (usually the rightmost button) 1075while the cursor is in an image 1076window, a menu will popup at that point. The first item on the 1077menu is \button{Jumpback}. This will reset the crosshair viewpoint to 1078the last location clicked upon. The main use of this feature is to 1079recover from accidentally clicking Button~1 in an inconvenient location. 1080 1081The second item on the popup menu is \button{Jump to}. This will popup 1082a window in which you may enter the $(x,y,z)$ coordinates (DICOM order) 1083of the point to which you wish to set the crosshair viewpoint. 1084(One application: the cluster locations reported by {\sf 3dclust} 1085may be pasted into the window.) 1086 1087The third item on the popup menu is \button{Image display}. This will collapse 1088the viewing window to just include the image. Selecting this item again 1089will bring the viewing window controls back. 1090(One application: making snapshots of nice functional displays.) 1091{\bf N.B.}:~This function does not work well on all X11 displays, for 1092unknown reasons. It may collapse the image window to zero size, which 1093is slightly inconvenient. 1094 1095When\seeme{Seeing individual voxel values} 1096all three viewing windows ({\tt Axial}, {\tt Sagittal}, and {\tt Coronal}) 1097are open, the bottom item on the popup 1098menu will contain a display of the background pixel value at the center 1099of the crosshairs. (The background is normally an anatomical image, but 1100can also be switched to be a functional image using the {\tt Function} controls.) 1101 1102\mysubsubsec{Resizing Image Windows} 1103When a viewing window is first opened, it is at the `natural' dimension 1104for the resolution set in the {\tt Datamode} controls (or in the dataset 1105header file, if viewing from the data brick). When jumping from one 1106coordinate system to another, or from one dataset to another, the 1107program attempts to keep the on-screen pixels/mm the same, so that no 1108sudden scale changes occur. 1109 1110When the viewing windows are resized, the images are stretched by 1111nearest-neighbor resampling. This has nothing to do with the resampling 1112modes set in the {\tt Datamode} and {\tt Function} controls. For example, 1113the crosshairs are exactly one pixel thick in the `natural' dimension of 1114each window. If a window is stretched, then the crosshairs will become 1115thicker. If a window is shrunk, the crosshairs may disappear when they 1116are missed during the display resampling. 1117 1118When viewing from the data brick, and when the data voxels are not cubical, 1119the viewing windows will similarly stretch the coarser direction to maintain 1120the correct physical aspect ratio on the screen (assuming that the X11 pixels 1121are square). This can produce a blocky looking image. To force a smoothing, 1122the {\tt Warp~on~Demand} mode should be used. 1123\vspace{2ex}\goodbreak\begin{samepage} 1124\centerline{\epsfxsize=5in\epsffile{afni200_graph1.eps}}\vspace{1ex} 1125\centerline{\sf Sample Graphing Window} 1126\end{samepage}\goodbreak\vspace{1ex} 1127 1128 1129%----------------------------------------------------------------------------- 1130\mysubsec{Graph Display} 1131When the current anatomical dataset is 3D+time and is not set to 1132warp-on-demand (using the {\tt Datamode} controls), then the 1133three \button{Graph} buttons (next to the \button{Image} buttons) will be activated. 1134These allow the display of graphs of voxel intensity vs.\ time. 1135(Although \afnit graph windows look very like the graph window in the auxiliary program 1136{\sf FD2}, there is at least one major difference: \afnit graph windows 1137can be resized\seeme{}.) 1138 1139The above figure shows a sample, with $3\times3$ data time series sub-graphs displayed. 1140The central sub-graph is bordered in a light color (here, a~shade of gray). 1141This sub-graph is a plot of the data time series at the viewpoint voxel --- the one 1142displayed at the crosshairs in the image viewing windows. The other sub-graphs 1143are of neighboring pixels, in this case in the sagittal plane. (In the 1144corresponding sagittal viewing window, the crosshairs will show a box 1145outlining the pixels being graphed.) If you shift the viewpoint in 1146an image viewer, then the graph viewpoint will shift accordingly. 1147 1148The voxel indexes of the viewpoint are shown at 1149the lower left edge of the graph display; for example, {\tt Z:~8} means 1150that this is slice number~8 (counting from~0). 1151Then the spacing between vertical grid lines (in time steps) is shown; in this 1152case, there is a grid line every $10^{\rm th}$ time step. The {\tt Num:} 1153label shows the number of points in the time series. 1154At the bottom of the graphs is a label starting with {\tt index=}. 1155This shows the time index of the current point (which can be altered 1156with the \button{Index} control on the \afnit controller window), 1157the value of the time series at that point, and the time coordinate 1158of that time index (in this case, {\tt 211.25} seconds). The current time 1159point is displayed with a little red ball overlaid n the central sub-graph 1160(in the figure above, red is rendered in gray). 1161 1162At the\seeme{Graph scaling} 1163left of the graphs are two numeric labels; in this case, {\tt 802} 1164and {\tt 891} (${}={\tt 802}+{\tt 89}$). 1165This shows the vertical range of the central sub-graph. 1166In this display, each sub-graph has its minimum point at the 1167bottom of its sub-window. {\it Every sub-graph has the same vertical 1168scale factor, but has a different vertical offset.} This is so 1169that they will all fit in the same display easily. This can be 1170confusing when comparing levels of adjacent pixels: it is important 1171to realize that there can be an arbitrary constant offset between 1172adjacent sub-graphs. 1173The \button{Baseline} 1174button on the \button{Opt} menu can be used 1175to ensure that all sub-graphs are plotted 1176with the same vertical offset. 1177 1178\mysubsubsec{Button Clicks in a Graph} 1179At the lower left of the graph window is a logo, whose main function is to 1180remind you from which plane these graphs are drawn. This can be 1181suppressed (for window snapshot purposes) by clicking Button~1 on the 1182logo. Clicking Button~1 in that space again will restore the logo. 1183(The \button{FIM} and \button{Opt} buttons will also be hidden and 1184restored by these operations.) 1185 1186Clicking Button~1 on the central sub-graph will cause the time index 1187to jump to that point. If the Shift or Ctrl key is pressed while 1188doing this, the time index instead will move up or down by~1, in 1189whichever direction corresponds to the mouse cursor relative to 1190the time index indicator ball. 1191 1192Clicking Button~1 on any other sub-graph 1193will cause the spatial viewpoint to jump to that location, without 1194changing the time index. Clicking Button~3 on a sub-graph will popup 1195a small window with some statistics about that time series. 1196 1197Some keystrokes, if pressed while the graph window has `focus', 1198will carry out certain functions. These functions are also available from 1199the \button{Opt} menu, and are described below. 1200\vspace{2ex}\goodbreak\begin{samepage} 1201\centerline{\epsfxsize=5in\epsffile{afni200_graph2.eps}}\vspace{1ex} 1202\centerline{\sf Graphing \button{FIM} (left) and \button{Opt} (right) menus} 1203\end{samepage}\goodbreak 1204 1205\newcommand{\bitem}[1]{\item[\blob\button{#1}]} 1206\newcommand{\kq}[1]{`{\tt #1}'} 1207 1208\mysubsubsec{\button{Opt} menu} 1209The items on this menu control the appearance of the graphs: 1210\begin{description} 1211 1212 \bitem{Scale} This is a `pullright' menu, used to control the 1213 vertical scale of the graphs. The figure above 1214 shows the sub-menu that results from pulling-right 1215 on this item. The \button{Down} and \button{Up} 1216 buttons will cause the graphs to scale down (shrink) 1217 and up (grow). Pressing the keys \kq{-} and \kq{+} 1218 in the graph window will have the same effects. 1219 The \button{Choose} button will cause a little 1220 chooser to popup, which allows you set the vertical 1221 scale factor manually. If the scale factor 1222 is positive, then it is the number of screen pixels 1223 to use per unit of data. If the scale factor is 1224 negative, its absolute value is the number of units 1225 of data per screen pixel. Thus, increasing the 1226 scale factor will cause the graph to grow vertically. 1227 There is no provision in \afnit for automatic 1228 scaling to fit the dataset range; each graph window 1229 starts with its scale factor set to~1. Judicious 1230 use of the \kq{-} or \kq{+} keys may be needed to 1231 make a graph visible. 1232 1233 \bitem{Matrix} This pullright menu is used to control the number 1234 of sub-graphs displayed. It shows a sub-menu 1235 similar to the \button{Scale} sub-menu. 1236 In this case, \button{Down} (keystroke~\kq{m}) 1237 will cause the number of sub-graphs displayed 1238 across and down to decrease by~1; \button{Up} 1239 (keystroke~\kq{M}) will increase the array size by~1; 1240 \button{Choose} will let you directly set the 1241 number of sub-graphs. 1242 1243 \bitem{Grid} This pullright menu lets you control the spacing 1244 (in time steps) between vertical grid lines. 1245 1246 \bitem{Slice} This pullright menu lets you move the spatial viewpoint 1247 between slices in the dataset (moving within a slice is controlled 1248 by Button~1 clicks, as described above). 1249 1250 \bitem{Grid Color} This item just rotates the vertical grid color between the 1251 available choices. 1252 1253 \bitem{Baseline} This item switches the way that graph baselines 1254 are computed. By default, each sub-graph has the 1255 minimum value of its time series mapped to the bottom 1256 of its sub-window. By pressing this item 1257 (or the \kq{b} key), the sub-graphs will switch to 1258 having a common baseline. That is, the minimum 1259 value in {\tt all\/} the displayed time series will mapped 1260 to the bottom of each sub-window. (In many cases, doing 1261 this will require scaling down the graphs with the \kq{-} key.) 1262 Choosing this item again will restore the original 1263 graph baseline mode. 1264 1265 \bitem{Write Center} Selecting this item (or pressing the \kq{w} key) will 1266 write the dataset time series in the central sub-graph to 1267 disk, in a filename like {\tt 033\_034\_008.suffix.1D}\@. 1268 The \kq{suffix} 1269 is selected by the next menu item, \button{Set 'w' Suffix}, 1270 and the prefix numbers are from the voxel spatial index 1271 in the dataset. 1272 The output file is ASCII, one number per line. 1273 ({\bf N.B.}:~the output is the dataset time series, 1274 and is unaffected by the {\tt Tran} transformations below.) 1275 1276 \bitem{Tran 0D} This item is the same as the \button{Tran 0D} item on 1277 the image viewer \button{Disp} panel. It allows the 1278 application of a pointwise transformation function to 1279 the time series before graphing occurs. 1280 1281 \bitem{Tran 1D} This item allows the application of general 1282 transformations to the time series before graphing. 1283 The two built-in \button{Tran 1D} functions are 1284 \button{Median3} and \button{OSfilt3}, which are 1285 order-statistics smoothing filters using a 3-wide neighborhood. 1286 (In addition, the {\tt plug\_lsqfit} plugin defines two 1287 more functions, which can be used to do linear least squares 1288 fits of various functions to dataset time series.) 1289 1290 \bitem{Double Plot} Normally, if a \button{Tran 1D} transformation is 1291 applied, the graph of the transformed data replaces 1292 the graph of the original data. If this item is 1293 selected, then both graphs will be displayed. 1294 (This was added to be able to see the least squares 1295 fits from {\tt plug\_lsqfit} plotted over the input data.) 1296 1297 \bitem{Done} This closes the graphing window (the keystroke \kq{q} has the 1298 same effect). 1299\end{description} 1300 1301 1302\mysubsubsec{\button{FIM} menu} 1303This menu is used to control the computation of functional datasets (of the 1304{\tt fico} type) from 3D+time datasets. Some of the functions of this 1305menu are duplicated on the {\tt Function} control panel \button{FIM} menu. 1306 1307\displayline{Theory of {\tt FIM}} 1308If $x_n$ is a data time series, and $r_n$ is a known reference (or ideal) 1309vector corresponding to the expected activation time course, then 1310the statistical model for $x_n$ is 1311\begin{eqnarray*} 1312 x_n &=& \alpha r_n + a + b n + \eta_n \qquad (n=0,1,\ldots) \\* 1313 \eta_n &\sim& N(0,\sigma^2) \qquad\qquad\qquad \hbox{i.i.d.} 1314\end{eqnarray*} 1315where $\alpha$ is the unknown amplitude of the activation, 1316$a$~is the unknown mean signal level, $b$~is the unknown linear drift in 1317time, and $\sigma^2$ is the unknown noise variance. The correlation 1318method~\cite{Bandettini,Cox-Rtime} computes the sample 1319correlation coefficient between $x_n$ and $r_n$, and uses that to 1320determine the significance of the hypothesis that $\alpha \neq 0$. 1321 1322\displayline{Time Series Files} 1323\MCW$\!$ \afnit stores single time series (such as $r_n$) in the format 1324described earlier: ASCII format, one number per line. A~number greater 1325than $33333.0$ means that particular point in time should be ignored. 1326This convention goes back to the original {\sf fim} program in 1990, and 1327is due to Andrzej Jesmanowicz of \MCW. 1328(The \button{Write Center} button described above is one way to create 1329such a time series file. Another is with the auxiliary program {\sf sqwave}. 1330Yet another is simply to use a text editor, such as {\tt vi}.) 1331 1332When \afnit starts up, it will read in time series files from the session 1333directories that it opens. The program will attempt to read a time series 1334from any file whose name ends in \kq{.1D}. 1335These time series will be pooled into 1336a `library', whose entries can be selected from a menu, as described below. 1337 1338You may wish to keep some time series files stored separately from any 1339particular session directory. \afnit can be made to read such files 1340by defining the shell environment variable {\tt AFNI\_TSPATH}. 1341Like the executables variable {\tt PATH}, this is a colon-separated 1342list of directories in which to search for particular files: in this 1343case, \kq{*.1D} files. For example:\\*[1ex] 1344\centerline{\tt setenv AFNI\_TSPATH \$\{HOME\}/timeseries:./}\vspace{1ex} 1345will cause \afnit to search for time series in the {\tt timeseries} directory under 1346your home directory, and in the current working directory. 1347Normally, you would put this type of command in your {\tt .cshrc} file so that 1348it would always be executed when you login (I'm assuming 1349that you use the C-shell {\tt csh} or its superset,~{\tt tcsh}.) 1350 1351I said above that time series files are stored as one number per line. 1352This is true of the older programs such as {\sf fim2}, {\sf FD2}, etc\@., 1353but \afnit itself allows more than one number per line. In this way, more 1354than one time series can be stored per file: 1355\begin{samepage}\begin{verbatim} 1356 99999 99999 99999 99999 1357 99999 99999 99999 99999 1358 0 0 0 0 1359 10 0 0 0 1360 10 10 0 0 1361 0 10 10 0 1362 0 0 10 10 1363 10 0 0 10 1364 10 10 0 0 1365 ... ... ... ... 1366\end{verbatim}\end{samepage} 1367The above example defines four time series in one file. Each one 1368starts with two {\tt 99999}s, which indicates that these two points 1369should not be used in any analysis with these time series. 1370The subsequent values could be used as an ideal waveform in {\tt FIM} 1371analysis. In this example, each timeseries (after the first) is a time-delayed copy 1372of the one to the left. 1373A~Unix command of the form\\[1ex] 1374\centerline{\tt pr -m -t -s" " a.1D b.1D c.1D d.1D > abcd.1Dx}\vspace{1ex} 1375can be used to `glue' multiple files together horizontally 1376into a single file with multiple columns. You should be sure that all the files have the 1377same number of lines before using the {\tt pr} command, which is 1378really a program designed for formatting files for printout. 1379(On SGI workstations, the {\tt pr} command has a small upper limit 1380to the number of columns it will output. On such systems, it may 1381be necessary to `paste up' a large number of columns in two stages.) 1382 1383To allow such time series files to be distinguished from `ordinary' files 1384(containing only one time series), \afnit allows the use of the filename 1385suffix \kq{.1Dx}, as in the {\tt pr} command example above. 1386However, there is no difference between the \kq{.1Dx} files and 1387the \kq{.1D} files as far as \afnit is concerned: it is perfectly 1388acceptable to have a multi-column time series filename end 1389in \kq{.1D}, or to have a single column time series filename end 1390in \kq{.1Dx}. 1391 1392At this release, only the actual \afnit program will recognize 1393these multi-column time series files correctly. Other programs, such 1394as {\sf fim2}, still require each file to contain only one time series. 1395\vspace{2ex}\goodbreak\begin{samepage} 1396\centerline{\epsfxsize=2.5in\epsffile{afni200_graph3.eps}}\vspace{1ex} 1397\centerline{\sf Sample time series chooser menu} 1398\end{samepage}\goodbreak 1399 1400\displayline{\button{FIM} Menu Items} 1401\begin{description}\vspace*{-3.2ex} 1402 \bitem{Pick Ideal} This button pops up a chooser window which allows you 1403 to select a time series file to be used as the 1404 ideal waveform $r_n$ 1405 (an example of this chooser is shown above). 1406 With each time series filename is shown the 1407 dimensions of the time series. In the example, 1408 the file {\tt qqq.1Dx} has 68 points in time (68 lines of data) 1409 and has 13 columns. 1410 1411 If the ideal time series has more than one column, the 1412 {\tt FIM} computations compute the correlation coefficient 1413 of each voxel with each column separately. Then the 1414 column that is most highly correlated with the voxel 1415 time series is selected to compute the $\alpha$ for 1416 that voxel; $\alpha$ becomes the `intensity' and 1417 the correlation coefficient becomes the second sub-brick 1418 stored in the resulting {\tt fico} dataset. 1419 1420 When the ideal time series is selected, it will be plotted 1421 at the top of the center sub-graph window, in red. 1422 Sections of it that are marked to be ignored will 1423 be plotted in blue. If there is more than one 1424 column in the ideal time series, by default they will all 1425 be plotted. 1426 1427 (By the way, the \button{Plot} button on the time series 1428 chooser is permanently deactivated. I~intended to 1429 provide the ability to preview a time series in a little 1430 window, but never got around to implementing it. 1431 The button remains to remind me of this, and to remind me 1432 of all my other goals for \afnit that have yet to come to fruition.) 1433 1434 \bitem{Pick Ort} In the mathematical model for $x_n$ given earlier, note 1435 that we included $a + b n$ in the model to represent 1436 the unknown baseline and drift of the data time series. 1437 These are `orts': time series to which the data time series 1438 is orthogonalized prior to the correlation coefficient 1439 calculation~\cite{Cox-Rtime}. \afnit always orthogonalizes 1440 the data to these two time series. In addition, you 1441 may specify another time series to which the data time 1442 series in each voxel should be orthogonalized. 1443 If the ort time series has more than one column, each 1444 data time series will be orthogonalized to all columns 1445 prior to the correlation coefficient calculation. 1446 1447 When the ort time series is selected, it will be plotted 1448 in the middle of the center sub-graph window, in green. 1449 Sections of it that are marked to be ignored will 1450 be plotted in blue. 1451 1452 \bitem{Edit Ideal} This pullright sub-menu (shown in a figure far above) 1453 is used to control the ideal waveform. 1454 The menu sub-items are: 1455 \begin{itemize} 1456 \item \button{Ideal = Center} will take the central sub-graph data time 1457 series and make it the ideal time series. 1458 1459 \item \button{Ideal+= Center} will take the central sub-graph data time 1460 series and average it into the ideal time series. In this way, 1461 it is possible to select a group of voxels (one at a time) 1462 and average them together to make a single waveform. 1463 1464 \item \button{Smooth Ideal} will apply a 3-neighborhood order-statistics 1465 filter to smooth the current ideal waveform. If the 3 points 1466 input are $a$, $b$, and $c$, then 1467 the output is 1468 \begin{displaymath} 1469 y_n = 0.70 \cdot {\rm median}\,(a,b,c) 1470 + 0.15 \cdot {\rm max}\,(a,b,c) 1471 + 0.15 \cdot {\rm min}\,(a,b,c) \;. 1472 \end{displaymath} 1473 1474 \item \button{Shift Ideal} will popup a control panel that allows you 1475 to generate shifted copies of the current ideal waveform. 1476 All the shifted copies form a multi-column time series. 1477 In this way, it is possible to construct a single column ideal 1478 waveform, use \afnit to create time shifted copies of it, 1479 and then correlate them all with the data, picking out the 1480 `best' time shift at each voxel. 1481 1482 \item \button{Clear Ideal} will clear the current ideal waveform; that is, 1483 the ideal waveform will be undefined after this is pressed. 1484 The graph of the ideal waveform will also be cleared. 1485 1486 \item \button{Clear Ort} will clear the current ort waveform. 1487 1488 \item \button{Read Ideal} allows you to read in the ideal waveform 1489 from an external file. 1490 1491 \item \button{Write Ideal} allows you to write the current ideal waveform 1492 to disk. In this way, an ideal created from the current dataset 1493 can be saved for later analysis. 1494 1495 \item \button{Store Ideal} allows you to store the current ideal waveform 1496 into the \afnit menu for possible later selection. 1497 (The only way to create an ort from a dataset is to first create 1498 it as an ideal, then to store it with this button, and then 1499 to use \button{Pick Ort} to get it off the time series menu.) 1500 The {\tt Write} and {\tt Store} operations are independent: 1501 writing to disk does not imply storing in the menu system, or 1502 {\it vice versa}. 1503 \end{itemize} 1504 1505 \bitem{Ignore} This pullright menu allows you set the number of points 1506 to be ignored at the beginning of each time series. 1507 (This is often desirable, since in rapid scan MRI the 1508 longitudinal magnetization may take several images 1509 to reach steady state.) Time points that are ignored --- either 1510 through the use of this control or large values (33333+) in 1511 the ideal waveform --- will be skipped in the correlation 1512 analysis. In addition, points that are ignored with 1513 this control will not be graphed. This allows 1514 large initial transients to be suppressed, and makes 1515 it easier to read the graphs. 1516 1517 \bitem{FIM Plots} This pullright menu allows you to specify whether 1518 all the columns of the ideal and ort waveforms should 1519 be plotted, or just the first columns. 1520 1521 \bitem{Compute FIM} This will start the correlation calculations. 1522 At the least, an ideal waveform must be specified 1523 before this button will work. You may also wish 1524 to set the {\tt Ignore} value and the ort waveform 1525 prior to these computations. 1526 1527 The calculations use the recursive method of Cox 1528 {\it et al.}~\cite{Cox-Rtime}. While they are 1529 proceeding, a~`progress meter' will display 1530 over the titlebar of the \afnit controller window. 1531 When the results are finished, the new {\tt fico} 1532 dataset will become the current functional 1533 dataset, and can be examined immediately in 1534 the image viewers. If the input 3D+time dataset 1535 were named {\tt elvis+orig}, then the {\tt fico} 1536 dataset will be named {\tt elvis@\#+orig}, where 1537 {\tt \#} will be one of {\tt 1}, {\tt 2}, {\tt 3},~\ldots. 1538 If desired, the {\tt Dataset Rename} ({\tt plug\_rename.c}) 1539 plugin can be used to change the prefix to something more 1540 convenient. 1541\end{description} 1542 1543%----------------------------------------------------------------------------- 1544\mysubsec{Viewing Controls} 1545The second column of the \afnit control window contains many controls 1546that affect how the datasets are viewed, transformed, and output. 1547 1548\mysubsubsec{View Modes} 1549At the top of this second column are the view mode controls. These 1550let you switch between the available views: {\tt Original}, 1551{\tt AC-PC aligned}, or {\tt Talairach}. 1552If a particular view is not available for the currently active 1553anatomical dataset, then the corresponding button will be inactive (grayed-out). 1554 1555When you switch view modes, you will see that the windows change size. 1556That is because in the {\tt +acpc} and {\tt +tlrc} views, the images are 1557clipped to the known dimensions of human heads. This is to save space 1558when such datasets are written to disk. The window resizing is set up to preserve 1559the pixels-per-brain-millimeter ratio. The program also attempts to keep 1560the crosshair viewpoint 1561in the same anatomical location as they were in the previous view 1562mode, but they may shift slightly. Since the {\tt +orig} view will 1563generally be rotated from the {\tt +acpc} and {\tt +tlrc} views, keeping 1564the viewpoint at the same location does {\it not\/} mean keeping the 1565slices in the same location. 1566 1567\mysubsubsec{\button{Define} Controls} 1568Each \button{Define} button opens up another control panel to the right 1569of this second column. They are discussed separately later. Note 1570that to close a {\tt Define} control panel, you press its button again. 1571To help with this, the \button{Define} buttons that are currently open are 1572displayed in inverted colors. You may open more than one {\tt Define} control 1573panel at a time, but they will all lie on top of each other (most recently opened 1574panel on top). 1575 1576\mysubsubsec{\button{Switch} Controls} 1577These controls let you choose which session, and which datasets from 1578that session, you are viewing at any given moment. They popup 1579a chooser that lets you cycle between the session directories, 1580the anatomical dataset prefixes, and the functional dataset prefixes, 1581respectively. 1582 1583When you switch datasets, \afnit may be forced to switch views as 1584well. This can occur if the new dataset doesn't exist in the view 1585mode you were formerly in. For example, if you save several 1586functional datasets in the Talairach view mode 1587(using the {\tt Datamode} controls), then combine them with {\tt 3dmerge}, 1588the result will only exist in the {\tt +tlrc} view. You can only 1589view this functional dataset when the view mode corresponds, so the 1590program will jump to that mode. If such a view mode switch occurs, 1591the program will beep when it makes the transition. 1592 1593%----------------------------------------------------------------------------- 1594\mysubsec{\button{Define Markers}} 1595The transformation to the AC--PC aligned view, and from there to the 1596Talairach view, is accomplished by means of `markers'. These are anatomical 1597landmarks that you manually select using the control column opened up 1598by this control. 1599 1600Only 3D anatomical datasets can have markers set; 3D+time datasets 1601have the markers disabled. It is only possible to transform a 3D+time 1602dataset to Talairach coordinates using a `parent' 3D dataset, 1603as described earlier (the \kq{X}s and \kq{O}s diagram). 1604 1605\mysubsubsec{Markers for the AC--PC Aligned Transformation} 1606The AC--PC aligned view mode is defined by a rigid body transformation 1607that makes the AC--PC line the new $y$-axis, makes the longitudinal 1608fissure the new $xz$-plane, and makes the line perpendicular to that 1609the new $x$-axis (right-to-left). The new origin is put at the 1610intersection of the AC--PC line and the vertical line passing through 1611the posterior margin of the~AC. See \cite{Talairach} for details. 1612\vspace{2ex}\goodbreak\begin{samepage} 1613\centerline{\epsfxsize=5in\epsffile{afni200_acpc.eps}}\vspace{1ex} 1614\centerline{\sf Cartoon of central brain, showing key anatomical locations} 1615\end{samepage}\goodbreak 1616 1617To select the landmarks, you must first choose \button{Allow edits}, so 1618that \afnit will let you change the markers. After that, you 1619choose the five landmarks: 1620\begin{description} 1621 \item[\blob AC superior edge] The highest point on the anterior commissure, 1622 in the mid-sagittal plane. 1623 \item[\blob AC posterior margin] The rearmost point on the anterior commissure, 1624 in the mid-sagittal plane. 1625 \item[\blob PC inferior edge] The lowest point on the posterior commissure, 1626 in the mid-sagittal plane. 1627 \item[\blob First mid-sag pt] Two points are required in the longitudinal 1628 fissure --- they are used to define the new $z$-axis. (Two points 1629 are required to make sure that the new vertical plane is defined 1630 adequately; the mismatch between the AC--PC line and these two 1631 points must be less than~$2^\circ$.) 1632 \item[\blob Another mid-sag pt] Should be at least 20 mm away from the first one. 1633\end{description} 1634\goodbreak\begin{samepage} 1635\centerline{\epsfxsize=6.4in\epsffile{afni200_mark1.eps}}\vspace{1ex} 1636\centerline{\sf Original (left) and AC-PC Aligned (right) \button{Define Markers} Control Panels} 1637\end{samepage}\goodbreak 1638You select a landmark by depressing its button, then moving the crosshairs 1639to the desired location, then clicking the \button{Set} button. A~visible 1640marker will appear. You can reset this point, or \button{Clear} it. When a 1641marker is set, its toggle button will appear in inverted colors. 1642 1643The atlas definitions of the marker locations are always in terms of 1644a boundary. That is slightly ambiguous when it comes to discrete 1645images: do you mark the last voxel visible in the structure, or the first 1646voxel just outside the structure? 1647My arbitrary solution to this problem is always 1648to mark the last voxel visible in the structure. For example, in 1649marking the `top' of the AC, I~move up until it is just no longer visible 1650in the axial image. Then I drop back down one axial slice. 1651It is possible to use 1652`warp-on-demand'\seeme{Sub-voxel marker locations} 1653to place markers at subvoxel locations --- see the {\tt Datamode} controls. 1654 1655On MR images with 1 mm$^3$ voxels and with good gray-white matter 1656contrast, it is usually quite easy to set the 1657AC markers. (At \MCW, we use a GE Signa SPGR sequence for this purpose.) 1658The PC is harder to spot, but it is always near the 1659top of the cerebral aqueduct (in subjects with normal anatomy --- it might 1660be displaced by some pathological conditions; if you suspect this has 1661happened, consult a neuroradiologist immediately!). 1662Examination of the sample \afnit dataset, and some consultation with a 1663neuroanatomy textbook will probably be helpful 1664in learning to recognize the required anatomical landmarks. 1665 1666\mysubsubsec{Making the Transformation} 1667When all markers are set, the \button{Quality?} button will become active. 1668This button will check the marker set for elementary consistency. 1669If the markers {\it don't\/} pass the test, an error message pops up 1670to explain what happened. If they do pass the test, then the 1671\button{Transform Data} button becomes active. When you press this, the 1672new dataset will be created (in this case, the {\tt +acpc} view of the 1673anatomical dataset you were just marker-ing). 1674 1675This new dataset will {\it not\/} have a {\tt .BRIK} file 1676on disk, just a {\tt .HEAD} file. When \afnit comes to display this 1677dataset, it will simply transform the needed data from the {\tt +orig} 1678dataset. If you wish, you may save the data voxels in the new view 1679to disk using the {\tt Datamode} controls. 1680(If you wish to manipulate a transformed 1681dataset using the auxiliary programs, you will have 1682to save the data voxels to disk.) 1683 1684\mysubsubsec{Transformation to Stereotaxic ({\it i.e.}, Talairach) Coordinates} 1685After you create the AC--PC aligned view, you can switch to it with 1686the \button{AC-PC Aligned} button. 1687At this point, you can set markers for the scaling to the 1688Talairach view. Six markers are required to define the bounding box 1689of the cerebral cortex. These should be set quite carefully, since 1690it is often easy to mistake the sagittal sinus for cortex, which would 1691give an erroneously large box in the $+z$-direction. Generally, I~find 1692that the most inferior point (in one of the temporal lobes) is the hardest to pick out. 1693 1694In the {\tt +acpc}~$\to$~{\tt +tlrc} transformation marker control 1695panel, a~toggle switch labeled \button{Big Talairach Box} appears 1696just below the \button{Transform Data} button. In the earliest versions 1697of \afni, the brain data was clipped at 55 mm inferior to the AC-PC line, 1698this being the location of the bottom of the Talairach-Tournoux atlas figures. 1699In subsequent work, we found this was inadequate for cerebellar 1700imaging. The new default clipping level is 65 mm inferior to the AC-PC line, 1701and this is referred to as the {\tt Big Talairach Box}. Datasets {\tt .BRIK}s 1702created with the old (small) box size are smaller than the new box size. 1703There is no way to mix old and new box size datasets together when 1704using the auxiliary analysis programs such as {\sf 3dANOVA}. 1705For this reason, and to maintain compatibility with old analyses, 1706it is possible to write out old box size dataset {\tt .BRIK}s 1707by toggling this switch off. For all future work, I~strongly recommend 1708using the new Talairach box size. 1709 1710The transformation carried out is precisely the one described in 1711\cite{Talairach}, and I recommend that anyone using \afnit read this atlas. 1712The dataset is divided into 12 subvolumes: 1713\begin{itemize} 1714 \item In $x$: Right-to-Midsagittal, Midsagittal-to-Left 1715 \item In $y$: Anterior-to-AC, AC-to-PC, PC-to-Posterior 1716 \item In $z$: Inferior-to-AC, AC-to-Superior 1717\end{itemize} 1718Each region is scaled separately to match the millimetric coordinates 1719in the atlas:\\[.5ex] 1720\centerline{\begin{tabular}{ll} 1721 $x$ axis: AC--PC line to most left point of cerebrum & = \ 68 mm \\ 1722 $x$ axis: AC--PC line to most right point of cerebrum & = \ 68 mm \\ 1723 $y$ axis: Most anterior point of cerebrum to AC & = \ 70 mm \\ 1724 $y$ axis: AC to PC & = \ 23 mm \\ 1725 $y$ axis: PC to most posterior point of cerebrum & = \ 79 mm \\ 1726 $z$ axis: Most inferior point of cerebrum to AC--PC line & = \ 42 mm \\ 1727 $z$ axis: AC--PC line to most superior point of cerebrum & = \ 74 mm 1728\end{tabular}}\vspace{0.5ex} 1729The atlas brain is from an adult female, and so a typical adult male brain will be 1730slightly compressed by these standard measurements. 1731(Any jokes at this point will be sternly dealt with.) 1732This transformation is then combined with the 1733{\tt +orig}~$\to$~{\tt +acpc} transformation, so that the data viewed 1734in the Talairach mode is only interpolated once, not twice. 1735 1736The whole procedure to produce the {\tt +tlrc} view from the 1737{\tt +orig} view only takes a few moments, once you become adept at 1738recognizing the requisite anatomical landmarks. 1739 1740You will find that the marker toggle buttons and set/clear 1741buttons are duplicated on the popup menu from the imaging windows. 1742This is for convenience, since it is often necessary to peer closely 1743at the screen to decide on a marker point, and I personally find it 1744annoying to have to switch my attention to another window in order 1745to set the marker. Also, note that depressing the toggle button (in the 1746marker control column or on the popup menu) for 1747an already set marker will cause \afnit to jump the crosshair viewpoint 1748to that marker location. 1749 1750Finally, note that there are no markers available to be set in the 1751Talairach view mode. At present, there are no transformations beyond 1752this one --- maybe someday. 1753 1754\mysubsubsec{Re-transformation and Re-creation of Datasets} 1755If you decide to re-mark and re-transform an anatomical dataset, then 1756the old transformed version will be deleted from disk before the new 1757version is made. Not only that, 1758but all the automatically manufactured transformed datasets that follow 1759on this transformation will also be destroyed and remade. 1760This can be disconcerting at first, but it is the only logical course 1761of action for \afnit to take --- otherwise, the transformed functional 1762datasets would have been made with a different transformation than the 1763new anatomical dataset on which they will be overlaid. 1764 1765The only time this destruction is inappropriate is when the 1766functional datasets in the transformed view are not in fact transformations 1767from original datasets in the same session. This could happen if you 1768copied a {\tt +tlrc} dataset into a session from another directory, or 1769if you created a {\tt +tlrc} dataset using {\sf 3dmerge}, say. 1770\afnit will not delete a dataset if there is no `parent' dataset from which 1771it was warped. 1772 1773\afnit will not let you mark and transform more than one anatomical dataset 1774per session. Once you have transformed one dataset in a session, 1775the others will be off-limits to direct marking and transformation. 1776Their transformations will be derived from the `master' dataset 1777that you mark first. 1778\vspace{2ex}\goodbreak\begin{samepage} 1779\centerline{\epsfxsize=3.4in\epsffile{afni200_func.eps} 1780 \blob\blob 1781 \epsfxsize=1.9in\epsffile{afni200_datamode.eps}}\vspace{1ex} 1782\centerline{\sf \button{Define Function} and \button{Define Datamode} control panels} 1783\end{samepage}\goodbreak 1784 1785%----------------------------------------------------------------------------- 1786\mysubsec{\button{Define Function}} 1787The buttons and other `widgets' on this control panel are used to manipulate how 1788functional datasets are displayed in the viewer windows. 1789 1790\mysubsubsec{Threshold Slider} 1791If the current functional dataset has a threshold data 1792sub-brick ({\it i.e.},~is not of the {\tt fim} type), 1793then the first item in the Function control panel 1794is a slider that lets you select the threshold to apply. 1795Only voxels whose associated value is equal to or 1796above this threshold will be overlaid in color. 1797If the functional dataset type is {\tt fico}, {\tt fitt}, 1798or {\tt fift}, then \afnit knows how to interpret the 1799threshold level in terms of the standard normal models 1800for these statistics, and will show the corresponding 1801`$p$' value (per voxel) just below the slider. The dataset threshold 1802type is shown at the top of the slider. 1803 1804If the functional dataset is of the {\tt fim} type, 1805then this slider will not be visible. In this case, 1806the leftmost item in the Function panel will be: 1807 1808\mysubsubsec{Color Pbar} 1809The multi-colored vertical bar with numerical 1810labels to the right, and a number selector labeled~{\tt \#} below 1811is called the `pbar' (after its name in the C~code). 1812This device controls the colors for the functional overlay. 1813 1814The number selector 1815beneath the pbar control how many color panes 1816are present: from 2 to 10 are available (the default in \afnit is set 1817to 9~panes). Just below that is a toggle switch \button{Pos.}. 1818This allows you to specify that only positive values will the 1819shown in the color pbar, or that both positive and negative 1820values will be shown. (Some functional datasets are naturally 1821nonnegative; for these, allocating colors to the negative range 1822is pointless.) 1823 1824The color in any pane may be altered by clicking inside the 1825pane itself. A~chooser will then popup to let you select from 1826the available palette (which is hard-coded into \afni, and can 1827only be changed via the {\tt .Xdefaults} file). 1828One color choice is `none', which 1829means that no color will display for that range of functional 1830intensities, even if they appear in voxels that are over the 1831selected threshold. 1832 1833Each color pane applies to the indicated range of functional 1834intensities. These intensities are relative to the {\tt Range} 1835control settings (to the lower right). 1836The {\tt Range} setting is is mapped to `{\tt 1.0}' on the pbar, 1837and all other pbar settings correspond to the similarly scaled 1838values in the functional dataset sub-brick being viewed. 1839You may click-and-drag on the `sashes' between the color panes 1840to change the intensity thresholds. 1841 1842\mysubsubsec{Options} 1843The options column is a grab bag of functional dataset stuff. 1844The first boxed set of buttons (\button{Anat underlay}, etc\@.) 1845lets you choose whether the anatomical dataset 1846or the functional dataset appears as the background (grayscale) 1847images in the viewing windows. 1848The second boxed set (\button{Func=Intensity}, etc\@.) 1849lets you choose between displaying the intensity or the threshold as the 1850color-determining function. 1851 1852The third boxed set comprised the range controls for the functional coloring. 1853At the top are the minimum and maximum values found in the current 1854datasets ({\it cf.}~auxiliary program {\sf 3dinfo}). 1855The next control is a toggle labeled \button{autoRange: xxxx}. The value 1856represented by {\tt xxxx} is the automatically assigned range for 1857the functional range (which corresponds to {\tt 1.0} on the pbar). 1858This {\tt autoRange} is chosen by \afnit as the largest absolute 1859value in the dataset sub-brick. If the toggle is off, then 1860the control below is activated, and allows you to specify the 1861functional value that maps to {\tt 1.0} on the pbar. Controlling this 1862range may be desirable when comparing several datasets. 1863 1864The lowest (so far) control in this column provides another \button{FIM} menu 1865button (see the Graph section). The label to the right of this button 1866shows the dataset that will be processed once the \button{Compute FIM} 1867button is pressed. 1868 1869%----------------------------------------------------------------------------- 1870\mysubsec{\button{Define Datamode}} 1871This control column determines how datasets are manipulated by \afni. 1872It also contains some miscellaneous controls that didn't `fit in' 1873elsewhere. 1874 1875\mysubsubsec{Resampling} 1876The\seeme{Warp-on-demand; subvoxel markers} 1877top boxed set of controls 1878lets you choose how the anatomical data that is actually displayed will be 1879generated. You can view the data directly from the {\tt .BRIK} file, 1880if it is available. In this case, you are limited to seeing the dataset 1881at the voxel resolution at which the data was generated. Alternatively, 1882you can choose \button{Warp Anat on Demand} viewing, which means that the data 1883will be interpolated from its source to whatever resolution you order 1884(using the controls just below). In this way, it is possible to place 1885markers at subvoxel locations. 1886 1887At present, \afnit cannot display graphs from a warp-on-demand 1888dataset. If you take an action that causes a 3D+time dataset 1889to be switched to warp-on-demand mode, then any open graph 1890windows will be destroyed. This will happen, for example, if 1891you switch from {\tt +orig} to {\tt +tlrc} view, and have 1892not yet written the 3D+time dataset to disk. 1893 1894The\seeme{Resampling modes} 1895interpolation modes are nearest-neighbor (\kq{NN}), linear (\kq{Li}), 1896cubic (\kq{Cu}), and `blocky' (\kq{Bk}) [this latter is intended mainly for 1897functional datasets, and is intermediate between {\tt NN} and {\tt Li}; its 1898mathematical definition is at the end of this manual]. 1899{\tt NN},~{\tt Li}, and {\tt Bk} 1900are fairly rapid on a decent workstation, but {\tt Cu} can be noticeably 1901slow. Since it uses 64 neighboring grid points to interpolate, vs.\ 8 1902for {\tt Li} and~{\tt Bk}, 1903and it uses more complex formulas, this is understandable. For most 1904purposes, {\tt Li} interpolation for anatomical images and {\tt Bk} interpolation 1905for functional images will be the best. 1906{\bf N.B.}:~threshold data in functional datasets is {\it always\/} resampled 1907using the {\tt NN} mode. This is because it is somewhat unreasonable to interpolate 1908a nonlinear statistic (such as correlation coefficient) between voxels, 1909and then to interpret this statistic using probabilistic models that 1910assume independence. 1911 1912The smallest resolution allowed by the {\tt Resam~(mm)} 1913selector is 0.1~mm. This is very tiny, and images will display 1914very slowly. You can do it if you wish; however, don't try to 1915write out a whole human head dataset to disk at this resolution! 1916The disk space required would be rather large. 1917 1918Controls for determining whether the functional dataset {\tt .BRIK} 1919(if available) or warp-on-demand will be used for computing the 1920functional slices are the next set down. The 1921functional {\tt .BRIK} can be used only if it actually exists 1922in the current view ({\it i.e.},~coordinate system) 1923and if it is at the same spatial resolution as the anatomical 1924dataset being viewed. 1925 1926\mysubsubsec{Dataset Output and Input} 1927The {\tt Write} buttons 1928will compute and write the {\tt .BRIK} files 1929to disk for the indicated datasets. The current resampling mode and 1930resampling dimension will be used for this purpose. 1931The \button{Anat} button will output the current anatomical 1932dataset; the \button{Func} button outputs the current functional dataset. 1933The \button{Many} button allows you to select more than one dataset 1934(from all sessions) and write them all out. This new control is provided 1935since the resampling process can be relatively slow --- now you can 1936select many datasets, start their output in Talairach coordinates, and 1937then go get something good to eat while \afnit churns away. 1938 1939\afnit will\seeme{} 1940not write over a dataset {\tt .BRIK} which cannot be 1941recreated by warping from a parent. 1942(This precaution does not extend to plugins, which can be 1943written so as to destroy unrecoverable {\tt .BRIK}s.) 1944It {\it is\/} possible to 1945use \afnit to resample a dataset in the {\tt +orig} view, but 1946only if the dataset is warp-on-demand from another dataset as parent. 1947This can be arranged using the {\sf 3ddup} auxiliary program. 1948 1949The {\tt Rescan} buttons are designed to re-read data from disk. 1950The first one, \button{This}, will re-read the current session. 1951This is useful if you use an auxiliary program such as {\sf 3dANOVA} 1952to create a new dataset outside of \afni, and then wish to view it. 1953In earlier versions, it was necessary to exit \afnit and restart 1954it to get new datasets into the program. 1955The \button{All} button will re-read all the sessions that were 1956initially loaded (there is no facility to read in an entire new 1957session at this time). Finally, the \button{*.1D} button 1958will re-read the time series directories, and load any new time 1959series files that are found. 1960 1961\mysubsubsec{Controller \button{Lock}} 1962With the \button{New} button (lower left of \afnit controller window), 1963it is possible to view several datasets at once in several sets of 1964viewing (and graphing) windows. 1965Normally, the viewpoints of the separate controllers are independent; 1966that is, clicking in the sagittal window of controller {\tt [A]} 1967will change the viewpoint of {\tt [A]}'s coronal and axial windows, 1968but will have no effect on {\tt [B]}'s image and graph windows. 1969 1970Under some circumstances, you may wish to lock some controllers 1971together, so that their viewer windows move in unison. This can 1972be done with the \button{Lock} menu. There is only one lock 1973in \afni. This menu determines which controller windows participate 1974in the lock. If the spatial viewpoint is changed in any 1975window that is affected by the lock, then \afnit will attempt 1976to jump all other locked windows to the corresponding viewpoint. 1977 1978In addition, the \button{Lock} menu has a \button{Clear} button, 1979to detach all controllers from the lock, and an \button{Enforce} 1980button, which can be used to make all viewer windows affected jump 1981to the locked position. (\button{Enforce} is only needed just after choosing 1982which controllers to be locked together.) 1983 1984A couple of applications for the lock: 1985\begin{itemize} 1986 \item Scrolling\seeme{Try this!} 1987 through several anatomies in Talairach coordinates, simultaneously 1988 viewing the similarities and differences. 1989 1990 \item Viewing a dataset in Original and Talairach coordinates simultaneously. 1991 1992 \item Comparing several different functional datasets overlaid on the 1993 same anatomy. 1994\end{itemize} 1995\afnit can have trouble when the lock is used between controllers 1996in different coordinate systems. The lock subroutine will work properly 1997if the dataset being viewed in one controller is just the realization 1998of the other controller's dataset in a different coordinate system --- it 1999will carry out the Talairach transformation (or its inverse) as needed 2000to keep the lock anatomically reasonable. 2001It will fail if the two controllers have different coordinate systems 2002and different datasets; for example, it doesn't know how to transform 2003from Talairach coordinates in one dataset to Original coordinates 2004in another dataset. 2005 2006\mysubsubsec{Plugins} 2007The last item in the {\tt Datamode} control panel is the 2008\button{Plugins} menu button. This will only be present 2009if \afnit is compiled with plugin support, and if the 2010program finds at least one plugin when it starts up. 2011 2012Plugins are external C functions, written in conformance 2013with the plugins manual, that provide extra functionality 2014to \afni. They are compiled into `shared objects' (or `shared libraries') 2015with the filename suffix~{\tt .so} (or~{\tt .sl} on HP-UX). 2016\afnit searches for them in a set of directories 2017specified in the shell environment variable 2018{\tt AFNI\_PLUGINPATH}. If this is not defined, then 2019{\tt PATH} is used; that way, storing the compiled plugins in the 2020same place as the \MCW$\!$ \afnit executables will work. 2021 2022Each plugin will create one or more `interface panels'. 2023When you select a plugin from the \button{Plugins} menu, 2024its interface panel will pop up. At that point, you 2025fill in the desired parameters, and then execute the actual 2026plugin code with one of the {\tt Run} buttons. 2027\vspace{2ex}\goodbreak\begin{samepage} 2028\centerline{\epsfxsize=4.5in\epsffile{plugclust.eps}}\vspace{1ex} 2029\centerline{\sf Clustering plugin ({\tt plug\_clust.c}) interface panel} 2030\end{samepage}\goodbreak 2031 2032%======================================================================= 2033\mysec{Command line switches} 2034The general form for the \afnit command line is\\*[1ex] 2035\centerline{\tt afni [options] [session\_directory ...]}\vspace{1ex} 2036where the options, listed below, all start with the character~\kq{-}. 2037If no session directories are entered, then the program acts 2038as if the user had typed \kq{./} for the session, which means 2039that the current working directory will be scanned for datasets. 2040 2041What I consider to be the more useful options are listed below. 2042A~complete list can be found by entering the command \kq{afni -help}. 2043\begin{itemize} 2044 \item {\tt -purge}\\ 2045 Conserves memory by purging datasets to disk when not in use. 2046 Use this if you run out of memory when running AFNI. 2047 This will slow the code down, so use only if needed. 2048 2049 Another application for the {\tt -purge} switch arises when 2050 using Unix symbolic links to make a dataset appear as if it is in more 2051 than one session directory at once (without copying the brick file). 2052 For example, suppose one creates (using {\tt 3dmerge}) an averaged 2053 anatomical dataset: {\tt GRP+tlrc.HEAD} and {\tt GRP+tlrc.BRIK}, from 2054 sessions {\tt fred}, {\tt ethel}, and {\tt lucy}. This could be done 2055 (from the directory above the sessions) by the commands 2056\goodbreak\begin{samepage}\begin{verbatim} 2057 3dmerge -prefix GRP -gmean */anat+tlrc.HEAD 2058 ln -s GRP+tlrc.HEAD fred/GRP+tlrc.HEAD 2059 ln -s GRP+tlrc.BRIK fred/GRP+tlrc.BRIK 2060 ln -s GRP+tlrc.HEAD ethel/GRP+tlrc.HEAD 2061 ln -s GRP+tlrc.BRIK ethel/GRP+tlrc.BRIK 2062 ln -s GRP+tlrc.HEAD lucy/GRP+tlrc.HEAD 2063 ln -s GRP+tlrc.BRIK lucy/GRP+tlrc.BRIK 2064\end{verbatim}\end{samepage}\goodbreak 2065 The {\tt ln -s} commands put links to the {\tt GRP} anatomy dataset into 2066 each of the session directories. In this way, if the user runs \afnit 2067 with the command\\*[.5ex] 2068 \centerline{\tt afni fred ethel lucy}\vspace{.5ex} 2069 then each of the sessions will have access to the {\tt GRP} dataset, 2070 but there will only be one physical copy of it on disk. 2071 2072 A problem arises with this scheme 2073 because of the manner in which \afnit accesses large brick files. 2074 The program will not recognize 2075 that the links point to the same actual file, and it will attempt 2076 to {\tt mmap} the {\tt GRP+tlrc.BRIK} file more than once. This 2077 will likely fail, and the program will crash when the second access 2078 is attempted (when the user switches to the second session). 2079 2080 Using the {\tt -purge} switch will avoid this problem. Before a new 2081 dataset is accessed (when switching sessions, anatomies, or functions), 2082 existing dataset bricks will be be {\tt munmap}-ed. This will prevent 2083 the attempt to {\tt mmap} the same brick file twice at the same instant. 2084 2085 Another way to approach this problem would be through 2086 the use of the {\sf 3ddup} program to create warp-on-demand copies 2087 of the {\tt GRP+tlrc} dataset in each of the session directories. 2088 2089 \item {\tt -R}\\ 2090 Recursively searches each {\tt session\_directory} for more session 2091 subdirectories. 2092 This will descend the entire filesystem hierarchy from 2093 each session\_directory given on the command line. On a 2094 large disk, this may take a long time. To limit the 2095 recursion to 5 levels (for example), use {\tt -R5}. 2096 2097 \item {\tt -ignore N} \\ 2098 Tells the program to ignore the first {\tt N} points in 2099 time series for graphs and {\tt FIM} calculations. 2100 2101 \item {\tt -unique}\\ 2102 Tells the program to create a unique set of colors 2103 for each AFNI controller window. This allows 2104 different datasets to be viewed with different 2105 grayscales or colorscales. {\tt -unique} 2106 will only work on 12-bit PseudoColor displays 2107 (for example, SGI workstations). 2108 2109 \item {\tt -ncolors nn}\\ 2110 Tells \afnit to use {\tt nn} gray levels for the image 2111 displays (default is 80). Since \afnit always uses the 2112 default colormap, on a 8-bit graphics system you may 2113 run out of colors if you run several graphics programs 2114 at once. WWW browsers are notorious for causing this problem, 2115 since they usually allocate many colormap entries and 2116 hold onto them (just like \afnit does). 2117\end{itemize} 2118 2119%======================================================================= 2120\mysec{Technical Notes} 2121The \MCW$\!$ \afnit package is distributed as a compressed Unix {\tt tar} 2122file: {\tt afni96.tgz}. 2123It is unpacked with the command\\*[1ex] 2124\centerline{\tt gzip -dc afni96.tgz | tar xf -}\vspace{1ex} 2125The files will go into a directory named {\tt AFNI96}. 2126 2127\afnit requires an ANSI C compiler, X11R5, and Motif~1.2. 2128It also requires that the default X11 Visual be an 8- 2129or 12-bit PseudoColor visual; the program will not work with anything 2130else. This is ordinarily not a problem except on very low end and 2131very high end workstations and/or X-terminals. 2132 2133Several {\tt Makefile}s are included in the distribution. 2134The machines they are intended for are indicated by their filename suffix. 2135In general, you will have to modify one of these to fit your needs. 2136You may also need to edit the file 2137{\tt machdep.h} to set up the flags for the {\tt mmap} routine appropriately. 2138 2139Copy the appropriate file to be {\tt Makefile}. Examine it 2140to make sure that it makes sense on your system! 2141To build the executables, use the command {\tt make~all}. 2142If you set the {\tt INSTALLDIR} macro correctly in the {\tt Makefile}, 2143then {\tt make~install} will {\tt mv} the executable images to their 2144final resting spot. 2145After that, a {\tt make~clean} is appropriate. 2146 2147To make and install the plugins supplied with \afni, the 2148commands {\tt make~plugins} and {\tt make~install\_plugins} 2149will work. Not all system specific {\tt Makefile}s have 2150the commands needed to compile plugins. This is because I do 2151not have access to such computer systems. 2152 2153There are undoubtedly still bugs in this software. 2154Suggestions for further improvements will be gladly received, 2155but no action on such suggestions can be guaranteed! 2156The e-mail address for \afnit comments is {\tt rwcox@mcw.edu}. 2157 2158%------------------------------------------------------------------ 2159\mysubsec{{\tt mmap}-ing} 2160\afnit uses the Unix function {\tt mmap} to access the {\tt .BRIK} files. 2161This is what makes it possible to read in many large datasets and 2162not choke the memory or swap space of the computer. Data is only read 2163from disk using {\tt mmap} --- all writes are done using {\tt fwrite}. 2164 2165If you need to disable the use of {\tt mmap}, edit the file 2166{\tt 3ddata.h} and {\tt \#define} {\tt MMAP\_THRESHOLD} to be~{\tt -1}. 2167This will make \afnit use {\tt malloc} and {\tt fread} to 2168access the {\tt .BRIK} data. This will also strongly limit the number 2169of datasets that can be used. 2170 2171If you receive a message that \afnit cannot load a dataset into memory 2172(or {\tt mmap} it), 2173then you should restart the program with the {\tt -purge} option. 2174This will force datasets not in immediate use to be purged from memory 2175and to be {\tt munmap}-ed, which might solve your problem. 2176This will also make the program run slower when you switch between datasets. 2177 2178\mysubsec{{\tt machdep.h}} 2179This C header file contains machine specific settings. If you are 2180porting \afnit to a system not available at MCW, you will have 2181to create a {\tt Makefile} appropriate for your computer, and will 2182have to edit {\tt machdep.h} to set various flags correctly. 2183In particular, flags for {\tt mmap} and dynamic loading of 2184plugins must be set correctly. Comments in this file describe 2185the options that are available. 2186 2187%-------------------------------------------------------------------- 2188\mysubsec{X11 Resources for \afni} 2189Included in the \MCW$\!$ \afnit distribution is a file called 2190{\tt AFNI.Xdefaults}. This contains examples of how various 2191features of \afnit can be controlled using X11 resources. 2192 2193 2194%-------------------------------------------------------------------- 2195\mysubsec{Formula for {\tt Bk} Resampling} 2196Define the cardinal basis function 2197\begin{displaymath} 2198 \phi(x) = 2199 \left\{ \begin{array}{ll} 2200 1 - 8 x^4 & 0 \leq |x| \leq \thalf \\[.5ex] 2201% 2202 8 (1-|x|)^4 & \thalf < |x| < 1 \\[.5ex] 2203% 2204 0 & 1 \leq |x| 2205 \end{array}\right. 2206\end{displaymath} 2207Then `blocky' interpolation in 3D of a function defined on a grid 2208with spacings $(\Delta x,\Delta y,\Delta z)$ to an arbitrary point in space is 2209\begin{displaymath} 2210 f(x,y,z) = \sum_i \sum_j \sum_k f(i\Delta x,j\Delta y,k\Delta z) 2211 \phi\left(\frac{x-i\Delta x}{\Delta x}\right) 2212 \phi\left(\frac{y-j\Delta y}{\Delta y}\right) 2213 \phi\left(\frac{z-k\Delta z}{\Delta z}\right) \;. 2214\end{displaymath} 2215The actual implementation of interpolation is done in a somewhat 2216different fashion, for the sake of efficiency. See the source 2217code in {\tt afni\_slice.c}. 2218 2219%======================================================================== 2220\mysec{Acknowledgements} 2221Many thanks to Jim Hyde for much support and many discussions on the 2222direction of FMRI analyses. Thanks also are due to Andrzej Jesmanowicz 2223for forging the way with \afni's grandfather,~{\sf FD}\@. 2224Doug Ward has contributed a lot with the {\sf 3dfim} and {\sf 3dANOVA} 2225programs, new features in {\sf 3dmerge}, plus the creation of the auxiliary 2226programs manual. 2227Mike Beauchamp has aided immeasurably by testing earlier versions 2228of this software and by coming up with many useful ideas. 2229Jay Kummer contributed the initial idea for plugins. 2230Many other people at \MCW\ have also helped, particularly 2231with ``quick questions'' (you know who you are) and the 2232occasional warm pumpernickel bagel. 2233This work was partly supported by the United States NIH through 2234grants MH51358 and NS34798, for which I am also grateful. 2235 2236 2237%============================================================================ 2238% for articles, \bit{authors}{title}{journal}{volume}{pages~(year)} 2239% for books, \bit{authors}{}{\rm ``title''}{}{publisher} 2240 2241\newcommand{\bit}[5]{{\rm #1}{\rm #2}{\it #3}{\bf #4}{\rm, #5}.} 2242 2243%\addcontentsline{toc}{section}{References} 2244\begin{thebibliography}{99}\vspace*{-2ex} 2245\addcontentsline{toc}{section}{References} 2246 2247\bibitem{Talairach} 2248 \bit{Jean Talairach and Pierre Tournoux, }{} 2249 {``Co-Planar Stereotaxic Atlas of the Human Brain''}{} 2250 {Thieme Medical Publishers, New York, 1988} 2251 2252\bibitem{Bandettini} 2253 \bit{Peter A. Bandettini, Andrzej Jesmanowicz, Eric C. Wong, and James S. Hyde, } 2254 {Processing strategies for time-course data sets in functional MRI 2255 of the human brain. } 2256 {Magn.\ Reson.\ Med.}{~30}{161--173~(1993)} 2257 2258\bibitem{Cox-AFNI} 2259 \bit{Robert W. Cox, } 2260 {AFNI: Software for analysis and visualization 2261 of functional magnetic resonance neuroimages. } 2262 {Computers and Biomedical Research}{~29}{162--173~(1996)} 2263 2264\bibitem{Cox-Rtime} 2265 \bit{Robert W. Cox, Andrzej Jesmanowicz, and James S. Hyde, } 2266 {Real-time functional magnetic resonance imaging. } 2267 {Magn.\ Reson.\ Med.}{~33}{230--236~(1995)} 2268 2269\end{thebibliography} 2270%===================================================================== 2271\newpage 2272%%\thispagestyle{empty} 2273\addcontentsline{toc}{section}{\MCW$\!$ \afnit Registration Form} 2274\small 2275\vspace*{0pt plus 1fill} 2276\setlength{\parindent}{0em} 2277\setlength{\parskip}{0.5ex} 2278\setlength{\oddsidemargin}{0in} 2279\setlength{\textwidth}{6.6in} 2280 2281\displayline{Disclaimer:} 2282\MCW$\!$~\afni, its associated programs, and its documentation are provided 2283as is, and no warranty for their correctness or usefulness for any 2284purpose is made or implied by the Medical College of Wisconsin (\MCW), 2285or by the author of the software. Neither \MCW\ nor the author 2286accepts any liability for any 2287defects in this software or its manuals, or for any damages caused by use of this 2288software. 2289 2290\displayline{Ownership, Conditions of Use, and Restrictions:} 2291\begin{itemize}\vspace*{-4.9ex}\setlength{\parindent}{0em}\setlength{\parskip}{0.1ex} 2292 \item Permission is granted to make use of and to make copies of the 2293 \MCW$\!$~\afnit software and documentation for non-commercial research 2294 purposes only. Ownership of \MCW$\!$~\afnit and all copies is retained by the 2295 Medical College of Wisconsin. 2296 2297 \item Patient-care applications are not recommended. \MCW$\!$~\afnit has not 2298 been evaluated by or approved by the United States Food and Drug Administration. 2299 2300 \item Use for {\it any\/} purpose 2301 by for-profit organizations is prohibited without prior arrangement 2302 and written permission. 2303 2304 \item Redistribution of \MCW$\!$~\afni, or any derived work, outside the receiving 2305 institution is prohibited without prior permission. 2306 2307 \item Copies may be made within the receiving institution without separate 2308 permission from the Medical College of Wisconsin. 2309 2310 \item Technical support ({\it e.g.},~the fixing of bugs) 2311 for\ \MCW$\!$~\afnit is not guaranteed. 2312\end{itemize} 2313I agree to abide by the terms and restrictions above.\vspace{2ex} 2314 2315{\bf SIGNATURE}:\vspace{2ex} 2316 2317 2318{\bf NAME}:\\ 2319(print clearly, or type)\vspace{2ex} 2320 2321{\bf DATE}:\vspace{2ex} 2322 2323{\bf E-MAIL ADDRESS}:\\ 2324(print clearly, or type)\vspace{0.5ex} 2325 2326\displayline{To Register} 2327Copy this page onto your departmental or institutional letterhead, 2328sign and date, include your e-mail address, and return via mail or FAX to\\[.5ex] 2329\hspace*{3em} Robert W. Cox, PhD \\ 2330\hspace*{3em} Biophysics Research Institute \\ 2331\hspace*{3em} Medical College of Wisconsin \\ 2332\hspace*{3em} 8701 Watertown Plank Road \\ 2333\hspace*{3em} Milwaukee WI 53226 USA\\[0.5ex] 2334\hspace*{3em} FAX: 414--456--6512 \\[0.5ex] 2335Instructions on how to obtain \afnit by {\tt anonymous ftp} 2336will be sent by e-mail. 2337 2338\end{document} 2339