Jump to: Description · Examples · Contour Preferences and Attributes · Bugs · See Also

AHELP for CIAO 4.5 ChIPS v1

add_contour

Context: contours

Synopsis

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

Syntax

add_contour([ChipsId,] filename [,levels] [,attributes])
add_contour([ChipsId,] IMAGECrate [,levels] [,attributes])
add_contour([ChipsId,] data-array [,x-dim, y-dim] [,levels] [,trans]
[,attributes])
add_contour([ChipsId,] xaxis, yaxis, zaxis [,levels] [,trans]
[,attributes])

Description

ChipsId - an optional ChipsId structure containing values to modify the currency state for the command.
IMAGECrate/filename - input data, specified as a filename or an IMAGECrate ("ahelp crates")
data-array - 1D or 2D regular, non-sparse data array containing the points to be contoured.
x-dim - size of the x dimension of data_array; this is only needed if data-array is not a two-dimensional numpy array
y-dim - size of the y dimension of data_array; this is only needed if data-array is not a two-dimensional numpy array
xaxis - a one-dimensional array giving the x coordinate of each pixel
yaxis - a one-dimensional array giving the y coordinate of each pixel
zaxis - a one-dimensional array giving the value of each pixel
levels - the exact contour levels to display
trans - coordinate transform to be applied to the data
attributes - optional parameters which allow the user to configure properties though a structure, list, dictionary or attribute string.

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:

as a filename, including any Data Model filters;
the return value of Crates' read_file() command (when called on an image);
as a one- or two- dimensional array (data-array) - the width (x-dim) and height (y-dim) are required if data-array is not a two-dimensional numpy array;
or as three one-dimensional arrays - xaxis, yaxis, zaxis - where the xaxis and yaxis arrays give the coordinate location and zaxis is the pixel value.

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.

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

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
'nice'
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
'arbitrary'
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
4
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> 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 5

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 6

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

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

Example 7

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 8

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

Add a contour with line color and style attributes specified.

Example 9

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

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

Example 10

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 11

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

Bugs

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