THE_TRANSFORMATION_SECTION · OPTIONAL_TRANSFORMATION_SECTION_FEATURES
THE_PHOTCAL_LANGUAGE_GLOSSARY · EXAMPLES
INTRODUCTION
The configuration file is a text file which describes how the input data is organized in the input standard star catalog and the observations files, and defines the form of the transformation equations required to convert from the observed or instrumental indices to the standard indices.
The catalog file contains the standard indices for a set of standard stars, referenced in the catalog by a name called the matching name . The matching name must be 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 observations 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 catalog section which describes the format of the catalog file, the observations section which describes the format of the observations file, and the transformation section 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 catalog and observations sections 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 transformation section 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 (the set equations ), define the derivatives of the transformation equations to be fit with respect to the parameters (the derivative equations or delta declarations ), define expressions for weights and errors (the weight and error equations ), and define the default expressions to be plotted during the interactive fitting process (the plot equation ).
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 catalog , followed by any number of name and error(name), column associations.
 Syntax

catalog name number error(name) number
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 error , 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.
 Example

# Sample catalog section for the UBV system. catalog V 2 error(V) 3 BV 4 error(BV) 5 UB 6 error(UB) 7
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 observation , followed by any number of name and error (name) column associations.
 Syntax

observation name number error (name) number
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 error , 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.
 Example

# 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
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 transformation , followed by the list of parameter declarations, followed by the transformation equation.
 Syntax

transformation fit parameter = value, parameter = value, ... constant parameter = value, parameter = value, ... label : expression = expression (function) (fit)
The fit 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 constant 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 transformation equations are composed of three elements: the equation label, the function expression, and the fit expression.
The label 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 function 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 fit 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.
 Example

# 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
OPTIONAL TRANSFORMATION SECTION FEATURES
The transformation section may also be used, OPTIONALLY, to define temporary variables (the set equations ), define explicitly the derivatives of the transformation equations to be fit with respect to the fit and constant parameters (the derivative equations or delta declarations ), define expressions for the weights and/or errors (the weight and error equations ), and define an equation to be plotted (the plot equation ).
 The Set Equation
The set equations 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.

syntax set name = expression
A set equation declaration begins with the set 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.

example set U = V + BV + UB
 The Delta Declaration and the Derivative Equations
The delta declaration statement or the derivative equation are used to tell the nonlinear 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 delta declaration syntax, or to supply explicit expressions for the derivatives with respect to the parameters, using the derivative 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 nonanalytic expressions the delta syntax is required.

syntax delta parameter = value, parameter = value or derivative (label, parameter) = expression
A delta declaration begins with the delta 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 emprically. All the delta values must be greater than zero.
A derivative equation begins with the keyword derivative , 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.

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)
 Weight equation
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.

weight (label) = expression min = expression max = expression
The weight equation begins with the weight 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 immeditiatly followed by the min and max 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.

example VFIT: V = v + v1 + v2 * x + v3 * (b  v) weight (VFIT) = 1.0 / sigmav ** 2
 The Plot Equation
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 resdiduals versus function plot.

syntax plot (label) = expression, expression (x axis) (y axis)
A plot equation begins with the plot 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.

example VFIT: V = v + v1 + v2 * x + v3 * (b  v) plot (VFIT) = b  v, V  (v + v1 + v2 * x + v3 * (b  v))
 Error equation
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.

syntax error (label) = expression min = expression max = expression
An error equation begins with the error 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 min and max 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.

example VFIT: V = v + v1  v2 * x + v3 * (b  v) error (VFIT) = sigmav
THE PHOTCAL LANGUAGE GLOSSARY
The configuration file consists of a series of instructions, written by the user in a minilanguage 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 constants 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 identifier (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 keyword 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 name 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 label 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 function is a builtin mathematical function that can be used in expressions.
The following identifiers are reserved by the program to name keywords and functions . These reserved identifiers cannot be used to name user variables or label equations.
# 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
Keywords may be abbreviated to up to three characters but names, labels, and functions may not be abbreviated.
The following arithmetic operators are recognized by PHOTCAL: "+" (addition), "" (substraction), "*" (multiplication), "/" (division), "**" (exponentiation), "" (minus sign), and "+" (plus sign). The arithmetic operators follow normal FORTRAN rules of precedence
Expressions can be any legal arithmetic FORTRAN expression, using the legal names, operators, functions, or constants defined above. Parenthesis "(" and ")" may be used as well.
Comments 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 line 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.
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.
# 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)
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.
catalog V 2 # V magnitude BV 3 # BV color UB 4 # UB color error(V) 5 # error in V magnitude error(BV) 6 # error in BV color error(UB) 7 # error in UB 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