agetcat: Extract astrometry files from astrometric catalogs

Package: astcat

Usage

agetcat regions output

Parameters

regions

The source of the extraction region definitions. The options are:

<filename>: The name of a text file containing a list of region definitions, one region definition per line. The format of the regions file is described in detail below.

<image list>: The list of images containing the region definition. The input images must have a valid FITS world coordinate system in order to be used for region definition.

pars: If regions is set to the reserved keyword "pars" then a single region definition is read from the aregpars parameter set. By default a region ten arc minutes in size around coordinates ra = "00:00:00.0" and dec = "+00:00:00" in the query coordinate system is extracted.

output: The list of output astrometry files. The number of output files must be equal to the number regions in the regions list times the number of astrometry catalogs in the catalog list. By default the output files are assigned names of the form "reg#[.cat#].cat.#" if the region definition source is "pars" or a file e.g. "reg002.cat.1", or "image[.cat#].cat.#" if the region definition source is an image list, e.g. "image.cat.1". The catalog number is only inserted if there is more than one catalog in the catalog list.

aregpars = "": The region definition parameter set. The aregpars parameters define the extraction region center, region width, region center units, and the region center coordinate system. The region definition parameters are used if regions = "pars".

catalogs = ")_.catalogs": The list of input astrometry catalogs. By default the catalog name is set to the value of the package parameter catalogs.

standard = yes: Output a standard astrometry file ? If standard = yes then a header describing the format of the astrometry file is written to the output file. The astcat package tasks use this information to decode the file. If standard = no, no header is written and the user must instruct the astcat tasks how to decode the file.

filter = no: Filter the results of the catalog query before writing the final results to the output astrometry file ?

afiltpars = "": The astrometry file filtering parameter set. These parameters permit the user to sort the output on a field or field expression, select or reject catalog records using a boolean expression, select or reject fields to output, add new fields that are expressions of existing fields to the output, and perform simple coordinate transformations.

update = no: Update the default values of the algorithm parameters, e.g. aregpars and afiltpars, at task termination ?

verbose = yes: Print status messages on the terminal as the task proceeds ?

catdb = ")_.catdb": The catalog configuration file. Catdb defaults to the value of the package parameter catdb. The default catalog configuration file is "astcat$lib/catdb.dat".

Description

Agetcat extracts astrometry files from local or remote astrometry catalogs catalogs using a list of region definitions regions supplied by the user and writes the results of each catalog query to the output astrometry files output.

A region definition consists of the coordinates of the field center, the field size, the units of the field center, and the coordinate system of the field center. If regions = "pars" these quantities are read from the aregpars parameters rcra, rcdec, rcrawidth, rcdecwidth rcraunits, rcdecunits., and rcsystem. If regions is an image they are read from the FITS world coordinate system in the image header. If regions is a file name they are read from a file whose format is the following.

# Optional comment

ra1 dec1 xwidth1 ywidth1 [raunits1 [decunits1 [system1]]]
ra2 dec2 xwidth2 ywidth2 [raunits2 [decunits2 [system2]]]
raN decN xwidthN ywidthN [raunitsN [decunitsN [systemN]]]

Quantities in square brackets are optional. If system is undefined the coordinate system defaults to the query coordinate system, i.e. if the catalog query expects coordinates in J2000.0 then ra and dec will be interpreted as though they were in the J2000.0 system. If undefined the ra and dec units default to the preferred units of the coordinate system, i.e. hours and degrees for equatorial coordinate systems, and degrees and degrees for ecliptic, galactic, and supergalactic coordinate systems.

A sample regions file is shown below. If the catalog query system is J2000.0 then all four region definitions are equivalent, since J2000.0 is assumed in examples 1 and 2, is specified in example 3, and example 4 is same region as example 3 but expressed in the B1950.0 coordinate system.

# List of targets

13:29:53.27 +47:11:48.4 10.0 10.0
13:29:53.27 +47:11:48.4 10.0 10.0 hours degrees
13:29:53.27 +47:11:48.4 10.0 10.0 hours degrees J2000.0
13:27:46.90 +47:27:16.0 10.0 10.0 hours degrees B1950.0

