FypML

For developers and advanced users

This section is only for those who want to learn the specifics about the content and structure of a Figure Composer figure document. It is not necessary to understand this section to use the application.

The figure file generated by Figure Composer is a plain-text ASCII file in which the figure's definition is written in a FC-specific shorthand, or "markup language", called FypML. FypML is a derivative of the industry-standard eXtensible Markup Language, or XML. A complete discussion of XML is beyond the scope of this online guide; suffice to say, it is a generic framework for defining a markup language that describes data and information belonging to a specific application domain in a precise and hierarchically structured manner. FypML is essentially a markup language geared toward the representation of publication-quality figures displaying one or more graphs of 1D, 2D or 3D data. As such, it recognizes a small set of elements that make sense in this domain: figure, graph, axis, label, trace, and so on. Each element typically possesses one or more defining attributes (width, height, font, strokeWidth, strokeColor are examples). Both the content and attribute list for each element class are restricted in a sensible way (e.g., a text label cannot contain a graph node as a child element), as are the set of values any given attribute may take on (strokeWidth=red would obviously be inappropriate).

This chapter defines the set of all recognized FypML elements and attributes, along with the rules that restrict the content and structure of valid markup defining a FypML figure. Note that the information herein does not constitute a valid XML schema or Document Type Definition (DTD), as FypML does not satisfy XML schema rules in all respects.

A historical note: Why a plain-text file format?

The figure document is simply an ASCII text file with content conforming to a precisely defined format. It evolved from the figure definition file used by Phyplot, its predecessor. When we first settled on a format for the Phyplot figure file, the focus was on a format that was easily transportable over the Internet. There was also interest in being able to create or at least view a figure document directly in a text editor. In addition, advanced users might want to create scripts that automatically generated a Phyplot figure from data collected and analyzed within another application, such as Matlab. For these reasons, we settled on developing a plain-text, XML-based markup language for describing Phyplot figures. Figure Composer inherited this format. However, data sets within a figure file are no longer represented as they were in Phyplot, as a series of comma-separated tuples of floating-point string tokens. Instead, data sets are stored in an opaque binary form that is base64-encoded so that it can be written to an ASCII text document. This major format change saves considerable space when writing figure files containing large data sets. However, at the same time, it makes it more difficult to generate a figure document outside of Figure Composer without detailed knowledge of how to write the data sets. We may eventually discard the plain-text format altogether at some point, except that easy transport over the Internet is still an important consideration.

A simple example

Here is a very simple figure created in Figure Composer, along with the FypML markup that defines it:

<?xml version="1.0" encoding="us-ascii" standalone="yes"?>

<?fyp appVersion="3.0.0" schemaVersion="8"?>

<figure psFont="Helvetica" fillColor="000000" strokeWidth="0.01in" strokeColor="000000" strokePat="solid" width="5in"

title="Single cartesian graph, 5in x 5in" loc="1.25in 2.5in" fontSize="10" font="Arial" altFont="sanserif" height="5in" fontStyle="plain" border="0.0050in"

xmlns="http://www.keck.ucsf.edu/datanav/namespace/schema8">

</axis>

</axis>

</trace>

</graph>

<ref>

AAAABHNyYzAAAAAAAAAAAgAAAAsAAAAAQSAAAEEgAABCIAAAQaAAAEKIAABB8AAAQpYAAEIgAABC

bAAAQkgAAEJQAABCcAAAQlwAAEKMAABCSAAAQqAAAEJOAABCtAAAQkwAAELIAABCSGZm

</set>

</ref>

</figure>

The first two lines in the markup are processing instructions; while they may not be omitted, they have nothing to do with the figure rendered. The first line declares a standalone document conforming to the XML 1.0 specification and encoded using the ASCII character set. XML content can be encoded in other character sets to support internationalization. However, all FypML figure documents use ASCII encoding for reasons discussed earlier; non-ASCII characters are included in the content by using a Unicode character escape (e.g, © = '\u00A9'). The second line is a FypML-specific processing instruction that declares the version of the program that was used to prepare the content, as well as the version of the markup schema to which the content conforms. This instruction was added during initial development to support migrating older figures as Figure Composer evolves. Whenever Figure Composer reads in a FypML document, it checks the document's schema version. If the schema is out-of-date, it will migrate the document to the current schema before proceeding.

