NAME

afiltcat -- filter astrometry files

USAGE

afiltcat input output

PARAMETERS

input

The list of input astrometry files. Astrometry files may be created by other astcat tasks, e.g. agetcat, in which case they are preceded by a header describing the format of the input astrometry file, or by other IRAF or user tasks in which case the acatpars parameter set must be used to describe them.

output

The list of output astrometry files. The number of output astrometry files must be equal to the number of input astrometry files. If the output file name equals the input file name then the original astrometry file is overwritten.

acatpars = ""

The default input astrometry file format parameters. The acatpars parameters are used only if the input astrometry file does not have a header. Type "help acatpars" for a detailed description of the acatpars parameters.

catalogs = "filename@noao"

The dummy input catalog name. Afiltcat task users should leave this parameter at its default setting.

standard = yes

Output a standard astrometry file ? If standard = yes then a header describing the format of the output astrometry file is written to the output file. Astcat package tasks use this information to decode the astrometry file. If standard = no, no header is written and astcat tasks must use the acatpars parameters to decode the astrometry file.

filter = yes

Filter rather than copy the input astrometry file to the output astrometry file ?

afiltpars = ""

The astrometry file filtering parameter set. Afiltpars 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 to the output that are expressions of existing fields, and perform simple coordinate transformations.

update = no

Update the default values of the algorithm parameter sets, e.g. acatpars and afiltpars, on 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 parameters catdb. The default catalog configuration file is "astcat$lib/catdb.dat".

DESCRIPTION

Afiltcat filters the list of input astrometry files input and writes the results to the output files output . The number of input astrometry files must equal the number of output astrometry files.

The format of the input astrometry files is defined by the file header if the file was written by an astcat package task, or by the acatpars parameter set. The acatpars parameters ftype and csystem define the input astrometry file type and coordinate system. The position, size, and units of the standard astrometry file fields the associated error fields are defined by the parameters: id , ra , dec , pmra , pmdec , catsystem , equinox , epoch , px , rv , mag , color , xp , yp , xc , yc , and imag , and: era , edec , epmra , epmdec , epx , erv , emag , ecolor , exc , eyc , eimag . More detailed information on astrometry files and the acatpars parameters can be found by typing "help files" and "help acatpars".

If filter = yes, the input astrometry file is filtered before being written to the outputfile. The filtering parameters are defined by the filtering parameter set afiltpars . The afilterpars parameters permit 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 afields , and change the coordinate system, units, and format of the output coordinates by setting the fosystem , foraunits , fodecunits , foraformat , and fodecformat parameters. A more detailed description of the filtering parameters can be obtained by typing "help afiltpars".

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

If update = yes the values of the acatpars and afiltpars parameters are updated at task termination. If verbose = yes then detailed status reports are issued as the task executes.

EXAMPLES

1. Sort the input astrometry file using the value of the magnitude field.

cl> page reg001.cat.1
... examine catalog header to determine name of magnitude field
cl> afiltcat reg001.cat.1 reg001.cat.2 fsort=mag1

2. Repeat example 1 but but only output records for which mag1 <= 16.0.

cl> afiltcat reg001.cat.1 reg001.cat.3 fsort=mag1 fexpr="mag1 <= 16.0"

3. Repeat example 2 but since the input astrometry file has 2 magnitude columns output a new color field equal to "mag2 - mag1".

cl> afiltcat reg001.cat.1 reg001.cat.4 fsort=mag1 fexpr="mag1 <= 16.0" \
fields="f[*],mag2-mag1"

4. Repeat example 1 but overwrite the input astrometry file.

cl> page reg001.cat.1
... examine catalog header to determine name of magnitude field
cl> afiltcat reg001.cat.1 reg001.cat.1 fsort=mag1

5. Filter a list of input astrometry files by extracting columns 1-4 but reversing the order of fields 3 and 4. Overwrite the input files.

cl> afiltcat @inlist @inlist fields="f[1-2],f4,f3"

6. Repeat the previous example for a list of text files which have no catalog headers but contain the ras and decs in hours and degrees in J2000 coordinates of a list of source in columns 1 and 2 of a simple text file.

cl> afiltcat @inlist @inlist ftype="stext" csystem=j2000 ra="1 hours" \
    dec="2 degrees" mag="3-4" fields="f[1-2],f4,f3"

TIME REQUIREMENTS

BUGS

SEE ALSO

aclist, agetcat, acatpars, afiltpars