imavgstat(1) General Commands Manual imavgstat(1)
NAME
imavgstat - Computes mean and SD images, and means in selected areas
SYNOPSIS
imavgstat
DESCRIPTION
Imavgstat generates statistics on the mean and standard deviation of
image density in selected areas of images that are obtained by averag-
ing multiple samples. It can also produce a new set of averaged images
that are all normalized to have the same average density in specified
reference areas. A set of images showing the standard deviation at
each pixel may also be produced and used for statistical analysis by
other programs such as SUBIMSTAT. Typically, the program would be used
to compare averages of different sample sets.
Before running the program, one uses IMOD to construct a model in which
each contour specifies a "summing region". A summing region may be
defined by either 2 points or 4 or more points. Four points define a
quadrilateral summing region (a 5th point to make the model contour
look like a quadrilateral is optional and is ignored by the program).
Two points define a line; the actual extent of the summing region per-
pendicular to this line is specified when one runs the program. This
model should be built on an image stack in which all of the images
being compared are aligned. More than 4 points can be used to specify
a region of complex shape.
The summing regions are used in the program in two different ways: to
specify the low and high density normalizing areas, and to specify the
summing areas, areas that are being compared between images.
The normalizing areas are used to scale the averages from all of the
different sample sets so that the mean density in the low area is 0 and
the mean density in the high area is 100. Each of these two areas may
be a combination of more than one summing region. However, all of the
regions used to specify a low or high normalizing area must be
described by contours of at least 4 points. If you do not want the
densities normalized, enter one contour for the low normalizing area
and the same contour for the high normalizing area. In this case,
average densities will have the same scaling as the original data.
Summing areas may be whole summing regions or subdivisions of summing
regions. When running the program, one specifies the number of summing
areas that each region should be divided into. If a region is a
quadrilateral, it will be divided into areas by lines parallel to the
short axis of the quadrilateral. A region specified by 2 points will
be divided into areas at points equally spaced along the line connect-
ing the two points. The shape of those areas is specified by a single
parameter: 0 for circular areas; 1 for square areas with edges parallel
and perpendicular to the connecting line; or, for rectangular areas,
the ratio of width to height (height being the dimension parallel to
the connecting line). If you want to divide up a region with more than
5 points, then you must trace the region in a special way. Start at
one end of the region and trace one side along the long axis, with as
many points as needed to define the region adequately. At the other
end, add a single line segment to describe that end, then trace back
along the other long side, with the same number of points as on the
first long side, and with each point opposite the corresponding point
on the other side. Both short ends must thus be decsribed by a single
line segment.
You can divide a region into areas by specifying either the number of
areas to divide it into, or the desired width (in pixels) of each of
the subdivisions. In the latter case, you enter the negative of the
width in pixels.
The program has an option to produce an image file with different col-
ored pixels for each summing area; one can use this while learning how
to produce summing regions at desired locations.
The program can compute statistics and averages from unaligned samples
within each data set, applying any needed transformations in a single
step rather than in the 2 or 3 steps that would ordinarily be used to
get a series of aligned averages. The averages produced by this pro-
gram might thus be superior in quality or appearance. For each data
set, one can specify 1 or 2 sets of transforms that are needed to align
all of the samples within the data set. If multiple data sets are
being used (or if the summing region model is built on an average that
was transformed to align with other averages), then one must specify in
addition the G transform applied to the average to align each data set
with other averages or with the model.
The program requests numerous entries of "lists", in which "ranges are
OK". In such a list, a range is specified by 2 numbers separated by a
dash, and ranges or individual values are separated by commas. For
example, 2-4,7,9,11-14 specifies the list 2,3,4,7,9,11,12,13,14 When
you put entries into a command file, you may put text after a list.
The program allows you to append its output to a set of existing files
from a previous run of the program. If you elect to append, then the
files (statistics output, average image, and standard deviation image)
will first be copied to new versions, then output will be appended to
those new files. If the program crashes, the previous versions will be
intact, but you must be careful to delete any new, incorrect versions
of the files before trying to run the program again. Be sure NOT TO
PURGE before doing this.
Entries to the program:
0 to place output in new files, or 1 to append to existing files.
Name of model file defining summing regions, or Return if no
summing or normalizing is desired
Name of file of G transforms used to align averages from different
data sets to each other. Enter Return if no G transforms.
Name of file to output the statistics into, or Return for no output.
This file is readable, but is meant to be run into Avgstatplot
Name of file to place new average images into, or Return for none
Name of file to place standard deviation images into, or Return
for none
IF you did not enter a model file with summing areas, skip the next
6 entries and go right to entering NX and NY:
Name of file for a map of the pixels in the summing areas, or Return
for none.
List of contours that comprise the LOW density normalizing area.
Here and in the next two entries, enter a series of pairs of
numbers, all on one line. The pair is either an IMOD object
number and contour number, or a WIMP object number and 0.
List of contours that comprise the HIGH density normalizing area.
To avoid normalization, enter the same contour as low and high
normalizing area.
List of contours specifying the summing regions.
Number of summing areas in each of the regions just specified, or the
negative of the width (in pixels) of the areas that you want the
region divided into. (You must enter one value per region.)
0 for circles, 1 for squares, or ratio of width to length for
rectangles. You must enter one value per region; just enter 0 for
regions specified by 4 or more points.
Horizontal and vertical pixel dimensions of the image file (NX and
NY).
Number of data sets to analyse and compare
Number of subsets of positions to average for each data set. Enter /
if you do not want to do subsets of positions; otherwise enter a
number for each data set (use zero for no subsets for a particular
set.)
--- The rest of the entries are required for each data set in turn:
Name of image file containing stack of samples to be averaged
List of section numbers to "try" to include in the averaging,
or / for all sections. Ranges may be entered.
Number of sets of F transforms to apply to the samples before
averaging. Enter 0, 1 or 2; do not count the G transforms
specified above.
IF you specified 1 or 2 sets of F's, next enter the name of the only
or first file of F transforms
IF you specified 2 sets of F's, next enter the name of the second
file of F transforms
IF you specified any F's, next enter the offset to add to the section
number to obtain the line number of the corresponding transform in
the file of F's. Both line and section numbers start at 0.
If alignment routines have been used properly, an entry of 0 will
suffice.
IF you specified a file of G transforms to align different sets to
each other, next enter the line number of the G transform for this
data set. The first line is number 0.
IF you specified that you wanted to average subsets of positions for
this data set, next make the following entries:
Name of file with list of position numbers for each section, as
produced by EXTPOSITION
For each subset, enter a list of position numbers to include in
the average. Enter each list on a separate line.
Enter 1 to set cutoffs for elimination of outliers, -1 for automatic
selection of cutoffs, or 0 to skip this option. If you do select
this option, the program enters a loop (with entries described
below) in which it repeatedly comes back to this point until you
enter a 0.
--- An entry of 0 at the last step completes the entries for a data
--- set; you then enter all parameters for the next data set, etc.
The last option allows you to interactively eliminate "outliers", sec-
tions that deviate the most from the average in the low and/or high
normalizing areas or in the difference between high and low areas.
This option should be used only if one has a specific basis for think-
ing that some subset of sections are significantly poorer than the
rest. Otherwise, it is strongly recommended that you skip through this
option by entering 0.
Outliers can be eliminated based one whether their low normalizing area
is more than a criterion number of standard deviations away from the
mean for all samples, or on whether the high normalizing area deviates
from the mean by more than a separate criterion, or on whether the dif-
ference between high and low areas deviates by more than yet another
criterion. If one enters a criterion of zero for one of these 3 devia-
tions, that deviation will not be considered. One may elect to elimi-
nate outliers only if all deviations being considered are above their
respective criteria, or if any of those deviations are above criterion.
If you do select manual elimination of outliers (with an entry of 1),
then there two entries:
Criterion number of S.D.'s for deviation from mean of low area, of
high area, and of difference between low and high areas. The
default is 2,2,2.
0 to eliminate a section if any of deviations being considered are
over criterion, or 1 to eliminate only if all deviations are over.
If you select automatic elimination of outliers with an entry of -1,
then there are no further entries. The program will then attempt to
find the outlier elimination that minimizes the sum of the standard
errors of the mean of all of SUMMING (not normalizing) areas. It does
this by repeatedly scaling the last-entered values of the three crite-
ria (or the default values, if none were entered) by a common factor
until it finds the scaling that minimizes the sum of SEM's.
HISTORY
Written by David Mastronarde 1/23/90; modified for IMOD 4/25/97
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 imavgstat(1)