Gallery: Images

The read_file routine is used to read in the data from the file "a2142_dss.fits" into the dss object. We then replace the pixel values in dss by the logarithm of their values using the copy_piximgvals and set_piximgvals routines. The dss variable is then displayed with the add_image routine, and we set the invert_colormap attribute to True so that high values are displayed as black rather than white.

The above can also be achieved using the scale_image_crate routine from the CIAO contributed scripts package, for example:

scale_image_crate(dss, "log10")

but the advantage of the manual approach is that the scaling is not limited to that provided by the scale_image_crate routine.

We could have used the following commands to display a logarithmically-scaled version of the optical data, but this would have lost the WCS information in the file header, which means we would not have been able to overlay the Chandra contours.

dss = read_file("a2142_dss.fits")
ivals = copy_pixvals(dss)
add_image(np.log10(ivals), ["invert_colormap", True])

The add_contour call overlays the contours onto the image; we chose to increase the width of the contours and to make them black so that they are visible both on the screen and in any hardcopy outputs created by print_window.

A label is positioned in the bottom-right corner of the plot, using the plot-normalized coordinate system; since the halign attribute is set to 0.5 the label is centered horizontally at x=0.7.

In order to remove the axes we have to call hide_axis, to hide both the X and Y axies, and set_plot to set the plot style to open, which hides the plot borders. Finally we call reposition_plot to make the plot fill the frame; an alternative method to achieve this - as used in the histogram overlay example - is to set the plot margins to 0.

The second add_image call results in a plot which just shows the X-ray data, since - by default - images are fully opaque and so the original image (from the DSS) is obscured. The set_image call is used to change two image attributes that will "merge" the two images:

1. The alpha attribute takes a two-element array that describes how the alpha channel should vary with the image pixel values. Here we use [0.7, 0.7] to say that each pixel being displayed should have an alpha-channel value of 0.7.

   If we had said [0.3, 1] then the opacity would have varied from 0.3 for pixels with the minimum displayed value to 1 for those with the maximum displayed value.

2. The threshold attribute is used to determine what range of pixel values is displayed by the colormap. Here, pixel values of 6, and below, are assigned to the minimum color whilst those with 60, or above, are given the maximum color. This range was selected to highlight the cluster emission whilst ignoring the X-ray background.

WCS projection support

In CIAO 4.10, WCS support in ChIPS is only available for tangent-plane projections (e.g. images with RA--TAN and DEC-TAN images). Other projections - such as the SIN projection - will be displayed in physical, or logical coordinates. For the gallery plots, SIN projection images (such as provided by NVSS) have been converted to TAN projection - using a combination of the remap program from WCSTools and the Montage package.

Opacity and Postscript output

Note that the postscript output created by print_window does not support opaque region or histogram fills; instead the opacity is taken to be 1. The relative depth of the objects can be changed - by altering the depth attribute or using the various "shuffle commands" (shuffle, shuffle_back, shuffle_front, shuffle_backward, shuffle_forward, and the set of shuffle_<object> routines) so that overlapping objects are not completely obscured if desired.

For this example we want to display a grid of plots - created by the split command - that fill the frame. Since the split command uses the default plot margins for determining how much of the frame to use when creating the grid, we first set the plot margins to 0 using the set_preferences routine. The add_window call is used to create a rectangular window; note that the on-screen size is not guaranteed to exactly match the requested size but that any postscript and PDF output will use this size (unless the fittopage attribute is set when calling print_window).

The set_plot call ensures that the following commands are applied to all the plots; this means, for instance, that the add_image call will create an image in each plot created by the split call.

Since we wish to display the different colormaps, we chose to display a simple image: a horizontal bar going from 1 to 4096. The plot is created with the data-aspect ratio set to 1:1. In this case this is not desired, so we use the set_data_aspect_ratio call to remove the setting, and change the Y-axis limits to cover just the image. An alternative way to set the Y-axis range would have use the image itself to set the range by saying:

limits(Y_AXIS, chips_image, "imag1")

