There is 1 other file named apman.mem in the archive. Click here to see a list.

Programming Note 25/2 Page 1 EASY GRAPH PLOTTING ------------------- Rob Cook Computer Centre La Trobe University 21-Jun-77 CONTENTS -------- 1.0 FUNCTION 2 2.0 ATOPLT SUBROUTINES AND CALLING SEQUENCES 3 2.1 Plotting a Single Graph 3 2.2 Plotting Up to 14 Sets of Data on the Same Graph 5 2.3 Changing Plotting Parameters 7 2.4 Obtaining Values of Plotting Parameters 7 2.5 Plotting the Tick Values as Character Strings 10 2.6 Plotting Logarithms of Data 12 2.7 Plotting Least Squares Lines 13 2.8 To Plot One Graph and a Least Squares Line 13 2.9 Plotting the Tick Values as Integers 15 2.10 Fixing the Tick Value Increment 16 2.11 Fixing One Tick Value 17 2.12 Fixing the Origin and Windowing 18 2.13 Even Simpler Graph Plotting 19 3.0 USAGE 20 3.1 Gould Plotter 20 3.2 Tektronix 4012 20 3.3 Internal Details 20 3.4 Error Messages 21 APPENDIX A - ATOPLT Variable Parameters A-1 APPENDIX B - Centring Symbols B-1

Programming Note 25/2 Page 2 1.0 FUNCTION Two FORTRAN subroutines ONEPLT and ATOPLT allow a programmer to plot graphs of one set of data against another using only one subroutine call. Either the Gould plotter or the Tektronix 4012 terminal can be used. ONEPLT draws one graph, plotting corresponding values from X and Y arrays and representing each point by a symbol. The points may optionally be joined by straight lines. The graph is drawn in a standard sized box with a title along the top edge. The data will be scaled so that the graph fits neatly into the box, or the user may specify the scaling. Tick marks are drawn along each edge and scale values are written at every second tick along the axes. The axes are titled, and if necessary the title will include an exponent multiplier for the tick values. ATOPLT will super-impose up to 14 graphs on the one plot. The data points are represented by different symbols which can be selected by the programmer. All the points will be scaled to a single overall scale to fit into the standard box. Ranges of data for various graphs should therefore be compatible. The points of each graph may optionally be joined by straight lines. The form of the plot is the same as for ONEPLT, except that ATOPLT adds a notes box to the right of the graph. The notes box contains an explanation for each symbol. A third subroutine, ATOPRM, allows the programmer to change the values of parameters used by ONEPLT and ATOPLT in drawing the plot, if the defaults are unsuitable. The parameters whose values may be changed, and their default values, are detailed in Appendix A. Other routines allow the plotting of the logarithms of data values, plot text as tick labels instead of numbers and draw least squares lines. A data set is defined, for the purposes of this document, as a set of ordered co-ordinate pairs (X,Y) which will, when plotted, be identified by the same centred symbol. Different sets are represented by different symbols.

Programming Note 25/2 Page 3 2.0 ATOPLT SUBROUTINES AND CALLING SEQUENCES 2.1 Plotting a Single Graph CALL ONEPLT(X,Y,N,XTTL,NX,YTTL,NY,HTTL,NH) X a real array containing the X data. Y a real array containing the Y data. N the number of elements in X and Y. XTTL either a literal or an array containing the X axis title. NX the number of characters in XTTL. If NX is negative the symbols plotted at the data points are joined by straight line segments. The maximum is about 50 characters. YTTL either a literal or an array containing the Y axis title. NY the number of characters in YTTL. If NY is negative no symbols will be drawn and the data points will be joined by straight lines. The maximum is about 30 characters. HTTL either a literal or an array containing the graph title. NH the number of characters in HTTL. The maximum is about 50 characters.

