Skip to the navigation links
Last modified: 11 October 2018

URL: https://cxc.cfa.harvard.edu/chips/gallery/annotations.html

Gallery: Annotations

Examples

  1. Using regular-sided regions to show the fill styles provided by ChIPS
  2. Using regions to display the field-of-view files of a Chandra observation
  3. Comparing Chandra and Suzaku observations
  4. The COSMOS survey

1) Using regular-sided regions to show the fill styles provided by ChIPS

This example highlights the range of fill styles (patterns) provided in ChIPS. Here we use a set of regular-sided regions to show off the different patterns; the other object type that can be filled with a pattern is a histogram, as shown in this earlier example.

[ChIPS output]
Version: Postscript; PDF
# Create a plot, that fills the frame, with no borders
add_plot(0,0,1,1,["style","open","window.width",8,"window.height",8,"window.units","inches"])

# Create regular-sided regions spaced evenly across
# the plot, each with a different fill pattern
pref = ChipsPreferences()
pref.region.opacity = 1
pref.region.edge.color = "default"
pref.region.fill.color = "brown"
pref.region.edge.style = "longdash"
set_preferences(pref)

# Row 1
add_region(3,0.125,0.875,0.1,["fill.style","nofill"])
add_region(4,0.375,0.875,0.1,["fill.style","solid"])
add_region(5,0.625,0.875,0.1,["fill.style","updiagonal"])
add_region(6,0.875,0.875,0.1,["fill.style","downdiagonal"])

# Row 2
add_region(7,0.125,0.625,0.1,["fill.style","horizontal"])
add_region(8,0.375,0.625,0.1,["fill.style","vertical"])
add_region(9,0.625,0.625,0.1,["fill.style","crisscross"])
add_region(10,0.875,0.625,0.1,["fill.style","brick"])

# Row 3
add_region(11,0.125,0.375,0.1,["fill.style","grid"])
add_region(12,0.375,0.375,0.1,["fill.style","hexagon"])
add_region(13,0.625,0.375,0.1,["fill.style","polkadot"])
add_region(14,0.875,0.375,0.1,["fill.style","wave"])

# Row 4
add_region(15,0.125,0.125,0.1,["fill.style","flower"])
add_region(16,0.375,0.125,0.1,["fill.style","userfill1"])
add_region(17,0.625,0.125,0.1,["fill.style","userfill2"])
add_region(18,0.875,0.125,0.1,["fill.style","userfill3"])

# Add a region overlapping the bottom row, showing
# opacity (not for the ps and PDF formats)
x = [0.1, 0.9, 0.9, 0.1]
y = [0.05, 0.05, 0.2, 0.2]
add_region(x,y,["fill.color","cyan","opacity",0.5])

For this visualization we create a plot that fills the frame, and hide its borders by setting the plot.style to open. We then create 16 regions - using add_region - positioned on a grid designed to fill the plot; since there has been no data added to the plot (i.e. no curves, histograms, contours, or images), the regions are positioned using the plot-normalized coordinate system, which has (0,0) as the bottom-left of the plot and (1,1) as the top-right of the plot.

Each of the 16 regions is created with a different number of sides and fill style. We add a seventeenth region across the bottom row, this time providing the vertices of the region as two arrays. Since the opacity of this region is less than 1, the contents of objects drawn below it - i.e. with a smaller depth value - are not fully obscured.

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.


2) Using regions to display the field-of-view files of a Chandra observation

This example uses the add_fov_region command - from the chips_contrib.regions module - to plot up the Field-Of-View (fov) files provided with each Chandra observation. In this example we show the areas of the sky covered by the Chandra observations of Abell 2142 with Observation Ids of 5005 and 7692.

[ChIPS output]
Version: Postscript; PDF
# Load in the add_fov_region command
from chips_contrib.all import *

add_fov_region("fov_5005.fits")
add_fov_region("fov_7692.fits",["*.color","brown"])

