34. Graphics

J gives you several ways to draw pictures. The Plot Package is a quick but powerful way to display datasets in 2D or 3D form. If you want to draw your own graphics, you can use the gl2 library for 2D graphics, or OpenGL for 3D.

Plot Package

The easy way to display data in J is with Plot. First, load the Plot Package: load 'plot'

Hand your data to the plot verb: plot 3 1 4 1 5 9

and it will give you a graph of your data.

Plot Demo

To see what J Plot can do, go to the menu bar in a J session and click down to Studio|Demos|plot. A Plot window will pop up, on whose menu bar pulldowns labeled 2D, 3D, Multi, Styles, and Gallery contain lists of demo plots. Click on one and you will immediately see the plot. When you find an interesting one, you may click Options|View Definition to see the commands that created it.

Interfaces to Plot

The Plot Package has two interfaces: lightning-fast (the plot verb) and fast (the pd verb). pd lets you build a custom plot containing multiple datasets and options. The picture described by plot 3 1 4 1 5 9 could have been built with

pd 'reset'

pd 'type line' pd 3 1 4 1 5 9 pd 'show'

plot and pd make up the Plot Package, which I will refer to simply as Plot.

Plot has a great variety of options which you can find listed in the User Guide. Here I will give enough of an overview to get started. If you need a feature for your plot, there's a good chance it's described in the User Guide. If you need to direct your plot to PostScript or to a control on a form, the User Guide explains that too.

Plot accepts a series of commands, options, and data. Commands are actions taken independent of any data: setting the size of the plot window(s), writing annotation text, and the like. Options, which include things like axis scaling and color selection, control the interpretation of subsequent data, which is added to the plot using whatever options are in effect when the data is encountered. A single plot may contain multiple sets of data with different options.

193

Commands and Options

Plot Type

The most important option is the type of plot: surface or wire to display 3-D data, line to graph 2-D or 3D data, symbol and dot to plot points individually, and a variety of types to produce bar charts, pie charts, error bars, and many others.

Colors

The components of a plot have different colors which you can specify. A color is given either as a 3-item list of red,green,blue intensity in the range 0-255, or as a name taken from J's list in system\packages\color\colortab.ijs. Names of colors are not case-sensitive. The standard colors for plot are BLUE, RED, GREEN,

PURPLE, FUCHSIA, OLIVE, TEAL, YELLOW, MEDIUMBLUE, AQUA, BROWN, and

GRAY.

The background of the plot is made up of two parts, the graph background which is the canvas the plot is drawn on, and the frame background which surrounds the graph background, filling out the window. These colors can be set simultaneously with

backcolor color_spec

The default is backcolor 255 255 255 or, equivalently, backcolor WHITE. The components of the background can be set individually with

framebackcolor color_spec graphbackcolor color_spec

Most plotted data is drawn with the item colors. The data is broken into sets of points, and the item colors are assigned to the sets sequentially. By default the item colors are the standard colors; they can be set by

itemcolor color_spec,color_spec...

The list of item colors can be as long as you want; it recycles as needed.

Certain plot types, such as density, derive the plotted colors from the data. For these plots you use

bandcolor color_spec,color_spec...

to specify the colors used for the bands of data.

Other components have their own colors, set by the following commands whose names are mostly self-explanatory: axiscolor, captioncolor, edgecolor (for edges of filled regions), gridcolor, keycolor (a list, used for legend boxes), rulecolor, symbolcolor (for symbol plots), textcolor, and titlecolor.

Fonts

You can select the font for the different kinds of text drawing. The commands are captionfont, keyfont, labelfont, symbolfont, textfont, and titlefont. An example is

titlefont Arial 18

Postscript Type 1 fonts are also supported.

194

Titles, Captions, and Labels

The title of the plot is drawn above the plot. You give the title with title title_text

titlecolor and titlefont apply to the title.

A caption is a character string displayed running parallel to an axis, and can be had with

Ccaption caption_text

