Initial commit

1 files changed, 267 insertions, 0 deletions

diff --git a/noao/digiphot/photcal/doc/evalfit.hlp b/noao/digiphot/photcal/doc/evalfit.hlp
new file mode 100644
index 00000000..9a256964
--- /dev/null
+++ b/noao/digiphot/photcal/doc/evalfit.hlp
@@ -0,0 +1,267 @@
+.help evalfit Aug91 noao.digiphot.photcal
+.ih
+NAME
+evalfit -- evaluate the fit
+.ih
+USAGE
+evalfit observations config parameters calib
+.ih
+PARAMETERS
+.ls observations
+The list of files containing the observations.
+\fIObservations\fR are multi-column text files, whose columns are delimited
+by whitespace, and whose first column is reserved for an object id.
+All observations files in the list must have the same format.
+.le
+.ls config
+The configuration file. \fIConfig\fR is a text file which
+specifies the format of the \fIobservations\fR and \fIcatalog\fR files, and
+defines the form of the transformation equations to be evaluated.
+More information can be obtained about this file by typing
+"help mkconfig" and "help config".
+.le
+.ls parameters
+The name of the file produced by the FITPARAMS task.
+\fIParameters\fR is a text file 
+containing the fitted parameter values for each
+equation and other information about the quality of the
+fit. Records in \fIparameters\fR are assigned a name equal to the label
+of fitted equation. If more than one record in \fIparameters\fR has
+the same name then the last record of that name is used by EVALFIT to 
+evaluate the fit.
+.le
+.ls calib
+The name of the output file. \fICalib\fR is a text file
+containing the name of the fitted object in the first column,
+followed by the \fIprint\fR
+variables if any, followed by the fitted value, error of the fit (if
+\fIerrors\fR is not "undefined"), and residual of the
+fit (if catalog matching is enabled) for each equation.
+.le
+.ls catalogs
+The list of files containing the catalog data.
+\fICatalogs\fR are multi-column text files, whose columns are delimited
+by whitespace, and whose first column is reserved for an object id.
+All catalog files in the list must have the same format.
+If \fIcatalogs\fR = "", then no id matching with the observations
+files is done.
+.le
+.ls errors = "undefined"
+The algorithm used to compute formal errors for each object fit. The choices
+are:
+.ls undefined
+No errors are computed and no error values are output.
+.le
+.ls obserrors
+The error in each fitted value is computed by summing in quadrature
+the contribution to the total error made by each individual error in the
+observations file variables. If no error columns are defined for the
+observations files the error is assumed to be INDEF.
+.le
+.ls equations
+The error in each fitted value is computed by evaluating the error
+equations associated with each transformation equation. If no error equation
+is defined then the error is assumed to be INDEF.
+.le
+.le
+.ls objects = "all"
+The type of objects to output to \fIcalib\fR. The choices are:
+.ls all
+Both program and standard stars are output.
+.le
+.ls program = yes
+Only program stars are output.
+.le
+.ls standard = yes
+Only standard stars are output.
+.le
+.le
+.ls print = ""
+Additional variables to be printed in the output file. These variables are
+printed immediately after the id, and may be any of the
+catalog variables, observations variables, or the set equation variables
+defined in \fIconfig\fR.
+.le
+.ls format = ""
+An SPP style format string to apply to the output data, in place of the
+default format.  SPP format strings
+are described in detail in the formats section.
+.le
+.ls append = no
+Append the output to \fIcalib\fR instead of creating a new file. If the
+file already exists and \fIappend\fR is "no" EVALFIT will abort.
+.le
+.ls catdir = ")_.catdir"
+The directory containing the supported standard star catalogs.
+The default parameter value  redirects \fIcatdir\fR
+to a package parameter of the same name. A list of standard
+catalogs may be obtained by printing the file "photcal$catalogs/README".
+Alternatively the user may create their own standard star catalogs 
+and standard star catalog directory.
+.le
+
+.ih
+DESCRIPTION
+
+EVALFIT evaluates the transformation  equations
+for the program and/or standard objects in \fIobservations\fR, using
+the transformation equations defined in \fIconfig\fR,
+the fitted parameter values in the file \fIparameters\fR produced by the
+FITPARAMS
+task, and writes the output to the file \fIcalib\fR. If \fIappend\fR is "yes"
+output may be appended to an existing file.
+
+EVALFIT computes the values of the catalog variables for the program
+stars by inserting the observations variables directly into the
+transformation equations. EVALFIT can evaluate any number of transformation
+equations, but if there are any standard catalog variables in the right-hand
+side of the transformation equation, EVALFIT will assign INDEF to the fitted
+for that equation.
+
+Below are two sets of transformation equations. The first set can be evaluated
+with EVALFIT, the second set cannot and must be inverted with INVERTFIT.
+In both cases the catalog variables to be fit are V and BV, and
+the observed quantities are mv, mb, Xv, and Xb.
+
+.nf
+    System 1:    V = v0 + mv + v1 * (Xv + Xb) / 2. + v2 * (mb - mv)
+		 BV = b0 + b1 * (Xv + Xb) / 2. + b2 * (mb - mv)
+
+    System 2:    mv = v0 + V + v1 * Xv + v2 * BV
+		 mb = b0 + V + BV + b1 * Xb + b2 * BV
+.fi
+
+
+Formal errors for each fit may
+be computed by,  1) setting \fIerrors\fR to "obserrors" and using the
+error columns defined in the observations section of \fIconfig\fR
+to estimate the errors or 2) evaluating the error equations defined in
+\fIconfig\fR.
+
+If the user wishes to match the objects in \fIobservations\fR with those
+in \fIcatalogs\fR in order for example, to compute the residuals of the fit,
+\fIcatalogs\fR must be defined. Similarly if \fIobjects\fR is "program"
+or "standard", \fIcatalogs\fR must be defined in order to enable
+id matching.
+
+Legal \fIcatalog\fR and \fIobservations\fR files are multi-column text
+files whose columns are delimited by whitespace.
+The first column of a catalog file is \fIalways\fR reserved for an object id.
+The first column of an observations file is reserved for an
+object id which can be
+used to match the observational data with the corresponding catalog data.
+All other columns may contain any quantity which can be
+expressed as an integer or real number.  Sexagesimal format numbers
+(hh:mm:ss) are interpreted internally as real numbers. The constant
+INDEF can be used to represent data that is missing or undefined.
+Double precision and complex data are
+not supported. Lines beginning with "#" are treated as comment lines.
+
+By default EVALFIT prints out the object id,
+followed by the variables listed in the \fIprint\fR
+parameter, followed by the fit value, estimated
+error (if \fIerrors\fR is not "undefined"), and residual of the fit
+(for any standard star observations that can be matched with the
+catalog values) for each fitted equation. The user can format the output
+by setting the \fIformat\fR parameter to an SPP style string. 
+SPP format strings are described in detail below.
+
+.ih
+FORMATS
+A format specification has the form "%w.dCn", where w is the field width,
+d is the number of decimal places or the number of digits of precision,
+C is the format code, and n is radix character for format code "r" only.
+The w and d fields are optional.  The format codes C are as follows:
+
+.nf
+b	boolean (YES or NO)
+c	single character (c or '\c' or '\0nnn')
+d	decimal integer
+e	exponential format (D specifies the precision)
+f	fixed format (D specifies the number of decimal places)
+g	general format (D specifies the precision)
+h	hms format (hh:mm:ss.ss, D = no. decimal places)
+m	minutes, seconds (or hours, minutes) (mm:ss.ss)
+o	octal integer
+rN	convert integer in any radix N
+s	string (D field specifies max chars to print)
+t	advance To column given as field W
+u	unsigned decimal integer 
+w	output the number of spaces given by field W
+x	hexadecimal integer
+z	complex format (r,r) (D = precision)
+
+
+Conventions for w (field width) specification:
+
+    W =  n	right justify in field of N characters, blank fill
+	-n	left justify in field of N characters, blank fill
+	0n	zero fill at left (only if right justified)
+absent, 0	use as much space as needed (D field sets precision)
+
+
+Escape sequences (e.g. "\n" for newline):
+
+\b	backspace   (\fBnot implemented\fR)
+\f	formfeed
+\n	newline (crlf)
+\r	carriage return
+\t	tab
+\"	string delimiter character
+\'	character constant delimiter character
+\\	backslash character
+\nnn	octal value of character
+
+Examples
+
+%s          format a string using as much space as required
+%-10s	    left justify a string in a field of 10 characters
+%-10.10s    left justify and truncate a string in a field of 10 characters
+%10s	    right justify a string in a field of 10 characters
+%10.10s     right justify and truncate a string in a field of 10 characters
+
+%7.3f       print a real number right justified in floating point format
+%-7.3f      same as above but left justified
+%15.7e	    print a real number right justified in exponential format
+%-15.7e     same as above but left justified
+%12.5g	    print a real number right justified in general format
+%-12.5g     same as above but left justified
+
+\n          insert a newline
+
+.fi
+
+
+Note that deferred value fields are \fBnot implemented\fR in EVALFIT.
+
+.ih
+EXAMPLES
+
+1. Evaluate the fit for a list of program stars in m92. Use the errors
+in the observed quantities to estimate the errors.
+
+.nf
+	ph> evalfit m92.obs m92.cfg m92.fit m92.cal
+.fi
+
+2. Repeat the fit computed above but include the variables xu and yu which
+are the positions of the objects in the u frame in the output.
+
+.nf
+	ph> evalfit m92.obs m92.cfg m92.fit m92.cal print="xu,yu"
+.fi
+
+3. Repeat the fit computed above but format the output. The user has
+determined that the output will have 5 columns containing the object id,
+xu, yu, fit value and fit error respectively.
+
+.nf
+	ph> evalfit m92.obs m92.cfg m92.fit m92.cal print="xu,yu"\
+	    format="%-10.10s  %-7.2f  %-7.2f  %-7.3f  %-6.3f\n"
+
+.fi
+
+.ih
+SEE ALSO
+mkconfig,chkconfig,fitparams,invertfit
+.endhelp