REFERENCES · EXAMPLES · TIME_REQUIREMENTS · BUGS · SEE_ALSO
apfile -- prepare an aperture corrections file from a list of photometry files using the daogrow algorithm
apfile photfiles incolumns naperts apercors
- A list of text files containing the images names or image ids, x and 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. Photfiles are assumed to be the output of the user's own digital photometry program. All the files in photfiles must have the format specified by incolumns .
- A list of ten numbers separated by commas or whitespace specifying which columns in photfiles contain the following quantities: the image name or image id, x coordinate, y coordinate, filter id, exposure time, airmass, time of observation, first aperture radius, magnitude measured inside the first aperture radius, magnitude error measured inside the first aperture radius respectively.
- The number of aperture radii for which aperture radii, magnitudes, and magnitude errors are to be extracted from photfiles .
- 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, airmasses, and times of observation 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, airmass, and time of exposure 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 of 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.
APFILE takes a list of user generated text files photfiles , containing image names or ids, x and y coordinates, filter ids, exposure times, airmasses, times of observation, 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 results to apercors .
APFILE computes the aperture corrections by performing the following steps: 1) extracts the image names or ids, 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.
The parameter incolumns describes the format of photfiles . Incolumns is a list of 9 numbers separated by commas or whitespace which specify the columns containing the following quantities: the image name or id, , the x coordinate, the y coordinate, the filter id, the exposure time, the airmass, the time of observation, the first aperture radius extracted, the first measured magnitude extracted, and the first magnitude error extracted. The number of aperture radii, magnitudes, and magnitude errors extracted are specified by naperts . For example if incolumns is "1,3,4,0,0,2,5,0,20,35" and naperts is 15, then the image name is assumed to be in column 1, the x and y coordinates in columns 3 and 4, the filter id, exposure time, and time of exposure are missing and will be assigned values of INDEF, 1.0, and INDEF respectively, the airmass is in column 2, the aperture radii in columns 5-19, the magnitudes in columns 20-34, and the magnitude errors in columns 35-49. The aperture radii must be written in photfiles in increasing order of size. The columns image name, x coordinate, y coordinate, aperture radii, magnitude, and magnitude error are mandatory and must be present in photfiles . The filter id, exposure time, and airmass columns are optional in which case they may be represented by a "0" in the appropriate place in incolumns .
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, "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 and exposure time 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 must realize that when deleting and undeleting points with the graphics cursor data for all the apertures above the one being deleted or undeleted will also be deleted.
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 or id, x and y position, filter id, exposure time, airmass, magnitude corrected to largeap using the observed magnitude and computed correction at the aperture radius with the highest signal-to-noise ratio, and the associated magnitude error, 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 ..
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
The algorithm used to compute the aperture correction is the DAOGROW algorithm developed by Peter Stetson (1990).
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 APFILE 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.
A full description of the DAOGROW algorithm used by APFILE 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).
1. Prepare an aperture corrections file from a set of observations from 5 different data frames taken in a single night. The input photometry files contain the image ids in column 1, the x and y positions in columns 3 and 4, the airmass in column 2, and the 15 aperture radii, magnitudes, and magnitude errors in columns 5-19,20-34,35-49 respectively.
ph> apfile photfiles "1,3,4,0,0,2,0,5,20,35" 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> apfile photfiles "1,3,4,0,0,2,0,5,20,35" 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 format of the input photometry files is the same as in the two previous examples and the the filter ids (U,B,V), exposure times, and airmasses were all present and correct in the photometry files.
ph> apfile stdfiles "1,3,4,0,0,2,0,5,20,35" 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