Programming Note 25/2 Page 4 C Example 1 C REAL A(8), B(8) DATA A /3.45, 2.67, 1.32, 4.44, 2.34, 8.00, 9.04,11.23/ DATA B /2.33, 4.36, 2.84, 1.23, 4.65, 7.01,11.35,15.24/ C CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 1',9) END C Example 2 C REAL X(100), Y(100) C DO 100 I = 1, 100 X(I) = I / 2.0 Y(I) = SIN(X(I)) - X(I) 100 CONTINUE CALL ONEPLT(X,Y,100,'X data',-6,'Y data',6,'Example 2',9) END

Programming Note 25/2 Page 5 2.2 Plotting Up To 14 Sets Of Data On The Same Graph The data arrays X and Y contain the values for up to 14 data sets. The data sets are distinguished by introducing a third array, ISYM, of the same size. Each element of ISYM is an integer (1 to 14) which indicates the data set to which the corresponding elements of X and Y belong. For example if ISYM(3), ISYM(6), and ISYM(14) contains the value 3 then the points (X(3),Y(3)), (X(6),Y(6)), (X(14),Y(14)), belong to the same data set. The value of an element of ISYM also has a unique correspondence with a symbol (see table of symbols in Appendix B), and that symbol is used to plot all points in a particular data set. For the example above, points (X(3), Y(3)), (X(6), Y(6)) and (X(14), Y(14)) will be represented by the symbol in the table corresponding to integer 3. This method allows the programmer to fill X and Y arrays in any order he wishes, provided that he fills the ISYM array in the same order. If any element of ISYM is negative the data point corresponding to that element will be joined to the previous data point of the same data set by a straight line. Each data set can be identified by a title written in the notes box. The titles are specified in the rows of the NOTES array, one title per symbol used. The titles may each be up to 20 characters long, drawn in two lines of ten characters each. The note contained in the elements (1,1), (1,2), (1,3), (1,4), of the array NOTES are associated with the data set represented by the lowest absolute valued symbol. (2,1), (2,2), are associated with the second lowest valued symbol and so on. The argument values are not altered by ATOPLT. CALL ATOPLT (X,Y,ISYM,N,XTTL,NX,YTTL,NY,HTTL,NH,NOTES,NN) X a real array containing X values for all the data sets. Y a real array containing Y values for all the data sets. ISYM an integer array containing values in the range -14 to -1 and 1 to 14. Each element specifies the symbol to be drawn for the corresponding (X,Y) point. Any other values in the array will cause the corresponding data point to be ignored and a warning message typed. N the number of elements in X,Y and ISYM. XTTL either a literal or an array containing the X axis title. NX the number of characters in XTTL. The maximum is about 60 characters. YTTL either a literal or an array containing the Y axis title. NY the number of characters in YTTL. The maximum is about 30 characters. HTTL either a literal or an array containing the graph heading. NH the number of characters in HTTL. The maximum is about 60 characters. NOTES an NN by 4 array containing the notes to be drawn in the note box. NN the number of notes in XNOTES need not be the same as the number of symbols used, in which case, the first NN symbols will be 'noted' and extra notes will be ignored.

Programming Note 25/2 Page 6 C Example 3 C REAL X(200), Y(200) INTEGER ISYM(200), NOTES(2,4) C DATA ISYM/100*1,100*-14/ DATA (NOTES(1,I),I=1,3)/'Y=Sin(X) and'/ DATA (NOTES(2,I),I=1,2)/'Y=Cos(X)'/ C DO 100 I = 1, 100 X(I) = I / 10.0 X(I+100) = X(I) Y(I) = SIN(X(I)) Y(I+100) = COS(X(I)) 100 CONTINUE CALL ATOPLT(X,Y,ISYM,200,'X data',6,'Y data',6, * 'Example 3',9,NOTES,2) END

