IBM Visualization Data Explorer User's Reference

Plot

Category

Function

Creates a 2-dimensional plot.

Syntax


plot = Plot(input, labels, ticks, corners, adjust, frame, type, grid,
            aspect, colors, annotation, labelscale, font, input2,
            label2, ticks2, corners2, type2,

            xticklocations, y1ticklocations, y2ticklocations,
            xticklabels, y1ticklabels, y2ticklabels);

Inputs

Name Type Default Description
input field or group none data to be plotted
labels string list {"x," "y"} axis label
ticks integer list 10 approximate number of tick marks
corners vector list or object {[xmin, ymin],
[xmax, ymax]} plot limits
adjust flag input dependent 0: end points not adjusted
1: end points adjusted to match tick marks
frame integer 0 framing style for plot
type string list "lin" plot type
grid integer 0 grid style
aspect scalar or string 1.0 y:x (aspect) ratio of resulting plot
colors vector list or string list appropriate colors for annotation
annotation string list "all" annotation objects to be colored
labelscale scalar 1.0 scale factor for labels
font string standard font for labels
input2 field or group no default second set of data to be plotted
label2 string {"y2"} label for second y-axis
ticks2 integer input dependent approximate number of tick marks for second y-axis.
corners2 vector or object {[ymin, ymax]} plot limits for second y-axis
type2 string "lin" plot type for second y-axis
xticklocations scalar list appropriate x tick locations
y1ticklocations scalar list appropriate y1 tick locations
y2ticklocations scalar list appropriate y2 tick locations
xticklabels string list xticklocations x tick labels
y1ticklabels string list y1ticklocations y1 tick labels
y2ticklabels string list y2ticklocations y2 tick labels

Name	Type	Default	Description
`input`	field or group	none	data to be plotted
`labels`	string list	{"x," "y"}	axis label
`ticks`	integer list	10	approximate number of tick marks
`corners`	vector list or object	{[xmin, ymin], [xmax, ymax]}	plot limits
`adjust`	flag	input dependent	0: end points not adjusted 1: end points adjusted to match tick marks
`frame`	integer	0	framing style for plot
`type`	string list	"lin"	plot type
`grid`	integer	0	grid style
`aspect`	scalar or string	1.0	y:x (aspect) ratio of resulting plot
`colors`	vector list or string list	appropriate	colors for annotation
`annotation`	string list	"all"	annotation objects to be colored
`labelscale`	scalar	1.0	scale factor for labels
`font`	string	standard	font for labels
`input2`	field or group	no default	second set of data to be plotted
`label2`	string	{"y2"}	label for second y-axis
`ticks2`	integer	input dependent	approximate number of tick marks for second y-axis.
`corners2`	vector or object	{[ymin, ymax]}	plot limits for second y-axis
`type2`	string	"lin"	plot type for second y-axis
`xticklocations`	scalar list	appropriate	x tick locations
`y1ticklocations`	scalar list	appropriate	y1 tick locations
`y2ticklocations`	scalar list	appropriate	y2 tick locations
`xticklabels`	string list	xticklocations	x tick labels
`y1ticklabels`	string list	y1ticklocations	y1 tick labels
`y2ticklabels`	string list	y2ticklocations	y2 tick labels

Outputs

Name Type Description
plot field the plot

Name	Type	Description
`plot`	field	the plot

Functional Details

This module creates a 2-dimensional plot from a line or set of lines. The following plot characteristics can be set on the line or lines with the Options module (in the Structuring category) before they are passed to Plot: line label, line marker type, marker size, number of markers, and the choice of creating a scatter plot or not (see "Creating a Legend", "Using Line Markers", and "Scatter Plots").

