.CHAPTER PLOTTING .AUTOPARAGRAPH This chapter describes the Fortran callable subroutines which permit the graphing of functions in a fairly simple manner. The first section describes the high level routines which provide autoscaling labelled x-y graphs of points or lines. The second section describes the low level "primitive" routines which are used by the high level routines to provide device-independent plotting. We have a number of different plotting devices: Tektronix emulating terminals (e.g. Retrographics), VT55 terminals, Epson FX-80 matrix printers, the Norpak colour raster display, and the HP7221B four colour plotter. The VT55 is not a true generalized plotting device, and as such is treated differently from the others. The plotting primitives are device independent. At the time the program is written, it is not necessary to decide which device is to be used. This decision is made at task build time, when the device-dependent library is selected. To build a program using these primitive routines is simple. Just add the name of the appropriate library for the desired output device to the BUILD command. If you wish to have access to more than one output device, you may specify that the plot output be directed to a file, which may be plotted later by the PLOTxx commands on various devices; this has the advantage that software character sets are used for the plot. .TESTPAGE 10 .LITERAL Library Device $PFLIB Device independent plot file. $TKLIB Tektronix type terminals; you must be logged into one. $HPLIB HP7221B plotter; you must be logged in through it. $NPLIB Norpak colour display; not necessary to log in to it. $LPLIB Line printer output onto matrix printer. .END LITERAL For example, to select the plot file output, use the build command BUILD MYPROG,$PFLIB. If you require another library, enclose the names in parentheses, BUILD MYPROG, ($INENLIB,$PFLIB). Usually one does not build a task with a device-specific library for one of the hard copy device such as HP or LP. For these, build with PFLIB instead, and then plot on the appropriate hardcopy device via PLOTxx. In fact the only time to use a device-specific library at all is when making interactive programs that ask questions, plot a graph, and ask more questions; TKLIB is appropriate for these. If you select a plot file output (PFLIB), when your program runs it will ask you to enter the name of the plot file. By just pressing return, you select the default name PLOT.PLT. If one exists already, a new version number will be created. You may enter any name you wish. To plot the contents of a plot file, enter the command PLOTxx, where xx is the two-letter code for the selected device like the library names above (TK, HP, NP, LP). If the plot file name is not PLOT.PLT you must also put on the command the name of the plot file (default extension .PLT). It will ask that you hit return before each frame is displayed. You can skip some frames at the beginning by specifying the first frame to skip after the filename on the command line; you can terminate plotting by entering control-z instead of return. If you enter a negative number for the first frame to plot (e.g., PLOTHP myfile.PLT,-1), it will ask you to enter the pen numbers to use for each pen colour; this is occasionally used on the plotter to override the pen colours, for example when using a single india ink pen. Plot files produced by PFLIB may be concatenated together using PIP to make a single larger file. For example, PIP PLOTALL.PLT=PLOT.PLT;* and then PLOTLP PLOTALL. Note that these plotting routines all require the use of logical unit 1 and local event flag 1, so do not attempt to open files on lun 1. .HL 1 SAMPLE PLOTTING PROGRAM Before launching into a description of all the available subroutines, look at the example Fortran program below to see how simple it is to generate nice graphs. Note that while three subroutines were called, a single call to GRAF1 would suffice to generate a reasonable curve. All the other routines described later are optional and only embellish some features. Don't let their number frighten you. .LITERAL C SAMPLE PLOTTING PROGRAM REAL X(100), Y(100) C C SET UP THE CURVE C DO 10 J=1,100 X(J) = J 10 Y(J) = SIN(X(J)/20.0) * EXP(-X(J)/35.0) C C GRAPH THE CURVE C CALL GRSYM (66) !SQUARES WITH LINES CALL GRAF1 (X,Y,100) !PLOT THE GRAPH C C PLACE TITLE ON GRAPH C CALL GRTITL ('Section 4.1 Sample Plot', 100, 1 'X Axis label centred', 100, 'Y Axis', 100) CALL EXIT END >FTN TESTPLOT >BUILD TESTPLOT,$PFLIB >RUN TESTPLOT PLOTS -- Enter name of plot file [PLOT.PLT]: >PLOTHP PLOTS -- enter options (? for help): 0.33,20 > .END LITERAL .HL 1 GENERALIZED GRAPHING ROUTINES These are a set of high level routines made up of the low level routines, which allow the user to graph simple x-y functions. They do not require any plotter initiation or termination -- this is all done for you. At the simplest extreme, a single call to GRAF1 produces a readable graph. The descriptions for the available routines are organized as follows. First are the routines which actually generate a graph, followed by those routines which can add something to a graph, followed by those parameter setting routines which are called before other routines to modify their action, followed by misc routines. .HL 2 ROUTINES WHICH GENERATE GRAPHS .HL 3 GRAF1 (X, Y, NPTS) This plots a set of points defined by the vectors (X,Y), whose first NPTS elements are used. The scales are chosen depending on the range of values in (X,Y). The axes are labelled and a grid is drawn. Points are connected by lines. Calling this routine alone will generate a readable graph, all other routines are optional. .HL 3 GRAF2 (X, Y, NPTS, MX, MY, ILOG, IOPT, TITLE, XLABEL, YLABEL) This is similar to GRAF1 in that it plots a graph of y versus x with the option of autoscaling. It draws the grid and labels it. In addition, however, it may plot from 1 to 6 graphs on the same page in various locations, depending on the choice of MX,MY. GRxxTK, GRxxTK may be called beforehand, GRLOC may be called afterwards, and the scales may be retrieved afterwards by GRGSCA and GRLSCA. The log/linear state is set as if a call to GRLOG were made and stays in effect when a later call to GRAF1 is made. All other parameter setting routines for GRAF1 have no effect on GRAF2. X and Y are real arrays dimensioned to at least NPTS elements. If solid lines are to connect data points, one of the arrays should be monotonic. NPTS is the numbers of points to be plotted. If NPTS is negative, the number of points is taken as the absolute value, and the points are plotted on top of the existing graph using the scale values of the last call to GRAF2, without drawing a new grid. MX and MY are integers in the range 1-3 which determine where on the page the present graph is to go. If MX=1 it fills the width of the page; if MX=2 it fills the left half; if MX=3 it fills the right half. Similarly for MY. Thus MX=1,MY=2 draws a graph in the upper half of the page. A new page is begun only when the top left graph is plotted, so always begin at the top left. ILOG is an integer which determines the linear or logarithmic nature of the graph. For ILOG=1 to 4, the graph will be lin/lin, linx/logy, logx/liny, and log/log respectively. IOPT is an integer which determines how the data curve is to be drawn. This parameter is coded as a decimal integer as , where each letter represents a decimal digit, and is the pen colour, is the plotting symbol, and is the increment for plotting a symbol at every th point. Use C=1-4 for the colours black, red, green and blue respectively. =00 for no symbol, 01 for dots of colour C, 65-72 for special symbols in black (see GRSYM). is 0 for plotting the symbol only at each point, greater than 0 for plotting the symbol on top of the connected curve at every th oint. A special case is IOPT=1 to 4, which draws a connected curve of colour IOPT. If IOPT is negative, no data points are plotted, but the grid is drawn and labelled, and the scale is chosen from the values in X,Y. This way one can force the scale, for example by using the first two values of X and Y to store the endpoints. TITLE, XLABEL and YLABEL are character strings to be written on the top, bottom and left side respectively, of the graph. These are ASCIZ strings which may be either quoted strings or byte arrays with a zero byte at the end. .HL 2 ROUTINES WHICH ADD TO AN EXISTING GRAPH .HL 3 GRTITL (TITLE, LTITLE, XLABEL, LXLABEL, YLABEL, LYLABEL) .P 5 This annotates the graph just drawn by GRAF1 with a title above it, and labels on the x and y axes. Each title is a character string, followed by its length in bytes. If the titles are specified as quoted strings, the length may be set to a large number. For example, CALL GRTITL ('graph title', 100, 'x label', 100, 'y label', 100). This must be called after the GRAF1 call. See the SYMBOL subroutine under primitive routines to see what special characters such as Greek and subscripts are available. .HL 3 GRDATE Places the date and time in the lower right corner of the graph just drawn by GRAF1. This must be called after the GRAF1 call. .HL 3 SYMBOL This can be called to write on the graph. See the description in the next section under primitive routines. Unless it is followed by a call to GRTITL or GRDATE, you must follow these primitive routines by CALL PLOTF to flush the buffers. .HL 3 GRAF1A (XC, YC, NC, IC, ILINE, THICK, IPENC, XS, YS, NS, IS, IPENS, DIA, ISYMB) This routine may be called after GRAF1 or GRAF2 have generated a graph, with or without data points. Using the last scale, it can plot a set of symbols and/or a curve such that the curve jumps over the symbols. This looks nice in that no part of the line touches the symbol markers. Also special thick dashed lines are used, which are not available from the basic GRAF1 and GRAF2. These embellishments are included in a separate routine so that basic graphing routines can be kept as compact as possible. XC,YC are the coordinates of a set of NC points which define the line to be drawn. The values in XC must be in ascending order. IC is the interleave factor, so that every IC'th point is plotted (usually IC=1). ILINE is the code for the line type to draw, between 1 and 10 (see GRDSHL for a description of the line types). THICK is the width of the line in inches (0.1 to 0.15 looks good). IPENC is the pen colour to use when drawing the line. XS,YS are the coordinates of the NS points at which symbols are to be drawn or avoided. These points need not bear any relationship to those points in XC,YC, and can represent any number of points where the line is not desired to go. However these points must be in ascending order in x. IS is the interleave factor for the symbols, so that every IS'th point is plotted (usually IS=1). DIA is the diameter of the symbol in inches. If DIA is negative, no symbols are drawn, but the line still avoids those locations to the given ABS(DIA). ISYMB is the code for the type of symbol to use at each point. See SYMBOL for a description of the special plotting symbols available in the range 65 to 101. IPENS is the pen colour to use when plotting the symbols. .HL 2 PARAMETER SETTING ROUTINES These routines optionally come before the plotting routines, and affect their action. Most of them stay in effect until again changed, but some are reset immediately after a graph is generated. .HL 3 GRSYM (ISYM) This defines the type of symbols to be used to plot the points in all subsequent calls to GRAF1. If not called, it defaults to ISYM=1. .LEFT MARGIN 10 .P -10 ISYM#>#0##the colour defined by ISYM will be used to draw lines between individual points. The default is 1, i.e. a black pen. See the notes in the next section under NEWPEN for a discussion of pen colours. Generally ISYM will be in the range 1-4. Note that if ISYM is positive, lines will be drawn between points, and so one of the variables must be monotonic to prevent retrace. .P -10 -65#<#ISYM#<#0 use pen colour abs(ISYM), but only put a dot at each point. .P -10 ISYM#<#-64#use special symbols at each point, as follows. Square, delta, circle, diamond, del, plus, times, star, correspond to -65 to -72 respectively. See the paragraph on SYMBOL below for the available symbols and codes. .P -10 ISYM#>#64#use special symbols as above, but also connect the points with a line. .LEFT MARGIN 0 .HL 3 GRLOG (LX, LY) .P 5 This sets the x and/or y axes as logarithmic in all future calls to GRAF1, if LX or LY are set to 1. If the value is 0, the corresponding axis will be linear. The default is linear axes. .HL 3 GRNOGR This causes the next call to GRAF1 to be produced without any grid at all. Only the data points will be plotted. This is used when it is desired to overplot the previous graph. .HL 3 GRLSCA This causes the next call to GRAF1 to use the scale used on the previous graph. This can be used in conjunction with GRNOGR to plot several curves on the same scale. Otherwise each new call to GRAF1 will result in a new scale being chosen depending on the range of the data. .HL 3 GRNOHA, GRYEHA These control the drawing of lines across the graph axes. GRNOHA says to draw small tick marks around the edge of the graph, GRYEHA says draw lines right across the graph at major tick marks. The default is small ticks. .HL 3 GRNOTK, GRYETK These control the drawing of tick marks between the major tick marks around the edge of the graph. GRYETK says to draw 10 minor ticks between the major ones. GRNOTK says do not draw minor ticks. .HL 3 GRSSCA (X0, X1, DX, Y0, Y1, DY) This causes the next call to GRAF1 to use the specified scale values rather than choosing its own. These values are in the user's units. For linear scales, X0 is the x value which will be plotted on the left side of the graph, X1 on the right side. DX is the spacing between grid lines and labels, again in the user units. For example, if one wished to plot the next graph from -5 to 15 marked every 2.5 in X, and from 0 to 500 marked every 100 in Y: CALL GRSSCA (-5.0, 15.0, 2.5, 0.0, 500.0, 100.0) For logarithmic scales, it uses the log base ten of the range of values, and DX=1 always; for example, a log scale from 1E3 to 1E6 is given as X0=3, X1=6, DX=1. .HL 3 GRGSCA (X0, X1, DX, Y0, Y1, DY) This retrieves the scale values used by the previous call to GRAF1. See GRSSCA above for a description of the values. This is useful for plotting several curves on the same graph. .HL 3 GRGPAR (IPENS, HITES) This subroutine gets the parameters used by the graphing routines, such as pen colours and symbols heights for various parts of the graphs. The arguments must be dimensioned as IPENS(10) and HITES(10). The returned values correspond to the pen number and character height in inches used for the following components: .LITERAL (1) Main title (2) X and Y axis titles (3) Numbers on the axes (4) Plotting symbols, e.g. triangles and diamonds (5) Date (6) Major tick marks (HITE is length of ticks) (7) Minor tick marks (HITE is length of ticks) (8) Frame (HITE is width of line using 3 strokes) (9) Curves (HITE is ignored; overridden by GRSYM and GRAF2) .END LITERAL .HL 3 GRSPAR (IPEN, HITE) This changes the parameters used to plot various components of the graph. See the description of GRGPAR above for an explanation of what the values correspond to. Generally one calls GRGPAR first to load the default values into the arrays, then changes the ones desired and then calls GRSPAR to affect the changes. .HL 2 MISCELLANEOUS ROUTINES .HL 3 GRLOC (XP, YP, XUSER, YUSER) This converts the user coordinates XUSER and YUSER to plotter coordinates XP and YP in inches, using the scale from the last call to GRAF1 or GRAF2. This is useful for locating points on the graph for placing labels on points. .HL 3 GRSPLI (XOUT, YOUT, NOUT, XOUT0, XOUT1, XIN, YIN, NIN, WORK) This routine takes a set of points XIN,YIN, and generates a smooth curve which passes through all the points, by means of fitting piecewise cubic splines to the points. This routine is useful in putting a smooth curve through a small number of points which are relatively smooth, such as calculated points along a theoretical curve. It does not look very good with a lot of points if there is a lot of scatter, since it will put the curve through all the points, unlike least-squares curve fitting. The curve can then be plotted by any of the usual graphing routines, such as GRAF1. It is capable of extrapolating outside the range of the data, but since it uses cubic fits, they generally curve a lot more than you would wish. Also the slope at the endpoints is a free variable, and so the ends of the curve may not be as you wish. If this is the case, give an extra pair of endpoints which go the way you want. The input parameters XIN,YIN are the coordinates of the points which define the curve, and NIN is the number of such points. NIN must be at least 4. XOUT,YOUT are arrays dimensioned to at least NOUT which will contain the coordinates of the smooth curve. XOUT0 and XOUT1 are the minimum and maximum value for x which will be calculated. XOUT will contain NOUT equally spaced values from XOUT0 to XOUT1, and YOUT will contain the corresponding y values. As mentioned above, there need not be any relationship between XOUT0,XOUT1 and the values in XIN, but it is preferrable that they lie inside the range of XIN. WORK is a work array which must be provided for calculating coefficients, and it must be dimensioned to at least 3*NIN. The array XIN must increase from left to right. .HL 3 GRDSHL (X, Y, IPEN, ITYPE, THICK) This routine is like the primitive plotting routine PLOT in that it draws lines, and in fact the first three arguments are the same as PLOT's. However it is capable of drawing various types of dashed and dotted lines of arbitrary thickness. X and Y are the coordinates in inches of the point to move to. If IPEN=3 the pen is raised before the move, but if IPEN=2 the pen is lowered and a line is drawn from the current point to X,Y. ITYPE is an integer which determines the line type. THICK is the thickness of the line in inches; usually 0.1 to 0.15 looks good. The dashes in the line will be continuous no matter how small the increments in X and Y are between calls, until the pen is raised at which time it starts again at the beginning of the dash. The available line types are as follows. .LITERAL ITYPE Line Type 0 No line 1 Solid line 2 Short dashes 3 Long and short dashes 4 Long dashes 5 1 long and 2 short dashes 6 Dots 7 1 long and 3 short dashes 8 2 long and 1 short dash 9 2 long and 2 short dashes 10 2 long and 3 short dashes .END LITERAL .HL 3 GRSCAL (X, Y, NPTS, X0, X1, DX, Y0, Y1, DY) This scans through the array of points (X,Y), which have NPTS elements, and chooses a nice set of scale values. This routine is called automatically by GRAF1, but may find other uses. .PAGE .HL 1 MORE SAMPLE PROGRAMS Here are more sample Fortran programs using the graphing routines. .LITERAL C THIS GENERATES A SAMPLE GRAPH USING GRAF. C IT DEMONSTRATES HOW TO OVERPLOT ON THE SAME GRAPH. C REAL X(100), Y(100) DO 10 J=1,100 X(J) = J-1 Y(J) = SIN(X(J)/5.0) * EXP(-X(J)/30.0) 10 CONTINUE C C DRAW THE CURVE USING THE DEFAULT BLACK LINE C CALL GRAF1 (X, Y, 100) CALL GRTITL ('Sample 2', 100, 'X axis label', 100, 1 'Y axis label', 100) C C NOW OVERPLOT WITH SYMBOLS C CALL GRNOGR !DON'T REDRAW GRID CALL GRLSCA !USE LAST SET OF SCALE VALUES (DON'T AUTOSCALE NEW) CALL GRSYM (-65)!USE SYMBOLS AT EACH DATA POINT CALL GRAF1 (X, Y, 100) !REPLOT POINTS CALL GRDATE CALL EXIT END .END LITERAL .SKIP 5 .LITERAL C THIS DEMONSTRATES THE USE OF GRAF2, BY PLOTTING C SEVERAL GRAPHS ON THE SAMPLE PLOT FRAME. C REAL X(100), Y(100) DO 10 J=1,100 X(J) = J Y(J) = SIN(X(J)/5.0) * EXP(-X(J)/30.0) + 1.0 10 CONTINUE C C DRAW THE CURVE, WITH AUTOSCALED AXES. C CALL GRYETK !DRAW MINOR TICK MARKS CALL GRAF2 (X, Y, 100, 2, 1, 1, 5661, 1 'Sample 4 - lin/lin', 'X axis', 'Y axis') C C DRAW ANOTHER CURVE BESIDE PREVIOUS ONE C CALL GRAF2 (X, Y, 100, 3, 1, 4, 9981, 1 'Sample 4 - log/log', 'X axis', 'Y axis') CALL EXIT END .END LITERAL .HL 1 PLOTTER PRIMITIVE ROUTINES These are the routines which enable plotting to be done independently of the actual plotting device used. It is recommended that all programs use these routines rather than the device specific ones if possible. The hypothetical plotting device has a horizontal dimension of 12 inches and a vertical dimension of 10 inches. All plotting is done in these units. The actual size may be scaled to fit the real plotter. The device is chosen at task build time by selecting the appropriate library. See the previous section. Slight differences in the actions of the routines are noted below. Calls to these subroutines may be mixed with the higher level routines described in the previous section. For example, SYMBOL may be used to annotate graphs that have just been drawn. It is advisable to do so after the call to GRAF1, and before a call to either GRTITL or GRDATE. If you use these routines after all such calls on a particular graph, you must call PLOTF to flush the buffer; GRTITL and GRDATE do this for you. .HL 2 PLOTS This must be called before any other plotting routine. It initializes both the software and the plotter device. It may be called repeatedly in the program if PLOTF is called in between. On terminals, it asks the user to hit the return key and then clears the screen. On the HP plotter, it asks the user for a scaling factor and a plotting speed. At this point the paper is loaded. The scale factor defaults to 0.75, which reduces the 12 by 10 logical plotting surface to fit onto 11 by 8.5 inch paper. The plotting speed defaults to 36 cm/s, but may be slowed down for final copies. Generally calls to to PLOTS and PLOTF will bracket every page plotted. .HL 2 PLOTF This must be called at the end of every plotting session. It empties the internal buffers and waits for transmission to finish. It may also be called part way through the program. .HL 2 PLOT .C;PLOT (X, Y, IPEN) This is the basic plotting routine. It causes the pen (or beam) to move to location (X,Y), where X and Y are measured in inches from the current origin. The value of IPEN determines whether a line is drawn on the way. .LITERAL IPEN = 3 => raise the pen before movement. IPEN = 2 => lower the pen before movement. IPEN = 1 => no change in pen status. IPEN < 0 => same effect as abs(IPEN), but causes the destination to become the new origin. .END LITERAL PLOTS sets the origin initially to the lower left corner. .HL 2 SYMBOL .C;SYMBOL (X, Y, HEIGHT, TEXT, ANGLE, NCHARS) This causes the NCHARS characters in TEXT to be written starting at location (X,Y) in inches from the current origin. ANGLE is the angle in degrees counterclockwise from the positive X axis that the characters are to be plotted at. HEIGHT is the character height in inches. If TEXT is a quoted string, NCHARS may be set to a large number and the length is determined automatically. If the program is taskbuilt with a plotting library which outputs directly to a plotting device, SYMBOL will use the hardware character generator. On certain devices this will look funny since characters will not be rotated correctly. However software character sets may be used to overcome this. Plots produced by PLOTxx automatically use the software character sets. If NCHARS=-1 or -2, the decimal value of TEXT(1) is used to select a special plotting symbol which is centered at X,Y. If NCHARS=-2 a line is drawn from the previous point to the current one, otherwise no line is drawn between symbols. For TEXT(1), one may use either an integer or a quoted ascii character. E.g., CALL SYMBOL (x, y, 0.15, 66, 0.0, -1), where 66 could be replaced with 'B'. The symbols available are: .LITERAL Int Code Ascii Symbol Int Code Ascii Symbol -------- ----- ------ -------- ----- ------------ 65 or -65 A square 97 or -97 a solid square 66 or -66 B delta 98 or -98 b solid delta 67 or -67 C circle 99 or -99 c solid circle 68 or -68 D diamond 100 or -100 d solid diamond 69 or -69 E del 101 or -101 e solid del 70 or -70 F plus 71 or -71 G times 72 or -72 H star .END LITERAL With the hardware character set, only the lefthand column is available; solid symbols are drawn as their open counterparts. The software character set includes the right hand column of solid symbols, and draws them a bit better. Again, PLOTxx uses the full set. The character string to be written may include certain control characters which affect the size and position of the characters. These control characters consist of a dollar sign ($) followed by one or two other characters, as shown below. .LITERAL $A Shift up to above division line. $B Shift down to below divison line. $C Advance to the next line, single spacing. $D Shift down to first level subscript. $E Shift up to exponent level (smaller than superscript). $G Change to GREEK character set for next character only. $H Advance to next line, one and a Half spacing. $I Shift down to index level (smaller than subscript). $J Jump back to last level command position. $L Shift down to second level subscript. $M Change to Math character set. $N Shift to normal level. $R Restore position. $S Save position. $T Advance to next line, double spacing. $U Shift up to superscript level. $V Generate a vector/mean value bar between occurences, ($V...$V). $W Change to script character set. $X Return to entry character set. $ Generates a half-space. $n Change to character set n, n=3,4,...,29. $. Generate a "Bullet". $* Generate a five pointed star "Bullet". $/ Generate a division line between occurences, ($/...$/). $\ End of text. $- Underline between occurences, ("$-...$-"). $= Double underline between occurences, ("$=...$="). $$ $ { Shift up to exponent level, like $I, or back to normal if after }. } Shift down to index level, like $I, or back to normal if after {. .END LITERAL For example, "W/cm{2} $Gx{0}". If switched to character set 9, the program will switch back to the entry character set after any character is referenced, i.e. to get an integral sign from character set 9 and then return to the entry character set, you need only type: $9I not $9I$X. The same is true for $G. To select a different character set, use $n, where n is the one or two digit code of the character set. Below is a list of the character sets available. The default is 3, but this may be changed on the PLOTxx command line in the third parameter, usually to the duplex set 5, e.g. PLOTHP plot.plt,,5. If this is done, then $G also selects the complex Greek set. .LITERAL 3 Simplex Roman 4 Simplex Greek 5 Duplex Roman 6 Complex Roman 7 Complex Greek 8 Complex Italic 9 Math and special characters ($M) 10 Math and special characters 11 Gothic English 12 Simplex Script ($W) 13 Complex Script 14 Gothic Italian 15 Gothic German 16 Cyrillic 17 Triplex Roman 18 Triplex Italic 20 Miscellaneous characters. .END LITERAL .HL 2 SYMBOC .C;SYMBOC (X, Y, HEIGHT, TEXT, ANGLE, NCHARS, ICENTR) This is identical to SYMBOL above, except for the new last argument ICENTR, which determines how the text is to be centered. For ICENTR=-1, the text is left justified at X,Y; for ICENTR=0 it is centered on X,Y; for ICENTR=1 it is right justified at X,Y. The bottom of the line of text always touchs X,Y, regardless of angle. Note that with the software character set, using multiple lines in a single call, all the lines will be justified individually. .HL 2 NUMBER .C;NUMBER (X, Y, HEIGHT, FNUM, ANGLE, NDEC) This causes the floating point number FNUM to be written starting at location (X,Y) in inches from the current origin, with HEIGHT in inches, and at ANGLE degrees counterclockwise from the positive X axis. NDEC is the number of digits after the decimal point. If NDEC=-1, it will be written as an integer. Otherwise it will be either in F or E format, depending on the value of the number. .HL 2 NEWPEN .C;NEWPEN (IPEN) This is used with output devices which are capable of drawing in more than one colour. If a monochrome device is used, it will ignore the choice of pen. It causes subsequent lines or characters to be drawn using pen number IPEN. IPEN may vary from 0 to 4 for the HP plotter, and from 0 to 255 for the Norpak. However for the Norpak, the lookup table is not set for colours higher than 4; this may be done by NPLLT, which has no effect on the HP plotter. Note that the pen is not actually changed until an attempt is made to draw with it, to reduce unnecessary pen motion. The supplied colours are: .LITERAL IPEN = 0 => put away current pen. IPEN = 1 => black pen (white on Norpak) IPEN = 2 => red pen IPEN = 3 => green pen IPEN = 4 => blue pen .END LITERAL Numbers higher than 4 give a blue pen on the HP, and give whatever the lookup table has been set to on the Norpak. This has no effect on monochrome devices. .HL 2 PLOTNM (filenm, icode) This is an optional routine which is ignored by all library versions except PFLIB. It is used to give a name to the output plot file through the ASCIZ string FILENM. ICODE is not used at this time, and should be coded with a zero. If this routine is called before the first call to PLOTS, PLOTS will not prompt the user for the name of the plot file. Note that the filename extension .PLT should be included in the filename given. This is useful in programs which know the name of the plotfile already, such as names derived from another known filename. .HL 2 SOFTWARE CHARACTER SET The PLOTxx commands which plot from plotfiles use large tables of pen strokes to generate the characters used to draw text via the SYMBOL routine. These tables require a lot of memory; to keep task size down for interactive tasks which use the device-specific libraries, such as TKLIB, these libraries will instead use the hardware character set available on the output device itself. However if better quality interactive characters are desired, an intermediate software character set is available, which does not support Greek or fancy lettering. This is loaded by including the file SF:[5,3]SWCHAR.OBS as an object file: .C;BUILD (progname,SF:[5,3]SWCHAR.OBS),$xxLIB Since the PLOTxx commands always use the software character set, it is not necessary to specify SWCHAR if you build with $PFLIB. .HL 1 VT55 VIDEO TERMINAL Because the VT55 terminals have limited capabilities, they are not treated as generalized plotting devices and so cannot use the general routines described above. A subroutine PLOT55 is provided by DEC to handle the graphic features of the VT55. Two high level routines are provided in VT55LIB for graphing simple functions on the VT55. To build a program using these routines, specify $VT55LIB as a library. .HL 2 GRAPH1 .C;GRAPH1 (X, Y, NPTS) This plots a graph of a single function of Y versus X, tabulated in the vectors X and Y. The scale factors are chosen automatically and the axes are labelled. The X values must be monotonic since multiple valued functions cannot be displayed. NPTS is the number of (X,Y) points to be plotted. .HL 2 GRAPH2 .C;GRAPH2 (X1, Y1, NPTS1, X2, Y2, NPTS2) This plots a graph of two independent functions. Otherwise it is similar to GRAPH1. .HL 2 TITLE1 .C;TITLE1 (LINE, NCHARS) This writes a title at the top of a graph created by GRAPH1 or GRAPH2. The title is a character string in LINE, of length NCHARS. If LINE is a quoted string, NCHARS may be set to a large number. .HL 1 DRAWGRAPH UTILITY We have a utility program called DRAWGRAPH or DRAW for short which makes use of the graphing routines described in the first section of this chapter. Rather than calling GRAF1 from inside a Fortran program which you have written, you construct a file of special instructions for DRAW which then draws the graph(s) into a plotfile. This is used for generating view-graphs for conferences and for publications. It gives a bit more control over the more detailed aspects of a plot, such as symbol size and pen selection. The input file should have extension FIG, such as VUGRAF.FIG. Each line of the file should start with a verb, some of which are shown below. The verb may be followed by some optional numbers, separated by spaces or commas, e.g. SYMBOL-HEIGHT 0.2. The verbs must be given exactly, although upper and lower case are ignored. There are a number of parameter setting verbs, then some plotting verbs (PLOT and OVERPLOT) which put everything together into a graph. To specify the coordinates of the data points to be plotted, they should be in a file with default extension DAT, each x-y pair on their own line with free format. This filename is then given with the PLOT or OVERPLOT command. The data points may also be included in the FIG file after the PLOT command if no filename is given; the data are then terminated by an END verb. It is preferable to draw first the data points which are plotted with symbols, then to plot the curves on top, because the program will endeavour not to draw a curve on top of a symbol already there. It can remember the location of a reasonable number of symbols. To run, just enter DRAW figname, and it will then make the graph(s). The plotfile may be plotted in the usual way, e.g., PLOTHP myplot. The command line may also contain more arguments, each separated by spaces or commas. The first one, the name of the input file which contains the directives, is required; it will be given default extension .FIG if not already there. The second argument is optional, and may be the name of the plot file to create; if not given, it will be asked for. .C;DRAW input_filename plot_filename P1 P2 ... P9 The rest of the command line is optional, and may contain from one to nine more arguments. These will be substituted for all occurrences of the string %n% in each directive line read, where n=1-9 is the number corresponding to which argument is desired. %1% corresponds to the first such argument, the third one on the command line. .HL 2 Verbs Used before the Graph is Drawn First, some comments on setting scales. If you do not specify any scales, the program will choose a nice set of scales from the range of the data. However you may want to override this mechanism, e.g. if the x-axis is degrees from 0 to 180, you may want the axis labelled at 0, 30, 60, 90, 120, 150, and 180, rather than the default 0, 50, 100, 150, 200. You may use X-SCALE and Y-SCALE to do this (or equivalently X-FIRST, X-LAST, X-INC, etc.) If you want part of the axis not to be labelled or for the first tick mark to start at some arbitrary location from the corner, then you can specify the values at the four corners using X-SPAN and Y-SPAN (or equivalently X-LEFT etc.). If these are not given then the corners correspond to the values set by X-SCALE and Y-SCALE. You can mix up defaults and overrides together; the program tries to determine what you want. The following are parameter setting commands, and must be given before the PLOT command. Their values stay in effect until changed. X-LEFT, X-RIGHT, Y-BOTTOM, Y-TOP set the range of the graph in user's units. For log scales, these values are the log base 10 of the values, e.g. 1E-5 is set as -5. Default values are chosen from the range of the data. X-FIRST, X-LAST, Y-FIRST, Y-LAST, X-INC, Y-INC set the values at which the major tick marks and numbers are written on the axes. For log scales, these are the log base 10 of the value, and the increments must be set to 1. Default values are chosen from the range of the data. X-SCALE, Y-SCALE have three parameters, corresponding to x-first, x-last, x-inc described in the previous paragraph. This is an equivalent way of setting the scales, but all 3 values must be given or will be set to zero. X-SPAN, Y-SPAN have two parameters, corresponding to x-left, xright etc. above. Both must be given if this command is used. X-LINEAR, X-LOG, Y-LINEAR, Y-LOG set the axes as either linear or logarithmic. Default is linear. LEFT-EDGE, RIGHT-EDGE, BOTTOM-EDGE, TOP-EDGE set the location of the corners of the graph frame on the plotting page. These are in inches on a 12 by 10 inch page. You must also leave room below and to the left for axis labels. Default is 2, 10, 2, 8.75 inches. LINE-TYPE specifies the type of line that is to be drawn between data points. It takes three parameters: the line type code (1-9, see writeup for GRTHKL), the line thickness in inches, and the pen number to use. The defaults are 1 (solid line), 0.08, 1. SYMBOL says that symbols are to be drawn at every data point, and selects the symbol to be used. See writeup for GRSYM subroutine. Parameter is in the range -65 to -72. (SYMBOL-PEN sets colour). The default is to draw a line between points (see LINE-TYPE), but the default for symbol's parameter is -66. SPLINE says that the next PLOT or OVERPLOT is to be fitted with a smooth curve which is generated by fitting piecewise cubic splines to the data points. This works best with a small number of data points since the curve passes through every point. The two parameters give the left and right x-values between which to draw the curve. If not given, the curve will be drawn between the first and last points. The x curve must go from left to right monotonically. X-FACTOR, Y-FACTOR give the scaling factors to transform the data points. These commands take two parameters, A and B, and the corresponding coordinate is transformed according to X' = AX + B. This stays in effect until a RESET or another X-FACTOR command. The default transformation is 1, 0. MAIN-TITLE, X-TITLE, Y-TITLE will print the rest of the line at the corresponding position on the graph. PUBLICATION sets a number of parameters suitable for graphs in publications. The characters are such that they will reduce to 2 mm in a 3.125 inch column. The pen for the main title is 2, so it may be used for notations when doing drafts; for the final copy, remove pen 2 from the plotter. VIEWGRAPH sets a number of parameters suitable for making viewgraphs. TICKS / NO-TICKS controls the minor tick marks. Default is ticks. GRID-LINES / NO-GRID-LINES controls the drawing of grid lines right across the plot. Default is no, just larger ticks. DATE / NO-DATE controls printing date in lower right corner. Default is no date. DECIMALS-X, DECIMALS-Y specifies the number of digits after the decimal point to use when putting numbers on the axes. This overrides the automatic mechanism which occasionally gets mixed up when scales are overridden. A positive value gives that many decimal places, a negative value specifies E format. MAIN-TITLE-HEIGHT, AXIS-TITLE-HEIGHT, DATE-HEIGHT, NOTE-HEIGHT, set the height in inches of the characters of these labels. Default 0.22, 0.22, 0.1, 0.22 inches. NUMERAL-HEIGHT sets the height of the numbers which label the axis values. Default is 0.16 inches. SYMBOL-HEIGHT sets the size of the plotting symbols. Default is 0.22 inches. MAJOR-TICK-LENGTH, MINOR-TICK-LENGTH sets the length of the ticks around the graph. Defaults are 0.25, 0.1 inches. FRAME-THICKNESS sets the width of the frame, which is drawn with three passes of the pen, each separated by this distance. Default is 0.012 inches. MAIN-TITLE-PEN, AXIS-TITLE-PEN, NUMERAL-PEN, DATE-PEN, SYMBOL-PEN, MAJOR-TICK-PEN, MINOR-TICK-PEN, FRAME-PEN, NOTE-PEN, select the pen colours for the corresponding parts of the graph. Values are in range 1-4 for HP plotter. Default 1. NOTE-ANGLE is the angle of the notes in degrees counterclockwise from the x axis. Default 0. COMMENT is used to denote a comment line and is ignored. RESET will reset the scales and attributes back to their default values. It does not affect character height or pen choices. .HL 2 Verbs to Draw the Graph The following commands generate the graph, so all parameter setting commands should have been given. However parameters may be changed before OVERPLOTS to change scales and plot characters, etc. PLOT filename will cause the named file to be read for xy pairs, then the graph is plotted using the parameters set up to that point. If filename is not given, the points are read from the following lines up to an END directive. OVERPLOT filename is the same as PLOT, except that the curve is plotted on top of the existing one. No axes or labels are drawn. .HL 2 Verbs after the Graph is Drawn These commands should come after the PLOT command, and may come before or after OVERPLOTs. NOTE x,y text and NOTE-UU x,y text will plot the text onto the graph. X and y are the coordinates for the lower left point of the text; for NOTE the coordinates are in inches, for NOTE-UU they are in the current user units. These must be used AFTER the PLOT command since scales are not set until the first PLOT. NOTE-CENTER, NOTE-RIGHT will center or right-justify the next note only, then NOTE will revert to left-justifying the text. See also NOTE-ANGLE. .HL 2 Sample DRAWGRAPH Input File Below is a sample of an input file to DRAWGRAPH which is used to draw a figure for a publication. The filename is DRAWSAMPL.FIG, and the plotfile is created by entering DRAW DRAWSAMPL. It first draws three sets of data points using symbols, then draws smooth splined curves through them. Note that the curves jump over the symbols. Finally three labels are written on the left to identify the curves. .LITERAL Contents of file DRAWSAMPL.FIG: PUBLICATION Main-title 3/2 $Gx Fig 8 X-title Wavelength ($Glm) Y-title 3/2 $Gx}0{ Intensity Comment Change some parameters to suit this narrow graph NO-ticks no-y-axis Numeral-height 0.2 Symbol-height 0.15 frame-thickness 0.01 left-edge 2 right-edge 7 top-edge 9 bottom-edge 1 Comment Set the scales x-scale 7.05, 7.1, 0.05 x-span 7.005, 7.13 y-bottom 0 y-top 10.5 Comment Plot the data with symbos first symbol -65 plot DRAWSAMP1.dat symbol -66 overplot DRAWSAMP2.dat symbol -68 overplot DRAWSAMP3.dat Comment Plot smooth curves through the points Line-type 1 0.05 spline overplot DRAWSAMP1.dat Line-type 2 spline overplot DRAWSAMP2.dat Line-type 3 spline overplot DRAWSAMP3.dat Comment Label the curves note-uu 7.01 1.5 30{o} note-uu 7.01 4.5 100{o} note-uu 7.01 7.5 150{o} .END LITERAL The program will read from three data files, DRAWSAMPn.DAT. Those should contain a number of lines with two numbers per line in any format, corresponding to the x-y coordinates of each point in any units. These numbers could also have been included after the PLOT or OVERPLOT verb in the DRAWSAMPL.FIG file, with an END verb after the last line. .LITERAL Contents of file DRAWSAMP1.DAT 7.0415E+00 6.3978E-01 7.0532E+00 3.6926E+00 7.0626E+00 2.3157E+00 7.0706E+00 2.4131E+00 7.0786E+00 3.3936E+00 7.0860E+00 2.8999E+00 7.0947E+00 5.8414E-01 7.1026E+00 1.8428E+00 7.1106E+00 2.3435E+00 7.1188E+00 5.5633E-01 .END LITERAL