Programming Note 25/2 Page 7 2.3 Changing Plotting Parameters There are 45 parameters in ONEPLT and ATOPLT which may be set by the user to vary the way the graph is plotted. This gives the user with special requirements considerable flexibility to change the size, shape and details of the graph produced. The changeable parameters are numbered 1 to 45 (see Appendix A for definitions and default values). Default values are changed by a call to the routine ATOPRM which identifies the parameters to be altered and supplies new values. A new value for any parameter remains in effect for all subsequent calls of ATOPLT and ONEPLT. CALL ATOPRM(N,IP,XP) N the number of elements in IP and XP (i.e. the number of parameters to be changed), limit 45. IP an integer array containing the integer codes corresponding to the parameters to be changed. XP a real array containing the new values of the parameters. The new values must correspond in order with the identifying integers in array IP. 2.4 Obtaining The Values Of ATOPLT Parameters The current settings of the ATOPLT parameters can be read by calling the ATOGET subroutine. You will need to read the values if you want to change them by ATOPRM and set them back to their original values later, or if you are writing programs to work on different plotters whose parameters may differ. CALL ATOGET(N,IP,XP) N number of parameters to be read IP an integer array containing the integer values corresponding to the parameters to be read XP a real array that receives the current values of the parameters

Programming Note 25/2 Page 8 EXAMPLE of use of ATOPRM to produce an overall grid in a graph box. DIMENSION IP(4), XP(4) C DATA IP, XP /7, 26, 27, 8, 220.0, 280.0, -2.0, 0.0/ C CALL ATOPRM(4,IP,XP) CALL ATOPLT(X,Y,ISYM,200,'X data',6,'Y data',6, * 'Example 4',9,NOTES,2) END This will cause the ticks to be made the same size as the axis (7 corresponds to X axis tick size, 26 corresponds to Y axis tick size, both set to default axis length), and half density lines to be drawn, i.e. a half density grid will be drawn over the graph.

Programming Note 25/2 Page 9 The above example depends on the fixed numbers 220.0 and 280.0 as the lengths of the Y and X axes, which is true for the Gould plotter but not for the Tektronix. The ATOGET subroutine could be used to find the actual sizes of the axes, and the program would become independent of plotter and any changes made to the axis length. DIMENSION IP(4), IG(2), XP(4) C DATA IP, XP /7, 26, 27, 8, 220.0, 280.0, -2.0, 0.0/ DATA IG /4, 3/ C CALL ATOGET (2, IG, XP) C CALL ATOPRM (4, IP, XP) CALL ATOPLT(X,Y,ISYM,200,'X data',6,'Y data',6, * 'Example 4',9,NOTES,2) END

Programming Note 25/2 Page 10 2.5 Plotting The Tick Values As Character Strings For some applications it is useful to be able to write a character string at a tick instead of a number. For example, ' Jan ' is more meaningful than '1.0', if you are specifying monthly data. This can be done by calling the subroutine ATOCHL before you call ATOPLT or ONEPLT. In the call to ATOCHL, you specify an array containing the labels to be used at successive ticks. Each label is a maximum of five characters and will be centred on the tick. So that if your label has three characters you should specify it as, e.g. ' Jan '. The first string is drawn at the origin and the strings are plotted at every other tick. Character labels are meaningless unless you fill the values for the ticks, so the ATOCHL call allows the programmer to specify the increment and origin value too. If you provide less labels than there are ticks, ATOPLT will re-use your labels when it runs out. So if you provide ' Jan ' through to ' Dec ' and there are 24 positions, the months will appear twice. Once ATOCHL has been used to set character labelling, it remains in effect for all subsequent calls to ATOPLT and ONEPLT, until a second call to ATOCHL is used to unset character labelling. CALL ATOCHL(IXY,NLAB,TLAB,TINC,ORGV) IXY 1 : set X-axis character labels 2 : set Y-axis character labels -1 : unset X-axis character labels -2 : unset Y-axis character labels NLAB integer number of labels provided; limit 24 TLAB array containing NLAB labels, each occupying one element and given in A5 format. TINC increment in value per tick ORGV value at axis origin.

Programming Note 25/2 Page 11 DIMENSION DAYS(7) C DATA DAYS/' Sun Mon Tue Wed Thu Fri Sat '/ C CALL ATOCHL(1,7,DAYS,0.5,0.0) CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 5',9) END