The label preferences are set to make sure any new label is drawn in white, with a font size of 16, and horizontally centered on the given location. These are set as preferences to avoid having to set them in each add_label call. We write a routine to automate setting the colormap and adding a label to each plot, imaginatively called doit. We take advantage of Python's "named keywords" when writing the function to support optional values; the routine defaults to using the upper-case version of the colormap name as the label text and not to invert the colormap, but these can be explicitly set with the label and invert arguments, as is done for the inverted-rainbow plot in plot9.

Each plot is selected, one of the default colormaps is chosen, and a label added - using the doit routine - to indicate which one is being used. The plots are arranged from left-to-right, and then top-to-bottom, by the split call; so plot1 is the plot in the top-left corner and plot4 is the plot in the top-right corner.

For the bottom-left plot (plot9), we use the same colormap as the plot above it - the rainbow map in plot5 - but invert the colormap.

The last three plots use the "user" colormaps - usercmap1, usercmap2, and usercmap3 - which default to the values shown here. The following example shows how these particular colormaps can be changed.

Here we decide to use the halley, a, and b colormaps from the lut parameter file. In order to get the file names, we load in the paramio module, and then use pget to query for the values. You can use the plist tool to view all the options (the actual location of the files depends on the location of your CIAO installation, here assumed to be /soft/ciao-4.7/):

chips> !plist lut

Parameters for /soft/ciao-4.7/param/lut.par

     (a = ${ASCDS_CALIB}/a.lut -> /soft/ciao-4.7/data/a.lut) Color lookup table
  (aips = ${ASCDS_CALIB}/aips.lut -> /soft/ciao-4.7/data/aips.lut) Color lookup table
...

Once the file names have been retrieved, we use the load_colormap call to load in the data into the usercmap1, usercmap2, and usercmap3 colormap slots. If the location of the files are already known, or you want to use other files, you can call load_colormap directly: e.g.

chips> load_colormap("fire.cmap")

where the format of the input file is described in the load_colormap help page.

Unlike the previous example, we use the Chandra observation of Abell 2142 as the image, and display it in a two by two grid of plots created by split. Rather than change the label preferences, we create the labels and then use the set_plot command to make sure all plots are current so that we can change the attributes of all the labels with a single call to set_label.

The load_colormap_cubehelix() routine sets the chips_usercmap1 slot to contain the default CubeHelix scheme. We then apply this to the smoothed Abell 2142 data; unlike previous examples we use an 'asinh' scaling, provided by the scale_image_crate routine.

The remaining parts of the script set up the title, using the contents of the OBJECT and TITLE keywords in the header of the image, and a colorbar below the plot, taking care to hide the axes first.

The get_cubehelix() routine is used to get the red, green, and blue components of the color scheme. An alpha channel - the variable a - is created to be the same size as these arrays, and with all values set to 1 (fully opaque). The first 20 elements are then changed so that the alpha channel ramps up linearly from 0 (first element) to 1 (twenty-first element) and then remains at 1 for the remaining elements. The choice over what range to do this scaling depends on the data; here 20 elements corresponds to almost 10 percent of the range and does not remove any of the important information.

The preferences for foreground.display and background.display are changed to make the opacity changes obvious on the screen display.

Note that most of the example code sets up the histogram display. Since ChIPS does not support multiple colors for curves or histograms, we create a histogram for each bin, setting its color by converting the 0-1 range of the red, green, and blue components into a hex-encoded string.

Opacity and Postscript output

Note that the postscript output created by print_window does not support opaque region or histogram fills; instead the opacity is taken to be 1. The relative depth of the objects can be changed - by altering the depth attribute or using the various "shuffle commands" (shuffle, shuffle_back, shuffle_front, shuffle_backward, shuffle_forward, and the set of shuffle_<object> routines) so that overlapping objects are not completely obscured if desired.

The wcs attribute is set to physical in the add_image call to avoid using the world coordinate system for the axes: e.g. as used in the first image example. The set_plot and hide_axis calls are used to make sure the image fills the frame, and to hide both the axes and plot borders (see the earlier overlay-a-contour example for an alternative method for this, using the reposition_plot routine).

The image is then annotated with a vertical dashed line and labels, used to indicate the regions used in creating the radial profiles, as shown by the use of dmhistory below:

unix% dmhistory rprof.n.fits dmextract action=pset
unix% pget dmextract infile
evt2.fits[sky=rect(0,3767,8000,8000)][bin sky=annulus(3786,3767,0:380:4)]

and

unix% dmhistory rprof.s.fits dmextract action=pset
unix% pget dmextract infile
evt2.fits[sky=rect(0,0,8000,3767)][bin sky=annulus(3786,3767,0:380:4)]

In order to provide some idea of the image scale, a circle of radius 200 pixels is drawn - in orange - about the center of the radial profiles. In CIAO 4.7 there is no native support for drawing a circle, so we approximate a circle as a set of line segments evaluated at 60 points around the circle. An alternative approach would have been to use the add_region command, and its support for regular-sided polyhedra to approximate a circle: for example

chips> add_region(60, 3786, 3767, 200/np.sqrt(2), ["fill.style", "none", "line.color", "gold"])

where 60 gives a similar number of vertices to the line version, and the sqrt(2) term is needed to get a circular radius of 200 pixels. The advantage of this approach is that the region is automatically closed, whereas you have to manually ensure it is closed using the line version.

We now add a plot to the bottom-half of the plot, and set its style to open so that the plot borders are not displayed (this removes the top and right borders from the display). The two radial profiles are added as red and green histograms, and the axis limits and scaling changed. A vertical line is added at a radius of 200 pixels in orange to match the circle drawn on the image.

Finally we use the *.color attribute to change the color attribute of all elements of both axes to white so that they will be visible in the hardcopy output created by print_window.

As with the COSMOS survey example, we create a window where the default colors for the on-screen display are set to match the hardcopy versions. This can be useful to check that the chosen color schemes will still be visible in the output created by print_window.

Once the window has been created the make_figure and set_image commands are used to set up the image. We use an Attribute Object - the img object - to set the image properties since we will re-use it later for the inset plot. Note that the image was created from the archival "event 2" file using the command:

unix% dmcopy "acisf03477N002_evt2.fits[energy=500:7000][bin x=1932.5:5565.5:8,y=2214.5:6321.5:8]" \
          img.3477.fits

The image is set to a depth of 50 so that it does not overlap the axis elements, in particular the majorgrid lines that are turned on by the

set_axis(["majorgrid.visible", True])

line. Changing the format used for the ticklabels - namely setting tickformat to ra and dec - also changes the location of these gridlines. All axis elements are set to gray, using the *.color short form, and then the labels, which lie outside the plot area, are set back to the default color (which happens to be black).

The add_region command is used to draw a circle indicating the two-arcminute uncertainty in the location from the GCN circular; we are actually approximating a circle by a 101-sided regular polyhedron.

To provide a close up of this region we add a second plot, within the first one, using the add_plot command, specifying the desired plot location in frame-normalized coordinates. Some trial and error may be required to get sensible values; you can either use undo and change the coordinates in the add_plot call or use either move_plot or reposition_plot to change the plot location.

Once the plot has been added, we add the same image to it as in the first plot, this time using the add_image command since we are not interested in the extra annotations that make_figure provides. Since the image fills the full area of the second plot we do not need to worry about contents of the first plot appearing through the plot as we did in the COSMOS survey example, which is why we did not need to create a second frame here.

Once the same error circle has been drawn we use the panto and zoom commands to change the image area displayed by the plot (for this example a zoom of 500% is a good match to the 4 arcminute diameter of the error circle).

Once the image area has been changed we finish by tidying up the second plot; the axes are hidden and the plot style changed to boxed, then the border axes have their thickness and color changed to provide visual distinction between the two plots.

We have split the task up into two basic parts, an add_thumbnail routine to add the image and the thumbnails() driver routine. With both these routines set up, the visualization is created with a call to thumbnails and then a few calls to set up the 2MASS sources.

We start with the add_thumbnail routine which - given a source number and maximum pixel value - displays an image of the source, and adds both a label and a line (representing 1 arcsecond). The label is positioned in the top-left corner of the plot, using the plot-normalized coordinate system. We want the scale bar - which has a length of one arcsecond - to end at the bottom-right corner of the plot, five percent in from both edges; in other words at a plot-normalized coordinate of (0.95,0.05). Converting these to the data system used by the plot allows us to calculate the length of the bar, correcting for the declination of the source.

