15. Graphics

The commands for graphing data begin with the g prefix key. Calc uses GNUPLOT 2.0 or 3.0 to do graphics. These commands will only work if GNUPLOT is available on your system. (While GNUPLOT sounds like a relative of GNU Emacs, it is actually completely unrelated. However, it is free software and can be obtained from the Free Software Foundation's machine `prep.ai.mit.edu'.)

If you have GNUPLOT installed on your system but Calc is unable to find it, you may need to set the calc-gnuplot-name variable in your `.emacs' file. You may also need to set some Lisp variables to show Calc how to run GNUPLOT on your system; these are described under g D and g O below. If you are using the X window system, Calc will configure GNUPLOT for you automatically. If you have GNUPLOT 3.0 and you are not using X, Calc will configure GNUPLOT to display graphs using simple character graphics that will work on any terminal.

15.1 Basic Graphics

The easiest graphics command is g f (calc-graph-fast). This command takes two vectors of equal length from the stack. The vector at the top of the stack represents the "y" values of the various data points. The vector in the second-to-top position represents the corresponding "x" values. This command runs GNUPLOT (if it has not already been started by previous graphing commands) and displays the set of data points. The points will be connected by lines, and there will also be some kind of symbol to indicate the points themselves.

The "x" entry may instead be an interval form, in which case suitable "x" values are interpolated between the minimum and maximum values of the interval (whether the interval is open or closed is ignored).

The "x" entry may also be a number, in which case Calc uses the sequence of "x" values x, x+1, x+2, etc. (Generally the number 0 or 1 would be used for x in this case.)

The "y" entry may be any formula instead of a vector. Calc effectively uses N (calc-eval-num) to evaluate variables in the formula; the result of this must be a formula in a single (unassigned) variable. The formula is plotted with this variable taking on the various "x" values. Graphs of formulas by default use lines without symbols at the computed data points. Note that if neither "x" nor "y" is a vector, Calc guesses at a reasonable number of data points to use. See the g N command below. (The "x" values must be either a vector or an interval if "y" is a formula.)

If "y" is (or evaluates to) a formula of the form `xy(x, y)' then the result is a parametric plot. The two arguments of the fictitious xy function are used as the "x" and "y" coordinates of the curve, respectively. In this case the "x" vector or interval you specified is not directly visible in the graph. For example, if "x" is the interval `[0..360]' and "y" is the formula `xy(sin(t), cos(t))', the resulting graph will be a circle.

Also, "x" and "y" may each be variable names, in which case Calc looks for suitable vectors, intervals, or formulas stored in those variables.

The "x" and "y" values for the data points (as pulled from the vectors, calculated from the formulas, or interpolated from the intervals) should be real numbers (integers, fractions, or floats). If either the "x" value or the "y" value of a given data point is not a real number, that data point will be omitted from the graph. The points on either side of the invalid point will not be connected by a line.

See the documentation for g a below for a description of the way numeric prefix arguments affect g f.

If you store an empty vector in the variable PlotRejects (i.e., [ ] s t PlotRejects), Calc will append information to this vector for every data point which was rejected because its "x" or "y" values were not real numbers. The result will be a matrix where each row holds the curve number, data point number, "x" value, and "y" value for a rejected data point. See section 14.5 The Evaluates-To Operator, for a handy way to keep tabs on the current value of PlotRejects. See section 14.3 Other Operations on Variables, for the s R command which is another easy way to examine PlotRejects.

To clear the graphics display, type g c (calc-graph-clear). If the GNUPLOT output device is an X window, the window will go away. Effects on other kinds of output devices will vary. You don't need to use g c if you don't want to--if you give another g f or g p command later on, it will reuse the existing graphics window if there is one.

15.2 Three-Dimensional Graphics

The g F (calc-graph-fast-3d) command makes a three-dimensional graph. It works only if you have GNUPLOT 3.0 or later; with GNUPLOT 2.0, you will see a GNUPLOT error message if you try this command.

The g F command takes three values from the stack, called "x", "y", and "z", respectively. As was the case for 2D graphs, there are several options for these values.

In the first case, "x" and "y" are each vectors (not necessarily of the same length); either or both may instead be interval forms. The "z" value must be a matrix with the same number of rows as elements in "x", and the same number of columns as elements in "y". The result is a surface plot where z_ij is the height of the point at coordinate (x_i, y_j) on the surface. The 3D graph will be displayed from a certain default viewpoint; you can change this viewpoint by adding a `set view' to the `*Gnuplot Commands*' buffer as described later. See the GNUPLOT 3.0 documentation for a description of the `set view' command.

Each point in the matrix will be displayed as a dot in the graph, and these points will be connected by a grid of lines (isolines).

In the second case, "x", "y", and "z" are all vectors of equal length. The resulting graph displays a 3D line instead of a surface, where the coordinates of points along the line are successive triplets of values from the input vectors.

In the third case, "x" and "y" are vectors or interval forms, and "z" is any formula involving two variables (not counting variables with assigned values). These variables are sorted into alphabetical order; the first takes on values from "x" and the second takes on values from "y" to form a matrix of results that are graphed as a 3D surface.

If the "z" formula evaluates to a call to the fictitious function `xyz(x, y, z)', then the result is a "parametric surface." In this case, the axes of the graph are taken from the x and y values in these calls, and the "x" and "y" values from the input vectors or intervals are used only to specify the range of inputs to the formula. For example, plotting `[0..360], [0..180], xyz(sin(x)*sin(y), cos(x)*sin(y), cos(y))' will draw a sphere. (Since the default resolution for 3D plots is 5 steps in each of "x" and "y", this will draw a very crude sphere. You could use the g N command, described below, to increase this resolution, or specify the "x" and "y" values as vectors with more than 5 elements.

It is also possible to have a function in a regular g f plot evaluate to an xyz call. Since g f plots a line, not a surface, the result will be a 3D parametric line. For example, `[[0..720], xyz(sin(x), cos(x), x)]' will plot two turns of a helix (a three-dimensional spiral).

As for g f, each of "x", "y", and "z" may instead be variables containing the relevant data.

15.3 Managing Curves

The g f command is really shorthand for the following commands: C-u g d g a g p. Likewise, g F is shorthand for C-u g d g A g p. You can gain more control over your graph by using these commands directly.

The g a (calc-graph-add) command adds the "curve" represented by the two values on the top of the stack to the current graph. You can have any number of curves in the same graph. When you give the g p command, all the curves will be drawn superimposed on the same axes.

The g a command (and many others that affect the current graph) will cause a special buffer, `*Gnuplot Commands*', to be displayed in another window. This buffer is a template of the commands that will be sent to GNUPLOT when it is time to draw the graph. The first g a command adds a plot command to this buffer. Succeeding g a commands add extra curves onto that plot command. Other graph-related commands put other GNUPLOT commands into this buffer. In normal usage you never need to work with this buffer directly, but you can if you wish. The only constraint is that there must be only one plot command, and it must be the last command in the buffer. If you want to save and later restore a complete graph configuration, you can use regular Emacs commands to save and restore the contents of the `*Gnuplot Commands*' buffer.

If the values on the stack are not variable names, g a will invent variable names for them (of the form `PlotDatan') and store the values in those variables. The "x" and "y" variables are what go into the plot command in the template. If you add a curve that uses a certain variable and then later change that variable, you can replot the graph without having to delete and re-add the curve. That's because the variable name, not the vector, interval or formula itself, is what was added by g a.

A numeric prefix argument on g a or g f changes the way stack entries are interpreted as curves. With a positive prefix argument n, the top n stack entries are "y" values for n different curves which share a common "x" value in the n+1st stack entry. (Thus g a with no prefix argument is equivalent to C-u 1 g a.)

A prefix of zero or plain C-u means to take two stack entries, "x" and "y" as usual, but to interpret "y" as a vector of "y" values for several curves that share a common "x".

A negative prefix argument tells Calc to read n vectors from the stack; each vector [x, y] describes an independent curve. This is the only form of g a that creates several curves at once that don't have common "x" values. (Of course, the range of "x" values covered by all the curves ought to be roughly the same if they are to look nice on the same graph.)

For example, to plot sin(n x) for integers n from 1 to 5, you could use v x to create a vector of integers (n), then V M ' or V M $ to map `sin(n x)' across this vector. The resulting vector of formulas is suitable for use as the "y" argument to a C-u g a or C-u g f command.

The g A (calc-graph-add-3d) command adds a 3D curve to the graph. It is not legal to intermix 2D and 3D curves in a single graph. This command takes three arguments, "x", "y", and "z", from the stack. With a positive prefix n, it takes n+2 arguments (common "x" and "y", plus n separate "z"s). With a zero prefix, it takes three stack entries but the "z" entry is a vector of curve values. With a negative prefix -n, it takes n vectors of the form [x, y, z]. The g A command works by adding a splot (surface-plot) command to the `*Gnuplot Commands*' buffer.

(Although g a adds a 2D plot command to the `*Gnuplot Commands*' buffer, Calc changes this to splot before sending it to GNUPLOT if it notices that the data points are evaluating to xyz calls. It will not work to mix 2D and 3D g a curves in a single graph, although Calc does not currently check for this.)

The g d (calc-graph-delete) command deletes the most recently added curve from the graph. It has no effect if there are no curves in the graph. With a numeric prefix argument of any kind, it deletes all of the curves from the graph.

The g H (calc-graph-hide) command "hides" or "unhides" the most recently added curve. A hidden curve will not appear in the actual plot, but information about it such as its name and line and point styles will be retained.

The g j (calc-graph-juggle) command moves the curve at the end of the list (the "most recently added curve") to the front of the list. The next-most-recent curve is thus exposed for g d or similar commands to use. With g j you can work with any curve in the graph even though curve-related commands only affect the last curve in the list.

The g p (calc-graph-plot) command uses GNUPLOT to draw the graph described in the `*Gnuplot Commands*' buffer. Any GNUPLOT parameters which are not defined by commands in this buffer are reset to their default values. The variables named in the plot command are written to a temporary data file and the variable names are then replaced by the file name in the template. The resulting plotting commands are fed to the GNUPLOT program. See the documentation for the GNUPLOT program for more specific information. All temporary files are removed when Emacs or GNUPLOT exits.

If you give a formula for "y", Calc will remember all the values that it calculates for the formula so that later plots can reuse these values. Calc throws out these saved values when you change any circumstances that may affect the data, such as switching from Degrees to Radians mode, or changing the value of a parameter in the formula. You can force Calc to recompute the data from scratch by giving a negative numeric prefix argument to g p.

Calc uses a fairly rough step size when graphing formulas over intervals. This is to ensure quick response. You can "refine" a plot by giving a positive numeric prefix argument to g p. Calc goes through the data points it has computed and saved from previous plots of the function, and computes and inserts a new data point midway between each of the existing points. You can refine a plot any number of times, but beware that the amount of calculation involved doubles each time.

Calc does not remember computed values for 3D graphs. This means the numerix prefix argument, if any, to g p is effectively ignored if the current graph is three-dimensional.

The g P (calc-graph-print) command is like g p, except that it sends the output to a printer instead of to the screen. More precisely, g p looks for `set terminal' or `set output' commands in the `*Gnuplot Commands*' buffer; lacking these it uses the default settings. However, g P ignores `set terminal' and `set output' commands and uses a different set of default values. All of these values are controlled by the g D and g O commands discussed below. Provided everything is set up properly, g p will plot to the screen unless you have specified otherwise and g P will always plot to the printer.

15.4 Graphics Options

The g g (calc-graph-grid) command turns the "grid" on and off. It is off by default; tick marks appear only at the edges of the graph. With the grid turned on, dotted lines appear across the graph at each tick mark. Note that this command only changes the setting in `*Gnuplot Commands*'; to see the effects of the change you must give another g p command.

The g b (calc-graph-border) command turns the border (the box that surrounds the graph) on and off. It is on by default. This command will only work with GNUPLOT 3.0 and later versions.

The g k (calc-graph-key) command turns the "key" on and off. The key is a chart in the corner of the graph that shows the correspondence between curves and line styles. It is off by default, and is only really useful if you have several curves on the same graph.

The g N (calc-graph-num-points) command allows you to select the number of data points in the graph. This only affects curves where neither "x" nor "y" is specified as a vector. Enter a blank line to revert to the default value (initially 15). With no prefix argument, this command affects only the current graph. With a positive prefix argument this command changes or, if you enter a blank line, displays the default number of points used for all graphs created by g a that don't specify the resolution explicitly. With a negative prefix argument, this command changes or displays the default value (initially 5) used for 3D graphs created by g A. Note that a 3D setting of 5 means that a total of 5^2 = 25 points will be computed for the surface.

Data values in the graph of a function are normally computed to a precision of five digits, regardless of the current precision at the time. This is usually more than adequate, but there are cases where it will not be. For example, plotting 1 + x with x in the interval `[0 .. 1e-6]' will round all the data points down to 1.0! Putting the command `set precision n' in the `*Gnuplot Commands*' buffer will cause the data to be computed at precision n instead of 5. Since this is such a rare case, there is no keystroke-based command to set the precision.

The g h (calc-graph-header) command sets the title for the graph. This will show up centered above the graph. The default title is blank (no title).

The g n (calc-graph-name) command sets the title of an individual curve. Like the other curve-manipulating commands, it affects the most recently added curve, i.e., the last curve on the list in the `*Gnuplot Commands*' buffer. To set the title of the other curves you must first juggle them to the end of the list with g j, or edit the `*Gnuplot Commands*' buffer by hand. Curve titles appear in the key; if the key is turned off they are not used.

The g t (calc-graph-title-x) and g T (calc-graph-title-y) commands set the titles on the "x" and "y" axes, respectively. These titles appear next to the tick marks on the left and bottom edges of the graph, respectively. Calc does not have commands to control the tick marks themselves, but you can edit them into the `*Gnuplot Commands*' buffer if you wish. See the GNUPLOT documentation for details.

The g r (calc-graph-range-x) and g R (calc-graph-range-y) commands set the range of values on the "x" and "y" axes, respectively. You are prompted to enter a suitable range. This should be either a pair of numbers of the form, `min:max', or a blank line to revert to the default behavior of setting the range based on the range of values in the data, or `$' to take the range from the top of the stack. Ranges on the stack can be represented as either interval forms or vectors: `[min .. max]' or `[min, max]'.

The g l (calc-graph-log-x) and g L (calc-graph-log-y) commands allow you to set either or both of the axes of the graph to be logarithmic instead of linear.

For 3D plots, g C-t, g C-r, and g C-l (those are letters with the Control key held down) are the corresponding commands for the "z" axis.

The g z (calc-graph-zero-x) and g Z (calc-graph-zero-y) commands control whether a dotted line is drawn to indicate the "x" and/or "y" zero axes. (These are the same dotted lines that would be drawn there anyway if you used g g to turn the "grid" feature on.) Zero-axis lines are on by default, and may be turned off only in GNUPLOT 3.0 and later versions. They are not available for 3D plots.

The g s (calc-graph-line-style) command turns the connecting lines on or off for the most recently added curve, and optionally selects the style of lines to be used for that curve. Plain g s simply toggles the lines on and off. With a numeric prefix argument, g s turns lines on and sets a particular line style. Line style numbers start at one and their meanings vary depending on the output device. GNUPLOT guarantees that there will be at least six different line styles available for any device.

The g S (calc-graph-point-style) command similarly turns the symbols at the data points on or off, or sets the point style. If you turn both lines and points off, the data points will show as tiny dots.

Another way to specify curve styles is with the LineStyles and PointStyles variables. These variables initially have no stored values, but if you store a vector of integers in one of these variables, the g a and g f commands will use those style numbers instead of the defaults for new curves that are added to the graph. An entry should be a positive integer for a specific style, or 0 to let the style be chosen automatically, or -1 to turn off lines or points altogether. If there are more curves than elements in the vector, the last few curves will continue to have the default styles. Of course, you can later use g s and g S to change any of these styles.

For example, '[2 -1 3] RET s t LineStyles causes the first curve to have lines in style number 2, the second curve to have no connecting lines, and the third curve to have lines in style 3. Point styles will still be assigned automatically, but you could store another vector in PointStyles to define them, too.

15.5 Graphical Devices

The g D (calc-graph-device) command sets the device name (or "terminal name" in GNUPLOT lingo) to be used by g p commands on this graph. It does not affect the permanent default device name. If you enter a blank name, the device name reverts to the default. Enter `?' to see a list of supported devices.

With a positive numeric prefix argument, g D instead sets the default device name, used by all plots in the future which do not override it with a plain g D command. If you enter a blank line this command shows you the current default. The special name default signifies that Calc should choose x11 if the X window system is in use (as indicated by the presence of a DISPLAY environment variable), or otherwise dumb under GNUPLOT 3.0 and later, or postscript under GNUPLOT 2.0. This is the initial default value.

The dumb device is an interface to "dumb terminals," i.e., terminals with no special graphics facilities. It writes a crude picture of the graph composed of characters like - and | to a buffer called `*Gnuplot Trail*', which Calc then displays. The graph is made the same size as the Emacs screen, which on most dumb terminals will be 80x24 characters. The graph is displayed in an Emacs "recursive edit"; type q or M-# M-# to exit the recursive edit and return to Calc. Note that the dumb device is present only in GNUPLOT 3.0 and later versions.

The word dumb may be followed by two numbers separated by spaces. These are the desired width and height of the graph in characters. Also, the device name big is like dumb but creates a graph four times the width and height of the Emacs screen. You will then have to scroll around to view the entire graph. In the `*Gnuplot Trail*' buffer, SPC, DEL, <, and > are defined to scroll by one screenful in each of the four directions.

With a negative numeric prefix argument, g D sets or displays the device name used by g P (calc-graph-print). This is initially postscript. If you don't have a PostScript printer, you may decide once again to use dumb to create a plot on any text-only printer.

The g O (calc-graph-output) command sets the name of the output file used by GNUPLOT. For some devices, notably x11, there is no output file and this information is not used. Many other "devices" are really file formats like postscript; in these cases the output in the desired format goes into the file you name with g O. Type g O stdout RET to set GNUPLOT to write to its standard output stream, i.e., to `*Gnuplot Trail*'. This is the default setting.

Another special output name is tty, which means that GNUPLOT is going to write graphics commands directly to its standard output, which you wish Emacs to pass through to your terminal. Tektronix graphics terminals, among other devices, operate this way. Calc does this by telling GNUPLOT to write to a temporary file, then running a sub-shell executing the command `cat tempfile >/dev/tty'. On typical Unix systems, this will copy the temporary file directly to the terminal, bypassing Emacs entirely. You will have to type C-l to Emacs afterwards to refresh the screen.

Once again, g O with a positive or negative prefix argument sets the default or printer output file names, respectively. In each case you can specify auto, which causes Calc to invent a temporary file name for each g p (or g P) command. This temporary file will be deleted once it has been displayed or printed. If the output file name is not auto, the file is not automatically deleted.

The default and printer devices and output files can be saved permanently by the m m (calc-save-modes) command. The default number of data points (see g N) and the X geometry (see g X) are also saved. Other graph information is not saved; you can save a graph's configuration simply by saving the contents of the `*Gnuplot Commands*' buffer.

If you are installing Calc you may wish to configure the default and printer devices and output files for the whole system. The relevant Lisp variables are calc-gnuplot-default-device and -output, and calc-gnuplot-print-device and -output. The output file names must be either strings as described above, or Lisp expressions which are evaluated on the fly to get the output file names.

Other important Lisp variables are calc-gnuplot-plot-command and calc-gnuplot-print-command, which give the system commands to display or print the output of GNUPLOT, respectively. These may be nil if no command is necessary, or strings which can include `%s' to signify the name of the file to be displayed or printed. Or, these variables may contain Lisp expressions which are evaluated to display or print the output.

The g x (calc-graph-display) command lets you specify on which X window system display your graphs should be drawn. Enter a blank line to see the current display name. This command has no effect unless the current device is x11.

The g X (calc-graph-geometry) command is a similar command for specifying the position and size of the X window. The normal value is default, which generally means your window manager will let you place the window interactively. Entering `800x500+0+0' would create an 800-by-500 pixel window in the upper-left corner of the screen.

The buffer called `*Gnuplot Trail*' holds a transcript of the session with GNUPLOT. This shows the commands Calc has "typed" to GNUPLOT and the responses it has received. Calc tries to notice when an error message has appeared here and display the buffer for you when this happens. You can check this buffer yourself if you suspect something has gone wrong.

The g C (calc-graph-command) command prompts you to enter any line of text, then simply sends that line to the current GNUPLOT process. The `*Gnuplot Trail*' buffer looks deceptively like a Shell buffer but you can't type commands in it yourself. Instead, you must use g C for this purpose.

The g v (calc-graph-view-commands) and g V (calc-graph-view-trail) commands display the `*Gnuplot Commands*' and `*Gnuplot Trail*' buffers, respectively, in another window. This happens automatically when Calc thinks there is something you will want to see in either of these buffers. If you type g v or g V when the relevant buffer is already displayed, the buffer is hidden again.

One reason to use g v is to add your own commands to the `*Gnuplot Commands*' buffer. Press g v, then use C-x o to switch into that window. For example, GNUPLOT has `set label' and `set arrow' commands that allow you to annotate your plots. Since Calc doesn't understand these commands, you have to add them to the `*Gnuplot Commands*' buffer yourself, then use g p to replot using these new commands. Note that your commands must appear before the plot command. To get help on any GNUPLOT feature, type, e.g., g C help set label. You may have to type g C RET a few times to clear the "press return for more" or "subtopic of ..." requests. Note that Calc always sends commands (like `set nolabel') to reset all plotting parameters to the defaults before each plot, so to delete a label all you need to do is delete the `set label' line you added (or comment it out with `#') and then replot with g p.

You can use g q (calc-graph-quit) to kill the GNUPLOT process that is running. The next graphing command you give will start a fresh GNUPLOT process. The word `Graph' appears in the Calc window's mode line whenever a GNUPLOT process is currently running. The GNUPLOT process is automatically killed when you exit Emacs if you haven't killed it manually by then.

The g K (calc-graph-kill) command is like g q except that it also views the `*Gnuplot Trail*' buffer so that you can see the process being killed. This is better if you are killing GNUPLOT because you think it has gotten stuck.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.