Elements

This page defines each of the elements recognized in the FypML namespace, in alphabetical order. Each description includes the element's purpose, its attribute list, and restrictions on its content. Element attributes are divided into three categories: required, inherited, and optional. Required attributes must be specified in the element's start tag. Inherited attributes are optional attributes that -- if they are not explicitly specified in the element's start tag -- inherit their value from the nearest ancestor element for which the corresponding attribute has been explicitly set. The only inherited attributes in FypML are graphic styles like font and strokeWidth. All other optional attributes have application-defined defaults. These default values are quoted in parentheses following the name of the optional attribute. See the Attributes page for a complete description of each attribute listed in these element descriptions.

area : A stacked area chart.

This data presentation element, introduced in DataNav 4.7.1, is specialized for rendering a relatively small collection of data sets {X: Y1 Y2 Y3 ...}  as a stacked area chart. The data source can be in any of the four 2D formats: ptset, series, mset or mseries. When the source is a mset or mseries collection, up to 20 individual data sets will be plotted from the collection, with each set rendered as a distinctly colored band in the area chart; the bands stack one on top of each other. Any additional sets beyond the first 20 are ignored. 

Area, bar and pie charts are all examples of "grouped-data" presentation elements. Each data group is associated with a unique fill color and legend label, and each group is represented by a separate entry in the parent graph's automated legend. The data group colors and labels are listed as string tokens in the element's text content, typically in color/label pairs: "color1, label1, color2, label2, ...". Each string token that can be parsed as an RGBColor attribute (6-digit hex, 8-digit hex, or the value "none") is treated as a color; all other non-empty tokens are treated as legend labels. The colors and labels are applied to the data source's individual member sets in the order they appear in the text content. If fewer colors and/or labels have been specified than the number of member sets, then Figure Composer will automatically generate the missing colors and labels. Any extra colors and labels are simply ignored.

axis : The primary or secondary axis of a 2D graph, or any of the three axes of a 3D graph.

The title attribute specifies the text string that appears as the axis's automated label. This label is oriented in the same way as the axis line itself, centered along the line, and offset from the line in accordance with the labelOffset property and the axis's position with respect to the graph's data window. Normally, the label is drawn as a single text line. However, if the text string contains any line break characters, then the label will be broken across two or more lines. In this case, the lineHt property (new in V4.5.2) specifies the baseline to baseline spacing from one text line to the next.

(As of V5.0.0) Observe that the same element is used to define the X and Y (or theta and radial, in a 2D polar plot) axes of the 2D graph, and the X, Y, and Z axes of the 3D graph node, graph3d. The log attribute applies ONLY in the 3D context; it determines whether the 3D graph axis is logarithmically or linearly scaled; it is ignored for in a 2D context, since the axis scaling is set by the 2D graph's coordinate system type. The units attribute is ignored in the 3D context, because it only applies to calibration bars in a 2D graph; graph3d does not support calibration bars at this time.

Another important difference between 2D and 3D graph axes: FC requires that start < end for any 3D graph axis; this need not be the case in a 2D context.

 

bar : A traditional bar plot.

This data presentation element, introduced in DataNav 4.6, is specialized for rendering a relatively small collection of data sets {X: Y1 Y2 Y3 ...}  as a traditional bar plot. It supports four different display modes: "vgroup" (groups of vertical bars), "hgroup" (groups of horizontal bars), "vstack" (single stacked vertical bar at each X coordinate), and "hstack" (single stacked horizontal bar at each Y coordinate). The data source must be an mset or mseries collection; up to 20 individual data sets will be plotted from the collection, with each set as a distinctly colored bar group. Any additional sets beyond the first 20 are ignored. The data should always be specified for the vertical display modes; in the horizontal modes, the data is simply transposed. Bar width is specified as an integer percentage (5-100), and this determines the spacing between adjacent bars at a given value of X, as well as the gap between adjacent bar groups (in the grouped display modes).

Like the area chart, the bar plot is a "grouped-data" presentation node, and its text content contains a sequence of RGBColor and label string tokens identifying the fill color and legend label for each data group (i.e., a bar group). See the area element for details.

back3d : One of the three backplanes in the 3D boxed backdrop for a 3D graph

