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

.help mkapfile Apr93 photcal
.ih
NAME
mkapfile -- prepare an aperture corrections file from a list of APPHOT
photometry files using the daogrow algorithm
.ih
USAGE
mkapfile photfiles naperts apercors
.ih
PARAMETERS
.ls photfiles
A list of APPHOT photometry files containing the images names or image ids, x-y
coordinates, filter ids, exposure times, airmasses, aperture radii,
magnitudes, and magnitude errors
of all the objects to be used to compute the aperture corrections.
.le
.ls naperts
The number of aperture radii for which aperture radii, magnitudes, and
magnitude errors are to be extracted from \fIphotfiles\fR.
.le
.ls apercors
The name of the output text file containing the aperture
corrections computed between \fIsmallap\fR and \fIlargeap\fR
for each image in \fIphotfiles\fR.
.le
.ls smallap = 1
The index of the smallest extracted aperture for which the aperture 
correction is to be computed.
.le
.ls largeap = 0
The index of the largest extracted aperture for which the aperture 
correction is to be computed. If \fIlargeap\fR is 0, then
the largest aperture is \fInaperts\fR.
.le
.ls magfile = ""
The name of an optional output text file containing the magnitudes
of all the stars in \fIphotfiles\fR, corrected to the aperture \fIlargeap\fR
by using the measured magnitude and computed aperture correction at
which the estimated error is a minimum.
.le
.ls logfile = ""
The name of an optional output text file containing details of the curve
of growth model fit for each image in \fIphotfiles\fR. If \fIlogfile\fR is
"", no file is written.  If \fIappend\fR = "no" a new logfile is written, if
"yes" output is appended to an existing logfile.
.le
.ls plotfile = ""
The name of an optional output plot file containing plots of the
curve of growth model fit, the fit residuals versus aperture radius,
magnitude inside the first aperture, x coordinate, and y coordinate,
and the aperture correction versus aperture radius for each image
in \fIphotfiles\fR. If \fIplotfile\fR is "", no file is written.
If \fIappend\fR = "no" a new plotfile is written, if
"yes" output is appended to an existing plotfile.
.le
.ls append = no
Open \fIlogfile\fR and/or \fIplotfile\fR in append mode ?
.le
.ls obsparams = ""
The name of an optional input text file containing the correct filter ids,
exposure times, and airmasses for each image whose values are either
undefined or incorrectly stored in \fIphotfiles\fR. The observing parameters
for each image are listed in \fIobsparams\fR,
1 image per line with the image name in column 1 and the filter id,
exposure time, and airmass in
\fIobscolumns\fR. The image names must match those in \fIphotfiles\fR.
.le
.ls obscolumns = "2 3 4 5"
The list of numbers separated by commas or whitespace specifying which
columns in the text file \fIobsparams\fR contain the correct filter ids,
exposure times, airmasses, and times of observation respectively. The
number 0 can be used as
a place holder in the obscolumns string. For example to correct only
the \fIphotfiles\fR airmass values, \fIobscolumns\fR should be set to
"0 0 column 0", where column is the airmass column number.
.le
.ls maglim = 0.10
The maximum magnitude error permitted in the input magnitude measurements.
Data at and following the first aperture radius whose associated magnitude
measurement has an error greater than \fImagerr\fR is rejected on input.
.le
.ls nparams = 3
The number parameters in the five parameter curve of growth model to be fit.
The remaining parameters 5 - nparams parameters are held constant.
For \fInparams\fR = 3, the parameters \fIswings\fR,
\fIpwings\fR, and \fIpgauss\fR are fit, and \fIrgescale\fR and 
and \fIxwings\fR maintain their default values.
\fINparams\fR must be greater than or equal to one.
.le
.ls swings = 1.2
The slope of the power law component of the analytic curve of growth model
describing the seeing independent part of the stellar profile. For a
physically reasonable profile \fIswings\fR must be greater than 1.
.le
.ls pwings = 0.1
The fraction of the total power in the seeing independent
part of the stellar profile, if \fIxwings\fR is 0.0.
.le
.ls pgauss = 0.5
The fraction of the total power in the seeing dependent part of the
profile contained in the gaussian rather than the exponential component
of the analytic curve of growth function.
.le
.ls rgescale = 0.9
The ratio of the exponential to the gaussian radial scale
lengths in the seeing dependent part of the profile.
In practice the curve of growth model fits for most data do not depend
significantly on this parameter and it can be left at its default value.
.le
.ls xwings = 0.0
A parameter describing the effect of airmass on the total power 
in the seeing independent part of the stellar profile, where this quantity
is defined as defined as \fIpwings\fR + \fIxwings\fR * \fIairmass\fR.
.le
.ls interactive = yes
Fit the curve of growth interactively ?
.le
.ls verify = no
Verify interactive user input ? This option is used only if \fIobsparams\fR
is set to the standard input STDIN.
.le
.ls gcommands = ""
The interactive graphics cursor.
.le
.ls graphics = "stdgraph"
The default graphics device.
.le

