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)

`-M``--mask`(

`=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.`-H``--mhdu`(

`=STR`) The header name of the mask extension.`-r``--ignoremin`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.

`-l``--lowerbin`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.

`--onebinvalue`(

`=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.`--noasciihist`Do not show an ASCII plot on the command-line.

`--mirrorquant`(

`=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`.`--checkmode`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.`--histrangeformirror`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`.

`--nohist`Do not calculate or save the histogram.

`--normhist`Make a normalized histogram, see Histogram and Cumulative Frequency Plot.

`--maxhistone`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.`-n``--histnumbins`(

`=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.`-i``--histmin`(

`=FLT`) The minimum value to use in the histogram. If`--histquant`is given, then any value given`--histmin`or`--histmax`is ignored.`-x``--histmax`(

`=FLT`) The maximum value to use in the histogram. Similar to`--histmin`.`-Q``--histquant`(

`=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.

`--nocfp`Do not calculate or store the cumulative frequency plot.

`--normcfp`Normalize the cumulative frequency plot, see Histogram and Cumulative Frequency Plot.

`--maxcfpeqmaxhist`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.

`--cfpsimhist`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.

`-p``--cfpnum`(

`=INT`) The number of points to store the cumulative frequency plot. They will be evenly distributed between the range of pixel values.`-a``--cfpmin`(

`=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.`-n``--cfpmax`(

`=FLT`) The maximum value to use for the cumulative pixel value range. Similar to`--cfpmin`.`-U``--cfpquant`(

`=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.

`--nosigclip`If this option is called, no \(\sigma\)-clipping will take place.

`-u``--sigclipmultip`(

`=FLT`) The multiple of the standard deviation above which to clip. This value is demonstrated by \(\alpha\) in Sigma clipping.`-t``--sigcliptolerance`(

`=FLT`) If the fractional difference of the standard deviation becomes less than this value, then \(\sigma\)-clipping will halt, see Sigma clipping.`-g``--sigclipnum`(

`=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.