Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

BSHST(1)							     BSHST(1)

NAME
	BSHST - an interactive histogram plotting routine called by GENHSTPLT
		and other programs

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.
  
  Values that must be entered:
  
  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
  
  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.

  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.
  
  The program tells you the number of counts in the biggest bin.

  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
  
  IF you selected a terminal plot, the plot appears and you must enter
     Return to continue
  
  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.
  
  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.

  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.
  
  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.
  
  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
  
  IF you selected plot 7, the program requests the following:
  
     The number of groups to place below the X-axis
  
     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)
  
     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
  
  IF you selected 6 or 7, next enter the following:
  
     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.
  
     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.
  
     IF you entered a negative lower Y coordinate, enter the amount to
        offset the horizontal grid lines in the Y direction
  
     1 for a new page, or 0 to plot on the same page as previous graphs
  
  IF you are plotting and the values are logarithms, enter the actual
     values (not the logarithms) at which X ticks should be drawn
  
  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.

  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.  

  First, for the X axis, enter:

     # of ticks to label with numeric labels, and number of lines of
         text labels.
  
     IF you specified a nonzero number of ticks to label, next enter:

       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.

           IF you entered 0,0, next enter the #'s of the ticks to label
  
       Labels for the ticks, in one line, separated by commas or spaces
  
       Numeric label size and separation from axis, in inches
  
     IF you specified a nonzero number of text labels, next enter for
         each label in turn:

        Text label size, separation from axis, and offset along axis
             between center of axis and center of text.
  
        Text label
  
  Next enter these parameters in the same order for the Y axis
  
  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).

     Enter the number of text labels, # of letters in circles,
         # of symbols in boxes, and # of dashed or solid lines to draw
  
     IF you entered a non-zero # of text labels, then for each, enter:
  
         X and Y position, and 0 for user or 1 for absolute or -1 for
             relative units 
  
         0 to center, -1 to left justify, or 1 to right justify the
             character string on this position
  
         Size of characters in inches, and orientation angle in
             degrees (usually 0 or 90)
  
         Text, on one line
  
     IF you entered a non-zero # of circled letters, then for each:
  
         X and Y position, and 0 for user or 1 for absolute or -1 for
             relative units 
  
         Diameter of circle in inches, line thickness

         Size of character in inches

         Letter (upper case)
  
     IF you entered a non-zero # of boxed symbols, then for each:
  
         X and Y position, and 0 for user or 1 for absolute or -1 for
             relative units 
  
         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
  
     IF you entered a non-zero # of lines, then for each, enter:
  
         0 for user, 1 for absolute, or -1 for relative units
  
         A line specification as described above, in the units just
             indicated

  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