/ ciao4.17 / ahelp / regphystocel.html

Jump to: Description · Examples · Parameters · About Contributed Software · See Also

AHELP for CIAO 4.17

regphystocel

Synopsis

Convert regions in physical coordinates to ds9 format regions in celestial (fk5) coordinates.

Syntax

regphystocel  infile outfile [wcsfile] [text] [tag] [verbose] [clobber]

Description

`regphystocel' will convert a region file stored in physical coordinates into a ds9-format region file using celestial coordinates. Most CIAO tools can make use of regions in either physical or celestial coordinates. However, when working with multiple observations with possibly different tangent plane projection parameters, using celestial coordinates may be necessary. This is the case when using the srcflux script with multiple observations.

The input region file can be either a FITS region file or an CIAO ASCII region file. The infile can also just be a region string.

The tool takes position and radius (in physical pixels) of each shape and applies the world coordinate system (WCS) transform. The angle is not modified (always measured counter-clockwise from the +X axis). If using a FITS region file, it may contain the WCS necessary to do the conversion to celestial coordinates; otherwise users can supply an image or event file as the wcsfile parameter.

Limitations

CIAO regions support complex region logic using logical AND and logical OR operations; the ds9 format does not support this. The following shapes are not supported: 'field', 'pie', and 'sector'.

Text and Tags

Regions stored in the ds9 format can have a title that will optionally be displayed above the region. They can also have one or more "tags" which allows the user to group sources together; users can access the list of groups by going to Region -> Groups ... from the ds9 main menu. When using a FITS region file regphystocel can take values from columns or keywords and populate the title or tags properties.

Examples

Example 1

% regphystocel ciao.reg ds9.reg wcsfile=img.fits

The ASCII region stored in the file "ciao.reg" is converted to celestial coordinates using the WCS from the "img.fits" file. The output is written to "ds9.reg" which will look similar to this:

# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
fk5
ellipse(01:13:51.0473,13:16:17.8925,1.26168",1.17667",25.8786)

Example 2

% regphystocel fov.fits fov.reg

The FITS region file "fov.fits" is converted to celestial coordinates using the WCS provided in the file itself. Most FITS region files will have a WCS. To determine if the file has a WCS just

% dmlist fov.fits cols
...
--------------------------------------------------------------------------------
World Coord Transforms for Columns in Table Block FOV
--------------------------------------------------------------------------------
 
ColNo    Name
1:    EQPOS(RA ) = (+18.4654)[degree] +TAN[(-0.000136667)* (POS(X)-(+4096.50))]
           (DEC)   (+13.2705)              (+0.000136667)  (   (Y) (+4096.50))

and in the "World Coord Transforms" section look for either "EQPOS" or "EQSRC". If neither is present, then a wcsfile which does have one of those two transforms must be supplied.

Example 3

% regphystocel "circle(4096.5,4096.5,100)-box(4096.5,4096.5,100,100)"
ds9.reg wcsfile=img.fits

In this example the region is provided directly in the infile parameter. While the ds9 format does not support the full CIAO logical AND and logical OR expressions, it does supported include and excluded shapes as shown here:

# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
fk5
circle(01:13:51.6855,13:16:13.8493,49.2")
-box(01:13:51.6855,13:16:13.8493,49.2",49.2")

Example 4

% regphystocel cell.src ds9.reg text=component
tag=double,double_id,obs_id

In this example we use the text and tag parameters to specify additional metadata to extract from the FITS region file (cell.src) and store in the ds9 region file. The value of the COMPONENT column are stored in the text field and will be displayed above the regions. The values for the double and double_id columns as well as the obs_id keyword are stored as tags. The output will look something like this:

# Region file format: DS9 version 4.1
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" select=1 highlite=1 dash=0 fixed=0 edit=1 move=1 delete=1 include=1 source=1
fk5
ellipse(05:23:0.8521,33:28:17.0340,1.50728",1.38265",175.227) # text={1}  tag={double=False} tag={double_id=0} tag={obs_id=4396}
ellipse(05:23:0.6545,33:28:6.6130,1.4234",1.28935",39.5983) # text={2}  tag={double=False} tag={double_id=0} tag={obs_id=4396}
ellipse(05:22:40.0080,33:28:31.1923,1.49205",1.23199",22.1857) # text={130}  tag={double=False} tag={double_id=0} tag={obs_id=4396}
ellipse(05:23:6.6306,33:28:8.8049,2.28348",1.86101",156.246) # text={131}  tag={double=True} tag={double_id=343} tag={obs_id=4396}
ellipse(05:23:5.3125,33:28:36.8242,3.32145",2.22307",115.958) # text={137}  tag={double=True} tag={double_id=139} tag={obs_id=4396}

In ds9, the user will see following groups: double=False, double=True, double_id=0, double_id=343, double_id=139, and obs_id=4396. The user can select the source in these groups for additional analysis.

Only a single column or keyword can be used for the text parameter. The tag parameter is a stack of column or keyword names.

Parameters

name	type	ftype	def	min	max	reqd	stacks
infile	file	input				yes
outfile	file	output				yes
wcsfile	file	input				no
text	string					no	no
tag	string					no	yes
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input region.

The infile can be either an ASCII CIAO region file (using physical coordinates) or a FITS format region file (always assumed to be using physical coordinates). Users can also supply a simple region expression.

Parameter=outfile (file required filetype=output)

Output file name.

The output is a ds9 format region file using celestial coordinates.

Parameter=wcsfile (file not required filetype=input)

File used to obtain world coordinate system transformation.

If the infile does not contain a recognized WCS, then users must supply a wcsfile which does. The infile or wcsfile must contain either an EQPOS or EQSRC coordinate transform. If the wcsfile is specified and the infile also has a WCS, the wcsfile parameters are used.

Parameter=text (string not required stacks=no)

The column value or keyword name to use for the region's text label.

When the infile is a FITS region file, the user can specify a column or keyword to use for the text label associated with each region.

Parameter=tag (string not required stacks=yes)

The column values or keyword names to use to tag each region.

When the infile is a FITS region file, the user can specify a stack columns and/or keywords to use for as grouping tags. Groups can be used to attach additional information to a region such as which source is associated with which background; which sources are extended, adding properties like number of counts, etc.

Parameter=verbose (integer default=1 min=0 max=5)

Amount of tool chatter level.

Parameter=clobber (boolean default=no)

Overwrite output files if they already exist?

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.