2D Graphs

The graph element serves as the container in which data sets are rendered in a two-dimensional coordinate system. It is one of the most complex elements in the FypML "vocabulary", with six component parts:

• The "X" and "Y" axes establish a two-dimensional coordinate system in which data is presented. Each axis, in turn, may contain any number of tick sets that define tick mark locations and labels along the axis. Typically, an axis will have just one such set of tick marks, which we'll refer to as the major tick marks.

• A special "Z" or "color" axis defines the graph's color map. It can be displayed as a color bar adjacent to the graph itself. Color is used to render 3D data in 2D in the form of a heat map or bubble plot.

• The graph's horizontal and vertical grid lines (angular and radial grid lines in the case of a polar plot).

• An auto-generated graph legend.

Under the hood, these component parts are defined by mandatory FypML child nodes under the graph element: axis, zaxis, gridline, legend. A tick mark set, in turn, is defined by an optional ticks node under an axis or zaxis element. For more information about these different node types, see the chapter on FypML. By design, these "component nodes" are not exposed in the Figure Navigator's node tree. It is probably best to think of a graph as a single composite graphic object with a rather complex definition. All of the properties of the graph itself, its axes, legend, and grid lines may be viewed and modified within the Graph Properties editor. As you can see in the adjacent screenshot, separate tabs on the editor panel are dedicated to the X, Y, Z (color) axes, the grid lines, and the automated legend.

The Main tab exposes properties that set the location and size of the graph, the coordinate system type and layout, and its general appearance. The last three rows of widgets display the usual text and draw style properties shared by most graphic objects in Figure Composer. The parameters [X Y W H] define the bounding box for the graph's data viewport and -- although rarely used -- θ specifies its orientation as a rotation about the bottom left corner (X,Y). Like the figure itself, you can rescale a graph in one operation using the Scale (%) field to enter a scale factor, then pressing the Fonts button to resize only the fonts in the graph, or All to resize the entire graph.

The data viewport is the rectangular window to which a data coordinate system is assigned in accordance with the graph's axis ranges and the coordinate system type: cartesian, semilogX, semilogY, loglog, poloar, semilogR (polar with a logarithmic radial axis). All data that lies within the specified X and Y axis ranges will appear within the data viewport; any data outside either range will also lie outside the viewport. If the Clip data? box is checked, any data rendered in the graph is clipped to the data viewport. Use the combo box-like widget in the top-left corner of the Main tab to select the graph's layout. The axes themselves are generally drawn outside the viewport in any of the single-quadrant layouts; for example, in the 1st-quadrant layout, the X-axis appears below the viewport, aligned with its bottom edge, while the Y-axis lies just left of the viewport, aligned with its left edge. The Z axis color bar is not shown by default, but you can always choose to turn it on. It can be displayed adjacent to any edge of the graph, just outside the data viewport.

Using the Auto-range? check boxes on the Main tab, you can configure the graph to automatically adjust the range of any combination of the three axes whenever a data presentation object is added, removed, or modified. Auto-ranging is disabled by default, but you may want to use the feature if you are developing a graph from scratch and want to make sure data is visible as it is added to the graph. The auto-ranging algorithm does not always give the best appearance, particularly with regards to tick mark locations and labels. However, once you've added or update the data within the graph, you can turn off auto-ranging and then manually adjust each axis as needed.

The text field at the top of the Main tab shows the graph's title. This is only for labeling purposes -- notice that the Figure Navigator displays the title in the graph's entry in the node tree. The title string is NOT rendered anywhere on the graph. If you want to place a title somewhere on the graph, add a label or textbox object to the graph (or the parent figure).

Finally, note the field labeled "ID (optional)" just underneath the title field. The notion of a "graphic object ID" was introduced in version 4.6.2 for select object types: text labels, text boxes, and graphs. If the ID is a non-empty string, it serves to uniquely identify the label, text box, or graph among all the graphic objects that comprise a figure. Like the graph title, the ID is never rendered in any way. It is really intended for use outside of Figure Composer --it provides a way to programmatically locate a particular label, text box or graph within an existing FypML figure, so that you can modify the content of the label or text box, replace the graph with a different one, and so on. If you have no need for the object ID, simply leave it blank.

X/Y Axis, Tick Set Properties

