add_contour

Synopsis

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]
[,attributes])

Description

The function arguments.

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.

Coordinates

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.

Examples

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

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.

Bugs

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

See Also

chips

chips, chipsgui, chipsrc, show_gui

concepts

aspectratio, attributes, chipsid, chipsopt, colors, coordsys, currency, depthcontrol, entitycreation, preferences, setget

contours

current_contour, delete_contour, display_contour, get_contour, hide_contour, set_contour, shuffle_contour