; TABED ;--------------------------------------------------------------- ;! Task to edit tables ;# TASK TABLE EDITING ;----------------------------------------------------------------------- ;; Copyright (C) 1995, 1999-2000, 2006-2008 ;; Associated Universities, Inc. Washington DC, USA. ;; ;; This program is free software; you can redistribute it and/or ;; modify it under the terms of the GNU General Public License as ;; published by the Free Software Foundation; either version 2 of ;; the License, or (at your option) any later version. ;; ;; This program is distributed in the hope that it will be useful, ;; but WITHOUT ANY WARRANTY; without even the implied warranty of ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ;; GNU General Public License for more details. ;; ;; You should have received a copy of the GNU General Public ;; License along with this program; if not, write to the Free ;; Software Foundation, Inc., 675 Massachusetts Ave, Cambridge, ;; MA 02139, USA. ;; ;; Correspondence concerning AIPS should be addressed as follows: ;; Internet email: aipsmail@nrao.edu. ;; Postal address: AIPS Project Office ;; National Radio Astronomy Observatory ;; 520 Edgemont Road ;; Charlottesville, VA 22903-2475 USA ;----------------------------------------------------------------------- TABED LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC TABED Task to edit tables 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) 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. 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. ---------------------------------------------------------------- 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. 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. See above -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, '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) 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). 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'. ---------------------------------------------------------------- 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 inplace 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 inplace 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. 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