Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

GENHSTPLT(1)							  GENHSTPLT(1)

NAME
	genhstplt - to plot histograms and 2-D plots on screen or paper

SYNOPSIS
	genhstplt

DESCRIPTION
  GENHSTPLT is a general-purpose interface to the BSHST and BSPLT histogram
  and 2-dimensional data plotting routines.  See the documentation of those
  routines (bshst(1) and bsplt) for instructions on operating them.
  
  The data file may have 1 or more columns of data values for each
  individual.  Before the first column of data, one may place a "type"
  value for each individual.  One can then form "groups" of values
  by combining individuals of one or more types.  If there are no type
  values, then there is only one group, consisting of all individuals
  in the file.  The actual type values are completely arbitrary and
  need not be 1, 2, 3, etc.  Once groups are formed, they are referred
  to in order as 1, 2, etc.
  
  The file may have lines at the beginning which can be skipped by the
  program.  The number of columns of data values (exclusive of the
  optional type value) may be put in the file, in the line just before
  the data begin, or it may be entered into the program interactively.
  
  Symbol types are selected by number, but the numbers have different meanings
  for symbols in the graphics window and in the Postscript printing
  file. Symbols 1 to 8 will appear on the screen as: filled and open circle,
  filled and open square, filled and open triangle, X and +; the same pattern
  repeats for numbers above 8.  Symbols 1 to 19 are available for Postscript
  output and appear as open and filled square (1 & 2), open and filled diamond
  (3 & 4), open and filled triangle (5 & 6), X and + (7 & 8), open and filled
  circle (9 & 10), open and filled inverted triangle (11 & 12), U (13), S
  (14), circle with vertical line (15), thick open circle (16), circle with
  central dot (17), small dot (18), and horizontal line (19). 0 will give no
  symbol; a negative value will produce the characters corresponding to the
  point number for each data value instead of a symbol; except that -2 will
  produce completely filled areas in histograms.

  Entries to the program are:

  0 for plots in the graphics window, or 1 for plots only on the terminal.
     Note that if you need to use terminal plots, you will need to specify
     that option each time that you do a plot.
  
  0 if there are just data values, or 1 if there are also types
  
  Number of columns of data values (excluding the optional types).
     Enter 0 if the number of columns is to be read just before the
      data.
  
  Number of lines to skip at start of file.  Do not count the line
     telling the number of columns, if there is one and you just
     entered 0 to the last question.
  
  Data file name
  
  IF there are types, next enter:

     Number of groups.  Enter the negative of the number of there is
        only one type per group, as a shortcut.

     IF you entered a positive number, then enter for each group:

        Number of types in group, symbol number
        The type values for the types in the group
  
     BUT IF you entered a negative number, then enter for each group
        the type value and the symbol number
  
  IF there are no type values, just enter the symbol number to be used.
  
  Next enter the column number of the data to be examined next.
  
  Next specify how the data are scaled:
     To leave the data alone, enter 0,0
     To take the logarithm after adding some base amount to the data,
        enter 1 and the base amount
     If the data are already logarithms, enter -1,0
  
  The program now enters BSHST, which you can skip through if desired.
  
  You are now at an option point, which you may return to repeatedly
  while running the program.  Your choices are:
  
     1 to examine a new data column
     2 to enter BSPLT and plot the column just examined as a set of Y
        values versus the previous column, as a set of X values.
     3 to plot the column just examined versus the previous column,
        first grouping points within each group on the basis of their
        X values and forming means and standard deviations within
        groups (see below)
     4 to loop back and define new groups and/or symbols
     5 to loop back to the start of the program and open a new file
     6 to plot the current Postscript file on workstation screen
     7 or 209 to plot the current Postscript file on printer
     8 or -123 to exit the program
     9 to plot the column just examined versus the previous column as
        series of Tukey box plots, one Tukey box per group.
     10 to plot values with error bars based on S.D. values in another
        column of the data file.
     11 to group points based upon their X values in the previous
       column (as in option 3) and then divide the average of the
       current column by the average of some other column
     12 to select subsets of the data based on the values in some
       other column than the ones being plotted
  
  If you select option 3, you first choose whether to plot error bars
  as a multiple of standard deviation or standard error of the mean,
  or as confidence limits.  Enter a positive number to get bars equal
  to that number of S.D.'s, or a negative value to get bars equal to
  that number of S.E.M.'s, or a positive number greater than 30 to get
  confidence limits at that percentage level (e.g., 90 for 90%
  confidence limits).  Then, for each group of types, you will be told
  how many data points there are.  Enter the number of groupings that
  you want to combine these points into, then enter the number of
  points to include in each of the groupings, or just a / to divide
  the points equally among the groupings.  If you enter individual
  numbers for each grouping, they should add up to the total number of
  points in that group of types.

  If you select option 9, then when the data are plotted on the
  printer, they will appear as Tukey box plots for each group.
  Each such box shows the median and 25 and 50 percentile values of the
  set of Y values for the group; lines and ticks show the 10 and 90
  percentile points, and symbols are plotted for any data values
  outside the 10 and 90 percentile levels.  The box is plotted at the
  mean X coordinate of the points in the group.
  
  If you select option 10, you first choose whether to plot error bars
  as a multiple of standard deviation or standard error of the mean,
  or as confidence limits.  Enter a positive number to get bars equal
  to that number of S.D.'s, or a negative value to get bars equal to
  that number of S.E.M.'s, or a positive number greater than 30 to get
  confidence limits at that percentage level (e.g., 90 for 90%
  confidence limits).  If you select S.D.'s, next enter the column
  number in the data file that contains the S.D.'s.  Otherwise, enter
  two column numbers: the one with the S.D.'s and one with N's.  Both
  of these parameters are needed to plot S.E.M.'s or confidence limits.
  
  If you select option 11, you first enter a value for error bars as
  in option 3.  Then enter the column to divide the current column by.
  Then specify the groupings of points for each group of data.  The
  default groupings will have nearly equal SUMS for the denominators.
  The program will compute and print out for each set of points the
  following values: mean of previous column (X), mean of current
  column, SD of current column, mean of denominator column, mean of
  current divided by mean of denominator column (Y), SD of current
  divided by mean of denominator (SD associated with Y), and number
  of points in the set.  Error bars based on the resulting SD values
  may or may not be meaningful depending on the nature of the data.

  If you select option 12, first enter the number of the column that
  will be used to test whether to include data.  Then enter a lower
  and upper limit to a range of values, plus either 0 to include only
  values in that range, or 1 to exclude values in that range.  Use this
  option repeatedly to enter multiple selection criteria.  Data points
  will have to meet all of the criteria to be included in the plots.
  After entering one or more selection criteria, you must select data
  by specifying columns with option 1.  To cancel all of the criteria,
  specify option 12 and enter 0 for the column.

HISTORY
	  Written by David Mastronarde, has wandered from one computer to the
	next over the years.