afiltpars: Default astrometry file filtering parameters

Package: astcat

Usage

afiltpars

Parameters

fsort = "": The field or field expression on which to sort the catalog / file records. The sort may be numeric or character. Sort fields may be expressed by name, e.g. "mag1" or field number, e.g. "f3". Sort expressions must be a combination of existing fields, e. g. "mag2 - mag1" or "f4 - f3". By default the records are not sorted.

freverse = no: Sort in descending order ?

fexpr = yes: The boolean record selection expression. By default all catalog / file records are selected, otherwise only records matching the selection expression are selected. Selection expressions must be combination of existing fields and field expressions, e.g. "mag1 < 16.0", or "(f4 - f3) < 1.5".

fields = "f[*]": The list of output fields and field expressions. By default the sorted and selected records are output as is. Output fields may be field names, e.g. "mag1", field numbers e.g. "f3", or field ranges e.g. "f[1-4]". Output field expressions must be a combination of existing fields, e.g. "mag2 - mag1", or "f4 - f3".

fnames = "": The list of new field names separated by commas. By default new fields, e.g. fields that are expressions of existing fields are assigned names of the form "f#" where # is the field sequence number. Field names must be valid tokens, i.e. they cannot be expressions or contain embedded blanks.

fntypes = "": The list of new field types separated by commas. By default new fields are assigned type real. Permitted field types are "s" for string, "i" for integer, "r" for real, or "d" for double.

fnunits = "": The list of new field units separated by commas. By default new fields are assigned units of INDEF. Units specifications may not contain embedded blanks.

fnformats = "": The list of new field formats. By default string, integer, and floating point fields are assigned formats of "%10s", "%10d", and "%10g" respectively.

fosystem = "": The output celestial coordinate system. If fosystem is undefined it defaults to the catalog celestial coordinate system. Popular options are "icrs", "j2000.0", "b1950.0". The full set of options can be examined by typing "help ccsystems".

fira = "ra": The name of the catalog field containing the right ascension / longitude of an object. Most users should leave fira set to "ra". If the user knows the number of the right ascension / longitude field the generic field name "f#", e.g. "f1" can be used.

fidec = "dec": The name of the catalog field containing the declination / latitude of an object. Most users should leave fidec set to "dec". If the user knows the number of the declination / latitude field the generic field name "f#", e.g. "f2" can be used.

foraunits = "": The units of fira. Permitted values are "hours", "degrees", and "radians". If foraunits is undefined it defaults to the preferred units of the output celestial coordinate system fosystem, e.g. hours for equatorial coordinate systems and degrees for ecliptic, galactic, and super-galactic coordinate systems.

fodecunits = "": The units of fidec. Permitted values are "degrees" and "radians". If fodecunits is undefined it defaults to the preferred units of the output celestial coordinate system fosystem, e.g. degrees for all systems.

foraformat = "": The format of fira. If undefined foraformat defaults to the equivalent catalog format.

fodecformat = "": The format of fidec. If undefined fodecformat defaults to the equivalent catalog format.

fixp = "xp": The name of the catalog field containing the predicted x coordinate of an object. Most users should leave fixp set to "xp". If the user knows the number of the predicted x coordinate field the generic field name "f#", e.g. "f1" can be used.

fiyp = "yp": The name of the catalog field containing the predicted y coordinate of an object. Most users should leave fiyp set to "yp". If the user knows the number of the predicted y coordinate field the generic field name "f#", e.g. "f2" can be used.

fixc = "xc": The name of the catalog field containing the centered x coordinate of an object. Most users should leave fixc set to "xc". If the user knows the number of the centered x coordinate field the generic field name "f#", e.g. "f1" can be used.

fiyc = "yc": The name of the catalog field containing the centered y coordinate of an object. Most users should leave fiyc set to "yc". If the user knows the number of the centered y coordinate field the generic field name "f#", e.g. "f2" can be used.

foxformat = "%10.3f": The format of fixp and fixc.

foyformat = "%10.3f": The format of fiyp and fiyc.

Description

The catalog / file filtering parameters are used to filter the results of a catalog query before writing the results to disk. Catalog / file filtering options include: sorting on a field or field expression, selecting and rejecting records by evaluating a boolean expression for each record, selecting a subset of the fields for output, transforming the coordinates from the catalog / file celestial coordinate system to a user specified celestial coordinate system, and computing new fields from existing fields.

fsort and freverse define the sort field or field expression and the sort order. Sort fields may be field names or field numbers, e.g. "mag1" or "f3". By default the sort order is ascending.

Records are selected or rejected based on the value of the boolean expression fexpr. By default all catalog / file records are selected. The boolean selection expression must be function of existing catalog fields, e.g. the expression "mag1 <= 16.0" will select all records for which the mag1 field is <= 16.0, and the expression "(f4 - f3) >= 0.0 && (f4 - f3) <= 1.0" will select all records for which the difference between fields 4 and 3 is >= 0.0 but <= 1.0.

The fields parameter defines the list output fields and field expressions. By default all the input fields are output. By setting fields appropriately the user can select a subset of the input fields for output, rearrange the order of the input fields, and compute new fields. For example setting fields to "f[2-5]" selects fields 2 to 5 for output; setting fields to "f[2-3],f5,f4" select fields 2 to 5 but reverses the order of fields 4 and 5; setting fields to "f[2-5],f5-f4" selects fields 2 to 5 and adds a new field which is the difference between fields 5 and 4.

By default new fields are assigned names of the form "f#" where # is the field number, a data type of real, units of INDEF, and formats of %10s, %10d, or %10g if they are character, integer, or real respectively. Users can define names, data types, units, and formats for the new fields by setting the fnames, fntypes, fnunits, and fnformats parameters.