input
is a field or group of fields, where each field has 1-dimensional positions representing the "x"-values, and 1-dimensional data representing the "y"-values. If the input is a group of Fields, each Field is plotted as a separate line.
There can be a "connections" component of element type "lines" connecting the positions; if a connections component for a given Field does not exist, the module adds one. The input can have a "colors" component, in which case the output plot preserves those colors. If the input does not have a "colors" component, the line is colored white.
labels
specifies the labels for the axes of the plot.
ticks
specifies the number of tick marks to be placed on the plot axes. The default is 10.
If the parameter value is a single integer, then approximately that many tick marks are placed along the axes. If the parameter list is a two-element integer list, the first element is interpreted as the approximate number of tick marks to be placed on the x-axis; the second element, the approximate number to be placed on the y-axis.
corners
specifies the limits of the plot axes. (The default limits are set by the input line or lines.) The specification can be a vector list or an object. If the specification is a vector list, then all points that lie outside of corners are eliminated from the plot. If the specification is an object (such as a group of lines), the module determines the minimum and maximum x- and y-values for the entire object and uses those to set the plot limits.
adjust
determines whether the axes end at tick marks or not.
frame
determines how the plot is framed. In all cases, axes and tick labels are drawn on the left side and bottom of the plot. For frame = 1, additional lines (without ticks) are drawn on the right side and top of the plot. For frame = 2, lines and major and minor ticks are drawn on the right side and top of the plot.
type
specifies the plot type. It is a string or string list and must be:

"lin" (linear plot)
"log" (logarithmic plot)
any two-element combination of these (e.g., {"lin," "lin"} or {"log," "lin"}). If type is a single string, both the x- and the y-axis are of that type. If type is two strings, then the first string applies to the x-axis while the second string applies to the y-axis.

grid
specifies whether and how to draw grid lines along major ticks. If grid = 0, no grid lines are drawn. If grid = 1, then grid lines are drawn horizontally along major ticks. If grid = 2, then grid lines are drawn vertically along major ticks. If grid = 3, grid lines are drawn both horizontally and vertically along major ticks. If grid is not equal to 0, adjust is set to 1.
aspect
allows you to set the approximate y:x aspect ratio of the resulting plot. You can also use the Scale module before Plot to adjust the aspect ratio. The default is an aspect ratio of 1.0. If you want Plot to simply use the actual aspect ratio of the data, set aspect to "inherent". Note that if a second plot is drawn (i.e. input2 is provided), aspect is set to 1.0 even if "inherent" is specified.
colors
together with annotation (see below), can be used to set the color of one or more components of the plot.
colors: specifies a single color (an RGB vector or color-name string) or a list of colors. Color-name strings must be from the list of defined color strings (see Color).
If colors is a single string and annotation is not specified or is "all," then that color is used for all axes annotation. Otherwise, the number of colors in colors must match the number of annotation strings exactly and in one-to-one correspondence. By default, a background is not drawn.
annotation
can be one of the following: "all," "axes," "background," "grid," "labels," or "ticks."
labelscale
allows you to change the size of the axes and tick labels. For example, to make the labels twice as large, specify labelscale = 2.
font
specifies the font used for labels. The default is "standard," which uses a fixed font for the tick-mark labels and a variable font for the axes labels. You may specify font as any of the defined fonts supplied with Data Explorer:
area gothicit_t pitman roman_ext cyril_d greek_d roman_d script_d fixed greek_s roman_dser script_s gothiceng_t italic_d roman_s variable gothicger_t italic_t roman_tser
For more information, see Appendix E. "Data Explorer Fonts" in IBM Visualization Data Explorer User's Guide.

The Plot module can also generate a second set of lines and a second y-axis on the right side of the plot. If a second plot is drawn, the aspect ratio defaults to 1. For this second plot and axis, you must repeat several specifications:

