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/axispar.hlp | 138 ++++++++++ pkg/utilities/nttools/doc/dvpar.hlp | 68 +++++ pkg/utilities/nttools/doc/gtedit.hlp | 116 ++++++++ pkg/utilities/nttools/doc/gtpar.hlp | 117 ++++++++ pkg/utilities/nttools/doc/imtab.hlp | 169 ++++++++++++ pkg/utilities/nttools/doc/keypar.hlp | 83 ++++++ pkg/utilities/nttools/doc/keyselect.hlp | 246 +++++++++++++++++ pkg/utilities/nttools/doc/keytab.hlp | 61 +++++ pkg/utilities/nttools/doc/parkey.hlp | 73 +++++ pkg/utilities/nttools/doc/partab.hlp | 62 +++++ pkg/utilities/nttools/doc/pltpar.hlp | 160 +++++++++++ pkg/utilities/nttools/doc/tabim.hlp | 98 +++++++ pkg/utilities/nttools/doc/tabkey.hlp | 68 +++++ pkg/utilities/nttools/doc/tabpar.hlp | 95 +++++++ pkg/utilities/nttools/doc/taextract.hlp | 109 ++++++++ pkg/utilities/nttools/doc/tainsert.hlp | 132 ++++++++++ pkg/utilities/nttools/doc/tcalc.hlp | 153 +++++++++++ pkg/utilities/nttools/doc/tchcol.hlp | 80 ++++++ pkg/utilities/nttools/doc/tcheck.hlp | 137 ++++++++++ pkg/utilities/nttools/doc/tchsize.hlp | 158 +++++++++++ pkg/utilities/nttools/doc/tcopy.hlp | 113 ++++++++ pkg/utilities/nttools/doc/tcreate.hlp | 378 ++++++++++++++++++++++++++ pkg/utilities/nttools/doc/tdelete.hlp | 74 ++++++ pkg/utilities/nttools/doc/tdiffer.hlp | 65 +++++ pkg/utilities/nttools/doc/tdump.hlp | 150 +++++++++++ pkg/utilities/nttools/doc/tedit.hlp | 295 +++++++++++++++++++++ pkg/utilities/nttools/doc/texpand.hlp | 159 +++++++++++ pkg/utilities/nttools/doc/thedit.hlp | 208 +++++++++++++++ pkg/utilities/nttools/doc/thistogram.hlp | 152 +++++++++++ pkg/utilities/nttools/doc/thselect.hlp | 90 +++++++ pkg/utilities/nttools/doc/tinfo.hlp | 125 +++++++++ pkg/utilities/nttools/doc/tintegrate.hlp | 97 +++++++ pkg/utilities/nttools/doc/tjoin.hlp | 120 +++++++++ pkg/utilities/nttools/doc/tlcol.hlp | 75 ++++++ pkg/utilities/nttools/doc/tlinear.hlp | 127 +++++++++ pkg/utilities/nttools/doc/tmatch.hlp | 225 ++++++++++++++++ pkg/utilities/nttools/doc/tmerge.hlp | 231 ++++++++++++++++ pkg/utilities/nttools/doc/tprint.hlp | 276 +++++++++++++++++++ pkg/utilities/nttools/doc/tproduct.hlp | 48 ++++ pkg/utilities/nttools/doc/tproject.hlp | 79 ++++++ pkg/utilities/nttools/doc/tquery.hlp | 115 ++++++++ pkg/utilities/nttools/doc/tread.hlp | 159 +++++++++++ pkg/utilities/nttools/doc/trebin.hlp | 257 ++++++++++++++++++ pkg/utilities/nttools/doc/tselect.hlp | 147 +++++++++++ pkg/utilities/nttools/doc/tsort.hlp | 84 ++++++ pkg/utilities/nttools/doc/tstat.hlp | 225 ++++++++++++++++ pkg/utilities/nttools/doc/ttranspose.hlp | 139 ++++++++++ pkg/utilities/nttools/doc/tunits.hlp | 143 ++++++++++ pkg/utilities/nttools/doc/tupar.hlp | 365 +++++++++++++++++++++++++ pkg/utilities/nttools/doc/wcspars.hlp | 184 +++++++++++++ pkg/utilities/nttools/doc/wlpars.hlp | 440 +++++++++++++++++++++++++++++++ 51 files changed, 7668 insertions(+) create mode 100644 pkg/utilities/nttools/doc/axispar.hlp create mode 100644 pkg/utilities/nttools/doc/dvpar.hlp create mode 100644 pkg/utilities/nttools/doc/gtedit.hlp create mode 100644 pkg/utilities/nttools/doc/gtpar.hlp create mode 100644 pkg/utilities/nttools/doc/imtab.hlp create mode 100644 pkg/utilities/nttools/doc/keypar.hlp create mode 100644 pkg/utilities/nttools/doc/keyselect.hlp create mode 100644 pkg/utilities/nttools/doc/keytab.hlp create mode 100644 pkg/utilities/nttools/doc/parkey.hlp create mode 100644 pkg/utilities/nttools/doc/partab.hlp create mode 100644 pkg/utilities/nttools/doc/pltpar.hlp create mode 100644 pkg/utilities/nttools/doc/tabim.hlp create mode 100644 pkg/utilities/nttools/doc/tabkey.hlp create mode 100644 pkg/utilities/nttools/doc/tabpar.hlp create mode 100644 pkg/utilities/nttools/doc/taextract.hlp create mode 100644 pkg/utilities/nttools/doc/tainsert.hlp create mode 100644 pkg/utilities/nttools/doc/tcalc.hlp create mode 100644 pkg/utilities/nttools/doc/tchcol.hlp create mode 100644 pkg/utilities/nttools/doc/tcheck.hlp create mode 100644 pkg/utilities/nttools/doc/tchsize.hlp create mode 100644 pkg/utilities/nttools/doc/tcopy.hlp create mode 100644 pkg/utilities/nttools/doc/tcreate.hlp create mode 100644 pkg/utilities/nttools/doc/tdelete.hlp create mode 100644 pkg/utilities/nttools/doc/tdiffer.hlp create mode 100644 pkg/utilities/nttools/doc/tdump.hlp create mode 100644 pkg/utilities/nttools/doc/tedit.hlp create mode 100644 pkg/utilities/nttools/doc/texpand.hlp create mode 100644 pkg/utilities/nttools/doc/thedit.hlp create mode 100644 pkg/utilities/nttools/doc/thistogram.hlp create mode 100644 pkg/utilities/nttools/doc/thselect.hlp create mode 100644 pkg/utilities/nttools/doc/tinfo.hlp create mode 100644 pkg/utilities/nttools/doc/tintegrate.hlp create mode 100644 pkg/utilities/nttools/doc/tjoin.hlp create mode 100644 pkg/utilities/nttools/doc/tlcol.hlp create mode 100644 pkg/utilities/nttools/doc/tlinear.hlp create mode 100644 pkg/utilities/nttools/doc/tmatch.hlp create mode 100644 pkg/utilities/nttools/doc/tmerge.hlp create mode 100644 pkg/utilities/nttools/doc/tprint.hlp create mode 100644 pkg/utilities/nttools/doc/tproduct.hlp create mode 100644 pkg/utilities/nttools/doc/tproject.hlp create mode 100644 pkg/utilities/nttools/doc/tquery.hlp create mode 100644 pkg/utilities/nttools/doc/tread.hlp create mode 100644 pkg/utilities/nttools/doc/trebin.hlp create mode 100644 pkg/utilities/nttools/doc/tselect.hlp create mode 100644 pkg/utilities/nttools/doc/tsort.hlp create mode 100644 pkg/utilities/nttools/doc/tstat.hlp create mode 100644 pkg/utilities/nttools/doc/ttranspose.hlp create mode 100644 pkg/utilities/nttools/doc/tunits.hlp create mode 100644 pkg/utilities/nttools/doc/tupar.hlp create mode 100644 pkg/utilities/nttools/doc/wcspars.hlp create mode 100644 pkg/utilities/nttools/doc/wlpars.hlp (limited to 'pkg/utilities/nttools/doc') diff --git a/pkg/utilities/nttools/doc/axispar.hlp b/pkg/utilities/nttools/doc/axispar.hlp new file mode 100644 index 00000000..d2a8dcbc --- /dev/null +++ b/pkg/utilities/nttools/doc/axispar.hlp @@ -0,0 +1,138 @@ +.help axispar Jul93 tables +.ih +NAME +pltpar -- Edit the parameter set that describes axis attributes. +.ih +USAGE +pltpar +.ih +DESCRIPTION +The 'axispar' parameters specify the attributes of plot axes. + +Note that this is a pset, not an executable task; it defines a set of +parameters used by other tasks. Invoking the pset by name runs +'eparam' on the parameter set, allowing the user to modify the +parameters. Alternatively, the parameters may be modified on the +command line by specifying the pset name and parameter name, for +example, the user can type "pltpar.pointmode=yes" to set only the +'pointmode' parameter. Parameters can also be edited by using +'eparam' on the calling task (e.g., by typing "eparam sgraph"), in +which case, 'pltpar' will appear as one of the task parameters; the +'pltpar' parameters may then be edited by positioning the cursor on +the line containing the pset name and typing ":e". After editing +the pset parameters, type Control-Z (or ":q") +to return to the main task parameter menu. +.ih +PARAMETERS +.ls (wl = 0.) [real] +Left world X-coordinate if not autoscaling. +.le +.ls (wr = 0.) [real] +Right world X-coordinate if not autoscaling. +.le +.ls (wb = 0.) [real] +Lower world Y-coordinate if not autoscaling. +.le +.ls (wt = 0.) [real] +Upper world Y-coordinate if not autoscaling. +.le +.ls (xflip = no) [boolean] +Flip the autoscaled X axis? +.le +.ls (yflip = no) [boolean] +Flip the autoscaled Y axis? +.le +.ls (transpose = no) [boolean] +Transpose the X and Y axes of the plot? If 'transpose = no', the +horizontal axis will have the X values or pixel number. +.le +.ls (logx = no) [boolean] +Scale the X axis logarithmically? +.le +.ls (logy = no) [boolean] +Scale the Y axis logarithmically? +.le +.ls (rejectlog = yes) [boolean] +Replace invalid logarithmic values with 'INDEF'? Invalid values will +be ignored in scaling and plotting. +.le +.ls (box = yes) [boolean] +Draw the box containing the axes and labels around the edge of the +window? +.le +.ls (ticklabels = yes) [boolean] +Label major tick marks? +.le +.ls (grid = no) [boolean] +Draw grid lines on the plot? +.le +.ls (xlabel) [string] +X-axis label. +.le +.ls (ylabel) [string] +Y-axis label. +.le +.ls (title = imtitle) [string] +The plot title may consist of one or two lines of text. If the +parameter 'sysid' is set to "yes", then the first line of the title is +a standard system-supplied string containing the user's name, date, +etc. If the 'title' parameter contains the string "imtitle" (the +default), then the plot title will contain a line made up from the +input file, image, or table name. The user can supply an optional +string for the 'title' parameter--this string will replace the string +resulting from the "imtitle" specification. +.le +.ls (sysid = yes) [boolean] +Include standard system information in the plot title? If the 'sysid' +parameter is "yes", then a string including the user's name, date, host +name, etc. is included in the plot title. +.le +.ls (lintran = no) [boolean] +Perform a linear transformation of the X axis? +.le +.ls (p1 = 0.) [real] +Starting input pixel value if 'lintran = yes'. +.le +.ls (p2 = 0.) [real] +Ending input pixel value if 'lintran = yes'. +.le +.ls (q1 = 0.) [real] +Starting output pixel value if 'lintran = yes'. +.le +.ls (q2 = 1.) [real] +Ending output pixel value if 'lintran = yes'. +.le +.ls (majrx = 5) [integer] +Number of major divisions along the X grid. +.le +.ls (minrx = 5) [integer] +Number of minor divisions along the X grid. +.le +.ls (majry = 5) [integer] +Number of major divisions along the Y grid. +.le +.ls (minry = 5) [integer] +Number of minor divisions along the Y grid. +.le +.ls (round = no) [boolean] +Round axes to nice values? (Values at tick marks will be significant, +based on scale of the data.) +.le +.ls (margin = INDEF) [real, min = 0, max = 1] +The margin between the viewport edges (plot axes) and the limits of the +plotted curve(s) as a fraction of the viewport (NDC). If 'margin = +INDEF', the default, a 2.5% margin will apply. That is, the plotted +curve(s) will be inset .025 times the size of the viewport. Set +'margin = 0' to plot curves to the axes. +.le +.ls (version = 17August92) [string] +Date the task was installed. This should not be changed by the user. +.le +.ih +EXAMPLES +.ih +BUGS +.ih +SEE ALSO +sgraph, pltpar, dvpar +.endhelp diff --git a/pkg/utilities/nttools/doc/dvpar.hlp b/pkg/utilities/nttools/doc/dvpar.hlp new file mode 100644 index 00000000..94bb4971 --- /dev/null +++ b/pkg/utilities/nttools/doc/dvpar.hlp @@ -0,0 +1,68 @@ +.help dvpar Jul93 tables +.ih +NAME +dvpar -- Edit the parameter set that describes the graphics device. +.ih +USAGE +dvpar +.ih +DESCRIPTION +The 'dvpar' parameter set (pset) specifies device-related parameters. +These include the device name, whether plots should be appended to +existing plots, and the edges of the device viewport--that part of the +display device on which to draw the plot. + +Note that this is a parameter set (pset)--not an executable task. That +means that if the task is invoked by name on the command line, it will +start the 'eparam' task to edit the 'dvpar' parameters. Individual +parameters may be assigned using CL assignment statements from the +command line, or through the task parameters for 'fieldplot'. +.ih +PARAMETERS +.ls (device = "stdgraph") [string] +The graphics device name. The default, "stdgraph", uses the CL +environment parameter `stdgraph' to find the device name. For +example, if you are using gterm in SunView, you could have set +`stdgraph=gterm' or `device=gterm'. To overlay graphics on an image +display, use an "imd" device, "imdr" for red, "imdg" for green, etc. +.le +.ls (append = no) [boolean] +Append the graph to an existing plot? +.le +.ls (left = 0) [real, min = 0, max = 1] +The NDC coordinates of the left edge of the plot. +.le +.ls (right = 0) [real, min = 0, max = 1] +The NDC coordinates of the right edge of the plot. +.le +.ls (bottom = 0) [real, min = 0, max = 1] +The NDC coordinates of the bottom edge of the plot. +.le +.ls (top = 0) [real, min = 0, max = 1] +The NDC coordinates of the top edge of the plot. +.le +.ls (fill = yes) [boolean] +Fill the viewport? + +If set to "yes", the plot will fill the area specified by +the 'left', 'right', 'bottom', and 'top' viewport parameters. Otherwise, the +shape of the plot will reflect the aspect of the input data, but will +not be larger than the specified viewport. Note that this does not +apply to all tasks using the 'dvpar' pset. +.le +.ls (coords) [*gcur] +Graphics cursor file. +This is used if the task supports interaction via the graphics cursor. +.le +.ls (image_coord) [*imcur] +Used if the task supports interaction via the image display cursor. +.le +.ih +EXAMPLES +.ih +BUGS +.ih +SEE ALSO +fieldplot, newcont, sgraph, siaper, wcslab, +cursor, plot +.endhelp diff --git a/pkg/utilities/nttools/doc/gtedit.hlp b/pkg/utilities/nttools/doc/gtedit.hlp new file mode 100644 index 00000000..6ce396cc --- /dev/null +++ b/pkg/utilities/nttools/doc/gtedit.hlp @@ -0,0 +1,116 @@ +.help gtedit Aug93 tables +.ih +NAME +gtedit -- Graphically edit an STSDAS table. +.ih +USAGE +gtedit input xcolumn ycolumn +.ih +DESCRIPTION +The 'gtedit' task lets you graphically edit +an STSDAS table. +You can use the editor to delete rows. You can +also choose whether to overwrite the existing +file (by setting 'inplace=yes') or you +can create a new output table. You can also +save deleted points in a separate file by +setting the 'reject' parameter to an output +file name. + +The rows that are plotted can be selected using the :x and :y +commands to specify columns for the X and Y axes. Points that +are to be deleted will be marked with an "x" (this information +is retained if columns change). + +To mark a point for deletion you can: +.nf +1) Specify the points individually +2) Define a box in which all points will be deleted +3) Delete all points on one side of the cursor or line segment +.fi + +You can also toggle between "delete mode" and "undelete mode". When +you are in undelete mode, any previously-deleted points that you +selected will be unmarked. + +If you don't like using 'gtedit', you can switch to the 'tedit' +task and edit the table in the usual manner. +.ih +CURSOR COMMANDS + +.nf + GTEDIT Interactive Cursor Commands + +? Print options +: Colon commands +a print out the complete row for the data point nearest the cursor +b delete all points with Y values less than the cursor Y position +c mark the corner of a box +d delete the point nearest the cursor +e exit and save changes in the output table +f make all the marked deletions and replot remaining data +h print out the column names of the input table +l delete all points with X values less than the cursor X position +p replot the graph possibly using new data columns +q quit and do not save changes made since the last 'f' +r delete all points with X values greater than the cursor X position +s mark one end of a line segment +t delete all points with Y values greater than the cursor Y position +u toggle between delete and undelete mode +v change from gtedit to tedit mode +z display current status (delete or undelete) + +:x(-) xcolumn set the table column for the X axis and possibly replot +:y(-) ycolumn set the table column for the Y axis and possibly replot +- do not automatically replot after reading in new column + +.fi +.ih +PARAMETERS +.ls input [file name] +The input table to be edited. +.le +.ls xcolumn +The name of the column in the input table to use for the X-axis of the plot. +.le +.ls ycolumn +The name of the column in the input table to use for the Y-axis of the plot. +.le +.ls (device = "stdgraph") +The standard graphics device. +.le +.ls (commands = "") +The graphics cursor. +.le +.ls (inplace = no) +Edit the table inplace. No new output table is created and the original +table is overwritten. +.le +.ls (output = "") +The name of the output table if the input table is not edited inplace. If +inplace = no then output should be a valid filename. +.le +.ls (reject = "") +If this parameter contains a valid filename then this table will contain +the points which were deleted using this task. +.le +.ls (gtpar = "") [pset] +The name of the pset containing the parameters which describe the plot +attributes. +.ih +EXAMPLES +1. Edit a table containing the output photometry from DAOPHOT. +Initially plot the magnitude (MAG) versus the error in the magnitude (MAGERR) +to decide which points to delete. + +.nf + st> gtedit m31.mag MAG MERR +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Dennis Crabtree. +.ih +SEE ALSO +.endhelp diff --git a/pkg/utilities/nttools/doc/gtpar.hlp b/pkg/utilities/nttools/doc/gtpar.hlp new file mode 100644 index 00000000..7a06d627 --- /dev/null +++ b/pkg/utilities/nttools/doc/gtpar.hlp @@ -0,0 +1,117 @@ +.help gtpar May92 tables +.ih +NAME +pltpar -- Parameters describing plot attributes. +.ih +USAGE +pltpar +.ih +DESCRIPTION +Parameters in the 'gtpar' pset specify the attributes of plots drawn with the +'gtedit' task. + +Note that this is a pset, not an executable task. Invoking the pset by name +runs 'eparam', enabling the parameters to be interactively edited. +Parameters can also be modified on the +CL command line by specifying the pset name and parameter name, +for example, "gtpar.box = no"). +The pset name will also appear as one of +the task parameters in the 'gtedit' task; +to change values in the pset, +position the cursor to the 'gtpar' pset name and type ":e" to invoke 'eparam'. +.ih +PARAMETERS +.ls (wx1 = 0) [real] +Left world X-coordinate (if autoscaling is not used). +.le +.ls (wx2 = 0.) [real] +Right world X-coordinate (if autoscaling is not used). +.le +.ls (wy1 = 0.) [real] +Lower world Y-coordinate (if no autoscaling is used). +.le +.ls (wy2 = 0.) [real] +Upper world Y-coord (if not autoscaling). +.le +.ls (marker = box) [string, allowed values: point | box | plus | +cross | circle | diamond | hline | vline | hebar | vebar] + +The name of the style of marker plotted at each point if 'pointmode=yes'. +.le +.ls (szmarker = 0.005) [real] +The size of the markers if 'pointmode = yes'. If this parameter is greater +than 0, its value represents the marker size in world coordinates (WC). If it +is less than zero, the absolute value will be used, representing size in +normalized device coordinates (NDC). If it is set to exactly zero, and the +input is from a list file, +then the third column in the input data is used as the marker size. +.le +.ls (logx = no) [boolean] +Scale the X axis logarithmically? +.le +.ls (logy = no) [boolean] +Scale the Y axis logarithmically? +.le +.ls (box = yes) [boolean] +Draw the box containing the axes and labels around periphery of the +window? +.le +.ls (ticklabels = yes) [boolean] +Label major tick marks? +.le +.ls (grid = no) [boolean] +Draw grid lines on plot? +.le +.ls (xlabel) [string] +X-axis label. +.le +.ls (ylabel) [string] +Y-axis label. +.le +.ls (title = imtitle) +The plot title consists of a standard system-supplied string containing +the user's name, date, etc. If the 'title' parameter contains the string +"imtitle" (the default), then the plot title will contain a second line +made up from the input file or table name. Otherwise, the title will +contain the string value. +.le +.ls (vx1 = 0.) [real, min = 0, max = 1] +Left limit of device viewport. +.le +.ls (vx2 = 0.) [real, min = 0, max = 1] +Right limit of device viewport. +.le +.ls (vy1 = 0.) [real, min = 0, max = 1] +Bottom limit of device viewport. +.le +.ls (vy2 = 0.) [real], min = 0, max = 1] +Upper limit of device viewport. +.le +.ls (majrx = 5) [integer] +Number of major divisions along the X grid. +.le +.ls (minrx = 5) [integer] +Number of minor divisions along the X grid. +.le +.ls (majry = 5) [integer] +Number of major divisions along the Y grid. +.le +.ls (minry = 5) [integer] +Number of minor divisions along the Y grid. +.le +.ls (round = no) [boolean] +Round axes to nice values? +.le +.ls (fill = yes) [boolean] +Fill the viewport rather than enforcing unity aspect ratio? +.ih +EXAMPLES +.ih +BUGS +.ih +SEE ALSO +sgraph + +Type "help tables opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/imtab.hlp b/pkg/utilities/nttools/doc/imtab.hlp new file mode 100644 index 00000000..a2438f8a --- /dev/null +++ b/pkg/utilities/nttools/doc/imtab.hlp @@ -0,0 +1,169 @@ +.help imtab Mar2000 tables +.nj +.ih +NAME +imtab -- Create a table from an image. +.ih +USAGE +imtab input outtable colname +.ih +DESCRIPTION +This task copies data from an image to a table. +Pixel values are read from the image line by line +and written to a column in increasing row number. +The image may be of any dimension, +but a single column is written. +If the table already exists then columns will be added to it; +names of new columns must not conflict with existing names. +If the table does not exist it will be created. + +The number of names in the 'input' list must be the same as +the number of names in the 'outtable' list, +unless 'outtable' is "STDOUT". + +Information about the image dimension and axis lengths will not be kept +in keywords, but there is an option to write the image pixel numbers +to columns of the table. +The pixel coordinates may be just the pixel numbers, +or they may be world coordinates at the pixel locations. + +A history record will be added to the table giving +the name of the data column and the name of the image. +If pixel coordinates are written to the table, +another history record is written that also gives +the column name for the image data +and gives the column names for the pixel coordinates. +.ih +PARAMETERS +.ls input = "" [file name template] +The names of the images to be written to the tables. +.le +.ls outtable = "" [file name template] +The names of the output tables. +If outtable = "STDOUT" or if the output has been redirected, +the values will be written to the standard output. + +If the output table is of type text (e.g. STDOUT), +the data values will be in the first column. +If the pixel coordinates are also printed, +they will be in the following columns. +.le +.ls colname = "" [string] +A column of this name will be created in the output table, +and the values of the image will be written to this column. +The same column name will be used for all output tables. +.le +.ls (pname = "") [string] +If 'pname' is not null, +the pixel coordinates will also be written to columns of the table. +The names of these columns will be the value of 'pname' with the +numbers 1, 2, 3, etc appended, +corresponding to the sample number, line number, band number, etc. +This may be especially useful for a multi-dimensional input image, +since all the data values are written to one column. +The same column names will be used for all output tables. +See also 'wcs' and 'formats'. + +If 'pname' is null (or blank) the pixel numbers will not be written. +.le +.ls (wcs = "logical") [string, allowed values: logical | physical | world] +This parameter is only gotten if 'pname' is not null. +In this case, the user has the option of which coordinate system +should be used when writing pixel coordinates to the table. +The "logical" coordinates are simply the pixel numbers +of the image or image section. +The "physical" coordinates are also pixel numbers, +but they can differ from logical coordinates +if an image section has been taken. +Physical coordinates have the same origin and sampling as the original image. +The "world" coordinates are coordinates such as wavelength, time, +or right ascension and declination. +The translation from logical to world coordinates is given by +header keywords CRVAL1, CRPIX1, CD1_1, CTYPE1, etc. + +The number of pixel coordinates written by 'imtab' differs from +the number written by 'listpixels' when wcs = "physical" or "world" +and an image section was used that reduces the dimension of the image. +'imtab' gives one pixel coordinate column for each dimension +of the original image, while 'listpixels' gives one pixel coordinate +for each dimension of the image section. + +Type "help mwcs$MWCS.hlp fi+" for extensive information on coordinate systems. +.le +.ls (formats) [string] +The print formats to use for the pixel coordinates, one format +per axis, with the individual formats separated by whitespace. +This parameter is only gotten if 'pname' is not null. +If the formats are not given, a default format is assigned. +See the help for 'listpixels' for extensive information on formats. +These formats are saved in the descriptors for the table columns, +so these formats will be used if the table is printed. +If the output table is text rather than binary, +these formats will be used to write the coordinates to the text table. +.le +.ls (tbltype = "default") [string, allowed values: default | row | +column | text ] + +If the output table does not already exist, +you can specify whether the table should be created in row or column +ordered format. +As an alternative to a binary table, +tbltype = "text" means the output will be a plain text file. +.le +.ih +EXAMPLES +1. Copy image "hr465_flux.imh" to table "hr465.tab", column "flux": + +.nf + tt> imtab hr465_flux.imh hr465.tab flux +.fi + +2. Copy the 2-D image "ir27.hhh" to column "ir27" of table "map.tab", +saving the pixel numbers in columns "pix1" and "pix2": + +.nf + tt> imtab ir27.hhh map.tab ir27 pname="pix" +.fi + +3. Copy the 1-D section [257:257,129:384] of +x0y70206t.d0h to column "x0y70206" of table "focus.tab". +Also write the right ascension and declination +("world" coordinates) to columns "p1" and "p2" respectively +using HH:MM:SS.d and DD:MM:SS.d formats. +We use "%12.1H" for right ascension and "%12.1h" for declination. +The capital "H" in the format means that the values will be divided by 15 +to convert from degrees to hours before formatting in sexagesimal. +Note that we get two columns of pixel coordinates even though +the image section is only 1-D. +Physical or world coordinates will be 2-D in this case +because the original image "x0y70206t.d0h" is 2-D. + +.nf + tt> imtab x0y70206t.d0h[257:257,129:384] focus.tab x0y70206 \ + >>> pname="p" wcs="world" formats="%12.1H %12.1h" +.fi + +4. Use the same image as in the previous example, +but print the values on the standard output. + +.nf + tt> imtab x0y70206t.d0h[257:257,129:384] STDOUT x0y70206 \ + >>> pname="p" wcs="world" formats="%12.1H %12.1h" +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +The 'tabim' task copies a column of a table to an image. +The 'listpixels' task in the 'images' package writes data values and +pixel coordinates to the standard output. +The parameters 'wcs' and 'formats' are the same in 'imtab' and 'listpixels'. +For detailed information on the distinction between logical, physical and +world coordinates, type "help mwcs$MWCS.hlp fi+". + +Type "help tables option=sys" for a higher-level description of +the tables package. +.endhelp diff --git a/pkg/utilities/nttools/doc/keypar.hlp b/pkg/utilities/nttools/doc/keypar.hlp new file mode 100644 index 00000000..b1f395f6 --- /dev/null +++ b/pkg/utilities/nttools/doc/keypar.hlp @@ -0,0 +1,83 @@ +.help keypar Dec94 tables +.ih +NAME +keypar -- Copy a header keyword to an IRAF parameter. +.ih +USAGE +keypar input keyword +.ih +DESCRIPTION +This task reads a header keyword from an image or table file. The +keyword is written to the IRAF parameter 'value' as a character +string. If the header keyword is boolean, the value of 'value' will +either be "yes" or "no". If the header keyword is not found, 'value' +will be set to a null string. String parameters, such as 'value', can +be converted to numeric data types with the built in functions real() +and int(). +.ih +PARAMETERS +.ls input [file name] +Name of the file containing the header keyword. +.le +.ls keyword [string] +Name of the header keyword to be retrieved. (The keyword +name is not case sensitive.) +.le +.ls (silent = no) [bool] +If this parameter is set to no (the default) a warning message will be +printed if the keyword is not found in the header. If it is set to +yes, the warning message is suppressed. +.le +.ls (value) [string] +An output parameter that will contain the value passed from the header +keyword. +.le +.ls (found) [bool] +An output parameter that will be set to yes if the keyword is found in +the header and no if it is not. +.le +.ih +EXAMPLES +1. Print the number of groups (i.e., the 'GCOUNT' keyword) +in the image file 'image.hhh': + +.nf +tt> keypar image.hhh gcount +tt> print(keypar.value) +.fi + +2. Print the range of the data in the second group of the same image by +reading the values of the 'DATAMIN' and 'DATAMAX' keywords: + +.nf +tt> keypar image.hhh[2] datamin +tt> x = real(keypar.value) +tt> keypar image.hhh[2] datamax +tt> y = real(keypar.value) +tt> print(y-x) +.fi + +3. Print the component name (i.e., the 'COMPNAME' header keyword) +for the table 'thruput.tab': + +.nf +tt> keypar thruput.tab compname +tt> print(keypar.value) +.fi + +4. Check for the existence of the exposure time in an image header: + +.nf +tt> keypar image.hhh exptime silent+ +tt> if (keypar.found) { +>>> print keypar.value +>>> } else { +>>> print INDEF +>>> } +.fi +.ih +REFERENCES +This task was written by Bernie Simon. +SEE ALSO +keytab, parkey, partab, tabkey, tabpar +.endhelp diff --git a/pkg/utilities/nttools/doc/keyselect.hlp b/pkg/utilities/nttools/doc/keyselect.hlp new file mode 100644 index 00000000..57e96137 --- /dev/null +++ b/pkg/utilities/nttools/doc/keyselect.hlp @@ -0,0 +1,246 @@ +.help keyselect Mar92 tables +.ih +NAME +keyselect -- Copy selected image header keywords to an STSDAS table. +.ih +USAGE +keyselect input output cols +.ih +DESCRIPTION +This task copies the specified image header keywords to an STSDAS +table. The required parameters are the input list of image names, the +output STSDAS table name, and the list of header keywords. All groups of +each image will be examined if the list of header keywords contains a +group parameter. Otherwise only the first group of each image will be +examined. The task appends rows to the output table if it exists or +creates a new table if the output table does not exist. If the output +table exists, column names must match the names in the existing table. +The column names in the output table are the same as the header keywords +unless they are explicitly specified, as described below. + +If a keyword is missing from an image header a warning message is +printed and a null value inserted into the table. The default type of +the table column is determined from the type of the header keyword. +Text columns have a default length of 19 characters, unless the table +column is the concatenation of several keywords, in which case the +default length will be 63 characters. A column description file must +be used if you want to override the default type or length of a table +column. + +The third parameter ('cols') is a list of items specifying the header keyword +names and table column names. Items in the list are separated by +commas or whitespace. Three different kinds of items may appear in the +list: a keyword name, a table column name followed by a equals sign +followed by a keyword name, or a table column name followed by an +equals sign followed by a list of keyword names separated by colons. +If the item in the list is a keyword name, the table column name is +the same as the keyword name. To specify a table column name different +than the keyword name, the item in the list should be the table column +name followed by an equals sign followed by the keyword name. To +concatenate several header keywords into a string separated by commas, +a list of keyword names separated by colons should replace the header +keyword name in the item. The following list gives examples of the +three types of items. + +.nf +FGWA_ID +GRATING=FGWA_ID +OBS_MODE=DETECTOR:FGWA_ID:APER_ID +.fi + +In the first case, both the header keyword name and table column name +are 'fgwa_id'. In the second case the table column name is 'grating'. +In the third case table column name is 'obs_mode' and the values in +the column are the concatenation of the header keywords 'detector', +'fgwa_id', and 'aper_id' separated by commas. + +Special keywords may also be used in the list wherever a header +keyword may be used. Special keywords are used to place the image name +or parts of the image name in the output table. The name of a special +keyword always starts with a "$". The different special keywords, +their types, and default table column names are given in the following +list. + +.nf +$group int group +$dir text directory +$ext text extension +$hdr text header_file +$pix text data_file +$root text rootname +.fi + +If an image has the name 'yref$y00vk101a.r1h[1]', the group will be 1, +the directory 'yref$', the extension 'r1h', the header file +'y00vk101a.r1h', the data file 'y00vk101a.r1d', and the root name +'y00vk101a'. + +The hidden task parameter 'expr' is used to select which images are +examined when writing header keywords to the output table. If this +task parameter is set to its default value, ' ' (a blank string), all +images named in the image template will be examined. Otherwise the +task parameter is interpreted as a boolean (logical) expression. The +variables in the expression are header keyword names. As each image is +opened the values of the header keywords are substituted for the +keyword name. If the expression is true, the header keywords specified +in the 'cols' parameter are copied into the output table. The special +keywords mentioned above may also be used in the expression. If a +keyword name contains dashes the keyword name should be preceded by a +'@' and enclosed in quotes. For example, 'date-obs' should be given as +'@"date-obs"' in the expression. + +The following boolean operators may be used in the expression: + +.nf +equal == not equal != +less than < less than or equal <= +greater than > greater than or equal >= +or || and && +negation ! +.fi + +The expression may also include the usual arithmetic operators and +functions. Arguments to the trigonometric functions must be in +degrees. The available operators are: + +.nf +addition + subtraction - +multiplication * division / +negation - exponentiation ** +string concatenation // +.fi + +The following is a list of the available functions: + +.nf +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) +modulo mod(x,y) keyword found find(x,y,z,..) +.fi + +One new function, find, is available in addition to the usual arithmetic +functions. The argument of this function is a list of header keyword +names. The function returns true if all the header keywords are found +in the image and false if one or more header keywords in the list are +not found. The arguments to this function should be placed in quotes +as otherwise the value of the header keyword will checked instead of +the name. That is, if 'find(detector)' is used instead of +'find("detector")', the task will look for a header keyword whose name +is the value of the detector keyword. + +The 'cols' and 'expr' parameters can also be the name of a file +preceded by an '@' character. If this is done, the task will read the +list of keyword names or boolean expression from the specified file. +Newlines in the file are treated as if they were blanks, so lines may +be broken wherever a blank would be correct. Comments (lines starting +with a '#' character) are not permitted in either file. + +The hidden parameter 'cdfile' is the name of the column description +file. The default value for this parameter is ' ' (a blank string). If +the parameter contains a blank string no column description file is +used and the column data type is taken from the type of the header +keyword. A column description file contains one line for each column +in the table. Each line contains four fields in the following order: +the column name, the data type, the print format, and the units. Any +of the fields except the column name may be omitted. If a field is +omitted the default for that field will be used instead. Fields are +not case sensitive except for the units field. The column name in the +column description file must match the column name in the 'cols' +parameter. If a column name in the 'cols' parameter is not found in +the column description file, a warning message is printed and the +defaults are used for that table column. Column names in the column +description file that are not in the 'cols' parameter are ignored. For +further information on the format of a column description file, refer +to the help file for 'tlcol'. + +.ih +PARAMETERS +.ls input [file name template] +List of image names. The usual wild card characters can be used. If +the list of keyword names or the expression contains a group parameter +all groups of each image will be examined unless a group is explicitly +specified as part of the image name. +.le +.ls output [file name] +The name of the output STSDAS table. If the table already exists new +rows will be added to the existing table. Column names must match +names in the existing table. If the table does not exist a new table +will be created and any column names may be used. +.le +.ls cols [string] +The list of header keyword names separated by white space or commas. +Table column names are the same as the keyword names unless explicitly +specified in the form =. Several keywords can be +concatenated by using the form =:. If the +first character in the parameter is an '@', the rest of the parameter +is interpreted as a file name containing the list of keyword names. +.le +.ls (expr = " ") [string] +A boolean expression used to select which images are examined for +header keywords. If the string is blank (the default) all images named +in the input list are examined. Variables in the expression are +header keyword names. An image is selected if substituting the value +of the header keywords for their names makes the expression true. The +syntax of the expression follows the usual CL and SPP conventions. If +the first character in the expression is a '@', the rest of the +expression is interpreted as a filename containing the expression. +.le +.ls (cdfile = " ") [file name] +The name of the column description file. The format of a column +description file is defined in the help for 'tlcol'. Column names used +in the column description file must match the names in the 'cols' +parameter (except for case). +.le +.ih +EXAMPLES +1. Create an STSDAS table from the headers of the dead diode reference +images: + +.nf +tt> keyselect yref$*.r4h ddt.tab detector,headname,dataname +.fi + +2. Create the same table, only name the columns "header_file" and +"data_file": + +.nf +tt> keyselect yref$*.r4h ddt.tab \ +>>> detector,header_file=headname,data_file=dataname +.fi + +3. Only select images with the blue detector: + +.nf +tt> keyselect yref$*.r4h ddt.tab detector,headname,dataname \ +>>> expr="detector='blue'" +.fi + +4. Use a column description file when creating the table: + +.nf +tt> keyselect yref$*.r4h ddt.tab \ +>>> detector,header_file=headname,data_file=dataname cdfile="ddt.cd" +.fi + +The contents of the column description file: + +.nf +DETECTOR CH*5 +HEADER_FILE CH*18 +DATA_FILE CH*18 +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO + +Type "help tables opt=sys" for a description of the 'tables' package. +.endhelp diff --git a/pkg/utilities/nttools/doc/keytab.hlp b/pkg/utilities/nttools/doc/keytab.hlp new file mode 100644 index 00000000..1bccecf5 --- /dev/null +++ b/pkg/utilities/nttools/doc/keytab.hlp @@ -0,0 +1,61 @@ +.help keytab Dec94 tables +.ih +NAME +keytab -- Copy a header keyword to a table element. +.ih +USAGE +keytab input keyword table column row +.ih +DESCRIPTION +This task reads a header keyword from either an image or a table file +and writes it to a table element (row and column position). If the +data type of the header keyword differs from that of the table +element, then the value is converted to the appropriate data type. If +the keyword is not found in the header, the element will be set to the +null value appropriate for the column type. +.ih +PARAMETERS +.ls input [file name] +Name of the file containing header keyword. +.le +.ls keyword [string] +Name of the header keyword to be read. (Keyword names are not case sensitive.) +.le +.ls table [file name] +Name of the table to which the value will be written. +.le +.ls column [string] +Name of table column. (Column names are not case sensitive.) +.le +.ls row [integer, min=1, max=INDEF] +Table row number. +.le +.ls (silent = no) [bool] +If this parameter is set to no (the default) a warning message will be +printed if the keyword is not found in the header. If it is set +to yes, the warning message is suppressed. +.le +.ih +EXAMPLES +1. Copy the component name (i.e., the 'COMPNAME' header keyword) +from the table 'thruput.tab' to the +first row of the table 'graph.tab'. + +.nf +tt> keytab thruput.tab COMPNAME graph.tab COMPNAME 1 +.fi + +2. Copy the zero point of the second group (i.e., the 'CRVAL1' keyword) +in the image file 'image.hhh' to the first +wavelength in the table 'spectrum.tab'. + +.nf +tt> keytab image.hhh[2] CRVAL1 spectrum.tab WAVELENGTH 1 +.fi +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +keypar, parkey, partab, tabkey, tabpar +.endhelp diff --git a/pkg/utilities/nttools/doc/parkey.hlp b/pkg/utilities/nttools/doc/parkey.hlp new file mode 100644 index 00000000..8cf317ee --- /dev/null +++ b/pkg/utilities/nttools/doc/parkey.hlp @@ -0,0 +1,73 @@ +.help parkey Dec90 tables +.ih +NAME +parkey -- Write an IRAF parameter to a header keyword. +.ih +USAGE +parkey value output keyword +.ih +DESCRIPTION +This task changes the value of a header keyword in either a table or an +image. If the value of the task parameter 'add' is "yes", the task will +allow you to add a new keyword to the header, otherwise, adding a new +keyword will cause an error. Type conversion is performed if the data type of +the header keyword differs from the data type of the input parameter 'value'. +If a new +keyword is added to the file, the type is determined +from the input value. The +strings "yes", "y", "no", "n", "true", "t", "false", and "f", in either +upper or lower case, are interpreted as boolean values. +.ih +PARAMETERS +.ls value [string] +Input value to be written to the header keyword. (Strings are case sensitive.) +.le +.ls output [file name] +Name of the file whose header keyword is to be changed. +.le +.ls keyword [string] +Name of the header keyword to be changed. (The name is not case sensitive.) +.le +.ls (add = no) [boolean] +Allow new header keywords to be added? + +If 'add = no', then existing keywords +can take new values but no new keywords can be added to the file. +.le +.ih +EXAMPLES +1. Set the header keyword 'OVERSCAN' in the file 'image.hhh' to 5: + +.nf +tt> parkey 5 image.hhh overscan +.fi + +2. Set the group parameter 'CTYPE1' in the second group of the same +file to "ANGSTROM": + +.nf +tt> parkey ANGSTROM image.hhh[2] ctype1 +.fi + +3. Set the header keyword 'YSTEP' to the value stored +in the IRAF parameter 'x': + +.nf +tt> parkey (x) image.hhh ystep +.fi + +4. Add the keyword 'COMPNAME' to the table header and put the value "FILTER1" +in it: + +.nf +tt> parkey FILTER1 graph.tab compname add+ +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +keypar, keytab, partab, tabkey, tabpar +.endhelp diff --git a/pkg/utilities/nttools/doc/partab.hlp b/pkg/utilities/nttools/doc/partab.hlp new file mode 100644 index 00000000..fb0b9239 --- /dev/null +++ b/pkg/utilities/nttools/doc/partab.hlp @@ -0,0 +1,62 @@ +.help partab Nov91 tables +.ih +NAME +partab -- Copy an IRAF parameter to a table element. +.ih +USAGE +partab value table column row +.ih +DESCRIPTION +This task changes the value of a table element to the value of the input +parameter 'value'. If 'value' is set to "INDEF", the table element will be +set to undefined. If the data type of the table element is different from +that of the input parameter 'value', this task will perform +type conversion. The strings +"yes", "y", "no", "n", "true", "t", "false", and "f", in either upper or +lower case are interpreted as boolean values. +.ih +PARAMETERS +.ls value [string] +The IRAF parameter that will be copied into the table element. +.le +.ls table [file name] +Name of the table. +.le +.ls column [string] +Column name. (Column names are not case sensitive). +.le +.ls row [integer, min=1, max=INDEF] +Row number. +.le +.ih +EXAMPLES +1. Set the twelfth component (i.e., row 12 of column 'COMPNAME') +in the file 'graph.tab' to "FILTER1": + +.nf +tt> partab FILTER1 graph.tab COMPNAME 12 +.fi + +2. Set the first wavelength (i.e., row 1 of column 'WAVELENGTH') in +the file 'spectrum.tab' to the value contained in parameter +'x': + +.nf +tt> partab (x) spectrum.tab WAVELENGTH 1 +.fi + +3. Set the hundreth wavelength (i.e., row 100 of column 'WAVELENGTH') +in 'spectrum.tab' to undefined: + +.nf +tt> partab INDEF spectrum.tab WAVELENGTH 100 +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +keypar, keytab, parkey, tabkey, tabpar +.endhelp diff --git a/pkg/utilities/nttools/doc/pltpar.hlp b/pkg/utilities/nttools/doc/pltpar.hlp new file mode 100644 index 00000000..d43ecde7 --- /dev/null +++ b/pkg/utilities/nttools/doc/pltpar.hlp @@ -0,0 +1,160 @@ +.help pltpar Jul93 tables +.ih +NAME +pltpar -- Edit the parameter set that describes plot attributes. +.ih +USAGE +pltpar +.ih +DESCRIPTION +The 'pltpar' parameters specify the attributes of plots drawn by the +'sgraph' task. + +Note that this is a pset, not an executable task; it defines a set of +parameters used by other tasks. Invoking the pset by name runs +'eparam' on the parameter set, allowing the user to modify the +parameters. Alternatively, the parameters may be modified on the +command line by specifying the pset name and parameter name, for +example, you can type "pltpar.pointmode=yes" to set only the +'pointmode' parameter. Parameters can also be edited by using +'eparam' on the calling task (e.g., by typing "eparam sgraph"), in +which case, 'pltpar' will appear as one of the task parameters; the +'pltpar' parameters may then be edited by positioning the cursor on +the line containing the pset name and typing ":e". After editing +the pset parameters, press Control-Z to return to the main task parameter menu. +.ih +PARAMETERS +.ls (stack = no) [boolean] +Stack multiple curves on separate vertical axes? + +If this is set to +"no", all curves will be scaled together and plotted on a single set of +axes. Otherwise a separate set of axes will be drawn, joined into a +single vertical column. +.le +.ls (axis = 1) [integer, min = 1, max = 7] +Axis along which projection is to be taken. If the input image has +more than one dimension, the data will be projected to a single +dimension. This parameter specifies the axis along which projection +will occur. The default is one, i.e., project along the X axis. +.le +.ls (pointmode = no) [boolean] +Plot points only? + +If set to "no", the task will plot connected curves. Note that to +plot error bars, you must set 'pointmode = no' and 'erraxis = 1' or 'erraxis = +2'. See the descriptions of 'marker' and 'szmarker'. +.le +.ls (marker = box) [string, allowed values: point | box | plus | +cross | circle | diamond | hline | vline | hebar | vebar] + +The marker style for each plotted point if 'pointmode=yes'. See also +'szmarker'. +.le +.ls (szmarker = 0.005) [real] +The size of the markers if 'pointmode = yes'. If 'szmarker > 0', use +this value as the size in normalized device coordinates (NDC) . If +'szmarker < 0', use the absolute value as the size in world coordinates +(WCS). If 'szmarker = 0' and the input comes from a text file, use the +third column in the input data as the marker size. If data are from an +image or a table, then 'szmarker' specifies the same size of every point. +.le +.ls (erraxis = 0) [integer, min = 0, max = 2] +Plot the data as error bars? If 'erraxis = 0', plot the data as values +rather than error bars; if 'erraxis = 1', plot the data as errors +parallel to the X axis; if 'erraxis =2', plot the data as errors +parallel to the Y axis. Note that the value of 'erraxis' is ignored if +'pointmode = yes' and error bars will not be drawn. +.le +.ls (errtype = bartck) [string, allowed values: tckbar | bar | tick | +limit] + +The style of error bars (if 'erraxis' is not zero). +.le +.ls (pattern = solid) [string, allowed values: solid | dashed | +dotted | dotdash] + +The line pattern style for the curve or the first of multiple curves. +.le +.ls (crvstyle = straight) [string, allowed values: straight | pseudohist +| fullhist] + +The curve style. 'straight' means line segments will connect data +points, 'pseudohist' means that horizontal segments will be placed at +each value and vertical segments will connect these, 'fullhist' means a +bar graph, or horizontal segments at each value with vertical lines +connecting the value with the bottom axis. +.le +.ls (rejectlog = yes) [boolean] +Replace invalid logarithmic values with 'INDEF'? + +Invalid values will +be ignored in scaling and plotting. +.le +.ls (box = yes) [boolean] +Draw the box containing the axes and labels around the edge of the +window? +.le +.ls (sysid = yes) [boolean] +Include standard system information in the plot title? + +If the 'sysid' +parameter is "yes", then a string including the user's name, date, host +name, etc. is included in the plot title. +.le +.sp +.ls (barpat ="hollow") [string, allowed values: hollow, solid, ahatch, +bhatch, chatch, dhatch] + +Fill pattern for bar plot. The nature of the pattern depends on the +device and graphics kernel (driver) used to plot. Many kernels do not +support fill patterns. +.le +.sp +.ls (crvcolor = INDEF) [integer, min = 1] +Color index of data curve(s). This color applies only to plotted data +curves. The color of any axes, labels, etc., is specified by +the `color' parameter. Note that the actual, drawn color will depend +on the device and graphics kernel (driver) used to plot. Many kernels +do not support color at all. The usual interpretation of the color +index is: +.nf + + 1 -- Black + 2 -- White + 3 -- Red + 4 -- Green + 5 -- Blue + 6 -- Yellow + 7 -- Cyan (blue/green) + 8 -- Magenta (red/blue) +.fi +.le +.ls (color = INDEF) [integer, min = 1] +Color index of axis and labels. The color of the data curve(s) is +specified by the `crvcolor' parameter. Note that the actual, drawn +color will depend on the device and graphics kernel (driver) used to +plot. Most kernels do not support color. +.le +.ls (cycolor = no) [boolean] +Cycle colors instead of line style for multiple curves? + +If multiple curves are plotted on the same viewport (axes), i.e., +'stack=no', then use the color specified by the 'crvcolor' parameter +for the first curve, and the next available color for each subsequent +curve. There are eight available colors, as described in the +description of the 'crvcolor' parameter. +.le +.sp +.ls (version = 17August92) [string] +Date that the task was installed. This parameter should not be changed by +the user. +.le +.ih +EXAMPLES +.ih +BUGS +.ih +SEE ALSO +sgraph +.endhelp diff --git a/pkg/utilities/nttools/doc/tabim.hlp b/pkg/utilities/nttools/doc/tabim.hlp new file mode 100644 index 00000000..2fdba5fb --- /dev/null +++ b/pkg/utilities/nttools/doc/tabim.hlp @@ -0,0 +1,98 @@ +.help tabim Mar2000 tables +.nj +.ih +NAME +tabim -- Copy a table column to an image. +.ih +USAGE +tabim intable output colname ndim n1 n2 n3 n4 n5 n6 +.ih +DESCRIPTION +This task writes values from a column of a table to an image. +If the image does not exist, it will be created. +The value in the first row is assigned to the first pixel of the image, +and the value in the last row is assigned to the last pixel of the image. +Columns containing pixel numbers (optionally written by 'imtab') are ignored, +but you can specify the axis lengths of a multi-dimensional output image. +The number of rows in the table must equal the number of pixels in the image. +.ih +PARAMETERS +.ls intable = "" [file name template] +The names of the input tables. +.le +.ls output = "" [file name template] +The names of the output images. +If an output image does not exist it will be created. +If the image does exist it will be overwritten with values from the table. +A section of an existing image may be specified, +but note that the size must equal the number of rows in the table. +.le +.ls colname = "" [string] +The name of the column in 'intable' that is to be written to the image. +The same column name is used for all input tables. +.le +.ls ndim = 0 [integer, min=0, max=7] +If the output image does not exist, +'ndim' can be used to specify +the dimension of the image to be created. +ndim = 0 or 1 results in a one-dimensional image +which has as many elements as rows in the table. +If 'ndim' is greater than one +and the output image does not already exist, +then the parameters 'n1', 'n2', etc will be taken +to specify the axis lengths of the output image. +The lengths of all but the last axis will be gotten from 'n1', 'n2', etc.; +the last axis length will be computed from +the number of rows in the table +and the lengths of the other axes. +It is an error if the product of the specified axis lengths +does not divide evenly into the number of rows in the table. +.le +.ls n1 = 1 [integer, min=1, max=INDEF] +Length of first axis. +'n1', 'n2', etc., are ignored if ndim = 0 or 1. +.le +.ls n2 = 1 [integer, min=1, max=INDEF] +Length of second axis. +This and the subsequent axis length parameters will be ignored if ndim < 3. +.le +.ls n3 = 1 [integer, min=1, max=INDEF] +Length of third axis. +.le +.ls n4 = 1 [integer, min=1, max=INDEF] +Length of fourth axis. +.le +.ls n5 = 1 [integer, min=1, max=INDEF] +Length of fifth axis. +.le +.ls n6 = 1 [integer, min=1, max=INDEF] +Length of sixth axis. +.le +.ih +EXAMPLES +1. Copy column "flux" from table "hr465.tab" to +the 1-D image "hr465_flux.imh": + +.nf + ta> tabim hr465.tab hr465_flux.imh flux 1 +.fi + +2. Create a three-dimensional image "ir27.imh" of size 62 x 64 x 4. +Read the values from column "v1" of table "t18_30.tab", +which has 62*64*4 rows. + +.nf + ta> tabim t18_30.tab ir27.imh v1 3 62 64 +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +The 'imtab' task copies an image to a column of a table. + +Type "help tables option=sys" for a higher-level description of +the tables package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tabkey.hlp b/pkg/utilities/nttools/doc/tabkey.hlp new file mode 100644 index 00000000..0f87c64f --- /dev/null +++ b/pkg/utilities/nttools/doc/tabkey.hlp @@ -0,0 +1,68 @@ +.help tabkey Nov91 tables +.ih +NAME +tabkey -- Copy a table element to a header keyword. +.ih +USAGE +tabkey table column row output keyword +.ih +DESCRIPTION +This task copies the value of a table element to a header +keyword in either a table +or an image. If the table element and the header keyword are of different +data types, this task will convert the type. +An error will occur if any attempt is made +to copy an undefined table element to a header keyword. If the value of +the task parameter 'add' is "yes", the task will allow you to add a new +keyword to the header, otherwise, adding a new keyword will cause an +error. +.ih +PARAMETERS +.ls table [file name] +Name of table containing the element to be copied. The particular element +is defined by the 'column' and 'row' parameters. +.le +.ls column [string] +Name of column. (Column names are not case sensitive.) +.le +.ls row [integer, min=1, max=INDEF] +Row number. +.le +.ls output [file name] +Name of the file with the header keyword whose value is to be changed. +.le +.ls keyword [string] +Name of header keyword. (Header keyword names are not case sensitive.) +.le +.ls (add = no) [boolean] +Allow new keywords to be added to the header? +If 'add = no', then only existing header keywords can be modified--an error +will occur if a keyword is specified that does not already exist. +.le +.ih +EXAMPLES +1. Copy the first component name (i.e., row 1 of column 'COMPNAME' +from the file 'graph.tab' to the header of the +table 'thruput.tab'. If the keyword does not already exist, then add +it: + +.nf +tt> tabkey graph.tab COMPNAME 1 thruput.tab COMPNAME add+ +.fi + +2. Copy the date of the tenth observation (i.e., row 10 of column 'DATE') +from the file 'schedule.tab' to the +header keyword 'DATE' in 'image.hhh'. The keyword 'DATE' must already exist: + +.nf +tt> tabkey schedule.tab DATE 10 image.hhh date +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +keypar, keytab, parkey, partab, tabpar +.endhelp diff --git a/pkg/utilities/nttools/doc/tabpar.hlp b/pkg/utilities/nttools/doc/tabpar.hlp new file mode 100644 index 00000000..8a5b9ffb --- /dev/null +++ b/pkg/utilities/nttools/doc/tabpar.hlp @@ -0,0 +1,95 @@ +.help tabpar May2002 tables +.ih +NAME +tabpar -- Copy a table element to an IRAF parameter. +.ih +USAGE +tabpar table column row +.ih +DESCRIPTION +This task reads a table element specified by a table name, column name, +and row number. The element is written to the task parameter 'value' as +a character string. If the table element is boolean, then 'value' will +be either "yes" or "no". If the element is undefined, the task parameter +'undef' will be set to "yes". String parameters, such as 'value', can be +converted to numeric types with the built in functions real() and int(). +.ih +PARAMETERS +.ls table [file name] +Name of the table from which this task is to read a value. +.le +.ls column [string] +Column name. (The column name is not case sensitive.) +.le +.ls row [integer, min=1, max=INDEF] +Row number. +.le +.ls (format=yes) [boolean] +Format the value using table print format? + +The value from the table is returned to this task as a string parameter +(see 'value'). +The default is to use the print format for 'column' to format the value, +because this preserves the behavior of the task +prior to the addition of the 'format' parameter. +This behavior may be desirable when using h or m format, for example, +or perhaps when using x or o format. +On the other hand, +it will often be the case that what you want is +the actual value in the table, +and using the print format +could significantly limit the accuracy of the result. +In this case, use format=no. +.le +.ls (value) [string] +This parameter is used to store the value read in from 'table'. +.le +.ls (undef) [boolean] +Is the value read in from 'table' undefined? +.le +.ih +EXAMPLES +1. Print the interval between the first 2 wavelengths (i.e., rows 1 and 2 +in the column 'WAVELENGTH') in the table 'spectrum.tab': + +.nf +tt> tabpar spectrum.tab WAVELENGTH 1 +tt> x = real(tabpar.value) +tt> tabpar spectrum.tab WAVELENGTH 2 +tt> y = real(tabpar.value) +tt> print(y-x) +.fi + +2. Print the twelfth component name (i.e., row 12 of the column 'COMPNAME', +after checking to see if it is undefined. If the value is undefined, then +print a message instead: + +.nf +tt> tabpar graph.tab COMPNAME 12 +tt> if (tabpar.undef) { +>>> print ("Component name undefined") +>>> } else { +>>> print ("Component name = ",tabpar.value) +>>> } +.fi + +3. Here is an example illustrating the difference between +format=yes and format=no for an integer column with x (hexadecimal) format: + +.nf +tt> tabpar g.tab counts 4 format=yes +tt> =tabpar.value +31 +tt> tabpar g.tab counts 4 format=no +tt> =tabpar.value +49 +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +keypar, keytab, parkey, partab, tabkey +.endhelp diff --git a/pkg/utilities/nttools/doc/taextract.hlp b/pkg/utilities/nttools/doc/taextract.hlp new file mode 100644 index 00000000..50e34dbe --- /dev/null +++ b/pkg/utilities/nttools/doc/taextract.hlp @@ -0,0 +1,109 @@ +.help taextract Jan98 tables +.nj +.ih +NAME +taextract -- Copy an array entry from one table +to a column of scalars in another. +.ih +USAGE +taextract intable outtable row column +.ih +DESCRIPTION +This task extracts one entry (presumably an array of values) +at a specified row and column +and writes it as a column of scalar values to another table. +If the output table exists it will be written to in-place; +otherwise, it will be created. + +By default, the same column name is used in both tables. +If the output table and column already exist, +the data in that column will be overwritten; +otherwise, the column will be created. +If the array size for the specified column in the input table is N, +then the values will be written to rows 1 through N of the output table. +If the output column already exists, +and the output table contains more than N rows, +then rows N+1 through the last will be set to INDEF for this column. + +The input row number is written to the header of the output table +using keyword ORIG_ROW. +This allows 'tainsert' to put the data back where 'taextract' got them from. +.ih +PARAMETERS +.ls intable [file name] +Name of the input table containing a column with array entries. +It is not an error for the array length to be one. +.le +.ls outtable [file name] +Name of the output table. +If this table doesn't exist it will be created. +If the table does exist the column will either be created or overwritten. +The input and output tables may not be the same, +and they may not be in the same file if FITS format is used. +.le +.ls row [integer, min=1, max=INDEF] +This is the row number in the input table. +In the output table there will be as many rows +as there are elements in the input table entry for 'column'. +.le +.ls column [string] +Column name. +This is used to find the column in the input table, +and by default the same name is used to create +(or find, if it already exists) +the column in the output table. +See the description for 'outcolumn'. +.le +.ls outcolumn = "" [string] +If 'outcolumn' is specified, +that name will be used for the output table; +otherwise, 'column' will be used for both input and output tables. +This provides an easier way to change the name of the output column +than by running 'tchcol' after running 'taextract'. +Note that if 'outcolumn' is specified, +it is used not only for finding the column in the output table +but also for creating the column if it wasn't found. +The 'datatype', 'colunits', and 'colfmt' parameters, by contrast, +are only used when creating a new column. +.le +.ls (datatype = "") [string] +When creating a new column in the output table, +the default is to use the same data type as the column in the input table. +However, if 'datatype' is specified (i.e. not null or blank), +this will be used as the data type when creating the new column. +For numeric and boolean columns, only the first character is used: +"r" and "d" for single and double precision floating point, +"s" and "i" for short integer and integer, +"b" for boolean. +For a character string of maximum length 12 (for example), use "ch*12". +.le +.ls (colunits = "") [string] +When creating a new column in the output table, +the units will be set to 'colunits' if it has been specified; +otherwise, the units will be copied from the column in the input table. +.le +.ls (colfmt = "") [string] +When creating a new column in the output table, +the print format will be set to 'colfmt' if it has been specified; +otherwise, the print format will be copied from the column in the input table. +.le +.ih +EXAMPLES +1. Extract the array from row 5, column "polar", from table "array.tab", +putting the values in column "polar" of table "scalar.tab". + +.nf +at> taextract array.tab scalar.tab 5 polar +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tainsert + +Type "help ttools opt=sysdoc" for a higher-level description of the 'ttools' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tainsert.hlp b/pkg/utilities/nttools/doc/tainsert.hlp new file mode 100644 index 00000000..3d07855b --- /dev/null +++ b/pkg/utilities/nttools/doc/tainsert.hlp @@ -0,0 +1,132 @@ +.help tainsert Jan98 tables +.nj +.ih +NAME +tainsert -- Copy a column of scalars from one table +to an array entry in another. +.ih +USAGE +tainsert intable outtable row column +.ih +DESCRIPTION +This task reads an entire column from one table +and inserts those values (presumably more than one) +at a specified row and column in an output table. +If the output table exists it will be written to in-place; +otherwise, it will be created. + +By default, the same column name is used in both tables. +If the column does not exist in the output table, the column will be created. +If the output table and the row and column already exist, +the array of values at that location will be overwritten. +The number of elements copied will be the minimum of +the number of input rows and the output column array size. +If the number of input rows is larger than the array size, +a warning message will be printed, +and the extra rows will be ignored. +If the number of input rows is smaller than the array size, +the remaining array elements will be set to INDEF. + +If the specified row number is less than one or is INDEF, +'tainsert' looks for the header keyword ORIG_ROW in the input table. +ORIG_ROW is written by 'taextract'. +If that keyword exists, its value is used as the row number. +.ih +PARAMETERS +.ls intable [file name] +Name of the input table. +.le +.ls outtable [file name] +Name of the output table. +If this table doesn't exist it will be created. +.le +.ls row = -1 [integer] +This is the row number in the output table. +The default means that 'tainsert' should use +the value of the header keyword ORIG_ROW. +.le +.ls column [string] +Column name in the input table and, by default, also in the output table. +If this column does not exist in the output table, it will be created, +and the array size will be set to the number of rows in the input table. +See the descriptions for 'outcolumn' and 'size', however. + +It is an error if this column in the input table contains array entries. +.le +.ls outcolumn = "" [string] +If 'outcolumn' is specified, +that name will be used for the output table; +otherwise, 'column' will be used for both input and output tables. +This provides an easier way to change the name of the output column +than by running 'tchcol' after running 'taextract'. +Note that if 'outcolumn' is specified, +it is used not only for finding the column in the output table +but also for creating the column if it wasn't found. +The 'size', 'datatype', 'colunits', and 'colfmt' parameters, +by contrast, are only used when creating a new column. +.le +.ls (size = INDEF) [int] +When creating a new column in the output table, +the default is for the array size of that column to be set to +the number of rows in the input table. +This may be overridden by specifying a value for 'size'. +If 'size' is a positive integer, not INDEF, +this will be used as the array size when creating the new column. +.le +.ls (datatype = "") [string] +When creating a new column in the output table, +the default is to use the same data type as the column in the input table. +However, if 'datatype' is specified (i.e. not null or blank), +this will be used as the data type when creating the new column. +For numeric and boolean columns, only the first character is used: +"r" and "d" for single and double precision floating point, +"s" and "i" for short integer and integer, +"b" for boolean. +For a character string of maximum length 12 (for example), use "ch*12". +.le +.ls (colunits = "") [string] +When creating a new column in the output table, +the units will be set to 'colunits' if it has been specified; +otherwise, the units will be copied from the column in the input table. +.le +.ls (colfmt = "") [string] +When creating a new column in the output table, +the print format will be set to 'colfmt' if it has been specified; +otherwise, the print format will be copied from the column in the input table. +.le +.ih +EXAMPLES +1. Copy the entire column "polar" from table "scalar.tab", +and insert the values into row 5, column "polar", of table "array.tab". +If "array.tab" does not exist it will be created. +If column "polar" does not exist in "array.tab", +that column will be created. + +.nf +at> tainsert scalar.tab array.tab 5 polar +.fi + +2. Copy the arrays from row 5, columns "wavelength" and "flux", +from "array.tab" to a temporary table, +sort them on the wavelength, +and insert them back where they came from. + +.nf +at> taextract array temp 5 wavelength +at> taextract array temp 5 flux +at> tsort temp wavelength +at> tainsert temp array 0 wavelength +at> tainsert temp array 0 flux +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +taextract + +Type "help ttools opt=sysdoc" for a higher-level description of the 'ttools' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tcalc.hlp b/pkg/utilities/nttools/doc/tcalc.hlp new file mode 100644 index 00000000..10b5415d --- /dev/null +++ b/pkg/utilities/nttools/doc/tcalc.hlp @@ -0,0 +1,153 @@ +.help tcalc Jan92 ttools +.ih +NAME +tcalc -- Perform arithmetic operations on table columns. +.ih +USAGE +tcalc table outcol equals +.ih +DESCRIPTION +This task evaluates an arbitrary expression that includes column names, +constants, and operators, and creates a specified column in the +table---or overwrites an existing column if the specified name already exists. +Variables in the expression are column names in either case. + +Columns +may be of any type except string. If the column name contains +non-alphanumeric characters, it should be preceded by a dollar sign +and followed by a blank. For example, the expression "date-obs+1." +contains the column "date-obs", but the task thinks that it contains +two column names, "date" and "obs". To ensure that the expression is +evaluated correctly, rewrite it as "$date-obs +1.". The variable +"rownum" may also be used in an expression if there is no column in +the table of the same name. Its value is the current row number. The +expression will be evaluated using the data types of the columns and +constants in the expression, with the usual rules of type promotion used in +Fortran. Please remember that integer division truncates. + +The output value in any row will be set to INDEF if one or more column +values used in the calculation is equal to INDEF. The result will be +INDEF if either of the clauses in an if expression contains a row with +an INDEF value. If the result of an operation is undefined (such as +division by zero) the output column will also be set to INDEF. + +The following Fortran-type arithmetic operators are supported. If the +second argument of the exponentiation is not an integer, the result +will be undefined if the first argument is not positive. Again, +remember that integer division truncates. + +.nf ++ addition - subtraction +* multiplication / division +- negation ** exponentiation +.fi + +The following logical operators are supported. Logical operators will +return a value of 1 if true or 0 if false. Logical operators are +supported in both their Fortran and SPP form. + +.nf +.or. || logical or .and. && logical and +.eq. == equality .ne. != inequality +.lt. < less than .gt. > greater than +.le. <= less or equal .ge. >= greater or equal +.not. ! not +.fi + +The following functions are supported. These functions all take a +single argument, which may be an expression. The argument or result of +trigonometric functions are in radians. + +.nf +abs absolute value acos arc cosine +asin arc sine atan arc tangent +cos arc cosine cosh hyperbolic cosine +cube third power double convert to double +exp E raised to power int convert to integer +log natural logarithm log10 common logarithm +nint nearest integer real convert to real +sin sine sinh hyperbolic sine +sqr second power sqrt square root +tan tangent tanh hyperbolic tangent +.fi + +The following functions take two arguments. + +.nf +atan2 arc tangent dim positive difference +max maximum min minimum +mod modulus sign sign transfer +.fi + +Conditional expressions of the form "if expr then expr else expr" are +supported. The expression after the else may be another conditional +expression. The words "if", "then", and "else" must be surrounded by +blanks. +.ih +PARAMETERS +.ls table [file name template] +The input table, or tables; these files are modified in-place. +Results will be written to a new column in the table unless an +existing column name is specified, in which case the existing values +will be overwritten. +.le +.ls outcol [string] +Output column name. This is the column where results are written. +Caution: if this column already exists, then it will be overwritten +with the results of the calculation. Note that column names are not +case sensitive. +.le +.ls equals [string] +The arithmetic expression to evaluate. If the expression is too long +to pass as a parameter, place the expression in a file and set the +value of this parameter to the file name preceded by an "@", for +example, "@filename". +.le +.ls (datatype = real) [string, allowed values: real | double | int ] + +Type of data stored in the output column, if it is a new column. +.le +.ls (colunits) [string] +Units for the output column, if it is a new column. This parameter +may be blank. +.le +.ls (colfmt) [string] +Print format for the output column, if it is a new column. If this +parameter is left blank then a default will be used. Type "help +ttools opt=sysdoc" for more information about print formats. +.le +.ih +EXAMPLES +1. Create a column called 'FLUX', which will contain a value equal to +10.0**(-x/2.5) where x is the value in the column 'MAG'. The new +column will contain single precision data. + +.nf +tt> tcalc "intab" "FLUX" "10.0**(-mag/2.5)" +.fi + +2. Create a column called 'POLY', which will contain a value equal to +x+x**2 where x is the row number in the table. + +.nf +tt> tcalc "test" "POLY" "rownum+sqr(rownum)" +.fi + +3. Set quotient to zero where divison by zero would otherwise occur: + +.nf +tt> tcalc "test" "QUOT" "if y != 0 then x / y else 0." +.fi + +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +imcalc + +Type "help ttools opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tchcol.hlp b/pkg/utilities/nttools/doc/tchcol.hlp new file mode 100644 index 00000000..1a53c00c --- /dev/null +++ b/pkg/utilities/nttools/doc/tchcol.hlp @@ -0,0 +1,80 @@ +.help tchcol Jan92 tables +.nj +.ih +NAME +tchcol -- Change column description. +.ih +USAGE +tchcol table oldname newname newfmt newunits +.ih +DESCRIPTION +This task may be used to change the name of a column, the display +format, or the units. +To change more than one column the task must be called more than once. +Only those items (name, units, format) that are not null will be changed. +The word "default" may be used to set +the print format or the units to their default values. +.ih +PARAMETERS +.ls table [file name template] +Names of tables to be modified. +The same change(s) will be made to all tables. + +Note that the tables are modified in-place. +.le +.ls oldname = "" [string] +Name of column to be changed. +If the column is not found, +a message will be printed, +and the current table will not be changed. +.le +.ls newname = "" [string] +New column name or a null string (""). + +If this is null or blank, the column name will not be changed. +.le +.ls newfmt = "" [string] +New value for print format, or "default" or "". + +If this is null or blank, the display format will not be changed. +If 'newfmt = "default"' the print format will be set to the default +for the column data type. +Type "help ttools opt=sysdoc" for more information about print formats. +.le +.ls newunits = "" [string] +New value for units, or "default" or "". + +If this is null or blank the units will not be changed. +If newunits = "default" the units will be set to null. +There is no way (with this task) to set the units to the value "default"! +.le +.ls (verbose = yes) [boolean] +Print the names of tables as the task progresses? + +If 'verbose=yes' then the table names are printed, +and for each item that is changed, a message is printed +giving the old and new values. +.le +.ih +EXAMPLES +In table 'm87pol.tab', change column name "chi" to "CHI" and set the units +to degrees. The display format is not changed. + +.nf +tt> tchcol m87pol chi CHI "" degrees +.fi + +In the same table, set the units of column "P" to null. +The name and format are not changed. + +.nf +tt> tchcol m87pol P "" "" default +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by J.C. Hsu and was modified by Phil Hodge. +.ih +SEE ALSO +.endhelp diff --git a/pkg/utilities/nttools/doc/tcheck.hlp b/pkg/utilities/nttools/doc/tcheck.hlp new file mode 100644 index 00000000..e9cb3e89 --- /dev/null +++ b/pkg/utilities/nttools/doc/tcheck.hlp @@ -0,0 +1,137 @@ +.help tcheck Aug91 tables +.ih +NAME +tcheck -- Check STSDAS table values. +.ih +USAGE +tcheck input chkfile +.ih +DESCRIPTION +This task allows the user to check the correctness of an STSDAS table by +printing the rows, column names, and values of selected table +elements. The table elements selected are controlled by lines in the +check file. Table elements are printed by placing their names on a +line in the check file followed by the word "when" and a logical +expression. The values of all columns listed before the "when" will be +printed for each row for which the expression is true. For example, + +.nf +ylower, yupper when ylower >= yupper +.fi + +prints the values of the columns 'ylower' and 'yupper' for any row +where 'ylower' is greater than or equal to 'yupper'. If the column names +and expression are too long to fit on a line, the line can be +continued by placing a backslash as the last character on the line. +Lines which are blank, or start with a comment character (#), are +ignored. + +An expression may contain table column names and string or numerical +constants. The table column names may be in either lower or upper +case. If "when" is a column name, place it in upper case so its +meaning will not be ambiguous. String constants may be surrounded by +either single or double quotes. Numeric constants will be treated as +real numbers if they contain a decimal point or integers if they do +not. + +The expression must have a boolean (logical) value. Boolean operators +can be used in an expression in either their SPP or Fortran form: + +.nf +equal == .eq. not equal != .ne. +less than < .lt. less than or equal <= .le. +greater than > .gt. greater than or equal >= .ge. +or || .or. and && .and. +negation ! .not. +.fi + +The expression may also include the usual arithmetic operators and +functions. Arguments to the trigonometric functions must be in +degrees. The available operators are: + +.nf +addition + subtraction - +multiplication * division / +negation - exponentiation ** +string concatenation // +.fi + +Three new functions are available in addition to the usual arithmetic +functions: +.nf + +row takes no argument, returns current row number +delta takes two dates (in CDBS format) and returns the + number of days between them +match returns true if the first argument matches one or more + of the remaining arguments of the function (the arguments + may be of any type, as long as all arguments have the + same type. +.fi + +The +following is a list of the available functions: + +.nf +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) +modulo mod(x,y) row number row() +date difference delta(x,y) equality match (x,y,z,...) +.fi + +.ih +PARAMETERS +.ls input [file name template] +List of tables that will be checked. +.le +.ls chkfile [file name] +Text file containing consistency checks. +.le +.ih +EXAMPLES +1. The simplest check is when a table element has one legal +value. This can be tested for as follows. + +.nf +overscan when overscan != 5 +.fi + +2. A range of values can also be tested, as in the following expressions. + +.nf +aper_area when aper_area <= 0.0 +pass_dir when detnum < 1 || detnum > 2 +.fi + +3. If a keyword has several legal values and they do not form a range, it +may be easier to use the match function. + +.nf +fgwa_id when ! match(fgwa_id,"CAM","H13","H19","H27",\ +"H40","H57","H78") +.fi + +4. The value of one keyword may depend on the value of another. This can +be tested by combining the conditions with an "and": + +.nf +aper_pos when aper_id == 'A-1' && aper_pos != 'SINGLE' +polar_id when fgwa_id == 'CAM' && polar_id != 'C' +.fi + +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +hcheck + +Type "help tables opt=sys" for a description of the 'tables' package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tchsize.hlp b/pkg/utilities/nttools/doc/tchsize.hlp new file mode 100644 index 00000000..fa9bbb96 --- /dev/null +++ b/pkg/utilities/nttools/doc/tchsize.hlp @@ -0,0 +1,158 @@ +.help tchsize Oct95 tables +.nj +.ih +NAME +tchsize -- Change the size of tables. +.ih +USAGE +tchsize intable outtable maxpar maxcols rowlen allrows +.ih +DESCRIPTION +This task changes the allocated sizes of various portions of a table +or a list of tables. +In some cases it is difficult to effectively use this task, +so caution is advised. + +NOTE: This task should not be used on FITS tables. +If any input table is of type FITS, +a message will be printed, and that file will be skipped. + +Four integer parameters specify table sizes. +Passing a value of -1 to any parameter means that the current value +should not be changed. A value (such as zero) that is smaller than +the minimum allowed value for that parameter results in the truncation +of unused space; for example, if three header parameters have already +been written to a table then setting 'maxpar=0' gives you a table with +space for only three header parameters. + +The input may be a general filename +template, including wildcard characters or the name of a list file (preceded +by an "@" sign) containing table names. The output may be null, a directory +specification, or a list of table names. If the output is a list of tables +then there must be the same number of names in the input and output lists, +and the names are taken in pairs, one from input and one from output. +A null string for the output is equivalent to specifying the same names +for the input and output tables. + +NOTE: Be careful when using a wildcard for the extension. +If you have the files 'table.tab' and 'table.lis' in the current directory, +for example, then "tchsize tab* test/" would crash when trying to open +'table.lis' as a table. +.ih +PARAMETERS +.ls intable [file name template] +A list of one or more tables whose sizes are to be changed. +.le +.ls outtable = "" [file name template] +Either a null string, a directory name, or a list of output table names. +.le +.ls maxpar = -1 [integer] +The number of records to allocate for header (i.e., user) parameters. + +Use 'maxpar=-1' if no change is to be made; set 'maxpar=0' to +truncate unused space. +.le +.ls maxcols = -1 [integer] +The amount of space to allocate for column descriptors. There must be +at least one for each column that is defined or is to be defined. +For a column-ordered table 'maxcols' actually determines the maximum +number of columns that may be defined (without having to rewrite the +table). For a row-ordered table, however, you must also specify an +appropriate value for 'rowlen'; you may want to use the 'tinfo' task +to get the +current row length before using this task. + +Set 'maxcols=-1' if no change is to be made; set 'maxcols=0' +to truncate unused space. +.le +.ls rowlen = -1 [integer] +The row length; this is only relevant for a row-ordered table. +The unit of length is the amount of memory used to store +a real number; so a double-precision column +takes two units, and a character*24 column takes six units (assuming +that a real +is four bytes). +The number of columns that may be defined is limited both by the +space allocated for column descriptors and by the row length. + +Set 'rowlen=-1' if no change is to be made; set 'rowlen=0' +to truncate unused space. +.le +.ls allrows = -1 [integer] +The number of rows to allocate; this is only relevant for a column-ordered +table. + +Set 'allrows=-1' if no change is to be made; set 'allrows=0' to truncate +unused space. +.le +.ls (verbose = yes) [boolean] +Display the names of the input and output tables for each table that is +processed? +.le +.ih +EXAMPLES +1. Truncate (in-place) all unused space in a single table: + +.nf + tt> tchsize table "" 0 0 0 0 + or + tt> tchsize table table 0 0 0 0 +.fi + +2. Set the allocated space for user (header) parameters to 27 records +without changing any other size parameter. The result is to be put +in a new file called 'table2.tab', leaving the input table unchanged. + + tt> tchsize table table2 27 -1 -1 -1 + +3. Truncate unused space in three different tables, with the truncated tables +named 'a.tab', 'b.tab', and 'c.tab': + +.nf + tt> tchsize table1,table2,tab67 a,b,c 0 0 0 0 + or + tt> tchsize tab*.tab a,b,c 0 0 0 0 +.fi +In the latter case the extension is given explicitly in case there +are other files beginning with 'tab' that are not tables; there must +be exactly three tables beginning with tab because the output list +has three names. + +4. Increase the space available for allocating new columns: + +Suppose the following information about the table has been obtained +by using the 'tinfo' task: + +.nf + tinfo.ncols = 7 + tinfo.maxcols = 8 + tinfo.rowlen = 12 + tinfo.rowused = 10 + tinfo.tbltype = "row" +.fi + +Suppose we want to add 10 more columns: five single-precision columns, +two double-precision, and three character*12. If the table were +column-ordered we would only have to increase 'maxcols' to at least 17 +('ncols'+10). Since the table is row-ordered we still must have 'maxcols=17', +but we also have to increase the row length to allow room for the +additional columns. The extra row length needed is 5 + 2*2 + 3*3 = 18, +so we must set the new row length to at least 'tinfo.rowused' + 18 = 28. +So we have + +.nf + tt> tchsize table "" -1 17 28 -1 +.fi + +if the space for header parameters does not need to be changed, and +the allocated number of rows is irrelevant for a row-ordered table. + +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tinfo +.endhelp diff --git a/pkg/utilities/nttools/doc/tcopy.hlp b/pkg/utilities/nttools/doc/tcopy.hlp new file mode 100644 index 00000000..a7ac05d7 --- /dev/null +++ b/pkg/utilities/nttools/doc/tcopy.hlp @@ -0,0 +1,113 @@ +.help tcopy Jan2001 tables +.nj +.ih +NAME +tcopy -- Copy tables. +.ih +USAGE +tcopy intable outtable +.ih +DESCRIPTION +This task is used to copy tables. The input may be a general filename +template, including wildcard characters or the name of a file (preceded +by an @ sign) containing table names. The output may be either a directory +specification or a list of table names. If the output is a list of tables +then there must be the same number of names in the input and output lists, +and the names are taken in pairs, one from input and one from output. +The input and output tables must not be the same. +This task will convert the format of the table +if the output filename extension indicates it. +For example, if the output filename extension is ".fits", +the output table will be a fits file. +If the output is redirected or piped, +it will be written to a text table. + +NOTE: Be careful when using a wildcard for the extension. +If you have the files "table.tab" and "table.lis" in the current directory, +for example, then the command "tcopy tab* test/" would copy both files +to the subdirectory "test". +.ih +PARAMETERS +.ls intable [file name template] +A list of one or more tables to be copied. +.le +.ls outtable [file name template] +Either a directory name or a list of output table names. + +If 'outtable' is not a directory, +the number of input tables and output tables must be the same. +An exception to this rule is that if 'outtable' is a FITS file +(i.e. an existing FITS file, or the name ends in ".fits") +then multiple input tables can be copied to one output file. +.le +.ls (verbose = yes) [boolean] +Display names of input and output tables as they are copied? +.le +.ih +EXAMPLES +1. To simply copy a table: + +.nf + tt> tcopy table.tab tablecopy.tab +.fi + +2. To copy one or more tables, possibly changing table type: + +.nf + tt> tcopy table1.tab,table2.tab a.fits,b.tab + tt> tcopy a.fits,b.tab a.tab,b.fits + tt> tcopy a.fits > a.txt +.fi + +The number of input and output tables must be the same. +In the third case, +"a.txt" will be a text file because +the output table name was "STDOUT" +(the name was implicitly set, in this case, +because the output was redirected.) + +3. To copy a set of tables to a new directory: + +.nf + tt> tcopy table*.tab directory + or + tt> tcopy table*.tab directory$ + or + tt> tcopy table*.tab osdirectory +.fi + +where "directory" is an IRAF environment variable for a directory name, +and "osdirectory" is an operating system directory name +(e.g., "/user/me/" in UNIX). + +4. To copy only specified extensions of a FITS file: + +.nf + tt> tcopy xyz.fits[3],xyz.fits[5] b.fits +.fi + +If "b.fits" did not already exist, +it would be created and would then contain two table extensions. +If it did already exist, +the two extensions would be appended. +Note that the number of input and output files are not the same; +this is OK because the output is a FITS file +and can therefore contain multiple table extensions. + +5. The input and/or output may be redirected: + +.nf + tt> dir l+ | tproject columns=c7,c3 | tcopy dir.tab > verbose.lis +.fi + +"verbose.lis" contains just the one line "# STDIN -> dir.tab", +and "dir.tab" has the output of 'tproject', the file names and sizes. +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tdelete +.endhelp 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 diff --git a/pkg/utilities/nttools/doc/tdelete.hlp b/pkg/utilities/nttools/doc/tdelete.hlp new file mode 100644 index 00000000..43b9ee64 --- /dev/null +++ b/pkg/utilities/nttools/doc/tdelete.hlp @@ -0,0 +1,74 @@ +.help tdelete Aug93 tables +.nj +.ih +NAME +tdelete -- Delete a table. +.ih +USAGE +tdelete table +.ih +DESCRIPTION +This task deletes tables. +The input may be a general filename template, +including wildcard characters, or the name of a list file +(preceded by the "@" character) containing table names. + +The task checks that the file to be deleted really is a table +before deleting it. +In order to protect against accidental deletion of files other than tables, +text tables may be deleted using 'tdelete' only if 'verify = yes'. +.ih +PARAMETERS +.ls table [file name template] +A list of one or more tables to be deleted. +.le +.ls (verify = no) [boolean] +Prompt for confirmation before deleting? It is possible to delete +text tables using 'tdelete' if 'verify' is set to "yes". +.le +.ls (default_action = yes) [boolean] +Default action for the verify query. If 'default_action = yes', then the +prompt will come back with "yes?" and striking return will proceed with +the delete. +.le +.ls go_ahead = yes [boolean] +This is a copy of 'default_action' used for prompting if 'verify = yes'. +This parameter is set by the task, it copies the value of 'default_action', +but cannot be directly set by the user. +.le +.ih +EXAMPLES +1. Delete a single table. + +.nf + cl> tdelete table +.fi + +2. Delete several tables. + +.nf + cl> tdelete table1,table2,tab67 + cl> tdelete *.tab,a,b,c + +.fi +In the latter case, the extension is given explicitly because there may be +other files beginning with "tab" that are not tables. + +3. Delete a list of tables using verify. + +.nf + cl> tdelete fits*.tab ver+ + cl> delete table `fits1.tab' ? (yes): yes + cl> delete table `fits2.tab' ? (yes): yes + cl> delete table `fits3.tab' ? (yes): yes +.fi +.ih +BUGS +Text tables cannot be deleted by 'tdelete' unless 'verify' is set to yes. +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +delete, tcopy, trename +.endhelp diff --git a/pkg/utilities/nttools/doc/tdiffer.hlp b/pkg/utilities/nttools/doc/tdiffer.hlp new file mode 100644 index 00000000..915aa4c6 --- /dev/null +++ b/pkg/utilities/nttools/doc/tdiffer.hlp @@ -0,0 +1,65 @@ +.help tdiffer May92 tables +.ih +NAME +tdiffer -- Create a new table which is the difference of two tables. +.ih +USAGE +tdiffer intable1 intable2 outtable colnam1 colnam2 +.ih +DESCRIPTION +This task creates an output table containing all the rows of the first table +which do not match the rows in the second table. +The first, second, and output tables are given by the task +parameters 'intable1', 'intable2', and 'outtable' respectively. +The match is done on the columns specified by the task parameters 'colnam1' +and 'colnam2'. +Other columns are ignored. +If the two tables are disjoint, the output table will be a copy of +the first table, except the rows will be sorted. +If the first table is a subset of the second, the output table will be empty. +.ih +PARAMETERS +.ls intable1 [file name] +The name of the first input table. +.le +.ls intable2 [file name] +The name of the second input table. +.le +.ls outtable [file name] +The name of the output table. The output table has the same header parameters +and column names as the first table. +.le +.ls colnam1 [string] +The column names in the first table used in the match. If more than one +column is used, columns from the first and second +table are associated with each other based on their position in the list +and not on their names, i.e., the first column name in 'colnam1' is matched +to the first column name passed to 'colnam2', regardless of whether the +names match. +.le +.ls colnam2 [string] +The column names in the second table used in the match. The same number of +column names must be passed to both the 'colnam1' and 'colnam2' parameters. +.le +.ih +EXAMPLES +1. There are two tables, "targets.tab", containing a list of targets +for observation, and "images.tab", containing a list of targets which +have already been observed. Create a table named "new.tab" containing +those targets which have not previously been observed: + +.nf +tt> tdiffer targets.tab images.tab new.tab targetid targetid +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tselect + +Type "help tables opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tdump.hlp b/pkg/utilities/nttools/doc/tdump.hlp new file mode 100644 index 00000000..ef146b58 --- /dev/null +++ b/pkg/utilities/nttools/doc/tdump.hlp @@ -0,0 +1,150 @@ +.help tdump Nov2000 tables +.nj +.ih +NAME +tdump -- Convert an STSDAS table to ASCII format. +.ih +USAGE +tdump table +.ih +DESCRIPTION +This task converts an STSDAS table to ASCII format. +The output does not include row numbers or column names; +use the 'tprint' task for more readable output. + +The two primary uses for 'tdump' are to allow editing that would be +difficult or impossible with 'tedit' (such as global substitutions) +and copying a table over a network to another computer. +For such purposes the table can be dumped to three separate files +(i.e., one containing column definitions, one for header parameters, +and one for table data), +the data may be edited, column data types changed, etc., +and then the 'tcreate' task can be used to reassemble the table +from the three ASCII files. +To prevent loss of information due to truncation, +floating point data are printed using g format with a wide field. +A character value with multiple words is printed with enclosing quotes +to make it clear that it is the value for a single column +and also for compatibility with 'tcreate'. + +All rows and columns of the table are dumped by default, +but ranges of rows and individual columns may be specified. + +The order of printing the data is as follows. +The first column of the first row is printed, +then the second column of the first row is printed, +then the third column of the first row, etc. +If any column contains arrays, +each element of the column array in the current row is printed +before moving on to the next column. +If the printed output is wider than a page (see 'pwidth'), +the output will consist of more than one line per row of the table. +After printing all columns in the first row, +the second row is printed in the same way. +Each row begins with a new line in the output text file. +Note that this can be different from 'tprint', +which prints all rows for those columns that will fit on a page, +then prints all rows for the next set of columns. +.ih +PARAMETERS +.ls table [file name] +The name of the STSDAS table to be dumped. +.le +.ls (cdfile = STDOUT) [file name] +If 'cdfile' is not null (i.e., it is not passed a value of "") +then the column definitions will be written +to an output file having the name passed to 'cdfile'. +(Note: A space is not null.) The column definitions consist of +the column name, data type ("R" for real, +"D" for double, "I" for integer, "B" for boolean, +or "CH*n" for character strings of length n), print format, and units. +For columns of arrays, +the array size is shown in square brackets appended to the data type. +.le +.ls (pfile = STDOUT) [file name] +If 'pfile' is not null (i.e., it is not passed a value of "") +then the header parameters will be written +to an output file with the name passed to 'pfile'. +This file will not be created +if there are no header parameters in the input file. +.le +.ls (datafile = STDOUT) [file name] +If 'datafile' is not null (i.e., it is not passed a value of "") then +the table data will be written +to an output file with the name passed to 'datafile'. +This file will not be created if the input table is empty. +.le +.ls (columns = "") [string] +The names of the columns to be printed. +A null value causes all columns to be printed. +A column template consists of a list +of either column names or column name templates that include wildcards. +Individual column names or templates are separated by commas or white space. +This list of column names can be placed in a list file and 'column' +will then be passed the file name preceded by a "@" character. +If the first non-white character in the column template +is the negation character (either "~" or "!") +the columns NOT named in the template will be printed. + +The 'tlcol' task (with the 'nlist' parameter set to 1) may be used +to generate a list of column names so there is no question about spelling. +This list may be edited to rearrange or delete columns. +.le +.ls (rows = "-") [string] +The range of rows to be printed. +The default of "-" means print all rows. +The first ten rows could be specified as 'rows="1-10"'. +To print the first ten rows and all rows from 900 through +the last (inclusive), use 'rows="1-10,900-"'. +Setting 'rows="1,3,7,23"' will print only those four rows. +It is not an error to specify rows larger than the largest row number; +they will simply be ignored. +Type "help xtools.ranges" for more information. +.le +.ls (pwidth = -1) [integer, min=-1, max=INDEF] +Width of the output for printing the table data. +The default value of -1 means that +checking the width should be disabled, +and each table row will be written to one line in the output file. + +If any column to be printed is wider than 'pwidth', +a warning message will be displayed, +and the data will overflow the page width. +The width of each character column is +increased by two to allow space for a pair of enclosing quotes, +which will be used if the value to be printed includes a blank or tab. +.le +.ih +EXAMPLES +1. Dump the table "junk.tab" to STDOUT: +.nf + + tt> tdump junk.tab cdfile=STDOUT pfile=STDOUT datafile=STDOUT + +.fi +2. Dump "junk.tab", but with the order of the columns rearranged: +.nf + + tt> tlcol junk.tab nlist=1 > colnames.lis + tt> edit colnames.lis + (Rearrange the column names and perhaps delete some of them.) + tt> tdump junk.tab columns=@colnames.lis +.fi + +3. Dump only the first 100 rows of the file "big.fits": + +.nf + tt> tdump big.fits rows="1-100" +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tprint, tlcol, tcreate, ranges + +Type "help tables opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tedit.hlp b/pkg/utilities/nttools/doc/tedit.hlp new file mode 100644 index 00000000..80ff3381 --- /dev/null +++ b/pkg/utilities/nttools/doc/tedit.hlp @@ -0,0 +1,295 @@ +.help tedit Oct94 tables +.ih +NAME +tedit -- Edit a table. +.ih +USAGE +tedit table +.ih +DESCRIPTION +This task is a screen editor for STSDAS tables. You edit a table by +moving the cursor around the screen with the cursor keys and typing in +the new value of the table element. The screen scrolls both sideways +and up and down as you move the cursor, so all elements of the table +can be reached. Other editing commands are entered on the command +line. To switch from table editing mode to command line mode, you +press the EXIT key (usually Control-Z, however, you can change this). After +performing your command, the editor returns to table editing mode, +unless the command exits the editor. The most important commands in +command mode are `help', `exit', and `quit'. The `help' command +displays all the editing key bindings and the command line commands. +The `exit' command will get you out of the editor and automatically +save the edited table. The `quit' command will get you out of the +editor after asking you whether you want to save the table. By +default, the editor modifies a copy instead of the original table, so +if you quit without saving the table, the original table is still +there without any modifications. + +If you try to edit a table that does not exist, the editor will ask if +you want to create the table. If you answer "no", the editor will +exit. If you answer "yes", the editor will ask you for each column +name, type, unit, and print format. When you have finished entering +all the columns, press the return key instead of entering another +column name. The editor will create the table and put you in table +editing mode. + +To add a new, blank line to the end of a table, press the return key +while you are on the last line of the table. You can add blank lines +anywhere in the table with the `add row' command, which will be +described later. + +Some editing commands are entered from the command line in command +mode. To get to command line mode, press the exit key. This key is +bound to Control-Z by default. If you enter a blank line, the editor will +return to table editing mode. Some commands take arguments. They can +be included when the command is entered, or if they are omitted, the +editor will prompt you for their values. If the argument has embedded +blanks, the argument should be enclosed in quotes if passed on the +command line. No quotes should be used if the argument is entered +interactively. When the editor interactively prompts you for a command +argument it will also display a default value for the argument. +Pressing the return key gets the default value. Some command names are +two words long, for example, "add row". Usually the second word is +optional and modifies the meaning of the first, for example "copy +append". If the second word is not optional and you omit it, the +editor will prompt you for it. All command names can be abbreviated to +one or more letters. If the command name is two words long, both words +can be abbreviated to one or more letters. + +The following is a list of the available commands: + +.ls add column +Add a new column to the table with the specified name and data type. +.le +.ls add row +Add new, blank rows after row number . The legal range of is +0 to the number of rows in the table. The number of blank rows to add is +. +.le +.ls copy +Copy the rows between and into the paste buffer. The +current contents of the paste buffer are destroyed before the copy. +The table is not modified by this command. The contents of the paste +buffer can be put back into the table by the 'insert' command. +.le +.ls copy append +Copy the rows between and into the paste buffer. The +current contents of the paste buffer are preserved and the new rows +are inserted after them. +.le +.ls delete +Delete the rows between and . The deleted rows are placed +into the paste buffer and the current contents of the paste buffer are +destroyed. +.le +.ls delete append +Delete the rows between and . The deleted rows are appended +to the paste buffer. +.le +.ls exit +Exit the table editor, saving any changes made to the table. +.le +.ls find +Find the next row in the table which makes true and move +the cursor to that row. The expression has the same syntax as an +expression in a Fortran if statement. The variables in the expression +are column names. For more information on the syntax of the +expression, read the help for 'tselect'. The direction of the search depends +upon previous 'find' commands. By default the search direction is forward; +however, if a "find backwards" command has been executed previously, +searches will be done in a backwards direction until a "find forward" +command is executed. +.le +.ls find forward +Find the next row in the table which makes true and move the +cursor to that row. The search is done in the forwards direction. +.le +.ls find backwards +Find the next row in the table which makes true and move the +cursor to that row. The search is done in the backwards direction. +.le +.ls goto +Move the cursor to and . +.le +.ls help +Display online help information for the table editor. The help includes +a brief description of each command line command and the key bindings +for table editing commands. +.le +.ls insert +Insert the contents of the paste buffer after row number . The +contents of the paste buffer are not changed. +.le +.ls lower +Convert to lower case. Only string columns can be converted. +.le +.ls next +Repeat the previous find command, using the same expression and search +direction that was used with it. +.le +.ls next forward +Repeat the previous find command, changing the search direction to +forwards. +.le +.ls next backwards +Repeat the previous find command, changing the search direction to +backwards. +.le +.ls quit +Exit the table editor. If the table has been changed, the table editor +will ask you whether to save it before exiting. +.le +.ls set +Set a column equal to an expression. If the column is a string column, +the expression must be a constant. If the column is numeric, the +expression can either be a constant or a Fortran-like expression. For +the exact syntax of the expression, see the help file for tcalc. +.le +.ls substitute +Search for and replace text patterns in a column. The syntax for the +target and replacement pattern strings largely follows that used in +the substitute command by the Unix text editors `ed' and `ex'. The +pattern consists of a sequence of ordinary characters, which match +themselves, and meta-characters, which match a set of characters. A +meta-character can be matched as if it were an ordinary character by +preceding it with the escape character, `\'. For example, the escape +character itself is indicated in a pattern by `\\'. The meta-characters +which can be used in the target pattern are: + +.nf +beginning of string ^ end of string $ +white space # escape character \ +ignore case { end ignore case } +begin character class [ end character class ] +not, in char class ^ range, in char class - +one character ? zero or more occurrences * +begin tagged string \( end tagged string \) +.fi + +A set of characters is indicated in the target string by the character +class construct. For example, punctuation could be indicated by +`[,;.!]'. A range of characters contiguous in the underlying +character set can be abbreviated by the range construct. For example, +`[a-z]' matches any lower case character. The complement of a +character set is indicated by making `^' the first character in a +class. For example, `[^0-9]' matches any non-digit. Repetition of a +character or character class is indicated by the following it with the +`*' meta-character. Thus, zero or more occurrences of a lower case +character is indicated by `[a-z]*'. The tagged string meta-characters +have no effect on the match, they only serve to identify portions of +the matched string for the replacement pattern. The meta-characters +which are used in the replacement pattern are the following: + +.nf +entire string & tagged string \n +capitalize \u upper case \U +lower case \L end case conversion \e \E +.fi + +The ditto meta-character, `&', indicates that the entire portion of the +string that was matched by the target pattern. The tag meta-character +indicates that the n-th tagged string. For example, `\1' indicates +the first tagged string and `\2' the second. The remaining +meta-characters affect the case of the output string. The +capitalization meta-character only affects the immediately following +meta-character, but the upper and lower case meta-characters must be +turned off explicitly with `\e' or `\E'. +.le +.ls upper +Convert to upper case. Only string columns can be converted. +.le + +The bindings to the table editing keys are read from the edcap file. +This is the same file which is used to define the key bindings for the +parameter editor and history editor. The edcap file defines key +bindings which resemble those of commonly used text editors. Three +edcap files are distributed with IRAF. They define key bindings which +resemble EDT, Emacs, and vi. These edcap files are located in the 'dev$' +directory and have the extension '.ed'. The appropriate file is chosen +according to the value of the environment variable 'EDITOR'. If you +want to customize the key bindings of the table editor, copy the +appropriate edcap file from the 'dev$' directory to your 'home$' directory +and edit the second column of the file. The table editor searches your +home directory first for the edcap file and if it does not find it, +then it searches the 'dev$' directory. + +The table editor also uses the termcap file to determine the screen +size and the escape sequences used to modify the screen. There are +entries in the termcap file for almost all terminal types. The proper +entry is selected according to the environment variable 'TERMINAL'. To +change your terminal type or the screen size, use the IRAF 'stty' +command. + +The 'tread' task can also be used to view a file in readonly mode. +.ih +PARAMETERS +.ls table [string] +The name of the table to be edited. The editor checks for the +existence of the table and its access mode before editing. If the +table does not exist, the editor will ask whether you want to create +a new table. If you do not have write access to a table you can only +edit it by setting 'rdonly=yes'. +.le +.ls (columns = "") [string] +The names of the columns to be edited. +A null or blank string means edit all columns. +A column template consists of a list of either +column names or column patterns containing the usual pattern matching +meta-characters. The names or patterns are separated by commas or +white space. The list can be placed in a file and the name of the +file preceded by an "@" given in its place. +If the first character in the column template is a bang (!), +all columns NOT named will be displayed. + +The 'tlcol' task (with the 'nlist' parameter set to 1) may be used to generate +a list of +column names so there is no question about spelling. This list may be +edited to rearrange or delete the names, and then the list +file is given preceded by an '@' sign, for example: + +.nf +tt> tedit junk columns=@colnames.lis +.fi +.le +.ls (silent = no) [boolean] +Turn off the bell indicating warning messages? +.le +.ls (rdonly = no) [boolean] +View a table without modifying it? This parameter prevents you from +executing +any command that would modify the file. +.le +.ls (inplace = no) [boolean] +Replace existing table? If 'rdonly' is +set to "yes" the table is always edited in place. +.le +.ih +EXAMPLES +1. Make a copy of the table 'm12b.tab' (if it exists) and edit the copy. +If the table does not exist +then a temporary table is created, and you will be prompted for the +name of the first column to be created. In either case, if you +exit (rather than quitting) the temporary table will be renamed to +'m12b.tab'. + +.nf +tt> tedit m12b +.fi + +2. Display the columns 'SHARP' and 'ROUND' in an existing table. Rows may +be added or deleted, and columns may be added. + +.nf +tt> tedit m12b columns="SHARP,ROUND" +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tread, tprint, tselect, stty + +Type "help tables opt=sys" for a description of the 'tables' package. +.endhelp diff --git a/pkg/utilities/nttools/doc/texpand.hlp b/pkg/utilities/nttools/doc/texpand.hlp new file mode 100644 index 00000000..52fd03e6 --- /dev/null +++ b/pkg/utilities/nttools/doc/texpand.hlp @@ -0,0 +1,159 @@ +.help texpand Dec90 tables +.ih +NAME +texpand -- Expand table rows according to a set of rules. +.ih +USAGE +texpand input output rbase +.ih +DESCRIPTION +This task uses a set of rules to convert each row in the input table +into one or more rows in the output table. Except for these +conversions, the output table is identical to the input table. The set +of rules is contained in a text file specified by the 'rbase' parameter. +Each rule has two parts, the target and +the action. + +Rules are applied in the following ways. The task reads a row +from the input table. It then looks at the target part of each rule in +the rules file in the order that they were placed in the file. If the +input row does not match the target part of any rule, it is written to +the output table without being changed. +Otherwise, the first rule whose target matches the +input row is used to convert the input row. The columns and values +contained in the action part of the rule are used to modify the +input row to produce a new output row. After the new row is produced, the set +of rules is searched again to see if any of the rules can be applied +to the new row. This process continues until no further matches can be +found, at which point the new rows are written to the output table. + +For example, suppose the following rules are contained in the rules +file: +.nf + +SEX = M && NAME = ANY => NAME = Tom || NAME = Dick || NAME = Harry; +SEX = F && NAME = ANY => NAME = Mary || NAME = Jane; +SEX = X => SEX = M || SEX = F; + +.fi +And suppose the input table contains the following information: +.nf + +NAME SEX TITLE +ANY X Astronomer + +.fi +The first two rules impose two conditions, the first on the value of +the 'SEX' column and the second on the value of the 'NAME' column. While +the value of the 'NAME' column matches the conditions in the first two +rules, the value of 'SEX' does not. The third rule only imposes one +condition, which does match the row in the input table. Thus the third +rule of the rule file is applied to the input table and the following +intermediate result is produced: + +.nf + +NAME SEX TITLE +ANY M Astronomer +ANY F Astronomer + +.fi +The rules file is searched again, and now the first rule matches the +first row and the second rule matches the second row. So the following +result is produced when these two rules are applied: +.nf + +NAME SEX TITLE +Tom M Astronomer +Dick M Astronomer +Harry M Astronomer +Mary F Astronomer +Jane F Astronomer + +.fi +The rules file is searched again, and because no matches are found, +the results are written to the output table. + +The above example shows some of the syntax of the rules file. The +target and action parts of a rule are separated by the symbol "=>" and +the entire rule is terminated by a semicolon. Unlike the above +example, a rule need not be contained on a single line; it can be +split among as many lines as desired, since the semicolon marks the +end of the rule. The amount of white space used is also optional, +symbols and identifiers may be run together or separated by blanks, +tabs, and blank lines. Comments may be placed on any line; they begin +with the "#" character and run to the end of the line. The different +conditions in the target part of a rule are separated by the symbol +"&&". Each condition consists of a column name and a column value +separated by an equals sign. The different results in the action part +of a rule are separated by the symbol "||". Each result consists of a +set of column names and values separated by equals signs. If there is +more than one column name and value in the result, the different +name/value pairs are separated by "&&" symbols. An example of a rule +with all these syntax elements is: +.nf + +TARGET = ANY && OBSERVER = ANY => # Two conditions + TARGET=M31 && OBSERVER = HUBBLE || # First result + TARGET='OMEGA CENT' && OBSERVER = STRUVE ; # Second result + +.fi +Notice that in the above example that an identifier containing a blank +can be used if the identifier is enclosed in quotes. Double quotes +could also have been used. Case is significant in an identifier. If a +syntax error is detected in a rules file or a column is named which +does occur in the input table, the task is terminated with a syntax +error. The error message contains the line and line number where the +error was detected and a brief message indicating the type of error. + +This task can also be used to process more than one table by using file +name templates for the 'input' and 'output' parameters instead of file names. +Because processing each table takes a relatively long time, the +parameter 'verbose' can be set to "yes" so that the name of each table +will be displayed when it is processed. +.ih +PARAMETERS +.ls input [file name template] +Name of a table, or list of tables, used as input to the task +.le +.ls output [file name template] +Name of a table, or list of tables, to be produced as output to the task. The +number of input and output tables must be equal. +.le +.ls rbase [file name] +The file containing the rules used to expand the tables. +.le +.ls (debug = "") [file name] +The file containing the debugging output. If the file name is blank or null, +no debugging output is produced. When creating a set of rules, the output +produced by this task is not always what you expect. Turning on the debugging +output prints all the intermediate rule expansions to the designated file +as an aid in debugging the set of rules. +.le +.ls (verbose = no) [boolean] +Display the names of the input and output tables on the terminal screen (i.e., +STDOUT) after each file is processed? +.le +.ih +EXAMPLES +1. Expand the table 'example' into 'example_2' using the rules in +'xrules.txt': + +.nf +tt> texpand example.tab example_2.tab xrules.txt +.fi + +2. Expand a set of fos tables using the rules in 'fosrules.txt': + +.nf +tt> texpand y*.tab y*%%_2%.tab fosrules.txt verbose+ +.fi +.ih +BUGS +The task cannot expand tables with boolean columns. +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +.endhelp diff --git a/pkg/utilities/nttools/doc/thedit.hlp b/pkg/utilities/nttools/doc/thedit.hlp new file mode 100644 index 00000000..9a3b2a2f --- /dev/null +++ b/pkg/utilities/nttools/doc/thedit.hlp @@ -0,0 +1,208 @@ +.help thedit Feb2002 ttools +.nj +.ih +NAME +thedit -- Edit or view keyword values in tables. +.ih +USAGE +thedit table keywords value +.ih +DESCRIPTION +This table header editor can be used to add, delete, edit, +or just print the values of table header keywords. + +Although this task was based on 'hedit', +there are significant differences. +The 'add', 'verify', and 'update' parameters of 'hedit' +are not included in 'thedit'. +If a specified keyword does not already exist, +then it will be added +(equivalent to add=yes in 'hedit'). +If a keyword does not exist, +and the value expression is ".", +a warning will be printed +('hedit' is silent in this case). + +Such parameters as the number of rows or columns in the table +are stored differently in FITS, STSDAS, and text tables. +The following special "keywords" can be used +to reference such information regardless of table type. +These may be used in the 'keywords' parameter when value=".", +or they can be used in the 'value' parameter as part of an expression. + +.nf + i_table string table name (may include extension ID) + i_file string name of the file containing the table + i_ctime string file modification (or creation) time + i_nrows int number of rows in the table + i_ncols int number of columns in the table + i_npar int number of keywords in the table header + i_type string table type +.fi + +'thedit' supports two of the special operands +that are available in 'hedit': "$" and "$I". +When 'value' is an expression, +"$" gives the value of the current keyword. +"$I" is equivalent to "i_table", +the name of the current table. +"$I" can be used as a keyword or as part of an expression. +.ih +PARAMETERS +.ls table [file name template] +A list of tables for which keywords are to be edited or printed. +If 'value' is ".", each table will be opened read-only; +otherwise, each table will be opened read-write. +.le +.ls keywords [string] +One or more keywords, separated by commas and/or blanks, +which are to be added, modified, or printed. +If the value expression (see 'value') is not ".", +any keyword in 'keywords' that is not already present +will be added to the header. + +Wildcards are supported; however, +the "@filename" syntax is not supported. +Do not use wildcard or other special characters +if a keyword is to be added to the header. +.le +.ls value = "." [string] +This is the value to be assigned to each keyword in 'keywords'. +The special value "." means that +the keywords should be printed rather than edited, +and in this case the table will be opened read-only. +If 'value' is not equal to ".", +the same value will be assigned to all the keywords +matching the template 'keywords'. + +In order to set a keyword value to "." or ",", +specify the value as "\." or "\," respectively. +(Note that if given on the command line, +the quotes are required in this case.) Requiring "," to be escaped +was added as protection against accidentally typing "," instead of ".". + +As with 'hedit', +a general expression may be given for 'value' +by enclosing the expression in parentheses. +The expression may include constants and/or keyword names; +it will be evaluated and then assigned to each keyword in 'keywords'. + +Note that if delete = yes, then 'value' will be ignored. +.le +.ls (delete = no) [bool] +If delete = yes, the specified keywords will be deleted. +All the keywords listed in 'keywords' will be deleted, +for each table in 'table'. +.le +.ls (show = yes) [bool] +Print a record of each edit operation? +.le +.ih +EXAMPLES +1. Display all the header keywords (except blank) in "example.tab". + +.nf + tt> thedit example.tab * . +.fi + +2. Display only the special keywords for "timetag.fits[events]". + +.nf + tt> thedit timetag.fits[events] i_* . + + timetag.fits[events],i_table = timetag.fits[events] + timetag.fits[events],i_file = timetag.fits + timetag.fits[events],i_ctime = "Wed 12:07:58 31-May-2000" + timetag.fits[events],i_nrows = 337824 + timetag.fits[events],i_ncols = 6 + timetag.fits[events],i_npar = 58 + timetag.fits[events],i_type = "fits, binary" +.fi + +3. Print all HISTORY keywords in "example.txt". + +.nf + tt> thedit example.txt history . +.fi + +4. Add a new HISTORY keyword to "example.tab". + +.nf + tt> thedit example.tab history \ + "('file name is ' // i_file) // '; number of rows = ' // str (i_nrows)" +.fi + +5. Increment the value of COUNT. + +.nf + tt> thedit example.tab count "($ + 1)" +.fi + +6. Delete all HISTORY and COMMENT keywords in "example.fits[1]". + +.nf + tt> thedit example.fits history,comment delete+ +.fi + +7. Evaluate a simple expression +and assign the result to keyword WAVELEN. +Keywords TCRVL1, TCDLT1, and NELEM +are assumed to be already present in the header. + +.nf + tt> thedit example.fits wavelen "(tcrvl1 + tcdlt1 * nelem/2.)" +.fi + +8. A keyword can be renamed by using a two-step process, +first creating a new keyword with the old value, and then +deleting the old keyword. +Note that while this procedure does copy the value, +the comment will be lost. +(The "k" instruction in 'tupar' can also be used to rename a keyword.) + +.nf + tt> thedit example.tab newkey "(oldkey)" + tt> thedit example.tab oldkey delete+ +.fi + +9. The primary header or an image extension of a FITS file +can also be opened as a table in order to access the keywords. + +.nf + tt> thedit o47s01kdm_raw.fits[0] rootname . + tt> thedit o47s01kdm_flt.fits[1] bunit "COUNTS/S" +.fi + +10. This could have been a big mistake. + +.nf + tt> thedit abc.fits[1] * , + + ERROR: In order to set a keyword value to ',' you must use value='\,' +.fi +.ih +BUGS +Expressions are evaluated using EVEXPR, +which does not support double precision. + +Header lines with keyword = ' ' cannot be displayed. + +The 'value' parameter is of type string, +and 'thedit' interprets the value +to determine what data type to use +when writing the value to the table. +This can fail when a value appears to be a number +but really should be treated as a string. +For example, a date and time could be written as "19940531:11515000". +'thedit' would interpret this as hours and minutes (HH:MMss) +and convert the value to 1994053. + 11515000./60. +A workaround for this case is to use 'tupar' instead of 'thedit'; +use the "pt" instruction, meaning put a keyword of type text. +.ih +REFERENCES +This task was written by Phil Hodge, +based on the 'hedit' task. +.ih +SEE ALSO +hedit, tupar +.endhelp diff --git a/pkg/utilities/nttools/doc/thistogram.hlp b/pkg/utilities/nttools/doc/thistogram.hlp new file mode 100644 index 00000000..f8c0003e --- /dev/null +++ b/pkg/utilities/nttools/doc/thistogram.hlp @@ -0,0 +1,152 @@ +.help thistogram Mar94 tables +.nj +.ih +NAME +thistogram -- Make a histogram of a table column. +.ih +USAGE +thistogram intable outtable column +.ih +DESCRIPTION +This task generates a histogram of the values in a column. +The histogram may be written to STDOUT or to a table. +If there is more than one table in the input list then a separate histogram +is generated for each table. +If there is more than one input table and the histogram of the values +in all the tables combined is needed, then the tables should first be +merged using the 'tmerge' task with the 'option' parameter set to "append". + +If x1 and x2 are the lower and upper limits of a particular bin, +a value X will be included in the bin if x1 <= X < x2. +Note that this also applies to the upper limit ('highval') of the last bin. + +There are six interrelated parameters +having to do with the number of bins, bin width, and bin locations. +Any number of these may be specified as long as the values are consistent. +As a minimum, only one value is required, either 'nbins' or 'dx'. +The task computes what it doesn't have +based on the parameters that were specified, +or based on the minimum and maximum data values +in the table column if necessary. +If the minimum (maximum) column data value is used, +that value will normally be reduced (increased) a bit +before being used as 'lowval' ('highval') +to ensure that the value is included in the range. +The relationships between the parameters is as follows: + +.nf + dx = (highval - lowval) / nbins + dx = (chigh - clow) / (nbins - 1) + clow = lowval + dx / 2 + chigh = highval - dx / 2 +.fi +.ih +PARAMETERS +.ls intable [file name template] +A list of input tables. +A histogram will be generated for one column in the table; +the same column name is used for each table in the list. +The name of the column is specified using the 'column' parameter, +.le +.ls outtable = STDOUT [file name template] +Output tables or STDOUT. +If the value of this parameter is "STDOUT" +then the histogram will be written to the standard output +preceded by a header line (beginning with "#") +that gives the number of rows included in the histogram +and the name of the table. +If 'outtable' is passed a file name, +then the number of names must match the number of file names in 'intable', +and the histogram of each input table +will be written to an output table of the specified name. +.le +.ls column [string] +Column name in input tables that will be used to generate the histogram. +Only the values in the column with this name will be used. +The same column name is used for each input table. +.le +.ls (nbins = 100) [integer, min=1] +Number of bins in the histogram. +Normally either 'nbins' or 'dx' (or both) must be given. +You could also give both 'lowval' and 'clow', +or both 'chigh' and 'highval', +since the bin width can be computed from these. +.le +.ls (lowval = INDEF) [real] +Lower limit for histogram. +Values below 'lowval' will not be used in generating the histogram. +If 'lowval = INDEF', then the minimum value in the table column will be used. +.le +.ls (highval = INDEF) [real] +Upper limit for histogram. +Values equal to or greater than 'highval' will not be used in generating +the histogram. +If 'highval = INDEF', then the maximum value in the table column will be used. +.le +.ls (dx = INDEF) [real] +Bin width. +.le +.ls (clow = INDEF) [real] +Value at the center of the first bin. +.le +.ls (chigh = INDEF) [real] +Value at the center of the last bin. +.le +.ls (rows = -) [string] +Range of rows to use for generating the histogram. +The default "-" means that all rows are used. +(Type "help xtools.ranges" for more information.) +.le +.ls (outcolx = value) [string] +Column name for bin centers. +If the output is written to a table rather than to STDOUT, then 'outcolx' +is the column name containing the bin centers. +This column will be double precision. +.le +.ls (outcoly = counts) [string] +Column name for histogram values. +If the output is written to a table then 'outcoly' is the column name +containing the number of counts in the bin. +This column will be of integer data type. +.le +.ih +EXAMPLES +1. Generate a histogram of the values in the 'flux' column in every table +whose name begins with "hr"; put all the histograms in the ASCII file +'hist.lis'. + +.nf + tt> thistogram hr*.tab STDOUT flux > hist.lis +.fi + +2. Generate the same histograms as in the previous example, but put the +results in tables rather than displaying them on the terminal screen. +One output file is produced for each input table; for example, +the histogram for an input table 'hr465.tab' would be put in 'hr465h.tab'. + +.nf + tt> thistogram hr*.tab hr*%%h%.tab flux +.fi + +3. Plot the histogram of column 'V' in 'bs.tab': + +.nf + tt> thistogram bs STDOUT V | sgraph (crvstyle="pseudohist") +.fi + +4. Plot the same histogram as in the previous example, +but set the spacing between bins to be 0.1. + +.nf + tt> thistogram bs STDOUT V nbins=INDEF dx=0.1 | \\ + >>> sgraph (crvstyle="pseudohist") +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +ranges +.endhelp diff --git a/pkg/utilities/nttools/doc/thselect.hlp b/pkg/utilities/nttools/doc/thselect.hlp new file mode 100644 index 00000000..7cabe98d --- /dev/null +++ b/pkg/utilities/nttools/doc/thselect.hlp @@ -0,0 +1,90 @@ +.help thselect Jul2000 ttools +.nj +.ih +NAME +thselect -- Print table keyword values. +.ih +USAGE +thselect table keywords expr +.ih +DESCRIPTION +This task was based on 'hselect', +and it behaves in a very similar manner, +except that it works on tables rather than images. + +Keyword values will be printed to the standard output, +one line per input table, +with the values separated by tabs. +String values that contain whitespace will be enclosed in quotes. +.ih +PARAMETERS +.ls table [file name template] +A list of tables for which keywords are to be printed. +These will be opened read-only and will not be modified. +.le +.ls keywords [string] +One or more keywords, separated by commas and/or blanks. +The special keywords such as "i_table" +that are supported by 'thedit' can also be used with 'thselect'. + +For each input table, +the values of these keywords in the current input table will be printed, +if 'expr' is a true expression for the current table. +Any keyword that is not found will be silently ignored. + +Wildcards are supported; however, +the "@filename" syntax is not supported. +.le +.ls expr = "yes" [string] +This is a boolean expression +to be evaluated for each table in the list. +The default value may be used to unconditionally print keyword values. + +The expression may include constants and/or keyword names. +.le +.ih +EXAMPLES +1. Compare 'thselect' with 'thedit' for displaying a single keyword value. + +.nf + tt> thselect timetag.fits[events,7] rootname yes + + O57P03030 + + tt> thedit timetag.fits[events,7] rootname . + + timetag.fits[events,7],ROOTNAME = O57P03030 / rootname of the obser + vation set +.fi + +2. Compare i_file with i_table for a FITS table +($I and i_table are equivalent). + +.nf + tt> thselect timetag.fits[events,7] i_file,i_table yes + + timetag.fits timetag.fits[EVENTS,7] +.fi + +3. Find all FITS files with DETECTOR = 'CCD' in the primary header. +Since the primary header of a FITS file can be opened +either as an image or as a table, +either 'hselect' or 'thselect' could be used for this example. + +.nf + tt> thselect *.fits[0] $I "detector == 'CCD'" + + h1v11148o_1dx.fits[0] + h4s13500o_1dx.fits[0] + i1c1615po_1dx.fits[0] +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge, +based on 'hselect'. +.ih +SEE ALSO +hselect, thedit +.endhelp diff --git a/pkg/utilities/nttools/doc/tinfo.hlp b/pkg/utilities/nttools/doc/tinfo.hlp new file mode 100644 index 00000000..4c712fbe --- /dev/null +++ b/pkg/utilities/nttools/doc/tinfo.hlp @@ -0,0 +1,125 @@ +.help tinfo Jun1999 tables +.nj +.ih +NAME +tinfo -- Display information about a table. +.ih +USAGE +tinfo table +.ih +DESCRIPTION +This task is used to display information about a table. +This information includes +such things as the number of rows and columns. +The output is written to STDOUT by default. +The first line of output for each table in the input list is the table +name preceded by a # sign. +The values for the last table in the list are also put into parameters +for the 'tinfo' task so that other tasks in a script may use the values. + +The parameters 'nrows', 'ncols', 'npar', 'rowlen', 'rowused', 'allrows', +'maxpar', 'maxcols', 'tbltype', 'subtype' and 'tblversion' +are output parameters. +Since they are set rather than read by 'tinfo', +any value assigned by the user will be overwritten. +.ih +PARAMETERS +.ls table [file name template] +A list of tables for which size information is to be produced. +.le +.ls (ttout = yes) [boolean] +Display information on the terminal screen as it is being placed into +parameters? Setting 'ttout = no' will cause information to be placed +only into task parameters. +.le +.ls (nrows) [integer] +The number of rows written to the table. +This and all subsequent parameters are output task parameters; +that is, they are written by the 'tinfo' task. +.le +.ls (ncols) [integer] +The number of columns in the table. +.le +.ls (npar) [integer] +The number of header parameters in the table. +.le +.ls (rowlen) [real] +For a row-ordered table, +'rowlen' is the amount of space allocated for each row in the table file. +The unit of 'rowlen' is the size of a single-precision real number. + +This is only relevant for row-ordered STSDAS format tables. +.le +.ls (rowused) [real] +'rowused' is the amount of the row length ('rowlen') +that has actually been used +by the columns that have been defined, +in units of the size of a real number. +For example, if a table contains three columns +with data types integer, real and double precision, +then 'rowused' would be four. +If the table contains only one column of data type short, +then 'rowused' would be 0.5. + +This is only relevant for row-ordered STSDAS format tables. +.le +.ls (allrows) [integer] +The number of allocated rows. +This is relevant only for column-ordered STSDAS format tables. +.le +.ls (maxpar) [integer] +The space allocated for header parameters. +.le +.ls (maxcols) [integer] +The space allocated for column descriptors. +.le +.ls (tbltype) [string] +The table type, currently either "stsdas", "fits" or "text". +"stsdas" is a machine dependent binary format, +the default .tab format. +"fits" means that the table is a TABLE or BINTABLE extension +in a FITS file. +"text" is an ASCII file in tabular format. +See also 'subtype'. +.le +.ls (subtype) [string] +For FITS tables the subtype can be either +"ascii" (a TABLE extension) or "binary" (a BINTABLE extension). +For text tables the subtype can be either +"simple" or "explicit column definitions". +The latter subtype means there are column definition lines in the file, +in the format: "#c column_name datatype print_format units". +A simple text table has column names c1, c2, etc., and no units. +For STSDAS format tables +the subtype will be either "row ordered" or "column ordered", +which indicates the way the elements are stored in the table file. +.le +.ls (tblversion) [integer] +The version code is an integer that identifies the version of +the tables package that created or last modified the table. +For STSDAS tables, the version code is stored in the table file; +for other formats this parameter is just +the current tables version code number. +This number is zero for 'stsdas' and 'tables' versions 1.2.3 and earlier, +the number is one for versions 1.3 through 1.3.3, +the number is two beginning 1995 March 6, +and the number is three beginning 1998 April 14. +.le +.ih +EXAMPLES +1. Get size information about the file 'm87pol.tab', +but do not print the information to STDOUT, +just put the values into parameters. + +.nf + tt> tinfo m87pol ttout=no +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tlcol +.endhelp diff --git a/pkg/utilities/nttools/doc/tintegrate.hlp b/pkg/utilities/nttools/doc/tintegrate.hlp new file mode 100644 index 00000000..9ea9f081 --- /dev/null +++ b/pkg/utilities/nttools/doc/tintegrate.hlp @@ -0,0 +1,97 @@ +.help tintegrate Jan96 tables +.ih +NAME +tintegrate -- Calculate the integral of one table column with +respect to another. +.ih +USAGE +tintegrate table integrand independent +.ih +DESCRIPTION +The program evaluates the integral of the column name passed to +'integrand' with respect to +the column passed to 'independent' using the simple trapezoidal rule. +The column passed to 'independent' must have values +sorted in ascending order. +INDEF values in either column are ignored, and there must be at least +two good points common to both columns. +The result is written to STDOUT and also recorded as a task parameter +'integral'. + +If the 'independent' parameter is null or blank, +the values in the 'integrand' column will simply be added up. +Note that this is not exactly the same as the trapezoidal rule +for integrating over row number. (A row number column +can be created using 'tcalc'.) When integrating over a column +that contains the row numbers, +'tintegrate' adds together all rows except the first and last +with unit weight; +the first and last are included with a weight of one half. +.ih +PARAMETERS +.ls table [file name] +The input table. +.le +.ls integrand [string] +Column name whose contents will be the integrand. +.le +.ls independent [string] +Column name whose contents will be the independent variable; +the values in this column must be increasing with row number. +If 'independent' is null, +then 'tintegrate' will just sum the values in the 'integrand' column. +.le +.ls (integral) [real] +The result returned by the task. +This is an output parameter; it is not directly changed by the user. +.le +.ls (ptsused) [integer] +The number of points used in calculating the integral. +This is also an output parameter and is not specified by the user. +.le +.ih +EXAMPLES +1. Calculate the integral of flux over wavelength, +printing the result to STDOUT +(and also storing it in the 'integral' parameter). + +.nf +tt> tintegrate intab flux lambda + integral= 0.8752311663155779 using 401 points +.fi + +2. Sum the values of flux, rather than integrating over wavelength. + +.nf +tt> tintegrate intab flux "" + integral= 30.32557976245881 using 401 points + +as an alternative: + +tt> tstat intab flux +# civ flux +# nrows mean stddev median min max + 401 0.07562488719 0.171107 -0.0381 -0.72729 0.22527 +tt> =0.07562488719 * 401 +30.32557976319 + +.fi + +3. Integrate the flux over row number. +This is the same as summing the flux except for the first and last rows. + +.nf +tt> tcalc intab row rownum datatype="real" colfmt="%8.1f" +tt> tintegrate intab flux row + integral= 30.34466478228569 using 401 points +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by David Giaretta. +.ih +SEE ALSO +tcalc +tstat +.endhelp diff --git a/pkg/utilities/nttools/doc/tjoin.hlp b/pkg/utilities/nttools/doc/tjoin.hlp new file mode 100644 index 00000000..45d2dcc2 --- /dev/null +++ b/pkg/utilities/nttools/doc/tjoin.hlp @@ -0,0 +1,120 @@ +.help tjoin Apr99 tables +.ih +NAME +tjoin -- Combine two tables based on equal values in common columns +.ih +USAGE +tjoin intable1 intable2 outtable column1 column2 +.ih +DESCRIPTION +This task combines two tables into a new table on the basis of one or +more common columns. Two rows from the input tables are combined to +form a row of the output table whenever the values in the common +columns are equal. If a row in one of the input tables matches several +rows in the other input table, all combinations of the rows are placed +in the output table. Null table elements are never matched. Tables +can be joined on row number as well as on column by setting the column +name to "row". + +This task has three hidden parameters, 'extrarows', 'tolerance', and +'casesens'. By default, if a row in one of the input tables does not +match any row in the other input table, it is not placed in the output +table. However, if the parameter 'extrarows' is set to 'first', rows +in the first table that are unmatched are added to the output table +and if 'extrarows' is set to 'both', unmatched rows from both input +tables are added to the output table. + +The task parameter 'tolerance' is a comma separated list of +values. The number of values should either equal to the number of join +columns or one. If only one value is supplied and there are more than +one join column, the value is used for all columns. If the difference +between two column values is less than or equal to the corresponding +value of 'tolerance', the values are considered equal and their +respective rows are placed in the output table. + +If 'casesens = no', the case of a string is ignored when testing for +equality. 'tolerance' must be set to zero when comparing string or +boolean columns. + +If a value of 'tolerance' is nonzero, the output table will contain the +corresponding join columns from both tables. If a value of +'tolerance' is zero, the output table will contain a single join column, +as both values are identical. If a column name in the first input +table is the same as a column name in the second input table, this +task tries to create a unique name by appending "_1" to the first name +and "_2" to the second name. If the task cannot create a unique name +in this way, it stops with an error. +.ih +PARAMETERS +.ls intable1 [file name] +First input table. +.le +.ls intable2 [file name] +Second input table. +.le +.ls outtable [file name] +Output table. This is the join of the two input tables. +.le +.ls column1 [string] +Names of the common columns in the first table. If there is more than +one column name, the names should be separated by commas. If a column +name is "row", the join is done on row number instead of the value of +a column. This only works if there is not column named "row" in the +table. +.le +.ls column2 [string] +Comma separated list of names of the common columns in the second +table. The number of names must match the number of names in column1. +The name may be "row", in which case the join is done on row number. +.le +.ls (extrarows = "neither") [string, allowed values: neither|first|both] +This parameter controls whether unmatched rows are added to the output +table. If it is set to 'neither', unmatched rows are not added. If it +is set to 'first', unmatched rows from the first table are added. If +it is set to 'both', unmatched rows from both tables are added. When +unmatched rows are added to the output table columns in the output +table derived from the other table have their values left undefined. +.le +.ls (tolerance = "0.0") [string] +Tolerance used in testing for equality between common columns. The +values must be greater than or equal to zero. If there is more than +one common column, this parameter may be a comma separated list of +values. In this case, the number of tolerance values must equal the +number of common columns or be one. If there is only one tolerance +value, the same value is used for all columns. +.le +.ls (casesens = yes) [boolean] +Is case important in testing equality of strings? +If set to "yes", the test for equality is case sensitive. +.le +.ih +EXAMPLES +1. Combine a table of star positions and a table of star magnitudes to create +a star catalog. The star name is not case sensitive: + +.nf +tt> tjoin starpos.tab starmag.tab starcat.tab name name case- +.fi + +2. Create a table of all spectral lines that match a set of reference +wavelengths within 10 angstroms: + +.nf +tt> tjoin spectrum.tab reference.tab lines.tab WAVE WAVE tol=10. +.fi + +3. Combine a phone list with an address list where the name is stored +in two columns, "last" and "first". + +.nf +tt> tjoin phone.tab address.tab output.tab LAST,FIRST LAST,FIRST +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tselect, tproject, tproduct +.endhelp diff --git a/pkg/utilities/nttools/doc/tlcol.hlp b/pkg/utilities/nttools/doc/tlcol.hlp new file mode 100644 index 00000000..c9bd9c94 --- /dev/null +++ b/pkg/utilities/nttools/doc/tlcol.hlp @@ -0,0 +1,75 @@ +.help tlcol May2000 tables +.nj +.ih +NAME +tlcol -- Display column information. +.ih +USAGE +tlcol table +.ih +DESCRIPTION +This task is used to list column information for a table. The output is +written to STDOUT, which may be redirected to a file. There will be one line +of output for each column in the table, and each output line may contain the +column name, data type, print format, and units. +The first line of output for each table in the input list is the table +name preceded by a # sign. + +The output from this task may be used as input to various tasks such +as 'tcreate', 'tprint', and 'tproject'. +.ih +PARAMETERS +.ls table [file name template] +A list of tables for which column info is to be printed. +.le +.ls (nlist = 4) [integer, min=1, max=4] +The number of items to list. +The output will consist of 'nlist' columns, +one line for each column that is defined in the table. +The items listed out are column name (displayed for all 'nlist' values), +data type (displayed if 'nlist' is 2 or higher), +display format (if 'nlist' is 3 or higher), +units (if 'nlist' is 4). +If 'nlist = 1', only the column name will be displayed; +the output list may be edited and used as input to +'tprint', 'tdump,' 'tedit', 'tread', 'tproject', or 'tquery'. +The default of 4 can be used to generate +a column-description file for the 'tcreate' task. + +If a column contains an array of values at each row, +rather than just a single element, +the array size is shown in square brackets appended to the data type. +.le +.ih +EXAMPLES +1. Display the names, data types, print formats, and units of all the +columns in the table "example.tab": + +.nf + tt> tlcol example.tab +.fi + +2. Print (using the 'tprint' task) specific columns: +.nf + + tt> tlcol example.tab nlist=1 >colnames.lis + tt> edit colnames.lis + (Rearrange the column names and perhaps delete some of them.) + tt> tprint example.tab columns=@colnames.lis + +3. Create a new table based on the columns in "example.tab": + + tt> tlcol example.tab nlist=4 >colnames.lis + tt> edit colnames.lis + (Delete or modify some column descriptions and/or add new ones.) + tt> tcreate ex2.tab cdfile=colnames.lis ... +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tinfo, tcreate, tdump +.endhelp diff --git a/pkg/utilities/nttools/doc/tlinear.hlp b/pkg/utilities/nttools/doc/tlinear.hlp new file mode 100644 index 00000000..66817fef --- /dev/null +++ b/pkg/utilities/nttools/doc/tlinear.hlp @@ -0,0 +1,127 @@ +.help tlinear Aug2000 tables +.ih +NAME +tlinear -- Fit a linear function to one or two table columns by linear +regression. +.ih +USAGE +tlinear intable outtable xcol ycol +.ih +DESCRIPTION +This task generates fitted Y values and their residuals in two columns. +These columns may be written to an output table, but cannot be written +to STDOUT--only the fit parameters can be written to STDOUT. +If there is more than one table in the input list then a separate fit +is made for each table. + +When a column of weights is used (see 'wcol'), +the weights will be applied when computing the +coefficients of the fit (a, b), +their standard deviations (siga2, sigb2), +and chi squared (chi2), +where the names in parentheses are the headings in +the output printed to STDOUT. +If any row has a weight that is exactly zero, +that row will not be counted in the "pts in fit" value. +The weights will NOT be used when computing +the RMS of the residuals and mean of the residuals +(residual rms, residual mean); +these are unweighted averages +except that rows with exactly zero weight will not be included. +.ih +PARAMETERS +.ls intable [file name template] +A list of input tables containing the columns to be fit. +A fit will be made of the columns specified by the 'xcol' and 'ycol' +parameters. If more than one file name is passed to 'intable', all of +the files must use the same column names. +.le +.ls outtable = STDOUT [file name template] +File names for creating output files, or STDOUT to send output to the screen. +If the value of this parameter is "STDOUT" then the parameters of the fit will +be written to STDOUT preceded by a header line (beginning with #) in tabular +form. +If 'outtable' is not "STDOUT" then the number of file +names must match the number +of names in 'intable', and the fitted Y values and residuals will be written +to an output table with the specified name. The parameters of the fit will +be written to the table header. +.le +.ls xcol [string] +Column name in the input tables to be fit. +The values in this column will be fit for the X axis. +(The same column name is used for each input table.) If a name is not specified +for the X values then row number is used. The values in the 'xcol' column will +be copied to 'outtable' unless the output is being directed to STDOUT. +.le +.ls ycol [string] +Column name in the input tables containing value to be fit for the Y axis. +(The same column name is used for each input table.) Values in 'ycol' will +be copied to 'outtable' unless 'outtable = STDOUT'. +.le +.ls (wcol) [string] +Column name in 'intable' that contains weight values for X and Y. +(The same column name is used for each input table.) If no column +name is passed to either the 'wcol' or 'scol' parameters, then a weight +of 1. is used. The value of the 'wcol' column is copied to 'outtable' unless +'outtable = STDOUT'. +.le +.ls (scol) [string] +Column in 'intable' containing the standard deviation of X and Y. +The X and Y values are weighted by the values in 'scol' +as the reciprocal of the values squared. (The same column name is used for each +input table.) If no value is passed to 'wcol' or 'scol', then +a weight of 1. is used. This task can accept either a weight value or a +standard deviation value, but not both. If both 'wcol' and 'scol' are +specified, then the weight column (i.e., 'wcol') will be used. +The value in the 'scol' column is written to 'outtable' unless 'outtable' += STDOUT. +.le +.ls (rows = "-") [string] +Range of rows to use for fitting the data. +The default "-" means that all rows are used. +(Type "help xtools.ranges" for more information.) +.le +.ls (outcoly = "yfit") [string] +Column name for fitted Y values. +This parameter is not used if 'outtable' = STDOUT. +This column will be double data type. +.le +.ls (outcolr = "yres") [string] +Name of the column to contain residuals. +This parameter is ignored if 'outtable' = STDOUT. +This column will be of double data type. +.le +.ih +EXAMPLES +1. Fit the values in the "flux" column in every table whose name begins with +"hr"; put all parameters of the fits in the ASCII file "fit.lis". + +.nf + tt> tlinear hr*.tab STDOUT "" flux > fit.lis +.fi + +2. Generate the same fits as in the previous example, but put the +results in tables, one output for each input table. For example, +the fitted Y values and +residuals for an input table named "hr465.tab" would be put in "hr465h.tab". + +.nf + tt> tlinear hr*.tab hr*%%h%.tab "" flux +.fi + +3. Fit the values in the "flux" column as a function of the values in the +"wavelength" column and write all the parameters of the fit to STDOUT. + +.nf + tt> tlinear hr*.tab STDOUT wavelength flux +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Betty Stobie. +.ih +SEE ALSO +ranges +.endhelp diff --git a/pkg/utilities/nttools/doc/tmatch.hlp b/pkg/utilities/nttools/doc/tmatch.hlp new file mode 100644 index 00000000..20b5abe4 --- /dev/null +++ b/pkg/utilities/nttools/doc/tmatch.hlp @@ -0,0 +1,225 @@ +.help tmatch Jan1999 tables +.ih +NAME +tmatch -- Find closest match between rows in two tables +.ih +USAGE +tmatch (input1, input2, output, match1, match2, maxnorm) +.ih +DESCRIPTION +This task combines rows from two tables into one. Rows are combined by +looking at each row in the first table and finding the row in the +second table whose match columns are closest to those in the first. +The distance between two rows is defined in the usual way to be the +square root of the sum of the squares of the difference between the +corresponding match columns. Rows are only written to the output table +if the distance between them is less than the distance specified by +maxnorm. This task converts match column units to degrees for the +purpose of computing the distance if the column units are recognized +angular units (seconds, minutes, degrees, hours, or radians or any +abbreviation of these). If the column units are blank or some +unrecognized string, no conversion is done. Thus, if the match column +is in some recognized angular units, maxnorm should be specified in +degrees. + +Columns named by the parameters 'incol1' and 'incol2' will be copied to +the output table. If these parameters are left blank, all columns will +be copied to the output table. Columns will have the same name in the +output table as in the input table, except that columns with the same +name in both input tables will have the suffix "_1" and "_2" added to +indicate which table they were copied from. + +This task optionally allows you to supply a set of weighting factors +that are multiplied by the difference between corresponding match +columns when computing the distance. These factors can be used to +supply units conversion when column units information is missing from +the input table or as a way to weight information from columns +containing distinct information. If factors are supplied, any column +units information is ignored. If the factors are left bank, they are +ignored and column units information is used to convert to degrees +when possible. + +If the match columns contain spherical coordinates, parameter 'sphere' +should be set to yes so that the distance on a sphere can be computed. +If the match columns do contain spherical units, the first column +should be the longitude column (such as right ascension) and the +second column should be the latitude column (such as declination). +Columns should also be in some recognized angular units, or a +conversion factor should be supplied explicitly. + +The task optionally produces a diagnostic output file if a file name +is supplied to parameter 'diagfile'. The diagnostic file contains the +rows from the first table that were not matched, the cases where +more than one row in the first table matched a single row in the +second table, and the ten matched rows in the with the largest +distance between them. Rows in the diagnostic output are identified by +their table number and row number and optionally by the contents of +the columns specified by the parameters 'nmcol1' and 'nmcol2'. + +This task differs from tjoin in two respects. First tjoin combines +tables on the basis of a single column, while this task can combine +tables based on multiple columns. Second, tjoin places every +combination of rows matching within the specified tolerance in the output +table, while this task only puts the closest match in the output table. +.ih +PARAMETERS +.ls input1 [string] +First input table name. +.le +.ls input2 [string] +Second input table name. +.le +.ls output [string] +Output table name. +.le +.ls match1 [string] +A column template describing columns from the first table used to +match the two tables. A column name template is a comma or whitespace +list of strings. Each string may either be a column name a pattern +containing wildcard characters which matches several column names. This +parameter will also accept the name of a list file (preceded by the +"@" character) containing column names to be matched. +If the first non-white character in the template +is the negation character (either "~" or "!"), +all columns NOT appearing in the list will be matched. +.le +.ls match2 [string] +A column name template describing columns from the second table used +to match the two tables. This parameter follows the same format rules +as 'match1'. The number of columns must equal those in 'match1'. +.le +.ls maxnorm min= 0.0, max=INDEF [real] +The distance between two rows must be less than 'maxnorm' in order for +them to match. Recognized angular units are converted to degrees +before computing the distance. The recognized units are seconds, +minutes, degrees, hours, radians, or any abbreviation of these. +.le +.ls (incol1 = " ") [string] +A column name template describing the columns to be copied from the +first input table to the output table. If this parameter is left blank +(the default) all columns in the first input table will be copied to +the output. +.le +.ls (incol2 = " ") [string] +A column name template describing the columns to be copied from the +second input table to the output table. If this parameter is left +blank (the default) all columns in the second input table will be +copied to the output. +.le +.ls (factor = " ") [string] +A comma or white space separated list of numeric factors multiplied by +the individual column differences when computing the distance between +rows in the first and second tables. If this parameter is left blank +(the default) conversion of angular units to degrees will be +performed, but not other weighting will be performed. If a list of +values is supplied, units conversion will NOT be performed, the +supplied numeric factors will be used instead. +.le +.ls (diagfile = " ") [string] +The name of the diagnostic output file. If the name is left blank (the +default) no diagnostic output is produced. Diagnostic output can be +sent to the terminal by setting this parameter to STDOUT or STDERR. +The diagnostic output contains a list of rows that were not matched, +cases where more than one row in the first table matched a single row +in the second table, and the ten pairs of rows with the largest +distance between them. +.le +.ls (nmcol1 = " ") [string] +A column template describing the columns from the first table that are +printed in the diagnostic output. The table and row number are always +printed, if this parameter is not blank, the specified columns are +also printed. +.le +.ls (nmcol2 = " ") [string] +A column template describing the columns from the second table that are +printed in the diagnostic output. +.le +.ls (sphere = no) [bool] +If this parameter is set to yes, a correction appropriate for +spherical coordinates will be applied to the first column +difference. The correction is the cosine of the average of the two +second column values. In order for this correction to be valid, the +first column must contain the longitude component and the second +column the latitude component. Units should be convertable to degrees +or an explicit conversion factor should be supplied. +.le +.ih +EXAMPLES +1. Two star catalogs are being matched. They both have the following +columns: + +.nf +Name CH*12 %12s "" +RA D %10.1h hours +Dec D %10.0h degrees +V R %7.2f "" +B-V R %7.2f "" +U-B R %7.2f "" +.fi + +To find the best match between the catalogs within a ten arcsecond +radius one would use the following command: + +.nf +tt> tmatch catalog1.tab catalog2.tab match.tab \ +>>> ra,dec ra,dec 0:00:10 sphere+ +.fi + +The search radius can either be supplied in sexagesimal notation, as +above, or in decimal degrees. + +2. Suppose the input catalogs did not contain units information, as +would be the case if they were text files. The units conversion could +then be supplied explicitly through the factor parameter: + +.nf +tt> tmatch catalog1.tab catalog2.tab match.tab \ +>>> ra,dec ra,dec 0:00:10 factor=15,1 sphere+ +.fi + +3. Suppose we want the output table to only contain the name from the +first catalog and get the rest of its information from the second +catalog. This could be done with the following command: + + +.nf +tt> tmatch catalog1.tab catalog2.tab match.tab \ +>>> ra,dec ra,dec 0:00:10 incol1=name sphere+ +.fi + +4. To get diagnostic output from the task, use the following command: + +.nf +tt> tmatch catalog1.tab catalog2.tab match.tab ra,dec ra,dec \ +>>> diag=diag.txt nmcol1=name nmcol2=name 0:00:10 sphere+ +.fi + +The following is a subset of the diagnostic output produced: + +.nf +The following objects matched the same object: +1:163 6601 GEM +1:164 6601 GEM +2:163 6601 GEM + + +The following objects have the largest norms: +Norm = 0.00253 +1:371 2319 SCO +2:371 2319 SCO + +Norm = 0.00247 +1:368 2101 SCO +2:368 2101 SCO +.fi + +The number before the colon is the table number, the number after the +colon is the row number, and the rest of the line is from the name +column. +.ih +REFERENCES +Written by Bernie Simon +.ih +SEE ALSO +tjoin +.endhelp diff --git a/pkg/utilities/nttools/doc/tmerge.hlp b/pkg/utilities/nttools/doc/tmerge.hlp new file mode 100644 index 00000000..301d7802 --- /dev/null +++ b/pkg/utilities/nttools/doc/tmerge.hlp @@ -0,0 +1,231 @@ +.help tmerge Jun1999 tables +.nj +.ih +NAME +tmerge -- Merge two tables, or append one to the other. +.ih +USAGE +tmerge intable outtable option +.ih +DESCRIPTION +This task is used to either merge or append tables, +depending on the option selected by the 'option' parameter. +The data type of each column is defined by +the first table in the input list containing that column. +If subsequent tables use the same column name, +then data are converted to the type defined by the first table. +Problems may occur when numerical data are written to +a boolean column or a narrow character column. + +The "merge" option is normally used for tables containing few, +if any, common columns. +When the user selects "merge", +an output table is created containing as many columns +as there are unique column names in all the input tables. +(But see the description of the 'allcols' parameter.) +The output table will have as many rows as the largest +number of rows in the input tables. +The input tables are read in order, +with all values being placed into the output table. +If different input tables have the same column names +then the first values put into the output table +will be overwritten by the later table values. +For example, if the two input tables both have the column name "X_VAL", +then for each row number, +the values written to the output table +will be taken from the second input table. +See below regarding text tables. + +On the other hand, if the "append" option is selected, all rows of +the first input table are written to the output table, followed by all +rows of the second table, and so on, until all input tables are written +to the output table. +The total number of output rows will be the sum +of the numbers of rows in the input tables. +Columns with the same name in different +input tables will be written into the same output column, but no data +will be overwritten because they are put into different rows. +The "append" option would normally be used for tables that have all +the same columns. + +An input table may have no rows. +Such a table may be used as the first input table +to control the order and definitions of columns in the output table. + +Header parameters are appended, +and parameters with the same keyword name +in different input tables are overwritten in the output file, +except for history and comment keywords. + +Care must be taken with text tables. +It is very likely that you would want +'allcols = yes' if 'option = merge' and +'allcols = no' if 'option = append'. +See the description of the 'allcols' parameter for details. +If the output table is a text file, +the line length may not be longer than 4095 characters, +which is a limitation for any text table. + +Column units are not checked. +If columns with the same name have different units +in two different input tables, +the merged (or appended) data are likely to have mixed units. +In addition, the column definition is taken from the first input table, +but some and perhaps all of the data would come from the second input table, +so the units in the output column definition would not be correct +for those data. +.ih +PARAMETERS +.ls intable [file name template] +Names of the tables to be merged or appended. This parameter will take +either a file name template describing several input tables, and may include +wildcard characters, or it will take the name of a list file preceded by the +"@" character; in the latter case the list file contains a list of file names +with each file name on a separate line. Wildcard characters should not be +used for file name extensions because files other than tables will be +processed, causing the program to crash. For example, if the directory +contains files "table.tab" and "table.lis", the command "tmerge tab*" would +open both files. +.le +.ls outtable [file name] +The name of the output table. +.le +.ls option = "merge" [string] +allowed values: merge | append + +Either merge the columns in each row of each input table--overwriting +previous values--or append files to each other. +See also 'allcols' below. +(These options are discussed in greater detail in the DESCRIPTION section.) +.le +.ls (allcols = yes) [boolean] +Define output table columns using columns from +all input tables? + +If 'allcols = no', the output table will contain +only those columns defined in the first input table. +If 'allcols = yes', the output table will contain +all columns from all input tables. +If 'option = merge', then it is likely that 'allcols' should be set to yes. + +For input tables that are simple text tables +(i.e. that do not contain explicit column definitions), +the 'allcols' parameter serves an additional function. +When 'allcols = yes' the name of each column +in a simple text table is changed +to be "c" followed by the column number in the output table. +This is intended to make the column names unique +in order to allow merging text tables +without having the columns overwrite previously written columns. +Since the column names in simple text tables are just c1, c2, etc., +columns would overwrite previously written columns in the output +if the names were not modified. +If all input tables are simple text tables, +and the output is also a text table, +the new names will be discarded, +so the net effect of this scheme is just to preserve all input data. +If the output is a binary table, however, +the modified column names will be retained. +If the modified column names turn out not to be unique, +a warning message will be printed. +.le +.ls (tbltype = "default") [string, allowed values: default | row | +column | text] + +This parameter specifies the table type. +Setting 'tbltype' to "row" or "column" results in an stsdas binary table, +the contents of which may be either row ordered or column ordered; +row order is recommended. +You can also specify that the output be a text table. +The default ('tbltype = "default"') means that the type of the output table +will be taken from the first input table. + +If the extension of the output file name is ".fits" or ".??f", +the table to be created will be a BINTABLE extension in a FITS file, +regardless of how 'tbltype' is set. +.le +.ls (allrows = 100) [integer, min=1, max=INDEF] +The number of rows to allocate. +This parameter is only used for column-ordered tables +(specified by the 'tbltype' parameter). +The 'allrows' parameter is the minimum number of rows an output +table will contain. +If the number of rows required by the input tables +is greater than 'allrows' then the number of rows in the output table will +be greater than 'allrows'. +If 'option = merge', then the total number of rows will be +the larger of 'allrows' or the number of rows in the largest table. +If 'option = append', the total rows in the output table will be the larger +of 'allrows' or the total number of rows in all input tables. +.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 table +(specified by the 'tbltype' parameter). +The default value of zero is normally appropriate, +but if you expect to define additional columns in the output table +at a later time +then you can allocate the necessary space +by specifying a value for 'extracol'. +One unit of space is taken by each single-precision real value, +integer value, or boolean value. +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 +.nf +1. Suppose you have the following two tables. + +tbl1.tab: + one two three + --- --- ----- + 1 -17 alpha + 2 -19 beta + 3 -23 gamma + +tbl2.tab: + one three four + --- ----- ---- + 27 beta 3.14 + 28 delta 2.72 + +then the statement + + cl> tmerge tbl1,tbl2 mrg merge + +would create the following output table: + +mrg.tab: + one two three four + --- --- ----- ---- + 27 -17 beta 3.14 + 28 -19 delta 2.72 + 3 -23 gamma INDEF + +while the statement + + cl> tmerge tbl1,tbl2 app append + +would create the following table: + +app.tab: + one two three four + --- --- ----- ---- + 1 -17 alpha INDEF + 2 -19 beta INDEF + 3 -23 gamma INDEF + 27 INDEF beta 3.14 + 28 INDEF delta 2.72 +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tselect, tproject, and proto.joinlines for text files +.endhelp diff --git a/pkg/utilities/nttools/doc/tprint.hlp b/pkg/utilities/nttools/doc/tprint.hlp new file mode 100644 index 00000000..47690159 --- /dev/null +++ b/pkg/utilities/nttools/doc/tprint.hlp @@ -0,0 +1,276 @@ +.help tprint Aug1999 tables +.nj +.ih +NAME +tprint -- Convert an STSDAS table to a readable ASCII file. +.ih +USAGE +tprint table +.ih +DESCRIPTION +This task is similar to the 'tdump' task in that it takes an STSDAS +table and produces a file in ASCII format; +however, this task offers more control over the appearance +of the final product and better prepares it for printing. +Formatting options are available +to control the width and length of a page, +and to produce the output in HTML, TeX or LaTeX format. + +By default, all rows and columns in the input tables will be printed, +but the 'rows' and 'columns' parameters can be used +to limit the range of rows and columns, respectively, that will be used. +When using the TeX or LaTeX options, +the number of output columns is limited to 52. +For the HTML option, +all the rows and columns that are to be printed +will be written to one HTML table, +rather than broken into pages. +There is no limit to the number of columns in ASCII format; +however, if the aggregate column width exceeds the page width +the output will be produced in sections +with columns kept together on a page--lines will not wrap. +If different columns for each row are printed on separate pages, +the row number will appear on each page, if 'showrow = yes'. + +The output will be printed to the standard output. +.ih +PARAMETERS +.ls table [file name template] +The file names of tables to be printed. +This parameter will accept a general file name template, +containing wildcard characters, +individual file names with each file name separated by a comma, +or the name of a list file (preceded by the "@" character) +containing the file names of all tables to be processed. +If more than one table is to be processed, +a blank line will be printed between tables. +.le +.ls (prparam = no) [boolean] +Should the header parameters be printed? +.le +.ls (prdata = yes) [boolean] +Should the table data be printed? +.le +.ls (pwidth = 80) [integer, min=40, max=INDEF] +If the output is redirected, +'pwidth' specifies the width of the output page; +otherwise, the screen size is taken from the environment variable 'ttyncols'. +Columns that are too wide to fit within this page size +(allowing also for the row number) will be truncated. + +This parameter is not used if option = "html". +.le +.ls (plength = 0) [integer, min=0, max=INDEF] +Lines of data per page. +This is the number of rows from the table to be printed on each page; +it does not include the line of column names. +It does, however, include any blank lines inserted in the data +because the user specified a value for 'lgroup'. +The default of zero gives no page breaks. + +This parameter is not used if option = "html". + +If the 'sp_col' parameter is not null +or if the 'lgroup' parameter is greater than zero, +the blank lines between groups are included in the count of lines per page. +Thus 'lgroup = 50' and 'plength = 51' would be consistent +and would give the same result as 'lgroup = 0', 'plength = 50'. +.le +.ls (showrow = yes) [boolean] +Print the number of each row? + +If more than one page is needed in order to print all the columns specified, +then the row numbers will be printed on each page. +If 'showrow = no' then row numbers are not printed. +.le +.ls (orig_row = yes) [boolean] +Print row numbers of the underlying table? + +This parameter only has an effect if a row selector expression +was included with the table name, +in which case the table appears to have fewer rows +than are actually present in the underlying table +(the complete table, including all rows). +When 'orig_row' is yes, the default, +the row numbers printed are those in the underlying table; +when 'orig_row' is no, +the selected rows are numbered sequentially starting with one, +as if those were the only rows in the table. +.le +.ls (showhdr = yes) [boolean] +Print header information? + +The table name, date of last modification, +and column names are printed only if 'showhdr = yes'. +If the 'option' parameter (see below) is set to either "latex" or "tex", +then 'showhdr' will affect the printing of +the default macro definitions for column separators +and the end-of-line string as well as the begin-table string +(i.e., "\begin{tabular}..." or "\halign..."). +.le +.ls (showunits = yes) [boolean] +Print the units for each column? If 'showunits = yes' +then the column units will be printed on the line below the column names. +.le +.ls (columns = "") [string] +The names of the columns to be printed. +An alternative way to do this +is to use a column selector with the table name +(type "help selectors" for more information). + +A null or blank string means print all columns. +This parameter is a column template--that is, +either a list of column names +or a template that can contain wildcard characters. +The column names should be separated by commas or white space. +The list of column names can be placed in a file +and the name of the file preceded by "@" passed to 'columns'. +If the first character in the column template +is the negation character (either "~" or "!"), +all columns NOT named will be printed. + +If you want to use a list file for this parameter, +the 'tlcol' task can be used to make the list +(be sure to set the 'nlist' parameter to 1). +Using the 'tlcol' task can eliminate potential problems +caused by incorrect spelling. +The list produced by 'tlcol' can also be edited to +rearrange column names (to change the order for printing) +or to delete unwanted columns. +.le +.ls (rows = "-") [string] +The range of rows which are to be printed. +An alternative way to do this +is to use a row selector with the table name +(type "help selectors" for more information). + +This parameter takes a character string +defining either specific rows to be printed, +a range of rows, or upper or lower limits on row numbers. +The default value "-" means print all rows. +The first ten rows could be specified as rows="1-10" or just rows="-10". +To print the first ten rows +and all rows from 900 through the last (inclusive), use rows="-10,900-". +Setting rows="1,3,7,23" will print only those four rows. +It is not an error to specify rows larger than the largest row number; +excess row numbers will simply be ignored. +(For more information type "help ranges".) +.le +.ls (option = "plain") [string, allowed values: plain | html | latex | tex] +The format in which output will be produced. +If option = "plain", the output will be ordinary ASCII text which may +be read or printed directly. +(See also the 'align' parameter, below.) + +If option = "html", +the output will be formatted with HTML tags, +and the output should be redirected to a file having the extension ".html". + +If option = "latex", +the output will be formatted for use as input to LaTeX, +and if option = "tex", +the output will be formatted for use as input to TeX. +In these two cases the output should be redirected to a file having +the extension ".tex". +Each value in each row will be preceded by a column-separator of the +form "\cola" through "\colz", "\colA" through "\colZ". +(Yes, there +is a limit of 52 columns to be printed on one page.) If the row number +is printed (i.e., by using the 'showrow' parameter) it will +be preceded by the string "\colzero"; the string "\cola" always +precedes the first column from the table. +The default definitions assign "\null" to the first of these +(either "\colzero" or "\cola") and assign "&" to all the rest. +Each row may span several physical rows and is terminated by "\eol", +which has the default definition of "\\" or "\cr" as appropriate. +(See also the description of the parameter 'showhdr'). +.le +.ls (align = yes) [boolean] +Increase column width to align with header? This parameter is only useful +when option = "plain". +If 'align = no', the print format stored in the table for each column +will be used without modification. +This can cause a problem in that some +column names may be longer that the field width for those columns, +consequently, the column names and their values will be misaligned +(this is especially true of subsequent columns). +The default value 'align = yes' will force the columns to be aligned +with the column names regardless of the print format. +Note that you can set 'showhdr = no' but 'align = yes', in which case the +column names will not be printed, but the columns will be spaced the +same as if the names were printed. +.le +.ls (sp_col = "") [string] +This is the name of a column in the table. +If it is specified (non-null), +and if the column is found in the input table, +a blank line will be printed +whenever the value in this column changes +from the value in the preceding row +(or from the preceding element, +if 'sp_col' contains arrays). + +The equality test is made on formatted +values in the column so that the user has more control over spacing +when the data type of 'sp_col' is either real or double. +The print format may be changed using either the 'tedit' or 'tchcol' tasks. +Both 'sp_col' and 'lgroup' may be used together, +which may be useful if the 'sp_col' column does not change very often. +.le +.ls (lgroup = 0) [integer, min=0, max=INDEF] +Print a blank line after each 'lgroup' lines. +If 'lgroup' is greater than zero, +a blank line will be printed between each block of 'lgroup' lines. +These blank lines are included in the count for 'plength' (page length). +For example, if lgroup = 10 and plength = 55, +five groups of ten lines will be produced for each page; +lgroup = 5, plength = 60 will +give ten groups of five lines per page. +The count of lines for these groups is reset at the beginning of each page, +so even if lgroup+1 does not divide into 'plength', +the first group on each page will have 'lgroup' lines. + +If any column that is being printed contains array elements +rather than just scalar values, +grouping by 'lgroup' will be applied to array elements +rather than to row numbers. +If option = "plain" +and the window width (or 'pwidth' if output is redirected) +is not large enough for all the columns, +the spacing can be by row number on some pages +and element number on other pages, +depending on which columns fit on those pages +(i.e. whether the columns contain arrays). +.le +.ih +EXAMPLES +1. Print all tables in the default directory. + +.nf + tt> tprint *.tab +.fi + +2. Print 'junk.tab', but rearrange the columns. + +.nf + tt> tlcol junk nlist=1 >colnames.lis + tt> edit colnames.lis + (Rearrange the column names and perhaps delete some of them.) + tt> tprint junk columns=@colnames.lis +.fi + +3. After using the 'tinfo' task to find that 'big.tab' has 100000 rows, +print the first five and last five rows. + +.nf + tt> tprint big rows="1-5,99996-" +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tdump, ranges +.endhelp diff --git a/pkg/utilities/nttools/doc/tproduct.hlp b/pkg/utilities/nttools/doc/tproduct.hlp new file mode 100644 index 00000000..8b9c2534 --- /dev/null +++ b/pkg/utilities/nttools/doc/tproduct.hlp @@ -0,0 +1,48 @@ +.help tproduct Dec90 tables +.ih +NAME +tproduct -- Form the Cartesian product of two tables. +.ih +USAGE +tproduct intable1 intable2 outtable +.ih +DESCRIPTION +This task creates an output table which is the Cartesian product of two input +tables. This Cartesian product consists of every possible combination of the +rows of the two input tables. Therefore, the number of rows in the output table +is the product of the number of rows in the two input tables. The output table +will contain all the columns from both input tables. If a column name in the +first input table is the same as a column name in the second input table, this +task tries to create a unique name by appending "_1" to the first name and "_2" +to the second name. If the task cannot create a unique name in this way, it +stops with an error. +.ih +PARAMETERS +.ls intable1 [file name] +First input table. +.le +.ls intable2 [file name] +Second input table. +.le +.ls outtable [file name] +Output table containing the possible Cartesian products. +.le +.ih +EXAMPLES +1. Find all persons sharing a phone from a phone list: + +.nf +tt> tproduct phone.tab phone.tab phone.tmp +tt> tselect phone.tmp share.tmp "phone_1 == phone_2 && name_1 < name_2" +tt> tproject share.tmp share.tab phone_2 inc- +tt> delete *.tmp +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tselect, tproject, tjoin +.endhelp diff --git a/pkg/utilities/nttools/doc/tproject.hlp b/pkg/utilities/nttools/doc/tproject.hlp new file mode 100644 index 00000000..7ab88158 --- /dev/null +++ b/pkg/utilities/nttools/doc/tproject.hlp @@ -0,0 +1,79 @@ +.help tproject May1999 tables +.ih +NAME +tproject -- Create a new table from selected columns of an old table. +.ih +USAGE +tproject intable outtable columns +.ih +DESCRIPTION +This task will create a new table containing a subset of the columns in an +old table. The column names are given as a column name template. There is an +optional parameter, 'uniq', that filters out duplicate rows from the +new table. + +If you do not need to eliminate duplicate rows, you can also use tcopy +with a column selector on the input table name. +.ih +PARAMETERS +.ls intable [file name template] +The table(s) from which the columns are to be copied. If input is +redirected, this parameter will ignored and input will be read from +STDIN instead. +.le +.ls outtable [file name template] +The new table(s) containing the copied columns. +The number of output tables must equal the number of input tables. +.le +.ls columns [string] +This is the column template describing those columns that should be +selected from the old table and put in the new table. +A column template consists of a list +of either column names or column name templates that include wildcard +characters. Column names (or templates) are separated by commas or white space. +This parameter will accept the name of a list file (preceded by the "@" +character) containing all of the column names to be selected. +If the first non-white character in the column template +is the negation character (either "~" or "!"), +the new table will contain those columns +whose names DO NOT match rest of the column template. +.le +.ls (uniq = no) [boolean] +Eliminate duplicate rows from the output table? + +If 'unique' is set to "yes", only one of each set of duplicate rows is +included in the output table. All columns in the output table must be +identical for the row to be removed. String comparisons are case +sensitive. Care should be used in setting this option for +large tables, as it significantly increases the running time. +.le +.ih +EXAMPLES +1. Extract the star names, magnitudes, and colors from a catalog: + +.nf +tt> tproject starcat.tab starmag.tab "name,mag,color" +.fi + +2. Exclude the measurement error from a set of spectra. Change the file name +extensions from ".tab" to ".tbl": + +.nf +tt> tproject *.tab *.%tab%tbl% "!error" +.fi + +3. Create a new table of engineering parameters using a column template stored +in the file 'columns.dat'. Eliminate duplicate rows: + +.nf +tt> tproject datalog.tab sublog.tab @columns.dat uniq+ +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tselect, tjoin, tproduct,tcopy +.endhelp diff --git a/pkg/utilities/nttools/doc/tquery.hlp b/pkg/utilities/nttools/doc/tquery.hlp new file mode 100644 index 00000000..61857fd7 --- /dev/null +++ b/pkg/utilities/nttools/doc/tquery.hlp @@ -0,0 +1,115 @@ +.help tquery Jan1999 tables +.ih +NAME +tquery -- Create a new table from selected rows and columns of an old table. +.ih +USAGE +tquery intable outtable expr columns sort +.ih +DESCRIPTION +This task combines the functions of the tasks 'tselect', 'tproject', and +'tsort' to create a more powerful task that can produce a sorted table of +user-selected rows and columns. +It can be used whenever you want to do more than one of these operations +without creating intermediate tables. This task creates a new table +containing a subset of the rows and columns in an old table. The rows in the +new table can be sorted on any column or combination of columns. The select, +project, and sort operations are controlled by the parameters 'expr', +'columns', and 'sort', +respectively. If the value of any of these parameters is a null or +blank string, the corresponding operation is not performed. Otherwise, the rows +are selected whenever the row meets the conditions defined by 'expr'; +columns are +selected by the 'columns' parameter, and rows are +sorted on the columns named in 'sort'. The hidden parameter 'uniq' is used +to eliminate duplicate rows from the output table. The hidden parameter +'ascend' sorts the table in ascending order, and the parameter 'casesens' +specifies whether sort conditions are to be case sensitive. +.ih +PARAMETERS +.ls intable [file name template] +Table(s) from which rows are copied. If input is redirected, this +parameter will ignored and input will be read from STDIN instead. +.le +.ls outtable [file name template] +The new table(s) containing the copied rows. +The number of output tables must equal the number of input tables. +.le +.ls expr [string] +The boolean expression which determines which rows are copied to the new +table. The expression may be placed in a file and the name of the file +preceeded by a '@' can be given in its place. If the expression is null +or blank, all rows are selected. The syntax and method used to define +this boolean expression is explained in detail in the help file for the +'tselect' task (type "help tselect" for more information). +.le +.ls columns [string] +Column template describing the columns that are to be selected +from the old table. A column template consists of a list +of column names, which can include wildcard characters. +The column names, or patterns, are separated by commas or white space. +The list of columns can be placed in a file and then +the name of that file passed to 'columns' (preceded by +the "@" character). If the first non-white character in the template +is the negation character (either "~" or "!"), +the new table will contain those columns +that do NOT match the column template. If the column template +is null or blank, all columns will be selected. +.le +.ls sort [string] +Column template describing the columns to be sorted. The +first column name is the primary sort key with subsequent columns +used to break ties. If this parameter +is null or blank, no sort will be done. +.le +.ls (uniq = no) [boolean] +Make sure all rows are unique in a table? + +If 'unique' is set to "yes", only one of each set of duplicate rows is included +in the output table. All columns in the output table must be identical for +the row to be removed. String comparisons are case sensitive. Care should +be used in setting this option for large tables, as it significantly increases +the running time. +.le +.ls (ascend = yes) [boolean] +Should sorts be performed in ascending order? + +If 'ascend = yes', the table is sorted in ascending order, with the first +row containing the smallest value of the sorted column. Otherwise, the table +is sorted in descending order, with the largest value first. +.le +.ls (casesens = yes) [boolean] +Are sort operations case sensitive? + +If 'casesens = yes', sorts on character columns are case sensitive, with upper +case letters preceding lower case. Otherwise, the sort is not case +sensitive. +.le +.ih +EXAMPLES +1. Extract all binary stars from a catalog; write their names, magnitudes, +and colors to a new table, sorted on magnitude: + +.nf +tt> tquery starcat.tab binary.tab binary name,mag,color mag +.fi + +2. Remove duplicate rows from a set of tables. Otherwise, leave the tables +unchanged. Using file name editing (i.e., the "%" characters to delineate +old strings and new strings), change the file name extensions from ".tab" +to ".tbl". + +.nf +tt> tquery *.tab *.%tab%tbl% "" "" "" uniq+ +.fi +.ih +BUGS +Column names must be set off from operators by blanks in the expression so +that they can be correctly parsed by the expression evaluator. +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tsort, tselect, tproject +.endhelp diff --git a/pkg/utilities/nttools/doc/tread.hlp b/pkg/utilities/nttools/doc/tread.hlp new file mode 100644 index 00000000..871ec66f --- /dev/null +++ b/pkg/utilities/nttools/doc/tread.hlp @@ -0,0 +1,159 @@ +.help tread Aug91 tables +.ih +NAME +tread -- View a table (read only). +.ih +USAGE +tread table +.ih +DESCRIPTION +The 'tread' task is a read-only version of 'tedit', the screen editor for STSDAS +tables. 'tread' lets you view a table by moving the cursor around the +screen with the cursor keys. The screen scrolls both sideways and up +and down as you move the cursor, so all elements of the table can be +reached. Other editing commands are entered on the command line. To +switch from table editing mode to command line mode, you press the +exit key (generally bound to Control-Z, though this can be changed). +When your +command is completed, the editor returns to table editing mode, unless +the command exits the editor. The most important commands in command +mode are `help' and `exit'. The `help' command displays all the +editing key bindings and the command line commands. The `exit' command +will get you out of the editor. + +Some editing commands are entered from the command line in command +mode. To get to command line mode, press the exit key (Control-Z). +If you enter a +blank line, the editor will +return to table editing mode. Some commands take arguments. They can +be included when the command is entered, or if they are omitted, the +editor will prompt you for their values. If the argument has embedded +blanks, the argument should be enclosed in quotes if passed on the +command line. No quotes should be used if the argument is entered +interactively. When the editor interactively prompts you for a command +argument it will also display a default value for the argument. +Pressing the return key gets the default value. Some command names are +two +words long, for example, "find forward". Usually the second word is +optional and modifies the meaning of the first. If the second word is +not optional and you omit it, the editor will prompt you for it. All +command names can be abbreviated to one or more letters. If the +command name is two words long, both words can be abbreviated to one +or more letters. + +The following commands are used by 'tread': +.ls exit +Exit the table editor. +.le +.ls find +Find the next row in the table which makes true and move +the cursor to that row. The expression has the same syntax as an +expression in a Fortran if statement. The variables in the expression +are column names. For more information on the syntax of the +expression, read the help for the 'tselect' task. The direction of the search +depends +upon previous find commands. By default the search direction is forward; +however, if a "find backwards" command has been executed previously, +searches will be done in a backwards direction until a "find forward" +command is executed. +.le +.ls find forward +Find the next row in the table which makes true and move the +cursor to that row. The search is done in the forwards direction. +.le +.ls find backwards +Find the next row in the table which makes true and move the +cursor to that row. The search is done in the backwards direction. +.le +.ls goto +Move the cursor to and . +.le +.ls help +Display online help information for the table editor. The help includes +a brief description of each command line command and the key bindings +for table editing commands. +.le +.ls next +Repeat the previous find command, using the same expression and search +direction that was used with it. +.le +.ls next forward +Repeat the previous find command, changing the search direction to +forwards. +.le +.ls next backwards +Repeat the previous find command, changing the search direction to +backwards. +.le +.ls quit +Exit the table editor. +.le + +The bindings to the table editing keys are read from the edcap file. +This is the file that defines key bindings for the +parameter editor and history editor. The edcap file defines key +bindings that resemble those of commonly used text editors. Three +edcap files are distributed with IRAF. They define key bindings which +resemble EDT, Emacs, and vi. These edcap files are located in the 'dev$' +directory and have the extension '.ed'. The appropriate file is chosen +according to the value of the environment variable 'EDITOR'. If you +want to customize the key bindings of the table editor, copy the +appropriate edcap file from the 'dev$' directory to your 'home$' directory +and edit the second column. The table editor searches your +home directory first for the edcap file and if it does not find it, +searches the 'dev$' directory. + +The table editor also uses the termcap file to determine the screen +size and the escape sequences used to modify the screen. There are +entries in the termcap file for almost all terminal types. The proper +entry is selected according to the environment variable terminal. To +change your terminal type or the screen size, use the IRAF 'stty' +command. + +.ih +PARAMETERS +.ls table [string] +Name of the table to be edited. The editor checks for the +existence of the table and its access mode before editing. The table +must exist in order to edit it with 'tread'. +.le +.ls (columns = "") [string] +Names of the columns to be edited. +A null or blank string means edit all columns. +A column template consists of a list of either +column names or column patterns containing the usual pattern matching +meta-characters. The names or patterns are separated by commas or +white space. The list can be placed in a file and the name of the +file preceded by an "@" character. +If the first character in the column template is a bang (!), +all columns NOT named will be displayed. + +The 'tlcol' task (with the 'nlist' parameter set to 1) may be used to generate a +list of +column names so there is no question about spelling. This list may be +edited to rearrange (or delete) the names, and then pass the list to this task +by preceding the its file name with an "@", for example, + +tt> tedit junk columns=@colnames.lis +.le +.ls (silent = no) [boolean] +Turn off the bell indicating warning messages? +.le +.ih +EXAMPLES +1. Display only the columns 'SHARP' and 'ROUND' from the table 'm12b.tab': + +.nf +tt> tread m12b columns="SHARP,ROUND" +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tedit, tprint, tselect, stty + +Type "help tables opt=sys" for a description of the 'tables' package. +.endhelp diff --git a/pkg/utilities/nttools/doc/trebin.hlp b/pkg/utilities/nttools/doc/trebin.hlp new file mode 100644 index 00000000..293c08ec --- /dev/null +++ b/pkg/utilities/nttools/doc/trebin.hlp @@ -0,0 +1,257 @@ +.help trebin Jul2000 tables +.nj +.ih +NAME +trebin -- Resample tables. +.ih +USAGE +trebin intable outtable column start end step +.ih +DESCRIPTION +This task resamples tables. +The grid on which to interpolate an input table +may be specified either by a table giving explicit values +or by start, end, and step values for uniform spacing. +The column names in the output table +will be the same as in the input table. + +If the independent variable column ('column') +in the input table contains scalar values, +each numeric column in the input table will be rebinned +to the values of the output independent variable. +Character and boolean columns +will not be copied to the output table. +Columns that contain arrays will also not be copied to output. +On the other hand, +if the input independent variable column contains arrays +rather than scalar values, +then each row of the input table will be rebinned individually. +Scalar columns will be copied to output unchanged. +Array columns which have the same length as 'column' +will be rebinned and written to the output table; +if the array size is not the same, +the column will not be copied to output. + +Except for function = "linear", +the output values are obtained by interpolation, not by fitting. +The distinction is important when rebinning to a spacing ('step') +that is significantly coarser than the spacing of the input data. +For functions other than linear, +each interpolated value is obtained as follows. +The values of the input data +nearest the current output independent variable value (X) are selected; +the input data are then interpolated at X +to obtain the value to write to the output table. +For function = "nearest", only one input point is used; +for function = "poly3" or "spline", four input points are used. +This is appropriate for rebinning +to a spacing not much different from the input data. +For resampling noisy data +to a significantly wider spacing than the input data, however, +these options will give very poor results. +In the latter case, function = "linear" (the default) should be used. +This option uses a linear fit to all the data +within an interval of width 'step' centered on each output X value. +If there are fewer than two input points in a given interval, however, +the value is interpolated the same way as is done for the other functions; +that is, the two input points nearest to X are selected, +and the value is interpolated at X +(note that these two points can be outside the 'step' interval). + +A significant limitation to this task is that +there is no option to conserve total counts. +'trebin' averages the data values, +rather than summing the input bins. +What 'trebin' does is appropriate for flux-calibrated spectra, +or for time series data expressed as count rate, +but it would not be correct for data in counts, +or for count rate spectra. +.ih +PARAMETERS +.ls intable [file name template] +List of input tables to be resampled. +.le +.ls outtable [file name template] +Output tables or directory. +The number of output tables must match the number of input tables unless +'outtable' is a directory name. +.le +.ls column [string] +Name of the independent variable column in the input table, +i.e., the column on which the data are being resampled. +The same column name is used for all input tables. +The values in this column must be +either monotonically increasing or decreasing. +INDEF values and trailing 'padvalue' (described below) will be ignored. + +The data type of the column is assumed to be a numeric type. +.le +.ls start [real] +If the independent variable values at which to interpolate the input values +are to be uniformly spaced, +they may be specified using 'start', 'end', and 'step'. +'start' is the first value of the output independent variable. + +See also 'xtable'; +'start', 'end', and 'step' will be ignored if 'xtable' was specified. +.le +.ls end [real] +Last value of the independent variable. +This may be rounded up by a fraction of 'step' to ensure that the entire +range from 'start' to 'end' is included in the output table. +.le +.ls step [real] +Increment in independent variable. +The sign of 'step' is ignored; +internally to 'trebin' the sign will be set to negative +if 'start' is larger than 'end'. + +If 'start' and 'end' are the same, +the output table will contain one row, +and 'step' will only be used for the case of function = "linear". +For other values of 'function', +since the data will be interpolated at just the one point 'start', +the step size will not be needed. +.le +.ls (xtable) [file name template] +The independent variable values at which to interpolate the input values +can either be specified explicitly with 'xtable' +or computed using 'start', 'end', 'step'. +If 'xtable' is specified, +there must either be just one table name, +or the number of names must be the same as +the number of names in 'intable'. +If there is only one 'xtable', +it will be used for all input tables. + +'xtable' must contain only one column. +The name of the column does not matter; +it does not need to be the same as given by 'column'. +If the actual table contains more than one column, +use the column selector syntax to specify which one to use. +The column may contain either scalar values or arrays. +If the column contains arrays, +there must be only one row; +if the actual table contains more than one row, +use the row selector syntax to specify which one to use. + +The data type of the column is assumed to be a numeric type. +.le +.ls (function = "linear") [string, allowed values: nearest | linear | +poly3 | spline] + +Interpolation function. +There must be at least four rows in the input table +for cubic polynomial or cubic spline interpolation. +Two rows are required for linear interpolation, +and only one for nearest-neighbor. + +The "linear" option uses a linear fit, +while all other functions are interpolations +using only the required number of points +nearest the value of the independent variable. + +If an input table does not contain enough rows, +or if a column being interpolated contains INDEF values +so that the total number of values is insufficient for interpolation, +the output column will be entirely INDEF; +if verbose = yes, a message will be printed. +.le +.ls (extrapolate = no) [boolean] +Extrapolate if out of bounds? See 'value' below. +.le +.ls (value = INDEF) [real] +Value to use if out of bounds. +The independent variable values +at which the input table is to be interpolated +may fall outside the range of values +in the independent variable column in the input table. +The value to write to the output table +for out of bounds independent variables depends on +the 'extrapolate' and 'value' parameters. +If 'extrapolate' is yes, then 'value' is ignored, +and the interpolation function is used for extrapolation. +If 'extrapolate' is no, +then 'value' is written to each dependent variable column +for each row that the independent variable +is outside the range of values in the input table. +Note that for columns of type integer or short, +'value' should be within the range of possible values of that type, +and if 'value' contains a fractional part +it will be rounded to the nearest integer. +.le +.ls (padvalue = INDEF) [real] +Trailing INDEF values in the independent variable column +(either in 'intable' or in 'xtable') +will be ignored. +'padvalue' can be used to specify an additional value, +such as zero, +which will also be ignored +if it occurs at the end of an array of independent variable values. +Values will be trimmed off the end of the array +until a value that is neither INDEF nor 'padvalue' is encountered. +.le +.ls (verbose = yes) [boolean] +If verbose = yes, +the input and output table names will be printed as they are processed, +and the names of columns that are not being copied to output +will also be printed. +.le +.ls (Version) [string] +This gives the date of installation of the current version. +.le +.ih +EXAMPLES +1. Resample all the columns in all tables beginning with "hr" so the values +in the "Wavelength" column range from 3000 to 8000 in steps of 10. +The output tables will have the same names, but will be written in the +directory "home$spec" (which should be different from the default directory). + +.nf + tt> trebin hr*.tab "home$spec/" Wavelength 3000. 8000. 10. +.fi + +2. Interpolate the text table "in" at a single point, +where the value in column one is 5, +and print the results on the standard output. + +.nf + tt> trebin in STDOUT c1 5. 5. 0. +.fi + +3. Interpolate the table from example 2 +onto the array of independent variable values +in column "wavelength" at row 37 of "x1d.fits". +As in example 2, +the independent variable in "in" is the first column, "c1". + +.nf + tt> trebin in STDOUT c1 xtable="x1d.fits[r:row=37][c:wavelength]" +.fi +.ih +BUGS +A column which contains an integer bit mask +will be interpolated as if it were an ordinary numeric column, +which is not the correct behavior. + +Sometimes a table contains array columns +where the allocated array size is (or can be) +larger than the number of elements actually used. +In this case, a scalar column might be used +to specify the effective array length. +The array size in the output table +will typically be different from the array size in the input table; +'trebin' will update the allocated array size, +but it will not modify any scalar column that gives the effective array size. +.ih +REFERENCES +This task was written by Phil Hodge. +The following Numerical Recipes subroutines are used by this task: +TUCSPL, TUHUNT, TUIEP3, and TUISPL. +Numerical Recipes was written by W.H. Press, B.P. Flannery, +S.A. Teukolsky, and W.T. Vetterling. +.ih +SEE ALSO +Type "help tables opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tselect.hlp b/pkg/utilities/nttools/doc/tselect.hlp new file mode 100644 index 00000000..56299faa --- /dev/null +++ b/pkg/utilities/nttools/doc/tselect.hlp @@ -0,0 +1,147 @@ +.help tselect Jul92 tables +.ih +NAME +tselect -- Create a new table from selected rows of an old table. +.ih +USAGE +tselect intable outtable expr +.ih +DESCRIPTION +This task creates a new table from a subset of rows in an input table. +The rows are selected on the basis of a boolean expression whose +variables are table column names. If, after substituting the values associated +with a particular row into the column name variables, the expression evaluates +to yes, that row is included in the output table. Boolean operators can be used +in the expression in either their Fortran or SPP forms. The following boolean +operators can be used in the expression: + +.nf +equal .eq. == not equal .ne. != +less than .lt. < less than or equal .le. <= +greater than .gt. > greater than or equal .ge. >= +or .or. || and .and. && +negation .not. ! pattern match ?= +.fi + +The pattern match operator (?=) has no corresponding Fortran form. It 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 meta-characters (i.e., wildcard +characters used in pattern matching). +The meta-characters themselves can be matched by preceeding them with the escape +character (\). +The meta-characters are: + +.nf +beginning of string ^ end of string $ +one character ? zero or more characters * +white space # escape character \ +begin ignoring 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. +Trigonometric functions use degrees, not radians. The following arithmetic +operators and functions can be used in the expression: + +.nf +addition + subtraction - +multiplication * division / +negation - exponentiation ** +concatenation // date difference delta(x,y) +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) +modulo mod(x) minimum min(x,y) +row number row() maximum max(x,y) +nearest integer nint(x) convert to integer int(x) +convert to real real(x) convert to string str(x) +.fi + +The row number function returns an integer value corresponding to the +row number in the table. The date difference function returns a real +value corresponding to the Julian date of the first argument minus the +Julian date of the second argument; the arguments to the data function +must be in CDBS date format: i.e., character strings of the form +YYYYMMDD:HHMMSSCC. Any field after the colon is optional. The last +date field (CC) is hundreths of a second. + +One concept in most databases and in STSDAS tables is the concept of a +null value: a value which indicates that the element is unknown or +non-existent. An element in an STSDAS table is null if it is INDEF in a +numeric column or a zero length string in a text column. Evaluating +expressions involving nulls requires a three valued logic: true, +false, and unknown. Any arithmetic operation on a null element should +return another null and any comparison operation should return an +unknown. Unfortunately, tselect does not implement a true three +valued logic correctly. The code instead evaluates any expression +containing a null element as unknown. Since tselect only returns rows +for which the expression is true, all such rows are excluded from the +output of tselect. This is usually right, but sometimes wrong, as in +the case where two comparisons are joined by an or and one evaluates +to true and the other evaluates to unknown. It also sometimes returns +nonintuitive results, as when checking that a column is not equal to +INDEF. +.ih +PARAMETERS +.ls intable [file name template] +Table(s) from which rows are copied. If input is redirected, this +parameter will ignored and input will be read from STDIN instead. +.le +.ls outtable [file name template] +The new table(s) containing the copied rows. +If more than one input table was used, then the number of output +tables must equal the number of input tables. +.le +.ls expr [string] +The boolean expression which determines which rows are copied to the new +table. The expression may be placed in a list file and the name of the file +passed to this parameter (preceded by the "@" character). +.le +.ih +EXAMPLES +1. Extract all binary stars brighter than fifth magnitude from a catalog: + +.nf +tt> tselect starcat.tab binary.tab "binary && mag <= 5." +.fi + +2. Create a new set of spectra where all measurements with errors greater +than ten percent are excluded. Use file name editing to create new tables +with the extension ".tbl" instead of ".tab": + +.nf +tt> tselect *.tab *.%tab%tbl% "ERROR / (FLUX + .001) < .1" +.fi + +3. Create a table of engineering parameters whose names begin with a digit: + +.nf +tt> tselect datalog.tab sublog.tab "name ?= '^[0-9]'" +.fi + +4. Return all observations in a schedule for the day of Dec 31, 1989: + +.nf +tt> tselect schedule.tab week.tab "abs(delta(date,'19891231:12'))<.5" +.fi +.ih +BUGS +Column names must be set off from operators by blanks in the +expression so that they can be correctly parsed by the expression +evaluator. Expressions involving nulls may evaluate incorrectly, see +above for a discussion. +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tproject, tjoin, tproduct + +Type "help tables opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tsort.hlp b/pkg/utilities/nttools/doc/tsort.hlp new file mode 100644 index 00000000..f07605e4 --- /dev/null +++ b/pkg/utilities/nttools/doc/tsort.hlp @@ -0,0 +1,84 @@ +.help tsort Dec90 tables +.ih +NAME +tsort -- Sort a table on one or more columns. +.ih +USAGE +tsort table columns +.ih +DESCRIPTION +This task sorts an STSDAS-format table. The sort is done in place, so if you want +to keep a copy of the unsorted table, you should copy it with the 'tcopy' +task before you +do the sort. The column, or columns, on which to sort are specified +using the parameter +'columns', which is a list of column names, or column name templates, +separated by +commas. The most significant column name is the first in the list---the +column whose values are sorted; subsequent +columns are used only to break ties. There are two flags, 'ascend' and +'casesens'. The 'ascend' parameter determines whether the sort is done +in ascending or descending order, if +'ascend = yes', the first row in the output table holds the lowest value (if +the sorted column is numeric) or the first string in alphabetic order (if the +sorted column is a character string). If 'casesens = yes', upper +case characters +precede lower case characters. Otherwise, case is not significant +in determining the sort order. When sorting a boolean column, "no" precedes +"yes". Null table elements are always last in the sort, regardless +of the value of 'ascend'. +.ih +PARAMETERS +.ls table [file name template] +Name of the table, or tables, to be sorted in-place. +All tables are sorted on the same column or columns; if more than one table +is specified all tables must have the column(s) specified by the 'columns' +parameter. +.le +.ls columns [string] +Column name or column name template describing columns on which sort will +be performed. A column name template consists of a list of +column names, or column patterns containing wildcard characters. +Individual column names, or templates, are separated by commas or white space. +The list of columns can be placed in a file and the name of the +file passed to 'columns' (preceded by a +"@" character). +.le +.ls (ascend = yes) [boolean] +Sort the table in ascending order? If you want the table sorted in descending +order, set 'ascend = no'. +.le +.ls (casesens = yes) [boolean] +Are sorts on character columns to be case sensitive? If 'casesens = yes', +upper case letters will precede lower case letters. If 'casesens = no', +case is ignored by the sort operation. +.ls +.ih +EXAMPLES +1. Sort a table of star positions by right ascension and declination: + +.nf +tt> tsort starcat.tab ra,dec +.fi + +2. Sort a phone list. Make the sort case insensitive: + +.nf +tt> tsort phone.tab lname,fname case- +.fi + +3. Sort a star catalog so that all binary stars (i.e., a boolean column +named 'binary') are first: + +.nf +tt> tsort starcat.tab binary asc- +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Bernie Simon. +.ih +SEE ALSO +tcopy +.endhelp diff --git a/pkg/utilities/nttools/doc/tstat.hlp b/pkg/utilities/nttools/doc/tstat.hlp new file mode 100644 index 00000000..709ddd57 --- /dev/null +++ b/pkg/utilities/nttools/doc/tstat.hlp @@ -0,0 +1,225 @@ +.help tstat Jan2001 tables +.nj +.ih +NAME +tstat -- Get statistics for a table column. +.ih +USAGE +tstat intable column +.ih +DESCRIPTION +This task gets the mean, standard deviation, median, minimum and maximum +values for a table column. +The output will be written to cl parameters and may also be written either +to the standard output (STDOUT) or to a table. +When more than one table is specified as 'intable', the statistics are +determined for each table separately, not cumulatively. The values +in the cl parameters therefore refer to the last table in the list. + +If an input table contains only one column +(either in fact or due to the use of a column selector with the table name), +then the 'column' parameter is ignored, +and statistics are computed for that one column. +If 'intable' includes more than one table, +the 'column' parameter may be required for some tables +(those with more than one column) but not for others. + +The range of rows to use for statistics +may be restricted either by the 'rows' parameter +or by use of a row selector with the table name. +Both may be used, in which case 'rows' +is interpreted to mean selected row numbers, +rather than rows in the underlying table. +That is, the row selector with the table name is applied first, +then the 'rows' parameter is used to further restrict the rows. + +For a column that contains arrays, +this task reads all elements of all selected rows +and computes statistics on all those elements together. +Typical usage for array columns would be to specify just one row, +but any number of rows may be included, +limited only by memory. + +Lower and upper limits may be set using the parameters 'lowlim' and 'highlim' +such that table values outside that range are not used when computing +the statistics. +Either the lower or upper limit may be set individually. +If there are no values within the range specified +and within the range of rows given by the 'rows' parameter, +then the average, etc, will be printed as INDEF. + +For some tables, one can get statistics on the data in a row +by using 'tdump' and piping the output to 'tstat'. +See the examples for more information. +.ih +PARAMETERS +.ls intable [file name template] +A list of input tables. +Statistics will be obtained for one column, the same name in every table. +If the input is redirected, +this parameter need not be specified; +that is, if there's only one command-line argument, +it will be taken to be the column name. +.le +.ls column [string] +Column in input tables. +The statistics are gotten for the values in the column with this name. +If an input table contains only one column, +this parameter will be ignored, +and you will not even be prompted for a value. +If 'intable' includes more than one table with only one column, +the column name does not need to be the same in each of these tables. +For tables containing more than one column, +this parameter is required, +and the same column name will be used for each table in the list +that contains more than one column. +.le +.ls (outtable = "STDOUT") [string] +Output table, STDOUT, or null. +If 'outtable' is null ("") then the results will only be written to cl +parameters (see 'nrows', 'mean', 'stddev', 'vmin', 'vmax'). +If 'outtable' is "STDOUT" then the results will be written to +the standard output preceded by a header line (beginning with #) +that gives the name of the table and the name of the column. +If 'outtable' is not "STDOUT" and is not null then it is interpreted as +a table name (just one name), and the statistics for the input tables +will be written to separate rows of the output table. +If the table already exists, +the rows will be appended to what is already there. +The output column names are given by +the parameters 'n_tab', 'n_nam', 'n_nrows', etc. +.le +.ls (lowlim = INDEF) [real] +Values below this are ignored. +.le +.ls (highlim = INDEF) [real] +Values above this are ignored. +.le +.ls (rows = -) [string] +Range of rows to use for statistics. +The default "-" means that all rows are used. +See the help for RANGES in XTOOLS for a description of the syntax. +.le +.ls (n_tab = table) [string] +Column name for name of input table. +This and other parameters that begin with "n_" are only used if the output values are +written to a table. +.le +.ls (n_nam = column) [string] +Column name for name of input column. +This and other parameters that begin with "n_" are only used if the output values are +written to a table. +.le +.ls (n_nrows = nrows) [string] +Column name for number of good rows. +.le +.ls (n_mean = mean) [string] +Column name for mean. +.le +.ls (n_stddev = stddev) [string] +Column name for standard deviation. +.le +.ls (n_median = value) [string] +Column name for median. +.le +.ls (n_min = min) [string] +Column name for minimum. +.le +.ls (n_max = max) [string] +Column name for maximum. +.le +.ls (nrows) [integer] +The number of rows for which the column value was not INDEF and was +within the range 'lowlim' to 'highlim'. +This is a task output parameter. +.le +.ls (mean) [real] +Mean value (of the last table in the input list 'intable'). +This is a task output parameter. +.le +.ls (stddev) [real] +Standard deviation of the values (not of the mean). +This is a task output parameter. +.le +.ls (median) [real] +Median value. +This is a task output parameter. +.le +.ls (vmin) [real] +Minimum. +This is a task output parameter. +.le +.ls (vmax) [real] +Maximum. +This is a task output parameter. +.le +.ih +EXAMPLES +1. Get statistics on column "flux" in all tables, putting the output +(assuming outtable="STDOUT") in the ASCII file 'flux.lis': +.nf + + tt> tstat *.tab flux > flux.lis +.fi + +2. In order to get statistics on the data +in a row rather than a column, +you can use 'tdump' for one row +and specify pwidth to be so small that +each value will be printed on a separate line. +The output of 'tdump' will then be a one-column table +containing the row from the input table, +and 'tstat' can be run on that one-column table. +Since the input is redirected, we don't specify the table name. +Note also that in this case the input contains only one column, +so we don't specify the column name either. +In this example, we get statistics on row 17 of "bs.fits": +.nf + + tt> tdump bs.fits cdfile="" pfile="" \ + >>> row=17 pwidth=15 | tstat +.fi + +3. When the input is redirected and has multiple columns, +the command-line argument should be the column name to use, +not the table name. +The table name in this case will internally be set to "STDIN". +.nf + + tt> dir l+ | tstat c3 +.fi + +4. The statistics on column "flux" in 'hr465.tab' are put in parameters +'tstat.nrows', 'tstat.mean', etc., +and are not written to STDOUT or to a table. +We only include rows for which column V is no larger than 12. +.nf + + tt> tstat "hr465.tab[r:v=:12][c:flux]" outtable="" +.fi + +5. The output statistics are written to a table. The default column name +for the mean value is overridden: +.nf + + tt> tstat hr465.tab flux outtable=hr465s.tab n_mean="mean_flux" +.fi + +6. Get statistics on column "flux" in table 'hr465.tab', but only for +rows 17 through 116, row 271, and row 952: +.nf + + tt> tstat hr465.tab[c:flux] outtable="STDOUT" row="17-116,271,952" +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +thistogram, ranges + +Type "help tables opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/ttranspose.hlp b/pkg/utilities/nttools/doc/ttranspose.hlp new file mode 100644 index 00000000..9a1a7c25 --- /dev/null +++ b/pkg/utilities/nttools/doc/ttranspose.hlp @@ -0,0 +1,139 @@ +.help ttranspose Nov94 tables +.nj +.ih +NAME +ttranspose -- Transpose or flip a table. +.ih +USAGE +ttranspose intable outtable action +.ih +DESCRIPTION +This task can be used to transpose a table +so that input rows become output columns +and input columns become output rows. +Another option is to flip the table horizontally, +that is, the first input column is the last output column. +Finally, the table can be flipped vertically, +i.e., the first input row is the last output row. +Any combination of these operations may be performed. + +If the table is actually transposed +(rather than just flipped horizontally and/or vertically), +the data types of all input columns must be the same. +In addition, if the columns contain arrays rather than scalars, +all the array lengths must be the same. +The data type and array size will be preserved in the output table, +but the column names of the output table will be "c1", "c2", "c3", etc, +with default print format and null units. +Actually, some mixing of data types is permitted. +If some columns are type real and others are double precision, +the output data type will be double precision. +Similarly, short integers will be promoted to integers. +Boolean columns can be mixed with any other data type; +for numeric columns, yes becomes 1 and no becomes 0. +When the columns in the input table are character strings, +different maximum string lengths are permitted, +and the output length will be the maximum of the input lengths. +The restrictions on data type are not imposed on text tables, +which can contain mixed integer, double precision and text columns. + +If the table is only flipped but not transposed, +the above restrictions on data type do not apply, +and the column names, units and print formats will be preserved. +Note that an operation such as "tht" +(which happens to be equivalent to "v") +does not actually transpose the table, +so the data types of the columns need not all be the same. + +The 'tstat' task gives statistics for the values in a column, +so one application of 'ttranspose' is to get statistics on +the values in a row by first transposing the table and then running 'tstat'. + +Text tables with too many rows cannot be transposed +due to the limit of 1024 on the length of each row of a text table. +.ih +PARAMETERS +.ls intable [file name template] +The list of input table names. +.le +.ls outtable [file name template] +The list of output table names. +There must be the same number of input and output names. +If the output is to be written to the standard output, however, +you can use outtable = "STDOUT" even if there several input tables. +.le +.ls action = "t" [string] +This is a string made up of the letters "t", "h", and "v" +which specify the operations to perform on the tables. +"t" means transpose (input rows become output columns), +"h" means flip horizontally (reverse the order of the columns), +and "v" means flip vertically (reverse the order of the rows). +The operations are performed in the order given from left to right. +Any combination of "t", "h", and "v" may be used, +in any order, and the letters may be repeated. + +Operations such as "tt", "hh" or "vv" are valid, +and they result in a simple copy of input to output. + +The symbols "/", "-" and "|" are equivalent to +the letters "t", "h" and "v" respectively. +.le +.ls verbose = yes [boolean] +Print the names of the tables as they are processed? +.le +.ih +EXAMPLES +1. The input is the text file "in", +and the output is to be displayed on the screen. +Each of the three operations ("t", "h", "v") +and some combinations are illustrated. + +.nf + tt> type in + one two three + four five six + seven eight nine + ten eleven twelve + + tt> ttranspose in STDOUT t + in --> STDOUT + one four seven ten + two five eight eleven + three six nine twelve + + tt> ttranspose in STDOUT h + in --> STDOUT + three two one + six five four + nine eight seven + twelve eleven ten + + tt> ttranspose in STDOUT v + in --> STDOUT + ten eleven twelve + seven eight nine + four five six + one two three + + tt> ttranspose in STDOUT hv + in --> STDOUT + twelve eleven ten + nine eight seven + six five four + three two one + + tt> ttranspose in STDOUT th + in --> STDOUT + ten seven four one + eleven eight five two + twelve nine six three +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +Type "help ttools opt=sys" for a description of the 'tables' package. +.endhelp diff --git a/pkg/utilities/nttools/doc/tunits.hlp b/pkg/utilities/nttools/doc/tunits.hlp new file mode 100644 index 00000000..553ebb6e --- /dev/null +++ b/pkg/utilities/nttools/doc/tunits.hlp @@ -0,0 +1,143 @@ +.help tunits Jan99 ttools +.ih +NAME +tunits -- Convert a table column from one set of units to another +.ih +USAGE +tunits table column newunits +.ih +DESCRIPTION +Tunits converts a column in a table from one set of units to +another. It supports both scalar and array columns. You supply the +table and column name and the new units you want the column to be +in. Optionally, you can apply the current column units if the units +string stored in the table is missing or incorrect. Tunits only +supports multiplicative conversions, conversions that involve additive +changes, like Kelvin to Celsius, are not supported. Unit names and +conversions are read from two tables. You can copy these tables and +edit them if you want to add new conversions. + +You can find out the current units for a table column by running +tlcol. If a units conversion is not supported by this task and you +know the conversion formula, you can run tcalc. + +Tunits must parse the unit strings you pass it, which requires that +they follow a certain set of rules. Units can be a simple units name, +such as ergs, or a units name raised to a power, such as meters^2, or +the product or quotient of units names raised to a power, such as +feet/sec or gm*cm/s^2. If two units names are next to each other +without any operator between them, a multiplication is assumed. If a +units name is followed by a number, the units name is assumed to be +raised to that power. + +Powers can also be specified by preceding the unit name with the +string "square", "sq", "cubic", or "cu". For example, "square meter" +is equivalent to "meter^2". + +The operators recognized are: + +.nf +division / or per +multiplication * +exponentiation ^ or ** +.fi + +Division has the lowest priority and exponentiation the highest. This +means ergs/sec*angstrom is interpreted as ergs/(sec*angstrom) and not +(ergs/sec)*angstrom, as it would be in most computer languages. The +default priority can be changed by changed by grouping terms with +parentheses. + +Each set of units can have several synonymous names. These names are +listed in the abbreviations table. Case is not significant in names +and regular plurals (made by adding an "s") are converted to the +singular. Names should contain only alphabetic characters. Blanks, +underscores and digits are not allowed. + +The conversions supported by this task are read from the units +conversion table. The table lists the old and new units and a +conversion factor. Only one conversion is allowed for each set of +units. + +.ih +PARAMETERS +.ls table [file] +The name of the table the conversion is applied to. +.le +.ls column [string] +The column to be converted. Both scalar and array columns are +supported. +.le +.ls newunits [string] +The new set of units for the column. The format of this parameter is +described above. This task writes the new units to the units field in +the table column. +.le +.ls (oldunits = " ") [string] +The units that the table column is currently in. If the value of this +parameter is blank, the units will be read from the table. +.le +.ls (abrevtab = "ttools$tunits/abrev.tab") [file] +A table of alternate names for each unit. This table contains two +columns. The first column is the name of the units and the second +column is the standard abbreviation. Because the default table is an +ascii file, columns are read positionally and not by column names + +Many units have more than one name or abbreviation. Using a standard +abbreviation allows units to be converted to a standard form, which +simplifies calculations. The standard abbreviation is used internally +when computing the conversion factor. Case is not significant in names +and regular plurals (made by adding an "s") are converted to the +singular before looking them up in the table. Names should contain +only alphabetic characters. Blanks, underscores and digits are not +allowed. + +The name of this table is a parameter to allow you to create your own +table of standard abbreviations, with additional units. +.le +.ls (unittab = "ttools$tunits/units.tab") [file] +A table of conversion factors from one set of units into another. +This table contains four columns. The first is the conversion factor, +a double precision number. The second is the units the task tries to +convert from. The third column is the units the task tries to convert +to. The fourth column is contains the boolean variable swap, explained +a little later. + +The table is interpreted as "There are in a ." +For example, "There are 100 centimeters in a meter." The last column, +swap, does not change the sense of the sentence but does change the +direction that the conversion is applied, For example, "60 seconds in +a minute" is actually a conversion from minutes to seconds because +swap is yes. Unit conversions should set swap to yes when the desired +conversion is not an exact value, but its inverse is. Only one +conversion is allowed per unit, which simplifies the program logic +considerably. Conversions should be chosen so that they ultimately +resolve to MKS units. To prevent endless loops conversions from the +fundamental units of MKS are checked for and forbidden. However, the +program does not check for other loops, so be careful when adding new +conversions! + +As in the case of the abbreviation table, the table name is a +parameter to allow you to create your own table with additional unit +conversions. +.le +.ls (verbose = no) [bool] +If you set this parameter to yes, the task will print a message to +STDERR for each units conversion utilized in computing the conversion +factor. +.le +.ih +EXAMPLES +Convert watts to ergs per second. Print the diagnostic messages: + +.nf +tt> tunits source.tab power "ergs/sec" old=watts verb+ +.fi +.ih +REFERENCES +This task was written by Bernie Simon +.ih +SEE ALSO +tlcol, tcalc + +.endhelp diff --git a/pkg/utilities/nttools/doc/tupar.hlp b/pkg/utilities/nttools/doc/tupar.hlp new file mode 100644 index 00000000..3c8d99b3 --- /dev/null +++ b/pkg/utilities/nttools/doc/tupar.hlp @@ -0,0 +1,365 @@ +.help tupar Jun97 tables +.nj +.ih +NAME +tupar -- Edit table header parameters. +.ih +USAGE +tupar table +.ih +DESCRIPTION +This task is an interactive editor that allows the user to modify table +header parameters. +Prompts are written to STDERR rather than +STDOUT so that STDOUT can be redirected to a file. +If STDERR is redirected, no prompts will appear. +Prompting is also turned off if the input is redirected from a file. + +The table to be edited is copied to a temporary table +in the same directory as the original table +(or in tmp$ if the first copy attempt fails), +and the changes are made to that copy. +When you exit 'tupar', +the copy is renamed back to the name of the original table. +If you quit rather than exit, +then the copy is deleted, so the original table will remain unchanged. + +The prompt ":" is used by the task when it is waiting for user input. +At this prompt the user can enter any editor command. +The "e" command (or end of file, e.g. Control-Z) will exit the editor. +The following commands are available: e, q, g, p, d, r, k, t, l. +These commands are interpreted as exit, quit (without saving changes), +get, put, delete, replace, change keyword name, type, and list respectively. +Each of these commands is described in detail below: + +The exit command, specified by "e" or end of file, +will close the file--saving all changes, +and open the next file if more than one file was specified +for the 'table' input parameter. + +The quit command is similar to exit except that changes that were made +to the header parameters will not take effect, +unless 'inplace = yes'. +If changes were made to the table header +you will be prompted for confirmation +unless the command was given followed by "!"; +for example, "q!" or "quit!". + +The type command, specified by "t", and the list command, +specified by "l", +both display header parameters---one header per line of output. +The difference between the two commands is that list will show the parameter +number and type will not. +Entering the command "t" or "l" will produce +a listing of all header parameters. +Optionally, an integer may follow +the command indicating that only a particular parameter is to be displayed. +Two integers following the command indicate a range of parameters. +If a number is specified that is beyond the range of valid headers, +an error message will be displayed. +The output consists of the name of the header parameter, +its data type (indicated by a single letter, +"r" for real, "b" for boolean, "i" for integer, or "d" for double), +and its current value. +If the keyword has an associated comment, +the comment will be displayed following the value. +The following are examples of valid syntax for listing header parameters: +.nf +t +l +t 3 +l 300 310 +.fi + +The get command, indicated by "g", will look for a specific keyword and +display its current value. +Optionally, the data type can be specified +using the letter "r" for real, "i" for integer, "d" for double, or +"b" for boolean. +If no data type is specified, then the type is assumed to be text. +If the data type is specified, +the type immediately follows the "g" command; +for example, typing the command "gd X" will get the value +contained in the header keyword "X" and display it as a double-precision +real value. +If "X" does not exist, no output will be produced. +If the keyword has an associated comment, +the get command displays the comment following the value; +a text string value will be enclosed in quotes +to distinguish the value from the comment. +Examples of valid syntax follow: +.nf +g history +gd coeff0 +gi numpts +.fi + +The put command, specified by "p", will either replace the value of an +existing parameter, +or it will create a new parameter if the specified parameter is not found. +The "p" command is followed on the command line by a keyword +name and the parameter value. +A comment may optionally follow the value. +The "p" command itself should +be followed by a single letter type specifier, "i" for integer, +"r" for real, "d" for double, or "b" for boolean. +If no type is specified, then the data type is assumed to be text. +In order to specify a comment with a parameter of type text, +the parameter value must be enclosed in quotes +in order to distinguish it from the comment. (Keyword names +HISTORY and COMMENT are already comments, +and further comments cannot be added to them.) +Examples of valid put command syntax follow: +.nf +p comment Created for testing. +gd coeff0 +pd coeff0 3.141592653589793 +pi ncoeff 7 number of coefficients +pt fittype chebychev +pt fittype "chebychev" type of fit that these coefficients represent +.fi + +The replace command, specified by "r", works much like the put command +described above; however, it will prompt the user for confirmation before +actually changing any values in the table. +A parameter can be specified by name or by number. +The "r" command will not change a keyword name or a data type, +whereas the "p" command can. +After the command is entered, +the current value of the keyword is displayed and +the editor waits for a new value to be entered by the user. +Pressing the return key indicates that no change is to be made. +Pressing the space bar will blank the current value. +You will then be prompted for +confirmation unless the command was issued as "r!" or the input was +redirected from a file. +The default action is given by the 'delete_default' parameter. + +A range of contiguous parameters can be replaced at one time by giving +the names or numbers of the first and last parameters to be replaced. +This can involve a lot of prompting for confirmation, +especially if several tables are being edited with 'same=yes'. +In this context, "contiguous" means adjacent in the table header. +Thus, when replacing a range by name, +it is not the parameters that fall alphabetically within the limits +that will be replaced +but rather the parameters that are numerically within the limits. +When editing a list of tables with 'same=yes', +the same replacement string is used for each table. +Thus it is essential that there be the same number of parameters in +the range in all tables being edited. +When no replacement value is given (i.e., just hit the return key), +then the current keyword value is not changed, +either in the first table or in subsequent tables. + +Sample replace commands follow: +.nf +r coeff0 +r 17 +r! 17 +r junk dummy +r junk 12 +r 5 12 +.fi + +The delete command, specified by "d", will delete a header parameter by +either name or number. +The editor prompts for confirmation of delete, +unless input is redirected from a file. +The default action is given by the 'delete_default' parameter. +If you do not want to be prompted for confirmation, enter the command as "d!". +If you want to delete a history or comment record other than the first, +you can identify the parameter by number rather than name. + +A range of contiguous parameters can be deleted at one time by giving +the names or numbers of the first and last parameters to be deleted. +As with replacing a range of parameters, +a contiguous block of parameters will be deleted. + +Examples of valid delete commands follow: +.nf +d testflag +d 17 +d! 17 +d junk dummy +d junk 12 +d 5 12 +.fi + +The "k" command changes the name of a keyword +without changing the data type, value, or comment. +Give the current and new keyword names following the "k". +Note that keywords are limited to eight characters. +If the name of a COMMENT or HISTORY keyword is changed, +only the first occurrence of that keyword will be changed. + +Examples of valid change keyword commands follow: +.nf +k history comment +k dummy test +.fi +.ih +PARAMETERS +.ls table [file name template] +A table name or list of table names whose header parameters are to be edited. +Unless 'inplace = yes', +each table will be copied (one at a time) to a temporary table, +and changes are made to the copy until you exit. +This can cause problems if there is not enough disk space for the copy; +however, the 'inplace' parameter can +be set to "yes" so that the tables are opened in-place. +.le +.ls (same = no) [boolean] +Apply the same set of instructions to all tables? + +This is only relevant when more than one table is being edited. +If 'same = no', instructions are processed separately for each table, +with the "e" command used to end processing of a table and open +the next table. + +If 'same = yes', the same instruction set is applied to all tables. +These instructions will be read from STDIN (which may be redirected) +and saved in a local buffer while the first table in the list is open. +For each subsequent table the instructions will be read from the local buffer. +Caution is advised when deleting or replacing parameters, especially by +number; remember that prompting for confirmation is turned off if the +input is redirected or if the instruction is given as "d!" or "r!". + +If 'same = yes' and you quit (rather than exit) from editing the first table, +the behavior of the task depends on whether changes were made before quitting. +If changes were made then the task aborts immediately +without opening the other tables in the input list. +If no change was made then the other tables are processed. +The idea is to allow "g", "t", and "l" commands +and still be able to quit rather than exit, +since nothing was modified. +If changes were made but you quit, +that's interpreted as trying to recover from an error, +so we don't change the first table and we don't continue. +.le +.ls (verbose = yes) [boolean] +Display the name of each table when it is opened? + +If STDOUT is redirected +then these file names will be written to STDERR as well as to STDOUT. +.le +.ls (readonly = no) [boolean] +Prevent changes from being made to the file? + +If 'readonly = yes', then the +table is opened with read only access. This is useful for viewing the +contents of the table while at the same time preventing changes from +being made to it. (Only the "g", "t", and "l" commands are useful in +read only mode). +.le +.ls (inplace = no) [boolean] +Edit the original table in-place? + +By default a copy of the original table is made, +either in the same directory or in tmp$. +This makes it possible to quit without saving changes. +If the table is large, however, +it may be undesirable to make a copy, +so the 'inplace' parameter gives you the option +of editing the original table. +In this case, however, it will not be possible to quit without saving changes. +.le +.ls (quit_default = no) [boolean] +The value of this parameter is the default response to the prompt +for confirmation if you give the quit command. +.le +.ls (delete_default = yes) [boolean] +The value of this parameter is the default response to the prompt +for confirmation for the delete and replace commands. +.le +.ls go_ahead [boolean] +The user does not set this explicitly. +It is the parameter which is actually gotten in response to a prompt. +.le +.ih +EXAMPLES +1. This example reads all history records from all tables in the default +directory and writes them to 'history.lis'. +.nf + +tt> tupar *.tab same=yes verbose=no readonly=yes >history.lis + (The task writes a ":" prompt and waits for input.) +:g history +:q +tt> +.fi + +2. This example illustrates the use of each of the commands when editing +parameters in one table. This kind of interactive use of the task +would not be appropriate when operating on a list of tables unless +the 'same' parameter is set to "no". +.nf + +tt> tupar junk + (The task writes the table name and a ":" prompt and waits for input.) +junk.lis +:g garvage + (The keyword was not found, so nothing was displayed.) +:g garbage +GARBAGE = 3.1416926535 +:pd garbage 3.1415926535 +:p comment yet another comment +:t +GARBAGE d 3.1415926535 +COMMENT t This is the first comment. +PI t 3.1415926535 not an accurate value +COMMENT t yet another comment +:l 3 999 + 3 PI t '3.1415926535' not an accurate value + 4 COMMENT t yet another comment +:g pi +PI = '3.1415926535' not an accurate value +:gd pi +PI = 3.1415926535 not an accurate value +:pd pi 3.14159265358979323846 a more accurate value +:l + 1 GARBAGE d 3.1415926535 + 2 COMMENT t This is the first comment. + 3 PI d 3.141592653589793 a more accurate value + 4 COMMENT t yet another comment +:d garbage +The following parameter is to be deleted: +GARBAGE d 3.1415926535 + ... OK to delete ? (yes): (user hits return) +:d comment +The following parameter is to be deleted: +COMMENT t This is the first comment. + ... OK to delete ? (yes): n (user types n) +:l 4 +parameter out of range; max is 3 +:d 3 +The following parameter is to be deleted: +COMMENT t yet another comment + ... OK to delete ? (yes): (user hits return) +:t +COMMENT t This is the first comment. +PI d 3.141592653589793 a more accurate value +:r 1 +keyword COMMENT, type t; give replacement value: +This is the first comment. (TUPAR writes this & waits) +this is a comment (this line entered by user) +Current parameter and its replacement are: +COMMENT t This is the first comment. +COMMENT t this is a comment + ... OK to replace ? (yes): n (user types n) +no action taken +:q +tt> +.fi +.ih +BUGS +.ih +REFERENCES +This task was written by Phil Hodge. +.ih +SEE ALSO +tprint, tdump, tedit + +Type "help tables opt=sys" for a higher-level description of the 'tables' +package. +.endhelp diff --git a/pkg/utilities/nttools/doc/wcspars.hlp b/pkg/utilities/nttools/doc/wcspars.hlp new file mode 100644 index 00000000..12e2dae1 --- /dev/null +++ b/pkg/utilities/nttools/doc/wcspars.hlp @@ -0,0 +1,184 @@ +.help wcspars Jul93 tables +.ih +NAME +wcspars -- Edit the parameter set that defines a world coordinate +system. +.ih +USAGE +wcspars +.ih +DESCRIPTION +The parameters in this pset are used to define a simple world +coordinate system (WCS) for use by various tasks that require such +information, such as 'wcslab' or 'siaper'. + +Note that this is a pset, not an executable task; it defines a set of +parameters used by other tasks. Invoking the pset by name runs 'eparm' +on the parameter set, allowing the user to modify the parameters. +Alternatively, the parameters may be modified on the command linne by +specifying the pset name and parameter name. For example, you can +type 'wcspars.ctype="ra---tan"'. Parameters may also be edited by +using 'eparam' on the calling task. An example is the task 'wcslab'. By +typing 'eparam wcslab', positioning the cursor on the parameter +'wcspars', and type ':e', the user would then be editing the parameters +in this pset. + +A WCS is used to transform coordinates from one system to another. +For example, for converting from pixel coordinates to celestial +coordinates. To perform such transformations, certain information is +required, such as the type of system. Below is a brief description of +the IRAF implementation of WCS and how to the parameters in this pset +to define a WCS. + +The IRAF implementation defines a transformation from some "logical" +system (e.g., pixel space) to some "world" system (e.g., RA and DEC). +The first piece of information required is the type of world system is +being dealt with. At the moment, there are two general systems +defined: 'linear' which provides a linear mapping from the logical to +world systems, and the celestial projects which provide a mapping from +pixel space to celestial coordinate space. The parameters 'crtype1' and +'ctype2' are used to specify the type of system. If a linear system is +desired, both parameters will have the value "linear". If the TANGENT +plane projection is desired where the first axis represents RA and the +second represents DEC, then the parameters would have the values, +'ctype1 = "ra---tan"', 'ctype2 = "dec--tan"'. There are also a sine +projection (SIN) and arc (ARC) projection provided. + +The scale factor and rotation between the two systems are defined by +a coordinate transformation (CD) matrix. Through matrix +multiplication, the logical coordinates are multiplied by the CD +matrix to produce the world coordinates. The matrix is represented in +the parameters as follows: +.nf + + |---------------| + | cd1_1 cd1_2 | + | | + | cd2_1 cd2_2 | + |---------------| + +.fi +To construct the CD matrix, the following definitions may be used: +.nf + + cd1_1 = Sx * cos(PA) + cd1_2 = -Sy * sin(PA) + cd2_1 = Sx * sin(PA) + cd2_2 = Sy * cos(PA) + +.fi +where Sx and Sy are the scale factors from the logical to world +systems and PA is the angle of rotation between the two systems +(positive rotation is counterclockwise). + +There is a special case for the transformation to RA and DEC. Since RA +increases "to the left", opposite of standard convention, -1 needs +to be multiplied through the CD matrix for the first axis. This +results in the formulas below: +.nf + + cd1_1 = -Sx * cos(PA) + cd1_2 = Sy * sin(PA) + cd2_1 = Sx * sin(PA) + cd2_2 = Sy * cos(PA) + +.fi + +Finally, the origins of the logical and world systems must be defined. +The parameters 'crpix1' and 'crpix2' define the coordinate in the logical +space that corresponds to the coordinate in world space defined by the +parameters 'crval1' and 'crval2'. Quite simply, the coordinate (crpix1, +crpix2) in the logical space, when transformed to the world space, +would be the coordinate (crval1, crval2). + +The last set of parameters, 'log_x1', 'log_x2', 'log_y1', 'log_y2', define a +region in the logical space over which the transformation is valid. +.ih +PARAMETERS +.ls (crtype1 = "linear") [string] +The system type of the first axis. Possible values depend on what +transformations have been implemented in the IRAF system. To date the +following values represent valid transformations: linear, xxx--tan, +xxx-sin, xxx-arc (where xxx is either "ra-" or "dec"). Note that if any +of the celestial transformations are used, the "ra" must appear in one +of 'crtype1' or 'crtype2' and "dec" must appear in the other parameter. +.le +.ls (crtype2 = "linear") [string] +The system type of the second axis. See above for values. +.le +.ls (crpix1 = 0.) [real] +The X coordinate of the reference point in logical space that +corresponds to the reference point in the world space. +.le +.ls (crpix2 = 0.) [real] +The Y coordinate of the reference point in logical space that +corresponds to the reference point in the world space. +.le +.ls (crval1 = 0.) [real] +The X coordinate of the reference point in world space that +corresponds to the reference point in the logical space. +.le +.ls (crval2 = 0.) [real] +The Y coordinate of the reference point in world space that +corresponds to the reference point in the logical space. +.le +.ls (cd1_1 = 1.) [real] +Entry in the CD matrix. Usually has the value , +or for RA and DEC systems, <-xscale * cos(angle)>. +.le +.ls (cd1_2 = 0.) [real] +Entry in the CD matrix. Usually has the value <-yscale * sin(angle)>, +or for RA and DEC systems, . +.le +.ls (cd2_1 = 0.) [real] +Entry in the CD matrix. Usually has the value . +.le +.ls (cd2_2 = 1.) [real] +Entry in the CD matrix. Usually has the value . +.le +.ls (log_x1 = 0.) [real] +The lower X axis extent in logical space over which the transformation +is valid. +.le +.ls (log_x2 = 0.) [real] +The upper X axis extent in logical space over which the transformation +is valid. +.le +.ls (log_y1 = 0.) [real] +The lower Y axis extent in logical space over which the transformation +is valid. +.le +.ls (log_y2 = 0.) [real] +The upper Y axis extent in logical space over which the transformation +is valid. +.le +.ih +EXAMPLES +1. The following example +is for an image that does not contain any WCS information. +The image is 512x512 pixels, where the pixels are approximately 1/10th +an arcsecond in size, whose center pixel is located at 9h 22m 30.5s +and -15o 5m 42s and is rotated 30 degrees towards the west: +.nf + + ctype1 = 'ra---tan' + ctype2 = 'dec--tan' + crpix1 = 256.0 + crpix2 = 256.0 + crval1 = 140.62708 + crval2 = -15.09500 + cd1_1 = -2.405626e-5 + cd1_2 = 1.388889e-5 + cd2_1 = 1.388889e-5 + cd2_2 = 2.405626e-5 + log_x1 = 1. + log_x2 = 512. + log_y1 = 1. + log_y2 = 512. + +.fi +.ih +BUGS +.ih +SEE ALSO +.endhelp diff --git a/pkg/utilities/nttools/doc/wlpars.hlp b/pkg/utilities/nttools/doc/wlpars.hlp new file mode 100644 index 00000000..08f987a9 --- /dev/null +++ b/pkg/utilities/nttools/doc/wlpars.hlp @@ -0,0 +1,440 @@ +.help wlpars Jul93 tables +.ih +NAME +wlpars -- Edit the parameter set that determines how WCS labeling +appears. +.ih +USAGE +wlpars +.ih +DESCRIPTION +These parameters determine the characteristics of plots that are +produced by the various tasks that use the World Coordinate System +(WCS) information from image data. Various +parameters can be set in 'wlpars', including those controlling +the appearance of features such as +major and minor tick marks, the use of grid lines, etc. + +Note that this is a pset, not an executable task; it defines a set of +parameters used by other tasks. Invoking the pset by name runs +`eparam' on the parameter set, allowing you to modify the +parameters. Alternatively, the parameters may be modified on the +command line by specifying the pset name and parameter name. For +example, the user can type "wlpars.major_grid=no" to not draw lines +for the major grid, but to include tick marks. +Parameters can also be edited by +using `eparam' on the calling task (e.g., by typing "eparam wcslab"), +in which case, `wlpars' will appear as one of the task parameters; the +`wlpars' parameters may then be edited by positioning the cursor on +the line containing the pset name and typing ":e". After editing the +pset parameters, press Control-Z to return to the main task parameter +menu. + +Below is a list of areas that explain in more detail what the +parameters in this pset accomplish. This explanation also occurs in +the help for 'wcslab'. + +.ls Axis Specification +For all linear transformations axis 1 and axis 2 specify which axis in +the image WCS is being referred to. +For example in a 2-dimensional image, the FITS image header keywords +CTYPE1, CRPIX1, CRVAL1, CDELT1, +CD1_1, and CD1_2 define the world coordinate transformation for axis 1. +Similarly the FITS image header keywords +CTYPE2, CRPIX2, CRVAL2, CDELT2, +CD2_1, CD2_2, define the world coordinate transformation for axis 2. + +THIS RULE DOES NOT APPLY TO THE CELESTIAL plane projection WCSs. +For this type of WCS, axis 1 and axis 2 +always refer to right ascension and declination respectively, +and 'wcslab' assumes that all axis 1 parameters refer to right +ascension and all axis 2 parameters refer to declination, regardless of +which axis in the image WCS actually specifies right ascension and declination. + +.le +.ls Grid Drawing +There are two types of grid lines and tick marks, "major" and +"minor". The major grid lines and tick marks are the lines or ticks +that will be labeled. The minor grid lines or tick marks are plotted +between the major marks. Whether lines or tick marks are drawn is +determined by the boolean parameters 'major_grid' and 'minor_grid'. +If these are set to "yes", lines are drawn; if "no", +tick marks are drawn. How the lines +appear is controlled by the parameters 'major_line' and 'minor_line'. + +The spacing of minor marks is controlled by the parameters 'axis1_minor' +and 'axis2_minor'. These parameters specify the number of minor marks +that will appear between the major marks along the axis 1 +and axis 2 axes. + +Spacing of major marks is more complicated. 'wcslab' tries to +present major marks only along "significant values" in the +coordinate system. For example, if the graph spans several hours of +right ascension, the interval between major marks will generally be an +hour and the major marks will appear at whole hours within the graph. +If the values chosen by 'wcslab' are unacceptable, the interval and range can +be modified by the parameters 'axis1_int', 'axis1_beg', +'axis1_end' for the 'axis 1', and 'axis2_int', 'axis2_beg', +and 'axis2_end' for 'axis 2'. All three parameters must be specified for +each axis in order for the new values to take affect + +.le +.ls Graph Appearance +'wcslab' supports three types of graph: normal, polar, and near_polar. + +A normal graph is the usual Cartesian graph where lines of constant +axis 1 or 2 values cross at least two different sides of the graph. +'wcslab' will, by default, plot a normal type graph for any image that +meets the following criteria: 1) +has no defined WCS, 2) has a linear WCS, and 3) where the sky +projection WCS approximates a Cartesian system. + +A polar graph is one in which the north or south pole of the +coordinate system actually appears on the graph. +Lines of constant declination are no longer approximately +straight lines, but are circles that may not intersect any +of the edges of the graph. In this type of graph, axis 1 values +are labeled all the way around the graph. +Axis 2 values are labeled within the graph +next to each circle. An attempt is made to label as many circles as +possible. If you don't like the labeling defaults, +the parameters, 'axis2_dir' and 'justify' can be modified +to control how the labeling is done. +The parameter 'axis2_dir' specifies along which axis 1 value the +axis 2 labels should be written; 'justify' specifies the side of +the value on which the label will appear. + +The "near_polar" graph is a cross between the normal graph and the polar +graph. In this case the pole is not on the graph, but is close enough +to significantly affect the appearance of the plot. The "near_polar" graph +is handled like a polar graph. + +The parameter 'graph_type' can be used to force 'wcslab' +to plot a graph of the type specified, although you may need to +change other 'wlpars' parameters to get good results. +For example, trying to plot a polar graph as +cartesian may producing a strange looking graph. +.le +.ls Graph Labeling +Due to the variety of graph types that can be plotted (see above), and +the arbitrary rotation that any WCS can have, the task of labeling +the major grid lines in a coherent and pleasing manner is not trivial. + +The basic model used is the cartesian or normal graph. Labels +normally appear on the left and bottom edges of the graph with one side +devoted solely to one of the WCS coordinate axis. For example, right +ascension might be labeled only along the bottom edge of the graph +and declination only along the left edge, or vice versa. + +If the defaults chosen by the task are unacceptable, the +parameters 'axis1_side' and 'axis2_side', can be used to specify which +side (or sides) the labels for axis 1 and axis 2 will appear. +Either a single side or a list of sides can be specified for either +axis. If a list is specified, labels will appear on each side listed, +even if the same side appears in both of the parameters. In this way, +labels can be made to appear on the same side of the graph. +.le +.ls Label Appearance +Due to coordinate rotations, lines of constant axis 1 or axis 2 value +may not intersect the edges +of the graph perpendicularly. To help clarify which line belongs to +which label, the labels will be drawn at an angle equal to that of the +line which is being labeled. If this is not desired, +the parameter rotate may be set to no, and labels will always appear +"normal", i.e., the text will not be rotated in any way. + +By default, all labels will be shortened to the smallest unit +needed to indicate the value of the labeled line. For example, if the +graph spans about 30 seconds of declination, the interval between the +labels will be approximately 5 or 10 seconds. The first label will contain the +full specification, i.e., -22:32:20. But the rest of the labels will +only be the seconds, i.e., 30, 40, 50. However, at the change in +minutes, the full format would be used again, -22:33:00, but then +again afterwards only seconds will be displayed, i.e., 10, 20, etc. +If this shortening of labels is undesirable, it +can be turned off by setting the parameter 'full_label = yes'. This +forces every label to use the full specification. + +Finally, the parameter 'label_size' can be used to adjust the size of the +characters used in the axis labels. +.le +.ls Titles +A graph title may specified using the parameter 'title'. +If 'title = "imtitle"', a default title constructed from the image name and title +is used. The location and size of the graph title are controlled by +the parameters 'title_side' and 'title_size'. +Similarly the content, placement and size of the axis titles are +controlled by the parameters 'axis1_title', 'axis2_title', +'axis1_title_side', 'axis2_title_side', and +'axis_title_size'. +.le +.ls Interactive Cursor +'wcslab' provides a simple cursor readback capability for retrieving +coordinates of objects and saving them in a file. However, you should +also look at the tasks 'tvmark' and 'rimcursor' for more advance +functionality. + +The cursor allows the user to examine +coordinates of specific objects and to make a file containing a +list of coordinates. For graphic displays, the user has the full cursor +functionality described by 'gcur'. However, there are a few extra +commands provided for transforming cursor position to celestial +coordinates. While in cursor mode, striking most lower-case +characters will result in the celestial coordinates of the cursor +position to be displayed on the terminal. + +Coordinates can also be written to a file by +striking the lower-case 'm'. When 'm' is hit, an 'X' is placed on the +display, and the coordinates are written to a coordinate list file. +This file can be specified in two ways. If you just start hitting +'m', a file called '.coord.list' will be created. You can +specify a +different +file with the colon command ":open ". After opening the +file, any +new coordinates marked with the 'm' key are written to the +file. You can go through as many files as you like. If a file is +specified that already exists, an attempt is made to read the file. +If it contains coordinate values, those coordinate positions are +displayed as crosses in the window, and any new position marked +will be appended. + +Striking the '?' key will display help concerning these task-specific +commands. Striking the 'q' key will exit the task. +.le +.ls Output Formats +Currently, only one coordinate format is supported: all right +ascensions are output in HH:MM:SS (hours:minutes:seconds) format +and +all declinations are output in DD:MM:SS (degrees:minutes:seconds). If +parameters are changed, such as 'axis1_int', they should be +input in the same format. For the coordinate list files, the first +line of the file begins with the comment character, '#', and displays +the format used in the file. + +If the WCS is linear, then output will not be formatted in any special +way; i.e., no assumptions are made about units, etc. +.le +.ih +PARAMETERS +.ls (major_grid = yes) [boolean] +Draw a coordinate grid instead of tick marks at the position of the major +intervals? + +If set to "yes", lines of constant axis1 and axis2 values are drawn. +If set to "no", tick marks will be drawn instead. Major grid lines and +tick marks will be labeled with the appropriate axis values. +.le +.ls (minor_grid = no) [boolean] +Draw a coordinate grid instead of tick marks at the position of the +minor intervals? + +If set to "yes", lines of constant axis1 and axis2 values +are drawn between the major grid lines and tick +marks. If this is set to "no", tick +marks will be drawn instead. Minor grid lines and tick +marks are not labeled. +.le +.ls (dolabel = yes) [boolean] +Label the major grid lines or tick marks? +.le +.ls (remember = no) [boolean] +Modify the 'wlpars' parameter file when done? + +Setting this to "yes" allows parameters that may have been calculated +by the task to be written back to the parameter file. If set to "no", +the default, the parameter file is left untouched by the task. This is +useful if some slight modification is desired to produce a slightly +different graph. +.le +.ls (axis1_beg = "") [string] +The lowest value of axis 1 in world coordinates units at which a major +grid line or tick mark will be plotted. If set to null ('axis1_beg = +""'), 'wcslab' will compute this quantity. 'axis1_beg' will be +ignored if 'axis1_end' and 'axis1_int' are undefined. +.le +.ls (axis1_end = "") [string] +The highest value of axis 1 in world coordinate +units at which a major grid line or tick mark will be plotted. +If 'axis1_end = ""', the task will compute this quantity. +'axis1_end' will be ignored if 'axis1_beg' and 'axis1_int' are undefined. +.le +.ls (axis1_int = "") [string] +The interval in world coordinate units at which +major grid lines and tick marks will be drawn along axis 1. +If 'axis1_int = ""', 'wcslab' will compute this quantity. +'axis1_int' will be ignored if 'axis1_beg' and 'axis1_end' are undefined. +.le +.ls (axis2_beg = "") [string] +The lowest value of axis 2 in world coordinates units +at which a major grid line or tick mark will be plotted. +If 'axis2_beg = ""', 'wcslab' will compute this quantity. +'axis2_beg' will be ignored if 'axis2_end' and 'axis2_int' are undefined. +.le +.ls (axis2_end = "") [string] +The highest value of axis 2 in world coordinate +units at which a major grid line or tick mark will be plotted. +If 'axis2_end = ""', 'wcslab' will compute this quantity. +'axis2_end' will be ignored if 'axis2_beg' and 'axis2_int' are undefined. +.le +.ls (axis2_int = "") [string] +The interval in world coordinate units at which +major grid lines or tick marks will be drawn along axis 2. +If 'axis2_int = ""', 'wcslab' will compute this quantity. +'axis2_int' will be ignored if 'axis1_beg' and 'axis1_end' are undefined. +.le +.ls (major_line = "solid") [string, allowed values: solid | +dotted | dashed | dotdash] + +The type of major grid lines to be plotted. +The permitted values are "solid", "dotted", "dashed", and "dotdash". +.le +.ls (major_tick = .03) [real] +Size of major tick marks relative to the size of the viewport. +By default the major tick marks are .03 times the size of the +viewport. +.le +.ls (axis1_minor = 5) [integer] +The number of minor grid lines or tick marks that will appear between major +grid lines or tick marks for axis 1. +.le +.ls (axis2_minor = 5) [integer] +The number of minor grid lines or tick marks that will appear between major +grid lines or tick marks for axis 2. +.le +.ls (minor_line = "dotted") [string, allowed values: solid | +dotted | dashed | dotdash] + +The type of minor grid lines to be plotted. +The permitted values are "solid", "dotted", "dashed", and "dotdash". +.le +.ls (minor_tick = .01) [real] +Size of minor tick marks relative to the size of the viewport. +BY default the minor tick marks are .01 times the size of the +viewport. +.le +.ls (tick_in = yes) [boolean] +Do tick marks point into instead of away from the graph? +.le +.ls (axis1_side = "default") [string] +The list of viewport edges, separated by commas, on which to place the axis +1 labels. If 'axis1_side' is "default", 'wcslab' will choose a side. +'axis1_side' may contain any combination of "left", "right", +"bottom", "top", or "default". +.le +.ls (axis2_side = "default") [string] +The list of viewport edges, separated by commas, on which to place the axis +2 labels. If 'axis2_side' is "default", 'wcslab' will choose a side. +'axis2_side' may contain any combination of "left", "right", +"bottom", "top", or "default". +.le +.ls (axis2_dir = "") [string] +The axis 1 value at which the axis 2 labels will be written for polar graphs. +If 'axis2_dir' is "", 'wcslab' will compute this number. +.le +.ls (justify = "default") [string] +The direction with respect to axis 2 along which the axis 2 +labels will be drawn from the point they are labeling on polar graphs. +If 'justify = ""', then 'wcslab' will calculate this quantity. The permitted +values are "default", "left", "right", "top", and "bottom". +.le +.ls (labout = yes) [boolean] +Draw the labels outside the axes? + +Setting this to "yes", draws labels outside the image viewport. +Otherwise, the axes labels will be drawn inside +the image border. The latter option is useful if the image fills the +display frame buffer. +.le +.ls (full_label = no) [boolean] +Always draw all the labels in full format (h:m:s or d:m:s) if the world +coordinate system of the image is in RA and DEC? + +If 'full_label = no', then +only certain axes will be labeled in full format, with the rest +labeled in minutes or seconds, as appropriate. +.le +.ls (rotate = yes) [boolean] +Permit the labels to rotate ? + +If 'rotate = yes', then labels will be written +at an angle to match that of the major grid lines that are being +labeled. If 'rotate = no', then labels are always written +"normally", that is horizontally. If 'labout = no', then rotate is +set to "no" by default. +.le +.ls (label_size = 1.0) [real] +The size of the characters used to draw the major grid line labels. +.le +.ls (title = "imtitle") [string] +The graph title. If 'title = "imtitle"', then a default title containing +the image name and title is created. +.le +.ls (axis1_title = "") [string] +The title for axis 1. By default no axis 1 title is drawn. +.le +.ls (axis2_title = "") [string] +The title for axis 2. By default no axis title will be written. +.le +.ls (title_side = "top") [string, allowed values: top | bottom | +left | right] + +The side of the plot on which to place the title. +The options are "left", "right", "bottom", and "top". +.le +.ls (axis1_title_side = "default") [string, allowed values: default | +top | bottom | left | right] + +The side of the plot on which to place the axis 1 title. +If 'axis1_title_side = "default"', 'wcslab' will choose a side for the title. +The permitted values are "default", "right", "left", "top", and +"bottom". +.le +.ls (axis2_title_side = "default") [string, allowed values: default | +top | bottom | left | right] + +The side of the plot on which to place the axis 2 title. +If 'axis2_title_side = "default"', 'wcslab' will choose a side for the title. +The permitted values are "default", "right", "left", "top", and +"bottom". +.le +.ls (title_size = 1.0) [real] +The size of characters used to draw the title. +.le +.ls (axis_title_size = 1.0) [real] +The size of the characters used to draw the axis titles. +.le +.ls (linecolor = INDEF) [integer] +Color used for drawing lines and tick marks. If this is not specified, +the default color +for the graphics output device will be used. +.le +.ls (labelcolor = INDEF) [integer] +Color used to write axis labels. If not specified, the color for the lines +and tickmarks will be used. +.le +.ls (titlecolor = INDEF) [integer] +Color used to write the plot title. If not specified, the color for the +labels will be used. +.le +.ls (graph_type = "") [normal | polar | near_polar] +String indicating what type of graph will be drawn. If empty, the +default, the task will determine the type. +.le +.ls (coords) [gcur] +The graphics cursor. +.le +.ls (image_coord) [imcur] +The image display cursor. +.le +.ls (version = "16Jun92" ) [string] +The date the current software was installed. +.le +.ih +EXAMPLES +.ih +BUGS +.ih +SEE ALSO +wcslab, cursors, newcont +.endhelp -- cgit