For each specified astrometry catalog in catalog agetcat loops through the regions list, formats the catalog query, makes a local or remote connection to the catalog server using the catalog description in the catalog configuration file catdb, and captures the results. Catalog names must be of the forms catalog@site, e.g. usno2@noao. Catalog names without entries in the catalog configuration file are skipped.

If filter = yes, the captured results are filtered using the values of the parameters in the filtering parameter set afiltpars. The afilterpars parameters permits the user to sort the query results by setting the sort field parameter fsort, select or reject catalog records by setting the selection expression parameter fexpr, select or reject fields for output by setting the output field list parameter fields, and change the coordinate system, units, and format of the catalog coordinates by setting the fosystem, foraunits, fodecunits, foraformat, and fodecformat parameters. A more detailed description of the region filtering parameters can be obtained by typing "help afiltpars".

If standard = yes a header is written to the output astrometry file which defines the contents and format of the output object list. The astcat tasks use this header to decode the input catalog files. If it is missing or has been modified by non-astcat tasks the user must use the acatpars parameters to define the astrometry file format. Most non-astcat tasks will interpret the astrometry file header as documentation and skip it.

If update = yes the values of the aregpars and afilterpars parameters will be updated at task termination. If verbose = yes then detailed status reports are issued as the task executes.

Examples

1. Extract data from the default catalog using the default region definition and page the results to determine the catalog format, i.e. the number and names of the default output fields.

cl> agetcat pars default
cl> page reg001.cat.1

2. Repeat the previous example but sort the output on the sort field "mag1".

cl> agetcat pars default filter+ fsort=mag1
cl> page reg001.cat.2

3. Repeat example 2 but output only those records for which mag <= 16.0.

cl> agetcat pars default filter+ fsort=mag1 fexpr="mag1 <= 16.0"
cl> page reg001.cat.3

4. Repeat example 3 but output a new field equal to mag2 - mag3.

cl> agetcat pars default filter+ fsort=mag1 fexpr="mag1 <= 16.0" \
fields="f[*],mag2-mag1"
cl> page reg001.cat.4

5. Run agetcat on the text file regions which contains a list of region definitions. Note that the coordinate system and coordinate units default to those expected by the catalog query. The latter information can be determined by running aclist on the default catalog.

cl> page regions
00:00:00.0 -90:00:00 10.0 10.0
00:00:00.0 -60:00:00 10.0 10.0
00:00:00.0 -30:00:00 10.0 10.0
00:00:00.0 +00:00:00 10.0 10.0
00:00:00.0 +30:00:00 10.0 10.0
00:00:00.0 +60:00:00 10.0 10.0
00:00:00.0 +90:00:00 10.0 10.0
cl> agetcat regions default
cl> page reg001.cat.5
cl> page reg002.cat.1
cl> page reg003.cat.1
cl> page reg004.cat.1
cl> page reg005.cat.1
cl> page reg006.cat.1
cl> page reg007.cat.1

6. Repeat example 5 but find data for two catalogs the usno2@noao and gsc@cadc.

page regions
00:00:00.0 -90:00:00 10.0 10.0
00:00:00.0 -60:00:00 10.0 10.0
00:00:00.0 -30:00:00 10.0 10.0
00:00:00.0 +00:00:00 10.0 10.0
00:00:00.0 +30:00:00 10.0 10.0
00:00:00.0 +60:00:00 10.0 10.0
00:00:00.0 +90:00:00 10.0 10.0
cl> agetcat regions default catalogs="usno2@noao,gsc@noao"

7. Run agetcat on a list of images containing valid FITS WCS information. Note that in the following example the test image dev$pix does not have a FITS WCS so no data is extracted for it.

cl> page imlist
dev$pix
dev$ypix
cl> agetcat @imlist default
cl> page wpix.cat.1

agetcat: Extract astrometry files from astrometric catalogs

Usage

Parameters

Description

Examples

Time requirements

Bugs

See also