.na
.nh
.TH bshst 1 4.6.34 IMOD
.SH NAME
BSHST - an interactive histogram plotting routine called by Genhstplt
and other programs
.SH DESCRIPTION
Subroutine BSHST plots histograms of values belonging to one or more
groups, in a graphics window, on the terminal, and to a Postscript file.
.P
Values that must be entered:
.P
First indicate what you want to do with the subroutine:
0 to skip right through the subroutine
1 to look at histograms
2 to compute means and SD's and return from the subroutine
209 to plot out the current contents of the metacode file and
return from the subroutine.
-123 to terminate the program
.P
The program will then tell you the minimum and maximum values and the
total range. If your values are logarithms, it also tells you
the minimum and maximum of the actual values.
.P
Next enter the value at the bottom of the lowest bin, the bin
width, and the number of bins. The lowest value must not be
greater than the minimum value which the program has just informed
you of. If your values are logarithms, then your lowest value
should be an actual (linear) value rather than the logarithm, but
the bin width must still be specified in log units.
NOTE: if you enter 0,0,N you will get N bins that span the
range of the data.
NOTE 2: Enter a negative bin width to do kernel smoothing with a
triweight kernel whose half-width h is the negative of the entered
value. In this case, the "number of bins" determines the width
of the graph, and a non-integer value can be usefully entered.
.P
The program tells you the number of counts in the biggest bin.
.P
Next enter either:
To get a plot in the graphics window, enter the desired count for
the full scale of the Y-axis, which should be bigger than the
highest bin, or
0 for a histogram on the terminal, or
-1 for a histogram on the terminal with bin labels
.P
IF you selected a terminal plot, the plot appears and you must enter
Return to continue
.P
Next enter an option to control output:
0 for none of these options
1 to type the value out on the terminal
-1 to write the values into a file
n+1 to draw n lines on a Postscript plot; e.g. 3 for 2 lines.
.P
IF you elect to write the data to a file, next enter a file name.
If the file already exists, the data will be appended to the file.
.P
At this point a histogram appears in the graphics window unless you
already had it on the terminal. The program tells you the range
of values corresponding to the X axis of the histogram.
.P
Next select one of these options:
0 to return to calling program
10 to loop back and and new lowest value, bin width, # of bins
4 or 5 for Postscript plot on upper or lower half of page
11-16 for Postscript plots in one of 6 positions (11-13 is
left column top to bottom, 14-16 is right column)
6 for Postscript plot with complete control of size, position,
and other parameters
7 for plot with complete control of parameters, and some groups
plotted below the X-axis
Enter the negative of a plot number to get a histogram without
a symbol for each data point.
.P
IF you selected a plot other than 7 and the "full scale count"
entered above is less than the number of counts in the highest
bin, the program next asks you to enter the full scale count again
.P
IF you selected plot 7, the program requests the following:
.P
The number of groups to place below the X-axis
.P
The group numbers of those groups (groups are numbered
sequentially from 1, regardless of the "type" values that were
used to assign values to different groups)
.P
The program next informs you of the number of counts in the
biggest bins above and below the X-axis and wants you to enter
full scale counts for the Y-axis above and below the X-axis
.P
IF you selected 6 or 7, next enter the following:
.P
Size of plot area in X and Y, and lower left X and Y coordinates,
(in inches), and number of ticks along the X and Y axis.
Enter the negative of the lower Y coordinate to offset the
horizontal grid lines from the edge of the graphing area.
For a linear axis, the "number of ticks" is actually the
number of divisions along the axis; but for a logarithmic
axis, it is the number of tick marks, which is the number of
divisions plus 1. Sorry.
Enter negative the number of ticks to get unidirectional ticks.
.P
Symbol size, tick length (inches), line thickness for the axes,
for the histogram, and for the symbols (small integers), and 1
for a box (axes on the top and right). If you selected
unidirectional ticks, positive and negative tick lengths give
ticks toward the inside and outside of the box, respectively.
.P
IF you entered a negative lower Y coordinate, enter the amount to
offset the horizontal grid lines in the Y direction
.P
1 for a new page, or 0 to plot on the same page as previous graphs
.P
IF you are plotting and the values are logarithms, enter the actual
values (not the logarithms) at which X ticks should be drawn
.P
IF you are plotting and said that you wanted to draw some lines,
next enter the specification for each line. The format is:
Slope (Y/X), Y-intercept, starting and ending X coordinate (all
in your units, not inches), line thickness (small integer), and
0,0 for a solid line or length of dash and length between
dashes for a dashed line. If you enter the negative of line
thickness, then X and Y are inverted, so the entries are the
X/Y slope, the X-intercept, and the starting and ending Y
coordinates.
.P
IF you selected graph 6 or 7, then you can next make many entries to
label the axes and add other symbols and lines to the graph.
.P
First, for the X axis, enter:
.P
# of ticks to label with numeric labels, and number of lines of
text labels.
.P
IF you specified a nonzero number of ticks to label, next enter:
.P
If the ticks are to be labeled at regular intervals, enter the
number of the first tick to label (first tick is #1) and
the interval between labeled ticks (e.g. 2 for every other
tick or enter 0,0 to specify a list of ticks to label.
.P
IF you entered 0,0, next enter the #'s of the ticks to label
.P
Labels for the ticks, in one line, separated by commas or spaces
.P
Numeric label size and separation from axis, in inches
.P
IF you specified a nonzero number of text labels, next enter for
each label in turn:
.P
Text label size, separation from axis, and offset along axis
between center of axis and center of text.
.P
Text label
.P
Next enter these parameters in the same order for the Y axis
.P
Finally, the program calls the IMMISC subroutine. Here, coordinates
may be specified in one of three ways independently for each of
the entries to the program. The coordinates may be in "user"
units (the units of the numbers being graphed), in absolute units
of inches on the plotter page, or in units relative to the frame
of the graph (e.g. 0.1,0.9 for a position in the upper left
corner, or 0.5,1.1 for a position centered above the graph frame).
.P
Enter the number of text labels, # of letters in circles,
# of symbols in boxes, and # of dashed or solid lines to draw
.P
IF you entered a non-zero # of text labels, then for each, enter:
.P
X and Y position, and 0 for user or 1 for absolute or -1 for
relative units
.P
0 to center, -1 to left justify, or 1 to right justify the
character string on this position
.P
Size of characters in inches, and orientation angle in
degrees (usually 0 or 90)
.P
Text, on one line
.P
IF you entered a non-zero # of circled letters, then for each:
.P
X and Y position, and 0 for user or 1 for absolute or -1 for
relative units
.P
Diameter of circle in inches, line thickness
.P
Size of character in inches
.P
Letter (upper case)
.P
IF you entered a non-zero # of boxed symbols, then for each:
.P
X and Y position, and 0 for user or 1 for absolute or -1 for
relative units
.P
Symbol type (or 0 for no symbol), symbol size in inches,
symbol thickness (a small integer), box size in inches
(or 0 for no box), box line thickness
.P
IF you entered a non-zero # of lines, then for each, enter:
.P
0 for user, 1 for absolute, or -1 for relative units
.P
A line specification as described above, in the units just
indicated
.P
NOTE FOR SIMPLEST USE: if you just want standard graphs, enter:
1 for histograms
Lowest value, bin width, # of bins
Full scale count
0 for no type out
0 return, 10 replot, or 4 or 5 or 11-16 for Postscript plots
1 for new page as needed
.SH BUGS
Email bug reports to mast@colorado.edu.