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/config.hlp | 679 +++++++++++++++++++++++++++++++++++ 1 file changed, 679 insertions(+) create mode 100644 noao/digiphot/photcal/doc/config.hlp (limited to 'noao/digiphot/photcal/doc/config.hlp') diff --git a/noao/digiphot/photcal/doc/config.hlp b/noao/digiphot/photcal/doc/config.hlp new file mode 100644 index 00000000..7e44ca24 --- /dev/null +++ b/noao/digiphot/photcal/doc/config.hlp @@ -0,0 +1,679 @@ +.help config Aug91 noao.digiphot.photcal +.ih +INTRODUCTION + +The \fIconfiguration file\fR is a text file which describes how the input data +is organized in the input standard star \fIcatalog\fR and the +\fIobservations\fR files, and defines the form of the transformation +equations required to convert from the observed or instrumental indices +to the standard indices. + +The \fIcatalog\fR file contains the standard indices for a set of +standard stars, referenced in the catalog by a name called the \fImatching +name\fR. The matching name must be in the first column of the +catalog and also must be unique, i.e. each catalog file +entry is assumed to be unique. The standard indices may be in any column +other than the first. + +The \fIobservations\fR files contain the observed indices for a +subset of the standard stars and/or program stars, referenced in the +file by a matching name, which must be in the first column of the +observations file. The observed indices may be in any column other than +the first. The names of the standard stars must match those +in the catalog file. +Only standard star observations whose matching names are found in the +catalog file are used to compute the transformation equations. + +The configuration file is divided into three sections: the \fIcatalog +section\fR which describes the format of the catalog file, the +\fIobservations section\fR which describes the format of the observations +file, and the \fItransformation section\fR which defines the form of +the transformation equations. The catalog section must occur before the +observation section in the configuration file, and the observation +section must occur before the transformation section. + +The \fIcatalog\fR and \fIobservations sections\fR are used to assign +names to the columns in the input file. +The named columns can later be referenced in the transformation equations, +by using the names +as though they were variables in a programming language. + +The \fItransformation section\fR is used to define the equations to be solved, +to specify which parameters are to be varied and which are to +be held constant during the fitting process, and to assign initial values +to all of the parameters. +Any number of transformation equations may be defined in the +transformation section. + +The transformation section may also be used, OPTIONALLY, to +define temporary variables (\fIthe set equations\fR), +define the derivatives of the transformation equations +to be fit with respect to the parameters (\fIthe derivative equations or +delta declarations\fR), +define expressions for weights and errors (\fIthe weight and error +equations\fR), and define the default expressions to be plotted +during the interactive fitting process (\fIthe plot equation\fR). + +.ih +THE CATALOG SECTION + +The catalog section is used to assign names to columns in the +standard star catalog, and optionally, to associate error columns with +the named columns. + +The catalog section begins with the keyword \fIcatalog\fR, followed by +any number of name and error(name), column associations. + +.ls Syntax +.nf +catalog + +name number + +error(name) number +.fi +.le + +The first declaration creates a name column number association. +It consists of a name followed +by a column number. The name becomes the variable name +for that column. + +The second declaration creates an error (name) column number association. +It begins with the keyword \fIerror\fR, followed by a name in parentheses +and a column number. +The name must be the name of an input column previously declared in the +catalog section. The error declarations are optional. + +The column number must be a decimal integer greater than two, since +catalog files always reserve the first column for a matching name. +This name is used to match objects in the catalog file with objects in the +observations file. + +.ls Example +.nf +# Sample catalog section for the UBV system. + +catalog + +V 2 +error(V) 3 +BV 4 +error(BV) 5 +UB 6 +error(UB) 7 +.fi +.le + +.ih +THE OBSERVATION SECTION + +The observation section is used to assign names to columns in the +observations files, and to optionally, associate error columns with the +named columns. + +The observations section begins with the keyword \fIobservation\fR, followed by +any number of name and error (name) column associations. + +.ls Syntax +.nf +observation + +name number + +error (name) number +.fi +.le + +The first declaration creates a name column number association. +It consists of a name followed +by a column number. The name becomes the variable name +for that column. + +The second declaration creates an error (name) column number association. +It starts with the keyword \fIerror\fR, followed by a name +in parentheses, and a column number. +The name must be the name of an input column previously declared in the +observation section. The error declarations are optional. + +The column number must be a decimal integer greater two, +since the first column of the observations file is reserved for a matching name. +This name is used to match objects in the observations file with +objects in the catalog file. + +.ls Example +.nf +# Sample observation section for the UBV system. + +observation + +u 2 +error(u) 3 +b 4 +error(b) 5 +v 6 +error(v) 7 +x 8 +.fi +.le + +.ih +THE TRANSFORMATION SECTION + +The transformation section is used to define the transformation equations, +to specify which parameters are to be altered and which are to be +held constant during the fitting process, and to assign initial values +to the parameters. + +The transformation section begins with the keyword \fItransformation\fR, +followed by the list of parameter declarations, +followed by the transformation equation. + +.ls Syntax +.nf +transformation + +fit parameter = value, parameter = value, ... + +constant parameter = value, parameter = value, ... + +label : expression = expression + (function) (fit) +.fi +.le + +The \fIfit\fR keyword begins a list of the parameters to be fit. +The named parameters will be fit if they are present +in a transformation equation. +The fit parameter values are used as the initial guesses for the +parameters. + +The \fIconstant\fR keyword begins a list of the parameters to be held +constant. +The named parameters will not be fit. Instead the values are regarded +as constant values in any transformation equation in which they appear. +Constant parameter declarations are used to fix +values if they are known, or to restrict the degrees +of freedom of the fit. + +All parameters, both fit and constant, must be declared before the first +equations in which they appear. +There may be any number of fit and constant parameter declaration statements. +Redefinitions are allowed, i.e., it is possible to declare a parameter with +the fit keyword, and redefine it later with the constant keyword. +The inverse is also true. + +The \fItransformation\fR equations are composed of three elements: the equation +label, the function expression, and the fit expression. + +The \fIlabel\fR is used to assign a name to the equation and fit expression. +The label can be any name not already in use. The ":" after the label is +necessary to delimit it from the rest of the transformation equation +definition. Labels are used primarily to associate the optional error, +weight and plot equations with the appropriate transformation equations. +However these labels can also be used in expressions belonging +to subsequent equations, an action equivalent to replacing them with the +fit expression they reference, before performing the actual evaluation. + +The \fIfunction\fR expression (left hand side of the "=" sign) is used as a +reference expression, i.e. an expression that has no fitting or +constant parameters in it. The function expression contains only values +computed from the input data which are known before the fit starts. + +The \fIfit\fR expression (right hand side of the "=" sign) is an expression +which contains the parameters, both those to be fit and those that are +fixed. +If this expression contains names defined +in the catalog section , it will be possible to perform the fit, +but will not be possible to apply the transformations in the forward +sense to program observations that don't have matching catalog values. +If the number of transformations equations is greater than or equal to +the total number of catalog variables used in the transformation equations, +it MAY be possible to invert the system of equations and so evaluate +the catalog variables for program objects. + +.ls Example +.nf + +# Sample transformation section for the UBV system + +transform + +# V equation + +fit v1 = 25.0, v2=0.03, v3=-0.17 +VFIT : V = v1 + v + v2 * (b - v) + v3 * x + +# B - V equation + +fit b1 = 2.10, b2 = 1.15, b3=-0.12 +const b4 = 0.0 +BVFIT : BV = b1 + b2 * (b - v) + b3 * x + b4 * (b - v) * x + +# U - B equation + +fit u1 = 3.45, u2 = 1.063, u3=-0.30 +const u4=0.0 +UBFIT : UB = u1 + u2 * (u - b) + u3 * x + u4 * (u - b) * x +.fi +.le + +.ih +OPTIONAL TRANSFORMATION SECTION FEATURES + +The transformation section may also be used, OPTIONALLY, to define +temporary variables (\fIthe set equations\fR), define explicitly the +derivatives of the transformation equations to be fit with respect to the +fit and constant parameters (\fIthe derivative equations or delta +declarations\fR), define +expressions for the weights and/or errors (\fIthe weight and error +equations\fR), and define an equation to be plotted (\fIthe plot equation\fR). + +.ls The Set Equation +.le + +The \fIset equations\fR are used to assign names to expressions. They are +primarily intended for computing quantities not listed explicitly +in the catalog or observation files, but that may be derived from them. + +.ls +.nf +syntax + +set name = expression +.fi +.le + +A set equation declaration begins with the \fIset\fR keyword, +followed by +a name, followed by an equal sign, followed by an expression. +The expression may contain any name defined in the catalog and +observation sections, or any names defined in a previous +set equation. + +In the example below the variables +V, BV and UB were declared in the catalog section, but the user wished +to define a new variable U to simplify the form of one of the +transformation equations. + +.ls +.nf +example + +set U = V + BV + UB +.fi +.le + +.ls The Delta Declaration and the Derivative Equations +.le + +The \fIdelta\fR declaration statement or the \fIderivative\fR equation +are used to tell +the non-linear least squares routines how to compute the derivatives +of the transformation equations with respect to the parameters to be fit. +If the user does +not specify how the derivatives are to be computed, a +default value for delta (see below) is used and the fit proceeds. For most +simple photometric transformations the default delta is entirely adequate, +and no delta statements or derivative expressions are required. + +However the user can elect to specify the derivatives implicitly using +the \fIdelta\fR +declaration syntax, or to supply explicit expressions for the derivatives +with respect to the parameters, using the \fIderivative\fR equation +syntax. For transformation equations which are linearly dependent on +their parameters, or in cases where the derivative expressions are +very complex the delta statement syntax is preferred over the more +correct derivative equation syntax. For non-analytic expressions the +delta syntax is required. + +.ls +.nf +syntax + +delta parameter = value, parameter = value + + or + +derivative (label, parameter) = expression +.fi +.le + +A \fIdelta\fR declaration begins with the \fIdelta\fR keyword, +followed by a list of parameter value associations, where each value +is the region over which the derivative with respect to that parameter +will be computed empirically. All the delta values must be greater than zero. + +A \fIderivative\fR equation begins with the keyword \fIderivative\fR, +followed by +the label of the equation whose derivative is being computed and +the name of the parameter +with respect to which the derivative is being taken in parentheses, finally +followed by the derivative +expression itself. + +If both a derivative equation and a delta statement are given for the same +parameter, the parser will issue a warning message, and the derivative +equation will take precedence over the delta declaration. + +The following example shows how the derivatives for an equation can be +specified in each of the two ways. + +.ls +.nf +example + +VFIT: V = v + v1 + v2 * x + v3 * (b - v) + delta v1=.1, v2=.05, v3=.02 + +or + +VFIT: V = v + v1 - v2 * x + v3 * (b - v) + deriv (VFIT,v1) = 1.0 + deriv (VFIT,v2) = x + deriv (VFIT,v3) = (b - v) +.fi +.le + +.ls Weight equation +.le + +The weight equation can be used to specify the way the weights will be +computed for each data point, +for each transformation equation. The weight equation is optional, and +whether or not the weight expression is actually used by the fitting procedure +depends on the application. The minimum and maximum weight expressions +are also optional. + +.ls +.nf +weight (label) = expression + min = expression max = expression + +.fi +.le + +The \fIweight\fR equation begins with the \fIweight\fR keyword, followed by +the label of the equation in parentheses, followed by an equal sign, +followed by the weight expression. Optionally, +the weight expression can be immediately followed by the \fImin\fR and +\fImax\fR keywords +each of which may be followed by an expression. +The expressions may contain any names declared in the catalog or +observations sections, names defined by a set equation, or parameters declared +in a fit or constant statement. Users should be extremely cautious about +the latter as weights are evaluated before the fit, i.e. before the +fit parameters have assumed their final values. + +In the following example weights are set to 1 over the standard deviation +of the v measurement, sigmav, where sigmav was declared in the observation +section. + +.ls +.nf +example + +VFIT: V = v + v1 + v2 * x + v3 * (b - v) + weight (VFIT) = 1.0 / sigmav ** 2 +.fi +.le + +.ls The Plot Equation +.le + +The plot equation is used to specify the default expressions for the x and y +axes respectively, to be plotted when the transformation equations are fit +interactively. The plot +defined by the plot equation will be in the graphics window +after the initial fit, instead of the default residuals versus function plot. + +.ls +.nf +syntax + +plot (label) = expression, expression + (x axis) (y axis) +.fi +.le + +A \fIplot\fR equation begins with the \fIplot\fR keyword, followed by +the label of the associated transformation equation in parentheses, +followed by an equals +sign, and finally followed by the plot expressions for the x and y axis +separated +by a comma. + +In the following example the user has decided he/she wants the default plot +for the VFIT equation to be a plot of the residuals versus the +observed (b - v) color. +It should be emphasized that the user could also produce the same graph +inside the interactive fitting routines by reprogramming one of the graph +keys. + +.ls +.nf +example + +VFIT: V = v + v1 + v2 * x + v3 * (b - v) + plot (VFIT) = b - v, V - (v + v1 + v2 * x + v3 * (b - v)) +.fi +.le + +.ls Error equation +.le + +The error equation is used to specify the way the error will be computed for +each data point for each transformation. The error equation is optional, and +whether or not it is used by the fitting or evaluation procedures +depends on the application. The minimum and maximum error expressions +are also optional. + +.ls +.nf +syntax + +error (label) = expression + min = expression max = expression +.fi +.le + +An \fIerror\fR equation begins with the \fIerror\fR keyword, followed by +the label of the associated transformation equation in brackets, +followed by an equal sign, +followed by the error expression. Optionally, +the error expression can be followed by the \fImin\fR and \fImax\fR keywords +each of which must be followed by an expression. +The expressions may contain any names declared in the catalog or +observations sections, names defined by a set equation, or parameters declared +in a fit or constant statement. + +In the following example the error for each data point is set equal to the +standard deviation of the v measurement, sigmav, which was declared earlier +in the observation section. + +.ls +.nf +example + +VFIT: V = v + v1 - v2 * x + v3 * (b - v) + error (VFIT) = sigmav +.fi +.le + +.ih +THE PHOTCAL LANGUAGE GLOSSARY + +The configuration file consists of a series of instructions, written by +the user in a mini-language understood by the PHOTCAL parser, which tell +the various PHOTCAL routines +what to do. The basic elements of the language are numerical constants, +identifiers, arithmetic operators, arithmetic expressions, and comment +statements. + +Numerical \fIconstants\fR may be decimal integers or floating point numbers. +Double precision and complex numbers are not supported. The INDEF constant +is not supported, although it is permitted in the input data. + +An \fIidentifier\fR (keyword, name, label, function) is an upper or +lowercase letter, followed by zero or more upper or lowercase letters or +digits. +Identifiers can be of any length up to the maximum text file line length. + +A \fIkeyword\fR is an identifier with special meaning to the PHOTCAL routines. +For example the three identifiers "catalog", "observations", and +"transformation" are used to declare the beginning of the catalog, +observations, and transformation sections of the configuration file. + +A \fIname\fR is a user variable that has either been declared in the +catalog or observation sections of the configuration file, declared as +a parameter using the fit or const declaration statements in the +transformation section of the configuration file, or +defined by a set equation in the transformation section. + +A \fIlabel\fR is an identifier which is assigned to an equation. It is used +to tell the parser which transformation equation, the optional derivative, +weight, error or plot equations are associated with. + +A \fIfunction\fR is a built-in mathematical function that can be +used in expressions. + +The following identifiers are reserved by the program to name +\fIkeywords\fR and \fIfunctions\fR. These reserved identifiers +cannot be used to name user variables or label equations. + +.nf +# keywords + +catalog constant delta derivative +error *extinction fit observations +plot *print set transformation +weight + +*reserved keywords not currently used + +# functions + +abs acos asin atan +cos exp log log10 +sin sqrt tan +.fi + +Keywords may be abbreviated to up to three characters but names, labels, +and functions may not be abbreviated. + +The following arithmetic \fIoperators\fR are recognized by PHOTCAL: +"+" (addition), "-" (subtraction), "*" (multiplication), "/" (division), +"**" (exponentiation), "-" (minus sign), and "+" (plus sign). +The arithmetic operators follow normal FORTRAN rules of precedence + +\fIExpressions\fR can be any legal arithmetic FORTRAN expression, using the +legal names, operators, functions, or constants defined above. +Parenthesis "(" and ")" may be used as well. + +\fIComments\fR may be placed anywhere in the configuration file, as long +as they are preceded by a "#" sign. +All input succeeding this character to the end of the line is skipped. + +Every physical \fIline\fR in the configuration file must be shorter than the +IRAF text file line limit, currently +161 characters, but long constructs, for example a long transformation +equation may span more than one physical line. + +.ih +EXAMPLES + +Example 1. A sample configuration file for reducing UBV photoelectric +photometry. Note the optional use of the delta declaration statement +and the weight equations. + +.nf +# Configuration file for reducing UBV photoelectric photometry. + +catalog + +V 2 # V magnitude +BV 3 # B - V color +UB 4 # U - B color + +observation + +v 2 # v instrumental magnitude +b 3 # b instrumental magnitude +u 4 # u instrumental magnitude +ev 5 # error in v instrumental magnitude +eb 6 # error in b instrumental magnitude +eu 7 # error in u instrumental magnitude +X 8 # airmass + +transformation + +fit v1 = 25.0, v2=0.16, v3=-0.043 +VFIT: V = v1 + v - v2 * X + v3 * (b - v) + delta v1=0.10, v2=0.02, v3=0.02 + weight (VFIT) = 1. / ev ** 2 + +fit b1 = 1.0, b2=0.09, b3=1.06 +BVFIT: BV = b1 - b2 * X + b3 * (b - v) + delta b1=0.10, b2=0.02, b3=0.02 + weight (BFIT) = 1.0 / (ev ** 2 + eb ** 2) + +fit u1 = 2.0, u2=0.300, u3=0.95 +UBFIT: UB = u1 - u2 * x + u3 * (u - b) + delta u1=0.10, u2=0.02, u3=0.02 + weight (UFIT) = 1. / (eb ** 2 + eu ** 2) +.fi + +Example 2. A sample configuration file for reducing UBV CCD photometry. +Note the optional use of the error column declarations in the catalog and +observations sections. The error columns can be used to compute +the weights by the FITPARAMS task. Also note how the set equations are +used to simplify the transformation equations. + +.nf +catalog + +V 2 # V magnitude +BV 3 # B-V color +UB 4 # U-B color +error(V) 5 # error in V magnitude +error(BV) 6 # error in B-V color +error(UB) 7 # error in U-B color + +observation + +ut1 3 # ut time of filter 1 observation +X1 4 # airmass of filter 1 observation +m1 7 # filter 1 instrumental magnitude +error(m1) 8 # error in filter 1 instrumental magnitude +ut2 10 # ut time of filter 2 observation +X2 11 # airmass of filter 2 observation +m2 14 # filter 2 instrumental magnitude +error(m2) 15 # error in filter 2 instrumental magnitude +ut3 17 # ut time of filter 3 observation +X3 18 # airmass of filter 3 observation +m3 19 # filter 3 instrumental magnitude +error(m3) 20 # error in filter 3 instrumental magnitude + + +transformation + +set B = V + BV +set U = V + BV + UB + +fit u1 = 0.0, u2=0.68, u3=-0.05 +const u4 = 0.0 +UFIT: u = u1 + U + u2 * Xu + u3 * UB + u4 * Xu * UB + delta u1=.1, u2=.02, u3=0.02 + +fit b1 = 0.0, b2=0.30, b3=-0.08 +const b4 = 0.0 +BFIT: b = u1 + B + b2 * Xb + b3 * BV + b4 * Xb * BV + delta b1=.1, b2=.02, b3=0.02 + +fit v1 = 0.0, v2=0.15, v3=0.03 +const v4 = 0.0 +VFIT: v = v1 + V + v2 * Xv + v3 * BV + v4 * Xv * BV + delta v1=.1, v2=.02, v3=0.02 +.fi + +.endhelp -- cgit