/ chips4.11 / ahelp / add_histogram.html

Jump to: Description · Examples · Histogram Preferences and Attributes · Bugs · See Also

AHELP for CIAO 4.11 ChIPS v1

add_histogram

Synopsis

Creates a histogram-style figure.

Syntax

add_histogram([id,] filename [,attributes])
add_histogram([id,] TABLECrate [,attributes])
add_histogram([id,] counts [,attributes])
add_histogram([id,] bins, counts [,attributes])
add_histogram([id,] bin_low, bin_high, counts [,attributes])
add_histogram([id,] bin_low, bin_high, counts, yerrs [,attributes])
add_histogram([id,] bin_low, bin_high, counts, ydown, yup,
[,attributes])

Description

The function arguments.

Argument	Description
id	A ChipsId structure identifying the item.
filename	The name of the file containing the columns to display. This can include CIAO DataModel filters, such as "evt2.fits[energy=500:7000][cols sky]", to automatically filter the table before displaying it.
TABLECrate	A table crate, returned either by a read_file call or a call to the TABLECrate constructor (see "ahelp crate").
counts	One dimensional NumPy array or Python list containing the number of counts in the bin. If no binning is specified then the bins are assumed to be contiguous, ascending, have unit width, and the first bin is centered at 1.
bins	One dimensional NumPy array or Python list containing the center of each bin; it must have the same size as the counts argument. The bins are considered to be contiguous and should be given in either ascending or descending order.
bin_low, bin_high	One dimensional NumPy array or Python lists containing the left and right edges of each bin. The bins should not overlap but do not need to be contiguous, should be in ascending order, and be the same size as the counts argument.
yerrs	One dimensional NumPy arrays or Python lists containing the symmetric error values (relative to counts and should be positive). The size must match the counts array.
ydown, yup	One dimensional NumPy arrays or Python lists containing the error values (relative to counts and should be positive, even for ydown). The size must match the counts array.
attributes	Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

The add_histogram command creates a histogram-style figure whose attributes are specified by user preferences or in an attribute list. The new histogram becomes current by default; providing a ChipsId overrides the currency state.

Note that this command does not do any calculations (i.e. it does not bin up an array to create a histogram); it takes the input data as given and creates the figure. The NumPy histogram routine can be used to create the necessary arrays; an example is included below.

Specifying the bins

If bin_low or bin_high column is set to "None", then the column that is provided is used as the midpoint of the bin.

The bin values should be given in either ascending or descending order. There is no guarantee that the hstogram will display correctly if the bins are not sorted or - if bin edges are given - overlap.

Customizing the Histogram

There are several attributes that control the histogram characteristics. The attributes can be set to the ChIPS defaults, values provided in the add_histogram command, or values from the user's preference file.

The attributes may also be modified with the set_histogram command at any time; see "ahelp set_histogram" and "ahelp setget" for more information.

Please see the "Histogram Preferences and Attributes" section below the examples for a list of the histogram preferences.

Examples

Example 1

chips> add_histogram("peak.fits[cols energy, counts]")

Create a histogram from energy and counts columns in the file "peak.fits".

Example 2

chips> dat = read_file("peak.fits[cols energy, counts]")
chips> add_histogram(dat)

Create a histogram from energy and counts columns in the file "peak.fits" via CRATES.

Example 3

chips> dat = read_file("peak.fits")
chips> x = copy_colvals(dat, "energy")
chips> y = copy_colvals(dat, "counts")
chips> add_histogram(x, y, ["fill.style", "solid"])
chips> set_histogram(["fill.opacity", 0.4])
chips> set_histogram(["*.color", "red"])

Create a histogram from energy and counts columns in the file "peak.fits" via CRATES. The histogram is drawn with a solid fill; this fill is then made opaque and then all color elements of the histogram set to red.

Note that the histogram attributes could be set in the add_histogram call by saying

chips> hopts = ['fill.style','solid','fill.opacity',0.4,'*.color','red']
chips> add_histogram(x, y, hopts)

or using one of the other methods - such as using a dictionary instead of an array, or the ChipsHistogram object - described in ahelp attributes.

Example 4

chips> add_histogram([10,12,15])

A simple add_histogram command, using the default attribute values. This command will divide the x-axis into three equally sized bins; the number of bins is the same as the number of elements in the counts array. The range of the x axis is also equal to the number of bins in the counts array. The center of the x bin ranges are equal to the integer number of bins (i.e. 1.0, 2.0, and 3.0). The Y axis is scaled to the min and max of the counts range array values.

Example 5

chips> add_histogram([1,5,9], [10, 15, 20], ["dropline", True])