input2
is a second field or group of fields (see input above).
label2
is the label for the second y-axis.
ticks2
is the approximate number of ticks for the second y-axis. A negative integer specifies outward, as opposed to inward, pointing ticks.
corners2 (see corners)
specifies the min and max for the second "y"-axis.
type2
specifies the type of second y-axis and must be either "log" or "lin."
xticklocations
explicit set of tick locations for the x axis. If specified, overrides the values for tick locations as determined from ticks.
y1ticklocations
explicit set of tick locations for the first y axis. If specified, overrides the values for tick locations as determined from ticks.
y2ticklocations
explicit set of tick locations for the second y axis. If specified, overrides the values for tick locations as determined from ticks.
xticklabels
list of labels to be associated with the specified xticklocations. If xticklabels is specified and xticklocations is not specified, then xticklocations to the integers 0 to n-1, where n is the number of items in xticklabels.
y1ticklabels
list of labels to be associated with the specified y1ticklocations. If y1ticklabels is specified and y1ticklocations is not specified, then y1ticklocations to the integers 0 to n-1, where n is the number of items in y1ticklabels.
y2ticklabels
list of labels to be associated with the specified y2ticklocations. If y2ticklabels is specified and y2ticklocations is not specified, then y2ticklocations to the integers 0 to n-1, where n is the number of items in y2ticklabels.

Creating a Legend