(As of V5.0.0) Typically a 3D graph -- defined by the graph3d element -- will be configured in one of two "boxed" backdrop styles, in which the three back-most faces of its 3D data box are drawn as 4-sided polygons possibly containing grid lines. These faces lie in the XY, XZ, and YZ "backplanes" of the 3D graph, and the appearance of each is governed by a back3d component of the graph3d node.

When rendered, the backplane perimeter is filled IAW the fillColor attribute, then stroked IAW the stroke properties of the relevant back3d node. The appearance of any grid lines in the backplane are governed by the appropriate gridline component of the parent graph3d node.

calib : A vertical or horizontal calibration bar within a graph.

contour : A data presentation node specialized for rendering a 3D dataset Z=F(x,y)  in 2D as a contour plot, a "heatmap" image using color indexing, or both.

This data presentation element was introduced in DataNav 5.0.1 (schema version 22), replacing the now-deprecated heatmap node. It renders a 3D data set in a 2D graph container and requires an xyzimg set, which is essentially a WxH matrix containing the values of an independent variable Z = f(X,Y) regularly sampled over a rectangle [X0..X1, Y0..Y1] in (X,Y)-space. Four different display modes are offered: 

Note that a contour node will NOT render at all if the parent graph is a polar plot; it is currently supported only in standard Cartesian, log-log, or semilog plots.

DataNav currently supports ten different color maps: gray, reversegray, hot, reversehot, autumn, reverseautumn, jet, reversejet, tropic, reversetropic. Originally, the color map selection was specified as a cmap attribute defined on the heatmap itself, and the entire observed data range was mapped linearly onto this colormap. As of DataNav 3.1 (schema version 9), color mapping is controlled by properties of the parent graph's third, or Z, axis. See discussion for the zaxis element. 

ebar : Specifies the graphic styling applied to the rendering of standard deviation data (error bars, error band, etc.) on a trace element.

figure : A single DataNav figure -- the root node and topmost renderable object in a valid and complete FypML fragment. Specifies the default values for all inheritable graphic styling attributes.

function : A mathematical function y = f(x) that is rendered in the data viewport of its parent graph.

graph : A two-dimensional graph, with three defined axes, two sets of grid lines, and an automated legend. Serves as the container for all 2D data presentation elements.

graph3d : A three-dimensional graph, with three defined axes, three sets of grid lines, three backplanes, and an automated legend. Serves as the container for all 3D data presentation elements.

(As of V5.0.0) The 3D graph object is the container for all true 3D data presentation nodes. Its 3D coordinate system XYZ and all 3D plots therein are projected onto the 2D figure canvas. The perspective projection is governed by properties of the graph3d node itself and its three axes. Plots are rendered in a 3D data box, the dimensions of which (in 3D space) are given by the width (X), height (Y), and depth (Z) attributes.  The three axis components set the axis ranges that map to each corresponding dimension. The loc attribute specifies the location of the origin of the XYZ coordinate system in the 2D viewport defined by the parent figure. The orientation of the coordinate system about that origin is set by two rotation angles: rotate specifies the rotation about the Z axis (in degrees CCW), while elevate specifies the subsequent rotation about the X axis. The "camera viewpoint" for the perspective projection lies in front of the 2D canvas, at a perpendicular distance P*D from the coordinate system origin, where P is the projection scale factor (pscale attribute) and D = max(width, height, depth). 

The graph's 3D data box can be depicted in any of several alternative backdrop styles, selected by the backdrop property. The backdrop can be hidden altogether, or only the axes may be drawn -- either emanating from the back-bottom corner of the 3D data box (axesBack) or lying along three outer edges of that box (axesOuter). More typically, however, a boxed backdrop is presented (box3D, openBox3D, xyPlane), with XY, XZ and YZ backplanes stroked and filled IAW the back3d components, and any grid lines in those backplanes drawn IAW the corresponding gridline components. The axes are drawn along the three outer edges of the data box IAW the axis components. In the box3D backdrop style, all 3 backplanes are visible and the three edges that connect at the front corner of the data box are also stroked; in the openBox3D backdrop, the front three edges are omitted; in the xyPlane style, only the XY backplane is rendered, along with the 3 axes and any grid lines in that backplane.