.ih
DESCRIPTION

MKAPFILE takes a list of APPHOT photometry files \fIphotfiles\fR, 
containing the image names, x and y coordinates, filter ids, exposure times,
airmasses, aperture radii, measured magnitudes, and magnitude errors for
one or more stars in one or more images, computes the aperture correction
between the apertures \fIsmallap\fR and \fIlargeap\fR for each image using
a weighted average of the computed model curve of growth and the observed
curve of growth, and writes the computed aperture corrections
to \fIapercors\fR.

MKAPFILE computes the aperture corrections by performing the following steps:
1) extracts the image names,  x and y coordinates, filter ids, exposure
times, airmasses, times of observation, and \fInaperts\fR aperture radii,
measured magnitudes,
and magnitude errors for all the objects in \fIphotfiles\fR, 2) rejects data
for all aperture radii greater than any aperture radius for which the magnitude
or magnitude error is INDEF, the magnitude error is > \fImaglim\fR,
or the number of apertures left containing good data is < 2, 
3) adds in quadrature a magnitude error of 0.001 magnitudes to the extracted
magnitude errors, 4) edits any incorrect or undefined values of
the filter id, exposure time, airmass, and time of observation
in \fIphotfiles\fR using the values
in \fIobsparams\fR if defined, or default values of INDEF, 1.0, 1.25, and INDEF
respectively, 5) computes the theoretical and observed curve of growth
curve for each image, 6) computes the adopted curve of growth for each
image by combining the theoretical and observed curves with weights that
favor the observed curve at smaller aperture radii and the theoretical curve
at larger aperture radii, 7) integrates the adopted growth curve between
the \fIsmallap\fR and \fIlargeap\fR apertures to
compute the final aperture correction, 8) writes the results for each image
to \fIapercors\fR, 9) optionally computes magnitudes for all the stars
in \fIphotfiles\fR corrected to \fIlargeap\fR using the observed magnitude
and computed correction for which the signal to noise is highest,
10) optionally writes a \fIlogfile\fR containing the details of the
fit for all the individual images, 11) optionally writes a file of
plots of the fit, the residuals, and the curve of growth for all the
images.

MKAPFILE extracts the fields/columns IMAGE, XCENTER, YCENTER, IFILTER,
ITIME, XAIRMASS, OTIME, RAPERT, MAG and MERR from \fIphotfiles\fR.
The number of aperture radii,
magnitudes, and magnitude errors extracted are specified by \fInaperts\fR.
For example if \fInaperts\fR
is 15, then the first 15 values of RAPERT, MAG, and MERR are extracted
from \fIphotfiles\fR.

Values of the filter ids, exposure times, airmasses, and times of
observation which are undefined
or incorrect in \fIphotfiles\fR, can be entered or corrected by reading values
from the file \fIobsparams\fR, a simple multi-column text file with a
format specified by \fIobscolumns\fR.
If no values are read from \fIphotfiles\fR or \fIobsparams\fR, default values
for the filter id, exposure time, airmass, and time of observation
of "INDEF", 1.0, 1.25, and INDEF respectively will be assigned.
It must be emphasized that the airmass is actually used in the curve of
growth analysis only if \fInparams\fR is equal to
5, and that the quantities filter id, exposure time, and time of observation
are not used in
the analysis at all. However if the user should wish to use the corrected
magnitudes optionally computed and written to \fImagfile\fR in any subsequent
analysis it is important to include the correct values of
these quantities in \fImagfile\fR. 

If \fIinteractive\fR is "yes", the user can interact with the curve of
growth fitting process by examining plots of the model fit, the residuals
versus aperture radius, magnitude in the first aperture, x and y coordinates,
and the aperture correction
as a function of radius, by changing the number of parameters to be fit and
their initial values, deleting and undeleting points with the graphics
cursor, refitting the model curve of growth and reexamining the results
until satisfied. Users should realize when deleting or undeleting points
with the graphics cursor that all
the apertures above the marked point will be deleted or undeleted.

The output aperture corrections file \fIapercors\fR is a simple text
file containing the image name in column 1, the aperture correction
computed from \fIsmallap\fR to \fIlargeap\fR in column 2, and the
estimated error in the aperture correction in column 3.
The sign of the aperture correction is such that the
correction must be added to the observed magnitude to compute the corrected
magnitude. \fIApercors\fR is written in a form suitable for input to
the MKNOBSILE, MKOBSFILE, or OBSFILE tasks.

