03 - AFNI Interactive: Session 1 of 2
Date Posted:
July 31, 2018
Date Recorded:
May 28, 2018
Speaker(s):
Daniel Glen, NIMH
All Captioned Videos AFNI Training Bootcamp
Description:
Daniel Glen, NIMH
For more information and course materials, please visit the workshop website: http://cbmm.mit.edu.ezproxyberklee.flo.org/afni
We recommend viewing the videos at 1920 x 1080 (Full HD) resolution for the best experience. A lot of code and type is displayed that may be hard to read otherwise.
PRESENTER: OK. So now we're going to switch to a little different part. Well, I say we're going to switch, and then-- OK. So I want everyone to open up a terminal window. And this is going to be a hands-on class. We're going to be using the AFNI GUI. Well be using the terminal.
If you have questions, ask Rick, and Gang, and me. And it's hands-on. Yeah.
So I want everyone to switch to this directory, the AFNI_data6/AFNI directory. You switch to it by typing-- well, I'm going to switch back to the home directory with cd. Then I'll type cd AFNI_data6/AFNI. And there I am.
And so what we do in AFNI is generally we like to start AFNI in the directory where we have our data. It's a little different than maybe in Windows programs or some other software. Yes?
AUDIENCE: Sorry, could you make the font a little bit larger?
PRESENTER: Oh, good point. Yes. Tell me when it's good.
AUDIENCE: Oh, that's--
AUDIENCE: That's great.
[LAUGHTER]
PRESENTER: Is that too big? Because I'll keep going. OK. All right.
So AFNI_data6/AFNI directory. It's the same directory we had been at one point. I think we switched away from it.
So we start in a directory that has data, and we check that our data is there with the ls command. Now, I've got a lot of other stuff in here. You're going to have to excuse that. But you'll see that most of the the things in the directory are these files that have .head or .brick. Or it might say .brick.gz.
So these are AFNI data sets. The .head is our header file. A .brick is our data-- the binary data. And it may have a .gz on the end of it, and that means it's compressed with Gzip probably. We have a couple different compression algorithms that we use.
So those are the two halves of our data set pairs. And you'll see that it has this prefix part. So for the anat, we have the anat plus orig. The prefix is the anat. And then it has a view, the plus orig. Or it might be plus talairach. So both of these things can exist. We can have the orig, the native format.
The plus talairach is in a standard format. It's not necessarily Talairach format. We'll talk about spaces of data sets tomorrow, but it could be any space. It could be marmoset space, it could be macaque space, it could be pediatric space. We have a lot of different spaces. We'll talk some more about that.
We also read NifTI. So that those would end in .nii or .nii.gz for the g-zipped form. So different formats there.
So generally you'll start AFNI in the directory where you have the data. You can call it from another directory and say-- we could have started it on the command line and said afni afni_data6-- what directory we want. And then it would start AFNI on that directory. Or we can have it recurse through a bunch of directories. Go find me all the directories that have data from the current directory downward. And so these would all show up sessions inside AFNI.
Now AFNI is a program like all the other programs of the afni package-- this lower case afni. This is our GUI. And this has help, just like the others. And you can start help. You can look at the help for AFNI with afni -help.
And it's going to be a lot of help, so I'm going to sorted through-- pipe it through less. And it shows you all the different things. So we have an option so you can look at the BIDs format. Is anyone using BIDs format here? A little bit. OK. This is becoming more and more popular across packages. It allows you to get directories of data with some header information about how the data is arranged. It gives you a kind of organization scheme, and AFI can read-- the Human Connectine Project uses the BIDs format. So you can use this by sub option to read across multiple subdirectories and put them all into one session inside AFNI.
And it goes on and on. But this is how you would get help for a program. You afni dash the program -help, pipe it through something. Or you can type, similarly, afni -h_view So this is help in a more visual way. And it opens it up into an editor-- same information, maybe a little bit fancier. And we also have an on our website too. I'll get to that.
AUDIENCE: Sorry. [INAUDIBLE]
PRESENTER: Yeah that was -h_view-- help in a viewer. This lets you scroll up and down in whatever editor you've set up on your system. All right.
Rick has already shown you the 3dinfo command, another one of our 600 programs. AFNI is this collection of software. It's 600 or so programs written mostly in C. But we have a fair bit of Python programs, and R programs, tshell scripts, bash scripts. There's a lot of different software that goes together.
AUDIENCE: [INAUDIBLE]
PRESENTER: Yes.
AUDIENCE: Is it Better to be running all this in tshell or bash?
PRESENTER: Well, we run most of our software-- we write most of our software in tshell. But I don't think there's any requirement that you be in tshell also. Having said that, a lot of times it's better to set up the environment variables in both bash and tshell if you're using bash. I don't know if there's any more that you would like to add.
AUDIENCE: The reason we stuck with tshell is mostly because it's a simpler syntax to read for people that don't master the shell programming [INAUDIBLE]. So we stuck with it for that, even though bash support [INAUDIBLE]. But again, most of you in here are probably using bash, and that's fine. But our scripts are more often written in tshell.
PRESENTER: OK. So now let's get to our main event here. Let's start the AFNI GUI. And we start that by just typing afni.
AUDIENCE: Where should we start it from?
PRESENTER: AFNI_Data6/AFNI directory. Just start it in your terminal there. And as it starts, there are a few things to note. We'll see a splash screen show up with a picture, maybe of a user, picture of a class. If you want your picture to show up when somebody starts AFNI, you can do it. You can get your 15 microseconds of fame, and you just have to send us your picture. It will be shown as a 128 by 128 pixel postage stamp of a picture, and it gets distributed inside AFNI.
We have many, many hundreds of pictures. People send pictures of themselves, pictures of their cats, of their babies, of their nieces. Whatever you want, we'll show it for you. Well, I mean, mostly.
[LAUGHTER]
AUDIENCE: [INAUDIBLE] AFNI is always my picture?
PRESENTER: Only if there are no other pictures. If there are no other pictures-- if you change his installation so that--
[LAUGHTER]
You'll find there's a whole set of faces in your AFNI binary directory.
AUDIENCE: On Bob's Birthday, you will only see pictures of him.
PRESENTER: That's right.
AUDIENCE: Curious pictures of him.
PRESENTER: And I think Rasmus gets a gets a special notice too. Because one day I was teaching a class, and all I saw was Rasmus.
[LAUGHTER]
So it could have been a coincidence, but I don't know. But Bob, I know for sure. We have Bob's pictures throughout his lifetime-- lots of pictures of him.
So we should also schedule a class picture too, so that we get this added in. So AFNI has started. Bring you back to the command line. When it starts, it tells you what version of AFNI you're running.
So here I can see I'm running a Linux Fedora 25 version, 64-bit. It was built on May 25. So that's two days old or so. It has a version number. Right now it's based on year, and quarter, and builds number.
As Rick said, we update AFNI all the time. And you should check to see if there are updates. The way that you update-- and don't do this now, because it will be a fairly large download-- is on the command line, you type @update.afni.binaries. I hit Tab to complete. And then -d for the default package that I already have installed. You can install another package. If you're on a certain variety of Linux and you want to try out another variety, they should be pretty similar. But if you're running a strange version of Linux, you might not have one that matches yours exactly . So this is how you would do that.
You can also just check your AFNI version with afni -ver. If you have a problem with something in AFNI, we will ask you for your version. And this is the easiest way to get that is just type afni -ver, and it shows the same thing that came at the beginning of the AFNI GUI started.
And the reason we ask for that is we may have fixed this problem that you're running into last month. We update AFNI often. And what we try to do is fix more bugs than we introduce. And it's a never-ending cycle. So the more software we write, the more bugs we have. And we have to fix those.
OK. Let me bring that down. I'll take this out of the way. So what do we see first? We see, by default, AFNI will start with a data set selected and some image windows open. But we can choose our data set by choosing the Underlay button here. This chooses our underlay data set.
And the underlay is a kind of background data set. What we're going to see are functional image over. Or it could be interested directly in the underlay data set, too. And, generally, it's going to be shown in this grayscale.
So here we get a list of the data sets in our directory. You won't have all these different things, because I've been playing around here. So there a lot of other data sets. But you'll see that we have anat data set. It tells the kind of data it is. It's what we call an anatomical bucket. It has one subbrick, one volume inside that data set.
After that we have an EPI data set. This is run1 of this EPI data. It's echo planar, it's 3D plus time, and it has 152 volumes. And so on it goes, on through the whole thing. And the sorting order is AFNI format first and then NifTI format, and then it even shows JPEGs and PNG files. So you can use this as just a general image viewer too.
So I'm just going to keep the same data set that I've got. You'll see several menus inside AFNI that will say things like this-- Quit, Apply, Set. Quit means just leave this menu and don't do anything. Apply means take the choice-- whatever choice I've made in this-- and apply it, and keep the window open. Or click Set, and that means choose this data set, and then set it, and exit the menu. So, in this case, I'm just going to do Set.
So now, we have this anatomical data set. We're looking at three views of this one data set. And this is our axial view, this is our sagittal view, and this is our coronal view. And you can take each of these windows and you can move them around and resize them-- make it bigger or smaller. If you have, I think, on Macs, you can resize it and squash it. Can you do that-- it'll be kind of weirdly squozen.
AUDIENCE: Oh, yeah.
PRESENTER: Yeah? So if you do that-- on Linux it doesn't allow me to do that. But on Mac systems, it doesn't respect the x11 requirements as much, so you can fix the aspect ratio by either clicking the A key over the image viewer or click the grayscale bar.
AUDIENCE: I don't see it.
PRESENTER: This bar to the right of the image.
AUDIENCE: Aha.
PRESENTER: So either the A or the grayscale bar. There's a way for AFNI to enforce that aspect by setting an environment variable. And the way you set an environment variable is by going to either Edit Environment, and we have a list of environment variables here. And here you can scroll down until you find-- where is it? Did we move it from this? I think we have-- I can't find it on this one.
Is AFNI enforce aspect there? What's that?
AUDIENCE: I think they were alphabetized at some point.
PRESENTER: Yeah. I'm not seeing it here. I don't see the AFNI enforce aspect. Maybe it's AFNI aspect. OK. Well, this is one place to set other environment variables. I'll show you-- and this is another important topic of customizing AFNI for your own use. In your home directory, if you've gone through the installation recommendations, you'll have something called .afnirc-- an AFNI resource configuration file. That's a dot there.
I'm going to open it up with my editor. You open up with yours. And let's see if I can make this one bigger.
So this is where you would set how you want AFNI to run. We should have something-- yeah. So we have an AFNI enforce aspect. On a Mac, you could set this. It will sometimes cause it to flash a little bit. But you can get the aspect to always be enforced.
But I want to point this out, not just for that one environment variable, but there's a whole long list of environment variables here, including if you want to use analyze for macaques or marmosets, you can have those templates and atlases-- the spaces defined here. Well, at least made to be your default if you're always dealing with macaques or marmosets. And so I have something like that at the top.
We'll talk more about spaces and that kind of thing later. But just, I want you to know that this exists. This allows you to control how AFNI is running. Back to the GUI.
So probably most of you have used these kinds of viewers before. If you haven't, this axial slice corresponds to this horizontal line of the sagittal view. This is the coronal slice. This corresponds to the vertical line of the sagittal view. And they're all connected to each other. Everywhere you click, that will change the other two slices.
We can scroll through slices by either dragging the slider at the bottom of each of these image viewers, or we can use the scroll wheel, or you can use the arrow keys. You can click in the troughs. You can use the Page Up and Page Down-- lots of different ways. Is it clear what those are doing? Because it is pretty basic for use of AFNI viewer.
So we show the crosshairs here. Everywhere you click, you'll also notice up here, on the upper-left corner of the AFNI GUI, you have the information about coordinates and controls for the crosshairs. So here the coordinates are listed. This, as Rick said, is an RAI order. So from right to left, on the right we have negative, and on the left it would be positive. So this is coordinate is at minus 34, minus 26, 39.
Now, there are two main coordinate orders that are used in neuroimaging, RAI DICOM order or LPI, which is also called SPM order. And it's also called neurological order for SPM and radiological order for DICOM. So two very common formats.
This is the order that we're showing the coordinates. This is not the order that they're stored on disk. So there are 48 possible combinations of right to left, and anterior to posterior, and inferior to superior. We can flip those around 48 different ways. On disk they could be in any of those 48. That depends on your acquisition scheme. But you can resample to another order if you want.
So you have to be aware of which order. When we are reporting coordinates, we want to use something that everyone else will use. So we'll either use RAI or LPI.
And mostly coordinates don't mean too much for anything that's not in a standardized space. So coordinates become important when we're talking about standardized spaces. So we have MNI space, we have Talairach space, we have D99 macaques, we have NIH marmosets-- lots of different spaces. They each have a particular template space, and we can report the coordinates for that space in somewhat standard ways.
Another thing that's important about AFNI is that it doesn't matter what order your data is stored in, we will show it in this way. We'll show it with axial slices in the image viewer, labeled axial. And the sagittal slices will be shown in sagittal. It doesn't matter how your data is stored. We don't have any requirement that your data is stored in a particular way, other than it be in a correct way. Meaning that the order is defined properly. So if you're acquiring animal studies and they're flipped over, we may not know that.
Let's go to the next thing. I showed you help on the command line. I want you also to know about other places you can get help. So you may notice that as you move your cursor over different parts of the image, over the menu, you can get different hints showing up. So open raise viewing window, and it shows you these hints. If you don't want to see them any longer, you can set the environment variable-- the AFNI environment variable-- AFNI hints to be to be no, and it won't show you those any longer. But for now, you can just keep them on.
If you want more help, you can type things like-- you can click on the Bhelp button. So Bhelp here changes the cursor to a hand. And then you can click somewhere in the menu and get help for that menu item. So you can click on buttons, you can click on windows. I'm going to click on a window.
And it shows you-- this is help. This is a particularly large help for within the AFNI GUI. And it shows you all these shortcut keys there that are available on that image viewer. So the image viewer has the fix aspect ratio that we talked about. But you can see there's a long list of things that are available there.
So we've talked about two or three ways to get help. If you still want more help, some of the menus actually have some more help here. There's AFNI tips here. It'll give you some advice about how to use the AFNI GUI-- some kind of insider tips there. If you want more help, you can go to our website.
And let me go to-- well, you've all been to the education part to download your data. Well, you probably followed it through a script. So let's start at the home page. This is a brand new picture. We just took this a couple of days ago. You can see all of us. There's Bob, there's Elaine, Brian-- this scrolls through-- Justin and Paul were there, and you know the three of us who are here.
So other things on the site, we have the installation instructions. We have some documentation. This is our newer form of documentation. It's a sphinxified documentation. So help about about SUMA and FATCAT. And this is continuing to grow. So a lot of information there too.
You can search through our website. There's different kinds of documents inside there. There's our class handouts. We have some videos from the class. But probably the most used one is our message board. So click on the message board tab, and you'll have to register, as Rick said. And here we have more than 20 years of messages, questions, and answers-- answers too about problems.
So if you post a question-- well, before you post a question, consider that there are 20 years of questions. Search for the answer. Now, generally, I like to use the Advanced button. And I search for the answers that I posted, because I don't remember what I said. And rather than figure it out all over again, I search our message board. And I recommend you do the same.
So if you have a question about a particular topic. Let's say you want to know about @auto.talairach, one of our alignment programs, you can go there and say search, and it will search through, and search through time. And it finds there were 1,098 questions about @auto.talairach. Kind of surprising. OK.
[LAUGHTER]
So lots of different questions. If you know the answer, you can even post the answer. Some of you will start answering stuff for us. That's great, because that saves us a lot of time. So we have several uses that will take part, and they help us out. And we really appreciate that.
We try to answer questions really quickly. We don't want to leave you suffering for too long, so we try to answer-- usually, it only takes us to three hours. Sometimes it will be a few days. It depends what's going on in our lives, and we've got bootcamps, and traveling, and that kind of thing.
You can also send us private messages through this. This all requires that you register on the site, because, otherwise, we get a lot of spam. So we try to restrict who can post messages. So you can send us a private message. So if you want to know something particular-- if it's just a little too long for a message board post, it's maybe too detailed, then you can send us that.
You may want to upload some data. We'll give you instructions on how to upload some data to us. We'll look at it and tell you what we think.
In some cases, also, people will email us. If it's more complicated and you've got to put a lot of images in there, or you want to talk to us about data, you can send us an email. We'll try to answer that.
And, in a few cases, we also do collaboration. We have a few collaborations with people around the world. Mostly with support people at NIH, but there are exceptions. So I guess the point is, you can get help someplace. And we try to do the best we can. OK.
So back to the GUI. So we're going to travel around-- let me pick one of these guys-- one particular image viewer. So we won't talk about all of them. If you don't know what something is, go ahead and click it. It's OK. It might break, but it doesn't matter.
[LAUGHTER]
So most of this is-- if you find something that breaks, please let us know. We would like to fix it too.
So let's go through what some of these things do. I'm going to start with the C and B. These are the Contrast and Brightness buttons. So you can increase and decrease brightness and contrast with the Up and Down buttons. So I click UP-- click, click, click, click, click. A lot of clicking there. I can change the contrast, lower the contrast, increase the brightness.
So that's one way to do it. We have a radiologist at NIH, John Butman, he said, the way we do it in radiology is not like that. What we'd like to do is drag the button, drag the mouse through the image. So it's the same thing as clicking the Up and Down on the buttons, but we're going to drag. So hold your left mouse button down, and going up and down changes the brightness. And going right and left changes the contrast.
What that means, really, is a mapping of the intensity to grayscale value. But you don't have to worry about it. You just move it till you find what you like. If you like the way it looks, that's perfect.
There are other controls. I like this gamma value control. [INAUDIBLE] that is a. G But most people don't use it. It's very popular in radiology. But it's there too. So a couple controls on that.
We'll get to what this 8 is for later. The Z key, this is a good one to use. You can zoom in. So every time you zoom in, it multiplies the magnification by 2-- 1, 2, 4, 8. And then you can pan around. So panning, you hold the left mouse button down while you pan.
Now, this is all doable even with the with keystrokes too. If you want the cursor to show up in the middle, you can hit the Home key. So if I go over there. Let's see if I get the Home key there. So the Home key brings the crosshairs to the middle. If you have a laptop, you may need to do Function-Home or something like that.
The upper case Z zooms in, and the lower case z zooms out. Is that clear what all that does? OK.
I didn't show this to you, but if you wanted to see that mapping of the intensity, you can say Display, Gray Map Plot. And then as you move this around, you can see the distribution of the data. So I did that quickly, probably while a lot of you weren't looking. So Display, Gray Map Plot. I right-clicked on the grayscale bar, which has its own its own menu.
There are a lot of hidden menus and features inside AFNI. And you have to keep up with that. You've got to look for these hidden menus. How do you find hidden menus? Well, on Linux systems it's kind of hard. On the Mac, it's a little bit easier. Because as you move your cursor, you'll see the arrow change color. So if you have a Mac, you'll probably see it change to yellow or something, and the tilt changes a little bit. That's a clue that there's a hidden menu hidden behind that. We have these little Easter eggs of menus.
There's so much stuff to put in-- so many features inside we have to hide it someplace, because we can't show you everything at once.
AUDIENCE: If you want to open a new image or overlay an image on this, what would you do?
PRESENTER: That's what the rest of this session is about.
[LAUGHTER]
But it is a good question, because that's what we have to do, right? So we have to get to that point. Anyway, I just wanted to show you this is what brightness does. See that black line is just raising and lowering that, and contrast is just changing the tilt to that. And you can play with gamma and see how that changes the curvature.
I'm going to click done on that. Another point that I will bring up-- although I'm presenting here at 1,024 by 768, which is a miserably low resolution for using AFNI, I recommend using giant screens, or two giant screens, or three, because you need a lot of real estate-- visual real estate-- to look at all your data. And we will quickly fill us up.
So I have a couple more minutes. Yeah. I'm going to continue to go around the interface here. So we've looked at the slider bar. This shows us what orientation we're looking at. And then we have something here, it says left equals left. Which seems like a pretty silly thing to say, but it's actually really important.
So when you're looking at an image, you could look at the left on the left, or you could look at the left on the right. And depending on whether you're a neurologist, or radiologist, or anybody else, you might like it the other way. And you can do that by clicking the L key. So there-- yes?
AUDIENCE: My L key is stuck in the plot.
PRESENTER: Your L key is stuck in the plot?
AUDIENCE: AFNI [INAUDIBLE] is stuck.
PRESENTER: AFNI is stuck.
AUDIENCE: The plot blood doesn't disappear anymore.
PRESENTER: Your plot doesn't disappear?
AUDIENCE: [INAUDIBLE] the grayscale bar.
PRESENTER: Yeah. OK. Rick will figured that out, I guess. So you click the L key and axial slice does this little Macarena move. And so you've got it moving around there.
Now, we say that left is left based on the information from the data set header, which we may have gotten from the DICOM header or maybe we got it from somebody else's NifTI header. This is not always true. Very often, on large data sets, data sets from other institutions, somewhere along the line this information has gotten lost. And left may not be the left, it may be the right.
And we don't know which one is correct, but we have a way to tell if the left and right of two data sets don't match up-- don't align well. And so we have a flipping check. And we find this happens over and over again with major public databases. Almost all the public databases have this problem of left and right flipping somewhere in their data.
One of our AFNI users used these tools though that we're going to show you today in the AFNI GUI. And they said, look at this. It doesn't look like it's aligning well. But if I flip it, it looks better. So we've integrated that idea into our alignment script. And so, now, we can do this automatically. And now afni proc does this automatically for you too.
So it will tell you, does the flipped version match better? If it matches better-- we don't know which one's which, but the left may not be on the right. You will have to go back and figure out which one is the left or the right. How do you know which one is really left or really right? You could have a vitamin E capsule. If the animal or human has surgery on one side, then you can know. But it's almost impossible to know by just looking at it.
You can do the same thing with the sagittal slice. We could do the L key over that too. But generally, it's easy to tell the front from the back. Even that problem has happened too. So we've gotten backward brains too. But mostly you can tell front from back.
have an interactive transcript feature enabled, which appears below the video when playing. Viewers can search for keywords in the video or click on any word in the transcript to jump to that point in the video. When searching, a dark bar with white vertical lines appears below the video frame. Each white line is an occurrence of the searched term and can be clicked on to jump to that spot in the video.
LEARNING