While the graph3d node can contain generic 2D graphic objects like text labels and text boxes, those objects cannot be located in 3D space because their loc attribute lacks a Z-coordinate. For positioning such objects, graph3d has a "2D viewport" defined by the rectangle that tightly bounds the 2D projection of the 3D data box (axes excluded) onto the 2D figure canvas. Obviously, this rectangle will change as changes are made to any graph3d property that affects the 2D projection. It is best to position such generic 2D graphic objects using percentage units. For example, to center a title above the 3D graph and keep it there despite changes in the graph's dimensions or orientation, use a label node at (50%,105%), horizontally centered.

The cmap attribute specifies the color map associated with the 3D graph. As in the 2D context, the 3D graph's color map is used exclusively to map the Z-coordinates of data points to a particular color. Currently, there is no support for depicting the color map via some sort of color bar analogous to the 2D graph's color axis (the zaxis element), but that will likely be provided in a future release.

gridline : The set of grid lines corresponding to one axis of a 2D or 3D graph.

Every graph element contains two gridline child elements (always the fourth and fifth children of the graph node). The first gridline node describes the graph's primary grid lines (parallel to the X-axis in a Cartesian graph or the concentric circles in a polar plot), while the second describes its secondary grid lines (parallel to the Y-axis in a Cartesian graph, or radial lines in a polar plot). The gridline element merely defines the appearance of the grid lines and determines whether or not they are rendered; the exact positioning of the grid lines depends on the major tick set (first ticks child of an axis node) defined on the orthogonal axis. If no such tick set exists, the grid lines will not be drawn.

(As of V5.0.0) Every graph3d element contains three gridline child elements  -- the fourth, fifth, and sixth child nodes, specifying the grid lines perpendicular to the X, Y, and Z axes, respectively (note the difference vs the 2D context!). In the 3D context, the hide attribute is ignored since it is really unnecessary. To hide any set of grid lines, simply specify a zero strokeWidth or a transparent strokeColor. The hide attribute may be removed altogether in a future release.

image : An embedded image scaled to fit within a specified rectangular box.

The image element, introduced in schema version 15 (application version 4.4.1), allows you to embed an image into a figure. While the image data is stored in the FypML document in PNG format, Figure Composer lets you embed any JPEG or PNG source image. The image -- or a cropped version of that image -- is scaled to fit within a target rectangle defined by the element's bounding box (loc, width, and height attributes), less an inner margin that is the same on all sides (the gap attribute). If the image's aspect ratio does not match that of the target rectangle, the scale factor and location of the image are adjusted so that its aspect ratio is preserved and it appears centered both horizontally and vertically within the target rectangle. The bounding box for the text block is stroked in accordance with the element's stroke properties and filled as specified by the bkg attribute -- using these properties you can render a "frame" of sorts around the embedded image. The optional crop attribute specifies a crop rectangle so that you can select only a portion of the original source image for display; the entire source image is stored in the FypML document, so it is always possible to recover the original image by resetting the crop rectangle.

