add_fov_region

Context: contrib

Synopsis

Display a Chandra FOV (field-of-view) file as a region.

Syntax

add_fov_region(fov)
add_fov_region(fov, wcs)
add_fov_region(fov, attrs)
add_fov_region(fov, wcs, attrs)

fov is either a filename or a Crate (the return value of read_file).
wcs defaults to "world"; it can be one of "world", "eqpos", "physical",
"pos", or "sky".
attrs is one of a ChipsRegion structure, an attribute list, or an
attribute string.

Description

This routine provides a quick way to plot up a FOV file of a Chandra observation, where each chip is displayed as a region (at least as long as the shape for the chip is a Polygon). Multiple FOV files can be plotted up, e.g. to show how a set of observations overlap, or they can be added on top of an image, to show what areas Chandra observered.

Loading the routine

The routine can be loaded into a ChIPS, Sherpa or Python session by saying:

from chips_contrib.regions import *
from chips_contrib.all import *

where the second line will load in all the ChIPS contributed routines, not just the regions module.

Adding axes and changing limits

Unlike a normal add_region call, the add_fov_region command will

create axes, if none are present, and set the data aspect ratio;
change the axes limits to include the region, even if the axes have been set to display a fixed range.

Limits and the data-aspect ratio

The add_fov_region command takes advantage of the aspect-ratio support added in CIAO 4.2 (see "ahelp aspectratio") to ensure that the aspect ratio of the plot is maintained as new FOV files are added to the plot. This can result in the final display only showing a subset of the full area, since ChIPS has to chose what limits to use to maintain the aspect ratio.

Examples

Example 1

chips> from chips_contrib.all import *
chips> clear()
chips> add_fov_region("acisf01234_000N001_fov1.fits")
chips> add_fov_region("acisf01235_000N001_fov1.fits",
["fill.color", "red"])

The first line (from chips_contrib.all import *) loads the add_fov_region() routine; it only needs to be made once per ChIPS session.

The remaining commands create a plot showing the FOV areas of two observations: obsid 1234 and obsid 1235. The first set of regions will be filled in green (the default values for a region), whereas the second observation use a red fill color.

The last command could also have been written as either:

chips> add_fov_region("acisf01235_000N001_fov1.fits", "fill.color=red")

chips> r = ChipsRegion()
chips> r.fill.color = "red"
chips> add_fov_region("acisf01235_000N001_fov1.fits", r)

If obsid 1234 contained data for ACIS CCD_IDs 0,1,2,3 and obsid 1235 only contained ACIS CCD_IDs 6 and 7 then the output of the info command after the above would be:

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 [obsid1234-ccd0]
      Region [obsid1234-ccd1]
      Region [obsid1234-ccd2]
      Region [obsid1234-ccd3]
      Region [obsid1235-ccd6]
      Region [obsid1235-ccd7]

Example 2

chips> clear()
chips> add_image("dss.fits")
chips> add_fov_region("acisf01234_000N001_fov1.fits",
["fill.style", "none"])
chips> add_fov_region("acisf01235_000N001_fov1.fits",
["fill.style", "none"])

Here we plot up an image - "dss.fits", in this case an optical observation of the area from the STScI Digitized Sky Survey - and overlay on the Chandra field of views. Unlike the previous example we remove the solid fill, so only the chip edges are shown.

Example 3

chips> cr1 = read_file("1234/primary/acisf01234_000N001_fov1.fits")
chips> cr2 = read_file("1235/primary/acisf01235_000N001_fov1.fits")
chips> clear()
chips> add_image("dss.fits")
chips> add_fov_region(cr1, ["opacity", 0.2])
chips> add_fov_region(cr2, ["opacity", 0.2, "fill.color", "orange"])

In this example the two FOV files are read in using the Crates read_file command, and the return values (cr1 and cr2) sent to add_fov_region for plotting. In this case we reduce the opacity from the default value of 0.5 to 0.2 for both observations.

Example 4

chips> clear()
chips> add_fov_region("fov1.fits[ccd_id<4]")
chips> add_fov_region("fov1.fits[ccd_id>3]", ["fill.color", "red"])

Here we plot up the chips from the ACIS-I array of an observation in green, and those chips in the ACIS-S array in red.

Changes in the December 2010 Release

Module name change

To load in all the ChIPS contributed modules you now have to say one of

import chips_contrib.all
from chips_contrib.all import *

rather than

import chips_contrib
from chips_contrib import *

which no longer loads in any code.

WCS axis support

The code has been updated to take advantage of the WCS axes support in ChIPS. Users should not see any major changes in behavior.

Bugs

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