| apfile | photcal | apfile |
apfile -- prepare an aperture corrections file from a list of photometry files using the daogrow algorithm
apfile photfiles incolumns naperts apercors
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
mkapfile, mknobsfile,mkobsfile,obsfile