diff options
Diffstat (limited to 'noao/astcat/doc/afiltpars.hlp')
| -rw-r--r-- | noao/astcat/doc/afiltpars.hlp | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/noao/astcat/doc/afiltpars.hlp b/noao/astcat/doc/afiltpars.hlp new file mode 100644 index 00000000..673f2185 --- /dev/null +++ b/noao/astcat/doc/afiltpars.hlp @@ -0,0 +1,357 @@ +.help afiltpars Mar00 astcat +.ih +NAME +afiltpars -- edit the catalog filtering parameters +.ih +USAGE +afiltpars +.ih +PARAMETERS +.ls 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. +.le +.ls freverse = no +Sort in descending order ? +.le +.ls 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". +.le +.ls 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". +.le +.ls 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. +.le +.ls 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". +.le +.ls 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. +.le +.ls fnformats = "" +The list of new field formats. By default string, integer, and floating +point fields are assigned formats of "%10s", "%10d", and "%10g" respectively. +.le +.ls 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". +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls foraformat = "" +The format of fira. If undefined foraformat defaults to the equivalent catalog +format. +.le +.ls fodecformat = "" +The format of fidec. If undefined fodecformat defaults to the equivalent +catalog format. +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls 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. +.le +.ls foxformat = "%10.3f" +The format of fixp and fixc. +.le +.ls foyformat = "%10.3f" +The format of fiyp and fiyc. +.le + +.ih +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. + +\fIfsort\fR and \fIfreverse\fR 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 +\fIfexpr\fR. 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 \fIfields\fR parameter defines the list output fields and field +expressions. By default all the +input fields are output. By setting \fIfields\fR 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 \fIfnames\fR, \fIfntypes\fR, \fIfnunits\fR, and \fIfnformats\fR +parameters. + +The coordinate system, units, or format of the output coordinates may +be changed by setting one or more of the \fIfosystem\fR, \fIforaunits\fR, +\fIfodecunits\fR, \fIforaformat\fR, \fIfodecformat\fR. 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 \fIfixp\fR, \fIfiyp\fR, +\fIfixc\fR, \fIfiyc\fR, \fIfoxformat\fR, or \fIfoyformat\fR 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. +.ih +EXPRESSIONS + +The output records are selected on the basis of the input boolean +expression \fIfexpr\fR 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 \fIfsort\fR or to define new fields in +\fIfields\fR. + +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. + +.nf + equal == not equal != + less than < less than or equal <= + greater than > greater than or equal >= + or || and && + negation ! pattern match ?= + concatenation // +.fi + +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. + +.nf + 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 - +.fi + +The expression may also include arithmetic operators and functions. +The following arithmetic operators and functions are supported. + +.nf +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) +.fi + +.ih +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: + +.nf +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 +.fi + +.ih +EXAMPLES +1. List the catalog / file filtering parameters. + +.nf +cl> lpar afiltpars +.fi + +2. Edit the catalog / file filtering parameters. + +.nf +cl> afiltpars +... edit the parameters in the usual way +... type :wq to quit and save the edits +.fi + +3. Edit the catalog filtering parameters from the agetcat task. + +.nf +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 +.fi + +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. + +.nf +cl> epar afiltpars +... edit some parameters in the usual way +... type :w afilt1.par +... type :q to quit +cl> agetcat ... afiltpars=afilt1.par ... +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +agetcat, afiltcat +.endhelp |