# Clean up the axis labels and add a title to the plot
set_plot_xlabel("")
set_plot_ylabel("")
set_plot(["leftmargin",0.2])
set_plot_title(r"Abell 2142 - ObsId: \color{green}5005  \color{brown}7692")

In order for the add_fov_region command to be used, the chips_contrib.regions module has to be loaded (this only needs to be done once per session). If the import fails then please ensure that the latest version of the CIAO contributed-scripts package is installed.

The add_fov_region command creates a set of regions, one for each chip in the FOV file, with the given region attributes. In the first call we use the default region preferences, whilst the second call changes all the color attributes of the region to brown.

The final commands remove the axis labels, increase the left margin of the plot, and set up a plot title; note the support for LaTeX-like commands in labels.

The resulting set of objects in the vizualization are:

chips> info()

Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.20,0.15)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Region [obsid5005-ccd0]
      Region [obsid5005-ccd1]
      Region [obsid5005-ccd2]
      Region [obsid5005-ccd3]
      Region [obsid5005-ccd6]
      Region [obsid7692-ccd0]
      Region [obsid7692-ccd1]
      Region [obsid7692-ccd2]
      Region [obsid7692-ccd3]

Opacity

The default opacity for the region fill is 0.5, which means that it is possible to see how the ACIS chips overlap in the multiple observations. It does not, however, scale linearly with the depth of the observation.

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.


3) Comparing Chandra and Suzaku observations

Here we overlay the FOV files shown in the previous example onto Suzaku and Chandra data of Abell 2142: the Suzaku image is a smoothed version from the Suzaku archive and the Chandra data is the same as used in earlier examples.

In this case we turn off the region fill for both FOV files, although this is not necessary.

[ChIPS output]
Version: Postscript; PDF
# Load in the add_fov_region command
from chips_contrib.all import *

# Display the Suzaku observation and overlay Chandra contours
add_image("a2142_suzaku_smoothed.img",["id","suzaku","colormap","heat"])
add_contour("a2142_smoothed.fits",["id","chandra"])

# Overlay the Chandra observation fov files
add_fov_region("fov_5005.fits[ccd_id<5]",["fill.style","nofill"])
add_fov_region("fov_7692.fits",["fill.style","nofill","edge.color","orange"])

# Re-center the display so that the two FOV outlines are visible
panto(239.572,27.30)

# Remove the axes and borders, fill the window, and make sure the
# frame background matches the zero-pixel color of the image
set_plot(["style","open"])
hide_axis()
reposition_plot(0,0,1,1)
set_frame(["bgcolor","black"])

Since we set fill.style to nofill, the FOV areas are indicated by green and orange polygons on top of the image.

The panto command is used to ensure that the outlines of the ACIS-I array from both observations are within the plot area. The final commands remove the axes and plots from the display and then re-sizes the plot so it fills the display.

The resulting set of objects in the visualization are:

chips> info()

Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.00,0.00)  .. (1.00,1.00)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      Image [suzaku]
      X Axis [ax1]
      Y Axis [ay1]
      Contour [chandra]
      Region [obsid5005-ccd0]
      Region [obsid5005-ccd1]
      Region [obsid5005-ccd2]
      Region [obsid5005-ccd3]
      Region [obsid5005-ccd6]
      Region [obsid7692-ccd0]
      Region [obsid7692-ccd1]
      Region [obsid7692-ccd2]
      Region [obsid7692-ccd3]

Regions that extend outside of the plot

To avoid the PS and PDF issue with displaying regions that extend outside the plot area - as seen in the CIAO 4.3 version of this visualization - the ACIS-S3 chip outline is excluded when displaying fov_5005.fits, and the display area is now centered on 239.572, 27.30, using the panto command, rather than using

limits(chips_image, "suzaku")

to display all of the Suzaku image.


4) The COSMOS survey

Here we use the add_fov_region command to display the coverage of the Chandra observations of the COSMOS survey (it does not include the COSMOS-Legacy fields). The FOV files used are named fov.<obsid>.fits, and are copies of the archival files, which have names like 7995/primary/acisf07995_000N001_fov1.fits.

