Delila Program: denplo

denplo program

Documentation for the denplo program is below, with links to related programs in the "see also" section.

{   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:
   image for denplo

   --------------------------------------

   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}
{created by htmlink 1.55}
U.S. Department of Health and Human Services  |  National Institutes of Health  |  National Cancer Institute  |  USA.gov  |  Viewing Files  |  Accessibility