Last modified: December 2013

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

set_histogram

Context: histograms

Synopsis

Modifies the attributes of an existing histogram.

Syntax

set_histogram(attributes)
set_histogram(id, attributes)

Description

The function arguments.

Argument Description
id A ChipsId structure identifying the item, or a string containing the name of the object.
attributes Configure object properties by giving an attribute string (a space-separated list of key=value pairs), list, dictionary, or a ChIPS object.

The set_histogram command sets the specified attributes to the provided values. The modified histogram becomes current. Multiple histograms may be modified with a single command by setting the currency to "all".

Customizing the Histogram

There are several attributes that control the characteristics of histograms. The set_histogram command may be used to modify the attribute values of an existing histogram at any time during a ChIPS session. See "ahelp attributes" and "ahelp setget" for more general information.

If multiple attributes are being set simultaneously and one of them fails, the entire command will fail and the histogram will not be modified.

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

Advanced Functions

The module of advanced ChIPS functions contains other commands for setting attribute values (refer to "ahelp chips" for information on loading the module):

set_histogram_depth
set_histogram_dropline
set_histogram_errcaplength
set_histogram_errcolor
set_histogram_errdown
set_histogram_errstyle
set_histogram_errthickness
set_histogram_errup
set_histogram_fillcolor
set_histogram_fillopacity
set_histogram_fillstyle
set_histogram_linecolor
set_histogram_linestyle
set_histogram_linethickness
set_histogram_symbolangle
set_histogram_symbolcolor
set_histogram_symbolfill
set_histogram_symbolsize
set_histogram_symbolstyle

Examples

Example 1

chips> set_histogram(["line.color", "cornflower", "dropline", True])

Using attribute/value pairs, set the histogram line color to cornflower and display droplines.

Example 2

chips> set_histogram({"line.color": "cornflower", "dropline": True})

This is a repeat of the previous example, using a dictionary rather than a list to define the attributes to change.

Example 3

chips> set_histogram(["*.color", "green"])

Here we use the "*.color" shortform to set all the color attributes of the histogram - e.g. line, symbol, fill, and error - to green.

Example 4

chips> set_histogram(["err.*", False])

To set both err.up and err.down at the same time, use the "err.*" name. In this example the error bars (both up and down) are turned off. This can also be achieved by saying:

chips> set_histogram(["err.up", False, "err.down", False])

Example 5

chips> s = ChipsHistogram()
chips> s.err.color = "red"
chips> s.symbol.style = chips_cross
chips> set_histogram("hist1", s)

Populate the "s" structure with attribute values, then use it to set red errors and cross-shaped symbols for the histogram called "hist1".

Example 6

chips> s = ChipsHistogram()
chips> s.all.color = "red"
chips> s.all.thickness = 2
chips> set_histogram("hist1", s)

Here we change all the color attributes of the histogram "hist1" to red and the thickness attributes to 2.


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

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

See Also

concepts
setget
histograms
add_histogram, current_histogram, delete_histogram, display_histogram, get_histogram, hide_histogram, shuffle_histogram
utilities
load_fill, set_current