Plotter:
Filter:
Classes | GUI > Accessories

Plotter

Plot numerical data on a window or view
Location: NOT INSTALLED!

Description

Plot data of up to three dimensions on a Window or UserView.

Keyboard shortcuts

When the plotter window has focus, the following keyboard shortcuts can be used to change the display:

+ / -vertical zoom
=compare plot channels
ntoggle normalize display (0..1) / (-1..1), or fit range
stoggle superposition (see: superpose)
mswitch plot mode (see: Plotter: -plotMode)
etoggle editing (see: Plotter: -editMode)
gtoggle horizontal (domain) grid
Gtoggle vertical (codomain) grid
pprint curve
ctrl-+ / -zoom font
alt-clickpost value

Method extensions

Plotter extends other classes with methods. To see what classes implements plot, see Methods: plot

plot(args)

plotGraph(n,from,to,...)

Class Methods

.new

Arguments:

name

Plot window title.

bounds

The window bounds (a Rect).

parent

Either a Window / View may be passed in - then the plot is embedded. Otherwise a new Window is created.

Discussion:

Inherited class methods

Instance Methods

Embedding in another view

.makeWindow

Open given plotter in a new window or within a given composite view.

See the Embedding in another View or GUI example.

Arguments:

argParent

Either a Window or View may be passed in - then the plot is embedded. Otherwise a new Window is created.

argBounds

The window bounds (a Rect).

Plot properties

.plotMode

Get/Set the style of data display. This can be an array of different modes for multi-channel data. Available modes:

\linearconnecting data points with linear interpolation
\pointsdraw data points only
\plinescombination of lines and points
\levelshorizontal lines
\stepsconnecting data points with step interpolation
\barsbar graph with filled bars

Arguments:

modes

A Symbol or an Array of Symbols.

If modes.size < numChannels, the plots will wrap around the array of modes.

Returns:

An Array of Symbols, unless there is only one mode specified or if all modes of a multi-channel plot are the same, in which case a single Symbol is returned.

Discussion:

.plotColor

Set or get the colors of your data plot.

Arguments:

colors

This can be an Array of Colors for multichannel data, or a single Color to map to all channels.

If colors.size < numChannels, the plots will wrap around the array of colors.

Returns:

An Array of Colors, unless there is only one color specified or if all colors of a multi-channel plot are the same, in which case a Color is returned.

.superpose

If true, plotter displays channels overlaid on a single plot. (keyboard shortcut: s)

.axisLabelX

Get/set the label for the x-axes. Can be a String or an Array of Strings, or nil to remove the label. See Axis labels example below.

.axisLabelY

Get/set the label for the y-axes. Can be a String or an Array of Strings, or nil to remove the label. See Axis labels example below.

.showUnits

Get/set whether the corresponding ControlSpec: -units are displayed as labels. The state of -unitLocation determines whether the units are shown as axis labels or appended to the tick labels.

Arguments:

bool

A Boolean.

Discussion:

When enabling showUnits, axis or tick labels will only be updated to show the units when the axisLabelX/Y or grid labelAppendString properties are nil, empty, or were previously set to show the spec units — i.e. showUnits won't overwrite a label that has been explicitly set.

See Unit labels example below.

.unitLocation

Get/set the label type on which the Spec ControlSpec: -units are shown.

See the Discussion in -showUnits about the interraction with pre-existing labels at the location, and Unit labels example below.

Arguments:

location

A Symbol, \axis or \ticks, to show the units as the axis label or appended to each of the tick labels, respectively.

.setProperties

Set properties of all plot views. Defaults are taken from GUI.skins.at(\plot);

WARNING: It's preferrable to use Plotter's instance methods when possible to set Plot properties to ensure proper behavior when using -superpose.

Arguments:

... pairs

A list of symbol,value pairs. Supported properties:

  • font
  • fontColor
  • gridColorX
  • gridColorY
  • plotColor (an Array)
  • backgroundColor
  • gridLinePattern
  • gridLineSmoothing ( Boolean )
  • labelX
  • labelY
  • gridOnX ( Boolean )
  • gridOnY ( Boolean )

Discussion:

Example:

.plots

Returns:

An Array of Plots.

Grid properties

.setGridProperties

Set one or more properties of the DrawGridX or DrawGridY used by all Plots.

Arguments:

axis

A Symbol denoting the axis whose grid you're modifying: \x or \y.

... propertyPairs

Key value pairs, listed as successive arguments, of the properties to change and their new values. The property key is a Symbol.

Any of setters of DrawGridX or DrawGridY can be used. Here is a subset of useful properties:

\labelAnchorA Symbol denoting the point on the label's bounding Rect that anchors to the point where the grid line meets the base of the axis. \center, \top, \bottom, \left, \right, \topLeft, \topRight, \bottomLeft, \bottomRight, \leftTop, \rightTop, \leftBottom, \rightBottom.
\labelOffsetA Point describing the offset of the \labelAnchor from the point where the grid line meets the base of the axis. The positive direction for the x and y dimensions is right and down, respectively.
\labelAlignAlignment of the text within its bounding Rect: \left, \center, or \right.
\constrainLabelExtentsA Boolean specifying whether the tick labels at either end of the axis are constrained by, or can extend beyond, the grid bounds.
\drawBaseLineA Boolean whether a line is drawn at the minimum extent of this axis.
\drawBoundingLinesA Boolean whether a line is drawn at both ends of the extent of this axis.
\drawBoundingRectA Boolean whether a Rect is drawn around the bounds of the grid area.
\labelAppendStringA string to append to all of the axis's tick labels.
\tickSpacingSet the minimum spacing between grid lines ("ticks") for each axis. See DrawGrid: -tickSpacing for details.
\numTicksSet the approximate number of grid lines ("ticks") for each axis. See DrawGrid: -numTicks for details.
\fontA Font (including size) to be used for the tick labels.
\fontColorThe Color of the tick labels.
\gridColorThe Color of the axis grid lines.

The properties \drawBaseLine, \drawBoundingLines, or \drawBoundingRect are mutually exlusive — setting any of them to true will set the others two to false. In the context of Plotter, setting \drawBoundingRect on one axis to true has the same appearance of setting \drawBoundingLines on both axes to true.

Discussion:

This is a convenience method to set the grid properties for all Plots to the same values. An Example:

To set the properties of grids on each Plot separately, iterate over the plots:

.getGridProperty

Get the value of a grid property. See -setGridProperties for a list of available properties.

Arguments:

axis

A Symbol denoting the axis whose grid you're modifying: \x or \y.

property

The property name as a Symbol.

Discussion:

As a convenience method, getGridProperty assumes that properties across all Plots are the same (as would be the case if set by -setGridProperties) so returns a single value. Alternatively, properties from individual plot grids can be collected by iterating over the plots:

.drawGridBoundingRect

Set whether a Rect is drawn around the boundary of the grid. Setting to false disables any bounding grid lines (including "base" lines).

Arguments:

bool

A Boolean.

Discussion:

In some cases, the GridLines of the grid will not fall on the minimum or maximum of it's spec's range. Using -drawGridBaseLines or -drawGridBoundingRect will give the appearance of grid lines at the lower end ("base") of the grid, or at both ends of the grid, respectively.

.drawGridBaseLines

Set whether a line is drawn at the lower extent of the grid axes. Setting to false disables any bounding grid lines (including a bounding Rect). See also the Discussion in -drawGridBoundingRect.

Arguments:

bool

A Boolean.

Data display properties

.specs

Set or get the spec for the y-axis (codomain).

See also the Explicit domain and axis specs example below.

.domainSpecs

Set or get the spec for the x-axis (domain).

See also the Explicit domain and axis specs example below.

Discussion:

When setting your Plotter -value, the default domainSpecs is a linear spec in the range [0, value.size-1] (i.e. the indices of the values). Therefore, your values are displayed as evenly sampled between the minval and maxval, unless you have explicitly set the -domain values.

If a new -value is set, you will need to update your domainSpecs.

.domain

Set/get the x-axis positions of your data points. The size of the domainArray must equal the size of your -value array, i.e. a domain value specified for each data point.

See also the Explicit domain and axis specs example below.

Discussion:

Domain values are mapped into the range of the -domainSpecs, so need not be evenly distributed. If -domain is set to nil, your values are displayed as evenly sampled between the minval and maxval of the -domainSpecs.

Currently, for multichannel data plots, it's assumed that all channels of data share a single -domain. I.e. domainArray must be an Array of rank 1.

If a new -value is set, you will need to update your -domain.

.resolution

Set the minimum number of pixels between data points (default: 1)

Plot data

.value

Return or set the data values. Data may be numerical arrays of up to 3 dimensions.

.setValue

Set the data values, with additional arguments determining how the plot is updated.

Arguments:

arrays

Arrays of data to plot. Data may be numerical arrays of up to 3 dimensions.

findSpecs

A Boolean. If true (default), bounds of the plot(s) are determined automatically. If false, previous bounds will persist.

refresh

A Boolean. If true (default), refresh the view immediately.

separately

A Boolean. If true (default), min and max of each set of data will be calculated and displayed separately for each plot. If false, each plot's range on the y-axis will be the same.

minval

(Optional) The minimum value displayed on the y-axis.

maxval

(Optional) The maximum value displayed on the y-axis.

defaultRange

(Optional) A default range for the y-axis in the case that the max and min values of the data are identical.

.findSpecs

If true, specs are derived from new data (using min and max values) automatically. Default: true.

.data

Reference to the current internal data (with shape up to depth of 3).

Edit mode

.editMode

If the edit mode is set to true, the data may be edited via cursor.

.editFunc

Supply a function which is evaluated when editing data. The function is called with the arguments: plotter, plotIndex, index, val, x, y.

Discussion:

Example:

.cursorPos

Returns:

The last cursorPos (a Point).

Inherited instance methods

Examples

Object .plot methods

Explicit domain and axis specs

Axis labels

Unit labels

The units of the grid specs are shown as labels, either axis labels or appended to tick labels. Unit labels won't overwrite preexisting labels, and can be disabled altogether.

Embedding in another View or GUI

Changing global defaults

The default styles are kept (and may be overridden) in GUI.skins.at(\plot). See also GUI help.