{ version = 2.23; (* of denplo.p 2022 May 04}
(* 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. Note: values larger than 1
will cause overlapping squares, so something like 1.01 will
slightly overlap the squares, guaranteeing that there will be
no space at all between them.
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:
https://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:
https://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.45}
{