| afiltpars | astcat | afiltpars |
afiltpars -- edit the catalog filtering parameters
afiltpars
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 fileds 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 amy 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.
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 metacharacters. The metacharacters themselves can be matched by preceding them with the escape character. The metacharacters 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)
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)
\f 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
1. List the catalog / file filtering parameters.
cl> lpar afiltpars
2. Edit the catalog / file filtering parameters.
cl> afiltpars ... edit the parameters in the usual way ... type :wq to quit and save the edits
3. Edit the catalog filtering parameters from the agetcat task.
cl> epar agetcat ... edit the agetcat parameters ... move to the afiltpars parameter line and type :e ... edit the afiltpars parameters ... type :wq to quit and save the afiltpars edits ... continue editing the remaining agetcat parameters ... type :go to execute the task
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 ... edit some parameters in the usual way ... type :w afilt1.par ... type :q to quit cl> agetcat ... afiltpars=afilt1.par ...