Programming Note 25/2 Page 12 2.6 Plotting Logarithms Of Data The logarithms of the data can be plotted by calling the subroutine ATOLOG before calling ATOPLT or ONEPLT. ATOLOG merely asks ATOPLT to use logarithms; it does not do any plotting itself. If during subsequent plotting any of the data to be plotted are negative a warning message is typed and the point is ignored. Once ATOLOG has been used to set logarithm plotting, it remains in effect for all subsequent calls to ONEPLT or ATOPLT, until a second call to ATOLOG is used to unset logarithm plotting. CALL ATOLOG(IXY) IXY 1 : set to plot logarithm of X-data 2 : set to plot logarithm of Y-data. -1 : unset to plot logarithm of X-data -2 : unset to plot logarithm of Y-data CALL ATOLOG(1) CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 6',9)

Programming Note 25/2 Page 13 2.7 Plotting Least Squares Lines Users plotting results from experiments may find it useful to add the linear least squares line that fits the data points. Two methods are available. By calling the subroutine ATOLSQ before calling ATOLPT or ONEPLT, the programmer can ask for a least squares line to be fitted to any or all of his data sets. By calling ATOLSP, he can ask for a linear least squares line that passes through a fixed point, for example [0,0]. After calls to ATOLSQ or ATOLSP, least squares lines will be added to plots drawn by all subsequent calls to ATOPLT and ONEPLT until a second call to ATOLSQ or ATOLSP sets the number of least squares lines, N, to zero. CALL ATOLSQ(N,IDS) N number of least squares lines (use 1 for ONEPLT) IDS array containing N data set indicator values (use 1 for ONEPLT) CALL ATOLSP(IDS,XPT,YPT,N) N number of last squares lines. IDS array containing N data set indicator values XPT,YPT arrays of co-ordinates of the fixed points 2.8 To Plot One Graph And A Least Squares Line The ONEPLS subroutine is identical to ONEPLT except that it adds a least squares line to the plot. CALL ONEPLS(X,Y,N,XTTL,NX,YTTL,NY,HTTL,NH)

Programming Note 25/2 Page 14 CALL ATOLSQ(1,1) CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 7',9) or CALL ONEPLS(A,B,8,'X data',6,'Y data',6,'Example 7',9)

Programming Note 25/2 Page 15 2.9 Plotting The Tick Values As Integers Tick values are normally plotted as REALs to 2 decimal places. The programmer can request INTEGER labels by setting the appropriate parameter using ATOPRM: Parameter Value X-axis INTEGER labels 37 1.0 Y-axis INTEGER labels 38 1.0 CALL ATOPRM(1,37,1.0) CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 8',9)

Programming Note 25/2 Page 16 2.10 Fixing The Tick Value Increment ATOPLT examines the data to be plotted and selects values for the origin of each axis and the increment in the value for each tick, so that axes cover the data as closely as possible while still giving 'sensible' numbers at each tick. Although the tick numbers are 'sensible' they may not be what the user requires. One way of getting better results is to specify the increment in value for each tick by a call to ATOPRM. To do this effectively, you need to have some idea of the range of your data and to be aware that ATOPLT writes the tick value on every other tick, starting at the origin. Therefore the ----- specified increment should be half the difference in numbers drawn at the ticks. A tick value of 0.0 means 'not specified'. Parameter X-axis tick value increment 33 Y-axis tick value increment 34 CALL ATOPRM(1,33,0.5) CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 9',9)

Programming Note 25/2 Page 17 2.11 Fixing One Tick Value Continuing on the same theme, to get a neat labelling for an axis may require more than just fixing the increment. For example, fixing the increment at 1.0 may give you labels of 1.13, 2.13, 3.13,..., whereas you would prefer 1.00, 2.00,... To do this you can both fix the increment and insist that a given value appears at one tick along the axis. In this case, you could say that 2.0 is to be a tick value. Two ATOPRM parameters must be used. You must declare that you are fixing a tick value and give the value. Parameter Value X-fix-value-flag 31 1.0 X fixed value 35 value Y-fix-value-flag 32 1.0 Y fixed value 36 value ATOPLT uses your fixed value (and increment if specified) and calculates an origin value and tick spacing so that the whole of your data will fit on to the graph. DIMENSION IP(2), XP(2) DATA IP, XP /31, 35, 1.0, 5.0/ C CALL ATOPRM(2,IP,XP) CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 10',10) END

