By downloading this code you agree to the
Source Code Use License (PDF). |
{ version = 9.52; (* of xyplo.p 2024 Jun 06} (* begin module describe.xyplo *) (* name xyplo: x, y data plotter (pronounced: "zyplo") synopsis xyplo(xyin: in, xyout: out, xyplop: inout, xyplom: in, warnings: out, output: out) files xyin: A set of header lines that begin with asterisk ('*') or pound sign ('#') are copied to output. Remaining lines are the data in columns, ending with end of file. Tabs may separate data. Missing columns are not allowed. See the demonstration file xyin.demo for an example. Once the first data line has been read, lines that begin with an '*' or '#" or that are entirely blank will be ignored. This allows one to place comments or other information deeper into the file without having xyplo object. The # allows files to be read by gnuplot too. xyplop: Parameters to control the plot, on lines as shown. The major sections of the parameter file are separated by lines that are used by the program as separators. A separator line may begin with blanks, and these must be followed by asterisks, as shown below. These lines simply make the file easier to deal with, but you must have them in the file! The easiest way to create a xyplop file is to copy the demonstration file (xyplop.std or xyplop.demo) and modify that to suite your needs. xzero yzero amounts to move the graph origin (cm) zx min max (character, real, real) if zx='x' then set xaxis zy min max (character, real, real) if zy='y' then set yaxis These two lines set the minimum and maximum range of the data to graph. Other characters mean the program automatically uses the range of the data. xinterval yinterval xsubintervals ysubintervals: These 4 parameters, all on one line, define the number of numbered intervals on each axes to plot and the number of unnumbered subintervals. Note that on a regular scale, going from 10 to 20 requires 10 intervals (to get whole numbers), but on a log scale, going from 10 to 100 requires 9 intervals (to get tics every 10), not 10 intervals! xwidth ywidth width of numbers in characters xdecimal ydecimal number of decimal places xsize ysize size of axes in cm xlabel the x axis label ylabel the y axis label NEW: 2016 Sep 29 the y label is now rotated and on the left side of the graph. To restore the original behavior of the y label above the y axis, put '^' in front of the title. zc if zc='c' then a crosshairs put on zero of x and y 'x' then only X axis is plotted 'X' then only X axis and crosshairs 'y' then only Y axis is plotted 'Y' then only Y axis and crosshairs 'n' then neither axis nor crosshairs 'N' then neither axis with crosshairs 'i' then numbering and tic marks but no line (invisible) Otherwise, both axes are plotted without crosshairs. zxl base if zxl='l' then convert the x axes to a log scale using the indicated base. zxl='L' is like 'l' but the numbers given on the axis have not had the log taken of them. zyl base if zyl='l' then convert the y axes to a log scale using the indicated base. zyl='L' is like 'l' but the numbers given on the axis have not had the log taken of them. * define columns to read data from *********************************** This section defines which column of xyin contains what kind of data. You can use a column only once. xcolumn ycolumn columns of xyin that determine the location of the symbol symbol-column the xyin column to read symbols from if zero, then use the first symbol defined below xscolumn yscolumn columns of xyin that determine the size of the symbol. If zero, then no data is expected. NOTE: for most symbols this is the entire size of the symbol. For the I beam symbol, the yscolumn is half of the total size plotted. Thus one may use standard deviations and obtain a symbol of 2 standard deviations high centered on the y coordinate. colorkind hucolumn sacolumn brcolumn define the hue saturation brightness columns. These control the color of the rectangle symbol. 1 0 0 is black (assumed if columns are all zero) 1 0 1 is white Hue runs from red (value 0) through the spectrum to violet (value 1). See the technical notes for further details. If the first character of the line is a digit, blank or 'h' then the hsb (hue saturation brigtness) color model is used. If the first character of the line is 'r' then the rgb (red green blue) color model is used. * define one or more symbols ***************************************** Each of these sections defines one of the symbols by specifying what to do for each symbol flag seen in the symbol column. There may be as many symbols as will fit in memory. The last of these sections must contain just a '.' as the 'symbol-to-plot'. This is required to end the symbol definition section since there are an indefinite number of symbols. symbol-to-plot (character) Most symbols are plotted at the coordinates given in xcolumn and ycolumn. 'c' plot a circle 'C' plot a circle; with connections in color 'b' plot a box 'B' plot a box; with connections in color 'x' plot an x '+' plot a plus 'I' plot an I beam symbol 'd' plot a box with central dot 'p' point (or dot) alone. 'm' mark according to a xyplom definition 'M' mark according to a xyplom definition, with connections in color 'R' plot a filled rectangle in color. Unlike the other symbols, which are centered on the data, the lower right hand corner of this rectangle is placed on the data. This allows the user more control on placement. 's' plot a histogram from zero to the height 'r' like 'R' but gray scale. The brightness column is used for controlling the brightness. 'f' Means to plot the symbol-flag (defined below). The 'f' type allows several symbols to be made each with its own regression and connection lines, but plotted with the entire flag string in xyin. The symbols are distinguished by their first character. The symbol-flag in xyplop should be set to the string that one desires to be recognized. 'f' will center the string. 'F' will left justify the string. 'g' Means 'grab bag'. The 'g' type has lower priority than any other symbol. Xyplo searches through all the available symbols looking for a match to the symbol-flag. If a symbol-flag cannot be found, then the data are assigned to the 'grab-bag'. The program uses the symbol-flag on the graph. The symbol-flag in xyplop can be anything. 'g' will center the string. 'G' will left justify the string. 'L' will make just lines using the current colors. The symbol underscore (_) in xyin is converted to a blank to allow the appearance of separated words. One can do grab-bag connected curves without symbols by setting g and the symbol-flag to ' '. One can also set the symbol-to-plot to blank (or other unrecognized symbol) to get specific connected curves. In this case, the symbols MUST be connected or the program will object (invisible symbol and invisible connection means data loss). 'm' Means to look up the symbol-flag name in the xyplom file and to use the PostScript definition there to create the symbol. 'M' like 'm' but draw the connecting line in color and if there is no symbol in the xyplom, don't draw any symbol. This allows one to make curves without symbols. symbol-flag The string of characters that indicates that this symbol should be plotted. Eg, if the 'symbol-to-plot' is I and the flag is x, then whenever an x is seen in the symbol column, an I beam will be plotted. The flag can be more than one character long, but (unfortunately) it cannot contain blanks. symbol-sizex Side in cm on the x axis of the symbol. If this value is negative, the data in xscolumn is used to determine the size. For circles, sizex determines the diameter, sizey is ignored. symbol-sizey Side in cm on the y axis of the symbol. If this value is negative, the data in yscolumn is used to determine the size. For circles, sizeX determines the diameter but a positive number is still required for sizey. connection linetype size If the first character is 'c' then the symbols will be connected by lines of linetype as defined below. (Linetype must follow the c immediately, without blanks.) linetype size linetype is a character defining the kind of regression line to plot for this symbol: 'l' means do regression line 'i' invisible, '.' dotted '-' dashed 'n' means no line. '-' and '.' require a size in cm for the spacing. The others also require a number, but it is ignored. * end the symbol definitions with a period (left justified!) ********* . * define zero or more user defined lines ***************************** linetype m b size One or more lines to be drawn on the plot, m and b are slope and intercept. Linetype and size are define as for the symbol connection lines. blank lines and lines that begin with "*" are ignored. in this section linetype is defined as for the regression lines. * end of the line definitions and start of more parameters *********** edgecontrol edgeleft, edgeright, edgelow, edgehigh: edgecontrol is a single character that controls how the bounding box of the figure is handled. If it is 'n' then the bounding box will be the page parameters defined in constants inside the program (llx, lly, urx, ury AND changes as set by the previous parameter line). If the parameter is 'p', there are four real numbers that define the edges around the clist in cm. To allow a map to be imbedded into another figure, its size must be defined in PostScript (with %%BoundingBox). By setting these four numbers, the edges are defined. Negative values are allowed, so one may move the edges as desired. (New as of 2003 Aug 22) xyout: regression results, ready for PostScript input. (See technical notes.) xyplom: A file containing definitions of additional symbols, written in PostScript. The symbols must be of the form: /mysymbol { % xsize ysize mysymbol - % xsize x size in points % ysize y size in points /xsize exch def /ysize exch def ... } bind def Xyplo translates to the proper location and sets the color before calling the routine. This allows the xyin file to control the color of the symbols, but of course it can be overridden by the user's routine. It is even possible for the symbol to use both colors! Be sure to define the symbol in the xyplop. If the xyplom file is empty, there are no user defined symbols. FONT CONTROL (New as of 2010 Oct 26) %F If the xyplom file contains any line starting with '%F' then the user defines the font. %T If the xyplom file contains any line starting with '%T' then the user can scale the tic marks on both axes. %X If the xyplom file contains any line starting with '%X' then the user can scale the tic marks on the X axis. %Y If the xyplom file contains any line starting with '%Y' then the user can scale the tic marks on the Y axis. %x If the xyplom file contains any line starting with '%x' then the user can move the x label up or down (cm). %y If the xyplom file contains any line starting with '%y' then the user can move the y label up or down (cm). %W If the xyplom file contains any line starting with '%W' then a white rectangle is written on the background. If figure is converted to a jpg using the ImageMagick convert program, the background will not be black. The white rectangle is determined from the bounding box. You can control the bounding box using edgecontrol. Example: %F % font control from xyplom /Helvetica-Bold findfont 16 scalefont setfont 2 setlinewidth % sets linewidth %T 1.5 % tic mark scale factor warnings: extensive warning messages. These get in the way if they go to output. One line appears on the output file if there are any warnings. output: messages to the user description The data in the xyin file are converted to graphics in the PostScript language on the xyout file, under control of the parameters set in xyplop. There are several distinct sections of the parameters: 1. The first set of parameters determine the overall characteristics of the graph. 2. The second set of parameters defines the columns of xyin to be read. 3. The next section of the parameter file defines one or more symbols to be plotted on the graph. If desired, a linear regression is performed between the data columns, and this may be graphed for each symbol. The invisible option allows one to obtain the regression data without the graph. Regression data include the correlation coefficient and Fisher's z'. 4. A section with just a period ends the symbols section. 5. The last section contains lines you define. Recommended procedure for using xyplo: obtain a copy of xyplop.demo and xyin.demo, set permission to read them for yourself (on a Unix system use chmod), and copy them to the names xyplop and xyin. Try them out as is. If you don't get a graph, doing your own data will not do any good! Then convert the xyplop to your own use by changing the xyplop.demo file and substitute your xyin file. This way the complexity of xyplop can be held at bay. see also Basic example files: xyin, xyout, xyplop, xyplom, Standard parameter file: xyplop.std Demonstration examples: xyplop.demo, xyin.demo, xyplop.test, xyin.test, xyplop.mul, xyin.mul, xyin.logs xyplop.xn xyplop.xl xyplop.xL xyplop.yn xyplop.yl xyplop.yL xyin.genbank xyplop.genbank Related program - generate histogram: genhis.p Related programs - graphics routines: dops.p doodle.p Technical note: To define the bounding box for the graph must be defined. The postscript program https://alum.mit.edu/www/toms/ftp/printerarea.ps will give the values for your printer. substitute in the values at %%BoundingBox Xyplo now accepts the '#' as the start of a comment so that data files can also be used for gnuplot. See: http://www.gnuplot.info/ Confidence Limits for the Correlation, Fisher's z': http://sportsci.org/resource/stats/sscorr.html#fisherz who says that to get the confidence limits of the correlation coefficient, "use the Fisher z transformation: z = 0.5log[(1 + r)/(1 - r)]. The transformed correlation (z) is normally distributed with variance 1/(n - 3), so the 95% confidence limits are given by z ± 1.96/sqrt(n - 3). You then have to back-transform these limits to correlation coefficients using the equation r = [(e^(2z) - 1)/(e^(2z) + 1)]." See also: Fisher RA (1921). On the probable error of a coefficient of correlation deduced from a small sample. Metron 1, 3-32. http://davidmlane.com/hyperstat/A50760.html author Thomas Schneider technical notes The program originally generated output in the pic format. One could then run this through pic and troff to produce a graph. However, the program has been modified to eliminate the pic notation (by substituting modules from dops rather than domods). All lines outside the graphics now are preceeded by a %, which is beginning of a comment in PostScript. Thus the output of the program can be run directly into a PostScript interpreter. This saves on both memory and speed of graphing since the intermediate file is no longer created. Colors in PostScript are defined with hue, saturation and brightness with the sethsbcolor function. (Xyplo does not use red, green, blue model because it does not give the most useful continuous scale, though maybe someday I'll put in a switch.) The standard hue runs from red at 0 to red at 1 with the Roy G. Biv in between. (The famous physicist Roy G. Biv stands for: red, orange, yellow, green, blue, indigo, violet, the colors of the spectrum. On 1992 September 16 I realized that, amazingly, the wavelength in nm match quite nicely! 700 red 750 orange 600 yellow 650 green 500 blue 550 indego 400 violet Ok, Ok, back to xyplo! Since the hue runs in a circle, the spectrum is not generated from the hue range 0 to 1. Xyplo therefore converts the input numbers by multiplying by 0.84 and adding 0.16. This gives the color range from yellow through red corresponding to values 0 to 1. (Note: adding 0.16 give the range from yellow through red, but that is not a spectrum which runs from red through violet.) As of version 8.50 (1996 March 21) the xyplo program now uses cm (YEA!) which means that ALL previous graphs are out of date. If you happen to be stuck in a backwards, primitive country, tough luck. Bite the bullet. Minor unobvious things have prevented people from getting graphs. Most problems occur when badly formed xyplop files are used, and the program has no way to tell what the difficulty is. More checks have been put it, so the program can detect most oddly formed xylop and xyin files. Check your xyplop carefully. Setting the Default Printer Area: The size of the page in PostScript is determined with 4 constants llx, lly, urx and ury. These must be set correctly for each printer. These can be easily obtained by printing the file: https://alum.mit.edu/www/toms/ftp/printerarea.ps In this program these parameters are set as 4 constants defaultllx, defaultlly, defaulturx and defaultury. The parameters for page edges define whether to use the defaults or to compute the size to show. bugs ENHANCEMENTS: * xyplo should apply a PostScript to clip everything outside the drawing area * xyplo has a numerical drift problem. For extremely large numbers of data points, the computed position differes from the position rendered by PostScript. This should be corrected by using gsave and restore, but it is not clear how to modify the draw routines to do this cleanly. As it is the program tracks the location of where it THINKS it is on the graphical display. ENHANCEMENTS: * xyplo: cannot handle error bars in log mode * xyplo: user defined lines have to be type l?? * xyplo: define symbols in postscript - should speed graphics a lot * xyplo bug: when the last line of the file is empty, the program halts (that's fine). The count of the location of the error does NOT include the * lines though! Yet it says: "at line 27 of data (INCLUDING * lines)" Correct this. * xyplo bug from Mark (email 1992 May 27) *) (* end module describe.xyplo *) {This manual page was created by makman 1.45}{created by htmlink 1.62}