For the latest version of JMP Help, visit JMP.com/help.


JSL Syntax Reference > JSL Functions > Graphics Functions
Publication date: 04/30/2021

Graphics Functions

Add Color Theme({"name", <flags>, {color}, <{position}>)

Description

Creates a custom color theme that you can apply to components such as markers, data table rows, and treemaps. Add the color theme to the JMP Preferences by including Add Color Theme(...) inside Preferences().

Returns

Null.

Arguments

name

The name of the color theme.

flags

An optional flag for the Continuous or Categorical color theme list and category of color.

Continuous, <Continuous>, Sequential

Continuous, <Continuous>, Diverging

Continuous, <Continuous>, Chromatic

Categorical, <Continuous>, Sequential

Categorical, <Continuous>, Diverging

Categorical, Qualitative

Categorical, <Continuous>, Chromatic

With the default JMP color themes, Sequential colors transition from left to right or right to left. Diverging colors are lighter in the middle. Chromatic colors consist of blocks or gradients of bright color. All categories except for Qualitative can be both continuous and categorical.

If you omit the flag, the color is shown in the Continuous, Sequential and Categorical, Sequential categories.

color

Lists of RGB values. These values define the blocks in categorical color themes and the gradients in continuous color themes. Each list of RGB values corresponds to a slider in the preferences Color Themes window.

position

An optional list of numbers between 0 and 1 with one position per color. Each position corresponds to a slider in the preferences Color Themes window. If you omit the position, the sliders are evenly spaced.

Examples

The following example creates a continuous color theme named Blue to Purple. The color is in the Diverging category. RGB values are defined in the four lists.

Add Color Theme(
	{"Blue to Purple", {"Continuous", "Diverging"}, {{0, 0, 255},
	{57, 108, 244}, "white", {128, 0, 100}}} );

Notes

Any style except for Qualitative can be Continuous and Categorical at the same time. For example, the Cool to Warm Diverging theme is in the Continuous and Categorical theme lists. In JMP, select Preferences > Graphs to see examples.

To delete a color theme, use Remove Color Theme(). See Remove Color Theme("Name"|{"Name", <flags>, {color, ...}, <{position, ...}>}>).

Arc(x1, y1, x2, y2, startangle, endangle)

Description

Inscribes an arc in the rectangle described by the arguments.

Returns

Null.

Arguments

x1, y1

The point at the top left of the rectangle

x2, y2

The point at the bottom right of the rectangle

startangle, endangle

The starting and ending angle in degrees, where 0 degrees is 12 o'clock and the arc or slice is drawn clockwise from startangle to endangle.

Arrow(<pixellength>, {x1, y1}, {x2, y2})

Description

Draws an arrow from the first point to the second point. The optional first argument specifies the length of the arrow’s head lines (in pixels).

Returns

Null.

Arguments

pixellength

(Optional) Specifies the length of the arrowhead in pixels.

{x1, y1}, {x2, y2}

Two lists of two numbers that each specify a point in the graph.

Notes

The two points can also be enclosed in square brackets: Arrow(<pixellength>, [x1, x2], [y1, y2]).

Back Color("name")

Description

Sets the color used for filling the graph’s background.

Returns

Null.

Argument

name

A quoted color name or a color index (such as "red" or "3" for the color red).

Char To Path("path")

Description

Converts a path specification from a string to a matrix.

Returns

A matrix.

Arguments

path

A string that contains the path specification.

Circle({x, y}, radius|PixelRadius(n), <...>, <"fill">)

Description

Draws a circle centered at {x, y} with the specified radius.

Returns

Null.

Arguments

{x, y}

A number that describes a point in the graph

radius

A number that describes the length of the circle’s radius in relation to the vertical axis. If the vertical axis is resized, the circle is also resized.

PixelRadius(n)

A number that describes the length of the circle’s radius in pixels. If the vertical axis is resized, the circle is not resized.

"fill"

Optional string. Indicates that all circles defined in the function are filled with the current fill color. If "fill" is omitted, the circle is empty.

Note

The center point and the radius can be placed in any order. You can also add additional center point and radius arguments and draw more than one circle in one statement. One point and several radii results in a bull’s-eye. Adding another point still draws all previous circles, and then adds an additional circle with the last radius specified. This means that this code:

graphbox(circle({20, 30}, 5, {50, 50}, 15))

results in three circles, not two. First, a circle with radius 5 is drawn at 20, 30. Second, a circle with radius 5 is drawn at 50, 50. Third, a circle with radius 15 is drawn at 50, 50.

Color To HLS(color)

Description

Converts the color argument (including any JMP color) to a list of HLS values.

Returns

A list of the hue, lightness, and saturation components of color. The values range between 0 and 1.

Argument

color

a number from the JMP color index.

Example

The output from ColorToHLS() can either be assigned to a single list variable or to a list of three scalar variables:

hls = Color To HLS( 8 );
{h, l, s} = Color To HLS( 8 );
Show( hls, h, l, s );

hls = {0.778005464480874, 0.509803921568627, 0.976};

h = 0.778005464480874;

l = 0.509803921568627;

s = 0.976;

Color To RGB(color)

Description

Converts the color argument (including any JMP color) to a list of RGB values.

Returns

A list of the red, green, and blue components of color. The values range between 0 and 1.

Argument

color

a number from the JMP color index.

Example

The output from ColorToRGB() can either be assigned to a single list variable or to a list of three scalar variables:

rgb = Color To RGB( 8 );
{r, g, b} = Color To RGB( 8 );
Show( rgb, r, g, b );

rgb = {0.670588235294118, 0.0313725490196078, 0.988235294117647};

r = 0.670588235294118;

g = 0.0313725490196078;

b = 0.988235294117647;

Contour(xVector, yVector, zGridMatrix, zContour, <zColors>)

Description

Draws contours given a grid of values.

Returns

None.

Arguments

xVector

The n values that describe zGridMatrix.

yVector

The m values that describe zGridMatrix.

zGridMatrix

An nxm matrix of values on some surface.

zContour

(Optional) Definition of values for the contour lines.

zColors

(Optional) Definition of colors to use for the contour lines.

Contour Function(expr, xName, yName, z, < <<XGrid(min, max, incr)>, < <<YGrid(min, max, incr)>, < <<zColor(color)>, < <<zLabeled>, < <<Filled>, < <<FillBetween>, < <<Ternary>, < <<Transparency(alpha|vector))

Description

Draws sets of contour lines of the expression, a function of the two symbols. The z argument can be a single value or an index or matrix of values.

Returns

None.

Arguments

expr

Any expression. For example, Sine(y)+Cosine(x).

xName, yName

Values to use in the expression.

z

A z-value or a matrix of z-values.

Optional Arguments

<<XGrid, <<YGrid

Defines a box, beyond which the contour lines are not drawn.

<<zColor

Defines the color in which to draw the contour lines. The argument can be either a scalar or a matrix, but must evaluate to numeric.

<<zLabeled

Labels the contours.

<<Filled

Fills the contour levels using the current fill color.

<<FillBetween

Fills only between adjacent contours using the current fill color. For nz contours specified, this option fills nz-1 regions for the intervals between the nz values. Using this option is recommended over using the <<Filled option.

<<Ternary

Clips lines to be within the ternary coordinate system inside ternary plots.

<<Transparency

sets the transparency level of the fill. A vector of numbers between 0 and 1 are sequenced through and cycled for the z contours. This option should be used only in conjunction with the <<FillBetween option.

Drag Line(xMatrix, yMatrix, <dragScript>, <mouseupScript>)

Description

Draws line segments between draggable vertices at the coordinates given by the matrix arguments.

Returns

None.

Arguments

xMatrix

A matrix of x-coordinates.

yMatrix

A matrix of y-coordinates.

dragScript

Any valid JSL script; it is run at drag.

mouseupScript

Any valid JSL script; it is run at mouseup.

Drag Marker(xMatrix, yMatrix, <dragScript>, <mouseupScript>)

Description

Draws draggable markers at the coordinates given by the matrix arguments.

Returns

None.

Arguments

xMatrix

A matrix of x-coordinates.

yMatrix

A matrix of y-coordinates.

dragScript

Any valid JSL script; it is run at drag.

mouseupScript

Any valid JSL script; it is run at mouseup.

Drag Polygon(xMatrix, yMatrix, <dragScript>, <mouseupScript>)

Description

Draws a filled polygon with draggable vertices at the coordinates given by the matrix arguments.

Returns

None.

Arguments

xMatrix

A matrix of x-coordinates.

yMatrix

A matrix of y-coordinates.

dragScript

Any valid JSL script; it is run at drag.

mouseupScript

Any valid JSL script; it is run at mouseup.

Drag Rect(xMatrix, yMatrix, <dragScript>, <mouseupScript>)

Description

Draws a filled rectangle with draggable vertices at the first two coordinates given by the matrix arguments.

Returns

None.

Arguments

xMatrix

A matrix of 2 x-coordinates.

yMatrix

A matrix of 2 y-coordinates.

dragScript

Any valid JSL script; it is run at drag.

mouseupScript

Any valid JSL script; it is run at mouseup.

Note

xMatrix and yMatrix should each contain exactly two values. The resulting coordinate pairs should follow the rules for drawing a rect(); the first point (given by the first value in xMatrix and the first value in yMatrix) must describe the top, left point in the rectangle, and the second point (given by the second value in xMatrix and the second value in yMatrix) must describe the bottom, right point in the rectangle.

Drag Text(xMatrix, yMatrix, "text", <dragScript>, <mouseupScript>)

Description

Draws the text (or all the items if a list is specified) at the coordinates given by the matrix arguments.

Returns

None.

Arguments

xMatrix

A matrix of x-coordinates.

yMatrix

A matrix of y-coordinates.

text

A quoted string to be drawn in the graph.

dragScript

Any valid JSL script; it is run at drag.

mouseupScript

Any valid JSL script; it is run at mouseup.

Fill Color(n)

Description

Sets the color used for filling solid areas.

Returns

None.

Argument

n

Index for a color or a quoted color name.

Fill Pattern()

Description

Sets the pattern for filled areas. See Add Fill Patterns in the Scripting Guide for examples.

Get Color Theme Details(name)

Description

Returns a script for the specified color theme.

Example

The following example returns the script for the JMP default color theme:

Get Color Theme Details( "JMP Default" );

{"JMP Default", 9221, {{213, 72, 87}, {57, 177, 67}, {64, 111, 223}...}}

Get Color Theme Names(<kind>)

Description

Returns a list of all color theme names or color themes of the specified kind. The kinds include “continuous”, “categorical”, “sequential”, “diverging”, “qualitative”, or “chromatic”.

Example

The following example returns all color themes:

Get Color Theme Names();

{"Green to Black to Red", "Green to White to Red", "White to Black"...}

The following example returns the diverging color themes:

Get Color Theme Names( "diverging" );

{"Green to Black to Red", "Green to White to Red", "Blue to Gray to Red"...}

Gradient Function(zexpr, xname, yname, [zlow, zhigh], zcolor([colorlow, colorhigh]), < <<XGrid(min, max, incr)>, < <<YGrid(min, max, incr)> < <<Transparency(alpha|vector))

Description

Fills a set of rectangles on a grid according to a color determined by the expression value as it crosses a range corresponding to a range of colors.

Example

Gradient Function(Log(a * a + b * b),
a, b, [2 10],
Z Color([4, 6]));

Zexpr is a function in terms of the two following variables (a and b), whose values range from zlow to zhigh (2 to 10). Zcolor defines the two colors that are blended together (4 is green, 6 is orange).

H Line(<x1, x2>, y)

Description

Draws a horizontal line at y across the graph. If you specify start and end points on the x-axis (x1 and x2), the line is drawn horizontally at y from x1 to x2. You can also draw multiple lines by using a matrix of values in the y argument.

H Size()

Description

Returns the horizontal size of the graphics frame in pixels.

Handle(a, b, dragScript, mouseupScript)

Description

Places draggable marker at coordinates given by a, b. The first script is executed at drag and the second at mouseup.

Heat Color(n, <"color theme">)

Description

Returns the JMP color that corresponds to n in the color "theme".

Returns

An integer that is a JMP color.

Arguments

n

A value between 0 and 1.

theme

Any quoted color theme that is supported by Cell Plot. The default value is "Blue to Gray to Red".

HLS Color(h, l, s)

HLS Color({h, l, s})

Description

Converts hue, lightness, and saturation values into a JMP color number.

Returns

An integer that is a JMP color number.

Arguments

Hue, lightness, and saturation, or a list containing the three HLS values. All values should be between 0 and 1.

In Path(x, y, path)

Description

Determines it the point described by x and y falls in path.

Returns

True (1) if the point (x, y) is in the given path, False(0) otherwise.

Arguments

x and y

The coordinates of a point.

path

Either a matrix or a string describing a path.

In Polygon(x, y, xx, yy)

In Polygon(x, y, xyPolygon)

Description

Returns 1 or 0, indicating whether the point (x, y) is inside the polygon that is defined by the xx and yy vector arguments.

The vector arguments (xx, yy) can also be combined into a 2-column matrix (xyPolygon), allowing you to use three arguments instead of four. Also, x and y can be conformable vectors, and then a vector of 0s and 1s are returned based on whether each (x, y) pair is inside the polygon.

Level Color(i, <n>, <"Color Theme">)

Description

Assigns a JMP color to categorical data in a graphic.

Returns

An integer that is a JMP color.

Arguments

i

An integer that is greater than or equal to 1 and less than or equal to the number of categories specified by n.

n

The number of categories.

"Color Theme"

A color theme from the Value Color list of the Column Properties window. If not specified, the JMP Default color theme is applied.

Note

When the second argument is a character string and not n, then the second argument determines the color theme.

Line({x1, y1}, {x2, y2}, ...), <<ValueSpace(0|1)

Line([x1, x2, ...], [y1, y2, ...]), <<ValueSpace(0|1)

Description

Draws a line between points.

Arguments

{x1, y1}, {x2, y2} or [x1, x2, ...], [y1, y2, ...]

Can be any number of lists of two points, separated by commas; or a matrix of x values and a matrix of y values.

<<ValueSpace (Boolean)

Draws lines that follow the projection when the line represents a movement of the underlying data, such as a bubble trail in a bubble plot. The Boolean value can be a constant or an expression.

Line Style(n)

Description

Sets the line style used to draw the graph.

Argument

n

Can be either a style name or the style’s number:

0 or Solid

1 or Dotted

2 or Dashed

3 or DashDot

4 or DashDotDot

Marker(<markerState>, {x1, y1}, {x2, y2}, ...)

Marker(<markerState>, [x1, x2, ...], [y1, y2, ...})

Description

Draws one or more markers at the points described either by lists or matrices. The optional markerState argument sets the type of marker.

Marker Size(n)

Description

Sets the size used for markers.

Mousetrap(dragscript, mouseupscript)

Description

Captures click coordinates to update graph properties. The first script is executed at drag and the second at mouseup.

Normal Contour(prob, meanMatrix, stdMatrix, corrMatrix, <colorsMatrix>, <fill=x>)

Description

Draws normal probability contours for k populations and two variables.

Arguments

prob

A scalar or matrix of probabilities.

meanMatrix

A matrix of means of size k by 2.

stdMatrix

A matrix of standard deviations of size k by 2.

corrMatrix

A matrix of correlations of size k by 1.

colorsMatrix

(Optional) Specifies the color(s) for the k contour(s). The colors must be specified as JSL colors (either JSL color integer values or return values of JSL Color functions such as RGB Color or HLS Color).

fill=x

(Optional) Specifies the amount of transparency for the contour fill color.

Oval(x1, y1, x2, y2, <fill>)

Oval({x1, y1}, {x2, y2}, <fill>)

Description

Draws an oval inside the rectangle whose diagonal has the coordinates (x1, y1) and (x2, y2). Fill is Boolean. If fill is 0, the oval is empty. If fill is nonzero, the oval is filled with the current fill color. The default value for fill is 0.

Path(pathMatrix|pathText, <fill>)

Description

Draws a stroke along the given path. If a fill is specified, the interior of the path is filled with the current fill color.

Argument

pathMatrix

An Nx3 matrix.

pathText

A string that contains SVG code.

fill

An optional, Boolean argument that specifies whether a line is drawn (0) or the path is filled (1). The default value is 0.

Note

A path matrix has three columns, for x and y, and a flag. The flag value for each point can be 0 for control, 1 for move, 2 for line segment, 3 for cubic Bézier segment, and any negative value to close the path.

Path To Char(path)

Description

Converts a path specification from a matrix to a string.

Returns

A string.

Argument

path

An Nx3 path matrix.

Note

A path matrix has three columns, for x and y, and a flag. The flag value for each point can be 0 for control, 1 for move, 2 for line segment, 3 for cubic Bézier segment, and any negative value to close the path.

Pen Color(n)

Description

Sets the color used for the pen.

Pen Size(n)

Description

Sets the thickness of the pen in pixels.

Pick Color( <"window title">, <name|index|RGBlist>)

Description

Creates a color picker, which enables the user to select a color to apply to graphs. The operating system color picker lets users select a predefined color or create their own color. You can also specify a default color in your script. If you omit the default color, Black is selected.

Returns

The color that the user selected in the operating system’s color picker.

Optional Arguments

window title

Specifies the title of the color picker window.

name

The name of the default JMP color.

index

The number of the default JMP color.

RGBlist

The RGB values of the default color.

Notes

See Create a Color Picker in the Scripting Guide.

Pie(x1, y1, x2, y2, startangle, endangle)

Description

Draws a filled pie slice. The two points describe a rectangle, within which is a virtual oval. Only the slice described by the start and end angles is drawn.

Pixel Line To(x, y)

Description

Draws a one-pixel-wide line from the current pixel location to the location given in pixel coordinates. Set the current pixel location using the Pixel Origin and Pixel Move To commands.

Pixel Move To(x, y)

Description

Moves the current pixel location to a new location given in pixel coordinates.

Pixel Origin(x, y)

Description

Sets the origin, in graph coordinates, for subsequent Pixel Line To or Pixel Move To commands.

Polygon({x1, y1}, {x2, y2}, ...)

Polygon(xmatrix, ymatrix)

Description

Draws a filled polygon defined by the listed points.

Polygon Area({x1, y1}, {x2, y2}, ...)

Polygon Area(xmatrix, ymatrix)

Description

Calculates the area of the specified polygon.

Examples

area = Polygon Area( {0, 0}, {0, 10}, {10, 10}, {10, 0} );
area = Polygon Area( [10 20 30], [10 30 20] );

Polygon Centroid({x1, y1}, {x2, y2}, ...)

Polygon Centroid(xmatrix, ymatrix)

Description

Calculates the centroid of the specified polygon.

Examples

{cx, cy} = Polygon Centroid( {0, 0}, {0, 10}, {10, 10}, {10, 0} );
centroid = Polygon Centroid( [10 20 30], [10 30 20] );

Pixel Path(h, v, path matrix|path text, <fill=0>, <scale=1.0>, <orient={0.0., 1.0})

Description

Draws a stroke along the given pixel-based path if the fill is 0, or paints the interior of the path if the fill is not 0.

Arguments

h, v

Specifies the horizontal and vertical position.

path matrix

Contains three columns for x, y, and flags for each point in the path. The flag values are 0 for control, 1 for move, 2 for line segment, 3 for cubic Bézier segment, and are negative if the point also closes the path.

path text

Supports SVG syntax. The path is scaled and translated about its origin according to the optional parameters, with the orientation specified in the axis space.

Pixel Text(<properties>, {h, v}, text, ...)

Description

Moves to the {h, v} pixel position and draws text the text argument specifies.

Optional Arguments

center justified

Center justifies the text.

right justified

Right justifies the text.

erased

Omits pixels from the edges of the

boxed

Displays a box around the text.

counterclockwise

Rotates the text counterclockwise.

clockwise

Rotates the text clockwise.

Rect(x1, y1, x2, y2, <fill>)

Rect({x1, y1}, {x2, y2}, <fill>)

Description

Draws a rectangle whose diagonal has the coordinates (x1, y1) and (x2, y2). Fill is Boolean. If fill is 0, the rectangle is empty. If fill is nonzero, the rectangle is filled with the current fill color. The default value for fill is 0.

Remove Color Theme("Name"|{"Name", <flags>, {color, ...}, <{position, ...}>}>)

Description

Removes a custom color theme from the global list, either by name or by the full color theme object.

Arguments

Name

The name of the color theme.

flags

A number that represents metadata such as whether the theme is continuous or categorical. Run Get Color Theme Details("name") on the color theme and use the flag that is returned.

color

The RGB values for the color.

position

A number between 0 and 1. There is one number per color that indicates where on the gradient that color is, where 0 is the beginning and 1 is the end.

Example

Remove Color Theme( {"Yellow Blue", 0, {{255, 255, 0}, {0, 0, 255}}, {0.0, 1.0}} );

RGB Color(r, g, b)

RGB Color({r, g, b})

Description

Converts red, green, and blue values into a JMP color number.

Returns

An integer that is a JMP color number.

Arguments

Red, green, and blue, or a list containing the three RGB values. All values should be between 0 and 1.

Text(<properties>, ({x, y}|{left, bottom, right, top}), "text")

Description

Draws the quoted string text at the given point, either the x and y axes or the left, bottom, right, and top axes.

Properties can be any of several named arguments: Center Justified, Right Justified, Erased, Boxed, Counterclockwise, Position, and named arguments. The position, named arguments, and strings can be added in any order. The position and named arguments apply to all the strings.

Text Color(n)

Description

Sets the color for text strings.

Text Font(fontName, <size>, <"bold italic underline strikeout">, <angle>)

Description

Sets the font for text strings. Use without arguments to get the current font properties. Angle is in degrees clockwise.

Text Size(n)

Description

Sets the font size in points for text strings.

Transparency(alpha)

Description

Sets the transparency of the current drawing, with alpha between 0 and 1 where 0 is clear (no drawing) and 1 is completely opaque (the default).

Note

Not all operating systems support transparency.

V Line(x, <y1, y2>)

Description

Draws a vertical line at x across the graph. If you specify start and end points on the y-axis (y1 and y2), the line is drawn vertically at x from y1 to y2. You can also draw multiple lines by using a matrix of values in the x argument.

V Size()

Description

Returns the vertical size of the graphics frame in pixels

X Function(expr, symbol, <Min(min), Max(max), Fill(value), Inc(bound), Show Details(n)>)

Description

Draws a plot of the function as the symbol is varied over the y-axis of the graph.

X Origin()

Description

Returns the x-value for the left edge of the graphics frame.

X Range()

Description

Returns the distance from the left to right edge of the display box. For example, X Origin() + X Range() is the right edge.

X Scale(xmin, xmax)

Description

Sets the range for the horizontal scale. The default value for xmin is 0, and the default value for xmax is 100.

XY Function(x(t), y(t), t, min(min), max(max), inc(bound) | steps(min))

Description

Combines an expression of x(t) and y(t) to draw an x-y curve for the specified range of parameter t.

Note: Either inc() or steps() is needed if the default granularity misses details.

Y Function(expr, symbol, <Min(min), Max(max), Fill(value), Inc(bound), Show Details(n)>)

Description

Draws a plot of the function as the symbol is varied over the x- axis of the graph.

Y Origin()

Description

Returns the y-value for the bottom edge of the graphics frame.

Y Range()

Description

Returns the distance from the bottom to top edges of a display box. For example, Y Origin() + Y Range() is the top edge.

Y Scale(ymin, ymax)

Description

Sets the range for the vertical scale. If you do not specify a scale, it defaults to (0, 100).

Want more information? Have questions? Get answers in the JMP User Community (community.jmp.com).