The screenshot on the right shows the X-axis tab of the Graph Properties editor; the Y-axis tab is identical. The tab panel is itself a collection of one or more subordinate tabs. The axis range, label, positioning and styling properties are shown on the Axis & Label tab, which is always present. Additional tabs display the properties of any tick mark sets that have been defined on the axis. Tick sets are optional. When a graph is initially created, each axis has a default tick set; its properties appear on the Major Ticks tab. You can define additional tick sets by clicking on the round green icon with the "+" sign; each tick set is displayed on its own tab: Ticks 2, Ticks 3, and so on. Remove any tick set -- including the Major Ticks -- by clicking the "close icon" that appears when the mouse hovers over the tab.

The start and end of the axis range are specified in numeric text fields along the top row of the Axis & Label tab. You can enter any numerical values you want into these two fields. However, if the specified range is invalid in any way (start == end, negative values on a logarithmic axis, etc.), Figure Composer will compute a valid substitute range and use that instead (without altering the values you entered). Furthermore, if the graph's auto-ranging feature is engaged for the X, Y, or Z axis, then the range controls are disabled on the corresponding axis tab -- FC computes the range for you.

On the same row with the range controls are the Log2? and Hide? check boxes. When the axis is logarithmic (e.g., the X-axis in a semilogx or loglog graph), checking the first box will change the logarithmic base from 10 to 2. Checking the second box will hide the axis altogether. This feature is useful in figures containing two or more graphs that share a common axis; the shared axis is hidden on all the graphs except one. You may also want to hide the axis when you choose to use a calibration bar to depict the data scale along that axis.

Below the axis range controls is a text area in which you can enter a single-line or multi-line axis label. To break the label onto two or more lines, insert a linefeed with the Enter key. Whenever you change the content in the text area, be sure to click the adjacent "update" button to apply the changes and see the result on the figure canvas. [Alternatively, use the keyboard shortcut Shift+Enter when the focus is on the text area -- or simply move the focus to another widget.] The Line Ht property determines the inter-line spacing in a multi-line axis label; the larger the value the greater the spacing.

The Gap parameter specifies the distance separating the axis line from the adjacent parallel edge of the graph's data viewport; it is specified as a measurement with physical units like inches, cm, or typographical points. The Offset parameter sets the distance separating the axis label from the axis line, again as a measured physical distance. Finally, the unmarked text field on the same row as the Gap and Offset fields is the axis' unit of measure. This rarely used property is often left blank; its value is used, however, to generate the automated label for any calibration bar that is parallel to the axis.

Tick mark locations are calculated from the tick set range and interval, which are specified in numeric fields in the top row of the Major Ticks tab pane (see screenshot). If you would like the tick set range to track the range of the parent axis, check the Track? box; when that feature is enabled, the tick set range controls are disabled. Any single tick set will render a maximum of 50 tick marks, although typically you'll want far fewer than that. If the axis is logarithmic, the series of 9 check boxes labeled "1" through "9" come into play. These determine where tick marks are drawn within a logarithmic decade. You'll almost always want to check "1", which corresponds to decade divisions like 0.1, 1, 10, and so on. For example, if the axis and tick set have a range of [0.01 .. 10] and you've checked "1", "2", and "5", then tick marks will be drawn at the following locations along the logarithmic axis: 0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10.

Under the 9 check boxes are widgets that control the appearance of the tick marks and their labels. The Len parameter specifies the tick mark length as a measured distance, while the Gap parameter sets the "gap" between the end of each tick mark and its corresponding label. The combo boxes on the same row select the tick mark direction (in = from the axis line toward the graph's data window; out = away from the graph's data window; and thru = bisecting the axis line) and the tick label format (integer, floating-point with 1, 2 or 3 digits after the decimal point, or "none"). Note that the label format may be ignored and scientific notation ("1.7e-4") used in certain situations: when the tick value is larger than 1.0e6, or when the value is smaller than 0.001 and the axis is logarithmic.

As of version 4.6.1, you can specify custom, non-numeric labels for a tick mark set. This is illustrated in the screenshot -- custom labels "A", "B", "C", and "D" are entered in the text field, separated by commas. When custom labels are defined, they are applied to the calculated tick mark locations in the order listed, replacing the standard numeric labels. If there are more labels than tick marks, the extra labels are unused; if there are too few, they are "recycled" until all tick marks are labeled. The custom labels are positioned and styled in the same manner as numeric labels.

Observe that each tick set has its own graphic style properties, like most any other graphic object in Figure Composer. Often the tick set styling mirrors that of its parent axis, so it may seem like overkill. But there are reasons you might want to style the tick set differently -- for example, you might want to use a smaller font size, or a different font altogether, for the tick mark labels so that they stand out from the axis label.