(C is replaced by x, y, or z to select the coordinate), where caption_text should be enclosed in double-quotes if it contains spaces. captioncolor and captionfont apply to captions.

Labeling the axes means marking them to indicate coordinate values and is controlled

by

labels xon yon [zon]

(default 1 1) to turn labeling on or off. By default the labels are just the numeric values of the coordinates at the tic marks, but you can use

Clabel label1 label2...

to specify the label at each tic. If labeln contains spaces, it should be enclosed in double-quotes. You can specify the coordinates at which labels are to be shown with

Cticpos positions

or you can apply labels at regular intervals with

Ctic label_interval tics_between_labels which will write a label at intervals of label_interval, and add

tics_between_labels unlabeled tics between labeled tics. The plot will be scaled to match the range of your data unless you specify the range of the coordinate with

Crange min max

labelcolor and labelfont apply to labels.

Annotation (Text in the Drawing Area)

Annotation text is given by the text options: textcolor color

where color is red,green,blue or a name such as RED; textfont font_name size

to select the font;

text xpos ypos text textc xpos ypos text textr xpos ypos text

to draw text at the given position, left-aligned, centered, or right-aligned. Many other options are on view in the User Guide.

Data; Constructing a Plot with pd

Commands, options, and data are all added to the plot using the monadic pd verb. Character operands to pd are interpreted as commands or options with the format

name value where name identifies the command/option, which is set to the (optional)

195

value. Multiple commands/options can be given to pd, either as a list of boxed strings, or as one long string with semicolons used as a separator between command/options.

Numeric operands to pd are data: one or more sets of points, where a point comprises a dependent variable and one or two independent variables Normally data will be a boxed list, x;y for 2-D data or x;y;z for 3-D data. The last item (y for 2-D, z for 3-D) is the dependent variable whose values correspond to the independent variables given by the previous items. We can distinguish 3 types of plot: 2-D line plots, 3-D line plots, and surface plots.

2-D Line Plots

The dependent variable y may be a list or an array. Each 1-cell of y gives a set of points, and each set is plotted with a different item color. x may have the same shape as y, or x may be a list with the shape of a 1-cell of y in which case it is repeated for each 1-cell of y.

3-D Line and Point Plots

The dependent variable z may be a list or an array. Each 1-cell of z gives a set of points, and each set is plotted with a different item color. x and y must each be a list, with the shape of a 1-cell of z, which is repeated for each 1-cell of z.

surface and wire Plots (3-D)

The dependent variable z is an array. x may have the same shape as z, or be a list with one atom for each row of z: the atom is repeated across the row. y may have the same shape as z, or be a list with one atom for each column of z: the atom is repeated down the column.

Unboxed operands to pd

The boxing can be omitted from a data operand to pd, in which case it gives values of the dependent variable (y for 2-D, z for 3-D) and the independent variables are taken to be integers starting at 0. Or, the operand can be a complex list in which case the real parts are x and the imaginary parts are y.

Control Commands to pd: Starting and Ending a Plot

The first command in a plot should be pd 'reset'. After you have sent all your data through pd, your last command should be pd 'show' which causes the plot to be displayed.

Quick Plots Using plot

If your plot does not require multiple datasets with different options, you can display the whole thing with one use of the plot verb:

commands_and_options plot data

plot starts a new plot, sends the commands_and_options through pd, sends the data through pd, and issues pd 'show' to display the result. The axes will be scaled to fit your data. If data is made up of a rank-2 array of boxes each of which contains a boxed list, each box gives the data for a subplot: the plot window is divided into tiles

196

based on the shape of data, and each atom of data is opened revealing a list of x;y[;z] boxes containing data to be plotted in corresponding tile. An example of subplots is

plot 2 1 $ (<3 1 4 1 5 9) ,&< (<2 7 1 8 2 8)

Generating Plots of Functions

Idioms for Generating Plot Operands: the steps verb

For a simple 2-D plot of the value of a function f evaluated at the values x, use plot x ; f x

If you just want evenly-spaced values of x, you can use the steps verb: steps initial_value final_value number_of_intervals

