Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: June 2010

URL: http://cxc.harvard.edu/ciao/ahelp/simple_hist.html
Jump to: Description · Examples · See Also


AHELP for CIAO 4.9

simple_hist

Context: contrib

Synopsis

Create a one-dimensional histogram of a data array

Syntax

simple_hist(array, nbins=10, min=None, max=None, step=None)

Description

The simple_hist() routine calculates a one-dimensional histogram of the input data (the array argument). For more control over the calculation use the numpy.histogram() routine.

Loading the routine

The routine can be loaded into Sherpa by saying:

from ciao_contrib.utils import *

Arguments

Name Default value Description
array The array of data to histogram.
nbins 10 The number of bins to use to create the histogram (only used when step is None).
min None The value to use for the lower edge of the first bin; if None then the minimum data value will be used.
max None The value to use for the upper edge of the last bin; if None then the minimum data value will be used. It can be over-ridden if step is not None.
step None The bin width to use (this overrides the nbins value).

The return value

The return value is an object with the following fields:

Field Value
xlow The lower edges of each bin.
xhigh The upper edges of each bin.
y The number of elements of array that fall within each bin.

Histogram calculation

The histogram is calculated using evenly-spaced bins; for all but the last bin the range is half-open, so that if it has edges xlow_i and xhigh_i then a value falls in this bin if it has a value in the range

xlow_i <= x < xhigh_i

The last bin is considered closed, so a value falls in this bin if

xlow_last <= x <= xhigh_last

Bin edges

If step is not given (i.e. it is None), then the bin width is calculated as

(max - min) / nbins

If step is given then it is used as the bin width and the upper edge will be adjusted to ensure there are an integer number of bins: so if the input values are min=0, max=1, and step=0.4 the histogram will be calculated for the bins 0 to 0.4, 0.4 to 0.8, and 0.8 to 1.2.

Example 1

chips> x = [0, 1, 2, 3, 2, 3, 4, 2, 1]
chips> h = simple_hist(x)
chips> add_histogram(h.xlow, h.xhigh, h.y)

The return value of h is an object with the fields "xlow", "xhigh", and "y", which contain the lower and upper bin edges and the histogram values respectively. These fields are used to plot up the histogram using the ChIPS add_histogram() routine.

chips> print (h)
xlow  = Float64[10]
xhigh = Float64[10]
y     = Int32[10]
chips> print (h.y)
[1 0 2 0 0 3 0 2 0 1]

Example 2

chips> x = [0, 1, 2, 3, 2, 3, 4, 2, 1]
chips> h = simple_hist(x, step=1)

The step size (width) of each bin is set to 1, which results in:

chips> print (h)
xlow  = Float64[4]
xhigh = Float64[4]
y     = Int32[4]
chips> print (h.y)
[1 2 3 3]

Example 3

chips> img = read_image("emap.fits")
chips> ivals = get_piximgvals(img)
chips> ix = np.isfinite(ivals)
chips> h = simple_hist(ivals[ix], nbins=20)

Here we use the Crates read_image() and get_piximgvals() to read in the contents of the image "emap.fits". Since it may contain "invalid" numbers, such as NaN and Infinity, we filter out these values before calculating the histogram (using 20 bins).

See Also

contrib
simple_stats
tools
detilt, dewiggle, symmetrize

Last modified: June 2010
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.