AIPS HELP file for TABED in 31DEC24
As of Fri Apr 26 3:23:28 2024
TABED: Task to edit tables
INPUTS
INNAME Input image name (name)
INCLASS Input image name (class)
INSEQ 0.0 9999.0 Input image name (seq. #)
INDISK 0.0 9.0 Input image disk unit #
INEXT Input table extension type
INVERS Input table file version no.
OUTNAME Output image name (name)
NB: default output = input!
OUTCLASS Output image name (class)
OUTSEQ -1.0 9999.0 Output image name (seq. #)
OUTDISK 0.0 9.0 Output image disk unit #.
OUTVERS Output table file version.
Must be equal to INVERS for
header functions(OPTYPE=KEY)
SEE HELP - not standard
BCOUNT 0.0 99999.0 Beginning row to copy
ECOUNT 0.0 99999.0 Last row to copy: 0 => end
OPTYPE Type of operation:
'COPY','ADD ','MULT','DIV ',
'REPL','CLIP','DELE','UFLG'
'KEY ' -> (header keyword)
APARM Column selection parameters:
1: Col. number.
2: Low subscript
3: High subscript
4: Keyword data type (1-6)
5: test col., 6: test value
7: test tolerance,
8: subscript, 9: no. char.
10. > 0 -> copy only selected
KEYWORD Name of table keyword.
KEYVALUE Value given to numeric parm.
CLIP value range
KEYSTRNG Value given to a character-
valued parameter.
TIMERANG Time range to use.
HELP SECTION
TABED
Task: TABED edits AIPS extension files in table format (i.e. not
history, plot, or slice files). Use PRTAB to determine the
relevant column numbers for specifying data. If the output
table is not the input table, the data selected will be
appended to the end of the output table.
NOTE: TABPUT (and TABGET) are simpler AIPS verbs that allow you
to put (or get) single table values. TABED is really meant for
rather more complex operations.
Adverbs:
INNAME.....Input image name (name). Standard defaults.
INCLASS....Input image name (class). Standard defaults.
INSEQ......Input image name (seq. #). 0 => highest.
INDISK.....Disk drive # of input image. 0 => any.
INEXT......Extension table type (e.g. 'CC') no defaults.
INVERS.....Version number of table to modify, 0=>highest.
-1 => loop over all tables of type INEXT.
OUTNAME....Output image name (name). ' ' = actual INNAME.
OUTCLASS...Output image name (class). ' ' = actual INCLASS
OUTSEQ.....Output image name (seq. #). 0 = actual INSEQ
OUTDISK....Disk drive # of output image. = = actual INDISK
The output image file or uv data set must exist before
running TABED.
OUTVERS....Output version number. 0 -> input number (INVERS) when
output file same as input file except COPY. If COPY
or output file not same as input, 0 -> new.
-1 => output number = input number.
Must be equal to INVERS for header functions
(OPTYPE=KEY).
BCOUNT.....Beginning row number to be included .
ECOUNT.....Last row number included. 0 = highest.
OPTYPE.....The operation type:
'COPY' = Copy selected data with no modification,
(APARM(10) > 0 to omit anything)
'ADD ' = Add KEYVALUE to table entries,
'MULT' = Multiply table entries by KEYVALUE,
'DIV ' = Divide table entries by KEYVALUE,
'REPL' = replace table entries by KEYVALUE or
KEYSTRING,
'CLIP' = flag rows for table entries out of range:
if KEYV(1)<KEYV(2), data < KEYV(1) and
data > KEYV(2) are out of range
else KEYV(2) <= data <= KEYV(1) are out of range
'DELE' = flag selected rows
'UFLG' = un-flag selected rows (must be previously
flagged)
'KEY ' = Replace/add KEYWORD in table header.
Note: the output file is ignored for
OPTYPE='KEY'. OUTVERS has to equal INVERS.
APARM......Column selection parameters:
1 = The logical column number for the column to be
modified. Use PRTAB to determine.
2 = Lowest subscript in array. A table entry can
be an array so this points to first value in
this array to modify. For character strings
this is the first character. 0=>1
3 = Highest subscript in the array. 0=>all.
4 = Data type for keyword operations:
1 = double precision
2 = single precision (now only 1 used)
3 = character (up to 8 char)
4 = long integer
5 = logical (KEYSTRNG='.TRUE' or '.FALSE.'
6 = short integer (now only 4 used)
The specified operation can be conditioned on the
result of a test comparision of a specified value
with a specified table entry. If this test is
specified the operation is only performed if the
specified table entry agrees with a specified
value to within a specified tolerance. This test
if specified if APARM(5) > 0.
APARM(5) = test column,
APARM(6) = test value,
APARM(7) = test tolerance,
APARM(8) = test column subscript,
APARM(9) = number of characters to compare
(used for character data only).
If the test column contains a character string
then the APARM(9) characters beginning with
APARM(8) are compared aginst the value in
KEYWORD. Recognized wildcards are:
'*' => any number of arbitrary characters,
'?' => as single arbitrary character.
Default APARM(8)=1, APARM(9)=8 (max=8).
10 > 0 -> copy only selected rows (BCOUNT, ECOUNT,
APARM(5-9), flagging)
<= 0 -> copy all rows, changing selected ones as
needed.
APARM(10) is forced to 0 for DELE and UFLG OPTYPEs.
KEYWORD.....The keyword name for table keyword operations or
the test character string for a conditional
operation on a table entry.
KEYVALUE....The value to be given to a numeric parameter.
If the data type is single precision use:
KEYVALUE(1)
If the data type is double precision use:
KEYVALUE(1) + KEYVALUE(2)
(except KEYV(1) when KEYV(1)=KEYV(2))
If the data type is integer use:
ROUND (KEYVALUE(1))
KEYSTRNG....The value to be given to a character parameter.
For logical variables use '.TRUE.' and '.FALSE.'
No default.
TIMERANG...Time range of the data to be used. In order:
Start day, hour, min. sec,
end day, hour, min. sec. Days relative to ref.
date. Only used if table has a column labeled
'TIME'.
EXPLAIN SECTION
TABED: Task to modify and/or copy portions of a table.
Documentor: W. D. Cotton
Related Programs: PRTAB, CLCOR, TACOP, TAFLG
This task allows the modification of entries in AIPS tables,
either in place or copying the results to another table. Either
header Keyword-Value pairs or "row" data may be modified. In
addition, an operation on row data may be conditioned on the result of
a test on a value or character string in each the row.
OUTPUT TABLE:
TABED may work either in place, in which case the input table is
modified, or writing the modified table entry to a second file. Note:
Keyword-Value operations are always done in place but if the output of
a table row operation is to a previously nonexistant table all of the
keywords from the input table are copied.
The output table is specified by OUTNAME, OUTCLASS, OUTSEQ,
OUTDISK and OUTVER. If these are not specified then the default
output file is the input file. If the output table is not the same as
the input table then the new entries are appended to the end of the
table.
KEYWORD OPERATIONS:
There are two types of operations, modifying a Keyword-Value pair
and everything else. The desired operation is specified by the ADVERB
OPTYPE. A description of the Keyword operation follows:
OPTYPE = 'KEY'
This operation is to modify the value associated with a Keyword in
the table header if it exists or add the Keyword-Value pair if the
Keyword is currently not in the header. This operation is always
inplace and the output file is the input file. The current Keywords
and their values may be determined using PRTAB.
The Keyword to be modified or added is given in the adverb
KEYWORD; the value to be associated with the Keyword is given by
KEYVALUE if it is numeric, or KEYSTRNG if a character string or
logical value. The keyword type for a Keyword to be added is given by
APARM(4) using the following codes:
1 = double precision (sum of KEYVALUE(1 and 2) except if
they are equal),
2 = single precision (now does same as type 1)
3 = character (up to 8 char from KEYSTRNG),
4 = long integer (INTEGER (KEYVALUE(1))),
5 = logical (KEYSTRNG='.TRUE' or '.FALSE.'
6 = short integer (now does same as type 4)
"ROW" OPERATIONS:
The table consists of a number of rows containing a number of
columns. All operations involve an entire row (logical record) in the
table. Each column in a row has an associated value which is either a
scalar or a 1-dimensional array. Each row in the table has the same
structure. Each column has an associated data type, the defined row
data types and the way values are passed to TABED are the following:
double precision: KEYVALUE(1)+KEYVALUE(2) if they are not equal
single precision: KEYVALUE(1)
character: up to 16 characters from KEYSTRNG
long integer: INTEGER (KEYVALUE(1))
logical: true or false as given by KEYSTRNG '.TRUE.' or
'.FALSE.'
short integer: INTEGER (KEYVALUE(1))
bit: Like logical but 1=true, 0=false.
A single column may be operated on at a time; this column is
specified by APARM(1); the data type of this column in contained in
the header and does not need to be specified although the value given
in KEYVALUE or KEYSTRNG must correspond to the column type. The
logical column numbers may be determined from a PRTAB listing, the
column numbers are given above the column label at the top of the
listing.
One value is passed to TABED but if the table entry to be
modified is an array then a number of contigious elements in the array
may have the same operation performed. The first array subscript is
given by APARM(2) and the highest by APARM(3).
All OPTYPEs work only on unflagged table rows except UFLG which works
only on flagged rows.
OPTYPE='COPY'
This OPTYPE specifies that the selected logical table entries
(entire rows) be copied from one table to another. No values are
modified.
OPTYPE='ADD'
This OPTYPE specifies that the value given in KEYVALUE be added
to the specified column entry(s) in the table. This operation is not
defined for character, logical or bit data.
OPTYPE='MULT'
This OPTYPE specifies that the new table value(s) is(are) the old
value(s) multiplied by the value specified in KEYVALUE. This
operation is not defined for character, logical or bit data.
OPTYPE='DIV '
This OPTYPE specifies that the new table value(s) is(are) the old
value(s) divided by the value specified in KEYVALUE. This operation
is not defined for character, logical or bit data.
OPTYPE='REPL'
This OPTYPE indicates that the current values of the specified
table entries are to be replaced with the value given in KEYVALUE or
KEYSTRNG. This operation is defined for all data types.
OPTYPE='CLIP'
This OPTYPE compares the existing table value(s) with KEYVALUE
and write the output row as "flagged" if the data are out of range.
If KEYV(1) < KEYV(2) then data are out of range if data < KEYV(1) or
data > KEYV(2). Otherwise data are out of range if KEYV(2) <= data <=
KEYV(1). This OPTYPE makes most sense when the output table is the
input table.
OPTYPE='DELE'
This OPTYPE writes each selected row as "flagged". It really
only makes sense when the output table is the input table.
OPTYPE='UFLG'
This OPTYPE writes each selected (previously flagged) row as
"good".
SPECIFYING THE ROWS:
The rows to be operated on may be specified unconditionally by
BCOUNT and ECOUNT, the first and last row numbers to be considered,
and/or conditionally by TIMERANG and/or APARM(5-9). If a column
title is 'TIME' then the range of values in this column for rows to be
considered further can be limited to the range given in TIMERANG.
This will work properly if the units of the TIME column are days; the
units may be determined from a PRTAB listing.
Rows passing any BCOUNT-ECOUNT or TIMERANG test may be further
selected by the result of a test on an arbitrary column. This column
is specified by APARM(5); a positive value of APARM(5) indicates that
such a test is to be performed. The array index of the column entry
to be tested is given in APARM(8).
For numeric columns the test is passed if the tabulated value
agrees with the test value APARM(6) to within a tolerance given by
APARM(7). If the test is passed the requested operation is performed.
For columns containing character data, the test string is passed
in adverb KEYWORD which is limited to 8 characters. The first
character in the tabulated string to be tested is given by APARM(8)
and the number of characters to be tested is given in APARM(9). Two
wildcard characters are recognized; '*' means any number of arbitrary
characters, '?' means a single arbitrary character.
***************************************************
Note: APARM(10) controls whether only selected rows are copied to
a new table (> 0) or all rows are copied with modifications to
selected ones (<= 0).
***************************************************
EXAMPLES:
The following examples show how to set that adverb values for
several different types of table editing operations.
The first example is to change the value of the logical Keyword
APPLIED in SN table 1 to false.
OUTNAME='ABC'; OUTCLASS='UVDATA'; OUTSEQ=1; OUTDISK=1
OUTVER=1; INEXT='SN'
OPTYPE='KEY'; APARM=0 0 0 5
KEYWORD='APPLIED'; KEYSTRNG='.FALSE.'
The next example is to multiply the fluxes of the first 25 CLEAN
components from one CC file by 1.273 and write the results to another.
The flux density is given in column 1. Note: the output table need
not exist prior to this operation.
INNAME='3CXYZ'; INCLASS='ICL001'; INDISK=2; INSEQ=1
INVER=1; INEXT='CC'
OUTNAME='ABC'; OUTCLASS='ICL001'; OUTDISK=3; INSEQ=1
OUTVER=1
OPTYPE='MULT'; APARM=1 1 1; KEYVALUE=1.273 0
BCOUNT=1; ECOUNT=25
The next example is to set the group delay for antenna 3, first
polarization (RCP), and IFs 1 and 2 to 0.0 for the time range
1/2:30:00 1/2:55:00 in an SN table. The antenna number is in column 4
and the delays for the first polarization "DELAY 1" are in column 12.
INNAME='3CXYZ'; INCLASS='MULTI'; INDISK=1; INSEQ=1;
INEXT='SN'; INVER=1
CLRO
OPTYPE='REPL'
APARM=12 1 2 0 4 3 0.3 1 0
KEYVALUE=0.0
BCOUNT=1; ECOUNT=0
TIMERANG= 1 2 30 0 1 2 55 0
The last example is to change the PFLAGS (Stokes correlator
flags) in an FG table to 1111 (all correlators i.e. RR, LL, RL, LR in
order, are flagged) if the REASON is 'TVFLG 28-AUG-87 13:34:28'. The
PFLAGS column is 8 and the REASON column is 9. The last 8 characters
of the REASON string are checked due to an ambiguity in the first 16
(i.e. TVFLG was run several times that day.)
INNAME='3CXYZ'; INCLASS='MULTI'; INDISK=1; INSEQ=1;
INEXT='FG'; INVER=1
CLRO
OPTYPE='REPL'
APARM=8 1 4 0 9 0 0 17 8
KEYWORD='13:34:28'; KEYSTRNG='.TRUE.'
BCOUNT=1; ECOUNT=0