Regions are two dimensional filters that can be used to include
or exclude data from a given file. They may be applied to any
`vector column' in the file.
Regions are made up of a number of shapes that are described
below. The shapes can either be inclusive or exclusive. The
different shapes can then be combined using either a boolean AND or
boolean OR operation which leads to a degree of flexibility to design
arbitrary regions.
The recognized shapes.
| RECTangle |
(xmin,ymin,xmax,ymax) |
| BOX |
(xcenter,ycenter,width,height) |
| BOX |
(xcenter,ycenter,width,height,angle) |
| ROTBOX |
(xcenter,ycenter,width,height,angle) |
| CIRcle |
(xcenter,ycenter,radius) |
| ANNULUS |
(xcenter,ycenter,iradius,oradius) |
| ELLipse |
(xcenter,ycenter,xradius,yradius,angle) |
| SECTor |
(xcenter,ycenter,minangle,maxangle) |
| PIE |
(xcenter,ycenter,iradius,oradius,minangle,maxangle) |
| POLYgon |
(x1,y1,x2,y2,x3,y3,...) |
| POInt |
(xcenter,ycenter) |
| REGION |
(file) |
| FIELD |
() |
In the table above, the text in capital letters is the minimum allowed
for each shape. The shape names are case insensitive, so
circle(4023.45,3769.23,120)
and
both refer to the same shape.
Angles are given in degrees from the
X axis, with positive values representing the
counter-clockwise direction.
This applies to all regions that take a length parameter (box,
rotbox, circle, annulus, ellipse, and pie).
The length or radius is interpreted as a physical coordinate
value (e.g. sky pixels). If a trailing d, ', or "
is added (e.g. 130d), then the value is interpreted as degrees,
minutes, or seconds of arc, respectively. Two single
quotes will also work for arcseconds.
For the polygon shape, if the last point is not equal to the
first point, it will add another point onto the end to close
the polygon. At present, polygons must be simple; that is they
must not intersect themselves.
Regions can be combined using boolean AND (intersection)
or boolean OR (union) operations. The syntax for these
is given in the table below, where shape1() and shape2()
refer to any recognised shape except for "region()".
Shape arithmetic
| OR |
shape1()+shape2() |
shape1()|shape2() |
shape1()shape2() |
| AND |
shape1()*shape2() |
shape1()&shape2() |
|
| NOT |
!shape1() |
shape1()-shape2() |
|
Region expressions are parsed using the normal precedence rule of the
mathematical "*" and "+" operators, with all "-" operators replaced
by "*!". This means that
circle(0,0,10)+rect(10,-10,20,10)-circle(10,0,10)
is read as
circle(0,0,10)+rect(10,-10,20,10)*!circle(10,0,10)
so that the second circle is only excluded from the rectangle, and
not the first circle. To exclude the second circle from both shapes
you would have to write
circle(0,0,10)-circle(10,0,10)+rect(10,-10,20,10)-circle(10,0,10)
An alternative method of excluding shapes is to use the exclude filter,
described in "ahelp dmfiltering". So, to exclude all rows within
a distance of 20 from (x,y)=(4000,4000) you could use either
"[(x,y)=field()-circle(4000,4000,20)]"
or
"[exclude (x,y)=circle(4000,4000,20)]"
The "region(file)" directive can read in ASCII region files
produced by SAOImage, SAOtng, and PROS (SAOds9 can write
out region files in any of these formats). It can also read
CXC-FITS REGION files, e.g. as produced by the source-detection
tools such as wavdetect or by the dmmakereg tool.
The region directive can not be combined with other shapes.
There are several subtleties with CIAO regions that are worth noting.
These arise particularly when using region files made by imagers like
DS9.
In order for a CIAO tool to make use of a region in
world coordinates, e.g.
circle(06:37:11,-40:20:00,5')
it must know about the mapping between world and
physical coordinates for the dataset in question.
Not all CIAO tools have this ability yet. If you
have problems with celestial coordinates, try
using a region in physical pixel coordinates instead.
DS9 region files saved in celestial coordinates in degrees
are not currently supported in CIAO; celestial coordinates
are only recognized in sexagesimal format.
It's important to understand the difference between two concepts: the
REGION STACK and the REGION FILE.
A region file defines a single 'region' which may have multiple
shapes. For example, a region file with
circle(4096,4096,20)
+circle(5000,2000,100)
is a single region consisting of two circles. Applying a
region file to some data lets CIAO decide whether points are
in the region, but no knowledge is returned about which
of the shapes a point is in.
A region stack contains multiple regions. CIAO will figure
out each of the regions separately. The most common use of
region stacks is in dmextract, where binning on a region
stack creates a histogram where each bin corresponds to
one region.
The syntax is
unix% dmextract "evt.fits[bin sky=@reg.stk]" ...
to operate on a region stack and make a histogram of counts
versus region. In contrast,
unix% dmextract "evt.fits[bin sky=region(reg.stk)]" ...
specifies a single (albeit complicated) region, which
will generate a single output bin.
The CIAO syntax requires excluded regions to follow
included regions. If you draw four circles on DS9,
two includes and two excludes, and then save the region,
the resulting file depends on the order the regions
were drawn. If the order is -circle+circle-circle+circle,
CIAO will not understand because of the leading -circle.
Note that
+circle(4096,4096,1000)
-circle(4096,4096,250)
+circle(4096,4096,50)
will have the inner 50-radius circle included, and the 50-250 radius
annulus excluded, but
+circle(4096,4096,50)
-circle(4096,4096,250)
+circle(4096,4096,1000)
will include everything, as it's interpreted as
"(R50 minus R250) OR R1000", and the R1000 includes everything.
Therefore, you must be careful about order when generating region
files in DS9.
CIAO does not understand all the shapes used in DS9-format
region files. This includes elliptical and box annuli,
the panda shape, and format used for writing grids of annuli.
For simple regions, the area can be calculated using analytical methods.
For complicated regions where shapes overlap, or are close enough that
it's not obvious they don't overlap, we must use a different method;
CIAO divides up the area into bins (which may be smaller than a single
pixel) and counts the number of bins which pass the test 'am I inside
the region?'. This approach using discrete bins has a finite error,
which is usually of order one percent of the area.
Region areas are most commonly used in the BACKSCAL keyword
added to PHA/PI spectral files generated by dmextract. The
error in the area is almost always small compared to other
calibration uncertainties.
Be particularly careful when making regions comparable in size to the
pixel size. When applying such a region to a table which contains
fractional pixel positions, filtering does occur in exactly the area
specified, although the user should be careful about interpretation -
for instance, the true radial profile of a source may be blurred by
aspect, PSF and instrument pixelization. When applying the region to an
image file, filtering will accept all the counts in a pixel if the pixel
center is within the region, and none of them if the pixel center is
outside the region; therefore, the effective area sampled is not quite
the same as the area calculated.
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}