Creating a Figure

Using Matlab to create figures

This mini-tutorial was created in the early days of Figure Composer. It does not demonstrate all the features nor all the different kinds of graphs you can create with the application. Nor does it show you how to load raw data sets into the data presentation nodes in your figure. But it does give you an indication that creating a figure from scratch can be tedious.

Since Matlab has long been ubiquitous as an analysis tool in the sciences, many users asked that Figure Composer support importing Matlab FIG files. Toward that end, the "FIG-to-FypML import engine" was introduced in Version 4.2.x (mid-2013), and since then Matlab has become an indispensable component in the workflow toward creating publication-quality figures with FC. The data analysis and initial figure creation happens in Matlab, and then the Matlab figure is converted into a FypML figure either via the Matlab utility function matfig2fyp(), or by saving it to a .fig file and importing it directly into FC.

Let's start with a step-by-step explanation of how to build a figure from the ground up. To get the most from this mini-tutorial, it is best to start Figure Composer and carry out the instructions on this page as you read along. When you're done, you should see a figure very similar to the one shown on the right (your figure might be a bit larger or smaller, and the text may look different depending on what fonts are installed on your machine).

The graph's initial properties are on display in the Property Editor. Note that the editor's contents are different from what they were when the figure node's properties were on display! On the Main tab, verify the graph's initial width W, height H, and location (X, Y). A graph's "data viewport" is the rectangular window to which a data coordinate system is assigned in accordance with the graph's axis ranges. The axes are drawn outside this viewport in a single-quadrant layout. Try modifying any of the four properties and note the change in the graph's position or size; a portion of the graph may disappear because the parent figure always clips content that falls outside its bounding rectangle. You can also use the mouse to interactively move the graph on the canvas. When you're done, reset the graph's size and position to the following values: X = 0.75in, Y = 0.75in, W = 4in, and H = 3.75in. This will leave a little room near the top of the figure for a title line.

To add that title, put the selection back on the figure node by clicking on the icon labelled "Figure" in the figure tree. Then press the appropriate button in the toolbar to add a label object to the figure (alternatively, select Edit|Insert|Text label from the menu bar). The initial text reads: "label". In the Figure Navigator, the label node is appended to the figure node's child list, and the label's text appears in the entry. To get the title as shown in the final version of our figure, we need to make some changes. First, reposition the label by setting X = 50% and Y = 95% using the relevant controls in the Property Editor. Use the two sets of toggle buttons to center the label vertically and horizontally. Use the text field to change the label's text to the desired title. Finally, use relevant controls to change the label's font size to 12 (font size is always in typographical points, as in most text editing programs) and the font style to italic.

We are now ready to make changes and additions to the graph itself. Start with the vertical axis. The easiest way to select that object is to use the mouse: simply "click" on the axis label in the Figure Canvas. The blue overlay rectangle should now highlight the rendering of the axis (including the label). In the Figure Navigator, observe that the parent graph node is highlighted with a blue rectangular outline. The "Graph Properties" editor is on display, with the Y tab in front to show the properties specific to the graph's vertical or Y axis.

In the Axis & Label subordinate tab, find the text field that currently contains "V AXIS"; change this to "f(t)". Above this text field are two numeric edit controls displaying the coordinate range spanned by the axis; change these to read "-50" to "50". Notice that the tick marks are automatically adjusted.

In the final version of our figure, the horizontal axis has been replaced by a calibration bar. To add the bar to the graph, first make sure the graph node is currently selected. As an exercise, select the root figure by clicking on the figure icon (labelled "Figure") at the top of the node tree displayed in the Figure Navigator. Now select Edit|Insert from the main menu and observe that the only graphic objects you can insert in a figure are shape, label, line, and graph. Now select the graph and select Edit|Insert again: all of the graphic objects listed are enabled, because a graph can be a container for any one of them.

