User's Reference - Plot

### Plot

Category

Annotation

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

Outputs

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.)

##### Column Charts

To create a column chart with positions connection data, set the "column" attribute on the field or group to 1 (one).

Notes:

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

2. 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.

3. 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

    PlotColumn.net
    PlotLine.net
    PlotLine2.net
    PlotTwoLines.net

    PlotSpecifyTicks.net

See Also

Compute, Construct, Histogram, Options

[ OpenDX Home at IBM | OpenDX.org ]