[NOTE: For simplicity's sake, the image data is embedded within the element's text content rather than in a separate node in the FypML document's ref element -- as is done for data sets. If the image is large, the document will be more difficult to review in a text editor.]

label : A single-line text label.

legend : Defines the appearance of a graph's automated legend.

line : An arbitrary line segment.

pie : A pie or "donut" chart.

This data presentation element, introduced in DataNav 4.7.1, is specialized for rendering a small 1D data set as a pie chart. It is rendered only when its parent graph is in polar coordinates. While the data source can be in any of the four 2D data formats (ptset,series, mset, mseries), the X-coordinate data are ignored; the pie chart reflects only the Y-coordinate data [y0..yN]. Each value y is represented by a "slice" in the pie with angular extent 360*y/T, where T=sum(y0..yN). Only the first N=20 values are taken into account; any additional values are simply ignored and any NaN or negative value is treated as zero.

The required float-valued start and end attributes specify the inner and outer radii of the pie chart; obviously, start must always be strictly less than end. A standard pie chart has start==0; for a "donut"-shaped chart, use a non-zero inner radius.

The displace attribute is an integer-valued property that indicates which pie slices, if any, are displaced radially from the chart origin: if bit N == 1 in displace, then the pie slice corresponding to datum yN is displaced. For a typical pie chart with no displaced slices, set displace to zero (the default). The gap attribute specifies the radial offset of any displaced slice as an integer percentage of the outer radius.

Like the area chart, the pie chart is a "grouped-data" presentation node, and its text content contains a sequence of RGBColor and label string tokens identifying the fill color and legend label for each data group (i.e., a pie slice). See the area element for details.

raster : A presentation node specialized for rendering "spike trains" or histograms.

This data presentation element is specialized to render a collection of sampled data as encapsulated by the raster1d data set format. This data set is a collection of zero or more x-rasters, a sequence of sample values in x. The node was originally introduced to render the occurrence times of action potentials as a sequence of short vertical hash marks -- "spike trains". But it can also present a histogram of the sampled data, whether those be spike times or anything else.

The mode attribute defines the display mode: trains / trains2 / histogram / pdf / cdf. In trains mode, each component raster is rendered in spike-train fashion, with short vertical hash marks drawn at each raster sample value. All sample values are offset in accordance with the value of xoff, which is always in "user" units. The baseline attribute serves as a y-coordinate offset; the baseline of the first raster is positioned there. The height attribute specifies the height of each raster hash mark in stroke-width units, while the spacer attribute specifies the distance between the baselines of consecutive raster lines, again in stroke-width units. Mode trains2 is similar to trains, except that the spacer attribute is ignored and the baseline of each individual raster is its ordinal position (starting at 0) in the raster collection, offset by the value of the baseline attribute; thus, the raster train is more closely tied to the vertical axis of the parent graph.

In histogram mode, DataNav renders a histogram computed from the sample data. The nbins attribute specifies the number of bins into which the histogram is divided. The start and end attributes set the sample range over which the data is binned; if start >= end, the actual observed sample range is used.  For each bin in the histogram, a bar is drawn from the specified baseline value to N, the # of samples falling in that bin; the bar spans the entire bin width. Bars are stroked IAW the node's stroke properties and filled with the specified fillColor; transparent, translucent or opaque colors are all supported. Typically, baseline will be 0, but that is not a requirement -- so a histogram bar could extend above or below the baseline. In this display mode, if the avg flag is set, the bin value is instead the average count per raster per bin (total count per bin divided by the number of individual rasters in the collection).

Two additional display modes were added in version 5.0.2 that offer an estimate of the data collection's probability density function, pdf, or cumulative density function, cdf. In the former case, each bin value = C/(T*W), where C is the sample count in that bin, T is the total sample count over the specified sample range, and W is the bin width. In the latter case, each bin value is S/T, where S is cumulative total sample count across the current bin and all preceding bins; the last bin, of course,

will have the value T/T = 1. The avg flag is ignored in these two modes. Also, unlike histogram mode, the histogram bars are drawn from baseline to (baseline + bin value).

ref : The container node for all "local data sources" stored in a DataNav figure. It occurs exactly once, as the last child of the figure node.

scatter : An X-Y scatter or bubble plot

This data presentation element, introduced in DataNav 4.6.2, is specialized for rendering a relatively small 2D or 3D point set as an X-Y scatter or bubble plot. It supports four different display modes: scatter (symbol of fixed size and color drawn at each well-defined data point), sizeBubble (symbol size varies with the Z-coordinate of each data point; fill color is constant), colorBubble (fill color varies with Z; fixed size), or colorSizeBubble (both size and fill color vary). The data source must be either a 2D ptset or the new 3D data format xyzset. Obviously, the ***Bubble display modes are applicable only when the data source is xyzset. 

If the display mode is scatter or sizeBubble, all symbols are filled with the color specified by the node's fillColor property (and since fillColor can be transparent, you can have "hollow" symbols in these modes). For the colorBubble and colorSizeBubble modes, the symbol representing a 3D data point (X,Y,Z) is drawn at (X,Y) and filled with the (opaque) color identified by mapping Z to the parent graph's color map, in accordance with the current definition of the graph's color axis. For best results in these modes, it is important that the color axis range match that of the data source backing the scatter node.

If the display mode is scatter or colorBubble, all symbols are drawn at the same size, as specified by the size attribute; in these modes, size will typically be relatively small, say 0.1in. In the sizeBubble and colorSizeBubble modes, the size of the symbol representing a 3D data point (X,Y,Z) is calculated as size*Z/Zmax, where Zmax is the maximum observed Z-coordinate value. Thus, the size attribute represents the "maximum symbol size" and in these two display modes it may be set to a relatively large value. Note that it is expected that all Z-coordinate data will be non-negative; else expect some strangeness!

Regardless the display mode, all marker symbols are stroked IAW the scatter node's stroking properties.

scatter3d : A 3D scatter, bubble, stem or line plot.

(As of V5.0.0) This 3D data presentation element is intended to render a 3D point set as a scatter, bubble, stem or line plot in a 3D graph. Like its 2D counterpart, It supports four different display modes: scatter (symbol of fixed size and background fill drawn at each well-defined data point), sizeBubble (symbol size varies with the Z-coordinate of each data point; background fill is the same for all symbols), colorBubble (background fill varies with Z; fixed size), or colorSizeBubble (both size and background fill vary). The data source format must be the 3D xyzset format.

All symbols are filled IAW the scatter3d node's bkg property (the symbol component's fillColor property is ignored). Unlike the 2D scatter plot, scatter3d supports a gradient fill, primarily so that you can reinforce the illusion of a 3D plot. If you pair a circular or elliptical symbol shape with a radial gradient fill that is bright white at the focus and a darker color at the perimeter, you create a false lighting effect that makes the 2D symbols look more three-dimensional! In the scatter and sizeBubble display modes, all symbols are filled with the same background fill as specified by the bkg property. In the colorBubble and colorSizeBubble modes, the symbol representing a 3D data point (X,Y,Z) is drawn at the projection of (X,Y,Z) onto the 2D plane, and it is filled with the color identified by mapping Z to the parent 3D graph's color map. If the background fill is a gradient, the mapped color replaces the second color stop, while the first color stop never changes.

