Initial commit

1 files changed, 297 insertions, 0 deletions

diff --git a/noao/digiphot/photcal/doc/invertfit.hlp b/noao/digiphot/photcal/doc/invertfit.hlp
new file mode 100644
index 00000000..0923d0fb
--- /dev/null
+++ b/noao/digiphot/photcal/doc/invertfit.hlp
@@ -0,0 +1,297 @@
+.help invertfit Aug91 noao.digiphot.photcal
+.ih
+NAME
+invertfit -- evaluate the fit by inverting the system of equations defined
+in the configuration file
+.ih
+USAGE
+invertfit 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 inverted.
+More information can be obtained about the format of this file
+by typing "help mkconfig" and "help config".
+.le
+.ls parameters
+The name of the file containing the fit 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 the fitted equation. If more than one record in \fIparameters\fR has
+the same name then the last record is used by INVERTFIT to do the inversion.
+.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 values of the \fIprint\fR variables if any,
+followed by the fitted value of each catalog variable, error in the
+catalog variable (if \fIerrors\fR is not
+"undefined"), and residual of the fit (if catalog matching is enabled).
+.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 always reserved for an object id.
+All catalog files in the list must have the same format.
+If \fIcatalogs\fR is "", then no id matching with the observations files
+is done, and the residuals of the fit cannot be computed.
+.le
+.ls errors = "obserrors"
+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 files variables. If no error columns are defined for the
+observations files, the error is assigned the value INDEF.
+.le
+.ls equations
+The error in each fitted value is computed by summing in quadrature
+the contribution to the total error made by each error 
+equation associated with a transformation equation.
+If no error equation is defined for any of the transformation
+equations, 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 objects are output.
+.le
+.ls program = yes
+Only program objects are output.
+.le
+.ls standard = yes
+Only standard objects are output.
+.le
+.le
+.ls print = ""
+Additional variables to be printed in the output file. These variables are
+printed immediately after the object 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 be used for formatting 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" INVERTFIT 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
+
+INVERTFIT computes magnitudes and colors for the standard or
+program stars in \fIobservations\fR by inverting the system of
+transformation equations defined in \fIconfig\fR, using the
+parameter values in the file \fIparameters\fR produced by the FITPARAMS
+task, and writes the fitted values to the output file \fIcalib\fR.
+If \fIappend\fR is "yes" output may be appended to an existing file.
+
+INVERTFIT computes the values of the catalog variables for the program
+stars by inverting the system of transformation equations defined in
+\fIconfig\fR. IT IS THE RESPONSIBILITY OF THE USER TO ENSURE THAT
+THE SYSTEM OF EQUATIONS IS ACTUALLY INVERTIBLE.
+Two minimum conditions must be met. First, the number of
+transformation equations must be greater than or equal to the number of
+catalog variables to be fit, and second, all the catalog variables must
+be on the right-hand side of the transformation equations.
+INVERTFIT will test for both of these conditions, issue a warning, and
+terminate execution if either of these conditions are not met.
+
+Below are two sets of transformation equations.
+The first set
+can be inverted by INVERTFIT, the second set cannot and must be
+evaluated by EVALFIT. 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:    mv = v0 + V + v1 * Xv + v2 * BV
+		 mb = b0 + V + BV + b1 * Xb + b2 * BV
+
+    System 2:    V = v0 + mv + v1 * (Xv + Xb) / 2. + v2 * (mb - mv)
+		 BV = b0 + b1 * (Xv + Xb) / 2.0 + b2 * (mb - mv) 
+.fi
+
+It is possible though not recommended, to use set equation variables as
+unknowns in the transformation
+equations, provided that the total number of unknowns on the right-hand
+side of the equations remains less than or equal to the number of transformation
+equations. Set equations containing catalog variables must not be used
+in the left-hand side of the transformation equations. An example of a set
+of transformation equations which use a set equation variable is shown
+below. Note that there still are only two independent variables V and BV and
+that the output file \fIcalib\fR will contain V and BV only.
+
+.nf
+    System 1:    set B = V + BV
+    		 mv = v0 + V + v1 * Xv + v2 * BV
+		 mb = b0 + B + b1 * Xb + b2 * BV
+.fi
+
+Some systems of equations are invertible but do not have a UNIQUE solution.
+A sample of such a system is shown below.
+There are quadratic terms in BV, implying that this set of
+equations probably has two solutions, both of which may be
+be mathematically correct, but only one of which is physically meaningful.
+INVERTFIT does not test for this condition and may converge to either solution.
+
+.nf
+    System 1: mv = v0 + V + v1 * BV + v2 * BV ** 2
+	      mb = b0 + V + BV + b1 * BV + b2 * BV ** 2
+.fi
+ 
+
+Formal errors for the 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) setting \fIerrors\fR to "equations" and
+using the error equations defined in \fIconfig\fR to estimate the errors.
+
+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 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 INVERTFIT prints out the id,
+followed by the variables listed in the \fIprint\fR
+parameter, followed by the fit value, estimated
+error (if \fIerrors\fR is "undefined", and residual of the fit (for any
+standard star observations that can be matched with the catalog values)
+for each fitted catalog variable.
+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
+
+.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> invertfit 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> invertfit m92.obs m92.cfg m92.fit m92.cal print="xu,yu"
+.fi
+
+3. Repeat the fit computed in 1 but format the output. The user has
+determined that the output will have 7 columns containing the object
+id, V, error(V), resid(V), BV, error(BV), and resid(BV).
+
+.nf
+	ph> invertfit m92.obs  m92.cfg m92.fit m92.cal\
+  	    format="%-10.10s %7.3f %6.3f %6.3f %7.3f %6.3f %6.3f\n"
+.fi
+
+.ih
+SEE ALSO
+mkconfig,chkconfig,fitparams,evalfit
+.endhelp