Programming Note 25/2 Page 18 2.12 Fixing The Origin And Windowing Another alternative is to specify the value at the origin of the axis. ATOPLT will "window" your data, that is, any data values that fall below your origin will not be plotted and lines joining these points to points on the graph will terminate at the graph border. If you specify a value increment as well, you are fixing the values at the end-points of the axis, because the axis contains a fixed number of points (that can be calculated from the axis length and the tick spacing) and data will be windowed at both ends of the axis. Parameter Value X-fix-value-flag 31 2.0 X-origin-value 35 value Y-fix-value-flag 32 2.0 Y-origin-value 36 value DIMENSION IP(2), XP(2) DATA IP, XP /31, 35, 2.0, 3.0/ C CALL ATOPRM(2,IP,XP) CALL ONEPLT(A,B,8,'X data',6,'Y data',6,'Example 11',10) END

Programming Note 25/2 Page 19 2.13 Even Simpler Graph Plotting These subroutines are extremely simple to use, for example, for students without much knowledge of FORTRAN. Standard titles are supplied. Both SIMPLT and SIMPLS plot a graph given the coordinates of the points. SIMPLS adds a least squares line. CALL SIMPLT(X,Y,N) and CALL SIMPLS(X,Y,N) X array containing X coodinates of points Y array containing Y coordinates of points N size of X and Y arrays CALL SIMPLT(A,B,8)

Programming Note 25/2 Page 20 3.0 USAGE 3.1 Gould Plotter There is a library file, PLPLOT.REL, on the PIC: directory containing ATOPLT configured for the Gould plotter. To load or execute a program that calls ATOPLT, use a command of the form: .EXECUTE program, PIC:PLPLOT/SEARCH - In a batch job, add a $INCLUDE card following $FORTRAN cards but before the $DATA or $EXECUTE card: $INCLUDE PIC:PLPLOT/SEARCH Each time a call to ATOPLT is executed a file will be created with a name of the form Q??S1.PLT. All files named *.PLT are queued to the plotter at logout but they can be plotted at any time by using the PLOT command to the monitor. 3.2 Tektronix 4012 The Tektronix terminal must be initialized correctly for graph plotting. If you have any problems use the SET TTY command at monitor level: .SET TTY NO CRLF FORM WIDTH 80 - There is a second library on the PIC: directory containing ATOPLT configured for the Tektronix terminal. To load or execute a program that calls ATOPLT, use a command of the form: .EXECUTE program, PIC:TKPLOT/SEARCH - 3.3 Internal Details 1. ATOPLT subroutines require at least 6P of memory and may require up to 13P depending on the features used. 2. Entry parts to ATOPLT are: ATOCHL, ATOGET, ATOLOG, ATOLSQ ATOLSP, ATOPLT, ATOPRM, ONEPLS ONEPLT, SIMPLS, SIMPLT 3. There are a large number of concealed subroutines in the ATOPLT system. They all have names of the form AP????, and users are advised not to use similar names to avoid the possibility of conflict. ATOPLT also uses named COMMON areas with names of the form AP????.

Programming Note 25/2 Page 21 4. ATOPLT has been written to be as independent as possible of the particular plotter hardware and software. Any user wishing to convert ATOPLT to work with some other plotter should consult PD36. 3.4 Error Messages 1. %ATPPOR ATOPRM index p out of range. ATOPRM parameters must lie in the range 1<p<45. - - 2. %ARPPLV ATOPRM parameter p value v is less than n %ATPPXV ATOPRM parameter p value v exceeds n. Some parameters have limits which cannot be exceeded. 3. %ATPAPL Attempt to plot log of v - point ignored v is a negative number and ATOPLT was asked to plot its logarithm. 4. %ATPTML Too many text labels supplied. The user cannot give more than 24 text labels in a call to ATOCHL. 5. %ATPNOV No origin value supplied with text labels. Text labelling must be combined with fixing the tick origin. 6. %ATPIOR XY-axis indicator out of range n The XY indicator must be either 1 for the X axis or 2 for the Y axis. 7. %ATPTMD Too many data sets in ATOLSQ call: n. %ATPTMD Too many data sets in ATOLSP call: n. Only 14 data sets can be used for least squares line drawing. 8. %ATPIOR Data point I out of range n. The data set indicators in the ISYM array must be in the range -14 to +14.