If the display mode is scatter or colorBubble, all symbols are drawn at the same size, as specified by the size attribute of the symbol component; in these modes, size will typically be relatively small, say 0.1in. In the sizeBubble and colorSizeBubble modes, the size of the symbol representing a 3D data point (X,Y,Z) is calculated as size*Z/Zmax, where Zmax is the maximum observed Z-coordinate value. Thus, the size attribute represents the "maximum symbol size" and in these two display modes it may be set to a relatively large value. Note that it is expected that all Z-coordinate data will be non-negative; else expect some strangeness!

Regardless the display mode, all marker symbols are stroked IAW the stroking attributes of the required symbol component.

Unlike its 2D counterpart, scatter3d also supports drawing a "stem line" from each well-defined data point (X,Y,Z) to a corresponding point (X,Y,Zo) on the so-called "stem base plane", Z=Zo. The value Zo is set by the baseline attribute.  Alternatively -- if stemmed == false -- a single, piecewise continuous trace line is drawn to connect the data points in the order in which they are listed in the data source. The stems or trace line are stroked IAW the stroke properties of the scatter3d node itself. If you want neither stems nor trace line, simply set the node's stroke width to 0 or make its stroke color transparent.

set : A raw data set that is rendered within a data presentation node in the DataNav figure.

This organizational scheme effectively separates the actual data from its presentation in a figure. This separation offers several advantages: (1) The same data can be repeated in several different graphs without having to repeat the data at several different places in the XML document. (2) A figure template can be constructed with any number of data presentation nodes defining how the data should appear. The same template can then be used as a "view" for multiple data sets, simply by loading the desired data sets into the figure document, and making sure each id attribute of a set node is matched to the src attribute of the target presentation node. In fact, in the current conception of a DataNav portal, a particular instance of a portal hub view is created by injecting hub data into the appropriate set nodes of the view's figure template.

A text-only element, the set node's text content is the actual binary data encoded as a base64 string. The dataset contents are stored in this (often very long) string as follows, in precisely the order listed:

