Creates a histogram-style figure.
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])
The function arguments.
|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.
Please see the "Histogram Preferences and Attributes" section below the examples for a list of the histogram preferences.
chips> add_histogram("peak.fits[cols energy, counts]")
Create a histogram from energy and counts columns in the file "peak.fits".
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.
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.
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.
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.
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.
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".
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).
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.
|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|
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.
- chips, chipsgui, chipsrc, show_gui
- aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
- current_histogram, delete_histogram, display_histogram, get_histogram, hide_histogram, set_histogram, shuffle_histogram