diff options
Diffstat (limited to 'noao/digiphot/daophot/doc/specs/daoutils.spc')
| -rw-r--r-- | noao/digiphot/daophot/doc/specs/daoutils.spc | 700 |
1 files changed, 700 insertions, 0 deletions
diff --git a/noao/digiphot/daophot/doc/specs/daoutils.spc b/noao/digiphot/daophot/doc/specs/daoutils.spc new file mode 100644 index 00000000..d943d63a --- /dev/null +++ b/noao/digiphot/daophot/doc/specs/daoutils.spc @@ -0,0 +1,700 @@ +.help daoutils Jan89 "Utility Package for DAOPHOT" +.sh +1. Introduction + +The DAOUTILS package will provide a set of tools for working +with the output from DAOPHOT. These tools will provide the user with +the ability to select data upon ranges and limits for any of the +fields in a daophot output table. The package will also provide tools +for merging results contained in different output files. + +.sh +2. Requirements +.ls 4 +.ls (1) +The tasks in the DAOUTILS package shall take as input the output ST Tables +from the DAOPHOT tasks. The convert task in the daophot package shall be +used to convert the output from apphot tasks into the proper format for use +with the daoutils package. +.le +.ls (2) +The tasks in the package which produce tabular output shall use the +ST Tables for their output and those tasks which read output from other +DAOUTILS tasks will be able to read ST Tables. +.le +.ls (3) +The DAOUTILS package shall include tasks to inspect and edit the results +from the photometry routines. These shall include tasks such as interactively +rejecting particular stars from the results, +producing plots of errors versus brightness, errors versus position etc. There +will also be a task for merging the results contained in several different +Tables. It shall also be possible to interactively examine the photometry +results with various graphical and/or display tools for inspecting/editing the +results. It shall also be possible to construct growth curves from the +aperture photometry for the purpose of calibrating the daophot magnitudes +to total magnitudes. There shall also be routines for calibrating the +photometry by the use of standard stars. +.le +.ls (4) +The tasks shall be able to be run in batch mode as well as interative +mode. In batch mode use of a graphics terminal or image display shall not +be required. +.le +.ls (5) +The DAOPHOT package shall be written in the SPP language in conformance with +the standards and conventions of IRAF. The code shall be portable and +device independent. +.le +.le +.sh +2.1 Limitations of the Initial DAOUTILS Package + +The DAOUTILS package will have the following limitations: +.ls +.ls (1) +The initial version of DAOUTILS will not make direct use of the interactive +image display. It will make use of cursor readback however. +.le +.le + +.sh +3. Specifications + +The DAOUTILS package will take the output from the DAOPOHT package as input +and provide a variety of tools which will allow the use to examine, edit and +calibrate the output from DAOPHOT. The output from DAOUTILS will consist of +ST Tables, graphical displays and printed summaries. + +The CL callable part of the DAOUTILS package will consist of the following +tasks: + +.ks +.nf + merge -- Merge the results from different runs of daophot + daograph -- Graph the results of daophot stored in ST Tables + gtedit -- Interactive graphical data editor + examine -- Interactively examine the output from daophot + growth -- aperture growth curves <--> PSF magnitudes + cmd -- Color-magnitude and color-color plots + calibrate -- do photometric calibration + +.fi +.ke + +In addition the ttools package provided as part of STSDAS provides for +many generic tools for working with the ST Tables are will be usable for +many of the data selection tasks which most users will wish to apply to +daophot output. + +.sh +3.1 The GTEDIT Task + +The user will be able to plot any two columns of a Table versus each other +and with the cursor interactively delete records. The user will move the +graphics cursor near the point on the graph which represents the record +which he wishes to delete from the input record. The user will also be able +to specify 'areas' of the plot for which all records pointed to by points +in the indicated sections will be deleted. The user will also be +able to undelete records. The records will not actually be deleted until the +task ends. The user will also be able to interactively change which columns +are being plotted versus each other. The user will also have the option of +editing the table in place or to create a new output table which will contain +the edited results of the input table. + +.sh +3.1.1 GEDIT Parameters + +GEDIT will have input parameters which control the input and initial +operation of the task. + +.ks +.nf +Positional or query mode parameters: + + input - filename + xcolumn - column name (string) + ycolumn - column name (string) +.fi +.ke + +.ks +.nf +Hidden parameters: + + inplace boolean "false" + output filename "" + reject filename "" +.fi +.ke + +The function and format of these parameters is decsribed in more detail +below. + +.ls +.ls 16 input +The name of the input table which contains the output from DAOPHOT. +.le +.ls xcolumn +The name of the column in the input table which will be used for the +X axis of the plot +.le +.ls ycolumn +The name of the column in the input table which will be used for the +Y axis of the plot +.le +.ls inplace +Controls whether the input table is modified in place or whether a new +table is created. +.le +.ls output +If inplace is false then the value of this parameter will be the name of +the output table which will contain the edited output. +.le +.ls reject +The name of the output file containing those objects which have been +deleted. If this parameter is NULL then the records which have been +deleted are not saved. +.le +.le + +.sh +3.1.2 Interactive GEDIT Commands + +Once GEDIT has plotted the two columns specified as the input there are +several commands available to the user. These allow the user to delete/undelete +points, change which columns are plotted, view a particular record from the +input table and exit GEDIT. + +.ks +.nf +In the interactive mode the following cursor keys are active: + + x -- delete the record represented by the point nearest the cursor + > -- delete all records represented by Y values > than the cursor + < -- delete all records represented by Y values < than the cursor + + -- delete all records represented by X values > than the cursor + - -- delete all records represented by X values < than the cursor + b -- mark the corner of box containing records to be deleted. + u -- undelete the record(s) deleted by the last delete operation + q -- exit GEDIT +.fi +.ke + +.ks +.nf +In addition the following colon commands are available: + + :xcol <name> Use the column <name> as the X axis + :ycol <name> Use the column <name> as the Y axis +.fi +.ke + +.sh +3.1.3 GEDIT OUTPUT + +The output from GEDIT is a direct copy of the input table with the records +which the user marked for deletion removed. If the parameter 'inplace' was +set to true then the edited table replaces the original table, otherwise a +new table is created. Is it important that no records be deleted until the +user exits GEDIT and confirms that the update is to take place. + +.sh +3.2 TGRAPH + +This task is will produce plots from the DAOPHOT output tables. It is similar +to the sgraph task in STSDAS but does not have the option of plotting image +sections. It does have the ability to plot error bars and columns of data from +two different tables. + +The following is the help for sgraph: + +.ih +NAME +graph -- graph one or more lists, image sections, or tables +.ih +USAGE +graph input +.ih +PARAMETERS +.ls input +List of operands to be graphed. May be STDIN, or one or more image +sections, tables and columns, or lists. SDAS table input is specified +by: a table name and column name, a table and two column names, or a +pair of table and column names, separated by white space. +.le +.ls stack = no +If stack = yes, plot multiple curves on separate axes (WCS) stacked +vertically rather than on the same axes. +.le +.ls wx1=0., wx2=0., wy1=0., wy2=0. +The range of user coordinates spanned by the plot. If the range of values +in x or y = 0, the plot is automatically scaled from the minimum to +maximum data value along the degenerate dimension. +.le +.ls vx1=0., vx2=0., vy1=0., vy2=0. +NDC coordinates (0-1) of the device plotting viewport. If not set by +the user, a suitable viewport which allows sufficient room for all labels +is used. +.le +.ls pointmode = no +If \fBpointmode\fR = yes, plot points or markers at data values, rather than +connected lines. +.le +.ls marker = "box" +Marker to be drawn if \fBpointmode\fR = yes. Markers are "point", "box", +"cross", "plus" or "circle". +.le +.ls szmarker = 0.005 +The size of a marker in NDC coordinates (0 to 1 spans the screen). +If zero and the input operand is a list, marker sizes are taken individually +from the third column of each list element. If positive, all markers are +of size \fBszmarker\fR. If negative and the input operand is a list, +the size of a marker is the third column of each list element times the +absolute value of \fBszmarker\fR. +.le +.ls xlabel = "", ylabel = "" +Label for the X-axis or Y-axis. +.le +.ls title = "imtitle" +Plot title. If \fBtitle\fR = "imtitle" +and the first operand in \fBinput\fR is an image, the image title is used +as the plot title. +.le +.ls box = yes +Draw axes at the perimeter of the plotting window. +.le +.ls fill = yes +Fill the output viewport regardless of the device aspect ratio? +.le +.ls axis = 1 +Axis along which the projection is to be computed, if an input operand is +an image section of dimension 2 or higher. Axis 1 is X (line average), +2 is Y (column average), and so on. +.le +.ls erraxis = 0 +If pointmode = no and erraxis is 1 or 2, the axis parallel to which +error bars are plotted (1 ==> X, 2 ==> Y). +.le +.ls errcolumn = "" +The column(s) in the input table to be used as the error amplitude(s). +If one column name, then symmetrical symmetrical error bars are drawn, +centered on the data points with the total size, in WC specified by the +values in the column from the same table specified in parameter input. +Two names specify two table columns for the lower and upper errors, +respectively. +.le +.ls pattern = "solid" +The line pattern for the first curve. Subsequent curves on the same +plot cycle through the set of patterns: solid, dashed, dotted, dotdash. +.le +.ls crvstyle = "straight" +The style of the plotted curve: "straight" is the usual straight +line connection between points, "pseudohist" consists of horizontal +segments at each data point connected by vertical segments, "fullhist" +is a bar graph or histogram style plot. +.le +.ls transpose = no +Swap the X and Y axes of the plot. If enabled, the axes are transposed +after the optional linear transformation of the X-axis. +.le +.ls xflip = no, yflip = no +Flip the axis? That is, plot and label X values increasing right to +left instead of left to right and/or Y values top to bottom instead of +bottom to top. +.le +.ls logx = no, logy = no +Log scale the X or Y axis. Zero or negative values are indefinite and +will not be plotted, but are tolerated. +.le +.ls ticklabels = yes +Label the tick marks. +.le +.ls majrx=5, minrx=5, majry=5, minry=5 +Number of major tick marks on each axis; number of minor tick marks between +major tick marks. Ignored if log scaling is in effect for an axis. +.le +.ls lintran = no +Perform a linear transformation of the X-axis upon input. Used to assign +logical coordinates to the indices of pixel data arrays (image sections). +.le +.ls p1=0, p2=0, q1=0, q2=1 +If \fBlintran\fR is enabled, pixel index P1 is mapped to Q1, and P2 to Q2. +If P1 and P2 are zero, P1 is set to 1 and P2 to the number of pixels in +the input array. +.le +.ls round = no +Extend the axes up to "nice" values. +.le +.ls append = no +Append to an existing plot. +.le +.ls device = "stdgraph" +The output device. +.le +.ih +DESCRIPTION +\fBGraph\fR graphs one or more lists, image sections, or table columns; +lists and image sections may be mixed in the input list at will. If the +curves are not all the same length the plot will be scaled to the +longest curve and all curves will be plotted left justified. If an +image section operand has more than one dimension the projection +(average) along a designated axis will be computed and plotted. By +default, a unique dash pattern is used for each curve, up to a maximum +of 4. + +List input may be taken from the standard input or from a file, +and consists of a sequence of Y values, X and Y values, or X, Y, +and marker size values, one pair of coordinates per line in the list. +Blank lines, comment lines, and extra columns are ignored. +The first element in the list determines whether the list is a Y list +or and X,Y list; it is an error if an X,Y list has fewer than two +coordinates in any element. INDEF valued elements appear as gaps +in the plot. + +SDAS table input is specified by a table name and column name, a table +and two columns, or a pair of table and column names separated by white +space. The table name may be a file name template. Note that this is a +single string, so that it must be quoted if entered on the command line. + +Error bars may be plotted for data from list or table input. Errors may +be in X or in Y and separate upper and lower errors may be specified. +If `pointmode' is "no" then the parameter `erraxis' specifies if the +errors are in X or in Y if its value is 1 or 2, respectively. If +`pointmode' is "no" and `erraxis' is zero, a polyline is plotted (see +below). If the input data come from a list, then the third (size) +column specifies the amplitude of symmetrical error bars. If there is a +fourth column, the third and fourth columns specify the amplitudes of +the lower and upper errors, respectively. If the input data are in a +table, the parameter `errcol' specifies the source of the errors. +If `errcol' contains a single word, it is the column in the same table +as the input data containing the amplitudes of symmetrical errors. If +`errcol' contains two words, they specify the columns in the same table +containing the amplitudes of the lower and upper errors, respectively. +If the X and Y data come from different tables, then `erraxis' specifies +which table contains the error column or columns. Error data may not +come from image data. The `append' parameter may be used +to overplot several curves of different style. + +Different line types and curve styles may be selected. The string +parameter `crvstyle' may take on one of the values: "none", "straight", +"pseudohist", or "fullhist", specifying the style of connections between +data points; the string parameter `pattern' can take on one of the +values "solid", "dashed", "dotted", "dotdash" to indicate the style +of the first line drawn. Subsequent lines drawn on the same graph cycle +the available styles. + +If \fBappend\fR is enabled, previous values for \fBbox\fR, +\fBfill\fR, \fBround\fR, the plotting viewport (\fBvx1\fR, \fBvx2\fR, +\fBvy1\fR, \fBvy2\fR), and the plotting window (\fBwx1\fR, \fBwx2\fR, +\fBwy1\fR, \fBwy2\fR) are used. + +By default, the plot drawn will fill the device viewport, if the viewport +was either specified by the user or automatically calculated by +\fIgraph\fR. Setting +the value of \fBfill\fR to "no" means the viewport will be adjusted so +that equal numbers of data values in x and y will occupy equal lengths +when plotted. That is, when \fBfill = no\fR, a unity aspect ratio is +enforced, and plots +appear square regardless of the device aspect ratio. On devices with non +square full device viewports (e.g., the vt640), a plot drawn by \fIgraph\fR +appears extended in the x direction unless \fBfill\fR = no. + +.ih +EXAMPLES +Plot the output of a list processing filter: + + cl> ... list_filter | graph + +Plot a graph entered interactively from the terminal: + + cl> graph STDIN + +Overplot two lists: + + cl> graph list1,list2 + +Graph line 128 of image "pix": + + cl> graph pix[*,128] + +Graph the average of columns 50 through 100: + + cl> graph pix[50:100,*] axis=2 + +Graph two columns from a table against each other: + + cl> graph "table xcol ycol" + +Graph a list in point plot mode: + + cl> graph list po+ + +Annotate a graph: + +.nf + cl> graph pix[*,10],pix[*,20] xlabel=column\ + >>> ylabel=intensity title="lines 10 and 20 of pix" +.fi + +Direct the graph to the standard plotter device: + + cl> graph list device=stdplot +.ih +BUGS +Indefinites are not recognized when computing image projections. + +End sgraph help. + +.sh +3.3 The MERGE Task + +This task will merge the results from a maximum of four DAOPHOT output +files based upon positional coincidence. This task will work on files +which could have been run images with different scales, orientations etc. +MERGE will need to transform the coordinate systems of the input photometry +lists to a common coordinate system. There will be two ways of inputing the +transformations to be applied to the coordinate lists: 1) Simple X, Y shifts +or 2) transformations as determined by the GEOMAP task. This will allow the +most common cases to handled in a simple way without having to run the GEOMAP +task. + +The user will be able to specify a match radius which will determine how +close to each other two objects must be to be considered a coincidence. +The user will also be able to specify the number of lists an object must +be identified in to be included in the output file. For example, if the +user was merging photometry results from four different output tables +he could request that the output table would contain entries for matches +between any two or more of the four tables. The output Table from MERGE +will simply contain pointers to the corresponding rows of the various +input tables and not contain a copy of the complete row from each table +for those objects which were matched. The user will then run another task, +MSELECT to select the fields he wants from the original photometry files. +This will allow the user to select only the fields he wants and to do the +selection more than once without remerging the individual files. + +.sh +3.3.1 MERGE Parameters + +MERGE shall have parameters which control the input and functioning of the +task. + +.ks +.nf +Positional or query parameters: + + ptable1 -- Input photometry table #1 + ptable2 -- Input photometry table #2 + ptable3 -- Input photometry table #3 + ptable4 -- Input photometry table #4 + matchrad -- Matching radius for coincidence + nmatch -- minimum number of matches to be included in output + merge_table -- output table containing merge pointers +.fi +.ke + +.ks +.nf +Hidden Parameters: + + gmfile12 -- geomap database name for transforming #1 -> #2 + gmrec12 -- geomap database record for transforming #1 -> #2 + gmfile13 -- geomap database name for transforming #1 -> #3 + gmrec13 -- geomap database record for transforming #1 -> #3 + gmfile14 -- geomap database name for transforming #1 -> #4 + gmrec14 -- geomap database record for transforming #1 -> #4 + dx12 -- X offset (x2 - x1) + dy12 -- Y offset (y2 - y1) + dx13 -- X offset (x3 - x1) + dy13 -- Y offset (y3 - y1) + dx14 -- X offset (x4 - x1) + dy14 -- Y offset (y4 - y1) +.fi +.ke + +These parameters perform the following functions: + +.ls 4 +.ls 16 ptable1 +The name of the first input photometry table. This should be a standard +DAOPHOT output table or one whose column names have been modified to agree +with the DAOPHOT standard. +.le +.ls ptable2 +The name of the second input photometry table. +.le +.ls ptable3 +The name of the third input photometry table. +.le +.ls ptable4 +The name of the fourth input photometry table. +.le +.ls matchrad +The matching radius for determining whether two objects should be identified +with the same object and potentially included in the output table. +.le +.ls nmatch +The minumum number of matches among the input photometry files for an object +to be included in the output Table. If there were four input files and +\fInmatch\fR was set to two then an object would be included in the output +if it was matched in files 1/2, 1/3, 1/4, 2/3, 2/4 or 3/4. If \fInmatch\fR +was three then the object would have to be identified in files 1/2/3, +2/3/4, 1/2/4 or 1/3/4 +.le +.ls gmfile12 +The name of the \fIGEOMAP\fR database containing the record which specifies +the transformation between photometry list 2 and photometry list 2 in the +sense of mapping objects in list #2 into the coordinate frame of the +list #1 +.le +.ls gmrec12 +The name of \fIGEOMAP\fR database record within \fIgmfile12\fR which +describes the transformation from coordinate system #2 to system #1 +.le +.ls gmfile13 +The name of the \fIGEOMAP\fR database containing the record which specifies +the transformation between photometry list 3 and photometry list 3 in the +sense of mapping objects in list #3 into the coordinate frame of the +list #1 +.le +.ls gmrec13 +The name of \fIGEOMAP\fR database record within \fIgmfile13\fR which +describes the transformation from coordinate system #3 to system #1 +.le +.ls gmfile14 +The name of the \fIGEOMAP\fR database containing the record which specifies +the transformation between photometry list 4 and photometry list 4 in the +sense of mapping objects in list #4 into the coordinate frame of the +list #1 +.le +.ls gmrec14 +The name of \fIGEOMAP\fR database record within \fIgmfile14\fR which +describes the transformation from coordinate system #4 to system #1 +.le +.ls dx12 +The X offset between coordinate system #2 and coordinate system #1 +in the sense of (x2 - x1). +.le +.ls dy12 +The Y offset between coordinate system #2 and coordinate system #1 +in the sense of (y2 - y1). +.le +.ls dx13 +The X offset between coordinate system #3 and coordinate system #1 +in the sense of (x3 - x1). +.le +.ls dy13 +The Y offset between coordinate system #3 and coordinate system #1 +in the sense of (y3 - y1). +.le +.ls dx14 +The X offset between coordinate system #4 and coordinate system #1 +in the sense of (x4 - x1). +.le +.ls dy14 +The Y offset between coordinate system #4 and coordinate system #1 +in the sense of (y4 - y1). +.le +.le + +If the parameters specifying the \fIGEOMAP\fR database file name for +a particular transformation is empty then the corresponding parameters +describing the transformation in terms of a simple shift are queried. + +.sh +3.3.2 +The Output from MERGE + +\fIMERGE\fR will produce an STSDAS Table as output with the table +containing pointers to records in the input Tables which identify the +objects which are positionally coincident. The output Table will contain +columns with the names \fIpoint0\fR, \fIpoint1\fR, \fIpoint2\fR and +\fIpoint3\fR. If an object is identified in a particular input photometry +list and also meets the \fInmatch\fR criterion then the entry in the +output Table will contain the row number in the corrsponding input Table. +For those objects which are included in the output Table but which are not +identified in a particular input Table the corrsponding entry will be +INDEF. + +.ks +.nf +Sample Output Format (ASCII representation) + + Point0 Point1 Point2 Point3 + + 1 3 INDEF 2 + 3 2 2 4 + 4 5 4 INDEF + INDEF 8 7 6 + + .fi + .ke + + In the above sample the first matched object corrsponds to rows 1, 3 and + 2 in input Tables 0, 1 and 3 respectively. This object was not matched + in input Table 0. + +The header of the Table output by MERGE shall contain the necessary information +for tracking the original data files, the data and time the merge was done etc. +The MSELECT task should check that the original photometry files have not been +modified since MERGE was run to ensure data integrity. + +.sh +3.4 MSELECT + +This task is used to select fields from the photometry Tables which +were used as input to the \fIMERGE\fR task. The output from \fIMERGE\fR +is a set of pointers to the appropriate records in the input tables. +Using \fIMSELECT\fR on an output file from \fIMERGE\fR will produce an +output file which will contain the specified fields for each of the +objects which have been matched. If an object has not been identified +in a particular Table then the values for each output field are set to +INDEF. + +.sh +3.4.1 MSELECT Parameters + +MERGE will have parameters wich will control the input and functioning +of the task. + +.ks +.nf +Positional Parameters: + + input filename "" + fields string "" + output string "" +.fi +.ke + +.ks +.nf +Hidden Parameters: + + tables string "" +.fi +.ke + +These parameters perform the following functions: + +.ls 4 +.ls 16 input +This specifies the input Table which must be an output Table from the +\fIMERGE\fR task. \fIMSELECT\fR will get the names of the actual +photometry Tables from the header of the input merge table. +.le +.ls fields +A list of fields to extract from the input photometry tables. +.le +.ls output +The name of the output table. This table will contain entries for +each of the selected fields of each photometry table. The values for +each field in the output table will be the values of the selected fields +for each of the input photometry tables. For those entries which were not +nmatched the corresponding entries will be INDEF. +.le +.ls tables +This parameter is used to select output for only a subset of the input +photometry tables. +.le + +.endhelp |