From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- pkg/utilities/nttools/doc/tcreate.hlp | 378 ++++++++++++++++++++++++++++++++++ 1 file changed, 378 insertions(+) create mode 100644 pkg/utilities/nttools/doc/tcreate.hlp (limited to 'pkg/utilities/nttools/doc/tcreate.hlp') diff --git a/pkg/utilities/nttools/doc/tcreate.hlp b/pkg/utilities/nttools/doc/tcreate.hlp new file mode 100644 index 00000000..0d12d277 --- /dev/null +++ b/pkg/utilities/nttools/doc/tcreate.hlp @@ -0,0 +1,378 @@ +.help tcreate Dec2003 tables +.nj +.ih +NAME +tcreate -- Create a table from ASCII files describing a table format. +.ih +USAGE +tcreate table cdfile datafile +.ih +DESCRIPTION +This task reads an ASCII file containing column descriptions for a new table. +The columns are defined and the table created; +data are read in from a file specified by +the 'datafile' parameter +(a specified number of lines may be skipped when reading in data). +There may be several lines of data per table row. +Blanks and tabs are skipped. +Blank lines and lines beginning with # are ignored. +In-line comments using # are permitted. +The lines in the input files may be up to 8195 characters long, +plus one character for the carriage return. +The input 'datafile' is read free-format. + +Undefined values require a place holder in the data file. +The word INDEF should be used as the place holder +for undefined (indefinite) numerical values, +the word "no" for boolean values, +and a pair of adjacent quotes ("") for undefined character strings. +If a value for a character string contains one or more blanks, +or the comment character (#), +then the entire value must be enclosed in quotes, e.g., "R CrB". + +This task can also read a file containing header parameters for the table. + +If a problem occurs when reading a particular data field, +the execution continues, and the table entry is marked as undefined. +.ih +PARAMETERS +.ls table [file name] +Output file name for the table created by this task. + +Note that, if 'table' is an existing FITS file, +the table that is created will be appended +as a new extension to the end of the file. +.le +.ls cdfile = STDIN [file name] +The name of the column definition file. + +The column definition file contains one line for each column to be created. +Each line contains up to four values giving attributes of the particular column. +Every line must have a column name; optionally, it may have a data type, +display format, and units. (Embedded blanks in any of these +attributes must be enclosed in quotes.) Adjacent quotes are used as +place holders and let you skip an attribute while defining the next one. +Column names and data types are NOT case sensitive. +Neither the format nor data type may contain embedded blanks. +Display formats may be of the type used by Fortran or those used by SPP. +If the format is not defined, a default format will be used. +The format is not used for internal representation of the data and +is ignored when reading data---it is used only for display purposes, +for example, by tasks such as 'tedit', 'tread', and 'tprint'. +Type "help ttools opt=sysdoc" for detailed information about print formats. +Comment lines may be included in this file +by beginning the line with the comment symbol (#). + +The following data types are recognized by this parameter +(the default data type is single-precision real): +.nf + + r - Single-precision real. + d - Double-precision real. + i - Integer. + s - Short integer. + b - Boolean. + ch*n - Character string of maximum length n. +.fi + +A column of arrays can be created by giving the array length +in square brackets appended to the data type. +For example, a data type of r[400] would mean that the column +contains an array of 400 single-precision real numbers in each row. +r[20,5,4] would also mean an array of 400 reals, +but in this case a TDIMi keyword will be written (for column number i) +that gives the numbers 20, 5 and 4, +indicating that the array should be regarded as 3-D, +with 20 elements along the most rapidly varying axis +and four elements along the least rapidly varying axis. +Up to seven dimensions may be specified, separated by commas. +For both of these cases, the data file must contain 400 values +for that column for each row; +the values need not all be on the same line of the data file. +Text tables and column-ordered stsdas tables +cannot contain arrays; see 'tbltype'. + +If you have an existing table +with columns similar to those +in the table you would like to create, +you can use the 'tlcol' task to generate a file +which can be edited and used as the input 'cdfile' for 'tcreate'. +That is, the output of 'tlcol' is exactly the format +that is expected for 'tcreate.cdfile'. +The syntax is also the same as +for column definitions in text tables, +except for the leading "#c " in text tables. + +If cdfile = "STDIN" and the input is not redirected, +the task prints a prompt asking for input. +Press Control-Z (or Control-D, i.e. your EOF character) +to terminate the list of column definitions; +note that the Control-Z must NOT occur on the same line as the last +column definition. +.le +.ls datafile = "STDIN" [file name] +The name of the input ASCII data file. + +The values in the file must be in the order of the columns +as given in the column-definitions file 'cdfile'. +Undefined values should have INDEF or "" as place holders +for numerical or character values, respectively. +Each row for the table must begin with a new line in 'datafile', +but there can be multiple lines in 'datafile' for each table row +(see also 'nlines'). + +If all data for a table row have been read from an input line +but there are additional data on the line, +or if there is a data type mismatch, +the following warning will be +printed: "out of synch or extra data in line ". + +Lines in the input data file are limited to 8196 characters, +including the newline at the end of each line. +If a longer line is encountered, the task will stop with an error. + +As with 'cdfile', +if datafile = "STDIN" and the input is not redirected, +the task prints a prompt asking for input. +Enter a carriage return before ending the last line +and then press Control-Z (or Control-D, i.e. EOF) to close the file. +.le +.ls (uparfile) [file name] +The name of the input ASCII file of header parameters. +This file is optional. + +Each line of this file defines one header parameter, +except that blank lines and lines beginning with # will be ignored. +Each line should contain three parts: keyword, datatype, and value; +an optional comment may be added following the value. +The keyword is a string (no embedded blanks) of up to eight characters. +The datatype is a single letter (t, b, i, r, or d) that indicates the type. +The value is limited to 70 characters. +If the type is text (t) it may contain more than one word, +but in that case it must be enclosed in quotes; +otherwise, the portion of the value following the first word +will be interpreted as a comment. + +Note that the syntax is not the same as +for header keywords in text tables. +The latter uses the much more reasonable "#k keyword = value comment". +The datatype shouldn't need to be specified, +since keywords are stored in the table as text strings anyway; +the current syntax has been retained for backward compatibility. + +It is possible, though not recommended, to set uparfile = "STDIN". +The problem is that it is read twice, +once just to count the number of entries, and once to read the values, +so you would have to type in the values twice. +.le +.ls (nskip = 0) [integer, min=0, max=INDEF] +Number of lines to skip at the beginning of the data file. + +The 'tcreate' task will also skip blank lines and lines beginning with #; +it will therefore not usually be necessary to specify 'nskip', +as header lines may be commented out by inserting a leading #. +Note that if 'nskip > 0' then exactly 'nskip' lines will be skipped, +even if some of them are blank or comment lines. +.le +.ls (nlines = 0) [integer, min=0, max=INDEF] +The number of lines in the input data file +corresponding to one row in the output table. +If 'nlines = 0' (the default) then lines will +be read from the data file until every column in the row is filled. +If 'nlines > 0' then exactly this many lines will be read for each row; +if for some rows the input data are compressed into fewer than this +many lines, extra dummy lines must be included following the good data. +Note that comment lines and blank lines are not counted. +.le +.ls (nrows = 0) [integer, min=0, max=INDEF] +The number of rows to write into the table. + +If this value is zero, then the entire input data file will be read. +If this value is greater than zero then +no more than 'nrows' will be written to the table, +even if the data file contains enough data to fill more than +'nrows' rows of data. +For a column-ordered table (see the 'tbltype' parameter), +'nrows' is the number of rows that will be allocated, +and the actual number in the data file may be smaller. +.le +.ls (hist = yes) [boolean] +Add a history record containing a creation date? + +If 'hist = yes', a header parameter will be written to the table with the +keyword 'HISTORY' that gives the date and time that 'tcreate' was run. +This parameter is added after those that were read from the 'uparfile', if any. +.le +.ls (extrapar = 5) [integer, min=0, max=INDEF] +Extra space to be reserved for header-parameter records. +This is the number of records for header parameters that will be allocated, +in addition to the number needed to hold the parameters +specified in the 'uparfile' parameter file. +The default is five, +which means that after the table is created +up to five more parameters may be added +(e.g., by using the 'tupar' task) +without the table being rewritten to reallocate space. +.le +.ls (tbltype = "default") [string, allowed values: default | row | +column | text] +Type of table to create. +The default is row-ordered stsdas format. +To create a FITS table, +use tbltype = "default" +and specify a table name ('table') +with filename extension ".fits", ".fit", or ".??f" +('?' is any single character). +.le +.ls (extracol = 0) [integer, min=0, max=INDEF] +Extra space to be reserved for columns in the output table. +This parameter is relevant only for a row-ordered stsdas format table. + +This is in addition to the number required to contain those columns +described by 'cdfile'. +One unit of space is taken by each +single-precision, integer, or boolean column. +A double-precision column requires two units of allocated space, +and a character-string column takes one unit of space for each four +characters, or fraction thereof. +.le +.ih +EXAMPLES +1. Wait for the user to type in column definitions and data, +each of which will be terminated by a Control-Z (or Control-D, i.e. EOF). +The prompts are printed by the 'tcreate' task; +these are the lines beginning with "Give column definitions" +and "Give table data". +The table will have 4 columns and 2 rows. +.nf + +tt> tcreate test STDIN STDIN + +Give column definitions (name, datatype, print format, units) + ... then newline & EOF to finish. +name ch*12 +ra d h12.1 hours +dec d h12.0 degrees +mag r f8.2 +^Z + +Give table data ... then newline & EOF to finish. +nameless 3:18:47 42:24 INDEF +"SA0 123456" 19:00:06.3 -0:00:01 3.5 +^Z + +.fi +2. Create a table called "outfile.tab" using the columns specified +in "columns.cd" and the data in "data.dat". + +tt> tcreate outfile columns.cd data.dat nskip=3 + +"columns.cd" may contain just the following: +.sp +.nf +STARno I i5 +X r "F6.2" pixels +Y R F6.2 "pixels" +MAG R "" magnitude + SHARP R + ROUND r +STARNAME ch*15 +.fi + +Note the free format of, and embedded tabs in, the column definitions file +itself. The format for display of MAG is not specified, but the unit is +given as magnitude, so adjacent quotes are used to mark the position where +the display format is expected. + +The file "data.dat" may contain (if 'nskip=3', 'nlines=2'): +.sp +.nf +This is a header + header2 + header3 + 1 3.0 4.0 + 5.0 6.0 7.0 HD12345 + 2 10.0 11.0 12.0 13.0 +14.0 "HD 122" +3 20.0 21.0 22.0 23.0 24.0 "" +dummy line +.fi + +Note the tabbed and free format of the data file +and the specification of the character strings. +If the character data contain embedded blanks +then the whole string should be quoted, +otherwise this is not necessary. +The final entry is the null character string. + +3. The following column definitions: +.sp +.nf +STARno i i6 +X r f9.2 pixels +Y r f9.2 pixels +MAG r f9.3 +SHARP r f9.3 +ROUND r f9.3 +STARNAME ch*15 + +could be used with the following data file: + + 1 7.92 2.64 -3.075 0.436 0.019 XXXXXXXXXXXXXXX + 2 33.89 3.14 -1.162 0.419 0.223 + 3 3.68 5.07 -2.454 0.421 -0.123 HD12345 + 4 42.70 5.08 -1.285 0.445 0.195 HD 123 +.fi + +4. The aperture photometry file from the 'daophot' task +may have the following data: +.sp +.nf + 1 6.95 2.61 99.999 99.999 99.999 99.999 . . . + 464.618 9.71 0.52 9.999 9.999 9.999 9.999 . . . + 2 200.06 2.80 99.999 99.999 99.999 99.999 + 465.180 7.79 0.16 9.999 9.999 9.999 9.999 + 3 156.25 5.17 14.610 14.537 14.483 14.438 + 462.206 7.26 0.37 0.013 0.014 0.015 0.016 + + +and could have the following column-definition file: + +STARno i +X r +Y r +MAG1 r +MAG2 r +MAG3 r + . + . + . +MAG15 r +SKYMOD r +SKYSD r +.fi + +The following could be used as an input file to define header parameters. +.sp +.nf +comment t Created 1987 July 22 +NL i 2 +NX i 284 +NY i 492 +THRESH r 27.0 +AP1 r 3.0 +PH/ADU r 20.0 +RNOISE r 6.50 +BAD r 300.0 +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +Type "help ttools opt=sysdoc" for a higher-level description of the 'ttools' +package. +See also the files in "tables$doc/". +.endhelp -- cgit