If \fImagfile\fR is not "", a file containing the image name, x and y
position, filter id, exposure time, airmass, time observation,
magnitude corrected to
\fIlargeap\fR using the observed magnitude and computed correction at the
aperture radius with the highest signal-to-noise ratio, the associated
magnitude error, and the radius to which the correction was made,
for all the stars in all the images in \fIphotfiles\fR.
\fIMagfile\fR is written in a form suitable for input to the OBSFILE task.

If \fIlogfile\fR is not "", all the details and diagnostics of the
curve of growth fit are logged either to a new file, if \fIappend\fR = "no"
or to a previously existing file, \fIappend\fR = "yes". The output
consists of: 1) a banner listing
the date, time, and \fIapercors\fR for which the entry is relevant, 2)
a listing of the number of parameters \fInparams\fR in the five parameter
curve of growth model to be fit, the initial values of all the parameters, and
the small and large aperture numbers, 3) the fitted values of the
curve of growth model parameters and their errors where parameters which
were not fit have zero-valued errors, 4) the computed seeing radius
for each image,
5) the theoretical, observed, and adopted curves of growth and
their associated errors, 6) the aperture correction to  largeap,
the estimated total aperture correction to an
aperture radius twice the largest aperture radius, and the estimated error
in the aperture correction, 7) the aperture
correction from \fIsmallap\fR to \fIlargeap\fR, 8) for each star
in the image the observed magnitudes, magnitude corrected to the largest
aperture, and magnitude corrected to twice the largest aperture, and
finally, 9) a summary of the mean adopted curve of growth, the mean residual,
and the mean residual squared for all the data for all the images
as a function of aperture radius.

If \fIplotfile\fR is not "", plots of the final curve of growth model fit,
residuals as a function of aperture radius, magnitude, x, y, and the
aperture correction to the largest aperture \fIlargeap\fR
for each image in \fIphotfiles\fR are saved in the plot metacode file
\fIplotfile\fR..

.ih
CURSOR COMMANDS

The following commands are available in interactive graphics cursor mode.

.nf
	Keystroke Commands 

?	Print help
w	Print computed aperture correction
c	Print coordinates of star nearest cursor
f	Compute a new fit
d	Delete point(s) nearest the cursor
u	Undelete point(s) nearest the cursor
m	Plot the observed and model cog versus radius
r	Plot the cog fit residuals versus radius
b	Plot the cog fit residuals versus magnitude
x	Plot the cog residuals versus the x coordinate
y	Plot the cog residuals versus the y coordinate
a	Plot the aperture correction versus radius
g	Redraw the current plot
n	Move to the next image
p	Move to the previous image
q	Quit task

	Colon commands

:show   parameters   Show the initial cog model parameter values
:show   model	     Show the fitted cog model parameters
:show   seeing       Show the computed seeing radii for all images
:image  [value]      Show/set the image to be analyzed

	Colon Parameter Editing Commands

:smallap   [value]  Show/set the index of the smallest aperture
:largeap   [value]  Show/set the index of the largest aperture
:nparams   [value]  Show/set the number of cog model parameters to fit 
:swings	   [value]  Show/set initial power law slope of stellar wings
:pwings	   [value]  Show/set fraction of total power in stellar wings 
:pgauss	   [value]  Show/set fraction of total core power in gaussian 
:rgescale  [value]  Show/set ratio of exp to gauss radial scales
:xwings	   [value]  Show/set the extinction coefficient
.fi

.ih
ALGORITHMS

The algorithm used to compute the aperture correction is the DAOGROW
algorithm developed by Peter Stetson (1990, see the references section).

In this algorithm the stellar profile is approximated by the following
3 component model where P, G, E denote the power law, gaussian, and
exponential analytic components of the model respectively. The subscript i
denotes quantities that are a function of each image. 

.nf

    I[r,X[i];RO[i],swings,pwings,pgauss,regscale,xwings] =
	(pwings + X[i] * xwings) * P[r;swings] + (1 - pwings - X[i] *
	xwings) * (pgauss * G[r;RO[i]] + (1 - pgauss) *
	E[r;rgescale,RO[i]])

    P[r;swings] = mnorm * (1 + r ** 2) ** swings
          mnorm = (swings - 1) / PI

    G[r;RO[i]] = gnorm * exp (-0.5 * r ** 2 / RO[i] ** 2)
         gnorm = 1 / (2 * PI * RO[i] ** 2)

    E[r;RO[i]] = hnorm  * exp (-r / (rgescale * RO[i]))
         hnorm = 1 /  (2 * PI * (rgescale * RO[i]) ** 2) 

.fi

This equation is actually applied to the magnitude differences between
apertures where the observed magnitude differences are computed as follows
for image i, star j, and aperture k.

