Last modified: November 2016

AHELP for CIAO 4.11 ChIPS v1


Context: contours


Creates a contour plot from an image or (x,y,z) values.


add_contour([id,] filename [,levels] [,attributes])
add_contour([id,] IMAGECrate [,levels] [,attributes])
add_contour([id,] numpy array [,levels] [,transform] [,attributes])
add_contour([id,] array, nx, ny [,levels] [,transform] [,attributes])
add_contour([id,] xaxis, yaxis, zaxis [,levels] [,transform]


The function arguments.

Argument Description
id A ChipsId structure identifying the item.
filename The name of the file containing an image to display. This can include CIAO DataModel filters, such as "evt2.fits[energy=500:7000][bin sky=8]", to automatically filter and bin a table before displaying it.
IMAGECrate An image crate, returned either by a read_file call or a call to the IMAGECrate constructor (see "ahelp crate").
numpy array A one- or two-dimensional NumPy array.
array, nx, ny A Python list or NumPy array. The nx and ny arguments must be given to determine the display size.
xaxis, yaxis, zaxis One-dimensional arrays giving the X, Y, and Z coordinate of each pixel. These arrays can not be sparse, so every pointin the X/Y grid must contain a value.
levels The contour levels to display, as a list or one-dimensional NumPy array.
transform A pytransform object that determines the mapping between the logical coordinate system, where (1,1) refers to the center of the bottom-left pixel, and the display system. At present this should either be a LINEAR2DTransform or WCSTransform object that contains a tangent-plane projection.
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_contour command creates a contour whose attributes are specified by user preferences or in an attribute list. The new contour becomes current by default; providing a ChipsId overrides the currency state.

Contouring an image

You can specify the image to contour in several ways:

The data-array is a one or two-dimensional array of data points to be contoured. If the array is not a two-dimensional numpy array then the image dimensions must be given (as the x-dim and y-dim arguments). If a transform is set to be applied, the data in data-array is first contoured and then the transform is applied to the contours.

For example:

chips> z = [0,1,1,0,1,3,4,1,0,2,1,0]
chips> add_contour(z, 4, 3)

will create a contour of the data going from x=1 to x=4 and y=1 to y=3, as will

chips> z2 = np.asarray([0,1,1,0,1,3,4,1,0,2,1,0])
chips> z2 = z2.reshape(4,3)
chips> add_contour(z2)

If xaxis, yaxis, and zaxis are given then the values must be ordered so that the X axis values increase fastest. The pixel sizes must remain the same; the routine will not create contours of irregularly, or sparsely, gridded data. So,

chips> x = [10,20,30,10,20,30,10,20,30]
chips> y = [1,1,1,2,2,2,3,3,3]
chips> z = [0,1,0,1,4,1,0,1,0]
chips> add_contour(x, y, z)

will create a contour of the data going from x=10 to x=30 and y=1 to y=3.


Unless explicitly set by the "wcs" attribute, contours are displayed using the "most specific" coordinate system supported by ChIPS; that is the WCS system, if specified and in the tangent-plane format, otherwise physical or, if not given, logical.

Customizing the Contour

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

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

Please see the "Contour Preferences and Attributes" section below the examples for a list of the contour attributes.


Example 1

chips> add_contour("img.fits")

Create contours from the file "img.fits". Equally-spaced levels are generated that cover the fullpixel range of the image. If the image contains WCS information, then it will be used for the X and Y axes; in this case you may wish to change the tick label format to use sexagesimal notation by saying:

chips> set_xaxis(["tickformat", "ra"])
chips> set_yaxis(["tickformat", "dec"])

The contour levels are chosen automatically in this case, using the contour.mode preference setting, which defaults to "nice". The actual values used can be found in the levels attribute of the return value of get_contour():

chips> get_contour().mode
chips> get_contour().levels
[53.5, 58.5, 63.5, 68.5, 73.5]

Example 2

chips> add_contour("img.fits", ["wcs", "physical"])

Here the contour is displayed using the physical coordinate system; for Chandra data this is the SKY system.

Example 3

chips> add_contour("img.fits", [60,68,75])

Create contours from the file "img.fits". Three contours are drawn, at levels of 60, 68, and 75. The contour mode - i.e. the algotithm used to determine the levels at which to display contours - is set to "arbitrary" in this case.

chips> get_contour().mode
chips> get_contour().levels
[60.0, 68.0, 75.0]

Changing the mode setting may change the contours used; below we switch to "nice" and then "interval" modes (in the latter case setting the spacing between levels to 15):

chips> set_contour(["mode", "nice"])
chips> get_contour().levels
[55.0, 60.0, 65.0, 70.0, 75.0, 80.0]
chips> set_contour(["mode", "interval", "interval", 15])
chips> get_contour().levels
[60.0, 75.0]

We now change the contouring to use the "count" mode and to use 4 levels; however the requested number of levels is not always possible to create, as in this case which ends up adding three contours.

chips> set_contour(["mode", "count", "numlevels", 4])
chips> get_contour().numlevels
chips> get_contour().levels
[60.0, 70.0, 80.0]

Finally we go back to the arbitrary mode and end up with the original selection of contour levels:

chips> set_contour(["mode", "arbitrary"])
chips> get_contour().levels
[60.0, 68.0, 75.0]

For this particular dataset the data range is roughly 50 to 80; the actual range can be found by using get_contour_zrange():

chips> get_contour_zrange()
[51.353700000000003, 80.367400000000004]

Example 4

chips> j, i = np.mgrid[-10:10:0.5, 20:50:0.5]
chips> r2 = (i-34)**2 + (j-2)**2
chips> add_contour(np.sqrt(r2), [2, 5, 10, 15])
chips> set_plot_aspect_ratio('fit')

The NumPy mgrid routine is used to create two 2D arrays (i and j) which contain the X and Y coordinates respectively for a grid ranging over x=20 to 50 and y=-10 to 10 with a grid size of 0.5 in both dimensions. Note that the upper bounds (ie x=20 and y=10) are not included in these grids.

The i and j arrays are used to create an image r2, where each pixel is the square of the distance of that pixel from x=34, y=2. The final display is of the square root of this distance, contoured to show those pixels whose distance is 2, 5, 10, and 15 units from the center.

Although the image is calculated with an X axis of 20 to 49.5 and Y axis of -10 to 9.5, the image is displayed in logical coordinates; so the X axis covers 0 to 60 and Y axis 0 to 40, as

chips> print(r2.shape)
(40, 60)

The actual plot range chosen will depend on the window size, the chosen plot area, and whether the aspect ratio is set. Here we use the set_plot_aspect_ratio command (see ahelp aspectratio) to resize the plot so that it fits the data.

Displaying the axis coordinates

The transform library can be used to create the necessary LINEAR2DTransform object, or we can take advantage of the imexent routine from the crates_contrib.images module:

chips> from crates_contrib.images import imextent
chips> tr = imextent(r2, 20, 49.5, -10, 9.5)
chips> add_window()
chips> add_contour(np.sqrt(r2), [2, 5, 10, 15], tr)
chips> set_plot_aspect_ratio('fit')

which ensures that the axes use the data values (e.g. starting at 20,-10).

Example 5

chips> add_contour("img.fits", ["color", "blue"])
chips> add_contour("img.fits", [0], ["color","green","thickness",2])

Two contours of the same image are created. The first set are drawn in blue, whilst the second one - which is overlain on the first - shows only the zero-level contour using a green contour, with a thickness of 2.

Example 6

chips> add_contour("img.fits", [10,20,30], ["wcs","logical"])

Create contours from the file "img.fits" using the specified contour levels. Use the logical coordinate system - namely the pixel numbers - for the axes.

Example 7

chips> img = read_file("contours.img")
chips> add_contour(img)

Create contours from the file "contours.img" via CRATES.

Example 8

chips> z1 = [1,1,1, 1,3,1, 1,1,1]
chips> z2 = np.asarray(z1).reshape(3,3)
chips> add_contour(z2)

The 3 by 3 array (z2) is contoured with equally-spaced levels. If the values were given as a one-dimensional array then the image dimensions would have had to be given too:

chips> add_contour(z1,3,3)

Example 9

chips> add_contour(z2, ["color", "lime", "style", "solid"])

Add a contour with line color and style attributes specified.

Example 10

chips> ci = ChipsContour()
chips> ci.color = "lime"
chips> = "solid"
chips> add_contour(z2, ci)

Add a contour with line color and style attributes specified via settings in the ChipsContour object.

Example 11

chips> add_contour(z2, [1.1,1.5,2,2.5])
chips> set_contour(["color","lime", "style","solid"])

Add a contour using user-specified levels, and then change the color and style of the contour lines.

Example 12

chips> img = np.arange(1,13).reshape(4,3)
chips> add_contour(img, ["color", "red"])
chips> get_contour_xrange()
[1.0, 4.0]
chips> get_contour_yrange()
[1.0, 3.0]
chips> add_contour(img, 3, 4, ["color","blue"])
chips> get_contour_xrange()
[1.0, 3.0]
chips> get_contour_yrange()
[1.0, 4.0]
chips> set_axis(["pad",0])
chips> get_plot_xrange()
[1.0, 4.0]
chips> get_plot_yrange()
[1.0, 4.0]

The img variable is a two-dimensional array containing the numbers 1 to 12 with 4 pixels in the X direction and 3 in the Y. The second add_contour call swaps the dimensionality, so that the array is treated as having 3 pixels in the X direction and 4 in the Y direction.

Contour Preferences and Attributes

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

Attribute Description Options Default Set?
algorithm the contouring algorithm to be used standard, marching marching Yes
color contour color name or hex; see the Color section of "ahelp chipsopt" default Yes
depth Depth used for the contour object see the Depth section of "ahelp chipsopt" default Yes
interval Indicates the delta value from one contour level to the next whem mode=interval Non-negative value 10 Yes
levels When setting, this attribute controls the the contour levels to display when the mode is "arbitrary". When using get_contour() this attribute contains the actual contour levels displayed. Array or list of numbers [] Yes
mode How the contour levels are determined arbitrary|count|interval|limits|nice; see the Tick Mode section of "ahelp chipsopt" nice Yes
numlevels number of contour levels when mode is count Non-negative integer 5 Yes
stem Stem used for contour id An alpha-numeric character sequence that does not contain a space ctr No
style Stipple pattern used to draw the line segment see the Line Style section of "ahelp chipsopt" solid Yes
thickness Thickness of the line 0.5 to 10.0; see the Thickness section of "ahelp chipsopt" 1 Yes
wcs The name of the coordinate system to use "logical", "physical", "world". You can also use the names of the transforms, such as "sky" and "EQPOS". "world", if available and supported (WCS-TAN). No

Supported World Coordinate Systems

WCS-TAN support

At present the only supported World Coordinate System for displaying data in ChIPS is the tangent-plane projection; namely WCS-TAN. Using an unsupported system will result in a warning message and the data will be displayed using the physical or - if it does not exist, logical - system.


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

See Also

chips, chipsgui, chipsrc, show_gui
aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget
current_contour, delete_contour, display_contour, get_contour, hide_contour, set_contour, shuffle_contour