Add the calibration bar by choosing Edit|Insert|Calibration bar from the menu, or by pressing the corresponding button in the toolbar. The program adds a horizontal calibration bar, centering it by default at the location (67%, -0.5in) with respect to the parent graph's viewport. The negative y-coordinate locates it 0.5 inches below the viewport's bottom edge, while the x-coordinate places it 2/3 of the way along the viewport's horizontal dimension. The default length is 10, so the calibration bar is about one-tenth the length of the corresponding axis (the units of measure for the bar's length are the implicit units associated with that axis -- generally called user units in this guide).

We'll fine-tune the appearance of the calibration bar in a moment. First, switch the selection to the horizontal axis, then check the Hide? box in the Axis & Label subordinate tab in the Property Editor. The horizontal axis disappears entirely. Change the coordinate range of the axis to [0 1000] and enter a label for the axis units: "sec" for seconds. Observe that Figure Composer has automatically adjusted the length of the calibration bar and included the units just entered in the bar's label!

Of course, the calibration bar looks terrible at this point -- a length of 10 user units is far too short. Select the calibration bar, then enter "200" for the bar's length in the Property Editor. In addition, move the bar's center point to (75%, -10%), select the linedown symbol for the bar's end-cap decoration, and set the end-cap size to 0.1in.

All that remains is to add some data and a legend to our graph. Rather than fabricate a data set, we choose to add a couple of function elements to the graph. Press the relevant button in the toolbar to add a function object to the graph. This adds a mathematical function of the form f(x) = x defined on the interval [0..10] -- not very interesting. Back in the Property Editor, change the function formula string from "x" to "0.05*x*sin(pi*x/100)"; be sure to hit the Enter key when you're done. If you make a mistake and Figure Composer cannot parse the function definition, the check mark icon to the right of the formula field changes to a red "X"; hover the mouse cursor over this icon to see a brief description of the error encountered. Not much happens on the Figure Canvas until we change the span over which the function is evaluated. Using the numeric edit controls below the formula field, set the range to [0..1000] with a sample interval of 10. You should see an amplitude-modulated sinusoidal function spanning the graph's data viewport, with no marker symbols drawn. This is because the initial marker symbol size is 0. On the Symbols tab, make sure the marker type is "circle" and set the symbol size to 0.05 in. Finally, at the top of the editor panel, set the function's title to "test #1" and make sure that the check box just to the left of the title field is checked, so that the function is included in the graph's automated legend. The function title serves a dual purpose: as a title for the function's entry in the graph legend, and as an identifying label on the user interface -- it appears in the tree node that represents the function object in the Figure Navigator. 

Repeat this procedure to add a second function element, with the formula string "70/(1 + exp(-0.03*(x-200))) - 40". Be sure to change the evaluation interval, or you won't see much of anything. To distinguish this second trace from the first, change the stroke pattern to dashed. And don't forget to set its title/legend entry label to "test #2".

Adding a legend to the graph is a cinch. Just select the graph node, open the Legend tab in the Property Editor, then uncheck the Hide? box on that tab (by default, a graph's legend is hidden when the graph object is initially created). A legend entry appears for each of the function nodes; each entry consists of a sample trace line about one-half inch long, followed by the function's title. Use the Location widgets to move the legend to the upper left corner of the graph: (X, Y) = (5%, 85%). 

That's it. If you have followed all of the steps outlined above carefully, what you now see in the Figure Canvas should be very much like the figure shown at the top of this page. More importantly, you will have likely concluded that building a complex figure can take some time!

Use old figures as templates

Once you've expended the effort to create a complex figure -- with multiple graphs, a precisely aligned and nicely proportioned layout, and so forth -- never throw it away. One way to save a lot of time in Figure Composer is to re-use old figures: copy the figure, replace the old data sets with new ones, then do a little "fine-tuning" to clean up the new figure. Essentially, the original figure is used as a design template to ease the creation of additional figures that are laid out in a similar manner. As you create more and more figures, you'll effectively build up a repertoire of your own design templates from which to choose. And since the Workspace Browser maintains a record of existing figure files you've created, finding a particular figure to re-use is a snap!