Create three bins of counts of 10, 15 and 20 centered at 1, 5, and 9. The value of dropline is "on", and adjacent bins share borders, so all bin borders are rendered.

Example 6

chips> add_histogram([10, 15, 20], [12, 17, 22], [5,8,13])

Create three bins of counts of 5, 8 and 13. As both the bin_low and bin_high arrays have been given, they are used to specify the actual bin bounds instead of centers.

Example 7

chips> add_histogram([10, 15, 20], [12, 17, 22], [5,8,13], [1,1,2])
chips> set_histogram(["symbol.style", "diamond", "err.style", "capped"])

The previous example is repeated, but symmetric error bars of lengths 1, 1, and 2 have been added. The error style is "capped".

Example 8

chips> add_histogram([10, 15, 20], [12, 17, 22], [5,8,13], [1,1,2],
[2,4,4])
chips> set_histogram(["symbol.style", "cross", "err.style", "capped"])

The previous example is repeated, but with asymmetric error bars (low values of 1,1,2 and high values of 2,4,4).

Example 9

chips> r = np.random.chisquare(5, 1000)
chips> (y,edges) = np.histogram(r, bins=20)
chips> xlo = edges[:-1]
chips> xhi = edges[1:]
chips> add_histogram(xlo, xhi, y, ['fill.style', 'solid',
'fill.opacity', 0.4])
chips> set_histogram(['fill.color', 'yellow'])

In this example we create an array of 1000 random numbers drawn from the Chi Square distribution with 5 degrees of freedom. This is then converted into a histogram - in the form of y values and bin edges - by the NumPy histogram routine. The bin edges are separated out to ignore the last and first points, using array slicing, and then plotted as a histogram. A green fill - mostly opaque - is added to the figure.

Histogram Preferences and Attributes

The attributes associated with histograms are given in the following table, where the "Set?" column refers to whether the attribute can be changed using the set_histogram() command. To change the histogram preference settings prepend "histogram." to the attribute name.

Attribute	Description	Options	Default	Set?
depth	Value indicating the depth of the plot title	see the Depth section of "ahelp chipsopt"	default	Yes
dropline	Boolean indicating whether bin edges are extended to 0 for connected bins	on\|off	on	Yes
err.caplength	Length of the cap drawn on error bars (when err.style is cap).	1 to 100, inclusive.	10	Yes
err.color	Color of the curve err bars	name or hex; see the Color section of "ahelp chipsopt"	default	Yes
err.down	Histogram y down errors if data provided	see the Booleans section of "ahelp chipsopt"	true	Yes
err.style	Specifies the error bar style	bar or cap	bar	Yes
err.thickness	Specifies the thickness of error bars	0.5 to 10.0; see the Thickness section of "ahelp chipsopt"	1	Yes
err.up	Histogram y up errors if data provided	see the Booleans section of "ahelp chipsopt"	true	Yes
fill.color	Color of the histogram fill	name or hex; see the Color section of "ahelp chipsopt"	default	Yes
fill.opacity	Opacity of the histogram fill	0.0 to 1.0, inclusive, where 0 is fully transparent and 1 is fully opaque	1.0	Yes
fill.style	The fill style for the histogram	see the Fill Pattern section of "ahelp chipsopt"	0 (no fill)	Yes
line.color	Color of the curve line	name or hex; see the Color section of "ahelp chipsopt"	default	Yes
line.style	The pattern used for the histogram line style	see the Line Style section of "ahelp chipsopt"	chips_solid	Yes
line.thickness	Thickness of the histogram line	0.5 to 10.0; see the Thickness section of "ahelp chipsopt"	1	Yes
stem	stem used for histogram id	An alpha-numeric character sequence that does not contain a space	hst	No
symbol.angle	The angle, in degrees, of rotation for the histogram symbols	-360.0 to 360.0	0.0	Yes
symbol.color	Color of the histogram symbols	name or hex; see the Color section of "ahelp chipsopt"	default	Yes
symbol.fill	Should the histogram symbols be filled or not	see the Booleans section of "ahelp chipsopt"	false	Yes
symbol.size	Size of the curve symbols	1 to 100	5	Yes
symbol.style	The shape of the glyph used as the histogram symbols	see the Symbol Styles section of "ahelp chipsopt"	chips_none	Yes

Bugs

Transparency support and PostScript formats

The Postscript (PS and EPS) output formats do not support the alpha settings of images or the opacity settings of region or histograms. The attribute values are treated as 1 when the object are displayed in these formats.

See the bugs pages on the ChIPS website for an up-to-date listing of known bugs.