|AHELP for CIAO 4.2||
CIAO region filtering syntax
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.
For a general introduction to table and image filtering in CIAO, refer to "ahelp dmfiltering".
The recognized shapes.
In the table above, the text in capital letters is the minimum allowed for each shape. The shape names are case insensitive, so
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()".
Region expressions are parsed using the normal precedence rule of the mathematical "*" and "+" operators, with all "-" operators replaced by "*!". This means that
is read as
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
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
The "region(file)" syntax is used to read FITS or ASCII region files. The files may be created in ds9, generated by the source-detection tools such as wavdetect, or created the dmmakereg tool. The region() syntax can not be combined with other shapes.
Here the dmstat tool is given only those rows of the file evt2.fits that pass the filter, in this case a circle centered at (4000,4000) and with a radius of 20 using the SKY values. Since "sky" is the name of a vector column in the file and translates to "(x,y)", the command could have been written as
where we have also taken advantage of the fact that the region name does not have to be fully spelled out.
Note that the default behavior for region filters is to exclude the entire field and then start adding to it.
The region used to filter the image "img.fits" consists of the whole image (as indicated by the "field()" shape) with a circular region removed from it. Since no coordinate system was given in the filter expression, the logical system is used, so that the above is a short form for
To use other coordinate systems for the filter, include the name of the axes in the expression; for example
Filter the file on the energy and time columns with the region stored in the file ds9.reg. Although the pha, pi pair do not form a vector column, you are allowed to define a paired column like this on the fly provided their datatypes are the same.
dmextract "evt2.fits[sky=region(src.fits[#row=2])][bin pi=::5]" spectrum.fits
Create a spectrum from the second source in the FITS region file and bin it by a factor of 5.
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.
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
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 firstname.lastname@example.org]" ...
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.
+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.
See the region library bugs page on the CIAO website for an up-to-date listing of known bugs.
- coords, level, pileup, times
- autoname, ciao, ciaorc, parameter, stack, subspace
- dm, dmascii, dmbinning, dmfiltering, dmopt
- pixlib, stackio
- dither_region, dmcontour, dmgroupreg, dmimgfilt, dmimglasso, dmmakereg, get_src_region, mkbgreg, mksubbgreg, tg_create_mask