From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001 From: Joseph Hunkeler Date: Wed, 8 Jul 2015 20:46:52 -0400 Subject: Initial commit --- noao/digiphot/photcal/doc/invertfit.hlp | 297 ++++++++++++++++++++++++++++++++ 1 file changed, 297 insertions(+) create mode 100644 noao/digiphot/photcal/doc/invertfit.hlp (limited to 'noao/digiphot/photcal/doc/invertfit.hlp') 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 -- cgit