add_histogram

Syntax

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

Description

ChipsId - an optional ChipsId structure containing values to modify the currency state for the command.
TABLECrate/filename - input data, specified as a filename or a TABLECrate ("ahelp crates")
counts - an array of values containing the sum of counts for each bin
bin_low - array of values indicating the low value of the bin delimiter range. The number of values in the array must equal the number of values in the counts array.
bin_high - array of values indicating the high value of the bin delimiter range. The number of values in the array must equal the number of values in the counts array.
error_down - array of error down values for each bin. The number of values in the array must equal the number of values in the counts array.
error_up - array of error up values for each bin. The number of values in the array must equal the number of values in the counts array.
attributes - optional parameters which allow the user to configure properties though a structure, list, dictionary or attribute string.

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.

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 section "Histogram Preferences and Attributes" below the examples for a list of the histogram preferences.

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).

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

Changes in CIAO 4.5

The call

chips> add_histogram(x, y, ['*.color', 'red'])

now correctly sets the 'fill.color' attribute.

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.