Embedded Files
Introduced in Figure Composer 5.1.2, the pgraph element is a 2D graph container specialized to present data in a polar coordinate system. While the original 2D plot container node, graph, supports polar coordinates as an option, we decided to introduce a separate container element that is designed specifically for polar plots and offers features not available with the graph element.
Typical polar plots do not have visually distinct axes with tick marks -- like the X and Y axes of a graph in Cartesian coordinates. Rather, the angular (θ) and radial (R) axes are represented by a polar coordinate grid, with companion labels often marking the grid divisions:
The grid for the θ axis is a series of radial lines emanating from the origin, with text labels along the outer edge of the grid reflecting the corresponding angular values.
The R axis grid is a series of circular arcs concentric about the origin. The arc extents depend on the displayed range of the θ axis (typically, the θ span is 90, 180 or 360 degrees, but there's no reason not to allow for other angular spans). The radial arc grid labels reflect the radial value for each arc, and they may be located along an invisible radial line at a specified angle within the defined range of the θ axis.
The layout of the polar grid may vary in terms of the location of zero angle (the direction in which θ = 0 deg points), whether θ increases in a clockwise or counterclockwise direction, and whether the radial value increases from the origin outwards or from the outer circumference inward (rare usage).
The polar plot on the right illustrates some of these features (double-click on the image for a larger view). It is not possible to create such a plot using the graph element -- in fact, the figure was generated in FC 5.1.2 using the new pgraph element.
The graph node only offers all-quadrant and single-quadrant layouts, so it is not possible to specify a θ axis range of [30..300] degrees with θ=0 pointing directly downward, as it is in the sample plot.
The θ coordinate always increases in a counterclockwise direction in a graph-based polar plot. The clockwise direction is not supported.
While you can create grid labels as shown in the figure using graph, you must do so by manually adding a label node for each grid label, and -- unless you position the labels in native coordinates -- you will have to readjust their locations each time you resize the graph. In pgraph, the grid labels are automatically generated.
The pgraph element was developed to address these and other deficiencies. While the polar coordinate system is still available for the graph element, pgraph offers a far better and more versatile solution when you need to render a polar plot. When importing polar plots from Matlab figures, FC's FIG-to-FypML import engine will convert the Matlab polar plot to a pgraph element. In fact, pgraph was modeled after the Handle Graphics "polaraxes" object, introduced in Matlab R2016 and generated by the new polar plotting functions polarplot(), polarscatter(), and polarhistogram().
Note that one of the available 2D data presentation elements is NOT supported in a polar plot: contour. (Support for polar bar plots was introduced in FC 5.4.1). Also, unlike graph, pgraph does not allow nesting of regular 2D graphs or polar plots.
Like the graph element, pgraph is a composite graphic object with a number of component parts:
The θ and R axes define the range and layout of the polar grid and its accompanying labels, as well as the general appearance of the grid lines and labels (color, stroke width, font, and so on).
A "color bar" defines the polar plot's color map; it is identical to the color bar for a standard 2D graph node. Color is used to render 3D data in 2D in the form of a polar bubble plot.
An auto-generated legend.
These component parts are defined by mandatory FypML child nodes under the pgraph element: two paxis elements represent the θ and R axes, while colorbar and legend define the color bar and legend. Unlike the axes of a Cartesian graph, the axes of a polar plot do not contain optional tick mark sets; instead, the grid divisions are defined by one of the properties of paxis element itself (the colorbar does allow a tick mark set, defined by the ticks element, as a child node). For more information about these different graphic elements, see the chapter on FypML.
By design, the "component nodes" are not exposed in the Figure Navigator's node tree. All of the properties of the polar plot itself, its axes, and legend may be viewed and modified within the Polar Plot Properties editor. As you can see in the adjacent screenshot, separate tabs on the editor panel are dedicated to the θ and R axes, the color bar/axis, and the automated legend.
The Main tab exposes properties that set the location and size of the polar plot, along with 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 polar plot. Like a graph node or the figure itself, you can rescale a polar plot in one operation using the Scale (%) field to enter a scale factor, then pressing the Fonts button to resize only the fonts, or All to resize the entire plot.
The polar grid is always sized to "just fit" within the bounding box specified by [X Y W H]. When the grid is a full-circle (θ axis range of 360 deg), the origin of the polar coordinate system will lie at the center of the box, and the grid diameter will be the smaller of W,H. When the grid is not a complete circle, the layout computation is more complex, but it always tries to make the grid as large as possible while still fitting within the bounding box (the θ grid labels, of course, will typically appear outside this box).
If the Clip data? box is checked, any data rendered in the polar plot is clipped to the grid shape, which will be a full circle or a pie shape. If you would like the grid and grid labels to be rendered on top of the data, check the Grid on top? box. Finally, if you would like to change the color of the grid's background, click on the Grid Bkg widget; solid or translucent colors are supported.
The styled text editor at the top of the Main tab edits the polar plot's title. The title may contain up to 3 text lines (any additional lines will be clipped). To render the title in the figure, check the Title box. The title appears just above the graph's data window. The horizontal alignment button indicates whether the title block is aligned along the left or right edge of the data window, or centered on it. The Gap widget specifies the size of the vertical separation between the title block and the top edge of the window. If this semi-automated title does not serve your purposes, you can always hide it and add a label or textbox element to the polar graph (or the parent figure).
The ID field specifies an optional graphic object ID. If not an empty string, it serves to uniquely identify the polar plot among all the graphic objects that comprise a figure. It is intended for use outside of Figure Composer -- providing a way to programmatically locate a particular graphic object within an existing FypML figure, so that you can modify that object in some way. For more information, see the description of the Matlab utility put2fyp() utility. If you have no need for the object ID, simply leave it blank.
The screenshot above includes an image of the θ axis tab of the Polar Plot Properties editor; the R axis tab is identical. Here you specify the axis range, grid divisions, custom grid labels (if any), and some other properties. It also includes the usual text and draw style properties, which govern the rendered appearance of the axis grid lines and associated labels.
The two numeric text fields near the top of the tab panel specify the polar axis range [T0..T1]. Unlike the X- and Y-axis of the graph element, the start T0 must always be less than the end T1 of the range. Furthermore, the θ axis range is always in degrees, and the range endpoints will be auto-corrected to ensure that both lie in [-360..360] and that (T1-T0) <= 360 degrees. If you wish to reverse the direction of either axis, check the Reversed? box. The reverse direction for θ is clockwise; for R, the reverse direction places T1 at the origin and T0 along the outer circumference of the polar grid.
The θ and R axes of pgraph do not admit any tick sets and do not have an "axis label" per se. Use the Divs text field to specify the grid divisions for the axis as a whitespace-separated list of floating-point tokens. The first token may take the form "S/E/M", defining regularly spaced grid divisions of size M starting at S and not exceeding E, where M>0 and S<=E are all numeric values. If S>=E, they are ignored and the axis range [T0,T1] is used instead -- so that the regular grid adjusts automatically with a change in axis range. If the "S/E/M" token is omitted, or if M<=0, then there will be no regular grid divisions. All remaining tokens in the list represent custom grid divisions. Up to a maximum of 20 grid divisions are supported. Finally, if the Divs field is completely blank, the axis will have no grid divisions whatsoever and thus no grid lines/arcs or grid labels will be rendered. Alternatively, you can simply hide the axis by checking the Hide? box.
If you need to define custom grid labels (see the polar plot example at the top of the page), enter the desired text labels as a comma-separated list in the Labels field. Note that the labels will be assigned to each grid division in ascending numeric order. The Gap property defines the offset separating the grid label from the endpoint of the corresponding grid line or arc; note that this is the distance separating the grid line/arc endpoint from the vertical and horizontal center of the grid label. Experiment with different values to determine what "looks best". The combo box adjacent to the Gap widget selects the numeric format for the auto-generated grid labels (integer, floating-point with 1, 2 or 3 digits after the decimal point, or "none").
Finally, the Reference Angle property has a different meaning for the two polar axes. For the θ axis, it specifies the direction in which θ=0 points, measured counterclockwise from a ray emanating from the origin and pointing to the right. For example, in the polar plot depicted at the top of this page, the Reference Angle for the θ axis is set to 270 or -90 degrees, so that θ=0 points straight down. For the R axis, this specifies the angle of the ray along which the radial grid labels are drawn, but in this case it is specified in degrees with respect to the angular coordinate system established by the θ axis. If the polar grid is not a full circle and this value is such that the ray lies outside the range for θ, then the labels are rendered along a line parallel to a ray at one end of the theta range, but offset from it in accordance with the Gap parameter. As an example, see the radial grid labels in the polar plot at the top of this page; the R axis reference angle was set to 30 deg.
The last two tab panels in the Polar Plot Properties editor define the plot's color bar and legend. These are identical to the corresponding panel in the Graph Properties editor; see that section of the guide for a full description.
Page updated
Report abuse