[ChIPS output]
Version: Postscript; PDF
# Load in the glob module and the add_fov_region command
import glob
from chips_contrib.all import add_fov_region

# Set up preferences and create a window
set_preferences(["region.edge.style","noline","region.opacity",0.1])
add_window(8,8,"inches",["foreground.display","black","background.display","white"])

# Add a region for each observation (ACIS-I chips only)
for fname in glob.glob("fov.*.fits"):
    add_fov_region(fname + "[ccd_id=0:3]", ["fill.color", "blue"])

# Add the ACIS-S data in a separate plot in the top-right corner.
# We use a frame so that the background does not show through.
#
add_frame(0.75,0.75,1,1,["border.visible",True])
add_plot(0,0,1,1,["style","open"])

for fname in glob.glob("fov.*.fits"):
    add_fov_region(fname + "[ccd_id>3]", ["fill.color", "red"])

# Now that axes have been created we want to hide them
hide_axis()

# Label the plots
current_frame("frm1")
set_plot_title("The Chandra COSMOS observations")
add_label(0.05,0.9,"ACIS-I",["coordsys",PLOT_NORM,"color","blue","size",18])

# get the plot range
pr = get_plot_range()

current_frame("frm2")

# add a line to indicate the plot range of the main plot
xl = [pr[0], pr[1], pr[1], pr[0], pr[0]]
yl = [pr[2], pr[2], pr[3], pr[3], pr[2]]
add_line(xl,yl,["style","longdash"])

add_label(0.15,0.8,"ACIS-S",["coordsys",PLOT_NORM,"color","red","size",18])

In this example we set up the window to have a white background and to draw objects in black, by setting the foreground.display and background.display settings, which matches the values used for the hardcopy outputs created by print_window. This can be useful when using partially-opaque regions, as we do here.

The glob routine is used to select all the FOV files that match the given pattern; these are then iterated through one at a time and regions created for the ACIS-I array (blue) by using the ccd_id Data Model filter in the add_fov_region calls. Once the ACIS-I regions have been displayed the plot margins are adjusted slightly to better take advantage of the window.

We choose to display the ACIS-S regions as an "inset" plot (actually, an overlapping plot) in the top-right of the window. To do this we create a second frame, using add_frame, and add a plot to it that fills the frame. The ACIS-S chips are then displayed using essentially the same loop as above. By making the frame border visible, setting the plot style to "open", and hiding both the axes in this plot we end up with a simple border, with no annotations, such as tick marks or labels. The reason for placing the second plot in its own frame, rather than just adding it to the existing frame, is to ensure that the plot obscures anything behind it (you can enter

set_frame("frm2", ["transparency", True])

to see how the visualization would look if done all in a single frame). The WCS Axis grids example shows an example of an inset plot created without adding a second frame.

To finish off we add a title to the first plot - which requires changing frame - and a label. We also use the get_plot_range command to get the axis ranges; this is then used in the second plot to draw a dashed line indicating the boundary of the main plot. The info output at the end looks something like (most regions have been excluded to save space):

Window [win1]
  Frame [frm1]
    Plot [plot1]   (0.15,0.15)  .. (0.90,0.90)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Region [obsid8024-ccd0]
      Region [obsid8024-ccd1]
      ...
      Region [obsid8000-ccd3]
      Label [lbl1]
  Frame [frm2]
    Plot [plot1]   (0.00,0.00)  .. (1.00,1.00)
      Border bottom [bx1]  top [bx2]  left [by1]  right [by2]
      X Axis [ax1]
      Y Axis [ay1]
      Region [obsid8024-ccd6]
      Region [obsid8024-ccd7]
      ...
      Region [obsid8000-ccd7]
      Line [line1]
      Label [lbl1]

Opacity

The regions are partly opaque which means that it is possible to see how the ACIS chips overlap in the multiple observations. It does not directly relate to the resulting depth of the observation.

Note that the final visualization depends on the order that the FOV files are added, which in this case depends on the value returned by the glob command.

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.