Initial commit

1 files changed, 502 insertions, 0 deletions

diff --git a/noao/digiphot/photcal/doc/apfile.hlp b/noao/digiphot/photcal/doc/apfile.hlp
new file mode 100644
index 00000000..51c64034
--- /dev/null
+++ b/noao/digiphot/photcal/doc/apfile.hlp
@@ -0,0 +1,502 @@
+.help apfile Apr93 photcal
+.ih
+NAME
+apfile -- prepare an aperture corrections file from a list of photometry
+files using the daogrow algorithm
+.ih
+USAGE
+apfile photfiles incolumns naperts apercors
+.ih
+PARAMETERS
+.ls photfiles
+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.
+\fIPhotfiles\fR are assumed to be the output of the user's own digital
+photometry program. All the files in \fIphotfiles\fR must have the format
+specified by \fIincolumns\fR.
+.le
+.ls incolumns
+A list of ten numbers separated by commas or whitespace specifying
+which columns in \fIphotfiles\fR 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.
+.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, airmasses, and times of observation 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, airmass, and time of exposure 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 of 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
+
+APFILE takes a list of user generated text files \fIphotfiles\fR, 
+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 \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 results to \fIapercors\fR.
+
+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 \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.
+
+The parameter \fIincolumns\fR describes the format of \fIphotfiles\fR.
+\fIIncolumns\fR 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 \fInaperts\fR.
+For example if \fIincolumns\fR is "1,3,4,0,0,2,5,0,20,35" and \fInaperts\fR
+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
+\fIphotfiles\fR 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 \fIphotfiles\fR. 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 \fIincolumns\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, "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 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 \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 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 \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 or id, x and y
+position, filter id, exposure time, airmass, magnitude corrected to
+\fIlargeap\fR 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 \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).
+
+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 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 \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 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).
+
+.ih
+EXAMPLES
+
+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.
+
+.nf
+	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
+.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> 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
+.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
+format of the input photometry files is the same as in the two previous
+examples and the filter ids (U,B,V), exposure times, and airmasses were
+all present and correct in the photometry files.
+
+.nf
+	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
+.fi
+
+.ih
+TIME REQUIREMENTS
+.ih
+BUGS
+.ih
+SEE ALSO
+mkapfile, mknobsfile,mkobsfile,obsfile
+.endhelp