APPENDIX A ATOPLT VARIABLE PARAMETERS The values of the parameters given below may be altered, by using the ATOPRM subroutine, allowing the ATOPLT user greater flexibility in choosing his graph layout. The units of all the values given below are 'plotter units' i.e. mm * magnification-factor unless otherwise stated. The physical size of the plot is determined by the paper size for the Gould plotter and by the size of the screen for the Tektronix. The default parameters are defined so that the drawing fills the physical plotting area. The lengths of the various parameters are in plotter units. Normally these units are mm, but they can be altered by setting magnification factors for each axis which affects all lines drawn in that direction. Parameter Gould Tektronix --------- ----- --------- 4012 ---- Overall Parameters ------------------ Physical size of the plot in mm X 1 400.0 200.0 Y 2 260.0 150.0 Magnification factor - 0.5 is X 28 1.0 1.0 half size and 2.0 double size Y 29 1.0 1.0 Coordinates of the graph origin X 5 50.0 27.0 relative to the plot origin Y 6 15.0 15.0 Lengths of the axes X 3 280.0 130.0 Y 4 220.0 120.0 Width of the notes box 9 55.0 41.0 Coordinates of the Program X 42 0.0 0.0 ID message Y 43 5.0 5.0 Close the plot on exit from 30 1.0 1.0 ATOPLT flag 1.0 = close plot 0.0 = leave plot open

ATOPLT VARIABLE PARAMETERS Page A-2 Titling ------- Coordinates of X axis title X 11 8.0 50.0 Y 12 2.0 1.0 Coordinates of Y axis title X 13 30.0 6.0 Y 14 40.0 40.0 Clearance of plot title from 18 3.0 3.0 top of graph frame (the plot title is centred over the frame) Ticks Along the Axes -------------------- Spacing between ticks on axis X 10 10.0 10.0 Y 45 10.0 10.0 Height of ticks on each axis X 7 2.5 2.5 Y 26 2.5 2.5 Difference between heights of 8 1.5 1.5 alternate ticks (one setting for both axes) Line density for ticks 27 1.0 1.0 (1.0 for full density, -2.0 for half density -4.0 for quarter density etc.) Clearance of labels from 20 2.0 1.5 graph frame Clearance of log labels exponent 41 0.75 0.75 power for exponents Integer labels (rather than X 37 0.0 0.0 reals) 0.0=reals; 1.0=integers Y 38 0.0 0.0 Increment in data values between X 33 0.0 0.0 ticks. 0.0 means ATOPLT will Y 34 0.0 0.0 scale values to fit ticks Fix-tick-value flags X 31 0.0 0.0 0.0 means no fixed values Y 32 0.0 0.0 1.0 means that (35,36) give tick value 2.0 means that (35,36) give any origin value Fixed tick value or origin X 35 0.0 0.0 Y 36 0.0 0.0

ATOPLT VARIABLE PARAMETERS Page A-3 Note Box Positioning -------------------- (X,Y) displacement of first X 22 5.0 2.0 note line from top left Y 23 8.0 4.0 corner of note box Spacing between note lines 24 5.0 5.0 Character Sizes --------------- Symbols used for ploting points 25 2.0 2.0 Axis titles X 15 5.0 5.0 Y 16 5.0 5.0 Plot title 17 5.0 5.0 Tick label 19 3.0 2.5 Exponents for log labels 39 2.5 2.5 Exponent powers for log labels 40 2.0 2.0 Program ID 44 3.0 2.0 Notes 21 3.0 3.0

APPENDIX B CENTRING SYMBOLS Listed below are the symbols plotted at the data points for data sets numbered from 1 to 14.