genhstplt(1) General Commands Manual genhstplt(1)
NAME
genhstplt - to plot histograms and 2-D plots on screen or paper
SYNOPSIS
genhstplt [graph options]
DESCRIPTION
Genhstplt is a general-purpose interface to the BSHST and BSPLT his-
togram 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 indi-
vidual. 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 can be detected by the
program as long as all the columns for an individual are on the same
line in the file. Otherwise, the number of columns (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.
Non-numeric text can be present after the last column of data.
Sometimes it is desirable to have one graph show two or more columns in
Y plotted versus the same column in X. If the data does not already
have type values, they may be rearranged so that each column becomes a
separate type. One column is chosen as the X column and is copied into
column 1 of the rearranged data, and all columns are copied sequen-
tially into column 2 of the rearranged data and given type numbers
equal to their original column numbers. This rearrangement can be done
when first reading in the data, or later by using option 15. The same
option can be used to restore the data to the original columnar organi-
zation.
Symbol types are selected by numbers from 1 to 19 and can be 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). As of IMOD 4.6.8,
the same symbols appear on the screen as in the Postscript plots,
except that 16 and 17 give open and filled circles. 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.
This is an interactive program that allows entries of one option after
another for plotting data in different ways. In many cases, you may
find it much more convenient to use Onegenplot, which displays a
single X/Y plot of one or more data types or columns specified with
command line arguments, then exits when the window is closed. Note
also that the graph window can be saved as a PNG file or printed from a
popup menu brought up by right-clicking in the window.
Genhstplt takes several standard command-line options about the graph-
ics window: -s followed by a window size in x and y, -p followed by a
window position in x and y (the coordinates of the upper left corner of
the window, where y is 0 at the top of the screen), -message followed
by a message to be shown in a message box, -tooltip followed by a
tooltip for the graphics window, and -nograph to disable the graphics
window.
Entries to Genhstplt are:
0 for plots in the graphics window, 1 for plots only on the terminal,
or -1 for plots always in the graphics window (default -1). If you
enter -1, this question will not be asked again and BSPLT will not
ask about doing terminal plots either. 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, or -1 to
have columns converted into types (default 0)
Number of columns of data values (excluding the optional types).
Enter -1 to have the number of columns detected automatically (the
default), 0 if the number of columns is to be read just before the
data, or enter the number of columns.
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 you entered -1 to have columns converted into types, and there is
more than one column, next enter the column to be placed into the first
column in the rearranged data.
IF there are types, next enter:
Number of groups. Enter the negative of the number if 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, first saving the current column as
the "previous" column
2 or 17 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. With 17,
successive points in a group will be connected by lines.
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
13 to divide the current data column by another column
14 to examine a new data column while retaining the existing X values,
i.e., without copying the current column into the "previous" column
15 to reorganization data without types to have one type per column, or
to restore data from this reorganization
16 to create an ordinal column, with values from 1 to the number of
points in a group for each group
18 to form a linear combination of two or more columns
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 per-
centile 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. Bars will not be drawn for S.D.
values less than 0.
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 pro-
gram will compute and print out for each set of points the following
values: mean of previous column (X), mean of current column, SD of cur-
rent column, mean of denominator column, mean of current divided by
mean of denominator column (Y), SD of current divided by mean of denom-
inator (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 enter-
ing 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.
If you select option 13, first enter the number of the column to divide
by, then enter lower and upper limits for the quotient, or 0,0 not to
limit the quotient. The current data column is not replaced, so you
can use this option repeatedly to divide the current data column by
different other columns.
Option 16 is useful for graphing a sequence of values when the data
file does not contain a column suitable for the X axis. This option
will create numbers in the current column from 1 up to the number of
items in each group . You will then have to use option 1 to select a
new column for the Y axis, and the ordinal values will be moved into
the "previous" column to serve as the X axis.
If you select option 18, enter a series of pairs of numbers, first a
coefficient then a column number, all on one line. For example,
"0.5,1,0.25,2,0.25,4" will form a weighted average of columns 1, 2, and
4 with wieths 0.5, 0.25, and 0.25. Coefficients need to add to one or
be positive. After entering this line, enter 0 to have to current Y
axis data be moved to the X axis as usual, or 1 to replace it and
retain the existing X axis data.
There are several additional options to control plotting, most of them
used by Onegenplot; options -4 and -5 are also generally useful if
making postscript plots:
-2 Enter X axis label and symbol key strings to appear to right of graph.
Follow with the X axis label or blank for none, then with the number
of key strings (between 0 and 8), then with the key strings on
separate lines.
-3 Invert display contrast to be white lines on black background, or back
to black on white.
-4 Enter a set of colors for selected groups, which will be applied for
symbols, lines in both screen plots and postscript plots. First
enter the number of colors to be entered; 0 eliminates all color
drawing. Then enter 4 values that number of times: a group number
(numbered from 1), and red, green, and blue components ranging from 0
to 255. A color will be ignored for the main graph and for key
symbols if the graph has fewer groups than the color's group
number. A color can be entered more than once if it needs to be
specified for both a text string and a line with option -5.
-5 Enter the index of a text string to apply a color to for each color
entered with -4; the colors will be used for the text strings that
can be added to a postscript plot. Or, enter the negative of the
index of a line drawn by psMiscItems to apply a color to that line.
-6 Enter a new value for the gap in connecting lines round symbols in
postscript plots, or 0 for no gaps. The value is multiplied by the
symbol size to obtain the actual gap; the default is 1.1.
-7 Enter a file name into which to save the graph window as a PNG;
the name should include the extension since it will not be attached
automatically.
-8 Wait until the graph window is closed then exit
-9 Enter the lower and upper limits of the Y range for the screen
graph. The usual rounding to nice values still applies.
-10 Enter the lower and upper limits of the X range for the screen
graph.
-11 Remove the input data file
-12 Print the message on the next input line
-13 Enter a file name into which to save the graph window as a TIFF,
including extension.
HISTORY
Written by David Mastronarde, has wandered from one kind of computer and
graphics to another over the years.
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.0.2 genhstplt(1)