Note that the encoded text content actually includes the data set identifier and format. These should match the values of the id and fmt attributes, respectively (those version 7 attributes were kept for convenience's sake but may be removed in a future schema version).

The exact content of the raw data array varies with the data set format, defined by the fmt attribute. Seven different formats are possible. In the descriptions that follow, B and L refer to the data set breadth and length, respectively.

For the ptset format, (xStd, yStd) are the standard deviations in x and y at each point (x,y), while (xe,ye) determine how nonzero standard deviations are rendered as error bars. If ye = 0, an error bar of length 2·yStd is drawn through the data point (x,y), from (x, y-yStd) to (x, y+yStd). If ye = 1, a one-sided error bar is drawn from (x,y) to (x, y+yStd); if ye = -1, the one-sided error bar is drawn from (x,y) to (x,y-yStd). If ye is any other value, then no error bar is drawn, even if yStd is nonzero. Analogously for xe. Only the data point's coordinates are required. An error bar is drawn only if the corresponding standard deviation is explicitly specified and nonzero; only the absolute value of the standard deviation is used. If an error bar position code is omitted (ie, if the datum tuple is {x y yStd} or {x y yStd ye xStd}), the error bar will be centered on the data point. [NOTE: To get a data point with a horizontal error bar only, we CANNOT use {x y xStd}, because the third number is always interpreted as yStd. Use {x y 0 0 xStd xe} instead.]

Note that NaN is acceptable as a floating-point number in the raw data array. It is used to mark an ill-defined point in the data. When rendered in a DataNav figure, an ill-defined data point usually creates a "gap" in the polyline.

What if the same data set is used twice in a figure, but under different IDs? Since data sets in DataNav are immutable objects, such a situation could easily arise as the author creates a figure. For example, he might paste the same data presentation node into two graphs, then give the underlying dataset a different ID in each graph. If the data set were very large, it would be extremely wasteful to store the raw data in both set elements when we write the figure file. The using attribute addresses this problem. If a set element with id = "B" contains exactly the same data as another set with id = "A", then the text content of set B is left empty and its using attribute is explicitly set to "A".

The v7 attribute was added to assist migration of the old "comma-separated tuples" text content of schema version 7 to the new base64 binary-encoded content in schema 8. If the v7 attribute is explicitly set to true, then the set element's text content will be in the version 7 format, which is described below. In this case, if the dx attribute is explicit, it is taken to specify the sample interval for a series or mseries data set (and the initial value x0 is assumed to be 0). If the v7 attribute is not present, then the dx attribute should not be present (if so, it is ignored), and the text content is in the current base64 binary format already described.

In schema version 7, the set element's text content was a comma-separated list of data point tuples. Each tuple was a list of 1 or more whitespace-separated floating-point number tokens. The expected format of each tuple was determined by the fmt attribute value:

Note that the other three data formats are not mentioned here, as they were introduced later in Figure Composer's development. 

IMPORTANT: The only enforced constraints on the text content were: (1) it is a comma-separated list of tokens, and (2) each such token is a whitespace-separated list of at least one floating-point number. This means that a tuple could have a length that was inconsistent with the current set format. If it was too long, the extra data was retained (we don't want to lose data!) but ignored. However, if it was too short, then the tuple was invalid, and the entire set was considered invalid. The user must fix the problem by changing the set format! This is no longer an issue in the new schema.

shape : A generic shape of arbitrary size.

(As of V4.7.2, schema version 20) The bkg attribute was added to give user more control over a closed shape's background fill and the color used to paint its centered label (title attribute). This attribute supports a solid-color, axial gradient, or radial gradient fill. The centered label, if any, is now painted IAW the fillColor attribute. Prior to this change, a closed shape was filled with the color specified by the fillColor attribute, and the centered label was painted using the strokeColor.

The former size attribute was replaced by separate width and height properties in V4.7.2 so that the shape can be resized independently in the horizontal and vertical directions.

surface : A 3D surface rendered as a polygonal mesh with optional wireframe.

(As of V5.0.0) This 3D data presentation element renders a 3D data set as a surface in a 3D graph. The surface is rendered as a polygonal mesh. For each value of (X,Y) in the data source and mesh cell dimensions (DX,DY), we compute the 3D vertices (X,Y,Z1), (X+DX,Y,Z2), (X+DX,Y+DY,Z3), and (X,Y+DY,Z4) from the data source. These are projected from 3D space onto the graph3d container's 2D viewport, forming a 4-sided polygon in 2D. Each such polygon is stroked IAW the surface node's stroke properties (solid strokes only) and filled IAW the fillColor and cmap properties. If the stroke width is 0 or the stroke color is transparent, the mesh lines are not drawn. If the cmap flag is false, then all mesh polygons comprising the surface are filled with the solid color specified in fillColor; in this case, if fillColor="none", the polygons are not filled at all. If cmap="true", then each polygon is filled with the color that maps to its assigned Z-value, as determined by the 3D graph's current color map. The Z-value of a mesh polygon is the average value of Z across its vertices (plus any "skipped" samples within the mesh cell due to sub-sampling to limit mesh count). Thus, you can render the surface as a "wire frame" mesh, a single color or color-mapped surface (like a 3D heatmap), or both.

The surface node's data source must adhere to the xyzimg format, which is essentially an NxM matrix of Z-values sampled over a regular grid in X,Y-space. The set includes the range [X0..X1] spanned by the data in X and the range [Y0..Y1] spanned in Y. Thus, DX=(X1-X0)/N and DY=(Y1-Y0)/M, and we can calculate the values of X and Y for each value of Z in the matrix. N is the mesh size in the X direction, while M is the mesh size in the Y direction. As mesh size increases, the time it takes to render the surface increases dramatically. As a compromise between rendering speed and fidelity, the limit attribute defines a maximum mesh size, S; its allowed range is [25..500]. As long as max(N,M) <= S, the entire data set is plotted without "sub-sampling". If N>S, then we find the smallest integer k>=2 such that N/k <= S. Then the mesh cell dimension in X will be DX*k. In computing the average Z value assigned to a mesh cell, the values at the "skipped" vertices are included in the average, unless the value is NaN. An analogous approach applies to the Y dimension when M>S.

What if the data set contains NaN values? As long as the Z value is well-defined at each of the 4 vertices of the mesh cell, the projected polygon is rendered. If any of the four vertices is ill-defined, then nothing is drawn for that mesh cell -- leaving a "hole" in the surface.

symbol : Governs the appearance of marker symbols in the rendering of any data trace element or mathematical function.

textbox : Multi-line text intended to fit within a specified rectangular box.

The textbox element allows you to put multi-line text labels within a figure. Prior to its introduction in schema version 15 (Figure Composer 4.4.1), you would have to create individual label nodes and carefully align them with respect to each other. The bounding box for the text block is stroked in accordance with the element's stroke properties and filled as specified by the bkg attribute. The optional gap  attribute specifies the size of an inner margin separating the text block from the edges of the bounding box. The horizontal alignment indicates how each line in the text block is positioned: starting on the left margin, ending on the right margin, or centered within the bounding box. The vertical alignment indicates how the entire block is positioned vertically: first line of block is aligned with the top margin, last line is aligned with bottom margin, or the block is centered vertically with respect to the bounding box.

Line breaks in the text block always respect the width of the bounding box (less the left and right margins, if nonzero). If any single word is too long to fit, it will be broken across two or more consecutive lines. After determining the line breaks, if there are too many lines to fit within the bounding box, then the text block will flow past the bottom margin, top margin, or both margins -- depending on the chosen vertical alignment. The lineHt property (new in V4.5.2) specifies the baseline to baseline spacing from one text line to the next (as a fraction of the font size). If the clip flag is set, then any text outside the margins is cut off.

All text within the text block is rendered in the same font. It is not possible to apply different fonts to different sections of the text block.

ticks : A set of tick marks rendered along a 2D or 3D graph axis.

(As of V5.0.0) There is a subtle difference between tick marks on a 2D graph axis vs a 3D graph axis. The graph3d element does not support auto-ranging of its axes, and there is no "track parent axis" feature for tick sets on a 3D graph axis. By design, the start, end, and intv attributes are all required in a 3D graph context and should satisfy: intv > 0, start <= end.

trace : A data trace, which renders a data set within a graph in one of several supported display modes.

This is a data presentation element, not a data storage element. The actual data set is referenced by the src attribute. Currently, only "local" data sources are supported -- i.e., data sets that are defined with the same figure document. The src attribute's value takes the form "#{srcid}" where {srcid} is the value of the id attribute of the set element (found in the single ref node of the root figure) that serves as the data source. It is considered an error if {srcid} does not identify an existing data set in the document. Note that the trace node is only suited for the display of ptset, series, mset, or mseries-formatted datasets. The specialized presentation nodes raster and heatmap render the newer data set formats raster1d and xyzimg, respectively.

The mode attribute defines the trace display mode: polyline, staircase, errorband, histogram, or multitrace. In polyline mode, the referenced data set is drawn as a "connect-the-dots" polyline, rendered in accordance with this element's styling attributes. If the data includes nonzero standard deviations in X and/or Y, error bars are drawn at each data point, defined and styled IAW the element's ebar child. In a polar plot, error bars in X will be circular arcs. Finally, marker symbols may be rendered at each data point, defined and styled IAW the element's symbol child. The staircase mode is very similar, except that consecutive data points are connected by a sample-and-hold "step" instead of a straight line segment; this mode might be used to emphasize the discrete nature of the underlying data set.

The errorband mode is intended for data sets with nonzero Y-standard deviation data. In this mode, the variation in the nominal data is rendered as a band encompassing +/-1 standard deviation about the nominal trace {x,y}. One polyline connects the points {x, y+dy}, while another connects the points {x, y-dy}, where dy represents one standard deviation in y at each point (x,y). Both standard deviation polylines are styled by the element's ebar child. The band between the two polylines will be filled with the ebar's current text/fill color (use a transparent fill -- fillColor = "none" -- if you don't want to fill the band. Finally, a polyline representing the nominal trace is drawn in accordance with the trace element's own style attributes.

In histogram mode, the data set is rendered as a histogram, possibly adorned with symbols and error bars. The histogram itself is drawn using the style attributes of the trace element, and the histogram bars are stroked and filled IAW the node's current stroke properties and fill color. The barWidth and baseline attributes define the histogram bar width and baseline level for this display mode (they do not apply to the other modes). If the barWidth is 0, the bars are drawn as lines instead. On a polar/semilogR graph, the bars become circular pie wedges (baseline = 0) or radial sections. The symbols and error bars are rendered in the same manner as in the polyline display mode, but no polyline connects the symbols.

Finally, the multitrace display mode is intended for a data source which is actually a collection of two or more individual point sets sharing the same x-coordinates. Typically, the individual point sets represent repeated measures of the same stochastic variable over time, so that the collection captures the variation in that variable. The individual point sets are drawn as separate polylines, each styled in accordance with the trace element's ebar child. If that child node's cap attribute is not "none", then it specifies a marker symbol to be rendered at each well-defined data point across all sets. On top of all this, a nominal trace -- representing the average across the individual data sets -- is rendered as a polyline with marker symbols -- but only if avg==true (the avg attribute has no meaning for the other display modes). The polyline is styled by the attributes of the trace element, while the marker symbols are styled by the attributes of its child symbol element. Note that, if the referenced data set does not contain two or more component point sets, then all that will be rendered is the "nominal" trace.

zaxis : The third, or Z axis, of a graph (currently specialized to control color-mapping properties of certain elements within the graph).

As of DataNav 3.1 (schema version 9), color-mapping of 2D contour plots, heat map images, and bubble plots is controlled by the parent graph's third axis, represented by the zaxis element. If more than one color-mapped data presentation node is displayed in the same graph, all abide by the color-mapping properties of the graph's Z axis:

The Z axis may be rendered along any edge (left, right, top or bottom) of the parent graph's data window. The rendering includes a "gradient bar" displaying the colormap content, as well as an axis line with tick marks and an automated label. The gap attribute controls the space between the gradient bar and the adjacent edge of the data window, the spacer attribute controls the distance between the gradient bar and the axis line, and the size attribute controls the width of the gradient bar.

The title attribute specifies the text string that appears as the axis's automated label. This label is oriented in the same way as the axis line itself, centered along the line, and offset from the line in accordance with the labelOffset property and the axis's position with respect to the graph's data window. Normally, the label is drawn as a single text line. However, if the text string contains any line break characters, then the label will be broken across two or more lines. In this case, the lineHt property (new in V4.5.2) specifies the baseline to baseline spacing from one text line to the next.