Previous: Mirror distribution, Up: ImageStatistics [Contents][Index]
ImageStatistics will print the major statistical measures of an image’s pixel value distribution. The executable name is astimgstat with the following general template
$ astimgstat [OPTION ...] InputImage.fits
One line examples:
$ astimgstat input.fits $ astimgstat animage.fits --ignoremin --nohist $ astimgstat anotherimage.fits --mask=detectionlabels.fits --mhdu=1
If ImageStatistics is to do any data processing, an input image should be provided with the recognized extensions as input data, see Arguments. See Common options for the list of options that are shared by all programs. All the main statistical operations have their specific set of options. If a string is given to the --output option, it is used as the base name for the generated files. Without this option, the input image name is used as the name-base.
Some of the options are necessary and if they are not included in the configuration file, ImageStatistics will not run, see Configuration files. However, for some others this is not so: --histmin, --histmax, --histquant, --cfpmin, --cfpmax, --cfpquant. These are options to do with the range of values in the histogram and cumulative frequency plots. If no value is given for these options when ImageStatistics is about to start processing the data, then the full data range will be used. Such that the minimum image value will be set for the minimums and the maximum image value will be used for the maximum. The Mask name and HDU are also not mandatory in the configuration file.
By default, in verbose mode 91, along with a short summary of the basic data statistics, a
simple ASCII histogram will also be printed. This can be useful for a
very quick and general view of the distribution. An example verbose
output of ImageStatistics on one of the $ make check outputs
can be seen below:
$ astimgstat ./tests/convolve_spatial_warped_noised.fits \
--histquant=0.05
ImageStatistics started on AAA BBB CC DD:EE:FF GGGG
- Input read: ./tests/convolve_spatial_warped_noised.fits (hdu: 0)
-- Number of points 10000
-- Minimum -38.2066
-- Maximum 1268.72
-- Sum 154927
-- Mean 15.4927
-- Standard deviation 60.5407
-- Median 4.82691
-- Mode (quantile, value) 0.4335, 2.90301
-- Mode symmetricity and its cutoff value 0.5909, 17.2507
-- ASCII histogram in the range: -13.912957 -- 65.058487:
| * *
| ********
| ********* **
| **************
| ******************
| ********************
| ***********************
|***************************
|******************************
|*****************************************
|************************************************************
|------------------------------------------------------------
- Sigma clipping results (Median, Mean, STD, Number):
- 4.00 times sigma by convergence (tolerance: 0.2000):
1: 4.826907, 15.492665, 60.540707, 10000
2: 4.665353, 10.117773, 27.793823, 9881
3: 4.433090, 7.458610, 18.510950, 9715
4: 4.216213, 6.176818, 15.231371, 9575
5: 4.088199, 5.679162, 14.183748, 9502
- 4.00 sigma-clipping 5 times:
1: 4.826907, 15.492665, 60.540707, 10000
2: 4.665353, 10.117773, 27.793823, 9881
3: 4.433090, 7.458610, 18.510950, 9715
4: 4.216213, 6.176818, 15.231371, 9575
5: 4.088199, 5.679162, 14.183748, 9502
ImageStatistics finished in: 0.006964 (seconds)
(=STR) The file name of a mask image. If this option is not given on the command-line or in the configuration files and --mhdu is not given or is identical to --hdu, then no mask image will be used.
(=STR) The header name of the mask extension.
Ignore all data elements that have a value equal to the minimum value in the image. In practice this is like masking those pixels, their values will not be used.
Set the first column of the histogram and cumulative frequency plots to the lower interval boundary. By default (without calling this option), the central interval value is used.
(=FLT) Make sure that one bin starts with the value to this option. In practice, this will shift the bins used to find the histogram and cumulative frequency plot such that one bin’s lower interval becomes this value. For example when the histogram range includes negative values, but the data doesn’t. If zero is somewhere between one bin, then the viewers of the plot(s) will think negative data is also present. By setting --onebinvalue=0, you can make sure that the viewers of the histogram will not be confused.
Note that by default, the first row of the histogram and cumulative
frequency plot show the central values of each bin. So in the example
above you will not see the 0.000. To see it, add the
--lowerbin option to show the lower value of each bin. If you
don’t care about the bin positions within the specified range you can
set the value to this option to a Not-a-Number (NaN) value on the
command-line (--onebinvalue=nan) or in the configuration
files with a nan following the option name. If the value is not
within the specified bin range, it will be ignored.
Do not show an ASCII plot on the command-line.
(=FLT) quantile to put the mirror. A value between 0 and 1. See Mirror distribution for a complete explanation. Outputs two files with suffixes _mirrorhist.txt and _mirrorcfp.txt.
The mode of the data is found by comparing the input data distribution with its mirror distribution. If this option is called, the mirror distribution’s histogram and cumulative frequency plots will be saved in to plain text files ending with _modehist.txt and _modecfp.txt. See the explanation for Mirror distribution for more details about these two files and how you can easily plot the outputs. This option only works when when ImageStatistics is in verbose mode. Since otherwise the mode is not calculated.
To draw the plots you can use the script in Mirror distribution. Just change the appended suffixes in the two calls to
np.loadtxt in the Python script.
Use --histmin and --histmax for the range of the mirror distributions (which are produced with the --mirrorquant and --checkmode options).
Histogram: The stored histogram is stored in a text file ending with _hist.txt.
Do not calculate or save the histogram.
Make a normalized histogram, see Histogram and Cumulative Frequency Plot.
Divide all histogram bins by the number in the bin with the most data points. This is very useful if you want to plot the histogram along with a normalized cumulative frequency plot in one plot. Note that if the histogram numbers are important in showing along with the cumulative frequency plot, you can use --maxcfpeqmaxhist, see below.
(=INT) The number of bins in the histogram. Note that in practice, this is also equivalent to the number of rows in the output text file.
(=FLT) The minimum value to use in the histogram. If --histquant is given, then any value given --histmin or --histmax is ignored.
(=FLT) The maximum value to use in the histogram. Similar to --histmin.
(=FLT) Set the range of the histogram based on the image quantile. So --histquant=0.05 is given, all the data from the 0.05 quantile to 0.95 quantile will be used in the histogram. This is useful when there is a small number of outliers in the image. Note that if this option is given, any (possible) value given to --histmin or --histmax are ignored.
Cumulative Frequency Plot: The cumulative frequency plot will be stored in a text file ending with _cfp.txt. To be more realistic, the average of the indexs in each interval is used as the second column, see Histogram and Cumulative Frequency Plot.
Do not calculate or store the cumulative frequency plot.
Normalize the cumulative frequency plot, see Histogram and Cumulative Frequency Plot.
Set the maximum cumulative frequency plot value to the maximum value in the histogram (if it is to be created). This is a useful in plotting the histogram and cumulative frequency plots together when the histogram numbers are important.
Set the range of the cumulative frequency plot and the number of points to store to the same range as the histogram. If the two are to be plotted together, this is very useful, since the first axis (column) of the two will become identical.
(=INT) The number of points to store the cumulative frequency plot. They will be evenly distributed between the range of pixel values.
(=FLT) The minimum value to use for the cumulative pixel value range. If --cfpquant is given, then any value given --cfpmin or --cfpmax is ignored.
(=FLT) The maximum value to use for the cumulative pixel value range. Similar to --cfpmin.
(=FLT) Similar to --histquant but for the cumulative frequency plot.
\(\sigma\)-clipping: The result of each iteration of \(\sigma\)-clipping will be printed in the terminal for both types of sigma clipping: A certain number of times and convergence of the standard deviation.
If this option is called, no \(\sigma\)-clipping will take place.
(=FLT) The multiple of the standard deviation above which to clip. This value is demonstrated by \(\alpha\) in Sigma clipping.
(=FLT) If the fractional difference of the standard deviation becomes less than this value, then \(\sigma\)-clipping will halt, see Sigma clipping.
(=INT) The number of iterations for the case where the \(\sigma\)-clipping iteration stops after a certain number of runs.
If the -q option is not called then all programs will operate in verbose mode, see Common options.
Previous: Mirror distribution, Up: ImageStatistics [Contents][Index]
JavaScript license information
GNU Astronomy Utilities 0.2.28-34fb manual, October 2016.