Instructions for the Plot package for Unix This file explains how to compile,link, and use the programs in the MIIPS Plot package on a Unix machine. The package consists of high level programs to create XY plots from one or two text files, a library of plot subroutines for creating custom applications, and several demonstration programs for XY, histogram, contour, mesh, Hammer-Aitoff, and animation plotting. Some features of the programs are: 1) XY, histogram, mesh, contour, and Hammer-Aitoff plotting 2) Full interactivity with the plots: adding annotation, changing colors, replotting subsections, arithmetic operatons on data, resetting axis parameters, reading cursor values, drawing vectors, etc. 3) Linear and antilog axes labeling 4) Any number of points, any number of simultaneous plots for XY plotting 5) Additional optional labeling for top and right of XY graph 6) Any size array for contour or mesh plotting 7) Text and annotation can include subscripts and superscripts, and Greek letters, and symbols, and can be added interactively or hard coded. 8) Output can be directed to more than one plot device at a time and to a standard plot file 9) Output can later be directed from the standard plot file to any supported plot device or format, with offsetting, scaling, and rotation 10) Supported output devices and formats are: graphics terminals, xterm, xgterm, VersaTerm Pro, Enhanced SAOimage, postscipt, and encapsulated postscript. Support for Grinnell, Houston Plotter, Lasergrafix, Printronix, Ramtek, Tektronix 4662 Plotter, and Trapix is available upon request. 11) The quality is suitable for publication in scientific and engineering journals and has been so used for over 25 years. To use the compiled versions on a Linux system with Intel processor, or on a Mac OS X system with Intel processor, download plot_linux_executables.tar.gz or plot_macosintel_executables.tar.gz, respectively from the link at http://www.astro.gsu.edu/~gudehus/plot.html, and then extract the execute images and other files. For Mac OS X PPC systems, download and extract the file plot_macosppc_executables.tar.gz. The compiled versions should work on any of the above mentioned systems, but if the system libraries have been changed from their default versions some programs might crash. One known vulnerability is the FORTRAN call to DTIME. After the executables are on your system, you should define some aliases which are described further below. If you wish or need to recompile, you can download the file plot_unix_source.tar.gz from the download link at http://www.astro.gsu.edu/~gudehus/plot.html, and then extract the source code and other files. Once you have plot_unix_source.tar.gz available on your Unix machine, just enter gzip -d plot_unix_source.tar.gz tar -xf plot_unix_source.tar from a desired directory location. Set default to the newly created plot directory and enter make linux for Linux systems, or make macosppc for Mac OS X PPC systems, or make macosintel for Mac OS X Intel systems, or make ultrix for Ultrix systems, or make unix for other Unix systems. It is also possible to use the command make -f makefile-plot.pgf77 for Linux and Mac OS X Intel systems, for example. Ignore any warning messages. The programs will compile and link on a DECstation with the default compiler. For Linux on Intel processors, and for Mac OS X on Intel processors, you will need to have installed the Portland Group f77 compiler (http://www.pgroup.com). A free 15-day trial version of their compiler is available from their website. Their compiler also works for Solaris on Intel processors, but I have not tested this. Presumably, the linux makefile should work for their compiler on Solaris as well. Other brand compilers may possibly work with this code but I have not investigated them. For Mac OS X PPC, you will need to have installed the Absoft Pro Fortran compiler (http://www.absoft.com). A free 30-day trial version of their compiler is available from their website. The Absoft f77 compiler doesn't support variable FORMAT expressions which necessitated creating a special set of files just for that compiler. Also, the Absoft compiler has a bug with handling %REF with character data. A special usrinp.for, i.e., usrinp_char.for, was created to handle this problem. New subroutines for this and other limitations are located in the subdirectories mac_os_ppc. The compiled PPC version will also run on Macintoshes which use the Intel processors and are able to run Rosetta. The Portland Group's compiler for Mac OS X with Intel will also work with the Linux make file. For other Unix flavors the default f77 compiler may or may not work. A compatible compiler should support BYTE data type, ENCODE, DECODE, %REF, %VAL, variable FORMAT expressions, CARRIAGECONTROL keyword, and PARAMETER statement with or without parentheses. For the C code files, the built-in compiler will work. A brief description of the source code files follows. In the directory plot, one should have the files: Name Description alogaxis.for Lower level plot routine alogcode.for Lower level plot routine alogdeccode.for Lower level plot routine alogdecode.for Lower level plot routine apple.for Lower level routine for postscript appleplot.for Lower level routine for postscript arrowhead.for Lower level plot routine ascii1.dat Test file for xyplot_ascii.exe demo ascii2.dat Test file for xyplot_ascii.exe demo ascii3.dat Test file for xyplot_ascii.exe demo ascii4.dat Test file for xyplot_ascii.exe demo ascii5.dat Test file for xyplot_ascii.exe demo axis.for Lower level plot routine bell.for Routine to ring the bell calc.for Lower level plot routine color_24_triplet.for Lower level plot routine color_input.for Lower level plot routine color.for Program to interconvert colors of various bit numbers colormode.for Lower level plot routine colormode_background.for Lower level plot routine contourdem.for Demo program for contour plotting contourplot.for High level subroutine for contour plotting cplotc.for Lower level plot routine crosshair.for Lower level plot routine cube.for Demo program for rotating cube cubeplot.for Lower level plot routine datalevel.for Lower level plot routine decode_intervals.for Lower level plot routine delay.for Routine to produce a delay display-plotting_availability.dat List of available plot devices errorbar.for Lower level plot routine fillmode.for Lower level plot routine findplot.for Lower level plot routine get_dp_availability.for Lower level plot routine hammer_aitoff.for Transforms angles to Hammer-Aitoff X and Y hammer_aitoff_dem.for Demo program for Hammer-Aitoff plotting hammer_aitoff_grid.for Plots a Hammer-Aitoff grid histogram.for Lower level plot routine imtoolchecksum.for Required lower level routine issubsup.for Lower level plot routine keyboard.for Lower level plot routine limit.for Lower level plot routine line.for Lower level plot routine line_symbl.for Lower level plot routine makefile General makefile to compile and link all the executables makefile-plot.macosppc Makefile for Mac OS X PPC, w/Absoft compiler. makefile-plot.pgf77 Makefile for Linux/Mac OS X, Intel w/Portland Group compiler makefile-plot.ultrix Makefile for Ultrix makefile-plot.unix Makefile for other Unix meshdem.for Demo program for mesh plots meshgen.for Lower level plot routine meshplot.for High level subroutine for mesh plots meshplot1.for Helper routine for meshplot nhint.for Required lowel level routine number.for Lower level plot routine penmode.for Lower level plot routine plot.for Lower level plot routine plot_linux_executables.com Command file to tar and compress the executables for Linux plot_macosintel_executables.com Like above but for Mac OS X Intel plot_macosppc_executables.com Like above but for Mac OS X PPC plot_ultrix_executables.com Like above but for Ultrix plot_unix_executables.com Like above but for Unix plotcom.for Program to plot from plot file plotdevices.for Lower level plot routine plotdevices2.for Lower level plot routine plotdevques.for Lower level plot routine ploterrs.for Plot package error messages pltdev.for Lower level plot routine pltread.for Lower level plot routine pltwrite.for Lower level plot routine proj.for Lower level plot routine prtmsg.for Required lower level routine resettek.for Lower level plot routine sao.for Lower level plot routine sao_curn.for Lower level routine for SAOimage sao_display_vect.for Lower level routine for SAOimage sao_draw.for Lower level routine for SAOimage sao_erase_cursor.for User routine to erase cursors sao_load_vlt.for Lower level routine for SAOimage sao_vect.for Lower level routine for SAOimage saocaption.for Lower level routine for SAOimage saoconvlt.for Lower level routine for SAOimage saoeras.for Lower level routine for SAOimage saofirst.for Lower level routine for SAOimage saoplot.for Lower level plot routine saostart.for Lower level routine for SAOimage scale_axis.for Lower level plot routine scan.for Lower level plot routine scan_simple.for Lower level plot routine scansl.for Lower level plot routine si_subs.c Lower level routine for SAOimage si_subs.h Lower level routine for SAOimage strludef.for Required lowel level routine symbol.for Lower level plot routine symbols.for Demo program to plot symbols symgen.for Routine to generate symbols symgengr.for Routine to generate Greek letters sys_keyin.c Lower level plot routine t.txt Explanation for simple demo programs t1.for Program to demonstrate vectors t2.for Program to demonstrate key press t3.for Program to demonstrate fill t4.for Program to demonstrate vector styles t5.for Program to demonstrate axis drawing t6.for Program to demonstrate axis drawing with user input t7.for Program to demonstrate pausing t8.for Program to demonstrate antilog axis drawing t9.for Program to demonstrate the symbol subroutine t10.for Program to demonstrate changing the data level t11.for Program to demonstrate pen widths t12.for Program to demonstrate the line subroutine t13.for Program to demonstrate the line_symbl subroutine t14.for Program to demonstrate interactive commands t15.for Program to demonstrate circles t16.for Program to demonstrate point plot mode t17.for Program to write a simple 1-inch square tek.for Lower level plot routine tekcon.for Lower level plot routine tekpau.for Lower level plot routine tekplot.for Lower level plot routine textcnch.for Lower level plot routine trace.for Lower level plot routine transform.for Lower level plot routine transparent_mode.for Program to go from Tek to terminal transparent_mode_x.for Program to go from Tek to terminal for xterm transparent_mode_xn.for Program to go from Tek to terminal for xterm without erasing plot transparent_to_tek.for Lower level plot routine vectmode.for Lower level plot routine where.for Lower level plot routine xyplohdem.for Demo program for histogram plots xyplot.for High level subroutine for XY plots xyplot_ascii.for Program to plot from one or more ASCII files xyplot_f.for Lower level plot routine xyplot_setup.dat Setup file for xyplot_ascii.exe xyplot_setup1.dat Setup file for xyplot_ascii.exe in demo xyplot_setup2.dat Setup file for xyplot_ascii.exe in demo xyplot_setup.for Lower level plot routine xyplotdem.for Demo program for XY plots xyplotdem2.for Demo program for XY plots In the directory plot/include one should have the files: Name Description plotpar.for Plotting parameters include file sao_default_vlt.for Default lookup table for saofacts.for Common block for Enhance SAOimage In the directory plot/mac_os_ppc one should have the files: Name Description apple.for Lower level routine for postscript color.for Program to interconvert colors of various bit numbers contourplot.for High level subroutine for contour plotting crosshair.for Lower level plot routine cube.for Demo program for rotating cube errorbar.for Lower level plot routine hammer_aitoff_dem.for Demo program for Hammer-Aitoff plotting imtoolchecksum.for Lower level routine for named pipes line.for Lower level plot routine line_symbl.for Lower level plot routine meshdem.for Demo program for mesh plots meshplot.for High level subroutine for mesh plots number.for Lower level plot routine plotcom.for Program to plot from plot file plotdevices.for Lower level plot routine pltread.for Lower level plot routine pltwrite.for Lower level plot routine scale_axis.for Lower level plot routine si_subs.c Lower level routine for named pipes si_subs.h Include file for the above file t2.for Program to demonstrate key press t9.for Program to demonstrate the symbol subroutine t14.for Program to demonstrate interactive commands xyplohdem.for Demo program for histogram plots xyplot.for High level subroutine for XY plots xyplot_ascii.for Program to plot from one or more ASCII files xyplot_setup.for Lower level plot routine In the directory plot/utilities one should have the files: Name Description alpha.for Character processing routine daxpy.for Routine for vector math dcd.for Routine to help usrinp dcopy.for Routine for vector math ddot.for Routine for vector math decode_decimal.for Lower level routine dmnmxme.for Lower level routine do.for Routine to help usrinp dspdi.for Routine for matrix math dspfa.for Routine for matrix math dswap.for Routine for vector math dynamic.for Routine to obtain dynamic memory dynamic_c.c Routine to obtain dynamic memory error.for Required lower level routine get_os_bytes.for Routine to get OS number of bytes get_os_bytes_c.c Routine to get OS number of bytes idamax.for Routine for vector math inel.for Routine to help usrinp linfit1d.for Routine for 1-dimensional linear least squares fitting linfit1d1.for Helper routine for linfit1d linfit1d2.for Helper routine for linfit1d makefile General makefile for the utility files makefile-plot_utilities.macosppc Makefile for Mac OS X PPC makefile-plot_utilities.pgf77 Makefile for Intel processors makefile-plot_utilities.ultrix Makefile for Ultrix makefile-plot_utilities.unix Makefile for other Unix matrixinv.for Routine for inverting a matrix matrixinv1.for Helper routine for matrixinv message.for Routine to display messages nel.for Routine to help usrinp neld.for Routine to help usrinp opencf.for User routine to open a character file pol.for Routine to evaluate a polynomial pol1.for Helper routine for pol polinterp1d.for Routine for 1-Dimensional polynomial interpolation polinterp1d1.for Helper routine for polinterp1d realindex.for Lower level routine release_memory_c.c Routine to release dynamic memory save.for Routine to help usrinp scalpol.for Helper routine for linfit1d2 strkey.for Routine to help usrinp syminv.for Routine to solve linear equations usrinp.for User input routine In the directory plot/utilities/mac_os_ppc one should have the files: Name Description dcd.for Mac OS X/Absoft version linfit1d1.for Mac OS X/Absoft version nel.for Mac OS X/Absoft version neld.for Mac OS X/Absoft version opencf.for Mac OS X/Absoft version save.for Mac OS X/Absoft version usrinp.for Mac OS X/Absoft version The makefile will also create the object libraries, plot_u.a and and utilities/utilities_u.a which can be used to link with any user written programs if desired. For whichever method you use to install the executable files, create the aliases: alias a 'transparent_mode.exe' alias ax 'transparent_mode_x.exe' alias axn 'transparent_mode_xn.exe' alias plot 'plotcom.exe' alias xyplot 'xyplot_ascii.exe' "a" will change from the Tektronix window to the text window in a graphics terminal. "ax" will change from the Tektronix window to the text window in xterm, and erase the screen. "axn" will change from the Tektronix window to the text window in xterm, without erasing the screen. "plot" will operate the plot command on the standard plot files (see below) "xyplot" will produce an XY plot of columnar data from one or more ASCII files. These definitions can be placed in a login file if desired. Finally, edit display-plotting_availability.dat to match the display and plotting devices availabile on your system. The plot device xgterm is a color xterm-like graphics terminal emulator which runs on Unix. Copies compiled for Linux with Intel processors for kernels 2.2 and 2.4, Mac OS X 10.4, Tiger, and Mac OS X 10.7/10.8 can be downloaded from the web page for this package. An early version of xgterm for Mac OS X 10.4 from iraf.net did not work correctly. While a plot could be sent to it, the Tek window never received focus, so no cursor readback was possible. The version on the web page was prepared by Chip Coldwell, and will work correctly. In the file .Xdefaults in your Unix home directory create the following settings for xgterm: !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! xgterm Xgterm*gterm*color0: black Xgterm*gterm*color1: ivory1 Xgterm*gterm*color2: red Xgterm*gterm*color3: green Xgterm*gterm*color4: blue Xgterm*gterm*color5: cyan Xgterm*gterm*color6: yellow Xgterm*gterm*color7: magenta Xgterm*gterm*color8: gold1 Xgterm*gterm*color9: DarkSlateGray3 Xgterm*gterm*height: 601 Xgterm*gterm*width: 801 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! These colors are frequently used in the demonstration programs. Running the Demonstration Programs First try running the demonstrations programs xyplotdem.exe, xyplotdem2.exe, xyplohdem.exe, contourplotdem.exe, meshdem.exe, hammer_aitoff_dem, and cube.exe. One is initially prompted for the plot device. Depending on the state of the display-plotting_availability.dat, one might be presented with: Enter the plot devices: S = SAOimage -S = SAOimage, no erasure of screen G = Graphics terminal (VT100/Retrographics and Visual 550) G4 = Graphics terminal emulator (Versaterm) X = Xterm (default) XG = Xgterm F = File Enter one or more letters corresponding to the plot devices you wish the plot to appear on, e.g. X F. If you are connected to a Unix system via telnet or ssh from a Macintosh, then it is possible to use Versaterm. Note that SAOimage refers to "Enhanced SAOimage", available from http://www.astro.gsu.edu/~gudehus/enhanced_saoimage.html. After the plot appears, several interactive plot commands are available (except when running cube.exe). Help can be obtained by typing (not entering) H or h. All or some of the following will then appear (note that ^ denotes that the control key is to be pressed as well): A = Turns on the crosshairs and by pressing the at chosen X limits, the mean Y value will be calculated for each plot. a = Allows the user to enter annotation at the location of the crosshairs with the color most recently selected. ^I (^L on Mac OS X) toggles to the Greek alphabet and special symbols and back to English ^H (^B on Mac Os X) gives a backspace ^K toggles to subscript, superscript, and back to normal ^A = Prompts user for the height of the annotation. B = Defines a box with the crosshairs placed at the lower left and upper right. Will replot with this scaling. b = Allows the user to be prompted for the background color on SAOimage. C = Turns on the crosshairs and by pressing the , prints the values at that location and puts the values in a common block; typing - deletes the last pair of values from the common block; and typing Q turns off the crosshairs. c = Allows the user to be prompted for the color. F = Allows the user to alter the scaling factor on the current plot device(s). f = Allows the user to change the fill style for each plot. H = Gives help. h = Gives help. I = Allows the user to be prompted for several of the plotting parameters before a replot is done. This command is typically used when preparing a plot for publication. The following operations are available: 1) Inverting the X axis and/or Y axis 2) Labeling the X and Y axes in the following ways: Linear automatic, Linear manual, Antilog automatic, Antilog manual (antilog refers to the fact that the labeling is the antilog of the plotted values which are logs) a) In the Linear manual mode one can specify for the X and Y axes, the lowest labeled physical value, the physical value/interval, and the number of intervals (coded as nn.llrr where nn is the integer part, .ll represents the left (or bottom) fractional part, and .rr represents the right (or top) fractional part of an interval). b) In the Antilog manual mode one can specify for the X and Y axes, the lowest displayed tick mark (coded as log.antilog where log is the integer part of the plotted value (which is a log), and antilog represents the first displayed tick mark of that decade (which is an antilog)). The antilog of the physical value at the first tick mark may or may not be printed byu the program. One can also specify the number of displayed decades (coded as n.antilog where n is the integer part of the number of decades, and antilog represents the rightmost displayed tick mark of an additional decade. For example, if one enters -1.5 for the lowest value and 3.2 for the number of decades, then the first tick mark will be at X=0.5 (log = -0.301 = -1 + 0.699) and the last tick mark will be at X=200 (log = 2.301). Note that fractional parts of .0 and .1 behave the same way. Note: If the original plot was linear, then the log of the data should be taken first (with the L command) for the antilog labeling to make sense. 3) Specifying symbol heights 4) Specifying labels for the X and Y axes 5) Specifying a title 6) Specifying one or more print devices L = Allows the user to take log(X) and log(Y). l = Allows the user to take ln(X) and ln(Y). M = Allows the user to modify the X and Y values by adding increments and adjusting by scaling factors. m = Allows the user to modify the X and Y values by adding increments and adjusting by scaling factors for a selected plot. O = Redoes the original plot with any new axes, colors, and symbols. o = Redoes the original plot without any new axes or symbols. P = Allows the user to take powers. p = Allows the user to specify the color of each plot. Q = Returns. q = Returns. R = Turns on the crosshairs and by pressing the at chosen X limits, replotting with automatic scaling will be done. S = Allows the user to specify the style of vector. s = Allows the user to specify the symbol for a set of points. V = Draws a vector of the color and vector style most recently selected. v = Allows the user to be prompted for the starting and ending physical values of a vector. X = Allows plotting an additional X axis in different linear units. x = Allows plotting an additional X axis in different antilog units. Y = Allows plotting an additional Y axis in different linear units. y = Allows plotting an additional Y axis in different antilog units. A subset of these commands are used in contourdem.exe, hammer_aitoff_dem.exe, and meshdem.exe. On SAOimage and xgterm, user prompts appear on the text terminal whereas on all other devices the prompts will appear on the Tek window. Note that a plot can be sent to more than one device at a time. Xgterm, a color xterm, behaves mostly like xterm. One difference between the two is that xterm allows one to use the left mouse button to interact with the plot whereas xgterm requires a press. SAOimage also requires a press for plot interaction. SAOimage on Mac OS also requires that it be given focus by clicking in the frame before any interaction is attempted. Following that, the cross cursor should be positioned within the SAOimage desktop area before and commands are given. The version of SAOimage available from most sources will not work with plotting; the version that is required is "Enhanced SAOimage, v. 1.24E", available at the MIIPS website. The version of Xgterm for the Macintosh available from iraf.net does not work properly either. Use the version in this package. Xgterm needs to have its colors defined in the user's .Xdefaults file. The following entries will ensure that the correct colors are displayed: Xgterm*gterm*color0: black Xgterm*gterm*color1: ivory1 Xgterm*gterm*color2: red Xgterm*gterm*color3: green Xgterm*gterm*color4: blue Xgterm*gterm*color5: cyan Xgterm*gterm*color6: yellow Xgterm*gterm*color7: magenta Xgterm*gterm*color8: gold1 Xgterm*gterm*color9: DarkSlateGray3 Xgterm*gterm*height: 601 Xgterm*gterm*width: 801 If a plot file is being created it is possible to add annotation that will be written to the file. For example, if one selects DEVICES=X F the plot will appear on an xterm and be written to a file. Pressing "a" while the plot is displayed on an xterm will then bring up a cursor. Position the cursor on the plot and then click the left mouse button (or press the for xgterm and SAOimage). You are then prompted to enter some annotation. You can enter either English text, Greek letters, special symbols, or some combination of them. Typing ^I (^L on Mac OS X) at this time, toggles to the Greek alphabet and special symbols, and back to English. In the Greek mode, the numbers 0 to 9 produce the symbols 0 to 9. One could for example use special symbol 1 (a circle) to denote the position of the primary in a plot of a relative orbit. Note however, that the cursor center currently corresponds to the lower left corner of the initial character. The Plot Command After a plot file has been created, the plot can at any time be directed to any of the available plot devices by using the plotcom.exe program. Since the plot file's default name is plot.plt, be sure to change this to some other name to avoid having it be overwritten by another plot file. To plot a plot file, first be sure that you have set up the alias 'plot' as described above. Enter: plot device=P xoff=X yoff=Y scale=S rotate=R number=N plot_file where 1) Each optional keyword, and in the case of "device", its value, can be shortened to an unambiguous abbreviation 2) If no device is specified, the default is xterm 3) If no plot_file is specified, the default is plot.plt 4) An optional / delimiter can be used between keywords (but not before the first one) 5) The keywords have the following meaning: device is the plot device, with values, P, equal to TEKTRONIX = Graphics terminal (VT100/Retrographics and Visual 550) GRAPHON = Graphon graphics terminal CODONICS = Codonocs graphics terminal MICROTERM = Microterm graphics terminal VERSATERM = Versaterm graphics terminal emulator for Macintosh XTERM = Xterm graphics terminal emulator for OpenVMS and Unix XGTERM = Xgterm grpahics terminal emulator for Unix SAOIMAGE = Enhanced SAOimage _SAOIMAGE = Enhanced SAOimage with not erasure of the previous image POSTSCRIPT = Postscript output file (default name is plot.ps) EPS = Encapsulated postscript output file (default name is plot.eps) (each device can be shortened to an unambiguous abbreviation, e.g. pos or POS for POSTSCRIPT) xoff is the horizontal offset, X, of the plot in inches yoff is the vertical offset, Y, of the plot in inches scale is the magnification, S, of the plot in terms of a factor. rotate is the counterclockwise rotation, R, of the plot in degrees number is the number, N, of the complete plot within the plot file. Because the plot file is not closed until the binary program quits, all plots are written to the same file, and the "number" keyword must be used to select the plot. 6) The keywords and their values can be upper- or lowercase 7) When both rotation and offsets are given, the operation can be thought of as either 1) rotation about the lower left corner of the plot followed by translation in the rotated coordinate system, or 2) translation followed by rotation about the old location of the corner. Thus a plot on xterm can be viewed rotated 90 counterclockwise with a command such as: plot yof=-6 rot=90 sca=0.75 myplot.plt 8) Postscript files created by the plot command are by default matched to a printed sheet viewed in landscape orientation. Thus when such a file is viewed with ghostview or another postscript viewer, they will appear to be rotated by 90 degrees counterclockwise. To create a postscript file without the prerotation, use a command such as: plot dev=pos xof=-8.0 rot=-90 myplot.plt 9) Encapsulated postscript files are by default not prerotated and will appear in the correct orientation in ghostview. In addition, encapsulated postscript files are by default created with a bounding box size just slightly larger than the default XY plot size (X axis = 6 inches, Y axis = 5 inches). If your plot size is larger or smaller than the default size just use an editor such as vi to change the dimensions in the *.eps file. The BoundingBox line is 5th from the top. The encapsulated postscript files will not ordinarily produce output on a printer because because they do not contain the 'showpage' command. If you wish to see a printed version of your eps file, just add 'showpage' after the last 'stroke' command on the third line from the end. 10) The keyword, number, selects the number of the plot within a multi-plot file. If the number keyword is not given, by default the first plot is displayed on devices such as graphic terminals, xterm, xgterm, and SAOimage. If a postscript file is created and no number keyword is given, all plots are written to the file. For an eps file, only the first file is written. If the value given for the number keywords is -1, then all plots are displayed overlapped on all devices, postscript files, and eps files. Plotting from an ASCII File One or more ASCII files of data can be plotted with the program xyplot_ascii.exe, a general purpose interface for the xyplot.for. Three cases can be handled. In the first case, the data for the abscissa and ordinate are contained in one file having an arbitrary number of header lines, an arbitrary number of columns, and an arbitrary number of rows of data. All columns must have the same number of rows however. Multiple plots are possible by selecting more than one column for the abscissa and ordinate. The number of columns chosen for the abscissa and ordinate must match. In the second case, the data for the abscissa are contained in a first file and the data for the ordinate are contained in a second file. The number of rows in both files, other than header rows, must match. Multiple plots are again possible. In the third case, the abscissa and ordinate data for the first plot are contained in the first of several files, and the abscissa and ordinate data for additional plots are contained in additional files up to a maximum of fifteen plots. This is the most general case because the numbers of rows do not have to match between files. In all three cases the data can be in the form of decimal or integer values. A setup file needs to be opened which sets up the line dashing, pen width, line style, symbols, and colors. By editing this setup file, many different graphs can be produced. In the setup file, the name of the control parameter is followed on successive lines by the values desired for each plot. The control parameters may be in any order. The number of values can be less than, equal to, or greater than the number of plots desired. The program will simply use the values up to the last one available, and then roll the values over. The file xyplot_setup1.dat, shown below, is an example of this format: LINE VECTOR STYLE 0 0 0 0 0 0 0 1 2 3 4 5 PEN WIDTH 20 LINE TYPE -1 0 997 997 -1 997 997 SYMBOL 0 1 100 100 327681 100 100 5 6 7 8 9 10 INVERT X NO INVERT Y NO COLOR 16776960 Yellow 16711935 Magenta 65280 Green 65280 Green 16711680 Red 8388564 Aquamarine 8388564 Aquamarine 255 Blue 16766720 Gold1 65535 Cyan 7982541 DarkSlateGray3 16777200 Ivory1 10824234 Brown 16716947 Deep pink 5597999 Dark olive greem 15631086 Violet 16766720 Gold 16770229 Moccasin X LABEL X Axis Y LABEL Y Axis TITLE Anonymous 1) Each keyword is followed, on successive lines, by the values for a single plot within the complete plot. If there are more plots than values, rollover will occur. If there are fewer plots than values, the extra ones will not be used. 2) The keywords may be in any order 3) Comments are allowed to the right of a value, however it is very important that there be no tabs in the line. 4) The LINE TYPE (as explained in line.for) controls the plot lines and the type of plot, where: a) The magnitude of the value controls the frequency of plotted symbols, e.g. zero gives no symbols, and 4 gives a symbol every 4th data point b) Positive values give a straight line connecting every data point c) Negative values give no connecting straight lines d) If the value is 997 error bars are drawn (two plots are required) e) If the value is 998 a histogram is drawn with the bars stacked vertically if multiple plots are made f) If the valud is 999 a histogram is drawn with the bars placed next to each other is multiple plots are made 5) The SYMBOL controls the type of symbol where a) values from 0 to 13 in the first byte give the built-in symbols b) a character may be plotted if the ASCII code is placed in the second byte c) if a histogram is to be drawn, the value in the first byte give the filling style d) if error bars are to be drawn, the value in the first byte give the style of the bar, i.e., 0 give a short tick, 1 gives nothing, 2 gives an arrowhead. If 100 is added to the first byte, the X or Y locations contain the central location and the deviation to the low and high directions, respectively, for the adjacent array locations. Because errorbars require two plots, the values should be repeated. e) the value in the third byte give the symbol height in hundredths of an inch. If the value is not present a default of 0.14 inch is used. In the above example setup file, the values under LINE TYPE and SYMBOL indicate that the first plot will consist of points drawn with symbol number 0 with no connecting lines, and the second plot will have connecting lines between the points with no symbols drawn. The third plot will be error bars drawn with the usual short ticks at the ends. Because error bars require two adjacent plot array locations, the values for each keword are repeated. The fourth plot will consists of points drawn with symbol number 1, but because the symbol is to be drawn with a smaller size of 5/100 inches, 5 is added to the 3rd byte, giving a final value of 1 + 5*256**2 = 327681. A future version of xyplot_ascii will attempt to make this operation more user friendly. The next plot is again error bars, requiring repeated values. Five sample ASCII files are included in this package to demonstrate how xyplot_ascii.exe works. Launch the program, and you will be presented with the following menu: Enter a choice for the input data: 1 = Abscissa and ordinate data for one or more plots in one file (default) 2 = Abscissa data in one file and ordinate data in another file for one or more plots 3 = Abscissa and ordinate data for first plot in first file, additional data for additional plots in successive files, up to a maximum of ten files CHOICE= Enter 1, and the program responds with: Open the file containing the abscissa and ordinate data for one or more plots. Enter the file name: FILE= Enter ascii1.dat, and the program asks: How many lines are in the header? (default = 1) LINES_HEADER_1= Enter 1 or take the default, and the header line will be displayed, along with the counts of the number of columns of data and the number of lines of data. The program then asks: Enter the column(s) to be plotted as abscissa values: COLUMNS_ABSCISSA= Here we are going to plot the data in column 2 against time in column 1, plot the curve in column 6 against time, and plot error bars for the data. Because all abscissa values originate from column 1, and because there are 4 plots (data, curve, and error bars requiring 2 plots) we enter 1 1 1 1. The program then asks: Enter the column(s) to be plotted as ordinate values: COLUMNS_ORDINATE= We enter 2 6 2 3 (column 2 for the data, column 6 for the curve, column 2 for the central location of the error bar, and column 3 for the amplitdue of the error bar). Now the program asks for the name of the setup file: Open the setup file: (default = xyplot_setup.dat) SETUP_FILE= Enter xyplot_setup1.dat (do not take the default) and the program then asks Enter the plot devices: S = SAOimage (Enhanced version) -S = SAOimage, no erasure of screen G = Graphics terminal (VT100/Retrographics and Visual 550) G4 = Graphics terminal emulator (Versaterm) X = Xterm (default) XG = Xgterm F = File Enter the appropriate device name, and you will see the plot. If you enter 1 1 1 1 1 1 1 for the abscissa columns, and 2 6 2 3 4 4 5 for the ordinate columns, you will see an additional set of data points plotted with a different symbol, a different symbol size, a different error bar length, and different colors (if you are using a color display). ************* Launch xyplot_ascii.exe again and this time enter 2 for the choice of input data. In this case, the abscissa data come from one file and the ordinate data from a second file. The program responds with: Open the file containing the abscissa data for one or more plots. Enter the file name: FILE= Enter ascii2.dat, and the program asks: How many lines are in the header? (default = 1) LINES_HEADER_1= Enter 1 or take the default, and the header line will be displayed, along with the counts of the number of columns of data and the number of lines of data. The program then asks: Enter the column(s) to be plotted as abscissa values: COLUMNS_ABSCISSA= Enter 1 1 1 1. The program then asks: Open the file for the ordinate Enter the file name: FILE= Enter ascii1.dat, and the program asks: How many lines are in the header? (default = 1) LINES_HEADER_2= Enter 1 or take the default, and the header line will be displayed, along with the counts of the number of columns of data and the number of lines of data. The program then asks: Enter the column(s) to be plotted as ordinate values: COLUMNS_ORDINATE= Enter 2 6 2 3, as before, and the program asks: Open the setup file: (default = xyplot_setup.dat) SETUP_FILE= Enter xyplot_setup1.dat, as before, and the program then asks Enter the plot devices: S = SAOimage (Enhanced version) -S = SAOimage, no erasure of screen G = Graphics terminal (VT100/Retrographics and Visual 550) G4 = Graphics terminal emulator (Versaterm) X = Xterm (default) XG = Xgterm F = File Enter the appropriate device name, and you will see a plot which differs from the first one in that the abscissa values are larger by a factor of 100. ************* Launch xyplot_ascii.exe again and this time enter 3 for the choice of input data. In this case, the abscissa and ordinate data for the first plot are contained in the first of several files, and the abscissa and ordinate data for additional plots are contained in additional files up to a maximum of fifteen plots. The program responds with: Open the file containing the abscissa and ordinate data for the first plot. Enter the file name: FILE= Enter ascii3.dat, and the program asks: How many lines are in the header? (default = 1) LINES_HEADER= Enter 13, and the program will report the number of columns of data and the number of lines of data, and then ask: Enter the column(s) to be plotted as abscissa values: COLUMNS_ABSCISSA= Enter 1 1 1, (the columns for the x data points and their error bars). Then the program asks: Enter the column(s) to be plotted as ordinate values: COLUMNS_ORDINATE= Enter 2 2 3, (the columns for the y data points and their error bars), and the program responds with: Enter the name of the input file for an additional plot; enter 0 to continue: FILE= Enter ascii4.dat, and the program asks: How many lines are in the header? (default = 1) LINES_HEADER= Enter 13, and the program will report the number of columns of data and the number of lines of data, and then ask: Enter the column(s) to be plotted as abscissa values: COLUMNS_ABSCISSA= Enter 1, (the column for the x data of a single curve). Then the program asks: Enter the column(s) to be plotted as ordinate values: COLUMNS_ORDINATE= Enter 2, (the column for the y data of that curve). The program next asks: Enter the name of the input file for an additional plot; enter 0 to continue: FILE= Enter ascii5.dat, and the program asks: How many lines are in the header? (default = 1) LINES_HEADER= Enter 13, and the program will report the number of columns of data and the number of lines of data, and then ask: Enter the column(s) to be plotted as abscissa values: COLUMNS_ABSCISSA= Enter 1 1 1, (the columns for the x data points and their error bars for another set of data). Then the program asks: Enter the column(s) to be plotted as ordinate values: COLUMNS_ORDINATE= Enter 2 2 3, (the columns for the y data points and their error bars). The program next asks: Enter the name of the input file for an additional plot; enter 0 to continue: FILE= Enter 0, because we are done entering the ascii files of data. Now the will ask: Open the setup file: (default = xyplot_setup.dat) SETUP_FILE= Enter xyplot_setup2.dat (don't take the default). Then you are asked: Enter the plot devices: S = SAOimage (Enhanced version) -S = SAOimage, no erasure of screen G = Graphics terminal (VT100/Retrographics and Visual 550) G4 = Graphics terminal emulator (Versaterm) X = Xterm (default) XG = Xgterm F = File DEVICES= Enter your current graphics device and a plot with two sets of data with error bars, and a curve with a dashed line will be displayed. You can then use the built-in interacive commands of xyplot to rescale, arithmetically tranform the data, add annotation, and send the plot to the same or a different device, or a file. Additional Notes The MIIPS plot package also allows programmers to create their own specialized plot applications. Besides the above demonstrations programs there are several simple examples, described in t.txt, which demonstrate one or more aspects of the package. Try running the test programs t1.exe, etc to get familiar with the subroutines. Some of these programs will ask for the device number. The numbers can be found in pltdev.for, and have the following associations: NDEV DEVICE 1 Graphics Terminal (VT100/Retrographics, Visual 550) 101 Graphics Terminal (GraphOn) 201 Graphics Terminal (Codonics) 301 Graphics Terminal (Micro-term) 401 Graphics Terminal emulator (Versaterm) 10001 Xterm 20001 Xgterm 2 File 4 1 and 2 (temporarily retained for compatibility) 999811 Encapsulated postscript file (no printing) 999911 Postscript file (no printing) 13 SAOimage -13 SAOimage without erasure Any questions should be directed to Donald Gudehus at gudehus@astro.gsu.edu.