The coordinate system, units, or format of the output coordinates may be changed by setting one or more of the fosystem, foraunits, fodecunits, foraformat, fodecformat. By default the filtering code expects the input coordinates to be located in fields called "ra" and "dec". If these fields do not have valid names then generic field names of the form "f#" can be substituted.

The names and format of any newly computed pixel coordinate fields may be specified by setting one or more of the fixp, fiyp, fixc, fiyc, foxformat, or foyformat parameters. By default the filtering code expects the pixel coordinates to be located in fields called "xp", "yp", "xc", and "yc". If these fields do not have standard names then generic field names of the form "f#" can be substituted.

Expressions

The output records are selected on the basis of the input boolean expression fexpr whose variables are the field names specified in the configuration file or the generic equivalents f#. If after substituting the values associated with a particular record into the field name variables the expression evaluates to yes, that record is included in the output catalog. Numeric expressions can also be used to define the sort expression fsort or to define new fields in fields.

The supported operators and functions are briefly described below. A detailed description of the boolean expression evaluator and its syntax can be found in the manual page for the images package hedit task.

The following logical operators can be used in the boolean expression.

equal             ==    not equal               !=
less than         <     less than or equal      <=
greater than      >     greater than or equal   >=
or                ||    and                     &&
negation          !     pattern match           ?=
concatenation     //

The pattern match character ?= takes a string expression as its first argument and a pattern as its second argument. The result is yes if the pattern is contained in the string expression. Patterns are strings which may contain pattern matching meta-characters. The meta-characters themselves can be matched by preceding them with the escape character. The meta-characters listed below.

beginning of string     ^       end of string           $
one character           ?       zero or more characters *
white space             #       escape character        \
ignore case             {       end ignore case         }
begin character class   [       end character class     ]
not, in char class      ^       range, in char class    -

The expression may also include arithmetic operators and functions. The following arithmetic operators and functions are supported.

addition                +               subtraction             -
multiplication          *               division                /
negation                -               exponentiation          **
absolute value          abs(x)          cosine                  cos(x)
sine                    sin(x)          tangent                 tan(x)
arc cosine              acos(x)         arc sine                asin(x)
arc tangent             atan(x)         arc tangent             atan2(x,y)
exponential             exp(x)          square root             sqrt(x)
natural log             log(x)          common log              log10(x)
minimum                 min(x,y)        maximum                 max(x,y)
convert to integer      int(x)          convert to real         real(x)
nearest integer         nint(x)         modulo                  mod(x)

Formats

A format specification has the form "%w.dCn", where w is the field width, d is the number of decimal places or the number of digits of precision, C is the format code, and n is radix character for format code "r" only. The w and d fields are optional. The format codes C are as follows:

b       boolean (YES or NO)
c       single character (c or '\c' or '\0nnn')
d       decimal integer
e       exponential format (D specifies the precision)
f       fixed format (D specifies the number of decimal places)
g       general format (D specifies the precision)
h       hms format (hh:mm:ss.ss, D = no. decimal places)
m       minutes, seconds (or hours, minutes) (mm:ss.ss)
o       octal integer
rN      convert integer in any radix N
s       string (D field specifies max chars to print)
t       advance To column given as field W
u       unsigned decimal integer
w       output the number of spaces given by field W
x       hexadecimal integer
z       complex format (r,r) (D = precision)

Conventions for w (field width) specification:

    W =  n      right justify in field of N characters, blank fill
        -n      left justify in field of N characters, blank fill
        0n      zero fill at left (only if right justified)
absent, 0       use as much space as needed (D field sets precision)

Escape sequences (e.g. "\n" for newline):

\b      backspace   (not implemented)
     formfeed
\n      newline (crlf)
\r      carriage return
\t      tab
\"      string delimiter character
\'      character constant delimiter character
\\      backslash character
\nnn    octal value of character

Examples

%s          format a string using as much space as required
%-10s       left justify a string in a field of 10 characters
%-10.10s    left justify and truncate a string in a field of 10 characters
%10s        right justify a string in a field of 10 characters
%10.10s     right justify and truncate a string in a field of 10 characters

%7.3f       print a real number right justified in floating point format
%-7.3f      same as above but left justified
%15.7e      print a real number right justified in exponential format
%-15.7e     same as above but left justified
%12.5g      print a real number right justified in general format
%-12.5g     same as above but left justified

%h          format as nn:nn:nn.n
%15h        right justify nn:nn:nn.n in field of 15 characters
%-15h       left justify nn:nn:nn.n in a field of 15 characters
%12.2h      right justify nn:nn:nn.nn
%-12.2h     left justify nn:nn:nn.nn

%H          / by 15 and format as nn:nn:nn.n
%15H        / by 15 and right justify nn:nn:nn.n in field of 15 characters
%-15H       / by 15 and left justify nn:nn:nn.n in field of 15 characters
%12.2H      / by 15 and right justify nn:nn:nn.nn
%-12.2H     / by 15 and left justify nn:nn:nn.nn

\n          insert a newline

Examples

1. List the catalog / file filtering parameters.

cl> lpar afiltpars

2. Edit the catalog / file filtering parameters.

cl> afiltpars

3. Edit the catalog filtering parameters from the agetcat task.

cl> epar agetcat

4. Save the current afiltpars parameter values in a text file called afilt1.par. Use the saved parameter set in the next call to the agetcat task.

cl> epar afiltpars
cl> agetcat ... afiltpars=afilt1.par ...