Last modified: December 2013

URL: https://cxc.cfa.harvard.edu/chips/ahelp/add_histogram.html
AHELP for CIAO 4.11 ChIPS v1

add_histogram

Context: histograms

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.

See Also

chips
chips, chipsgui, chipsrc, show_gui
concepts
aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
histograms
current_histogram, delete_histogram, display_histogram, get_histogram, hide_histogram, set_histogram, shuffle_histogram
utilities
load_fill