The remainder of the FypML sample is a tree of element nodes, where each element takes the form:

<elname attrib1="val1" attrib2="val2"> # element "start" tag

content # element content

</elname> # element "end" tag

The syntax is prescribed by the XML specification; depending on the element class, the element content may include other "child" elements, plain character data, both elements and character data, or nothing at all. Here, elname is the "tag" name for an element class, attrib1 is an attribute name, and val1 is an attribute value. The indentation and linebreaks help clarify the tree-like structure of the content, but they are not required. Note that an attribute's value may be implied -- it may be inherited from the parent element or may be currently set to an application-defined default value; in such cases the attribute need not be listed in the element's "start" tag.

The root, or document, node is always the figure element; every valid FypML figure document will contain a single figure node, with everything else inside it. In addition to specifying the figure's size, print location, and border width, this node includes the default values for a number of common attributes, such as font characteristics and drawing colors. If the same font and draw colors are used throughout the figure, then these attribute values are "inherited" down the tree and need not be specified on each and every element.

The figure node in the example contains a single graph element. The figure's width and height attributes define the absolute size of the figure in measurement units like inches or centimeters. Within a figure, child elements may be positioned relative to their parent element's viewport by specifying their location and size as percentages -- which eases the task of resizing a completed figure. In the sample above, the graph's bottom-left corner is located at (15%, 13%) in the parent figure's viewport, while its top-right corner is at (95%, 95%).

Obviously, the graph element is the most important and most complex of all element classes in FypML, since it governs the appearance of two-dimensional graphed data within a figure. Cartesian, semilog, loglog, and polar plots are all supported by the graph element's type attribute; in the example above, the type is implicit, so the default graph type is rendered -- a Cartesian plot. The graph includes two mandatory axis elements; the first encapsulates the horizontal or "X" axis, while the second represents the vertical or "Y" axis (note: for polar plots, the two axes correspond to the angular and radial coordinates, respectively). The axis ranges define the graph's data coordinate system in "user" units (since the measurement units for any data are dictated by the user!). Two mandatory gridline elements define the color, line width, and styling of the graph's vertical and horizontal grid lines. Gridlines are not used often, so the gridline's hide attribute has a default value of "true" -- meaning the gridlines are not drawn, as is the case in this example. These are followed by a mandatory legend element, which lays out the graph's automated legend. Note that there is no legend in the figure. This is because, like the gridline nodes, the legend node is hidden by default (the implicit value for its hide attribute is "true").

After these five mandatory elements, the graph may contain any number of other elements: text labels, lines, data traces, even other graph elements.In the example above, a label element provides a title for the graph, and a trace element appears as a dashed trace connecting the points in the data set, with filled black circles marking the location of each datum. The eleven data points are rendered with respect to the coordinate system established by the graph's axis ranges. If you want to add a data set that covers a larger range, simply adjust the axis ranges accordingly. Also note that FypML separates the data source from its presentation: The trace element describes how to render the data points defined in a separate data set element, which is referenced by an src attribute. All data sources are defined as set nodes in a single ref node, which is always the last child of the root figure element. This organization makes it easier to review the figure document in an ordinary text editor; all data sets, which are encoded in unreadable base64, appear at the tail end of the file.

While the graph container has been around since the very first release of Figure Composer, two additional data containers have been introduced more recently. The graph3d element (as of V5.0.0) offers a true 3D graph container, which uses perspective projection to map the 3D plot onto the 2D figure canvas. The pgraph element (as of V5.1.2) is a specialized 2D polar plot, offering more versatility than the polar coordinate system available in the graph node.

The remaining pages of this chapter provide a succinct listing of all FypML elements and attributes, along with the rules governing each element's content, allowed attribute values, and so forth. It is intended as a reference for developers and for advanced users that wish to develop programs that can generate valid FypML figure documents.