**
**

{ version = 2.20; (* of denplo.p 2014 Mar 28} (* begin module describe.denplo *) (* name denplo: density plot in color synopsis denplo(data: in, denplop: inout, denploxyin: out, denploxyplom: out, denploxyplop: out, output: out) files data: data pairs denplop: parameters to control the program. The file must contain the following parameters, one per line: 0. parameterversion: The version number of the program. This allows the user to be warned if an old parameter file is used. 1. numbertoprocess: number of data items to process (negative = all) This allows the user to explore a part of a large data set before committing to a long process time. I suppose it would also allow you to make a movie of the data building up! 2. XminValue, XmaxValue, Xintervals: (real, real, integer) range for x, and the number of intervals 3. YminValue, YmaxValue, Yintervals: (real, real, integer) range for Y, and the number of intervals 4. NuWi, NuDe: (integer) define the width and decimal places of output numbers. NuWi = 1, Pascal will give the number out anyway! This is a big space saver. 5. Xcolumn, Ycolumn: (integer) column numbers for X and Y data. They can be in any order. 6. Xsize, Ysize: (real) size of the plotting area, cm. 7. Xcorner, Ycorner: (real) lower left corner of the plotting area, cm. 8. XDisplayIntervals, YDisplayIntervals XDisplaySubIntervals, YDisplaySubIntervals : (integer) Number of numeric intervals for xyplo to display on the axis This keeps the number of numbers on the side of the graph reasonable but does not affect the graph itself. It allows one to have a highly dense plot without labeling every data interval. If one of the DisplayInterval values is less than or equal to zero, then the corresponding bin interval will be used. For example, if XDisplayIntervals = 0 then the display interval used will be given by the value of Xintervals. Sub intervals apply all the time. 9. xwidth, ywidth: (integer) axis number width 10. xdecimal, ydecimal: (integer) axis number decimals 11. background, grey (character, real) color to give when there are no data: b = black g = grey; the grey value is given (between 0.0 and 1.0) w = white c = colorful. For debugging: a complex formula is used to change the colors of squares over the background so one can debug the program. Data are plotted on top of this. So most of the time this option is not useful to people. For white no background square needs to be written, so it isn't. When there are sparse data above the cutoff, this option can be extremely efficient because very little data needs to be written to the denploxyin file. For black, grey or colorful every square is written all the time. 12. cutoffvalue (character, real, [real]): The first character on the line defines the kind of cutoff: 'c': use the number of counts in a bin (one value used) 'f': use the fraction of this bin to the fullest bin (one value used) 'C': range of counts to plot (two values needed) 'F': range of fractions to plot (two values needed) For 'c' and 'f', only one number is needed. The number is the cutoff value. Counts are reported for values higher than or equal to the cutoff. For example, in c mode a zero cutoff will have denplo display cases with 0 or more counts. For 'C' and 'F', two numbers are need, this is the range of counts or fractions to use. 2009 Apr 11: cutoff values are now inclusive, so if a count is 5 and the range is 5 to 10 it will be plotted. 13. shrinkfactorX, shrinkfactorY (real): numbers above zero A value of 1 will make the display be completely covered while one less than 1 will leave gaps that allow one to distinguish between the squares. 14. XaxisLabel: (string, entire line): the label for the x axis. 15. YaxisLabel: (string, entire line): the label for the y axis. 16. cog: (character): color or grey The first character on the line defines the value: 'c': use colors in the spectrum 'g': use grey scale COLOR KEY DISPLAY CONTROLS The color key is a set of rectangles surrounded by a black edge. To the right are numbers that report the density. The numbers can either report the number that the color corresponds to or the density relative to the highest density in the plot. The key is placed into the denploxyplom file where it can then be passed to xyplo as a xyplom file. 17. keyintervals: The number of boxes in the key will be keyintervals+1 (to allow for a zero). If keyintervals is zero, then no color key is shown. Example: To get boxes numbered 0.0, 0.0 ... 10.0, use 10 for keyintervals. 18. keytype (character): f: fraction of maximum, n: raw number. The way to display the key numbers. 19. keyX: X coordinate of the lower left corner of the key (cm) 20. keyY: Y coordinate of the lower left corner of the key (cm) 21. keyXsize: X size of key boxes (cm) 22. keyysize: Y size of key boxes (cm) 23. keyshrinkfactor: a number between 0 and 1 which defines how much the key boxes should shrink. 24. thelinewidth: the width of a line around each key box (cm) If thelinewidth is zero than the line is the default width. If less than zero, no line is drawn. 25. keydecimals: number of decimal places for the numbers placed to the right of each key box. 26. keyfontsize: the font size for the key numbers. 10 is a good place to stat. 27. 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. FINDING LOCAL PEAKS 28. findpeak, startX, startY, SearchRange: l: findpeak is a single character for which 'l' means to search for a local peak starting at coordinate (startX, startY) instead of using the global maximum. If the local peak found is not the global maximum, then positions that have more counts than the local peak are shown by black. The search is made in a series of squares, starting at (startX, startY). The side of each square is determined by SearchRange: side = 2*Searchrange+1. That is, if SearchRange = 0, the side is 1 and the peak is set at (startX, startY). When SearchRange = 3, the side is 3 and 9 positions are searched. The square is moved to the position that has the highest local density. This is repeated until no higher position is found. The algorithm is deterministic (no random numbers are used) and the result may depend on the order of scanning the square. maxpeak, BinMax: m: If the first character is 'm' then instead of finding the peak the second parameter is used for the maximum BinMax. This allows one to force the maximum color to be a particular value and so allows comparison of plots on the same scale. 29. yaverage, shrinkYav: (character, positive real) if 'y' then compute the average of y values in the bins and display. The average is shown by a black bar with width the width of the displayed rectangles. The height of the bar is determined by shrinkYav. shrinkYav is the factor by which to scale the bar vertically. If shrinkYav = 1, then the bar will be the same size as the display rectangles. (Note that its position will vary up and down depending on where the average is so it will not necessarily match the rectangles.) If shrinkYav = 2 then the bar will be half the size of the rectangles (vertically). 30. zxl xbase if zxl='l' then convert the x axes to a log scale using the indicated base. 31. zyl ybase if zyl='l' then convert the y axes to a log scale using the indicated base. The resulting log plot is very pretty! 31. smoothkind (char), smoothsize (real) If smoothkind is '-' then no smoothing is done. If smoothkind is 's' then smoothing is in a square. A square of side smoothsize cells is averaged and placed into the center (if smootsize is odd) or to the positive side (if smoothsize is even). Once the data are collected into the first array, they are averaged into a second array of the same size as the first array. The edges are lost (set to zero) depending on the size. The second array is then printed. denploxyin: control file for xyplo: density of data pairs represented in color. Copy or link this file to xyin. denploxyplom: control file for xyplo: a postscript file that contains marks. It also contains the color key if that is being used. Copy or link this file to xyplom. denploxyplop: control file for xyplo: parameters Copy or link this file to xyplop. Documentation is in the xyplo.p program. output: messages to the user description Denplo takes a file containing pairs of numbers and (using the xyplo program) plots the density of the numbers in color. The user specifies a rectangular region on the X-Y plane. Then each axis is divided into the number of intervals requested by the user. These define a set of data bins onthe X-Y plane. The data are dropped into the bins and counted. The output of denplo consists of the three files that control the xyplo plotting program. For example, one output file is called a denploxypop = a denplo xyplop = density plot, x-y plotter parameter file. This is pronounced 'den-plo-zye-plop'! The denploxyin is 'den-plo-zin' and the denploxyplom is 'den-plo-zye-plom'. :-) Since these are not the names used by xyplo (so that xyplo files are not overwritten), you need to copy (Unix cp) or move (Unix mv) them into the names that xyplo uses: cp denploxyin xyin cp denploxyplom xyplom cp denploxyplop xyplop Then you can run xyplo to get the xyout (xy-out = 'zyout'), which is a eps PostScript file. examples example denplop file: 1.88 0. parameterversion: denplo version this parameter file is designed for -1 1. numbertoprocess: number of data items to process (negative = all) 0 10 10 2. XminValue,XmaxValue,Xintervals: (real,real,integer) X range,ints 0 10 10 3. YminValue,YmaxValue,Yintervals: (real,real,integer) Y range,ints 8 5 4. NumberWidth, NumberDecimals: (integer) 1 2 5. Xcolumn, Ycolumn: (integer) column numbers for X and Y data. 10 10 6. Xsize, Ysize: (real) plotting area, cm 3 7 7. Xcorner, Ycorner: (real) lower left corner of the plotting area, cm. 10 10 2 2 8. X/YDisplayIntervals X/YDisplaySubIntervals 8 8 9. xwidth, ywidth: (integer) axis number width 0 0 10. xdecimal, ydecimal: (integer) axis number decimals g 0.9 11. background: b = black, g = grey, w = white, c = colorful (debug), c 0 100 12. cutofftype [c,f,C,F] cutoffvalue(min and max) 0.8 0.8 13. shrinkfactorX, shrinkfactorY (real) X axis label Y axis label c 16. cog: color or grey plot 5 17. keyintervals: # of boxes in the key (not including the zero) n 18. keytype (character): f: fraction of maximum, n: raw number. 10.2 19. keyX: X coordinate of the lower left corner of the key (cm) 0.1 20. keyY: Y coordinate of the lower left corner of the key (cm) 0.5 21. keyXsize: X size of key boxes (cm) 1.0 22. keyYsize: Y size of key boxes (cm) 0.8 23. keyshrinkfactor: between 0 and 1: box shrink. 0.005 24. thelinewidth: the width of a line around each key box (cm) 1 25. keydecimals: number of decimal places for the key 12 26. keyfontsize: the font size for the key numbers p 1.50 2.50 1.50 1.50 edgecontrol, edgeleft, edgeright, edgelow, edgehigh cm - 0 0 28. findpeak(l), startX, startY, SearchRange | maxpeak(m), BinMax see also Example data file (copy to 'data' to use): denplo.data Example Parameter file: denplop Given these two files, you can run denplo. To do this: cp denplo.data data denplo cp denploxyin xyin cp denploxyplom xyplom cp denploxyplop xyplop followed by running xyplo.p : xyplo The final results use the general plotting program: xyplo.p The resulting example density plot is: -------------------------------------- a larger example, with large key scale: denplop.ri-example -------------------------------------- Information about PostScript: http://alum.mit.edu/www/toms/postscript.html This describes how to convert from PostScript to PDF. Program that describes label controls: makelogo.p See bugs for further information on this partially implemented feature. How to make a movie: http://alum.mit.edu/www/toms/paper/ev/movie/ Related density program: denri.p Information about the color hue formula: diana.p xyplo.p author Thomas Dana Schneider bugs Smarter crosshairs: xyplo needs an upgrade so that the crosshairs can be put in for x and y and independently the x and y axes. Then this program could control them. One could implement strings like '\c' within the axes labels to produce data counts into the labels. (A mechanism like that in makelogo could be used.) \t total counts \b maximum bin count \i start italics and end italics The function in makelogo is putreal, inside module makelogo.postscriptstring in makelogo.p. This routine is now in the program but not fully integrated so \t and \b are not available yet. You can, however, do italics and special symbols; instructions are in the makelogo.p program. technical notes Constants set in the program: maxValue is the largest number of allowed bins allowed on each axis. Postscript hue colors range from red (at 0) to red (at 1). To avoid this ambiguity, only part of the hue range is used. I have found that this formula is useful for 0 <= r <= 1: hue := 0.84*r + 0.16. See diana.p and xyplo.p module pic.setcolor. The denploxyplom has this correction built in since the xyplom is not color corrected. For this reason, the values in the color scale in denploxyplom will not match those in the denploxyin. However, when plotted with xyplo they are identical. The edge control method is from xyplo.p. *) (* end module describe.denplo *) {This manual page was created by makman 1.44}

U.S. Department of Health and Human Services | National Institutes of Health | National Cancer Institute | USA.gov | Viewing Files | Accessibility