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])
The function arguments.
|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:
- 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.
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.
Please see the "Contour Preferences and Attributes" section below the examples for a list of the contour attributes.
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]
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.
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]
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).
chips> add_contour("img.fits", ["color", "blue"]) chips> add_contour("img.fits", , ["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.
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.
chips> img = read_file("contours.img") chips> add_contour(img)
Create contours from the file "contours.img" via CRATES.
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(z2, ["color", "lime", "style", "solid"])
Add a contour with line color and style attributes specified.
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.
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.
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.
|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
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.