path: root/noao/digiphot/photcal/doc/invertfit.hlp

.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