.nf

    mdiff[i,j,k] = m[i,j,k] - m[i,j,k-1]           k=2,..,naperts

.fi


The observed differences are fit by least-squares techniques to 
to the theoretical model differences represented by the following equation.

.nf

diff[i,j,k] = -2.5 * log10 (integral (2 * PI * r * I) from 0 to r[k] /
          integral (2 * PI * r * I) from 0 to r[k-1])

.fi

The integrals of the three model components P, G, and E are the following.

.nf

    integral (2 * PI * r * P) = 1 - (1 + r ** 2) ** -swings

    integral (2 * PI * r * G) = 1 - exp (-r ** 2 / (2 * RO[i] ** 2))

    integral (2 * PI * r * H) = 1 + (1 + r / (rgescale * RO[i]) *
                          exp (-r / (rgescale * RO[i]))

.fi

In a given run of MKAPFILE the seeing radius
RO[i] is fit separately for each image, but the parameters swings, pwings,
pgauss, rgescale, and xwings are fit to the entire data set. Therefore
the RO[i] values define a family curves, each differing from the other
by the seeing radius RO[i] alone. It turns out that for most data the
fits do not depend significantly on the \fIrgescale\fR and \fIxwings\fR
parameters.  Therefore by default \fInparams\fR is set to 3 and
\fIrgescale\fR and \fIxwings\fR are set to default values of 0.9 and 0.0
respectively.

After the theoretical and observed growth curves are computed for
each image, they are combined to produce an adopted growth curve. The
weighting scheme used in the combining process is such that at small radii
where the observed magnitude differences have the smallest errors,
the observed values,
are favored, and at large radii  the theoretical curve is favored. At
all points in the computation of the theoretical curve, the observed curve,
and the adopted curve, tests are made for deviant data points and these
are down-weighted. The adopted curve is integrated between \fIsmallap\fr
and \fIlargeap\fR to produce the aperture correction for each image.

Because the error in the observed magnitudes grows rapidly toward
larger radii, while the error in the aperture correction grows
rapidly toward smaller radii, the combined error for the star will
have some minimum value, usually at an intermediate aperture. If
\fImagfile\fR is not "", the magnitudes corrected to \fIlargeap\fR
using the observed magnitude and correction where the  error
is lowest are written to \fImagfile\fR, along with the image id, x and y
coordinates, filter ids, exposure times, airmasses, and errors in the
magnitude. This file can be read into the OBSFILE program so as to
create a photometry catalog suitable for input into PHOTCAL.


.ih
REFERENCES

A full description of the DAOGROW algorithm used by MKAPFILE can be
found in the article "On the Growth-Curve Method for Calibrating
Stellar Photometry with CCDs" by Peter Stetson in PASP 102, 932
(1990).

.ih
EXAMPLES

1. Prepare an aperture corrections file from a set of observations
from 5 different data frames taken in a single night.

.nf
	ph> mkapfile *.mag.* 15 apercor

	    ... plot of the cog for the first image will appear

	    ... type r to examine fit residuals versus radius

	    ... type a to examine the aperture correction curve
		versus radius

	    ... type n to look at results for next image

	    ... type d to remove a discrepant point

	    ... type f to refit the cog

	    ... type r to examine the residuals for this image

	    ... type p to recheck the residuals for the first image

	    ... step through the remaining image deleting points and
		refitting as necessary

	    ... type q to quit

	    ... the compute aperture corrections will appear in apercor
.fi

2. Repeat the previous example in non-interactive mode saving all the
details and plots of the fit in the log and plot file respectively.

.nf
	ph> mkapfile *.mag.* 15 apercor inter- logfile=apercor.log\
	    plotfile=apercor.plot

	ph> page apercor.log

	    ... page through the log file

	ph> gkiextract apercor.plot "1-25" | stdplot

	    ... send all the plots of the fit to the default plotter
.fi

3. Compute the magnitudes corrected to largeap, of all the standard
stars observed in a night using the observed magnitude and computed magnitude
correction at the aperture radius with the lowest error.
Assume that the filter ids (U,B,V), exposure times, and airmasses were
all present and correct in the photometry files.

.nf
	ph> mkapfile stdfiles 15 apercor inter- magfile="stdfiles.ap"\
	    logfile=apercor.log plotfile=apercor.plot

	ph> obsfile stdfiles.ap "1,2,3,4,5,6,7,8,9" "U,B,V" imsets stdobs 

	    ... create a standard star observations file suitable for
		input to the photcal package
.fi

.ih
TIME REQUIREMENTS
.ih
BUGS
.ih
SEE ALSO
apfile, mknobsfile,mkobsfile,obsfile
.endhelp