To create a legend for the plot, use Options to set a "label" attribute on the incoming lines. Plot will then create an appropriate plot legend and place it in the upper right corner (see the first example below). The legend contains a short line segment with a color matching that of the line it corresponds to, along with the label for the line. The "label" attribute can also be set in the Data Explorer file format (see Appendix B. "Importing Data: File Formats" in IBM Visualization Data Explorer User's Guide).

Using Line Markers

You may also choose markers for your plot lines. You may set a "mark" attribute on the input lines using the Options module. "mark" should have as a value one of the following: "circle," "diamond," "dot," "square," "star," "triangle," or "x." By default, a mark is placed at every point on the line. You can also set a "mark every" attribute with an integer as a value. For example, the value 3 would cause every third point to be marked. You can control the size of the mark using the "mark scale" attribute, which applies a scale factor to the default mark size. For example, a "mark scale" value of 2 would make the marks twice as large. If you are using the "label" attribute, the mark will also appear in the legend.

Note: The "dot" mark type will only be visible if you also set the "scatter" attribute to 1 (see "Scatter Plots").

Different colored lines

If you want your lines to have different colors, simply pass them through the Color module before passing them to Plot.

Scatter Plots

To create a scatter plot (with no line drawn between markers), set the "scatter" attribute on the line to 1 (one). (The default is a line between markers.)

Notes:

If corners is more restrictive than the ticklocations, then the given locations outside the corners are not shown.

If corners is less restrictive than the given ticklocations, or if corners is not specified, then all given tick locations are shown, whether or not there is data there.

If ticklocations is specified, then the data range determines the extent of the axes, unless corners is specified, in which case the given corners are used.

Bar Charts

If the input to Plot has a "data" component that is dependent on "connections" rather than "positions," a bar chart is created.

Components

Creates "positions," "connections," and "colors" components.

Example Visual Programs

PlotLine.net
PlotLine2.net
PlotTwoLines.net

PlotSpecifyTicks.net

See Also

Compute, Construct, Histogram, Options

[Data Explorer Home Page | Contact Data Explorer | Same document on Data Explorer Home Page ]

[IBM Home Page | Order | Search | Contact IBM | Legal ]

`input`	is a field or group of fields, where each field has 1-dimensional positions representing the "x"-values, and 1-dimensional data representing the "y"-values. If the input is a group of Fields, each Field is plotted as a separate line. There can be a "connections" component of element type "lines" connecting the positions; if a connections component for a given Field does not exist, the module adds one. The input can have a "colors" component, in which case the output plot preserves those colors. If the input does not have a "colors" component, the line is colored white.
`labels`	specifies the labels for the axes of the plot.
`ticks`	specifies the number of tick marks to be placed on the plot axes. The default is 10. If the parameter value is a single integer, then approximately that many tick marks are placed along the axes. If the parameter list is a two-element integer list, the first element is interpreted as the approximate number of tick marks to be placed on the x-axis; the second element, the approximate number to be placed on the y-axis.
`corners`	specifies the limits of the plot axes. (The default limits are set by the input line or lines.) The specification can be a vector list or an object. If the specification is a vector list, then all points that lie outside of `corners` are eliminated from the plot. If the specification is an object (such as a group of lines), the module determines the minimum and maximum x- and y-values for the entire object and uses those to set the plot limits.
`adjust`	determines whether the axes end at tick marks or not.
`frame`	determines how the plot is framed. In all cases, axes and tick labels are drawn on the left side and bottom of the plot. For `frame` = 1, additional lines (without ticks) are drawn on the right side and top of the plot. For `frame` = 2, lines and major and minor ticks are drawn on the right side and top of the plot.
`type`	specifies the plot type. It is a string or string list and must be: "lin" (linear plot) "log" (logarithmic plot) any two-element combination of these (e.g., {"lin," "lin"} or {"log," "lin"}). If `type` is a single string, both the x- and the y-axis are of that type. If type is two strings, then the first string applies to the x-axis while the second string applies to the y-axis.
`grid`	specifies whether and how to draw grid lines along major ticks. If `grid` = 0, no grid lines are drawn. If `grid` = 1, then grid lines are drawn horizontally along major ticks. If `grid` = 2, then grid lines are drawn vertically along major ticks. If `grid` = 3, grid lines are drawn both horizontally and vertically along major ticks. If `grid` is not equal to 0, `adjust` is set to 1.
`aspect`	allows you to set the approximate y:x aspect ratio of the resulting plot. You can also use the Scale module before Plot to adjust the aspect ratio. The default is an aspect ratio of 1.0. If you want Plot to simply use the actual aspect ratio of the data, set `aspect` to "inherent". Note that if a second plot is drawn (i.e. `input2` is provided), `aspect` is set to 1.0 even if "inherent" is specified.
`colors`	together with `annotation` (see below), can be used to set the color of one or more components of the plot. `colors`: specifies a single color (an RGB vector or color-name string) or a list of colors. Color-name strings must be from the list of defined color strings (see Color). If `colors` is a single string and `annotation` is not specified or is "all," then that color is used for all axes annotation. Otherwise, the number of colors in `colors` must match the number of `annotation` strings exactly and in one-to-one correspondence. By default, a background is not drawn.
`annotation`	can be one of the following: "all," "axes," "background," "grid," "labels," or "ticks."
`labelscale`	allows you to change the size of the axes and tick labels. For example, to make the labels twice as large, specify `labelscale` = 2.
`font`	specifies the font used for labels. The default is "standard," which uses a fixed font for the tick-mark labels and a variable font for the axes labels. You may specify `font` as any of the defined fonts supplied with Data Explorer: area gothicit_t pitman roman_ext cyril_d greek_d roman_d script_d fixed greek_s roman_dser script_s gothiceng_t italic_d roman_s variable gothicger_t italic_t roman_tser For more information, see Appendix E. "Data Explorer Fonts" in IBM Visualization Data Explorer User's Guide.

`input2`	is a second field or group of fields (see `input` above).
`label2`	is the label for the second y-axis.
`ticks2`	is the approximate number of ticks for the second y-axis. A negative integer specifies outward, as opposed to inward, pointing ticks.
`corners2` (see `corners`)	specifies the `min` and `max` for the second "y"-axis.
`type2`	specifies the type of second y-axis and must be either "log" or "lin."
`xticklocations`	explicit set of tick locations for the x axis. If specified, overrides the values for tick locations as determined from `ticks`.
`y1ticklocations`	explicit set of tick locations for the first y axis. If specified, overrides the values for tick locations as determined from `ticks`.
`y2ticklocations`	explicit set of tick locations for the second y axis. If specified, overrides the values for tick locations as determined from `ticks`.
`xticklabels`	list of labels to be associated with the specified `xticklocations`. If `xticklabels` is specified and `xticklocations` is not specified, then `xticklocations` to the integers 0 to n-1, where n is the number of items in `xticklabels`.
`y1ticklabels`	list of labels to be associated with the specified `y1ticklocations`. If `y1ticklabels` is specified and `y1ticklocations` is not specified, then `y1ticklocations` to the integers 0 to n-1, where n is the number of items in `y1ticklabels`.
`y2ticklabels`	list of labels to be associated with the specified `y2ticklocations`. If `y2ticklabels` is specified and `y2ticklocations` is not specified, then `y2ticklocations` to the integers 0 to n-1, where n is the number of items in `y2ticklabels`.