A plot of one period of the sine function is given by

plot (steps 0 2p1 100) ; sin steps 0 2p1 100

(2p1 is 2π). To plot two functions at the same x values, make each function's values a row of an array:

x =. steps 0 2p1 100

plot x ; (sin x) ,: cos x

If you learn about tacit programming, you will be able to express this plot as plot (; sin,:cos) steps 0 2p1 100

For 3-D plot of a function f evaluated on a grid of x and y values, use plot x ; y ; x f"0/ y

f"0/ is described in the "Make a Table" section of the chapter "Odds and Ends".

x f"0/ y evaluates f at each combination of x and y . To plot cos®/(1+r) we would use

x =. y =. steps _4 4 100

f =. 4 : '(cos r) % 1 + r =. x. +&:*: y.' plot x ; y ; x f"0/ y

The tacit version of this plot is given succinctly by plot x ([ ; ] ; f"0/) y

The Simplest Function Plotting: Let Plot Evaluate Your Function

The simplest way to plot a function is to give Plot the description of the function and the domain, and let Plot decide where to evaluate the function. You do this by giving the function instead of the data as the dependent variable in the right argument to plot or pd . An example is

plot 0 10 ; 'sin'

The character string instead of data tells Plot to evaluate the sin function over the interval [0,10].

The independent variable(s) are given either as intervals or as lists of points. An interval is indicated by 2 or 3 numbers, specifying start value,end value,number of steps. A list of points is indicated by a boxed argument containing the points, or by an unboxed list of more than 3 points. Multiple intervals or point-lists are allowed.

197

If the number of steps is omitted or 0, Plot will pick an appropriate number of points to use. It does so by repeatedly subdividing the interval until the curve is smooth or it decides that the curve is discontinous, in which case it plots continuous sections separately.

The subdivision is controlled by the plot commands Cfuncres and singtoler. Cfuncres (C is x or y) gives the subdivision resolution: an interval smaller than 1/Cfuncres of the screen will not be split. Cfuncres defaults to twice the pixel resolution of the plot. singtoler is used when the display has singularities, and controls how much of the heading-off-to-infinity tail of the curve will be shown at the singularity. You can experiment to find a good value for singtoler for your application; the default is 10 and higher numbers cause more of the tail to be displayed.

The function(s) to be displayed can be given as a list of gerunds, one for each verb to be drawn, or as a string where the verb-specifiers are separated by the ` character (use doubled ` as an escape if your verb contains a ` character). Each verb-specifier can be in either tacit or explicit form: if it contains the characters y. it is assumed to describe an explicit verb, otherwise a tacit one.

The verbs are invoked with lists as arguments and should be able to return a list of results. If you use pd, note that the verbs are not executed until pd 'show' is processed, so the values of any public variables that are referred to by an explicit verb will use the values in effect when the pd 'show' is executed. Public variables referred to in a tacit verb are frozen (using f.) when the pd for the function is issued.

Examples of function plots:

plot _10 10 ; '%' NB. reciprocal: has a discontinuity plot _10 10 ; 'sin`cos' NB. two curves

plot 0.001 0.1 ; 'sin % y.' NB. sin(1/x), a busy function

The 3-D plot shown above can be created with plot _4 4 100 ; _4 4 100 ; 'f'

Assembling a Multipart Plot with pd

A plot of a function with discontinuities, or multiple functions with different domains, can be assembled using pd. If we want to plot the function 1/x (the J primitive %) by hand rather than using function plotting as shown above, we need to plot the negative and positive sides individually:

pd 'reset'

pd 'type line'

pd 'color 0 0 255'

pd (^ steps _2 2 50) ; % (^ steps _2 2 50)

pd (- ^ steps _2 2 50) ; % (- ^ steps _2 2 50) pd 'show'

Here we plotted the positive x values, then the negative ones. We set color to override Plot's default behavior of giving each dataset a different color. The exponential applied to the x values keeps the points spaced fairly uniformly along the curve.

198