Initial commit

1 files changed, 179 insertions, 0 deletions

diff --git a/pkg/proto/doc/mimstat.hlp b/pkg/proto/doc/mimstat.hlp
new file mode 100644
index 00000000..c6c389ea
--- /dev/null
+++ b/pkg/proto/doc/mimstat.hlp
@@ -0,0 +1,179 @@
+.help mimstatistics Sep01 proto
+.ih
+NAME
+mimstatistics -- compute and print image pixel statistics using iterative
+rejection and masks
+.ih
+USAGE	
+imstatistics images
+.ih
+PARAMETERS
+.ls images
+The input images or image sections for which pixel statistics are to be
+computed. Image sections are automatically applied to the input masks
+\fIimasks\fR if input masks are not mask sections.
+.le
+.ls imasks = ""
+The list of input masks or input mask sections associated with \fIimages\fR.
+Good and bad data values are assumed to be presented by mask values of 0 and
+1 respectively. The number of input masks must be 0, 1, or equal to the number
+of input images. Input mask sections if present override the input image
+sections.
+.le
+.ls omasks = "" 
+The list of output masks which are a combination of the input mask if any
+and pixels rejected using the good data limits and / or iterative clipping.
+Data used to compute the statistics are represented by 0 in the output mask,
+rejected data by zero. The number of output masks must be 0 or equal to
+the number of input images.
+.le
+.ls fields = "image,npix,mean,stddev,min,max"
+The statistical quantities to be computed and printed.
+.le
+.ls lower = INDEF
+The minimum good data limit.  All pixels are above the default value of INDEF.
+.le
+.ls upper = INDEF
+The maximum good data limit.  All pixels are above the default value of INDEF.
+.le
+.ls nclip = 0
+The maximum number of iterative clipping cycles. By default no clipping is
+performed.
+.le
+.ls lsigma = 3.0
+The low side clipping factor in sigma.
+.le
+.ls usigma = 3.0
+The high side clipping factor in sigma.
+.le
+.ls binwidth = 0.1
+The width of the histogram bins in sigma used for computing the midpoint
+(estimate of the median) and the mode.
+.le
+.ls format = yes
+Label the output columns and print the results in fixed format ? If format
+is "no" no column labels are printed and the output is in free format.
+.le
+.ls cache = no
+Cache the image data in memory ? This can increase the efficiency of the
+task if nclip > 0 or if either of the midpt or mode statistics is computed.
+.le
+.ih
+DESCRIPTION
+The statistical quantities specified by the parameter \fIfields\fR are
+computed and printed for each image in the list specified by \fIimages\fR.
+The results are printed in tabular form with the fields listed in the order
+they are specified in the fields parameter. The available fields are the
+following:
+
+.nf
+	 image - the image name
+	  mask - the mask name
+	  npix - the number of pixels used to do the statistics
+	  mean - the mean of the pixel distribution
+	 midpt - estimate of the median of the pixel distribution
+	  mode - the mode of the pixel distribution
+	stddev - the standard deviation of the pixel distribution
+	  skew - the skew of the pixel distribution
+      kurtosis - the kurtosis of the pixel distribution
+	   min - the minimum pixel value
+	   max - the maximum pixel value
+.fi
+
+The mean, standard deviation, skew, kurtosis, min and max are computed in a
+single pass through the image using the expressions listed below.
+Only the quantities selected by the fields parameter are actually computed.
+
+.nf
+          mean = sum (x1,...,xN) / N
+	     y = x - mean
+      variance = sum (y1 ** 2,...,yN ** 2) / (N-1)
+        stddev = sqrt (variance)
+          skew = sum ((y1 / stddev) ** 3,...,(yN / stddev) ** 3) / (N-1)
+      kurtosis = sum ((y1 / stddev) ** 4,...,(yN / stddev) ** 4) / (N-1) - 3
+.fi
+
+The midpoint and mode are computed in two passes through the image. In the
+first pass the standard deviation of the pixels is calculated and used
+with the \fIbinwidth\fR parameter to compute the resolution of the data
+histogram. The midpoint is estimated by integrating the histogram and
+computing by interpolation the data value at which exactly half the
+pixels are below that data value and half are above it. The mode is
+computed by locating the maximum of the data histogram and fitting the
+peak by parabolic interpolation.
+
+Pixels are rejected from the initial statistics computation by specifying an
+input mask \fIimasks\fR or by setting the good data limits \fIlower\fR
+and \fIupper\fR. Iterative rejection can be performed by setting the
+clipping parameters \fInclip\fR, \fIlsigma\fR, and \fIusigma\fR.
+
+The input masks \fIimasks\fR can be specified in a variety of ways as
+shown below.
+
+.nf
+	       "" - empty mask, use all the pixels
+	    EMPTY - empty mask, use all the pixels
+	 !KEYWORD - use mask specified by  header keyword KEYWORD
+	!^KEYWORD - use inverse of mask specified by  header keyword KEYWORD
+	     mask - use specified mask
+	    ^mask - use inverse of specified mask
+.fi
+
+In all cases the mask values are assumed to be 0 in good data regions and 
+non-zero in rejected data regions. The input masks may in pixel list, e.g.
+".pl" format, or integer images format, e.g. ".imh", ".fits", etc.
+
+
+.ih
+EXAMPLES
+1. Find the number of pixels, mean, standard deviation and the minimum
+and maximum pixel value of a bias region in an image.
+
+.nf
+    cl> mimstat flat*[*,1] ""
+    #      IMAGE      NPIX      MEAN    STDDEV       MIN       MAX
+      flat1[*,1]       800     999.5     14.09      941.     1062.
+      flat2[*,1]       800     999.4     28.87      918.     1413.
+.fi
+
+The string "flat*" uses a wildcard to select all images beginning with the
+word flat.  The string "[*,1]" is an image section selecting row 1.
+
+2. Compute the mean, midpoint, mode and standard deviation of a pixel
+distribution.
+
+.nf
+    cl> mimstat m51 "" fields="image,mean,midpt,mode,stddev"
+    #      IMAGE    PIXELS      MEAN     MIDPT     MODE     STDDEV
+	     M51    262144     108.3     88.75    49.4       131.3
+.fi
+
+3. Compute the image statistics in an image section using a mask.
+
+.nf
+    cl> mimstat m51[200:400,200:400] imasks=M51.bpm.pl 
+
+    cl> mimstat m51[200:400,200:400] imasks=M51.bpm.pl[200:400,200:400] 
+
+    cl> mimstat m51[200:400,200:400] imasks=M51.crm.pl[1:201,1:201] 
+.fi
+
+Note that the first two examples are equivalent so there is no need to
+specify the input mask section in the second case.
+
+4. Compute the image statistics using interactive rejection and save the
+rejected pixel mask.
+
+.nf
+    cl> mimstat m51 omasks=m51.rej.pl nclip=3
+.fi
+
+.ih
+BUGS
+When using a very large number of pixels the accumulation of the sums
+of the pixel values to the various powers may encounter roundoff error.
+This is significant when the true standard deviation is small compared
+to the mean.
+.ih
+SEE ALSO
+.endhelp