The second part - represented by the thumbnails() routine - is the driver routine. Given a set of sources, and a maximum pixel value, it sets up the plots, adds the thumbnails, arranges the grid of plots, and sets up the color bar across the top.

This routine takes advantage of Python decorators to use the add_chips_undo_buffer routine from the chips_contrib.decorators module - provided as part of the CIAO contributed-script package - so that calling this routine will act as if it is a single ChIPS command. That is:

1. will only display the final visualization to the user, so that you do not see all the intermediate steps (it acts as if the window.display setting is False until the close_undo_buffer call),

2. if the commands were successful, they will be treated as a single ChIPS command by the undo and redo routines,

3. and if there was a problem then all the ChIPS commands made up to that point (by the example) will be forgotten, so that the previous visualization will be unchanged.

The set_preferences call is used to change the plot preferences so that a single plot fills most of the frame, which will be used by the grid_objects call later on, and to make the on-screen display use the same colors as the hardcopy versions for the default color and bgcolor values.

For each source we create a plot - with the name src#, where # is the source number - and add the thumbnail to it. At this point the plots all overlap, so we use the grid_objects routine to create a square grid of plots. We could instead have used the split command before the add_thumbnail calls - but then would have had to delete any excess plots (i.e. for those cases when the number of sources is not a square number).

After re-arranging the plots we hide the axes in all the plots, leaving just an outline. As the images were created with a depth less than 100 these plot edges will be visible.

The grid is finished by adding a colorbar above the plots. Since the colorbar is associated with an image, we add it to the first plot, using halign=0 together with an x position of 0 to start the bar at the left edge of the plot. The length of the bar - here given in the cbar variable - is calculated so that the bar extends across all the columns in the grid of plots. The length is defined in the plot-normalized coordinate system of the first plot, so we use the frame-normalized coordinate system, together with convert_coordinate, to convert between the different coordinate systems in use.

After all the X-ray images have been created we mark on sources from the 2MASS catalogue. The file 2mass.315.tsv was created as a tab-separated ASCII file using the catalog support in ds9, and contains the source locations in the RAJ2000 and DEJ2000 columns. Since we have displayed the images using the EQPOS coordinate system, we can just add the catalog values as a curve (the [opt kernel=text/tsv] fragment is needed since this format can not be guessed by the support for ASCII files in the CIAO Data Model). By setting the plot currency to "all" before the add_curve call we add the points to all plots (even though in this case only two plots actually contain a matching source).

The output of the info command after this visualiation looks like:

Window [win1]
  Frame [frm1]
    Plot [src12]   (0.05,0.63)  .. (0.34,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      ColorBar [cbar1]
      Curve [2mass]
    Plot [src13]   (0.36,0.63)  .. (0.64,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      Curve [2mass]
    Plot [src26]   (0.66,0.63)  .. (0.95,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      Curve [2mass]
    Plot [src29]   (0.05,0.34)  .. (0.34,0.61)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      Curve [2mass]
    Plot [src31]   (0.36,0.34)  .. (0.64,0.61)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      Curve [2mass]
    Plot [src35]   (0.66,0.34)  .. (0.95,0.61)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      Curve [2mass]
    Plot [src39]   (0.05,0.05)  .. (0.34,0.32)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      Curve [2mass]
    Plot [src45]   (0.36,0.05)  .. (0.64,0.32)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [image1]
      X Axis [ax1]
      Y Axis [ay1]
      Label [lbl1]
      Line [line1]
      Curve [2mass]

Using the ChIPS buffer routines directly

The add_chips_undo_buffer() routine can be removed and replaced with:

1. The initial import of the "advanced" ChIPS module:

   import pychips.advanced as adv

2. Placing the ChIPS commands in the thumbnails routine within the following try/except/else block:

   adv.open_undo_buffer()
   try:
       ... ChIPS commands ...
   except:
       adv.discard_undo_buffer()
       raise
   else:
       adv.close_undo_buffer()