Matlab Programming - Functions, Scripts, M-files
This page looks specifically at how to read m-files and m-file programming - functions, scripts, etc.. For the most basic of basics, check out MatlabBasics. As well, MatlabPaths answers questions about modifying your search paths, and MatlabDebugging touches specifically on strategies for troubleshooting - how to get more information, what parts of error messages to look for, and how you can dig through a script to find what's gone wrong.
In the following, text in fixed-width font are commands that you can type directly into Matlab.
M-files and Programming
Once you've figured out some basic ways to create and refer to your variables and store some information in them, you probably want to manipulate that information. That's where functions and scripts come in. There are tons of built-in Matlab functions, and tons of non-built-in functions written by the SPM folk or the Gablab programmers or other folks.
A function is essentially a shorthand name for a whole set of commands. They're stored in m-files - text files with .m extensions. Any file with a .m extension you can generally read with a standard text editor, and it'll just contain a whole set of Matlab commands. Conventionally, you put only one command per line of the file, and when you run the function, Matlab just reads through the file top to bottom, executing each command in order. You run a function simply by typing the name of its m-file, assuming that m-file is in the Matlab path (see below on paths).
Functions often will take some data as input and spit back out some data as output. Functions are referred to kind of like arrays, but instead of supplying indices, you supply input variables. So saying spm_vol(VY) is calling the function spm_vol and passing it the input variable VY. If you said mydata = spm_vol(VY), you'd be saying you wanted whatever output that spm_vol chose to spit out to be stuck into the variable mydata.
A .m file can contain either a function or a script. The difference between the two is subtle but important; it has to do with what workspace you have access to when you're executing the commands inside your m-file. You can easily tell the two apart; functions always have the function command as their first executable line, which will specify the name of the function and what its input and output are. Scripts don't have the function command - they just launch right in.
The difference between the two is in the workspace. When you run a function, it opens its own, clean workspace. Any variables you have in the workspace when you run the function can't be accessed inside the function, unless you pass them in as input variables. When it ends, it closes its workspace and any variables there that aren't designated as output variables are lost.
Scripts, by contrast, operate in the same workspace from which they're called. So any variable you have in the workspace when you call a script can be manipulated by the script, and any variable created in the script will be left in the workspace when the script ends. This is why, for example, when you run glassbrain, you need to be currently viewing your SPM results; glassbrain is a script that accesses several variables SPM leaves in the main workspace while you're looking at the results. glassbrain3, by contrast, is a function, which is why you run it with the command glassbrain3(SPM,VOL). It uses those same variables left in the workspace by SPM, but it doesn't automatically get access to them - you need to pass them in as input variables.
Reading .m files
If you're running the graphical version of matlab, you can open the built-in text editor with the command open filename. The single best thing you can do to learn and teach yourself about the inner workings of SPM (or other Matlab packages) is to open up particular functions and read through them to see what they're actually doing. Reading them can seem like reading Greek a lot of the time, but it's a skill you can learn, and it'll help you understand what's happening to your data better than anything else. Unless you can read Matlab code, you'll always be a little in the dark about what's being done in your analysis. You don't need to know how to program the code - just to understand more or less what it's doing.
Reading code is relatively straightforward in some ways - you simply start from the top and go through line-by-line to see what each successive line does. But there are some things to keep in mind on the way:
- Lines that start with % are "comments." Anything after a % on a line is ignored by Matlab (even if there was real code before the % on the line), and so comments are used by programmers to explain what's happening in a file. Most functions have some overview comments at the top of the file, to try and explain what's happening overall and hopefully some of the data structures and variables in use. Good programmers also comment throughout the function, to point out different sections of code and help explain what's happening in each chunk, or why they chose to use a particular strategy. Read the comments! They can be super helpful in understanding what's going on.
- If you hit on a line with some variable name and you have no idea what that variable is supposed to be, don't be surprised. SPM programmers in particular have a habit of choosing incredibly non-obvious and non-descriptive variable names for their data. Jeff has a programmers's cheat sheet available which explains what most of the variables used in major SPM functions mean - we'll try and get that posted on the site soon, but in the meantime ask him if you want a copy. If you don't know what it's for, though, try walking backwards up through the script and seeing how and when the variable was created. Often that can tell you something about what it's for. If you can't find it being created anywhere, keep in mind that 'load' statements can bring in any number of variables, so look for load as well.
- If you see a function name and don't know what it does, check the Matlab help! There's a lot of information in there about what every function under the sun does. Many Matlab functions are obviously named, but not all. If it's not a Matlab function, try typing help function-name at the prompt anyways - a lot of times something will come up.
- Certain statements control the flow of execution through the program - if and for are the biggies, but there are others like switch or while, too. They're generally paired with an end statement; anything in between the if or for and the end is under the control of that flow statement. Generally those blocks of code are indented, for readability. They're often nested within each other, too. An if statement specifies some condition to test; if the condition is true, then the block of code before the paired end will be executed. If the condition is false, that code won't run at all. A for statement is used to execute a block of code several times. For statements specify some index variable - often named i or j, but sometimes other things - and specify the range of values it will take on. It'll then loop over the code before the paired end statement and execute it for each value of the index variable. So for i = 1:10 will make a loop that will run 10 times, with i becoming one number bigger each time. This is often used to walk through a whole vector or array of numbers and do something to each element, using the index variable as the index into the array.
- If you get stuck, ask somebody! There are experienced programmers out there who can help.