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 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.
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.
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.
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.
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.
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.
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 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.
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.
The delta declaration statement or the derivative 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 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 non-analytic expressions the
delta syntax is required.
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.
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.
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.
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.
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.
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.
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.
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 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 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.
Example 1. A sample configuration file for reducing UBV photoelectric
photometry. Note the optional use of the delta declaration statement
and the weight equations.
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.
THE CATALOG SECTION
catalog
name number
error(name) number
.le
# Sample catalog section for the UBV system.
catalog
V 2
error(V) 3
BV 4
error(BV) 5
UB 6
error(UB) 7
.le
THE OBSERVATION SECTION
observation
name number
error (name) number
.le
# 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
.le
THE TRANSFORMATION SECTION
Syntax
transformation
fit parameter = value, parameter = value, ...
constant parameter = value, parameter = value, ...
label : expression = expression
(function) (fit)
.le
# 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
.le
OPTIONAL TRANSFORMATION SECTION FEATURES
syntax
set name = expression
.le
example
set U = V + BV + UB
.le
The Delta Declaration and the Derivative Equations
syntax
delta parameter = value, parameter = value
or
derivative (label, parameter) = expression
.le
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)
.le
weight (label) = expression
min = expression max = expression
.le
example
VFIT: V = v + v1 + v2 * x + v3 * (b - v)
weight (VFIT) = 1.0 / sigmav ** 2
.le
syntax
plot (label) = expression, expression
(x axis) (y axis)
.le
example
VFIT: V = v + v1 + v2 * x + v3 * (b - v)
plot (VFIT) = b - v, V - (v + v1 + v2 * x + v3 * (b - v))
.le
syntax
error (label) = expression
min = expression max = expression
.le
example
VFIT: V = v + v1 - v2 * x + v3 * (b - v)
error (VFIT) = sigmav
.le
THE PHOTCAL LANGUAGE GLOSSARY
# 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
EXAMPLES
# 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)
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
This page automatically generated from the iraf .hlp file. If you
would like your local iraf package .hlp files converted into HTML
please contact Dave Mills at NOAO.dmills@noao.edu