STScI Logo

mkapfile photcal


NAME · USAGE · PARAMETERS · DESCRIPTION · CURSOR_COMMANDS · ALGORITHMS
REFERENCES · EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

mkapfile -- prepare an aperture corrections file from a list of APPHOT photometry files using the daogrow algorithm

USAGE

mkapfile photfiles naperts apercors

PARAMETERS

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.
naperts
The number of aperture radii for which aperture radii, magnitudes, and magnitude errors are to be extracted from photfiles .
apercors
The name of the output text file containing the aperture corrections computed between smallap and largeap for each image in photfiles .
smallap = 1
The index of the smallest extracted aperture for which the aperture correction is to be computed.
largeap = 0
The index of the largest extracted aperture for which the aperture correction is to be computed. If largeap is 0, then the largest aperture is naperts .
magfile = ""
The name of an optional output text file containing the magnitudes of all the stars in photfiles , corrected to the aperture largeap by using the measured magnitude and computed aperture correction at which the estimated error is a minimum.
logfile = ""
The name of an optional output text file containing details of the curve of growth model fit for each image in photfiles . If logfile is "", no file is written. If append = "no" a new logfile is written, if "yes" output is appended to an existing logfile.
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 photfiles . If plotfile is "", no file is written. If append = "no" a new plotfile is written, if "yes" output is appended to an existing plotfile.
append = no
Open logfile and/or plotfile in append mode ?
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 photfiles . The observing parameters for each image are listed in obsparams , 1 image per line with the image name in column 1 and the filter id, exposure time, and airmass in obscolumns . The image names must match those in photfiles .
obscolumns = "3 4 5"
The list of numbers separated by commas or whitespace specifying which columns in the text file obsparams 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 photfiles airmass values, obscolumns should be set to "0 0 column 0", where column is the airmass column number.
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 magerr is rejected on input.
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 nparams = 3, the parameters swings , pwings , and pgauss are fit, and rgescale and and xwings maintain their default values. Nparams must be greater than or equal to one.
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 swings must be greater than 1.
pwings = 0.1
The fraction of the total power in the seeing independent part of the stellar profile, if xwings is 0.0.
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.
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 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.
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 pwings + xwings * airmass .
interactive = yes
Fit the curve of growth interactively ?
verify = no
Verify interactive user input ? This option is used only if obsparams is set to the standard input STDIN.
gcommands = ""
The interactive graphics cursor.
graphics = "stdgraph"
The default graphics device.

DESCRIPTION

MKAPFILE takes a list of APPHOT photometry files photfiles , 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 smallap and largeap 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 apercors .

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 naperts aperture radii, measured magnitudes, and magnitude errors for all the objects in photfiles , 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 > maglim , 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 photfiles using the values in obsparams 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 smallap and largeap apertures to compute the final aperture correction, 8) writes the results for each image to apercors , 9) optionally computes magnitudes for all the stars in photfiles corrected to largeap using the observed magnitude and computed correction for which the signal to noise is highest, 10) optionally writes a logfile 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 photfiles . The number of aperture radii, magnitudes, and magnitude errors extracted are specified by naperts . For example if naperts is 15, then the first 15 values of RAPERT, MAG, and MERR are extracted from photfiles .

Values of the filter ids, exposure times, airmasses, and times of observation which are undefined or incorrect in photfiles , can be entered or corrected by reading values from the file obsparams , a simple multi-column text file with a format specified by obscolumns . If no values are read from photfiles or obsparams , 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 nparams 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 magfile in any subsequent analysis it is important to include the correct values of these quantities in magfile .

If interactive 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 apercors is a simple text file containing the image name in column 1, the aperture correction computed from smallap to largeap 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. Apercors is written in a form suitable for input to the MKNOBSILE, MKOBSFILE, or OBSFILE tasks.

If magfile is not "", a file containing the image name, x and y position, filter id, exposure time, airmass, time observation, magnitude corrected to largeap 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 photfiles . Magfile is written in a form suitable for input to the OBSFILE task.

If logfile is not "", all the details and diagnostics of the curve of growth fit are logged either to a new file, if append = "no" or to a previously existing file, append = "yes". The output consists of: 1) a banner listing the date, time, and apercors for which the entry is relevant, 2) a listing of the number of parameters nparams 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 smallap to largeap , 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 plotfile 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 largeap for each image in photfiles are saved in the plot metacode file plotfile ..

CURSOR COMMANDS

The following commands are available in interactive graphics cursor mode.

	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

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.


    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) 

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.


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

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


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])

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


    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]))

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 rgescale and xwings parameters. Therefore by default nparams is set to 3 and rgescale and xwings 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 smallap and largeap 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 radidly toward smaller radii, the combined error for the star will have some minimum value, usually at an intermediate aperture. If magfile is not "", the magnitudes corrected to largeap using the observed magnitude and correction where the error is lowest are written to magfile , 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.

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

EXAMPLES

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

	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

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.

	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

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.

	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

TIME REQUIREMENTS

BUGS

SEE ALSO

apfile, mknobsfile,mkobsfile,obsfile


Search Form · STSDAS