Visualization and Documentation Tutorial
Pascal Wallisch
This chapter represents part of the fundamental materials, to help set the stage for other lessons. The content of this chapter, Visualization and Documentation, will be quite likely be revisited as long as you use MATLAB®. It is worthwhile to devote a chapter to this content, to get a firmer grip on these ubiquitous issues.
Keywords
visualization; documentation; set; get; findall; children
5.1 Goals of This Chapter
This chapter represents the last chapter of the fundamentals before moving on to the later parts of the book that contain more specific and more modular material. The content of this chapter, Visualization and Documentation, will be revisited in each subsequent one and quite likely as long as you use MATLAB®. Therefore, it is worthwhile to devote a chapter to it at this point, getting a firmer grip on these elementary issues, allowing you to focus on the specific new content that is introduced later on.
5.2 Visualization
The ability to rapidly and effectively visualize data that is afforded by MATLAB is one of the key reasons why MATLAB is so popular in the first place, perhaps only second to its efficient computation of matrix operations. In the previous chapters, we have already seen how easy it is to create figures from data in MATLAB. It is so easy that anyone can do it. However, this low threshold can be treacherous. While it is easy to make the figure, comparatively few people know how to make the figure so that it looks just how they want it to look. This causes much frustration and often drawn-out and lengthy modification of figures with other image processing software. It is better to avoid this altogether by taking complete control of the figure and its appearance from the start.
We already encountered the function set in Chapter 2 when we manipulated the color of individual subplots. set is a key function in this context. It allows you to set the value of any figure attribute you want.
We will start with creating a figure in itself. By now, you have probably noticed that MATLAB creates figures by default with a certain size and in a certain position. For many purposes, this default is too small, which means you have to resize the figure manually each time the program is executed. A better way to do this is to create the figure with the right size from the get-go.
This code creates a figure at a position on the screen that is at a distance of 100 pixels from the left edge of the screen, is 200 pixels from the bottom, extends 400 pixels to the right (width), and extends 300 pixels upwards (height). The function that accomplished this is set, which allows us to set the value of object attributes (the object in this case is a figure, and attributes are called “properties” within MATLAB).
set expects three values in the parentheses: the handle of the object we refer to, the property we want to change, and the new property value, in this order and separated by commas.
In this case, we told the function set that we want to refer to a figure not by giving it the object handle, but by using the function gcf, which stands for “get handle for current figure.” This is adequate, as the current figure is the one we just created. If there are multiple active figures, it is better to create the figures with a handle, and later specify the handle of the figure object we want to refer to. The second value here was ‘Position’; it is important to put it into quotes, so that MATLAB recognizes it as a property. The third and last value is a vector of the form
You can think of the figure as a rectangular window that starts at the point defined by the Left_edge and Bottom_edge values as their x and y and extends from there, as specified by width and height.
But how are you supposed to know all of this? How do you know which properties can be set and what values they expect?
That is an excellent question. Luckily, the solution is relatively straightforward. Try
This command displays a long list of figure properties that, as we just created the figure, are set to default values, except for position, which should be what we set it to be. You can use the function get to either get all of the figure properties and their values as with the previous command, or a specific one, as with the command ahead, for the case of position.
Note that you can either use this for your edification as in the previous command, in which MATLAB is telling you what the position vector of the figure is, or you can store it for further use, as with any other vector in MATLAB, and as in this command:
You can now use the variable tempfigpos to do calculations, like so
Does it still fit on your screen? (I do realize that—given the rapid advance of technology—the answer to this question will strongly depend on when you are reading this).
Speaking of figures fitting on the screen: For most applications, it is opportune to set the figure size to the screen size. This will allow you to take advantage of the entire screen real estate, which is beneficial for complicated figures, particularly if you have a second monitor—which allows you to code in one window and look at the figures in another. If you don’t know the number of pixels on your screen or you change monitors often, it is better to ask MATLAB than to hardcode this, like so:
“Screensize” is a property of root, which can be accessed by giving the function set “0” as the object handle. But how were you supposed to know that 0 would work as a handle?
This is a good time to introduce the hierarchy of graphics objects within MATLAB. At the top of the hierarchy is root, the screen itself (handle is 0). The screen (or root) can contain any number (limited by memory) of figures. Each figure has a handle which allows you to access its properties. If you don’t specify a handle, the figure handles are simply consecutive integers, in order of figure creation, starting with 1. So passing an object handle of “0” accesses root, whereas “1” accesses the first figure, “2” the second figure, and so on. Each figure in turn contains any number (within reason) of individual axes, which can also have their own handles. You can change the property values of any property of any graphics objects in MATLAB by specifying its corresponding object handle. Understanding this will allow you, as promised, to take complete charge of the appearance of the figures you create. As you get more practice, this will substantially cut down on the amount of post-processing you will have to do.
Note: Some of the root properties will have byzantine names and a possible use that will likely escape you at this point. Do not be discouraged by this. It will come, in time.
Back to the figure. Let’s say that for this particular project, you want a figure that doesn’t feature the usual MATLAB figure gray as a background (represented by the RGB color vector [0.8 0.8 0.8]), but uses red instead. There are many ways to do this. The most straightforward one involves passing the current figure handle and property a new value, in this case “r” (for red).
Your figure background should look red now.
MATLAB knows eight different character codes for all integer combinations of the three-element RGB vector, such as “r” for red [1 0 0], “g” for green [0 1 0], “b” for blue [0 0 1], and so on. If you need more nuanced coloring, you can pass the vector directly, using non-integral values. For instance, if you want a darker shade of red with a touch of purple, this would do it:
Time to plot something. To make matters easy, we’ll just plot a sine wave. This will do it, creating a nice sine wave:
Your figure should now look something like Figure 5.1.
This command did two things; first, it created an axis in our figure, and then it created an object within that axis. Both can be addressed.
One issue that is immediately obvious is that the axes are now hard to make out, as they are plotted in the default black. Setting them (both x and y) to a brighter shade of gray should solve the problem:
>> set(gca,‘xcolor’, [0.7 0.7 0.7]) %Changing the color of the current x-axis.
>> set(gca,‘ycolor’, [0.7 0.7 0.7]) %Changing the color of the current y-axis.
Voila. Now you can read the axis values again. However, the actual sine wave still looks positively anemic. It might be prudent to increase the line width. Alas, you plotted it without giving it an explicit object handle. It still has one, but you don’t know it. What to do?
There are several ways to retrieve the object handle.
One way is to use the findall command. findall returns a list of all objects for a given handle. In this case, we’ll use the current axis:
This yields two object handles, one for the axis itself and one for the line (represented by numbers; your numbers might vary, as they are assigned by MATLAB). But how to find out which one is the line and one which one is the axis?
Note that in the output, one will list “axes” as “type,” the other “line.” We want to modify the line.
We can now either access this object handle, or—for future use—redefine temp as only the object in the current axis out of all the objects that is a line, like this:
Now set the line width to a thicker strength, but hash it at the same time:
The figure should now look something like Figure 5.2.
Note: If you were to print this figure, it would use up a lot of colored ink. To prevent this, MATLAB prints the background as white and the axes in black by default. If you want MATLAB to print things exactly as they look on the screen, you need to set a figure property, like this: set(gcf, ‘InvertHardCopy’, ‘off’).
Of course, things really get interesting as one introduces multiple objects in the same axes. Let’s do it.
In order to do this without erasing the other object, we need to put the hold on, so type
This adds a cosine to the mix. Now we have two line objects. The sine wave from before, and the new one. This time, we labeled our object with an explicit object handle, “h.” We can now access it.
Say that in a not so distant future you have a busy figure with a large number of lines. For some reason, you want to take all lines of a particular color and change a particular property, e.g., their line width. To do this, you can use the function findobj. It returns the handles of all objects with a particular property. For example,
finds the handles of our two lines again (as they are plotted in blue, per MATLAB default). We can now set their line width to a uniform 3 and, while we are at it, change their color to green (see Figure 5.3).
If this is what your figure was supposed to look like, you can declare victory at this point.
Of course, there is a lot left to be done. One important concept to be understood is that of children in MATLAB. Another one is that of multiple axes in the same figure. We’ll tackle both at the same time.
If you type >> get(0,‘children’), you should get “1” as an output. You are asking MATLAB how many children (figures) the screen has. At this point, it has 1. If you open another figure (please do so, by typing “figure”), the output will now be a vector with two elements: 1 and 2.
The second figure seems to be empty at this point, as confirmed by
but that is an illusion. MATLAB sometimes uses hidden handles, particularly if it doesn’t want the user to accidentally do something foolish. However, even these handles can be displayed and accessed by using the allchild function. For example,
returns plenty of handles.
There are, of course, a lot of figure, axes, and line properties to modify. It will take time to become familiar with all of them. With some simple examples, this tutorial demonstrated how to access these properties in principle. For more information on these properties and their potential values, search the help (or the function browser) for figure_props (for figure properties), axes_props (for axes properties), and line_props or linespec (for line properties). There are a lot of them.
Finally, what is left to do is to explore the syntax to add multiple axes to a given figure.
In Chapter 2, we already discussed how to add a tiled (and ordered) number of axes to a figure by using the subplot command. While this is sufficient for many purposes, it is good to know how to add axes at arbitrary positions in the figure.
This is done in relative figure coordinates, where 0,0 corresponds to the lower left and 1,1 to the upper right.
For instance, if we want to place three unequally shaped plots on a figure, we could type
to create the 3 axes and their handles, then type
to get a figure that looks something like Figure 5.4.
5.3 Documentation
There are several interpretations of the notion of “documentation.” One of these, in the sense of “commenting your code,” was already covered in the previous chapter. If you skipped it, you might want to revisit that. All I want to say about it here is that you do want to comment your code as neatly as possible. I can guarantee you that the very code you just wrote, sans comments, will make perfect sense to you now, but it will be so opaque to you in about 6 months that it might as well have been written by someone else. This is a problem. It happens surprisingly often; for instance, it happens when you need to revisit your code because reviewer 2 suddenly asks for a different analysis in the second round of reviews of your paper.
Another sense of “documentation” is the sense of a protocol. This can come in handy when you are in need of documenting your work, e.g., for a class. Copying and pasting individual inputs and outputs from the command window to a word processor can get tedious quickly. It might be easier just to copy the entire command history and paste that, but it lacks the outputs. A simple solution is to type diary, which toggles the function diary on (it is off by default). If it is invoked in the absence of a filename, “diary” will be the filename, in the “current folder” directory. Of course you can specify a filename, e.g., by typing
Yet another sense of “documentation” is the documentation of MATLAB itself. We already covered the generic help function in Chapter 2; however, as you might appreciate by now, MATLAB uses a great deal of punctuation, all of which has distinct meaning. This can seem overwhelming to the beginner. But don’t despair. You don’t have to memorize this all. Proficiency will come with use. In the meantime, you can rely on specific MATLAB help functions for reminders, such as:
>>help punct %Details on punctuation
>>help relop %Details on logical and relational operators
>>help paren %Explains parentheses, braces, brackets and their use
Executing these functions by themselves (without help) doesn’t do anything. They are specific help functions to remind you of the syntax.