diff options
Diffstat (limited to 'noao/digiphot/photcal/doc')
| -rw-r--r-- | noao/digiphot/photcal/doc/apfile.hlp | 502 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/chkconfig.hlp | 42 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/config.hlp | 679 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/evalfit.hlp | 267 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/fitparams.hlp | 633 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/inlfit.hlp | 259 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/invertfit.hlp | 297 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/mkapfile.hlp | 473 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/mkcatalog.hlp | 220 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/mkconfig.hlp | 451 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/mkimsets.hlp | 356 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/mknobsfile.hlp | 516 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/mkobsfile.hlp | 519 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/mkphotcors.hlp | 274 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/obsfile.hlp | 511 | ||||
| -rw-r--r-- | noao/digiphot/photcal/doc/pcintro.hlp | 727 |
16 files changed, 6726 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 diff --git a/noao/digiphot/photcal/doc/chkconfig.hlp b/noao/digiphot/photcal/doc/chkconfig.hlp new file mode 100644 index 00000000..be3ed549 --- /dev/null +++ b/noao/digiphot/photcal/doc/chkconfig.hlp @@ -0,0 +1,42 @@ +.help chkconfig Aug91 noao.digiphot.photcal +.ih +NAME +chkconfig -- Check the grammar and syntax of the configuration file +.ih +USAGE +chkconfig config +.ih +PARAMETERS +.ls config +The name of the configuration file to be checked. \fIConfig\fR is the +text file specifying both the format of the input files, and the form of +transformation equations. +.le +.ls verbose = yes +Print detailed diagnostic information on the standard output ? +.le + +.ih +DESCRIPTION + +CHKCONFIG parses the configuration file \fIconfig\fR line by line, +searching for syntax and/or semantic errors. Its primary function is to aid +the user in setting up a complete and correct set of transformation +equations to be fit. CHKCONFIG is run automatically by the task MKCONFIG, +but can also be run stand-alone at any time. + +.ih +EXAMPLES + +Check the configuration file for grammar and syntax errors. + +.nf +ph> chk config +.fi + +.ih +BUGS +.ih +SEE ALSO +mkconfig,fitparams +.endhelp diff --git a/noao/digiphot/photcal/doc/config.hlp b/noao/digiphot/photcal/doc/config.hlp new file mode 100644 index 00000000..7e44ca24 --- /dev/null +++ b/noao/digiphot/photcal/doc/config.hlp @@ -0,0 +1,679 @@ +.help config Aug91 noao.digiphot.photcal +.ih +INTRODUCTION + +The \fIconfiguration file\fR is a text file which describes how the input data +is organized in the input standard star \fIcatalog\fR and the +\fIobservations\fR files, and defines the form of the transformation +equations required to convert from the observed or instrumental indices +to the standard indices. + +The \fIcatalog\fR file contains the standard indices for a set of +standard stars, referenced in the catalog by a name called the \fImatching +name\fR. The matching name must be in the first column of the +catalog and also must be unique, i.e. each catalog file +entry is assumed to be unique. The standard indices may be in any column +other than the first. + +The \fIobservations\fR files contain the observed indices for a +subset of the standard stars and/or program stars, referenced in the +file by a matching name, which must be in the first column of the +observations file. The observed indices may be in any column other than +the first. The names of the standard stars must match those +in the catalog file. +Only standard star observations whose matching names are found in the +catalog file are used to compute the transformation equations. + +The configuration file is divided into three sections: the \fIcatalog +section\fR which describes the format of the catalog file, the +\fIobservations section\fR which describes the format of the observations +file, and the \fItransformation section\fR which defines the form of +the transformation equations. The catalog section must occur before the +observation section in the configuration file, and the observation +section must occur before the transformation section. + +The \fIcatalog\fR and \fIobservations sections\fR are used to assign +names to the columns in the input file. +The named columns can later be referenced in the transformation equations, +by using the names +as though they were variables in a programming language. + +The \fItransformation section\fR is used to define the equations to be solved, +to specify which parameters are to be varied and which are to +be held constant during the fitting process, and to assign initial values +to all of the parameters. +Any number of transformation equations may be defined in the +transformation section. + +The transformation section may also be used, OPTIONALLY, to +define temporary variables (\fIthe set equations\fR), +define the derivatives of the transformation equations +to be fit with respect to the parameters (\fIthe derivative equations or +delta declarations\fR), +define expressions for weights and errors (\fIthe weight and error +equations\fR), and define the default expressions to be plotted +during the interactive fitting process (\fIthe plot equation\fR). + +.ih +THE CATALOG SECTION + +The catalog section is used to assign names to columns in the +standard star catalog, and optionally, to associate error columns with +the named columns. + +The catalog section begins with the keyword \fIcatalog\fR, followed by +any number of name and error(name), column associations. + +.ls Syntax +.nf +catalog + +name number + +error(name) number +.fi +.le + +The first declaration creates a name column number association. +It consists of a name followed +by a column number. The name becomes the variable name +for that column. + +The second declaration creates an error (name) column number association. +It begins with the keyword \fIerror\fR, followed by a name in parentheses +and a column number. +The name must be the name of an input column previously declared in the +catalog section. The error declarations are optional. + +The column number must be a decimal integer greater than two, since +catalog files always reserve the first column for a matching name. +This name is used to match objects in the catalog file with objects in the +observations file. + +.ls Example +.nf +# Sample catalog section for the UBV system. + +catalog + +V 2 +error(V) 3 +BV 4 +error(BV) 5 +UB 6 +error(UB) 7 +.fi +.le + +.ih +THE OBSERVATION SECTION + +The observation section is used to assign names to columns in the +observations files, and to optionally, associate error columns with the +named columns. + +The observations section begins with the keyword \fIobservation\fR, followed by +any number of name and error (name) column associations. + +.ls Syntax +.nf +observation + +name number + +error (name) number +.fi +.le + +The first declaration creates a name column number association. +It consists of a name followed +by a column number. The name becomes the variable name +for that column. + +The second declaration creates an error (name) column number association. +It starts with the keyword \fIerror\fR, followed by a name +in parentheses, and a column number. +The name must be the name of an input column previously declared in the +observation section. The error declarations are optional. + +The column number must be a decimal integer greater two, +since the first column of the observations file is reserved for a matching name. +This name is used to match objects in the observations file with +objects in the catalog file. + +.ls Example +.nf +# Sample observation section for the UBV system. + +observation + +u 2 +error(u) 3 +b 4 +error(b) 5 +v 6 +error(v) 7 +x 8 +.fi +.le + +.ih +THE TRANSFORMATION SECTION + +The transformation section is used to define the transformation equations, +to specify which parameters are to be altered and which are to be +held constant during the fitting process, and to assign initial values +to the parameters. + +The transformation section begins with the keyword \fItransformation\fR, +followed by the list of parameter declarations, +followed by the transformation equation. + +.ls Syntax +.nf +transformation + +fit parameter = value, parameter = value, ... + +constant parameter = value, parameter = value, ... + +label : expression = expression + (function) (fit) +.fi +.le + +The \fIfit\fR keyword begins a list of the parameters to be fit. +The named parameters will be fit if they are present +in a transformation equation. +The fit parameter values are used as the initial guesses for the +parameters. + +The \fIconstant\fR keyword begins a list of the parameters to be held +constant. +The named parameters will not be fit. Instead the values are regarded +as constant values in any transformation equation in which they appear. +Constant parameter declarations are used to fix +values if they are known, or to restrict the degrees +of freedom of the fit. + +All parameters, both fit and constant, must be declared before the first +equations in which they appear. +There may be any number of fit and constant parameter declaration statements. +Redefinitions are allowed, i.e., it is possible to declare a parameter with +the fit keyword, and redefine it later with the constant keyword. +The inverse is also true. + +The \fItransformation\fR equations are composed of three elements: the equation +label, the function expression, and the fit expression. + +The \fIlabel\fR is used to assign a name to the equation and fit expression. +The label can be any name not already in use. The ":" after the label is +necessary to delimit it from the rest of the transformation equation +definition. Labels are used primarily to associate the optional error, +weight and plot equations with the appropriate transformation equations. +However these labels can also be used in expressions belonging +to subsequent equations, an action equivalent to replacing them with the +fit expression they reference, before performing the actual evaluation. + +The \fIfunction\fR expression (left hand side of the "=" sign) is used as a +reference expression, i.e. an expression that has no fitting or +constant parameters in it. The function expression contains only values +computed from the input data which are known before the fit starts. + +The \fIfit\fR expression (right hand side of the "=" sign) is an expression +which contains the parameters, both those to be fit and those that are +fixed. +If this expression contains names defined +in the catalog section , it will be possible to perform the fit, +but will not be possible to apply the transformations in the forward +sense to program observations that don't have matching catalog values. +If the number of transformations equations is greater than or equal to +the total number of catalog variables used in the transformation equations, +it MAY be possible to invert the system of equations and so evaluate +the catalog variables for program objects. + +.ls Example +.nf + +# Sample transformation section for the UBV system + +transform + +# V equation + +fit v1 = 25.0, v2=0.03, v3=-0.17 +VFIT : V = v1 + v + v2 * (b - v) + v3 * x + +# B - V equation + +fit b1 = 2.10, b2 = 1.15, b3=-0.12 +const b4 = 0.0 +BVFIT : BV = b1 + b2 * (b - v) + b3 * x + b4 * (b - v) * x + +# U - B equation + +fit u1 = 3.45, u2 = 1.063, u3=-0.30 +const u4=0.0 +UBFIT : UB = u1 + u2 * (u - b) + u3 * x + u4 * (u - b) * x +.fi +.le + +.ih +OPTIONAL TRANSFORMATION SECTION FEATURES + +The transformation section may also be used, OPTIONALLY, to define +temporary variables (\fIthe set equations\fR), define explicitly the +derivatives of the transformation equations to be fit with respect to the +fit and constant parameters (\fIthe derivative equations or delta +declarations\fR), define +expressions for the weights and/or errors (\fIthe weight and error +equations\fR), and define an equation to be plotted (\fIthe plot equation\fR). + +.ls The Set Equation +.le + +The \fIset equations\fR are used to assign names to expressions. They are +primarily intended for computing quantities not listed explicitly +in the catalog or observation files, but that may be derived from them. + +.ls +.nf +syntax + +set name = expression +.fi +.le + +A set equation declaration begins with the \fIset\fR keyword, +followed by +a name, followed by an equal sign, followed by an expression. +The expression may contain any name defined in the catalog and +observation sections, or any names defined in a previous +set equation. + +In the example below the variables +V, BV and UB were declared in the catalog section, but the user wished +to define a new variable U to simplify the form of one of the +transformation equations. + +.ls +.nf +example + +set U = V + BV + UB +.fi +.le + +.ls The Delta Declaration and the Derivative Equations +.le + +The \fIdelta\fR declaration statement or the \fIderivative\fR equation +are used to tell +the non-linear least squares routines how to compute the derivatives +of the transformation equations with respect to the parameters to be fit. +If the user does +not specify how the derivatives are to be computed, a +default value for delta (see below) is used and the fit proceeds. For most +simple photometric transformations the default delta is entirely adequate, +and no delta statements or derivative expressions are required. + +However the user can elect to specify the derivatives implicitly using +the \fIdelta\fR +declaration syntax, or to supply explicit expressions for the derivatives +with respect to the parameters, using the \fIderivative\fR equation +syntax. For transformation equations which are linearly dependent on +their parameters, or in cases where the derivative expressions are +very complex the delta statement syntax is preferred over the more +correct derivative equation syntax. For non-analytic expressions the +delta syntax is required. + +.ls +.nf +syntax + +delta parameter = value, parameter = value + + or + +derivative (label, parameter) = expression +.fi +.le + +A \fIdelta\fR declaration begins with the \fIdelta\fR keyword, +followed by a list of parameter value associations, where each value +is the region over which the derivative with respect to that parameter +will be computed empirically. All the delta values must be greater than zero. + +A \fIderivative\fR equation begins with the keyword \fIderivative\fR, +followed by +the label of the equation whose derivative is being computed and +the name of the parameter +with respect to which the derivative is being taken in parentheses, finally +followed by the derivative +expression itself. + +If both a derivative equation and a delta statement are given for the same +parameter, the parser will issue a warning message, and the derivative +equation will take precedence over the delta declaration. + +The following example shows how the derivatives for an equation can be +specified in each of the two ways. + +.ls +.nf +example + +VFIT: V = v + v1 + v2 * x + v3 * (b - v) + delta v1=.1, v2=.05, v3=.02 + +or + +VFIT: V = v + v1 - v2 * x + v3 * (b - v) + deriv (VFIT,v1) = 1.0 + deriv (VFIT,v2) = x + deriv (VFIT,v3) = (b - v) +.fi +.le + +.ls Weight equation +.le + +The weight equation can be used to specify the way the weights will be +computed for each data point, +for each transformation equation. The weight equation is optional, and +whether or not the weight expression is actually used by the fitting procedure +depends on the application. The minimum and maximum weight expressions +are also optional. + +.ls +.nf +weight (label) = expression + min = expression max = expression + +.fi +.le + +The \fIweight\fR equation begins with the \fIweight\fR keyword, followed by +the label of the equation in parentheses, followed by an equal sign, +followed by the weight expression. Optionally, +the weight expression can be immediately followed by the \fImin\fR and +\fImax\fR keywords +each of which may be followed by an expression. +The expressions may contain any names declared in the catalog or +observations sections, names defined by a set equation, or parameters declared +in a fit or constant statement. Users should be extremely cautious about +the latter as weights are evaluated before the fit, i.e. before the +fit parameters have assumed their final values. + +In the following example weights are set to 1 over the standard deviation +of the v measurement, sigmav, where sigmav was declared in the observation +section. + +.ls +.nf +example + +VFIT: V = v + v1 + v2 * x + v3 * (b - v) + weight (VFIT) = 1.0 / sigmav ** 2 +.fi +.le + +.ls The Plot Equation +.le + +The plot equation is used to specify the default expressions for the x and y +axes respectively, to be plotted when the transformation equations are fit +interactively. The plot +defined by the plot equation will be in the graphics window +after the initial fit, instead of the default residuals versus function plot. + +.ls +.nf +syntax + +plot (label) = expression, expression + (x axis) (y axis) +.fi +.le + +A \fIplot\fR equation begins with the \fIplot\fR keyword, followed by +the label of the associated transformation equation in parentheses, +followed by an equals +sign, and finally followed by the plot expressions for the x and y axis +separated +by a comma. + +In the following example the user has decided he/she wants the default plot +for the VFIT equation to be a plot of the residuals versus the +observed (b - v) color. +It should be emphasized that the user could also produce the same graph +inside the interactive fitting routines by reprogramming one of the graph +keys. + +.ls +.nf +example + +VFIT: V = v + v1 + v2 * x + v3 * (b - v) + plot (VFIT) = b - v, V - (v + v1 + v2 * x + v3 * (b - v)) +.fi +.le + +.ls Error equation +.le + +The error equation is used to specify the way the error will be computed for +each data point for each transformation. The error equation is optional, and +whether or not it is used by the fitting or evaluation procedures +depends on the application. The minimum and maximum error expressions +are also optional. + +.ls +.nf +syntax + +error (label) = expression + min = expression max = expression +.fi +.le + +An \fIerror\fR equation begins with the \fIerror\fR keyword, followed by +the label of the associated transformation equation in brackets, +followed by an equal sign, +followed by the error expression. Optionally, +the error expression can be followed by the \fImin\fR and \fImax\fR keywords +each of which must be followed by an expression. +The expressions may contain any names declared in the catalog or +observations sections, names defined by a set equation, or parameters declared +in a fit or constant statement. + +In the following example the error for each data point is set equal to the +standard deviation of the v measurement, sigmav, which was declared earlier +in the observation section. + +.ls +.nf +example + +VFIT: V = v + v1 - v2 * x + v3 * (b - v) + error (VFIT) = sigmav +.fi +.le + +.ih +THE PHOTCAL LANGUAGE GLOSSARY + +The configuration file consists of a series of instructions, written by +the user in a mini-language understood by the PHOTCAL parser, which tell +the various PHOTCAL routines +what to do. The basic elements of the language are numerical constants, +identifiers, arithmetic operators, arithmetic expressions, and comment +statements. + +Numerical \fIconstants\fR may be decimal integers or floating point numbers. +Double precision and complex numbers are not supported. The INDEF constant +is not supported, although it is permitted in the input data. + +An \fIidentifier\fR (keyword, name, label, function) is an upper or +lowercase letter, followed by zero or more upper or lowercase letters or +digits. +Identifiers can be of any length up to the maximum text file line length. + +A \fIkeyword\fR is an identifier with special meaning to the PHOTCAL routines. +For example the three identifiers "catalog", "observations", and +"transformation" are used to declare the beginning of the catalog, +observations, and transformation sections of the configuration file. + +A \fIname\fR is a user variable that has either been declared in the +catalog or observation sections of the configuration file, declared as +a parameter using the fit or const declaration statements in the +transformation section of the configuration file, or +defined by a set equation in the transformation section. + +A \fIlabel\fR is an identifier which is assigned to an equation. It is used +to tell the parser which transformation equation, the optional derivative, +weight, error or plot equations are associated with. + +A \fIfunction\fR is a built-in mathematical function that can be +used in expressions. + +The following identifiers are reserved by the program to name +\fIkeywords\fR and \fIfunctions\fR. These reserved identifiers +cannot be used to name user variables or label equations. + +.nf +# keywords + +catalog constant delta derivative +error *extinction fit observations +plot *print set transformation +weight + +*reserved keywords not currently used + +# functions + +abs acos asin atan +cos exp log log10 +sin sqrt tan +.fi + +Keywords may be abbreviated to up to three characters but names, labels, +and functions may not be abbreviated. + +The following arithmetic \fIoperators\fR are recognized by PHOTCAL: +"+" (addition), "-" (subtraction), "*" (multiplication), "/" (division), +"**" (exponentiation), "-" (minus sign), and "+" (plus sign). +The arithmetic operators follow normal FORTRAN rules of precedence + +\fIExpressions\fR can be any legal arithmetic FORTRAN expression, using the +legal names, operators, functions, or constants defined above. +Parenthesis "(" and ")" may be used as well. + +\fIComments\fR may be placed anywhere in the configuration file, as long +as they are preceded by a "#" sign. +All input succeeding this character to the end of the line is skipped. + +Every physical \fIline\fR in the configuration file must be shorter than the +IRAF text file line limit, currently +161 characters, but long constructs, for example a long transformation +equation may span more than one physical line. + +.ih +EXAMPLES + +Example 1. A sample configuration file for reducing UBV photoelectric +photometry. Note the optional use of the delta declaration statement +and the weight equations. + +.nf +# Configuration file for reducing UBV photoelectric photometry. + +catalog + +V 2 # V magnitude +BV 3 # B - V color +UB 4 # U - B color + +observation + +v 2 # v instrumental magnitude +b 3 # b instrumental magnitude +u 4 # u instrumental magnitude +ev 5 # error in v instrumental magnitude +eb 6 # error in b instrumental magnitude +eu 7 # error in u instrumental magnitude +X 8 # airmass + +transformation + +fit v1 = 25.0, v2=0.16, v3=-0.043 +VFIT: V = v1 + v - v2 * X + v3 * (b - v) + delta v1=0.10, v2=0.02, v3=0.02 + weight (VFIT) = 1. / ev ** 2 + +fit b1 = 1.0, b2=0.09, b3=1.06 +BVFIT: BV = b1 - b2 * X + b3 * (b - v) + delta b1=0.10, b2=0.02, b3=0.02 + weight (BFIT) = 1.0 / (ev ** 2 + eb ** 2) + +fit u1 = 2.0, u2=0.300, u3=0.95 +UBFIT: UB = u1 - u2 * x + u3 * (u - b) + delta u1=0.10, u2=0.02, u3=0.02 + weight (UFIT) = 1. / (eb ** 2 + eu ** 2) +.fi + +Example 2. A sample configuration file for reducing UBV CCD photometry. +Note the optional use of the error column declarations in the catalog and +observations sections. The error columns can be used to compute +the weights by the FITPARAMS task. Also note how the set equations are +used to simplify the transformation equations. + +.nf +catalog + +V 2 # V magnitude +BV 3 # B-V color +UB 4 # U-B color +error(V) 5 # error in V magnitude +error(BV) 6 # error in B-V color +error(UB) 7 # error in U-B color + +observation + +ut1 3 # ut time of filter 1 observation +X1 4 # airmass of filter 1 observation +m1 7 # filter 1 instrumental magnitude +error(m1) 8 # error in filter 1 instrumental magnitude +ut2 10 # ut time of filter 2 observation +X2 11 # airmass of filter 2 observation +m2 14 # filter 2 instrumental magnitude +error(m2) 15 # error in filter 2 instrumental magnitude +ut3 17 # ut time of filter 3 observation +X3 18 # airmass of filter 3 observation +m3 19 # filter 3 instrumental magnitude +error(m3) 20 # error in filter 3 instrumental magnitude + + +transformation + +set B = V + BV +set U = V + BV + UB + +fit u1 = 0.0, u2=0.68, u3=-0.05 +const u4 = 0.0 +UFIT: u = u1 + U + u2 * Xu + u3 * UB + u4 * Xu * UB + delta u1=.1, u2=.02, u3=0.02 + +fit b1 = 0.0, b2=0.30, b3=-0.08 +const b4 = 0.0 +BFIT: b = u1 + B + b2 * Xb + b3 * BV + b4 * Xb * BV + delta b1=.1, b2=.02, b3=0.02 + +fit v1 = 0.0, v2=0.15, v3=0.03 +const v4 = 0.0 +VFIT: v = v1 + V + v2 * Xv + v3 * BV + v4 * Xv * BV + delta v1=.1, v2=.02, v3=0.02 +.fi + +.endhelp diff --git a/noao/digiphot/photcal/doc/evalfit.hlp b/noao/digiphot/photcal/doc/evalfit.hlp new file mode 100644 index 00000000..9a256964 --- /dev/null +++ b/noao/digiphot/photcal/doc/evalfit.hlp @@ -0,0 +1,267 @@ +.help evalfit Aug91 noao.digiphot.photcal +.ih +NAME +evalfit -- evaluate the fit +.ih +USAGE +evalfit observations config parameters calib +.ih +PARAMETERS +.ls observations +The list of files containing the observations. +\fIObservations\fR are multi-column text files, whose columns are delimited +by whitespace, and whose first column is reserved for an object id. +All observations files in the list must have the same format. +.le +.ls config +The configuration file. \fIConfig\fR is a text file which +specifies the format of the \fIobservations\fR and \fIcatalog\fR files, and +defines the form of the transformation equations to be evaluated. +More information can be obtained about this file by typing +"help mkconfig" and "help config". +.le +.ls parameters +The name of the file produced by the FITPARAMS task. +\fIParameters\fR is a text file +containing the fitted parameter values for each +equation and other information about the quality of the +fit. Records in \fIparameters\fR are assigned a name equal to the label +of fitted equation. If more than one record in \fIparameters\fR has +the same name then the last record of that name is used by EVALFIT to +evaluate the fit. +.le +.ls calib +The name of the output file. \fICalib\fR is a text file +containing the name of the fitted object in the first column, +followed by the \fIprint\fR +variables if any, followed by the fitted value, error of the fit (if +\fIerrors\fR is not "undefined"), and residual of the +fit (if catalog matching is enabled) for each equation. +.le +.ls catalogs +The list of files containing the catalog data. +\fICatalogs\fR are multi-column text files, whose columns are delimited +by whitespace, and whose first column is reserved for an object id. +All catalog files in the list must have the same format. +If \fIcatalogs\fR = "", then no id matching with the observations +files is done. +.le +.ls errors = "undefined" +The algorithm used to compute formal errors for each object fit. The choices +are: +.ls undefined +No errors are computed and no error values are output. +.le +.ls obserrors +The error in each fitted value is computed by summing in quadrature +the contribution to the total error made by each individual error in the +observations file variables. If no error columns are defined for the +observations files the error is assumed to be INDEF. +.le +.ls equations +The error in each fitted value is computed by evaluating the error +equations associated with each transformation equation. If no error equation +is defined then the error is assumed to be INDEF. +.le +.le +.ls objects = "all" +The type of objects to output to \fIcalib\fR. The choices are: +.ls all +Both program and standard stars are output. +.le +.ls program = yes +Only program stars are output. +.le +.ls standard = yes +Only standard stars are output. +.le +.le +.ls print = "" +Additional variables to be printed in the output file. These variables are +printed immediately after the id, and may be any of the +catalog variables, observations variables, or the set equation variables +defined in \fIconfig\fR. +.le +.ls format = "" +An SPP style format string to apply to the output data, in place of the +default format. SPP format strings +are described in detail in the formats section. +.le +.ls append = no +Append the output to \fIcalib\fR instead of creating a new file. If the +file already exists and \fIappend\fR is "no" EVALFIT will abort. +.le +.ls catdir = ")_.catdir" +The directory containing the supported standard star catalogs. +The default parameter value redirects \fIcatdir\fR +to a package parameter of the same name. A list of standard +catalogs may be obtained by printing the file "photcal$catalogs/README". +Alternatively the user may create their own standard star catalogs +and standard star catalog directory. +.le + +.ih +DESCRIPTION + +EVALFIT evaluates the transformation equations +for the program and/or standard objects in \fIobservations\fR, using +the transformation equations defined in \fIconfig\fR, +the fitted parameter values in the file \fIparameters\fR produced by the +FITPARAMS +task, and writes the output to the file \fIcalib\fR. If \fIappend\fR is "yes" +output may be appended to an existing file. + +EVALFIT computes the values of the catalog variables for the program +stars by inserting the observations variables directly into the +transformation equations. EVALFIT can evaluate any number of transformation +equations, but if there are any standard catalog variables in the right-hand +side of the transformation equation, EVALFIT will assign INDEF to the fitted +for that equation. + +Below are two sets of transformation equations. The first set can be evaluated +with EVALFIT, the second set cannot and must be inverted with INVERTFIT. +In both cases the catalog variables to be fit are V and BV, and +the observed quantities are mv, mb, Xv, and Xb. + +.nf + System 1: V = v0 + mv + v1 * (Xv + Xb) / 2. + v2 * (mb - mv) + BV = b0 + b1 * (Xv + Xb) / 2. + b2 * (mb - mv) + + System 2: mv = v0 + V + v1 * Xv + v2 * BV + mb = b0 + V + BV + b1 * Xb + b2 * BV +.fi + + +Formal errors for each fit may +be computed by, 1) setting \fIerrors\fR to "obserrors" and using the +error columns defined in the observations section of \fIconfig\fR +to estimate the errors or 2) evaluating the error equations defined in +\fIconfig\fR. + +If the user wishes to match the objects in \fIobservations\fR with those +in \fIcatalogs\fR in order for example, to compute the residuals of the fit, +\fIcatalogs\fR must be defined. Similarly if \fIobjects\fR is "program" +or "standard", \fIcatalogs\fR must be defined in order to enable +id matching. + +Legal \fIcatalog\fR and \fIobservations\fR files are multi-column text +files whose columns are delimited by whitespace. +The first column of a catalog file is \fIalways\fR reserved for an object id. +The first column of an observations file is reserved for an +object id which can be +used to match the observational data with the corresponding catalog data. +All other columns may contain any quantity which can be +expressed as an integer or real number. Sexagesimal format numbers +(hh:mm:ss) are interpreted internally as real numbers. The constant +INDEF can be used to represent data that is missing or undefined. +Double precision and complex data are +not supported. Lines beginning with "#" are treated as comment lines. + +By default EVALFIT prints out the object id, +followed by the variables listed in the \fIprint\fR +parameter, followed by the fit value, estimated +error (if \fIerrors\fR is not "undefined"), and residual of the fit +(for any standard star observations that can be matched with the +catalog values) for each fitted equation. The user can format the output +by setting the \fIformat\fR parameter to an SPP style string. +SPP format strings are described in detail below. + +.ih +FORMATS +A format specification has the form "%w.dCn", where w is the field width, +d is the number of decimal places or the number of digits of precision, +C is the format code, and n is radix character for format code "r" only. +The w and d fields are optional. The format codes C are as follows: + +.nf +b boolean (YES or NO) +c single character (c or '\c' or '\0nnn') +d decimal integer +e exponential format (D specifies the precision) +f fixed format (D specifies the number of decimal places) +g general format (D specifies the precision) +h hms format (hh:mm:ss.ss, D = no. decimal places) +m minutes, seconds (or hours, minutes) (mm:ss.ss) +o octal integer +rN convert integer in any radix N +s string (D field specifies max chars to print) +t advance To column given as field W +u unsigned decimal integer +w output the number of spaces given by field W +x hexadecimal integer +z complex format (r,r) (D = precision) + + +Conventions for w (field width) specification: + + W = n right justify in field of N characters, blank fill + -n left justify in field of N characters, blank fill + 0n zero fill at left (only if right justified) +absent, 0 use as much space as needed (D field sets precision) + + +Escape sequences (e.g. "\n" for newline): + +\b backspace (\fBnot implemented\fR) +\f formfeed +\n newline (crlf) +\r carriage return +\t tab +\" string delimiter character +\' character constant delimiter character +\\ backslash character +\nnn octal value of character + +Examples + +%s format a string using as much space as required +%-10s left justify a string in a field of 10 characters +%-10.10s left justify and truncate a string in a field of 10 characters +%10s right justify a string in a field of 10 characters +%10.10s right justify and truncate a string in a field of 10 characters + +%7.3f print a real number right justified in floating point format +%-7.3f same as above but left justified +%15.7e print a real number right justified in exponential format +%-15.7e same as above but left justified +%12.5g print a real number right justified in general format +%-12.5g same as above but left justified + +\n insert a newline + +.fi + + +Note that deferred value fields are \fBnot implemented\fR in EVALFIT. + +.ih +EXAMPLES + +1. Evaluate the fit for a list of program stars in m92. Use the errors +in the observed quantities to estimate the errors. + +.nf + ph> evalfit m92.obs m92.cfg m92.fit m92.cal +.fi + +2. Repeat the fit computed above but include the variables xu and yu which +are the positions of the objects in the u frame in the output. + +.nf + ph> evalfit m92.obs m92.cfg m92.fit m92.cal print="xu,yu" +.fi + +3. Repeat the fit computed above but format the output. The user has +determined that the output will have 5 columns containing the object id, +xu, yu, fit value and fit error respectively. + +.nf + ph> evalfit m92.obs m92.cfg m92.fit m92.cal print="xu,yu"\ + format="%-10.10s %-7.2f %-7.2f %-7.3f %-6.3f\n" + +.fi + +.ih +SEE ALSO +mkconfig,chkconfig,fitparams,invertfit +.endhelp diff --git a/noao/digiphot/photcal/doc/fitparams.hlp b/noao/digiphot/photcal/doc/fitparams.hlp new file mode 100644 index 00000000..fbd9a61e --- /dev/null +++ b/noao/digiphot/photcal/doc/fitparams.hlp @@ -0,0 +1,633 @@ +.help fitparams Aug91 noao.digiphot.photcal +.ih +NAME +fitparams -- solve for the parameters of the transformation equations +.ih +USAGE +fitparams observations catalogs config parameters +.ih +PARAMETERS +.ls observations +The list of files containing the observational data. Observations files are +multi-column text files whose columns are delimited by whitespace, and +whose first column is usually reserved for the object id. +All observations files in the list must have the same format. +The format of legal observations files is described in further detail in +the description section. +.le +.ls catalogs +The list of files containing the catalog data. Catalog files are +multi-column text files whose columns are delimited by whitespace, +and whose first column is always reserved for the object id. +If more than one entry with the same id exists in the list of catalogs, +only the first entry is used. +All catalog files in the list must have the same format. +The format of legal catalog files is described in further detail in +the description section. +.le +.ls config +The name of the configuration file. The configuration file is a text file +specifying the format of the input catalog and observations files, and the +form of the transformation +equations. A brief description of the syntax and grammar of this file +is given in the configuration file section. +.le +.ls parameters +The name of the output database file. +Parameters is a text database file to which the error analysis of the fit +and the parameter values and errors for each transformation equation are +written. +The output of fitparams is appended to parameters as a set of new records, +one for each of the transformation equations. +If more than one record exists with the same record name, the +last record written takes precedence. +.le +.ls weighting = "uniform" +The following weighting schemes are supported. +.ls uniform +The data points are all assigned a weight of one. +.le +.ls photometric +The total error squared for each data point is set to the total error in the +catalog variables squared plus the total error in the observations variables +squared and the weight for each data point is set to 1.0 / error ** 2. +This option assumes that all the sources of error are in the photometric +indices (magnitudes and colors), that error columns (see the description +of the configuration file below) have been declared for at least one +photometric index, and that the contribution of each catalog or observations +variable to the total error is weighted by the number of times it occurs +in the transformation equation. +If \fIaddscatter\fR is "yes" then an additional "scatter" term is fit and +added to the weights. +.le +.ls equations +The weight equation (see the description of the configuration file below) +is evaluated for each point and the weight for that point is set to that +value. If there is no weight equation the weights are all set to one. +If \fIaddscatter\fR is "yes" then an additional "scatter" term is fit and +added to the weights. +.le +.le +.ls addscatter = yes +Add an additional scatter term to the weights if the average error in the fit +is much greater than the average error in the measurements? \fIAddscatter\fR +has no effect if \fIweighting\fR is "uniform". \fIAddscatter\fR is recommended +if \fIweighting\fR is "photometric" as the intrinsic error in the +transformations is often much greater than the formal errors of +measurement and the scatter term stabilizes the fit. +Users of the \fIweighting\fR equals "equations" option +may wish to turn off \fIaddscatter\fR. +.le +.ls tolerance = 3.0e-5 +The convergence tolerance for the non-linear least squares fit. +The fit will stop iterating +when the fractional change in the reduced chi-square of the residuals from +iteration to iteration is less than \fItolerance\fR. +.le +.ls maxiter = 15 +The maximum number of iterations for the non-linear least squares fit. +When this number is reached the fitting process will terminate even +if the fit has not converged. +.le +.ls nreject = 0 +The maximum number of bad data rejection iterations. If \fInreject\fR is +greater than zero the initial fit is used +to detect and reject deviant points before performing the final fit. +No rejection is performed if \fInreject\fR is less than or equal +to zero. +.le +.ls low_reject = 3.0, high_reject = 3.0 +The lower and upper rejection limits in units of the rms of the fit. +Points deviating from the initial fit by more than this amount are rejected +before performing the final fit. No rejection is done if both limits +are zero. +.le +.ls grow = 0.0 +The default rejection growing radius. Points within a distance given +by this parameter of any rejected point are also rejected. +.le +.ls interactive = yes +Fit equations interactively ? When this parameter is \fIyes\fR, the user will +be presented with plots of the data and can interact with the fitting +process. +.le +.ls logfile = "STDOUT" +The name of the output text file to which selected detailed results of the +fitting process are written. By default logfile is the standard output. +If logfile is "", logging is turned off altogether. Otherwise new +output is appended to logfile which can therefor become quite large. +.le +.ls log_unmatched = yes +Write the list of observations with no corresponding catalog entries to +logfile? This option is useful for checking for errors in the observed +object id names and for users who like to run fitparams in non-interactive +mode. +.le +.ls log_fit = no +Write the error analysis of the final fit in logfile? This option is +useful for users who like to run fitparams in non-interactive mode. +.le +.ls log_results = no +Write the results of the current fit to logfile? This option is +useful for users who like to run fitparams in non-interactive mode. +.le +.ls catdir = ")_.catdir" +The directory containing the supported standard star catalogs. +The default parameter value redirects \fIcatdir\fR +to a package parameter of the same name. A list of standard +catalogs may be obtained by printing the file "photcal$catalogs/README". +Alternatively the user may create their own standard star catalogs +and standard star catalog directory. +.le +.ls graphics = "stdgraph" +The default graphics device. +This parameter is used only if \fBinteractive=yes\fR. +.le +.ls cursor = "" +Graphics cursor input. When null the standard graphics cursor is used. +Otherwise the specified cursor command file is used. +This parameter is used only if \fBinteractive=yes\fR. +.le + +.ih +DESCRIPTION + +FITPARAMS parses the configuration file \fIconfig\fR checking for +grammar and syntax errors. FITPARAMS attempts to recover from any +errors and to finish parsing the configuration +file, but it will not process the input data if errors are present. +The configuration file is described briefly in the configuration file +section and in detail in the help page for the configuration file. + +Once the configuration file is successfully parsed, FITPARAMS reads the list +of catalog files and loads the values of the catalog variables +declared in \fIconfig\fR into memory. +If no catalog section is declared in \fIconfig\fR, if the catalog section +is empty, or if catalogs is "", no catalog data is read +and all the required input data is assumed to be in \fIobservations\fR. +After the catalog data is read, FITPARAMS reads the observations files +\fIobservations\fR, matches the object ids of the observations with the +corresponding catalog object ids, and loads all the observations +variables declared in \fIconfig\fR into memory. Id matching is disabled +if no catalog +data is read, otherwise only those observations which have a matching catalog +entry will be used in the fit. If a catalog section declaration was made +in \fIconfig\fR, even an empty one, FITPARAMS assumes that the object ids +are in column 1 of \fIobservations\fR. + +Legal \fIcatalog\fR and \fIobservations\fR files are multi-column text +files whose columns are delimited by whitespace. +The first column of a catalog file is \fIalways\fR reserved for an object id. +The first column of an observations file is \fIusually\fR reserved for an +object id which can be +used to match the observational data with the corresponding catalog data. +All other columns may contain any quantity which can be +expressed as an integer or real number. Sexagesimal format numbers +(hh:mm:ss) are interpreted internally as real numbers. The constant +INDEF can be used to represent data that is missing or undefined. +Double precision and complex data are +not supported. Lines beginning with "#" are treated as comment lines. + +FITPARAMS solves the fit +for each equation in the configuration file either interactively +or non-interactively depending on the value of \fIinteractive\fR, +and writes the solution in the output file \fIparameters\fR for later +use by the evaluation routines EVALFIT or INVERTFIT. +Selected results can also be written to \fIlogfile\fR if +any of the switches \fIlog_unmatched\fR, \fIlog_fit\fR, or \fIlog_results\fR +are enabled. +In interactive mode the user can use all the interactive capabilities +of the interactive non-linear least squares package INLFIT. +INLFIT is described more fully below. + +.ih +THE CONFIGURATION FILE + +The configuration file is a text file which specifies how the data is +organized in the input files and how the transformation +equations are to be fit. + +The input data are assumed to come from two different sources that may +be either in the same input file or in different input files. +These sources are known as the \fIcatalog\fR and the \fIobservations\fR +respectively. + +The \fIcatalog\fR contains values indexed by a name called the +matching name. This name must be in the first column of the +catalog and is also assumed to be unique, i.e, each catalog +entry is assumed to be unique. + +The \fIobservations\fR are values that may be either indexed by a matching +name if a catalog section is specified in the configuration file, or a +stream of input values in an ordinary text file. +If a catalog section is specified and non-empty, each observation is +matched against the +catalog entries, and only observations whose matching names are found in the +catalog are used to compute the transformation equations. +Otherwise all values are used. + +The configuration file is divided in three sections: the \fIcatalog +section\fR which describes the format of the catalog files, the +\fIobservations section\fR which describes the format of the observation +files, and the \fItransformation section\fR which defines the +transformation equations in that order. + +The catalog and observations sections permit the user to assign +names to the input file +columns. These columns can later be referenced by name in the configuration +file by using these assigned names +as if they were variables in a programming language. + +The transformation section is used to define the equations to solve, +and assign initial values to the fitting parameters. +The user may also optionally define equations for the derivatives of +the transformation equations with respect to the parameters, +the weights to be used in the fit, +the errors of the fit and the default equations to be +plotted in the interactive fitting process. +It is possible to specify any number of transformation equations in +this section. + +SAMPLE CONFIGURATION FILES + +Example 1. Configuration file for reducing UBV photoelectric photometry. + +.nf +# Configuration file for reducing UBV photoelectric photometry. + +catalog + +V 2 # V magnitude +BV 3 # B - V color +UB 4 # U - B color + +observation + +v 2 # v instrumental magnitude +b 3 # b instrumental magnitude +u 4 # u instrumental magnitude +ev 5 # error in v instrumental magnitude +eb 6 # error in b instrumental magnitude +eu 7 # error in u instrumental magnitude +X 8 # airmass + +transformation + +fit v1 = 0.0, v2=0.16, v3=-0.043 +VFIT: V = v1 + v - v2 * X + v3 * (b - v) + weight(VFIT) = 1.0 / ev ** 2 + plot(VFIT) = V, V - (v1 + v - v2 * X + v3 * (b - v)) + +fit b1 = 0.0, b2=0.09, b3=1.21 +BVFIT: BV = b1 - b2 * X + b3 * (b - v) + weight (BVFIT) = 1.0 / (eb ** 2 + ev ** 2) + plot(BVFIT) = BV, BV - (b1 - b2 * X + b3 * (b - v)) + +fit u1 = 0.0, u2=0.300, u3=0.861 +UBFIT: UB = u1 - u2 * X + u3 * (u - b) + weight (UBFIT) = 1.0 / (eu ** 2 + eb ** 2) + plot(UBFIT) = UB, UB - (u1 - u2 * X + u3 * (u - b)) +.fi + +Example 2. Configuration file for reducing UBV CCD photometry. + +.nf +catalog + +V 2 # V magnitude +BV 3 # B - V color +UB 4 # U - B color +error(V) 5 # error in V magnitude +error(BV) 6 # error in B-V color +error(UB) 7 # error in U-B color + +observation + +m1 2 # filter 1 instrumental magnitude +error(m1) 3 # error in filter 1 instrumental magnitude +Xm1 4 # airmass of filter 1 observation +m2 6 # filter 2 instrumental magnitude +error(m2) 7 # error in filter 2 instrumental magnitude +Xm2 8 # airmass of filter 2 observation +m3 10 # filter 3 instrumental magnitude +error(m3) 11 # error in filter 3 instrumental magnitude +Xm3 12 # airmass of filter 3 observation + + +transformation + +fit u1 = 27.0, u2=0.68, u3=0.05 +UFIT: m3 = u1 + V + BV + UB + u2 * Xm3 + u3 * UB + +fit b1 = 26.0, b2=0.30, b3=0.18 +BFIT: m2 = b1 + V + BV + b2 * Xm2 + b3 * BV + +fit v1 = 25.0, v2=0.17, v3=-0.02 +VFIT: m1 = v1 + V + v2 * Xm1 + v3 * BV +.fi + + +.ih +THE NON-LINEAR INTERACTIVE FITTING PACKAGE + +DESCRIPTION + +INLFIT fits an n-dimensional function to a set data +points, iterating until the reduced chi-squared changes +by less than \fItolerance\fR percent between successive iterations, or +machine precision is reached and the fit converges, or until the maximum number +of iterations \fImaxiter\fR is reached. If the maximum number +of iterations is reached before convergence a status flag +is set. + +After computing an initial fit, INLFIT presents the user with a plot of +the fit and activates the graphics cursor. +At this point the user may examine and/or interact with the fit by, +for example, reprogramming the default graph keys, +editing the default convergence or bad data rejection parameters, +deleting and undeleting points, +altering which parameters in the fitting function are actually to be +fit and which are to be held constant, and refitting the data. + +If \fInreject\fR is greater than zero the RMS of the residuals is computed +and points whose residuals are less than \fIlow_reject\fR * RMS +or \fIhigh_reject\fR * RMS value are excluded from the fit. Points within +a distance \fIgrow\fR of a rejected point are also excluded from +the fit. The function is then refit without the rejected points. +The rejection algorithm is executed until the number of rejection +iterations reaches \fInreject\fR or no more points are rejected. + +ALGORITHMS + +INLFIT uses the standard Levenberg-Marquardt non-linear least squares +algorithm to fit the data. Detailed descriptions of the algorithm can +be found in the following two references. +.nf + +1. Bevington, P.R., 1969, Data Reduction and Error Analysis for the + Physical Sciences, Chapter 11, page 235. + +2. Press, W.H. et al., 1986, Numerical Recipes: The Art of Scientific + Computing, Chapter 14, page 523. + +.fi + +CURSOR COMMANDS + +The following interactive cursor keystroke commands are available from +with the INLFIT package. +.ls ? +The terminal is cleared and a menu of cursor keystroke and colon commands +is printed. +.le +.ls c +The id, coordinates of the data point nearest the cursor, along with the +function value, the fitted value and the residual, are printed on the status +line. +.le +.ls d +The data point nearest the cursor and not previously deleted is marked with an +X. It will not be used in further fits until it is undeleted. +.le +.ls f +The function is fit to the data and the fit is graphed using the default +plot type. +.le +.ls g +Redefine the graph keys "h-l" from their defaults. A prompt is issued for the +graph key to be redefined. Another prompt is issued for the data to be +plotted at which point the user must enter the x and y axis data to plot, +delimited by a comma. The data types are the following (they can be +abbreviated to up to three characters). +.nf + + function Dependent variable or function + fit Fitted value + residuals Residuals (function - fit) + ratio Ratio (function / fit) + nonlinear Nonlinear component + identifier Independent variable named "identifier" (if defined) + var n Independent variable number "n" + user n User defined plot equation "n" (if defined) + +.fi +The application program can define independent variable names and user plot +functions, aside from the standard options provided. If variable names are +supplied, the user can reference them by their names. Otherwise they can be +always referenced by "var n", where "n" is the variable number (the user has +to know the variable order in this case). The ":variables" command will +list the currently defined variables by name and number. +The application program may +define any number of plot equations aside from the defaults provided. In this +case the user may reference them by "user n", where "n" is the plot function +number (the user must know the equation order in this case). +.le +.ls h, i, j, k, l +By default each key produces a different graph. The graphs are described by +the data which is graphed along each axis as defined above. The default graph +keys, +which may be redefined by the application program or interactively by using +the 'g' key, are the following. +.nf + + h function, fit + i function, residuals + j function, ratio + k var 1, function + l user 1, user 2 (default) + +.fi +The initial graph key, if not redefined by the application program is 'h'. +.le +.ls o +Overplot the next fit provided the graph format has not changed. +.le +.ls q +Exit from the interactive curve fitting package. +.le +.ls r +Redraw the current graph. +.le +.ls t +Toggle fit overplotting on and off. If this option is on the data +and fitted values are overplotted. Otherwise only data points are plotted. +The fitted values are marked using boxes. +.le +.ls u +Undelete the data point nearest the cursor which has been previously deleted. +This option does not work over points marked as deleted by the application +program before calling inlfit. +.le +.ls w [key] +Set the graph window or data range along each axis to be graphed.. This is a +\fBgtools\fR option which prints the prompt "window:". The available cursor +keystroke commands are printed with '?' and on-line help is available by +typing "help gtools". +.le +.ls I +Interrupt the task immediately without saving the current fit. +.le + +Colon commands are used to show or set the values of parameters. +The application program calling \fBinlfit\fR can add more commands. +Parameter names can be abbreviated. The following commands are supported. +.ls :show [file] +Show the current values of the fitting parameters high_reject, +low_reject, niterate, grow, tol, itmax. The default output device +is the terminal (STDOUT) and the screen is cleared before the information +is output. If a file is specified then the information is appended +to the named file. +.le +.ls :variables [file] +List the currently loaded variables. The number, id, minimum value and maximum +value of each variable is printed. The default output device is the terminal +(STDOUT) and the screen is cleared before the information is output. +If a file is specified then the information is appended to the named file. +.le +.ls :data [file] +List the raw data. The value of each standard catalog and observations +catalog variable for each data point is printed. The default output device +is the terminal (STDOUT) and the screen is cleared before the information +is output. If a file is specified then the information is appended to +the named file. +.le +.ls :errors [file] +Show the error analysis of the current fit. The number of iterations, +total number of points, the number of rejected and deleted points, +the standard deviation, the reduced chi, average error (always = 1.0 if +weight = 1.0, otherwise = 1.0 / <weight>), +average scatter (always = 0.0 if no weights scatter term is fit) +and the rms value are +printed on the screen. +The fitted parameters and their errors are also printed. The default output is +the terminal (STDOUT) and the screen is cleared before the information is +output. If a file is specified then the information is appended to +the named file. +.le +.ls :results [file] +List the results of the current fit. The function value, the fitted value, +the residual, and the weight are printed for each data point. The default +output device is the terminal (STDOUT) and the screen is cleared before +the information is output. If a file is specified then the information is +appended to the named file. +.le +.ls :vshow [file] +A verbose version of ":show" which is equivalent to a ":show" plus a ":errors" +plus a ":results". The default output device is the terminal (STDOUT) +and the screen is cleared before the information is output. +If a file is specified then the information is appended to the named file. +.le +.ls :page file +Page through the named file. +.le +.ls :tolerance [value] +Show or set the value of the fitting tolerance. Tolerance is the maximum +fraction by which the reduced chi-squared can change from one iteration to the +next for the fit to meet the convergence criteria. +.le +.ls :maxiter [value] +Show or set the maximum number of fitting iterations. +.le +.ls :nreject [value] +Show or set the maximum number of rejection iterations. A value of zero +means that automatic bad data rejection is turned off. +.le +.ls :low_reject [value], :high_reject [value] +Show or set the values of the bad data rejection limits. +If both low_reject and high_reject are zero then automatic bad data +rejection is turned off. +If either of the high or low rejection limits are greater than zero, +and nreject is greater than zero, the rms of the initial fit is computed. +Points with residuals +more than low_reject * rms below zero and high_reject * rms above zero +are removed before the final fit. Rejected points are marked on the +graphs with diamonds. +.le +.ls :grow [value] +Show or set the value of the rejection growing radius. Any points +within this distance of a rejected point are also rejected. +.le +.ls :fit [parameter] [value] +Set the starting guess value for the named coefficient and allow the +parameter value to change (converge) during the fit. +If the value is not specified inlfit will use the last starting guess. +.le +.ls :const [parameter] [value] +Set the named parameter to be a constant with the specified value, i.e, +its value won't change during the fit. +If the value is not specified inlfit will use its last starting value. +.le +.ls :/help +Print help for the graph formatting options (the w key). +.le +.ls :.help +Print help for the general IRAF graphics options. +.le + +.ih +EXAMPLES + +1. Fit a set of UBV standard star data non-interactively using the automatic +bad data rejection algorithm and the configuration file shown in example +2 under the configuration file section. + +.nf + ph> fitparams m92.obs m92.cat m92.config m92.fit nreject=10 inter- + + ... compute valued for the parameters in all the transformation + equations + + ph> page m92.fit + + ... check that the fitted parameter values are reasonable + + ph> invertfit m92.obs m92.cat m92.config m92.fit m92.out + + ... evaluate the transformation equations for all the standard + stars +.fi + +2. Fit the same set of data interactively but deleting bad points by +eye instead of using the automatic rejection algorithm. + +.nf + ph> fitparams m92.obs m92.cat m92.config m92.fit + + ... a default plot of the UFIT equation comes up on the screen + (the fit or right-hand side of the equation is plotted + versus the function or left-hand side of the equation) + + ... type '?' to show the available commands + + ... type 'i' to plot the residuals versus the function (LHS of + the equation) + + ... delete bad points with the 'd' key and refit using the 'f' + key + + ... check for any dependencies of the residuals on the color + term by reprogramming the graph key 'l' using the 'g' key + (type 'g' to enter the reprogramming menu, 'l' after the + prompt to reprogram the 'l' key, and "UB, residuals" in + response to the question of which axes to plot + + ... list the plot windowing menu by typing 'w' followed by '?' + after the "window:" prompt + + ... type 'w' followed by 'z' after the ":window" prompt to zoom + up on an interesting area in the plot, a 'w' followed by 'a' + will return to normal scaling + + ... type 'q' to quit the fit for this equation + + ... answer "yes" to the question about saving the fit + + ... proceed to the next fit by typing "next" in response to the + prompt + +.fi + +.ih +SEE ALSO +chkconfig,mkconfig,gtools,inlfit +.endhelp diff --git a/noao/digiphot/photcal/doc/inlfit.hlp b/noao/digiphot/photcal/doc/inlfit.hlp new file mode 100644 index 00000000..0daf5cd6 --- /dev/null +++ b/noao/digiphot/photcal/doc/inlfit.hlp @@ -0,0 +1,259 @@ +.help inlfit Aug91 noao.digiphot.inlfit +.ih +NAME +inlfit -- The interactive non-linear least squares fitting package + +.ih +SYNOPSIS + +The INLFIT package is a set of procedures, callable from any IRAF task, +for interactively fitting an arbitrary function of n independent variables +using non-linear least squares techniques. The calling task +must supply the function to be fit and its derivatives, initial values for +various convergence and bad data rejection parameters, the data to be fit, +and weights for all the data points. The INLFIT package is layered on the +NLFIT package which does the actual fitting. + +.ih +DESCRIPTION + +INLFIT fits an n-dimensional function to a set of data +points iterating until the reduced chi-squared changes +by less than \fItolerance\fR percent between successive iterations, or +until machine precision is reached, or until +the maximum number +of iterations \fImaxiter\fR is reached. If the maximum number +of iterations is reached before convergence a status flag +is set. + +After computing an initial fit, INLFIT presents the user with a plot of +the fit and activates the graphics cursor. +At this point the user may examine and/or interact with the fit by, +for example, reprogramming the default graph keys, +editing the default convergence or bad data rejection parameters, +deleting and undeleting points, +altering which parameters in the fitting function are actually to be +fit and which are to be held constant, and refitting the data. + +If \fInreject\fR is greater than zero the RMS of the residuals is computed +and points whose residuals are less than \fIlow_reject\fR * RMS +or greater than \fIhigh_reject\fR * RMS value are excluded from the fit. +Points within +a distance \fIgrow\fR of a rejected point are also excluded from +the fit. The function is then refit without the rejected points. +The rejection algorithm is executed until the number of rejection +iterations reaches \fInreject\fR or no more points are rejected. + +.ih +CURSOR COMMANDS + +The following interactive cursor keystroke commands are available from +with the INLFIT package. +.ls ? +The terminal is cleared and a menu of cursor keystroke and colon commands +is printed. +.le +.ls c +The id, coordinates of the data point nearest the cursor, along with the +function value, the fitted value and the residual, are printed on the status +line. +.le +.ls d +The data point nearest the cursor and not previously deleted is marked with an +X. It will not be used in further fits until it is undeleted. +.le +.ls f +The function is fit to the data and the fit is graphed using the default +plot type. +.le +.ls g +Redefine the graph keys "h-l" from their defaults. A prompt is issued for the +graph key to be redefined. Another prompt is issued for the data to be +plotted at which point the user must enter the x and y axis data to plot, +delimited by a comma. The data types are the following (they can be +abbreviated to up to three characters). +.nf + + function Dependent variable or function + fit Fitted value + residuals Residuals (function - fit) + ratio Ratio (function / fit) + nonlinear Nonlinear component + identifier Independent variable named "identifier" (if defined) + var n Independent variable number "n" + user n User defined plot equation "n" (if defined) + +.fi +The application program can define independent variable names and user plot +functions, aside from the standard options provided. If variable names are +supplied, the user can reference them by their names. Otherwise they can be +always referenced by "var n", where "n" is the variable number (the user has +to know the variable order in this case). The ":variables" command will +list the currently defined variables by name and number. +The application program may +define any number of plot equations aside from the defaults provided. In this +case the user may reference them by "user n", where "n" is the plot function +number (the user must know the equation order in this case). +.le +.ls h, i, j, k, l +By default each key produces a different graph. The graphs are described by +the data which is graphed along each axis as defined above. The default graph +keys, +which may be redefined by the application program or interactively by using +the 'g' key, are the following. +.nf + + h function, fit + i function, residuals + j function, ratio + k var 1, function + l user 1, user 2 (default) + +.fi +The initial graph key, if not redefined by the application program is 'h'. +.le +.ls o +Overplot the next fit provided the graph format has not changed. +.le +.ls q +Exit from the interactive curve fitting package. +.le +.ls r +Redraw the current graph. +.le +.ls t +Toggle fit overploting on and off. If this option is on the data +and fitted values are overplotted. Otherwise only data points are plotted. +The fitted values are marked using boxes. +.le +.ls u +Undelete the data point nearest the cursor which has been previously deleted. +This option does not work over points marked as deleted by the application +program before calling inlfit. +.le +.ls w [key] +Set the graph window or data range along each axis to be graphed.. This is a +\fBgtools\fR option which prints the prompt "window:". The available cursor +keystroke commands are printed with '?' and on-line help is available by +typing "help gtools". +.le +.ls I +Interrupt the task immediately without saving the current fit. +.le + +Colon commands are used to show or set the values of parameters. +The application program calling \fBinlfit\fR can add more commands. +Parameter names can be abbreviated. The following commands are supported. +.ls :show [file] +Show the current values of the fitting parameters high_reject, +low_reject, niterate, grow, tol, itmax. The default output device +is the terminal (STDOUT) and the screen is cleared before the information +is output. If a file is specified then the information is appended +to the named file. +.le +.ls :variables [file] +List the currently loaded variables. The number, id, minimum value and maximum +value of each variable is printed. The default output device is the terminal +(STDOUT) and the screen is cleared before the information is output. +If a file is specified then the information is appended to the named file. +.le +.ls :data [file] +List the raw data. The value of each standard catalog and observations +catalog variable for each data point is printed. The default output device +is the terminal (STDOUT) and the screen is cleared before the information +is output. If a file is specified then the information is appended to +the named file. +.le +.ls :errors [file] +Show the error analysis of the current fit. The number of iterations, +total number of points, +the number of rejected and deleted points, the standard deviation, +the reduced chi, the average error (always = 1.0 if weight=1.0, otherwise += 1.0 / <weight>), the average scatter (always 0.0 if no weights scatter term is +fit), +the reduce chi, and the rms are printed on the screen. The fitted parameters +and their errors are also printed. The default output is the terminal +(STDOUT) and the screen is cleared before the information is +output. If a file is specified then the information is appended to +the named file. +.le +.ls :results [file] +List the results of the current fit. The function value, the fitted value, +the residual, and the weight are printed for each data point. The default +output device is the terminal (STDOUT) and the screen is cleared before +the information is output. If a file is specified then the information is +appended to the named file. +.le +.ls :vshow [file] +A verbose version of ":show" which is equivalent to a ":show" plus a ":errors" +plus a ":results". The default output device is the terminal (STDOUT) +and the screen is cleared before the information is output. +If a file is specified then the information is appended to the named file. +.le +.ls :page file +Page through the named file. +.le +.ls :tolerance [value] +Show or set the value of the fitting tolerance. Tolerance is the maximum +fraction by which the reduced chi-squared can change from one iteration to the +next for the fit to meet the convergence criteria. +.le +.ls :maxiter [value] +Show or set the maximum number of fitting iterations. +.le +.ls :nreject [value] +Show or set the maximum number of rejection iterations. A value of zero +means that automatic bad data rejection is turned off. +.le +.ls :low_reject [value], :high_reject [value] +Show or set the values of the bad data rejection limits. +If both low_reject and high_reject are zero then automatic bad data +rejection is turned off. +If either of the high or low rejection limits are greater than zero, +and nreject is greater than zero, the rms of the initial fit is computed. +Points with residuals +more than low_reject * rms below zero and high_reject * rms above zero +are removed before the final fit. Rejected points are marked on the +graphs with diamonds. +.le +.ls :grow [value] +Show or set the value of the rejection growing radius. Any points +within this distance of a rejected point are also rejected. +.le +.ls :fit [parameter] [value] +Set the starting guess value for the named coefficient and allow the +parameter value to change (converge) during the fit. +If the value is not specified inlfit will use the last starting guess. +.le +.ls :const [parameter] [value] +Set the named parameter to be a constant with the specified value, i.e, +its value won't change during the fit. +If the value is not specified inlfit will use its last starting value. +.le +.ls :/help +Print help for the graph formatting options. +.le +.ls :.help +Print help for the general IRAF graphics options. +.le + +.ih +ALGORITHMS + +INLFIT uses the standard Levenberg-Marquardt non-linear least squares +algorithm to fit the data. Detailed descriptions of the algorithm can +be found in the following two references. +.nf + +1. Bevington, P.R., 1969, Data Reduction and Error Analysis for the + Physical Sciences, Chapter 11, page 235. + +2. Press, W.H. et al., 1986, Numerical Recipes: The Art of Scientific + Computing, Chapter 14, page 523. + +.fi + +.ih +SEE ALSO +gtools +.endhelp diff --git a/noao/digiphot/photcal/doc/invertfit.hlp b/noao/digiphot/photcal/doc/invertfit.hlp new file mode 100644 index 00000000..0923d0fb --- /dev/null +++ b/noao/digiphot/photcal/doc/invertfit.hlp @@ -0,0 +1,297 @@ +.help invertfit Aug91 noao.digiphot.photcal +.ih +NAME +invertfit -- evaluate the fit by inverting the system of equations defined +in the configuration file +.ih +USAGE +invertfit observations config parameters calib +.ih +PARAMETERS +.ls observations +The list of files containing the observations. +\fIObservations\fR are multi-column text files, whose columns are delimited +by whitespace, and whose first column is reserved for an object id. +All observations files in the list must have the same format. +.le +.ls config +The configuration file. \fIConfig\fR is a text file which specifies the +format of the \fIobservations\fR and \fIcatalog\fR files, and defines the +form of the transformation equations to be inverted. +More information can be obtained about the format of this file +by typing "help mkconfig" and "help config". +.le +.ls parameters +The name of the file containing the fit produced by the FITPARAMS task. +\fIParameters\fR is a text file +containing the fitted parameter values for each +equation and other information about the quality of the +fit. Records in \fIparameters\fR are assigned a name equal to the label +of the fitted equation. If more than one record in \fIparameters\fR has +the same name then the last record is used by INVERTFIT to do the inversion. +.le +.ls calib +The name of the output file. \fICalib\fR is a text file containing +the name of the fitted object in the first column, +followed by the values of the \fIprint\fR variables if any, +followed by the fitted value of each catalog variable, error in the +catalog variable (if \fIerrors\fR is not +"undefined"), and residual of the fit (if catalog matching is enabled). +.le +.ls catalogs = "" +The list of files containing the catalog data. +\fICatalogs\fR are multi-column text files, whose columns are delimited +by whitespace, and whose first column is always reserved for an object id. +All catalog files in the list must have the same format. +If \fIcatalogs\fR is "", then no id matching with the observations files +is done, and the residuals of the fit cannot be computed. +.le +.ls errors = "obserrors" +The algorithm used to compute formal errors for each object fit. The choices +are: +.ls undefined +No errors are computed and no error values are output. +.le +.ls obserrors +The error in each fitted value is computed by summing in quadrature +the contribution to the total error made by each individual error in the +observations files variables. If no error columns are defined for the +observations files, the error is assigned the value INDEF. +.le +.ls equations +The error in each fitted value is computed by summing in quadrature +the contribution to the total error made by each error +equation associated with a transformation equation. +If no error equation is defined for any of the transformation +equations, then the error is assumed to be INDEF. +.le +.le +.ls objects = "all" +The type of objects to output to \fIcalib\fR. The choices are: +.ls all +Both program and standard objects are output. +.le +.ls program = yes +Only program objects are output. +.le +.ls standard = yes +Only standard objects are output. +.le +.le +.ls print = "" +Additional variables to be printed in the output file. These variables are +printed immediately after the object id, and may be any of the +catalog variables, observations variables, or the set equation variables +defined in \fIconfig\fR. +.le +.ls format = "" +An SPP style format string to be used for formatting the output data, in +place of the default format. SPP format +strings are described in detail in the formats section. +.le +.ls append = no +Append the output to \fIcalib\fR instead of creating a new file. If the +file already exists and \fIappend\fR is "no" INVERTFIT will abort. +.le +.ls catdir = ")_.catdir" +The directory containing the supported standard star catalogs. +The default parameter value redirects \fIcatdir\fR +to a package parameter of the same name. A list of standard +catalogs may be obtained by printing the file "photcal$catalogs/README". +Alternatively the user may create their own standard star catalogs +and standard star catalog directory. +.le + +.ih +DESCRIPTION + +INVERTFIT computes magnitudes and colors for the standard or +program stars in \fIobservations\fR by inverting the system of +transformation equations defined in \fIconfig\fR, using the +parameter values in the file \fIparameters\fR produced by the FITPARAMS +task, and writes the fitted values to the output file \fIcalib\fR. +If \fIappend\fR is "yes" output may be appended to an existing file. + +INVERTFIT computes the values of the catalog variables for the program +stars by inverting the system of transformation equations defined in +\fIconfig\fR. IT IS THE RESPONSIBILITY OF THE USER TO ENSURE THAT +THE SYSTEM OF EQUATIONS IS ACTUALLY INVERTIBLE. +Two minimum conditions must be met. First, the number of +transformation equations must be greater than or equal to the number of +catalog variables to be fit, and second, all the catalog variables must +be on the right-hand side of the transformation equations. +INVERTFIT will test for both of these conditions, issue a warning, and +terminate execution if either of these conditions are not met. + +Below are two sets of transformation equations. +The first set +can be inverted by INVERTFIT, the second set cannot and must be +evaluated by EVALFIT. In both cases the catalog variables to be fit +are V and BV, and the observed quantities are mv, mb, Xv, and Xb. + +.nf + System 1: mv = v0 + V + v1 * Xv + v2 * BV + mb = b0 + V + BV + b1 * Xb + b2 * BV + + System 2: V = v0 + mv + v1 * (Xv + Xb) / 2. + v2 * (mb - mv) + BV = b0 + b1 * (Xv + Xb) / 2.0 + b2 * (mb - mv) +.fi + +It is possible though not recommended, to use set equation variables as +unknowns in the transformation +equations, provided that the total number of unknowns on the right-hand +side of the equations remains less than or equal to the number of transformation +equations. Set equations containing catalog variables must not be used +in the left-hand side of the transformation equations. An example of a set +of transformation equations which use a set equation variable is shown +below. Note that there still are only two independent variables V and BV and +that the output file \fIcalib\fR will contain V and BV only. + +.nf + System 1: set B = V + BV + mv = v0 + V + v1 * Xv + v2 * BV + mb = b0 + B + b1 * Xb + b2 * BV +.fi + +Some systems of equations are invertible but do not have a UNIQUE solution. +A sample of such a system is shown below. +There are quadratic terms in BV, implying that this set of +equations probably has two solutions, both of which may be +be mathematically correct, but only one of which is physically meaningful. +INVERTFIT does not test for this condition and may converge to either solution. + +.nf + System 1: mv = v0 + V + v1 * BV + v2 * BV ** 2 + mb = b0 + V + BV + b1 * BV + b2 * BV ** 2 +.fi + + +Formal errors for the fit may +be computed by, 1) setting \fIerrors\fR to "obserrors" and using the +error columns defined in the observations section of \fIconfig\fR +to estimate the errors or 2) setting \fIerrors\fR to "equations" and +using the error equations defined in \fIconfig\fR to estimate the errors. + +If the user wishes to match the objects in \fIobservations\fR with those +in \fIcatalogs\fR in order for example, to compute the residuals of the fit, +\fIcatalogs\fR must be defined. Similarly if \fIobjects\fR is "program" +or "standard", \fIcatalogs\fR must be defined in order to enable +id matching. + +Legal \fIcatalog\fR and \fIobservations\fR files are multi-column text +files whose columns are delimited by whitespace. +The first column of a catalog file is \fIalways\fR reserved for an object id. +The first column of an observations file is reserved for an +object id which can be +used to match the observational data with the catalog data. +All other columns may contain any quantity which can be +expressed as an integer or real number. Sexagesimal format numbers +(hh:mm:ss) are interpreted internally as real numbers. The constant +INDEF can be used to represent data that is missing or undefined. +Double precision and complex data are +not supported. Lines beginning with "#" are treated as comment lines. + +By default INVERTFIT prints out the id, +followed by the variables listed in the \fIprint\fR +parameter, followed by the fit value, estimated +error (if \fIerrors\fR is "undefined", and residual of the fit (for any +standard star observations that can be matched with the catalog values) +for each fitted catalog variable. +The user can format the output by setting the \fIformat\fR parameter to an SPP +style string. SPP format strings are described in detail below. + +.ih +FORMATS +A format specification has the form "%w.dCn", where w is the field width, +d is the number of decimal places or the number of digits of precision, +C is the format code, and n is radix character for format code "r" only. +The w and d fields are optional. The format codes C are as follows: + +.nf +b boolean (YES or NO) +c single character (c or '\c' or '\0nnn') +d decimal integer +e exponential format (D specifies the precision) +f fixed format (D specifies the number of decimal places) +g general format (D specifies the precision) +h hms format (hh:mm:ss.ss, D = no. decimal places) +m minutes, seconds (or hours, minutes) (mm:ss.ss) +o octal integer +rN convert integer in any radix N +s string (D field specifies max chars to print) +t advance To column given as field W +u unsigned decimal integer +w output the number of spaces given by field W +x hexadecimal integer +z complex format (r,r) (D = precision) + + +Conventions for w (field width) specification: + + W = n right justify in field of N characters, blank fill + -n left justify in field of N characters, blank fill + 0n zero fill at left (only if right justified) +absent, 0 use as much space as needed (D field sets precision) + + +Escape sequences (e.g. "\n" for newline): + +\b backspace (\fBnot implemented\fR) +\f formfeed +\n newline (crlf) +\r carriage return +\t tab +\" string delimiter character +\' character constant delimiter character +\\ backslash character +\nnn octal value of character + +Examples + +%s format a string using as much space as required +%-10s left justify a string in a field of 10 characters +%-10.10s left justify and truncate a string in a field of 10 characters +%10s right justify a string in a field of 10 characters +%10.10s right justify and truncate a string in a field of 10 characters + +%7.3f print a real number right justified in floating point format +%-7.3f same as above but left justified +%15.7e print a real number right justified in exponential format +%-15.7e same as above but left justified +%12.5g print a real number right justified in general format +%-12.5g same as above but left justified + +\n insert a newline + +.fi + +.ih +EXAMPLES + +1. Evaluate the fit for a list of program stars in m92. Use the errors +in the observed quantities to estimate the errors. + +.nf + ph> invertfit m92.obs m92.cfg m92.fit m92.cal +.fi + +2. Repeat the fit computed above but include the variables xu and yu which +are the positions of the objects in the u frame in the output. + +.nf + ph> invertfit m92.obs m92.cfg m92.fit m92.cal print="xu,yu" +.fi + +3. Repeat the fit computed in 1 but format the output. The user has +determined that the output will have 7 columns containing the object +id, V, error(V), resid(V), BV, error(BV), and resid(BV). + +.nf + ph> invertfit m92.obs m92.cfg m92.fit m92.cal\ + format="%-10.10s %7.3f %6.3f %6.3f %7.3f %6.3f %6.3f\n" +.fi + +.ih +SEE ALSO +mkconfig,chkconfig,fitparams,evalfit +.endhelp diff --git a/noao/digiphot/photcal/doc/mkapfile.hlp b/noao/digiphot/photcal/doc/mkapfile.hlp new file mode 100644 index 00000000..7f1d5876 --- /dev/null +++ b/noao/digiphot/photcal/doc/mkapfile.hlp @@ -0,0 +1,473 @@ +.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 diff --git a/noao/digiphot/photcal/doc/mkcatalog.hlp b/noao/digiphot/photcal/doc/mkcatalog.hlp new file mode 100644 index 00000000..11f03a3f --- /dev/null +++ b/noao/digiphot/photcal/doc/mkcatalog.hlp @@ -0,0 +1,220 @@ +.help mkcatalog Aug91 noao.digiphot.photcal + +.ih +NAME +mkcatalog -- create or edit a catalog, usually but not necessarily +a standard star catalog +.ih +USAGE +mkcatalog catalog +.ih +PARAMETERS +.ls catalog +The name of the new output catalog to be created or a previously existing +catalog to be edited. +.le +.ls review = no +Review any pre-existing entries? +.le +.ls verify = no +Verify each new entry? +.le +.ls edit = yes +Enter edit mode after entering all the values? +.le +.ih +DESCRIPTION + +MKCATALOG is a script task which permits the user to create or edit +the catalog \fIcatalog\fR, usually but not necessarily, a standard star +catalog. MKCATALOG has two modes of operation, entry mode and edit mode. +In entry mode MKCATALOG prompts the user for input. +In edit mode MKCATALOG calls up the default editor specified by +the IRAF environment variable \fIeditor\fR. + +If \fIcatalog\fR is a new catalog, MKCATALOG prompts the user for +the name of the object id column, the names of the data columns, +the names of the error columns (these are optional), and the widths +of the columns. Typing the end-of-file character <EOF>, +usually ^Z or ^D, terminates column definition +and places the user in entry mode. +In entry mode MKCATALOG prompts the user for the object ids and data values. +Entering carriage return, <CR>, after MKCATALOG prompts for a new object id +writes a blank line to the output catalog. +Entering <CR> after MKCATALOG prompts for any other column +value writes INDEF (the IRAF undefined value) in that column of the +output catalog. +Entry mode is terminated by typing <EOF> in response to a query for +a new object id. The user may verify each new +entry by setting the parameter \fIverify\fR to "yes". + +Each new catalog created by MKCATALOG has an associated format +description file listing the column names and numbers associations defined by +the user. This file, referenced by its parent catalog name, can be +used as input to the MKCONFIG task. +The actual name of the format description file on disk is constructed by +prepending the catalog name \fIcatalog\fR with the string "f" and +appending the string ".dat". For example if a new catalog +called "UBVcat" is created by MKCATALOG, a format description +file called "fUBVcat.dat" will also be created. Any pre-existing format +description file of that name, which does not have an associated catalog +file, will be deleted. + +If the catalog \fIcatalog\fR exists and was created with MKCATALOG, +MKCATALOG reads +the number of columns, the column names, and column widths from the +header of the catalog, and enters entry mode positioned at the end +of the file. If the parameter \fIreview\fR = "yes", then the user can +review and verify existing catalog entries before entering new ones. +When entry mode is terminated MKCATALOG enters edit mode +in the usual way. + +If \fIcatalog\fR exists but was not created with MKCATALOG, MKCATALOG +enters edit mode immediately. + +If \fIcatalog\fR is a standard star catalog, the user should be aware +that the object ids he/she has typed in, are those against which the object +ids in the standard star observations files will be matched by the +fitting task FITPARAMS. +Normally the user is expected to edit the object ids in the standard +star observations +files to match those in the standard star catalog. +For example, the PHOTCAL APPHOT/DAOPHOT pre-processor tasks MKNOBSFILE +and MKOBSFILE, produce observations files whose object ids +are of the form "field-#", where "field" is the name +of the observed field and "#" is a sequence number, which is defined +only if there is more than one observed star in the field. +In this scheme the id of the the fourth observed star in the field "M92" +is "M92-4". If this star is actually the standard star "IX-10" in +\fIcatalog\fR, the user must change the object id in the observations file +to "IX-10". Alternatively the user can set up the naming +convention in \fIcatalog\fR itself, to match the naming +convention of MKNOBSFILE +or MKOBSFILE by assigning the standard stars names like "field-#" and +subsequently measuring the standard stars in the same order as they +appear in the catalog. In this scheme star, "M92-4" in +the observations file would also be "M92-4" in the standard star +catalog, and no editing would be required. This technique is most useful +for standard sequences in clusters. + +THE MKCATALOG TASK AND THE ENTIRE PHOTCAL PACKAGE IMPOSE THE FOLLOWING +RESTRICTIONS +ON BOTH STAR ID NAMES AND THE COLUMN ID NAMES THAT MAY BE ASSIGNED, AND ON +THE FORMAT OF EACH FIELD. + +Object id names must be composed of characters in the set [a-z,A-Z,0-9,+,-,_]. +Other characters may be included as part of the user id, but +will be ignored by the PHOTCAL id matching code. Object id names are +case insensitive. To the id matching code the name "BD+61_305" is the +same as "bd+61_305". + +Column names must be composed of characters in the set [a-z,A-Z,0-9] +and the first character of the column name must be a letter of the alphabet. +This means for example, that an individual column cannot be assigned the +name "B-V", since "B-V" will be interpreted as an arithmetic expression not +as a variable, by the PHOTCAL equation parsing routines. +"B-V" may be replaced with something like "BV" or "BMV". +MKCATALOG will complain if the user tries to enter an illegal column name. +Column names are case sensitive. Column "BV" is not the same as +column "bv". + +Whitespace is not permitted in either the object ids or in the column +values. MKCATALOG will truncate any id or column value at the first +whitespace encountered. The column widths entered by the user are used +solely to determine +the maximum width of each field (excess characters will be truncated) +and to align the columns for ease of +visual inspection by the user. The column widths are not used by the +PHOTCAL catalog reading code. + +.ih +EXAMPLES + +1. Create a new standard star catalog containing the 3 photometric indices +V, B-V, and U-B and their respective errors. Note that MKCATALOG supplies +default names of the form "error(name)" for the error columns where "name" +is the name of the previous column. Users are strongly urged to use the +default names since they simplify the use of the statistical weighting +scheme in the FITPARAMS task. If no error information is available +error column entry can be skipped by typing <-> in response to the query +for an error column name. + +.nf +ph> mkcatalog UBVcat + +... enter the column names, error column names and widths as prompted + and shown below, note that the end-of-file character <EOF> is + actually ^Z in this case + +Enter the id column name (name, <CR>=ID, <EOF>=quit entry): + Enter width of id column (width, <CR>=15): +Enter a name for column 2 (name, <CR>=COL2, <EOF>=quit entry): V + Enter width of column 2 (width, <CR>=10): +Enter a name for error column 3 (name, <CR>=error(V), <->=skip): + Enter width of column 3 (width, <CR>=10): +Enter a name for column 4 (name, <CR>=COL4, <EOF>=quit entry): BV + Enter width of column 4 (width, <CR>=10): +Enter a name for error column 5 (name, <CR>=error(BV), <->=skip): + Enter width of column 5 (width, <CR>=10): +Enter a name for column 6 (name, <CR>=COL6, <EOF>=quit entry): UB + Enter width of column 6 (width, <CR>=10): +Enter a name for error column 7 (name, <CR>=error(UB), <->=skip): + Enter width of column 7 (width, <CR>=10): +Enter a name for column 8 (name, <CR>=COL8, <EOF>=quit entry): ^Z + + +Catalog UBVcat in file UBVcat has 7 columns + Column 1: ID + Column 2: V + Column 3: error(V) + Column 4: BV + Column 5: error(BV) + Column 6: UB + Column 7: error(UB) + + +... note that the <EOF> character terminates column definition + +... enter values for each defined column as prompted + +... type <EOF> to terminate entry mode + +... review the entries with the editor +.fi + + +2. Add new entries to the file created in example 1. + +.nf +ph> mkcatalog UBVcat + +... enter new values as prompted + +... type <EOF> to terminate entry mode + +... review the catalog with the editor +.fi + + +3. Edit an existing catalog created with a foreign program. + +.nf +ph> mkcatalog VRI.usr + +... review the catalog with the editor +.fi + +.ih +TIME REQUIREMENTS + +.ih +BUGS + +The longest line permitted by an editor varies from editor to +editor. Users should be aware that it may not be possible to use +edit mode on very long text lines. + +.ih +SEE ALSO +photcal$catalogs/README,mknobsfile,mkobsfile,mkconfig +.endhelp diff --git a/noao/digiphot/photcal/doc/mkconfig.hlp b/noao/digiphot/photcal/doc/mkconfig.hlp new file mode 100644 index 00000000..ff4e2cf2 --- /dev/null +++ b/noao/digiphot/photcal/doc/mkconfig.hlp @@ -0,0 +1,451 @@ +.help mkconfig Aug91 noao.digiphot.photcal +.ih +NAME +mkconfig -- create a new configuration file +.ih +USAGE +mkconfig config +.ih +PARAMETERS +.ls config +The name of the new configuration file. +.le +.ls catalog +The source of the standard star catalog format description. +\fICatalog\fR may be one of the supported standard star +catalogs maintained +in the directory "photcal$catalogs/", a catalog created with +MKCATALOG, the standard input "STDIN", +or a file created by the user containing the catalog +format description. +\fICatalog\fR is not prompted for if \fItemplate\fR is "". +.le +.ls observations +The source of the observations file format description. +\fIObservations\fR may be a catalog created by MKNOBSFILE, +MKOBSFILE, OBSFILE, or MKCATALOG, the standard input "STDIN", +or a file created by the user containing the observations file format +description. \fIObservations\fR is not prompted for if \fItemplate\fR is "". +.le +.ls transform +The source of the transformation equations definition. +\fITransform\fR may be the name of one of the supported standard star +catalogs maintained in the directory "photcal$catalogs/", +the standard input "STDIN", or a file created by the user +containing the transformation equations definition. +\fITransform\fR is not prompted for if \fItemplate\fR is "". +.le +.ls template = "" +The name of an existing configuration file that can be used as a template +for the new configuration file. +If \fItemplate\fR is the null string "", then MKCONFIG +prompts the user for the source of the standard star catalog +and observations file format descriptions +\fIcatalog\fR and \fIobservations\fR, and the source of the transformation +equation definitions \fItransform\fR. +If \fItemplate\fR exists, +MKCONFIG copies \fItemplate\fR into \fIconfig\fR and enters the editor +if \fIedit\fR is "yes". +.le +.ls catdir = ")_.catdir" +The directory containing the supported standard star catalogs. +The default parameter value redirects \fIcatdir\fR +to a package parameter of the same name. A list of standard +catalogs may be obtained by printing the file "photcal$catalogs/README". +Alternatively the user may create their own standard star catalogs +and standard star catalog directory. +.le +.ls verify = no +Verify each new entry in the configuration file as it is entered? +.le +.ls edit = yes +Enter the editor and review the new configuration file? +.le +.ls check = yes +Check the new configuration file for semantic and syntax errors? +.le +.ls verbose = no +Print detailed information about the results of the check step instead +of only a short summary? +.le + +.ih +DESCRIPTION + +MKCONFIG is a script task which creates and/or edits the configuration +file \fIconfig\fR. If the configuration file already +exists MKCONFIG, quits with a warning message. If the configuration file is +a new file, MKCONFIG either prompts the +user for input if \fItemplate\fR = "", or copies the existing configuration +file \fItemplate\fR into \fIconfig\fR. + +If \fItemplate\fR is "", MKCONFIG prompts the user for: +1) the source of the standard star catalog format description +\fIcatalog\fR, which assigns names to the columns of the standard star +catalog, +2) the source of the observations file format description +\fIobservations\fR, which assigns names to the columns of the observations file, +3) and the source of the transformation equations \fItransform\fR, which +defines the form of the transformation equations from the +instrumental to the standard system. + +If \fIcatalog\fR, \fIobservations\fR, or \fItransform\fR +are set to the standard input "STDIN", MKCONFIG prompts for input from +the terminal, verifying the input as it is entered if \fIverify\fR is "yes". + +If \fIcatalog\fR is a standard star catalog name or a file name, +MKCONFIG searches 1) the current directory for the associated format +description file "fcatalog.dat", 2) the directory +\fIcatdir\fR for the format description file "fcatalog.dat", +and 3) the current directory for a file called "catalog", in that order. +\fICatalog\fR is usually one of the supported standard star catalogs or +a standard star catalog created by the user with MKCATALOG. + +If \fIobservations\fR is an observations file name or a file name, +MKCONFIG searches 1) the current directory for the format +description file "fobservations.dat", and 2) +the current directory for a file called "observations", in that order. +\fIObservations\fR is usually created by the user with MKNOBSFILE or MKOBSFILE. + +If \fItransform\fR is assigned a standard star catalog name or a file name, +MKCONFIG searches 1) the directory +\fIcatdir\fR for the transformation equations definition file +"ttransform.dat", and 2) +the current directory for a file called "transform", in that order. +\fITransform\fR is usually one of the supported standard star catalogs or +"STDIN". + +The default photometric standards directory is "photcal$catalogs/". +A list of supported catalogs is shown below. +The standard catalog format description files may be listed or +printed with the commands +"dir photcal$catalogs/f*.dat" or "lprint photcal$catalogs/f*.dat" respectively. +The standard transformation equation definition files may be listed or +printed with +the commands "dir photcal$catalogs/t*.dat" or "lprint photcal$catalogs/t*.dat" +respectively. + +After data entry, and if \fIedit\fR is "yes", +MKCONFIG enters the default text editor defined by the +IRAF environment variable \fIeditor\fR. Small +corrections to the configuration file may be made at this point. +Next the configuration file is checked for semantic and syntax errors +if \fIcheck\fR is "yes" and the results are written on the terminal. + +.ih +STANDARD CATALOG FORMAT AND TRANSFORM FILES + +The list of standard star catalog files, catalog format description files +and transformation equation definitions files is presented below. + +.nf + # catalogs # formats # transformations + + landolt.dat flandolt.dat tlandolt.dat +.fi + +.ih +THE CONFIGURATION FILE + +The \fIconfiguration file\fR is a text file which describes how the input data +is organized in the input files, and defines the form of the transformation +equations required to convert from the instrumental to the standard system. + +The input data is assumed to come from two sources, +standard star catalogs known as \fIcatalogs\fR +and \fIobservations\fR files. +The \fIcatalog\fR files contain the standard indices of a set of standard +stars, referenced in the catalog by a name called the +matching name. +The \fIobservations\fR files contain the instrumental magnitudes or colors of +a subset of the standard stars and/or program stars, also referenced by a +matching name. +The names of the observed standard stars must match the names in the +standard star catalog. The matching names must be stored in column 1 +in both the catalog and observations files. + +The configuration file is divided up into three sections: the \fIcatalog +section\fR which describes the format of the catalog files, the +\fIobservations section\fR which describes the format of the observation +files, and the \fItransformation section\fR which defines the +transformation equations. The catalog section must always appear before the +observation section, and the observation section must always appear before the +transformation section. + +The \fIcatalog and observations sections\fR are used to assign +names to the columns in the input catalog and observations files. +These columns may later be referenced by name and the names used +as variables in the transformation equations. + +The \fItransformation section\fR is used to define the +transformation equations, +to specify which parameters are to be varied and which are to be held constant +during the fitting process, +and to assign initial values to all the parameters. +Any number of transformation equations may be defined in +the transformation section. + +The transformation section may also be used to, OPTIONALLY, +define temporary variables (the set equations), define explicitly +the derivatives of the transformation equations to be fit with respect +to the parameters (derivative equations +and delta declarations), define expressions for the weights and +errors (weight and error equations), and define an expression to be +plotted (the plot equation). + +For a detailed description +of the grammar and syntax of the configuration file type \fI"help config"\fR. + +The following examples show typical configuration files for two different types +of photometric calibrations. + + +\fIExample 1\fR. A sample configuration file for reducing UBV photoelectric +photometry. Note that the instrumental magnitudes are all on the right-hand +side of the transformation equation and that the standard magnitudes and colors +are all +on the left-hand side. Once the values of the transformation equation +parameters are computed by FITPARAMS using observations of the standard stars, +standard magnitudes and colors for the program stars can be computed simply by +evaluating the right-hand side of the transformation equation using +the task EVALFIT. In this type of setup the equations are fit separately +and evaluated separately. Note also the use of the error column declarations +in the observation section, and the use of the const statement to fix the +values of some parameters. + +.nf +# Configuration file for reducing UBV photoelectric photometry. + +catalog + +V 2 # V magnitude +BV 3 # B - V color +UB 4 # U - B color + +observation + +v 2 # v instrumental magnitude +b 3 # b instrumental magnitude +u 4 # u instrumental magnitude +error(v) 5 # error in v instrumental magnitude +error(b) 6 # error in b instrumental magnitude +error(u) 7 # error in u instrumental magnitude +X 8 # airmass + +transformation + +fit v1 = 0.0, v2=0.16, v3=-0.043 +const v4 = 0.0 +VFIT: V = v1 + v - v2 * X + v3 * (b - v) + v4 * X * (b - v) + +fit b1 = 0.0, b2=0.09, b3=1.266 +const b4 = 0.0 +BVFIT: BV = b1 - b2 * X + b3 * (b - v) + b4 * X * (b - v) + +fit u1 = 0.0, u2=0.300, u3=0.861 +const u4 = 0.0 +UBFIT: UB = u1 - u2 * X + u3 * (u - b) + u4 * X * (u - b) +.fi + + +\fIExample 2\fR. A sample configuration file for reducing UBV CCD photometry. +Note that the instrumental magnitudes are all on the left-hand side of the +transformation equations and the standard star magnitudes and colors +are all on the right-hand +side. Once the values of the transformation equation parameters have been +computed by FITPARAMS using observations of the standard stars, the +standard magnitudes and colors of the program stars +can be computed by inverting the system of equations using the task +INVERTFIT. +In this type of setup the equations are fit independently, but evaluated +as a system. +Note also that the telescope filter slots 1, 2 and 3 were assigned to +filters v, b and u respectively which is why MKNOBSFILE assigned the names +m1, m2, m3 to v, b, and u respectively. The user can change these if desired. +Note also the use of the error declaration statements in both the catalog +and the observations section. + +.nf +catalog + +V 2 # V magnitude +BV 3 # B - V color +UB 4 # U - B color +error(V) 5 # error in V magnitude +error(BV) 6 # error in B-V color +error(UB) 7 # error in U-B color + +observation + +ut1 3 # ut time of filter 1 observation +X1 4 # airmass of filter 1 observation +m1 7 # filter 1 instrumental magnitude +error(m1) 8 # error in filter 1 instrumental magnitude +ut2 10 # ut time of filter 2 observation +X2 11 # airmass of filter 2 observation +m2 14 # filter 2 instrumental magnitude +error(m2) 15 # error in filter 2 instrumental magnitude +ut3 17 # ut time of filter 3 observation +X3 18 # airmass of filter 3 observation +m3 19 # filter 3 instrumental magnitude +error(m3) 20 # error in filter 3 instrumental magnitude + + +transformation + +fit u1 = 0.0, u2=0.68, u3=0.060 +UFIT: m3 = u1 + V + BV + UB + u2 * X3 + u3 * UB + +fit b1 = 0.0, b2=0.30, b3=0.010 +BFIT: m2 = b1 + V + BV + b2 * X2 + b3 * BV + +fit v1 = 0.0, v2=0.15, v3=0.000 +VFIT: m3 = v1 + V + v2 * X3 + v3 * BV +.fi + +.ih +EXAMPLES + +1. Type in from scratch a new configuration file to reduce some UBV +photoelectric photometry. The catalog and observations file are simple +text files written with the user's own data acquisition software, whose +format is known by the user. + +.nf + ph> mkconfig ubv.cfg + + ... answer "STDIN" in response to the query for the catalog + parameter, and enter the standard star catalog format + description as prompted + + ... a sample input session is shown below, note that in this + examine <EOF> is implemented as ^Z + + ENTER THE STANDARD STAR CATALOG FORMAT DESCRIPTION + + Enter column definition (name number, ?=help, <EOF>=quit entry): V 2 + Enter column definition (name number, ?=help, <EOF>=quit entry): BV 3 + Enter column definition (name number, ?=help, <EOF>=quit entry): UB 4 + Enter column definition (name number, ?=help, <EOF>=quit entry): ^Z + + ... answer "STDIN" in response to the query for the + observations parameter, and enter the observations file + format description as prompted + + ... a sample input session is shown below, note that in this + example <EOF> is implemented as ^Z + + ENTER THE OBSERVATIONS FILE FORMAT DESCRIPTION + + Enter column definition (name number, ?=help, <EOF>=quit entry): v 2 + Enter column definition (name number, ?=help, <EOF>=quit entry): b 3 + Enter column definition (name number, ?=help, <EOF>=quit entry): u 4 + Enter column definition (name number, ?=help, <EOF>=quit entry): X 5 + Enter column definition (name number, ?=help, <EOF>=quit entry): ^Z + + ... answer "STDIN" in response to the query for the + transform parameter, and enter the transformation + equations as prompted + + ... a sample input session is shown below for a single equation is + shown below, note that in this example <EOF> is implemented as + ^Z + + ENTER THE TRANSFORMATION EQUATIONS + + Enter the label and functional form for EQUATION 1 + + Enter label (e.g. VFIT) (label, ?=help, <EOF>=quit entry): VFIT + Enter equation (equation, equation\=continue, ?=help, <EOF>=quit entry): + V = v + v1 + v2 * X + v3 * (b - v) + + Enter initial values for the parameters to be fit in EQUATION 1 + + Enter parameter 1 (name value, ?=help, <EOF>=quit entry):v1 25. + Enter parameter 2 (name value, ?=help, <EOF>=quit entry):v2 -.15 + Enter parameter 3 (name value, ?=help, <EOF>=quit entry):v3 1.06 + Enter parameter 4 (name value, ?=help, <EOF>=quit entry):^Z + + Enter initial values for the parameters to be held constant in + EQUATION 1 + + Enter parameter1 and value (name value, ?=help, <EOF>=quit entry):^Z + + Enter the label and functional form for EQUATION 2 + + Enter label (e.g. VFIT) (label, ?=help, <EOF>=quit entry): BFIT + + ... after the program enters the editor make any small changes + required + + ... examine the final output for errors + + ph> edit ubv.cfg + + ... correct any errors with the editor + + ph> chkconfig ubv.cfg + + ... check the newly edited file for errors + +.fi + +2. Create a configuration file to reduce some JHK photometry. In this +example the user has created a JHK standard star catalog called jhkcat +using the task MKCATALOG, an observations file called jhkobs +using the task MKNOBSFILE, and has decided to type in the transformation +equations by hand using the default editor. + +.nf + ph> mkconfig jhk.cfg jhkcat jhkobs + + ... answer "STDIN" in response to the query for the + transform parameter, followed by <EOF>, usually ^Z + to terminate prompting for the transformation equations + + ... use the editor to enter the transformation equations + + ... check the result for errors + + ph> edit jhk.cfg + + ... correct errors found in previous run using the editor + + ph> chkconfig jhk.cfg + + ... check the edited file for errors +.fi + +3. Create a new configuration file for reducing some UBVR photometry, using +the UBVR standards in the landolt UBVRI standard star catalog. The standard +star observations file "stdobs" was created with the task MKNOBSFILE. + +.nf + ph> mkconfig ubvr.cfg landolt stdobs landolt + + ... read in the catalog format description for the + landolt UBVRI standards catalog + + ... read in the observations file format description + created by a previous run of mknobsfile + + ... read in the sample transformation description file for the + landolt UBVRI system + + ... use the editor to delete any references to catalog + variables that are not going to be used in the + transformation equations, and to edit the transformation + equations as desired + + ... check the result for errors + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +edit,chkconfig,mknobsfile,mkobsfile +.endhelp diff --git a/noao/digiphot/photcal/doc/mkimsets.hlp b/noao/digiphot/photcal/doc/mkimsets.hlp new file mode 100644 index 00000000..1ba9165a --- /dev/null +++ b/noao/digiphot/photcal/doc/mkimsets.hlp @@ -0,0 +1,356 @@ +.help mkimsets Apr94 noao.digiphot.photcal +.ih +NAME +mkimsets -- create an image set file from the observations for input +to MKNOBSFILE OR OBSFILE +.ih +USAGE +mkimsets imlist idfilters imsets +.ih +PARAMETERS +.ls imlist +The file(s) containing all the image names and filter ids associated with +the observations. +\fIImlist\fR is a list of APPHOT/DAOPHOT databases if \fIinput\fR = +"photfiles", a list of images if \fIinput\fR = "images", or the name +of a user text file if \fIinput\fR = "user". +The default input is a list of APPHOT/DAOPHOT databases. +.le +.ls idfilters +The ids of the filters, separated by whitespace or +commas, which define a complete observation. +The order in which the filter ids are listed in the string \fIidfilters\fR +determines the order in which the image names associated with each observation +are written in \fIimsets\fR. +.le +.ls imsets +The name of the output image set file which lists each observation of +each star field, assigns a name +to each observation, and specifies which images belong to the same +observation of that star field. +.le +.ls imobsparams = "" +The name of the output image list file containing the image name, +the filter id, +and the quantities specified by \fIfields\fR, for each +unique image referenced in \fIimlist\fR. +\fIImobsparams\fR includes changes made by the user if \fIedit\fR is +"yes". If \fIimobsparams\fR is "" the output image list +is not saved. +.le +.ls input = photfiles +The source of the information used to create the image set file. +The options are: +.ls photfiles +Extract the image list from the APPHOT/DAOPHOT +databases containing +the photometry. This option uses the PTOOLS task DUMP to extract +the image name, the filter id, the exposure time, the airmass, the +time of observation, and +other user selected fields \fIfields\fR from the database files. +.le +.ls images +Extract the image list from the headers of the images containing +the objects measured +with APPHOT or DAOPHOT. This option uses the IMAGES task HSELECT to extract +the image name, the filter id \fIfilter\fR, and other user selected +fields \fIfields\fR from the image headers. Useful additional fields +might be the image title and the time of the observation. +.le +.ls user +Extract the image list from a user created file which has the +image name in the first column, the filter id in the column +\fIfilter\fR, and +other useful information in the columns specified by \fIfields\fR. +.le +.le +.ls filter +The filter id keyword. +\fIFilter\fR is always the APPHOT/DAOPHOT database keyword "IFILTER" +if \fIinput\fR is "photfiles", +the image header keyword which defines the filter id if \fIinput\fR is +"images", or the number of the column +containing the filter id, if \fIinput\fR is "user". +.le +.ls fields = "" +The list of additional fields, besides the image name and filter id, +to be extracted from \fIimlist\fR, separated by whitespace or commas. +If \fIinput\fR is "photfiles" \fIfields\fR is a list of APPHOT/DAOPHOT +keywords including "itime,xairmass"; if \fIinput\fR is "images" +\fIfields\fR is a list of image +header keywords; if \fIinput\fR is "user" \fIfields\fR is a list of the +column numbers defining the fields to be extracted from the user file. +\fIFields\fR may include any quantities, for example airmass, image title, or +the time of the observation, which aid the user in the interactive +image name grouping process. +.le +.ls sort = "" +Sort the extracted image list in order of the value of the quantity \fIsort\fR. +\fISort\fR must be one of the fields +\fI"image"\fR, \fIfilter\fR, or \fIfields\fR if \fIinput\fR +is "images" or "photfiles", or the column number in the user file of the +field to be sorted on if \fIinput\fR is "user". +\fISort\fR is used to reorder the image list +before entering the editor. +.le +.ls edit = yes +Edit the extracted image name list interactively, checking that the images +belonging to a single observation are adjacent to one another in the list, +and that the filter ids are present and match those in \fIidfilters\fR. +For each observation there must be an image name for every filter +in \fIidfilters\fR. +Missing set members must be assigned the image name "INDEF" for undefined +and the filter id of the missing observation. +.le +.ls rename = yes +Enter new names for each observation of each field interactively. +If \fIrename\fR is "no", default names +of the form "OBS1", "OBS2", ..., "OBSN" are assigned. If \fIrename\fR is "yes", +MKIMSETS prints each image set +on the terminal and prompts the user for the new name. +Images sets containing a single standard star observation should be assigned +the name of the standard star in the standard star catalog. +.le +.ls review = yes +Review and edit \fIimsets\fR to check that the image set names are correct +and that the images names have been properly grouped into sets. +.le +.ih +DESCRIPTION +MKIMSETS is a script task which takes as input a list of +the image names and filter ids, \fIimlist\fR, associated +with objects whose magnitudes have been measured with APPHOT, DAOPHOT, +or a user program, and produces the image set file \fIimsets\fR +required as input by the preprocessor tasks MKNOBSFILE or OBSFILE. +MKIMSETS is used in conjunction with MKNOBSFILE OR OBSFILE to combine many +individual digital photometry measurements, for example standard star +measurements, +into a single observations file. The source of the input image list is +a list of IRAF images if \fIinput\fR is "images", +a list of APPHOT or DAOPHOT database files if \fIinput\fR is "photfiles", +or a user supplied text file if \fIinput\fR is "user". + +The output image set file \fIimsets\fR lists each observation of +each star field, assigns a name supplied by the user +to each observation, and specifies which images belong to the same +observation of that star field. +In the case of image sets which contain a single standard star measurement, +the image set name should +match the name of the standard star in the standard star catalog. + +The optional output image observing parameters file \fIimobsparams\fR +lists each unique image in \fIimlist\fR, its +filter id \fIfilter\fR, and other user specified fields \fIfields\fR. +\fIImobsparams\fR may be edited by +the user, and used by the preprocessor tasks MKNOBSFILE or OBSFILE +to correct erroneous or undefined values of +filter id, exposure time, airmass and time of observation in the input +databases. By default \fIimobsparams\fR is not written. + +After task initialization, MKIMSETS extracts each unique image name, +the corresponding filter id stored in column \fIfilter\fR, +and the corresponding values of the user defined fields \fIfields\fR, +from the input list \fIimlist\fR, and writes the resulting image list +in tabular form to a temporary file. +The temporary image list file contains the image name in column 1, +the value of \fIfilter\fR in column 2, and the values of +any additional fields in succeeding columns in the order they were +specified in \fIfields\fR. + +If \fIsort\fR is one of the extracted +fields "image", \fIfilter\fR, or \fIfields\fR, MKIMSETS sorts the image +list based on the values of \fIsort\fR, before writing the results to the +the temporary image list file. + +If \fIedit\fR is "yes", the user enters the text editor and edits the +temporary image list interactively. +The image list must be arranged so that members of each image set are +adjacent to each other in the image list. +Missing images may be represented by +an INDEF in column 1, the appropriate filter id in column 2, and +INDEF in any other columns. +The edit step is necessary if the image names are not in any logical +order in \fIimlist\fR for \fIinput\fR = "images", +do not occur in any logical order in the APPHOT/DAOPHOT +databases for \fIinput\fR = "photfiles", or are not listed logically +in \fIimlist\fR for \fIinput\fR = "user". +At this point MKIMSETS saves the temporary image list in the text file +\fIimobsparams\fR, if \fIimobsparams\fR is defined. + +After the initial edit, MKIMSETS groups the images in the temporary image list, +by using the filter ids in \fIidfilters\fR, and assuming that the image +names are in logical order. +If \fIrename\fR is "yes", MKIMSETS prompts the user for the name of each +image set. Otherwise the default names OBS1, OBS2, ..., OBSN are +assigned. +If \fIreview\fR is "yes", MKIMSETS enters the editor, permitting the user +to review \fIimsets\fR and interactively +correct any mistakes. +Image sets are written to \fIimsets\fR, 1 set +per line with the image set name in column 1, a colon in column 2, +followed by, in filter order and separated by whitespace, the names of the +images of that field, for that observation. + +.ih +EXAMPLES + +1. Create an image set file from a list of APPHOT databases which +contain UBV observations of 5 standard stars. The UBV filters are +identified in the APPHOT databases by the filters ids "1","2", "3" +respectively. There is one database file +for each star measured. Since data for each of the stars was taken +sequentially and the images were read sequentially off tape, the user +requests MKIMSETS to sort the extracted data by image name. Note that +the time of observation field was undefined in the input data sets. + +.nf + ph> mkimsets *.mag.* "1,2,3" jan10.stdim sort="image" + + ... MKIMSETS constructs the image list and sorts on + the image name + + ... MKIMSETS enters the editor and lists the first few + lines of the intermediate image list file + + im001 1 3.0 1.150 INDEF + im002 2 2.0 1.150 INDEF + im003 3 2.0 1.140 INDEF + im004 1 6.0 1.300 INDEF + im005 2 4.0 1.300 INDEF + im006 3 2.0 1.300 INDEF + im007 1 5.0 1.263 INDEF + im008 3 1.0 1.270 INDEF + im009 2 3.0 1.270 INDEF + im010 1 2.0 1.030 INDEF + im011 3 10.0 1.030 INDEF + im012 1 30.0 1.093 INDEF + im013 2 20.0 1.110 INDEF + im014 3 10.0 1.110 INDEF + + ... the user notices that standard 4 is missing a B + observation and that the observations of standard 3 + are out of order and edits the file as follows + + im001 1 3.0 1.150 INDEF + im002 2 2.0 1.150 INDEF + im003 3 2.0 1.140 INDEF + im004 1 6.0 1.300 INDEF + im005 2 4.0 1.300 INDEF + im006 3 2.0 1.300 INDEF + im007 1 5.0 1.263 INDEF + im009 2 3.0 1.270 INDEF + im008 3 1.0 1.270 INDEF + im010 1 2.0 1.030 INDEF + INDEF 2 INDEF INDEF INDEF + im011 3 10.0 1.030 INDEF + im012 1 30.0 1.093 INDEF + im013 2 20.0 1.110 INDEF + im014 3 10.0 1.110 INDEF + + ... the user quits the editor + + ... MKIMSETS groups the image list prompting for a + name for each image set + + ... MKIMSETS enters the editor, displays the first few + lines of the imsets file, and allows the user to + correct any mistakes + + STD1 : im001 im002 im003 + STD2 : im004 im005 im006 + STD3 : im007 im009 im008 + STD4 : im010 INDEF im011 + STD5 : im012 im013 im014 + + ... quit the editor +.fi + + +2. Create the image set file from the list of IRAF images associated with +the APPHOT databases in example 1. The images contain the image +header keyword "f1pos" which specifies the filter id and which may assume +the values "1,2,3" where "1,2,3" stand for "U,B,V". +Since the data for the individual stars was taken sequentially the user +requests MKIMSETS to print out value of the sidereal time stored in the +image header keyword "ST", and to sort on that +parameter. The image title is also printed out as an image grouping +aid to the user. It is placed last in the fields parameter because any +internal blanks in the title would otherwise confuse the sorting routine. + +.nf + ph> mkimsets *.imh "1,2,3" jan10.stdim input="images" \ + filter="f1pos" fields="ST,i_title" sort="ST" + + ... MKIMSETS constructs the image list and sorts on + the column containing the sidereal time + + ... MKIMSETS enters the editor and lists the first + few lines of the temporary image list file, the sidereal + time is in column 3 and the image title containing + some blanks is in column 4 + + im001 1 12:30:50.2 STD1 U filter + im002 2 12:35:40.1 STD1 B + im003 3 12:40:16.2 STD1 v filter + im004 1 12:50:50.2 STD2 + im005 2 12:55:40.1 STD2 B + im006 3 12:59:58.2 STD2 V + im007 1 13:10:50.2 STD3 U + im008 3 13:15:40.1 STD3 V + im009 2 13:20:16.2 STD3 B + im010 1 13:30:50.2 STD4 u + im011 3 13:40:40.1 STD4 V + im012 1 13:50:50.2 STD5 U + im013 2 13:55:40.1 STD5 B + im014 3 13:59:58.2 STD5 V + + ... the user notices that standard 4 is missing a B + observation and that the observations of standard 3 + are out of order and edits the file as follows + + im001 1 12:30:50.2 STD1 U filter + im002 2 12:35:40.1 STD1 B + im003 3 12:40:16.2 STD1 v filter + im004 1 12:50:50.2 STD2 + im005 2 12:55:40.1 STD2 B + im006 3 12:59:58.2 STD2 V + im007 1 13:10:50.2 STD3 U + im009 2 13:20:16.2 STD3 B + im008 3 13:15:40.1 STD3 V + im010 1 13:30:50.2 STD4 u + INDEF 2 INDEF INDEF + im011 3 13:40:40.1 STD4 V + im012 1 13:50:50.2 STD5 U + im013 2 13:55:40.1 STD5 B + im014 3 13:59:58.2 STD5 V + + ... the user quits the editor + + ... MKIMSETS groups the edited image list prompting for a + name for each image set + + ... MKIMSETS enters the editor, displays the first few + lines of the image set file and permits the + user to correct any mistakes + + STD1 : im001 im002 im003 + STD2 : im004 im005 im006 + STD3 : im007 im009 im008 + STD4 : im010 INDEF im011 + STD5 : im012 im013 im014 + + ... quit the editor + + ... note that MKIMSETS did not save the output image list + +.fi + + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +images.hselect,ptools.dump,mknobsfile,mkobsfile +.endhelp diff --git a/noao/digiphot/photcal/doc/mknobsfile.hlp b/noao/digiphot/photcal/doc/mknobsfile.hlp new file mode 100644 index 00000000..cb2497b3 --- /dev/null +++ b/noao/digiphot/photcal/doc/mknobsfile.hlp @@ -0,0 +1,516 @@ +.help mknobsfile Apr94 noao.digiphot.photcal +.ih +NAME +mknobsfile -- prepare an observations file from a list of APPHOT/DAOPHOT +files containing observations of objects in one or more fields +.ih +USAGE +mknobsfile photfiles idfilters imsets observations +.ih +PARAMETERS +.ls photfiles +The APPHOT or DAOPHOT output database(s) containing the standard +and/or program object instrumental magnitudes. These databases +are normally created by the +APPHOT QPHOT and PHOT tasks or the DAOPHOT PHOT task, but may also +have been written by the DAOPHOT PEAK, NSTAR or ALLSTAR tasks. +.le +.ls idfilters +The list of filter ids separated by whitespace or +commas which define a complete observation. +.le +.ls imsets +The input image set file which lists the observations of +each field, assigns a name to each +field, and tells MKNOBSFILE which images belong to the same +observation of that field. +Only observations corresponding to the images specified in \fIimsets\fR +will be extracted from \fIphotfiles\fR. +Observations are listed in \fIimsets\fR, 1 observation +per line with the field name in column 1, a colon in column 2, +followed by the names of the +images of that field which belong to that observation. +The format of \fIimsets\fR is described in detail below. +.le +.ls observations +The output observation file suitable for input to FITPARAMS or +EVALFIT/INVERTFIT. +.le +.ls wrap = yes +Format the output observations file for easy reading ? If wrap = yes then +the observations for each filter are written to a separate line and the +* character in column 1 is interpreted as a continuation character. Otherwise +all the observations for a single object are written to a single line +where the maximum size of a line is SZ_LINE characters. +.le +.ls obsparams = "" +The name of an optional text file containing the correct filter ids, +exposure times, airmasses, and times of observation for each image whose values are either +not stored or incorrectly stored in \fIphotfiles\fR. +The observing parameters for each image are listed in the file +\fIobsparams\fR, 1 image per line with the image +name in column 1 and the filter ids, exposure times, airmasses, and times of observation, +in columns \fIobscolumns\fR. +The image names must match those in +\fIimsets\fR. Images which have no +entries in \fIobsparams\fR are assigned the values stored 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 ob observation respectively. +The number 0 can be used as a place holder in the \fIobscolumns\fR 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. +The default value of \fIobscolumns\fR corresponds to +the format of the default \fIobsparams\fR file produced by MKIMSETS. +.le +.ls minmagerr = 0.001 +The error that will be assigned to a non-INDEF valued magnitude measurement +if its recorded magnitude error is less than \fIminmagerr\fR. +.le +.ls shifts = "" +The name of the text file specifying the x and y shifts to be ADDED +to the x-y positions of all objects in an image before position matching (the +original x's and y's are retained in the output). +Shifts are listed for each image, 1 image per line with +the name of the image in column 1, followed by the x and y shifts +in columns 2 and 3 respectively. Image names must match those in +\fIimsets\fR. Images for which +no shift is supplied are assigned x and y shifts of zero. +.le +.ls apercors = "" +The name of the text file specifying the aperture corrections +to be ADDED to the extracted magnitudes. +Aperture corrections are listed for each image, 1 image per line with +the name of the image in column 1, followed by the aperture correction in +magnitudes in column 2. +The image names must match those in +\fIimsets\fR. Images for which +no aperture correction is supplied are assigned a default value of 0.0. +.le +.ls aperture = 1 +The aperture number +in \fIphotfiles\fR for which the magnitude is extracted, if the magnitudes +were measured through more than one aperture. +By default the magnitude through the first aperture is extracted. +.le +.ls tolerance = 5.0 +The tolerance in pixels for matching objects in the same observation, +but different images. MKNOBSFILE extracts +the x and y coordinates of each object in each image of a given observation +from \fIphotfiles\fR, adds the shift for that image in +\fIshifts\fR to the extracted x-y coordinates, +and matches the objects to within \fItolerance\fR pixels. +Missing objects are assigned INDEF entries in \fIobservations\fR. +If \fItolerance\fR is less +than or equal to 0 no coordinate matching is done, and objects are +matched in order of occurrence with missing objects being assigned +INDEF values. +.le +.ls allfilters = no +Output only objects which are successfully matched in all the filters +specified by \fIidfilters\fR. +.le +.ls verify = no +Verify any data entered interactively by the user ? +.le +.ls verbose = yes +Print status, warning, and error messages ? +.le + +.ih +DESCRIPTION + +MKNOBSFILE takes a list of APPHOT or DAOPHOT database files \fIphotfiles\fR, +where each file contains observations of 1 or more objects taken through 1 or +more filters, and the image set file \fIimsets\fR and prepares an observations +file \fIobservations\fR. +MKNOBSFILE is optimized for creating a single observations file from a large +number of observations of fields containing only a single star, or observations +of a large number of +fields containing only a few stars per field. MKNOBSFILE IS NORMALLY THE +PREPROCESSOR OF CHOICE FOR PREPARING STANDARD STAR OBSERVATIONS FILES. + +MKNOBSFILE performs the following functions: 1) extracts the quantities +image name, x and y position, exposure time, filter id, +airmass, time of observation, magnitude and error from +\fIphotfiles\fR, 2) corrects any erroneous or missing values of filter id, +exposure time, and airmass in \fIphotfiles\fR, 3) associates each +field with 1 or more sets of images of that +field taken through different filters 4) matches individual objects within +a given observation by order of occurrence or x-y position, +5) assigns a unique name to each object in each field. + +The image set file \fIimsets\fR assigns a name to each star field. +For fields containing only a single standard star this name should match the +name of the standard star in the standard star catalog. For fields +containing more than one star, MKNOBSFILE constructs a unique name for +each object in the field by adding +a sequence number to the field name in \fIimsets\fR, which if the star +is a standard star, the user must +later edit. For example the fourth star in the field "M92" will be assigned +the name "M92-4" in \fIobservations\fR. If this star is a standard star and +its true name is "IX-10" in the standard star catalog, then the user +must change "M92-4" to "IX-10" in \fIobservations\fR. \fIImsets\fR also +tells MKNOBSFILE which images +in \fIphotfiles\fR are images of the same region of the sky belonging +to the same observation. +The format of \fIimsets\fR is described in detail below. +If the number of observations is small the user may wish to simply type in +\fIimsets\fR by hand. If the number of observations is large, +a separate task MKIMSETS is available to assist users in preparing +\fIimsets\fR. + +Values of the filter ids, exposure times, airmasses, and exposure times +which are missing or incorrect in \fIphotfiles\fR, +can be corrected by reading values listed in the columns \fIobscolumns\fR +in the file \fIobsparams\fR. The format of \fIobsparams\fR is described +in detail below. + +MKNOBSFILE matches the objects in different images within the same observation +either +by order of occurrence if \fItolerance\fR is less than or equal to 0.0, +or by x-y position. Matching by position is done by identifying which objects +in each of the +images of a given field and observation set are within \fItolerance\fR +pixels of each other. The user may supply an optional file of x and y +shifts \fIshifts\fR to be added to the object positions prior to +matching. The format of \fIshifts\fR is described in detail below. +If the parameter \fIallfilters\fR is "yes", only objects which are matched +in all the filters \fIidfilters\fR are output to \fIobservations\fR. + +MNOBSFILE permits the user to supply +an optional file of aperture corrections \fIapercors\fR containing +magnitude corrections which are added to the instrumental +magnitudes in \fIphotfiles\fR. +The format of \fIapercors\fR is described in detail below. + +Each new observations file created by MKNOBSFILE has an associated format +description file listing the column names and numbers in +\fIobservations\fR, of the fields extracted +from \fIphotfiles\fR. +This file, referenced by its parent observations file name, can be +used as input to the MKCONFIG task. +The actual name of the format description file on disk is constructed by +prepending the observations file name \fIobservations\fR with the +string "f" and +appending the string ".dat". For example if a new observations file +called "nite1stds" is created by MKNOBSFILE, a format description +file called "fnite1stds.dat" will also be created. Any pre-existing format +description file of that name, which does not have an associated observations +file, will be deleted. + +THE IMSETS FILE + +The \fIimsets\fR file lists the +observations of each field which are to be extracted from \fIphotfiles\fR, +assigns a name to each +field, and informs MKNOBSFILE which images belong to the same +observation of that field. +Observations are listed in \fIimsets\fR, 1 observation +per line with the field name in column 1, a colon in column 2, +followed by the names of the +images of that field, for that observation, separated by whitespace. +Only data for images in \fIimsets\fR which match those in +\fIphotfiles\fR will be extracted. USERS SHOULD REALIZE THAT IF THE IMAGE +NAMES IN THE PHOTOMETRY FILES INCLUDE THE EXTENSIONS ".imh" OR ".hhh", +THEN THE IMAGE NAMES IN IMSETS MUST AS WELL. + +The field name is used to generate the object names in \fIobservations\fR. +If there is only a single measured object in a field, then the +name of that object in \fIobservations\fR will be the name of the field. +If the single object is a standard star, the user should edit +\fIimsets\fR so that the field name is the same as the name of the +standard star in the standard star catalog. +If a stellar field contains more than +one measured object, MKNOBSFILE generates names of the form "field-#" +where "field" is the field name and "#" is a sequence number. +For example the fourth star in the field "M92" will be assigned the +name "M92-4" in \fIobservations\fR. If the star is a standard star, +the user must edit the object names in \fIobservations\fR +to match those in the standard star catalog. + +Any number of observations may have the same field name. This normally +occurs, for example, when multiple observations of a single standard +star or standard star field are made at several airmasses. + +If there +are no filter ids in \fIphotfiles\fR or \fIobsparams\fR then the images in +each image set are assigned the filter ids in \fIidfilters\fR in order +of occurrence. + +The \fIimsets\fR file for a set of 50 UBV frames of fifteen standard star +fields, some containing a single star and some containing several stars, +is listed below. Column 1 contains the name of the standard field. +Column 2 contains a ':'. The U, B and V +images for each field are listed in columns 3, 4 and 5 respectively. +The missing U image for field "STDFIELD7" is represented by the name "INDEF". +The standard stars in "STDFIELD1" and "STDFIELD2" were observed twice in +the same night at different airmasses. + +.nf + STDFIELD1 : nite001 nite002 nite003 + STDFIELD1 : nite045 nite046 nite047 + STDFIELD2 : nite004 nite005 nite006 + STDFIELD2 : nite048 nite049 nite050 + ... + STDFIELD7 : INDEF nite019 nite020 + ... + STDFIELD14 : nite039 nite040 nite041 + STDFIELD15 : nite042 nite043 nite044 +.fi + +THE OBSPARAMS FILE + +A sample corrections file \fIobsparams\fR for the previous set of +UBV standards observations is shown below. +The filter ids, exposure times, airmasses, and times of observation for all the images were +correctly read +from the image headers with the exception of the filter id, exposure time, +airmass, and time of observation for the first "STDFIELD2" V frame. +The correct filter id, exposure time, and airmass is supplied +in \fIobsparams\fR and \fIobscolumns\fR is set to "2 3 4 5" + +.nf + nite006 3 8 1.256 05:34:03.2 +.fi + +Zero can be used as a place holder in \fIobscolumns\fR, +as in the following example where +the user only wants to correct the exposure time and the airmass and +leave the filter id alone. In this case \fIobscolumns\fR is "0 2 3 0" +and \fIobsparams\fR looks as follows. + +.nf + nite006 8 1.256 +.fi + +Only images listed in \fIimsets\fR can have their observing parameters +modified by \fIobsparams\fR. + +THE SHIFTS FILE + +The file \fIshifts\fR lists the shifts for each image, 1 shift per line, +with the image name in column 1 and the x and y shifts in columns 2 and +3 respectively. +The image names in \fIshifts\fR must match those in \fIimsets\fR. + +A sample shifts file for the previous set of UBV standards +observations is shown below. All the standards except for "STD14" are assumed +to have no significant shifts from filter to filter. The B and V frames +for "STDFIELD14" are shifted -10 pixels in x and -5 pixels +in y with respect to the U frame. Therefore +10 and +5 pixels should be +added to the "STDFIELD14" B and V frame positions respectively before +position matching. + +.nf + nite040 10.0 5.0 + nite041 10.0 5.0 +.fi + +An alternate way of listing the same observations would be the following. + +.nf + nite039 -10.0 -5.0 +.fi + +THE APERCORS FILE + +The file \fIapercors\fR lists the aperture corrections for each image, +1 aperture correction per line, +with the image name in column 1 and the aperture correction in magnitudes +in column 2 respectively. +The image names in \fIapercors\fR must match those in \fIimsets\fR. + +The \fIapercors\fR file for the previous set of UBV observations is shown +below. +The aperture corrections for all the standard stars are assumed to be +zero except for "STDFIELD14". + +.nf + nite039 -0.150 + nite040 -0.100 + nite041 -0.090 +.fi + +.ih +OUTPUT +For the previous set of UBV observations the output file +\fIobservations\fR produced by MKNOBSFILE will look like the following. +The filter ids for the U,B,V filters are assumed to be 1,2,3. +Note that the exposure times are assumed to have been normalized either prior +to executing MKNOBSFILE or by using the contents of the \fIobsparams\fR +file, and so are not included in \fIobservations\fR. + +.nf + # FIELD FILTER OTIME AIRMASS X Y MAG MERR + + STDFIELD1-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD1-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD1-3 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD1-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD1-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD1-3 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD2-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD2-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD2-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD2-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + ............................................................. + STDFIELD7 INDEF INDEF INDEF INDEF INDEF INDEF INDEF + * 2 . . . . . . + * 3 . . . . . . + ............................................................. + STDFIELD14 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD15-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STDFIELD15-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . +.fi + +The accompanying format description file has the following form. + +.nf +# Declare the observations file variables + +observations + +T1 3 # time of observation in filter 1 +X1 4 # airmass in filter 1 +x1 5 # x coordinate in filter 1 +y1 6 # y coordinate in filter 1 +m1 7 # instrumental magnitude in filter 1 +error(m1) 8 # magnitude error in filter 1 + +T2 10 # time of observation in filter 2 +X2 11 # airmass in filter 2 +x2 12 # x coordinate in filter 2 +y2 13 # y coordinate in filter 2 +m2 14 # instrumental magnitude in filter 2 +error(m2) 15 # magnitude error in filter 2 + +T3 17 # time of observation in filter 3 +X3 15 # airmass in filter 3 +x3 16 # x coordinate in filter 3 +y3 17 # y coordinate in filter 3 +m3 18 # instrumental magnitude in filter 3 +error(m3) 19 # magnitude error in filter 3 +.fi + +.ih +EXAMPLES + +1. Prepare an observations file, from a set of standard star observations +computed by the APPHOT PHOT +task, for input to FITPARAMS. There is one PHOT output file per standard star +per filter and each file contains only a single measurement. +Therefore position matching is not necessary. The magnitudes have been +been normalized to unit exposure time by PHOT, and the filter ids +and airmasses read from the image headers, and written to the PHOT database, +files are correct. + +.nf + ph> mkimsets *.mag.* "1,2,3" jun11.stdim + + ... interactively create the image set file + + ph> mknobsfile *.mag.* "1,2,3" jun11.stdim jun11.stobs tol=0.0 + + ... create the observations file + +.fi + +2. Prepare an observations file from a set of standard star observations +computed by the APPHOT PHOT +task, for input to FITPARAMS. The three PHOT files contain UBV measurements +respectively of several bright stars in one of the selected areas. +The stars in each image +were detected automatically with the APPHOT DAOFIND task so some measurements +of bright non-standard stars as well as standard stars are contained in the +PHOT output files. Position matching is therefore necessary but the x and +y shifts between frames are less than 5 pixels. + +.nf + ph> edit sa15.stdim + + ... since the imsets file will only have a single entry type + it in by hand, it will contain a single line and look + something like the following + + SA15 : obj215 obj216 obj217 + + ph> mknobsfile obj*.mag.* "1,2,3" sa15.stdim sa15.stdobs \ + tolerance=5.0 + + ... make the observations file + + ph> edit sa15.stdobs + + ... edit the observations file if necessary so that the names of + the standard stars correspond to those in the standard + star catalog +.fi + +3. Prepare an observations file from a set of standard star observations +computed by the APPHOT PHOT task, for input to FITPARAMS. +The single PHOT output file contains UBV +measurements of 18 standard stars in the M92 field. No position matching is +necessary, but the user forgot to define the exposure time keyword parameter +in PHOT, so the PHOT magnitudes are not normalized for exposure time. +The airmasses +and filter ids are correct. Since the images are still on disk the user +simply runs HSELECT in the images package to produce a list of the correct +exposure times and then runs MKNOBSFILE. + +.nf + ph> mkimsets M92.imh.mag.1 "1,2,3" jun11.stdim + + ... interactively create the image set file + + ph> hselect M92*.imh $I,exptime yes > exptimes + + ... create the obsparams file with the correct exposure times + + ph> mknobsfile M92.mag.1 "1,2,3" jun11.stdim jun11.stdobs\ + obscolumns="0 2 0 0" obsparams="exptimes" tolerance=0.0 + + ph> edit jun11.stdobs + + ... edit the observations file if necessary so that the names of + the standard stars correspond to those in the standard + star catalog +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +mkimsets,mkphotcors,mkobsfile +.endhelp diff --git a/noao/digiphot/photcal/doc/mkobsfile.hlp b/noao/digiphot/photcal/doc/mkobsfile.hlp new file mode 100644 index 00000000..114e789c --- /dev/null +++ b/noao/digiphot/photcal/doc/mkobsfile.hlp @@ -0,0 +1,519 @@ +.help mkobsfile Apr94 noao.digiphot.photcal +.ih +NAME +mkobsfile -- prepare a single observations file from a list of APPHOT/DAOPHOT +files containing observations of objects in a single field +.ih +USAGE +mkobsfile photfiles idfilters observations +.ih +PARAMETERS +.ls photfiles +The APPHOT or DAOPHOT output database(s) containing the +object magnitudes. In the case of MKOBSFILE these databases are +normally created by the DAOPHOT PEAK, NSTAR or ALLSTAR tasks, but may also +have been written by the APPHOT QPHOT and PHOT tasks or the DAOPHOT PHOT task. +.le +.ls idfilters +The list of filters separated by whitespace or +commas which define a complete observation. +.le +.ls observations +The output observations file suitable for input to FITPARAMS or +EVALFIT/INVERTFIT. +.le +.ls wrap = yes +Format the output observations file for easy reading ? If wrap = yes then +the observations for each filter are written on a separate line and the +* character in column 1 is interpreted as a continuation character. +Otherwise all the data for each object is written to a single line +where the maximum size of a line is the current value of SZ_LINE. +.le +.ls imsets = "STDIN" +The input/output image set file which lists the observations of each field, +assigns a name to each field, and tells MKOBSFILE which images belong to the +same observation of that field. +Only observations corresponding to the images listed in \fIimsets\fR +will be extracted from \fIphotfiles\fR. +If \fIimsets\fR is the +standard input "STDIN", MKOBSFILE prompts the user for the field name +and the associated list of images. +Otherwise the observations are assumed to be listed in +\fIimsets\fR, 1 observation per line with the field name in column 1, +a colon in column 2, +followed by, the names of the +images of that field belonging to that observation. +The format of \fIimsets\fR is described in detail below. +.le +.ls obsparams = "" +The name of an optional text file containing the filter ids, exposure times, +airmasses, and times of observation for each image whose values are +either not stored or incorrectly stored in \fIphotfiles\fR. +If \fIobsparams\fR is the standard input "STDIN", MKOBSFILE prompts the user +for the correct filter id, exposure time, airmass, and time of observation +for each image in each image set. +Otherwise the observing parameters for each image are assumed to be +listed in \fIobsparams\fR, 1 image per line, with the image +name in column 1 and the filter ids, exposure times, airmasses, +and times of observation in the columns defined by \fIobscolumns\fR. +The image names must match those in \fIimsets\fR. +Images which have no +entries in \fIobsparams\fR are assigned the values stored in \fIphotfiles\fR. +.le +.ls obscolumns = "2 3 4 5" +The list of numbers separated by commas or whitespace specifying which columns +in \fIobsparams\fR contain the correct filter ids, exposure times, +airmasses, and times ob observation respectively. +The number 0 may be used as a place holder in +the \fIobscolumns\fR 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. The default +value of \fIobscolumns\fR corresponds to the format of the default +\fIobsparams\fR file produced by MKIMSETS. +.le +.ls minmagerr = 0.001 +The error that will be assigned to a non-INDEF valued magnitude measurement +if the recorded error is less than \fIminmagerr\fR. +.le +.ls shifts = "STDIN" +The name of the text file specifying the x-y shifts to be added +to the x-y positions of all objects in an image before position matching (the +original x's and y's are retained in the output). +If \fIshifts\fR is the standard input "STDIN", MKOBSFILE prompts the +user for the correct x and y shift for each image in each image set. +Otherwise the shifts are assumed to be listed in \fIshifts\fR, +1 image per line, with +the name of the image in column 1, followed by the x and y shifts +in columns 2 and 3 respectively. Image names must match those in \fIimsets\fR. +Images for which no shift is supplied are assigned x and y shifts of zero. +.le +.ls apercors = "STDIN" +The name of the text file specifying the aperture corrections +to be added to the extracted magnitudes for each image before writing +the magnitudes to \fIobservations\fR. +If \fIapercors\fR is the standard input "STDIN", MKOBSFILE prompts the +user for the correct aperture correction for each image in each image set. +Otherwise the aperture corrections are assumed to be listed in \fIapercors\fR, +1 image per +line with the name of the image in column 1, followed by the aperture +correction in magnitudes in column 2. +The image names must match those in the \fIimsets\fR. Images for which +no aperture correction is supplied are assigned a default value of 0.0. +.le +.ls aperture = 1 +The aperture number +in \fIphotfiles\fR for which the magnitude is extracted, if the magnitudes +were measured through more than one aperture. +By default the magnitude through the first aperture is extracted. +.le +.ls tolerance = 5.0 +The tolerance in pixels for matching objects in the same observation, +but different images. MKOBSFILE extracts +the x and y coordinates of each object in each image of a given observation +from \fIphotfiles\fR, adds the shift for that image in +\fIshifts\fR to the extracted x-y coordinates, +and matches the objects to within \fItolerance\fR pixels. +Missing objects are assigned INDEF entries in \fIobservations\fR. +If \fItolerance\fR is less +than or equal to 0 no coordinate matching is done, and objects are +matched in order of occurrence with missing objects being assigned +INDEF values. +.le +.ls allfilters = no +Output only objects which are successfully matched in all the filters +specified by \fIidfilters\fR? +.le +.ls verify = no +Verify any data entered interactively by the user ? +.le +.ls verbose = yes +Print status, warning, and error messages ? +.le + +.ih +DESCRIPTION + +MKOBSFILE takes a list of APPHOT or DAOPHOT database files \fIphotfiles\fR, +each containing observations of one or more objects in one or more fields +and prepares an observation file \fIobservations\fR. +By default MKOBSFILE prompts the user for the 1) name of each observation +of each star field (\fIimsets\fR), 2) the names of the images belonging to +each observation of each starfield (\fIimsets\fR) , 3) shifts for each +image in each observation (\fIshifts\fR), and 4) aperture corrections for +each image in each observation (\fIapercors\fR). MKOBSFILE is optimized +for creating a single observations +file containing observations of many stars in a single star field. +MKOBSFILE IS THE +PREPROCESSOR OF CHOICE FOR PREPARING MULTI-OBJECT SINGLE FIELD OBSERVATIONS +OF A CROWDED STAR FIELD. + +MKOBSFILE performs +the following functions: 1) extracts the quantities +image name, x and y position, exposure time, filter id, +airmass, time of observation, magnitude and magnitude +error from \fIphotfiles\fR, +2) corrects erroneous or missing values of the filter id, exposure time, +airmass, and time of observation in \fIphotfiles\fR, 3) associates each +field with one or more sets of images of that field taken through +different filters, +4) matches individual objects within a given image set by order of occurrence +or x-y position +and, 5) assigns a unique name to each object in each field. + +The image set file \fIimsets\fR assigns a name to each field. +For fields containing only a single standard star this name should match +the name of the standard star in the standard star catalog. +For fields containing more than one star, MKOBSFILE constructs a unique +name for each object in the field by adding a sequence number to the field +name in \fIimsets\fR, which if the star is a standard star the user +must later edit. For example the fourth star in the field "M92" will +be assigned the name "M92-4" in \fIobservations\fR. If this star is a +standard star and its true name is "IX-10" in the standard star catalog, +then the user must change "M92-4" to "IX-10" in \fIobservations\fR. +\fIImsets\fR also tells MKOBSFILE which images in \fIphotfiles\fR are +images of the same region of the sky belonging to the same observation. +By default MKOBSFILE defines the image set file interactively +by prompting the user for input. +If the number of observations is small the user should leave \fIimsets\fR +set to "STDIN" and enter the image sets as prompted. If the number of +observations is large the user should consider using MKIMSETS and +MKNOBSFILE to create their observations file. +The format of \fIimsets\fR is described in detail below. + +Values of the filter ids , exposure times, airmasses, and times of +observation which are missing or incorrect in \fIphotfiles\fR, +can be corrected by reading the correct values from the columns +\fIobscolumns\fR in the file +\fIobsparams\fR. The format of \fIobsparams\fR is described in detail below. +If \fIobsparams\fR is the standard input "STDIN" then MKOBSFILE will +prompt the user for the filter ids, exposure times, airmasses, and times of +observation for each image in each image set. + +MKOBSFILE matches the objects in different images within the same observation +either +by order of occurrence if \fItolerance\fR is less than or equal to 0.0, +or by x-y position. Matching by position is done by identifying which objects +in each of the +images of a given field and observation set are within \fItolerance\fR +pixels of each other. The user may supply an optional file of x and y +shifts \fIshifts\fR to be added to the object positions prior to +matching. The format of \fIshifts\fR is described in detail below. +If the parameter \fIallfilters\fR is "yes", only objects which are matched +in all the filters \fIidfilters\fR are output. +If \fIshifts\fR is the standard input "STDIN" then MKOBSFILE will prompt +the user for the x and y shifts for each image in each image set. + +MKOBSFILE permits the user to supply +an optional file of aperture corrections \fIapercors\fR containing +the magnitude corrections to be added to the instrumental +magnitudes in \fIphotfiles\fR. +The format of \fIapercors\fR is described in detail below. +If \fIapercors\fR is the standard input "STDIN", then MKOBSFILE will +prompt the user for the aperture correction for each image in each +image set. + +Each new observations file created by MKNOBSFILE has an associated format +description file listing the column names and numbers in \fIobservations\fR, +of the fields extracted from \fIphotfiles\fR. This file, referenced by its +parent observations file name, can be used as input to the MKCONFIG task. +The actual name of the format description file on disk is constructed +by prepending the observations file name \fIobservations\fR with the string +"f" and appending the string ".dat". For example if a new observations +file called "m92long" is created by MKOBSFILE, a format description file +called "fm92long.dat" will also be created. Any pre-existing format +description file of that name, which does not have an associated observations +file, will be deleted. + +THE IMSETS FILE + +The \fIimsets\fR file lists the observations of +each field which are to be extracted from \fIphotfiles\fR, +assigns a name to each +field, and informs MKOBSFILE which images belong to the same +observation of that field. +Observations are listed in \fIimsets\fR, 1 observation +per line with the field name in column 1, a colon in column 2, +followed by the names of the +images of that field for that observation separated by whitespace. + +The field name is used to generate the object names in \fIobservations\fR. +If there is only a single measured object in a field, then the name of that +object in \fIobservations\fR will be the name of the field. If the single +object is a standard star, the user should edit \fIimsets\fR so that the +field name is the same as the name of the standard star in the standard star +catalog. If a stellar field contains more than one measured object, +MKOBSFILE generates names of the form "field-#" where "field" is the field +name and "#" is a sequence number. For example the fourth star in the +field "M92" is assigned the name "M92-4" in \fIobservations\fR. If the star +is a standard star, the user must edit the object names in \fIobservations\fR +to match those in the standard star catalog. + +Any number of observations may have the same field name. This normally +occurs, for example, when multiple observations of s single standard +star or standard star field are made at several airmasses. + +If there +are no filter ids in \fIphotfiles\fR or \fIobsparams\fR then the images in +each image set are assigned the filter ids in \fIidfilters\fR in order +of occurrence, or user input if \fIimsets\fR is "STDIN". + +The \fIimsets\fR file for a set of 9 UBV frames of the globular cluster +M92 is listed below. The U, B and V +images for a set of long, medium and short exposure image sets of M92 are +listed in columns 2, 3 and 4 respectively. + +.nf + M92L : m92ul m92bl m92vl + M92M : m92um m92bm m92vm + M92S : m92us m92bs m92vs +.fi + +THE OBSPARAMS FILE + +The file \fIobsparams\fR lists the correct filter ids, exposure times, +airmasses, and times of observation for each image, +1 image per line, with the image name in column 1, and the remaining +quantities in the columns specified by \fIobscolumns\fR. +The images names must correspond to those in \fIimsets\fR. + +A sample corrections file \fIobsparams\fR for the previous set of +UBV M92 observations is shown below. +The filter ids, exposure times, airmasses, and times of observation +for all the images were correctly read into \fIphotfiles\fR +from the image headers with the exception of the filter id, exposure time, +airmass, and time of observation for the V frame of "M92M". +The correct filter id, exposure time, airmass, and time of observation +is supplied in \fIobsparams\fR with \fIobscolumns\fR set to "2 3 4 5" +as follows. + +.nf + m92vm 3 300 1.256 03:14:20.4 +.fi + +Zero can be used as a place holder in \fIobscolumns\fR as in the +following example where +the user wants to correct only the exposure time and the airmass but +leave the filter id and time of observation alone. In this +case \fIobscolumns\fR is set to "0 2 3 0" and \fIobsparams\fR looks as follows. + +.nf + m92vm 300 1.256 +.fi + +THE SHIFTS FILE + +The file \fIshifts\fR lists the shifts for each image, 1 shift per line, +with the image name in column 1 and the x and y shifts in columns 2 and +3 respectively. +The image names in \fIshifts\fR must match those in \fIimsets\fR. + +A sample shifts file for the previous set of UBV M92 +observations is listed below. The U observations are used as the position +reference and so are assigned x-y shifts of 0. +The long and middle exposure B and V frames have small but significant +shifts with +respect to the U frames and so are included in the shifts file. +The short exposure images are not significantly shifted with respect to +one another and so are not included in the shifts file. + +.nf + m92ul 0.0 0.0 + m92bl -5.2 -2.9 + m92vl -10.0 -5.6 + m92um 0.0 0.0 + m92bm 4.0 -1.1 + m92vm 6.3 -2.7 +.fi + +THE APERCORS FILE + +The file \fIapercors\fR lists the aperture corrections for each image, +1 aperture correction per line, +with the image name in column 1 and the aperture correction in magnitudes +in column 2 respectively. +The image names in \fIapercors\fR must match those in +\fIimsets\fR. + +A sample \fIapercors\fR file for the previous set of UBV observations is shown +below. + +.nf + m92ul -0.15 + m92bl -0.09 + m92vl -0.05 + m92um -0.14 + m92bm -0.10 + m92vm -0.06 + m92us -0.16 + m92bs -0.10 + m92vs -0.04 +.fi + +.ih +OUTPUT +The output observations file has the following format. Note that +the exposure times are assumed to have been normalized either prior +to executing MKOBSFILE or by using the contents of the \fIobsparams\fR +file, and so are not included in \fIobservations\fR. + +.nf + # FIELD FILTER OTIME AIRMASS X Y MAG MERR + + M92L-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + M92L-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + . + . + . + M92L-N 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + ....................................................... + M92M-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + M92M-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + . + . + . + M92M-N 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + ........................................................ + M92S-1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + M92S-2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + . + . + . + M92S-N 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + ........................................................ +.fi + +The accompanying format description file has the following +format. + +.nf +# Declare the observations file variables + +observations + +T1 3 # the time of observation in filter 1 +X1 4 # airmass in filter 1 +x1 5 # x coordinate in filter 1 +y1 6 # y coordinate in filter 1 +m1 7 # instrumental magnitude in filter 1 +error(m1) 8 # magnitude error in filter 1 + +T2 10 # the time of observation in filter 2 +X2 11 # airmass in filter 2 +x2 12 # x coordinate in filter 2 +y2 13 # y coordinate in filter 2 +m2 14 # instrumental magnitude in filter 2 +error(m2) 15 # magnitude error in filter 2 + +T3 17 # time of observation in filter 3 +X3 18 # airmass in filter 3 +x3 19 # x coordinate in filter 3 +y3 20 # y coordinate in filter 3 +m3 21 # instrumental magnitude in filter 3 +error(m3) 22 # magnitude error in filter 3 +.fi + +.ih +EXAMPLES + +1. Prepare an observations file from a set of observations of an open cluster +computed by the DAOPHOT ALLSTAR task. +There is one ALLSTAR output file per filter, with each file +containing observations of several hundred cluster stars. +Position matching is required. The magnitudes have already been normalized to +unit exposure time by the earlier PHOT step, and the filter ids and airmasses +read from the image headers and written to the ALLSTAR files are correct. + +.nf + ph> assemble the following information + + ... the name of the image associated with each allstar file + + ... the appropriate x-y shifts for each image + + ... the aperture corrections for each image + + ph> mkobsfile ocl*.als.* "1,2,3" ocl.obs tol=4.0 + + ... for each complete observation mkobsfile prompts for the + field name and the associated image names (in this case + 3 since there are 3 filters in idfilters) taken through + each filter + ... the end-of-file character <EOF> typed in response to the + query for the next image set name terminates image set + set entry + + ... next mkobsfile prompts for an x and y shift for each + image in each image set + ... the end-of-file character <EOF> typed in response to the + query for the next image x-y shift terminates image shift + entry + + ... next mkobsfile prompts for an aperture correction for each + image in each image set + ... the end-of-file character <EOF> typed in response to the + query for the next image aperture correction terminates + aperture correction entry +.fi + +2. Prepare an observations file from a set of globular cluster standard star +observations computed with the DAOPHOT PHOT task. The three PHOT output +files contain UBV measurements for the all the standard stars +in the globular cluster field plus a few extraneous objects. +Position matching is required, but since the filter to filter shifts are +small no x-y offsets are required for position matching. +Since these objects are standard stars, aperture corrections are not +required. The user forgot to define the filter id, exposure time, +airmass, and time of observation image header keyword parameters +inside DAOPHOT, so the magnitudes are not normalized for exposure time, +and the airmasses, filter ids, and times of observation are incorrect. + +.nf + ph> assemble the following information + + ... the name of the image associated with each phot file + + ... the filter id, exposure time, and airmass of each image + + ph> mkobsfile gcl*.mag.* "1,2,3" gcl.obs obsparams="STDIN"\ + obcolumns="2 3 4 5" shifts="" apercors="" tolerance=5.0 + + ... mkobsfile prompts the user for a field name and an image + name corresponding to each filter as above + ... the end-of-file character <EOF> typed in response to the + query for the next image set name terminates image set + set entry + + ... mkobsfile prompts the user for the correct filter id, + exposure time, airmass, and time of observation for each + image in each image set + ... the end-of-file character <EOF> typed in response to the + query for the next set of corrections terminates image + corrections entry +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +mkimsets,mkphotcors,mknobsfile +.endhelp diff --git a/noao/digiphot/photcal/doc/mkphotcors.hlp b/noao/digiphot/photcal/doc/mkphotcors.hlp new file mode 100644 index 00000000..1ee3506a --- /dev/null +++ b/noao/digiphot/photcal/doc/mkphotcors.hlp @@ -0,0 +1,274 @@ +.help mkphotcors Apr94 noao.digiphot.photcal +.ih +NAME +mkphotcors -- type in and/or check the observing parameters, shifts +or aperture corrections files for a given image set file. +.ih +USAGE +mkphotcors imsets idfilters obsparams shifts apercors +.ih +PARAMETERS +.ls imsets +The name of the input/output text file of observations, where a complete +observation consists of an observation name usually the name of +the observed star field, +followed by a list of images of that star field taken through the filters +\fIidfilters\fR. +If \fIimsets\fR does not exist, MKPHOTCORS prompts the user for +input and writes the results to a new image set file \fIimsets\fR. +If \fIimsets\fR does exist, MKPHOTCORS reads the file and prints messages +about any errors or inconsistencies it finds in it. If \fIimsets\fR is "", +MKPHOTCORS prompts the user for input, but does not create a new \fIimsets\fR +file. +.le +.ls idfilters +The list of filters separated by whitespace or commas which define a complete +observation. If \fIimsets\fR is entered interactively by the user, +\fIidfilters\fR defines the number of images in an +observation. If \fIimsets\fR is an existing file, MKPHOTCORS uses +the number of filters specified by \fIidfilters\fR to +check that there are the correct number of images in each observation. +.le +.ls obsparams +The name of the input/output text file containing the quantities filter id, +exposure time, airmass, and time of observation, for each image in \fIimsets\fR. +If \fIobsparams\fR does not exist, MKPHOTCORS prompts the user for input +and writes the results to the new observing parameters file \fIobsparams\fR. +If \fIobsparams\fR already exists, MKPHOTCORS reads the file using the format +specified by \fIobscolumns\fR, and prints out messages about any +errors and inconsistencies it finds. +If \fIobsparams\fR +is "", the user is not prompted for input and no output file is created. +.le +.ls shifts +The name of the input/output text file containing the x-y shifts to be applied +to the measured x-y coordinates of each object in each image in \fIimsets\fR. +If \fIshifts\fR does not exist, MKPHOTCORS prompts the user for input +and writes the results to the new shifts file \fIshifts\fR. +If \fIshifts\fR already exists, MKPHOTCORS reads the file and prints out +messages about any errors and inconsistencies it finds. +If \fIshifts\fR is "", the user is not prompted for input and no output +file is created. +.le +.ls apercors +The name of the input/output text file containing the aperture corrections +to be applied +to the measured magnitudes of each object in each image in \fIimsets\fR. +If \fIapercors\fR does not exist, MKPHOTCORS prompts the user for input +and writes the results to the new aperture corrections file \fIapercors\fR. +If \fIapercors\fR already exists, MKPHOTCORS reads the file and prints out +messages about any errors and inconsistencies it finds. +If \fIapercors\fR is "", the user is not prompted for input and no output +file is created. +.le +.ls obscolumns = "2 3 4 5" +The list of numbers separated by commas or whitespace specifying which +columns in \fIobsparams\fR contain the filter ids, exposure times, +airmasses, and times of observation, respectively of the images listed in column 1. +\fIObscolumns\fR is only used if \fIobsparams\fR already exists on disk. +The number 0 may be used as a place holder in the \fIobscolumns\fR string. +For example to read in only the airmass values, \fIobscolumns\fR should be +set to "0 0 column" if the airmass values are in column. +.le +.ls verify = no +Verify all data entered interactively ? +.le +.ls verbose = yes +Print messages about actions taken by MKPHOTCORS, and any warning or error +messages generated. +.le + +.ih +DESCRIPTION +MKPHOTCORS takes an image set file \fIimsets\fR and a list of filter ids +\fIidfilters\fR and writes one or more of the photometric corrections files +\fIobsparams\fR, \fIshifts\fR and \fIapercors\fR required by the +preprocessor tasks MKNOBSFILE and MKOBSFILE. MKPHOTCORS is intended as +a simple tool to assist the user in creating and/or checking the input +required by the MKNOBSFILE and MKOBSFILE tasks. + +\fIImsets\fR is the name of the input/output text file which tells +MKNOBSFILE or MKOBSFILE which +observations are to be extracted from the photometry files. +A complete observation consists of the observation name, +for example "M92", followed by a list of images +taken through the filters \fIidfilters\fR, for example "m92u m92b m92v". +Observations are listed in \fIimsets\fR, 1 observation per line, with the +observation name in column 1, a colon in column 2, followed by, in filter +order and separated by whitespace, the names of the images belonging +to that observation. A sample image set file is shown in the next section. + +\fIImsets\fR may be an existing file created with the MKIMSETS task, a file +typed in by hand by the user, or a new file to be created by MKPHOTCORS. +If \fIimsets\fR already exists, MKPHOTCORS reads the file and prints warning +messages if it cannot decode the observations specification, or if the +number of images in the observation does not match the number specified +by \fIidfilters\fR. If imsets does not exist, MKPHOTCORS prompts the user +for input using \fIidfilters\fR to determine the number of images +there should be in each observation, and writes the results to the new +image set file \fIimsets\fR. If \fIimsets\fR is "", MKPHOTCORS prompts +the user for input but does not save the results. + +\fIObsparams\fR is the name of the input/output text file listing the +observing parameters filter id, exposure time, airmass, and time of observation, +for the images in +\fIimsets\fR. \fIObsparams\fR is used to correct missing or incorrect +filter ids, exposure times, airmasses, and times of observation in the photometry files, and +is not required if all these values are correctly recorded in the photometry +files. 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 observation in the columns \fIobscolumns\fR. +A sample observing parameters file is shown in the next section. + +\fIObsparams\fR may be an existing file created with the MKIMSETS task, +a file typed in by hand by the user, or a new file to be created by +MKPHOTCORS. If \fIobsparams\fR already exists, MKPHOTCORS reads the file +and prints warning messages if it cannot decode the observing parameters, +or if the there is an entry which does not correspond to one of the images +listed in \fIimsets\fR. If \fIobsparams\fR does not exist, MKPHOTCORS +prompts the user for input for each image in \fIimsets\fR and +writes the results to a new observing parameters file \fIobsparams\fR. +If \fIobsparams\fR is "", MKPHOTCORS does not prompt for input and no new +file is written. + +\fIShifts\fR is the name of the text file specifying the x-y shifts, as +a function of image, to be +added to the x-y positions of all objects in the images listed in \fIimsets\fR. +These shifts are +used to brings frames of the same star field taken through different +filters into rough alignment before matching individual objects. +\fIShifts\fR is not required if the frame to frame shifts are +small, as is usually the case if the filters are of comparable thickness, +and the exposures are short or well-guided. The x-y shifts are listed 1 +per line with the name of the image in column 1, and the x and y shifts in +columns 2 and 3 respectively. +A sample shifts file is shown in the next section. + +\fIShifts\fR may be an existing file created with the IMCENTROID task and +edited by the user, +a file typed in by hand by the user, or a new file to be created by +MKPHOTCORS. If \fIshifts\fR already exists, MKPHOTCORS reads the file +and prints warning messages if it cannot decode the shifts, +or if the there is an entry which does not correspond to one of the images +listed in \fIimsets\fR. If \fIshifts\fR does not exist, MKPHOTCORS +prompts the user for input for each of the images in \fIimsets\fR and +writes the results to a new shifts file \fIshifts\fR. +If \fIshifts\fR is "", MKPHOTCORS does not prompt for input and no new +file is written. + +\fIApercors\fR is the name of the text file specifying the aperture +corrections, as a function of image, to be added to the magnitudes of all +objects in the images listed in \fIimsets\fR. +The aperture corrections are most often used to correct the instrumental +magnitudes of stars +measured through a small aperture to minimize crowding affects, to the +instrumental magnitudes of standard stars measured through a larger +aperture. These aperture corrections will normally be a function of filter +and of seeing and focus which can change throughout the night. +Aperture corrections are normally not required for standard star measurements. +Aperture corrections are listed 1 per line with +the name of the image in column 1, and the aperture correction in column 2. +A sample aperture corrections file is shown in the next section. + +\fIApercors\fR may be an existing file +typed in by hand by the user, or a new file to be created by +MKPHOTCORS. If \fIapercors\fR already exists, MKPHOTCORS reads the file +and prints warning messages if it cannot decode the aperture corrections, +or if the there is an entry which does not correspond to one of the images +listed in \fIimsets\fR. If \fIapercors\fR does not exist, MKPHOTCORS +prompts the user for input for each of the images in \fIimsets\fR and +writes the results to a aperture corrections file \fIapercors\fR. +If \fIapercors\fR is "", MKPHOTCORS does not prompt for input and no new +file is written. + +.ih +OUTPUT + +A sample image set file for a set of UBV 100 second, 600 seconds, and +1800 second exposure images of the globular cluster m92 is shown below. +The labels "M92S", "M92M", and "M92L" stand for the 100, 600, 1800 second +exposure observations sets respectively. The names which follow the labels are +the names of the actual IRAF images comprising each data set. The image names +must match those in the photometry files. + +.nf + M92S : m92us m92bs m92vs + M92M : m92um m92bm m92vm + M92L : m92ul m92bl m92vl +.fi + +A sample observing parameters file is shown for the above data set. In this +example the user forgot to tell the photometry code to pick up the filter ids, +exposure times, airmasses, and times of observation from the image headers and +so is obliged to +correct them after the fact via the observing parameters file. The filters +U B V are represented by the numbers 1 2 3. + +.nf + m92us 1 100 1.10 03:10:53 + m92bs 2 100 1.09 03:14:06 + m92vs 3 100 1.06 03:18:54 + m92um 1 600 1.03 04:15:05 + m92bm 2 600 1.03 04:29:43 + m92vm 3 600 1.03 04:44:56 + m92ul 1 1800 1.06 06:10:33 + m92bl 2 1800 1.12 06:45:32 + m92vl 3 1800 1.18 07:23:02 +.fi + +A sample shifts file for the above data set is shown below. +Only the long exposure frames have significant frame to frame shifts +so only those images are included in the shifts file. +The long u frame is used a position reference so its x-y shift is zero. + +.nf + m92ul 0.0 0.0 + m92bl 5.4 8.4 + m92vl 9.6 17.1 +.fi + +A sample aperture corrections file for the above data set is shown below. +Note that the aperture correction appears to vary in a systematic +way with filter. + +.nf + m92us -.153 + m92bs -.110 + m92vs -.083 + m92um -.149 + m92bm -.108 + m92vm -.090 + m92ul -.160 + m92bl -.123 + m92vl -.079 +.fi + +.ih +EXAMPLES + +1. Type in the image set file and accompanying shifts and aperture corrections +files for a set of UBV observations of a crowded field in NGC4147. The filter +ids "1 2 3" stand +for "U B V". The photometry programs picked up the correct values of +the filter id, exposure time, and airmass from the image headers +and wrote them to the photometry +files so the observing parameters file is not required. + +.nf + ph> mkphotcors n4147.imsets "1,2,3" "" n4147.shifts n4147.apcors +.fi + +2. Type in the shifts and aperture corrections files for the already +existing image set file m17.imsets. In this case the filter set is "J H K". + +.nf + ph> mkphotcors m17.imsets "J,H,K" "" m17.shifts m17.apcors +.fi +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +mkimsets,mknobsfile,mkobsfile +.endhelp diff --git a/noao/digiphot/photcal/doc/obsfile.hlp b/noao/digiphot/photcal/doc/obsfile.hlp new file mode 100644 index 00000000..a0e5b480 --- /dev/null +++ b/noao/digiphot/photcal/doc/obsfile.hlp @@ -0,0 +1,511 @@ +.help obsfile Apr94 noao.digiphot.photcal +.ih +NAME +obsfile -- prepare an observations file from a list of user created +photometry files containing observations of objects in one or more fields +.ih +USAGE +obsfile photfiles incolumns idfilters imsets observations +.ih +PARAMETERS +.ls photfiles +A list of text files containing the image names or an image id, x-y positions, +magnitudes, magnitude errors, airmasses, filter ids, exposure times, and time +of observation of all the measured objects. \fIPhotfiles\fR are assumed to be +the output of the user's own digital photometry program. All the files in the +list 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 fields: the image name or id, +x coordinate, y coordinate, filter id, exposure time, airmass, time of +observation, instrumental magnitude, magnitude error, and object id +respectively. +.le +.ls idfilters +The list of filter ids separated by whitespace or commas which define a +complete observation. The filter ids must correspond to those in +\fIphotfiles\fR. +.le +.ls imsets +The name of the text file which lists the observations of each field, assigns a +name to each field, and tells OBSFILE which images belong to the same +observation of that field. Only observations corresponding to the images +specified in \fIimsets\fR will be extracted from \fIphotfiles\fR. Observations +are listed in \fIimsets\fR, 1 observation per line with the field name in +column 1, a colon in column 2, followed by, in filter order and separated by +whitespace, the names of the images of that field belonging to that +observation. The format of \fIimsets\fR is described in detail below. +.le +.ls observations +The output observations file suitable for input to FITPARAMS or +EVALFIT/INVERTFIT. +.le +.ls wrap = yes +Format the output observations file for easy reading ? If wrap = yes then the +observation in each filter are written on a separate line and the * character +in column 1 is interpreted as a continuation character. Otherwise all the +observations for a single filter are written on a single line where the maximum +length of a line is SZ_LINE characters. +.le +.ls obsparams = "" +The name of an optional text file containing the correct filter ids, exposure +times, airmasses, and time of observations for each image whose values are +either undefined or incorrectly stored in \fIphotfiles\fR. The observing +parameters for each image are listed in the file \fIobsparams\fR, 1 image per +line with the image name in column 1 and the filter ids, exposure times, +airmasses, and times of observation listed in columns \fIobscolumns\fR. The +image names must match those in \fIimsets\fR. Images which have no entries in +\fIobsparams\fR are assigned the values stored 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 \fIobscolumns\fR 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. The default value of +\fIobscolumns\fR corresponds to the format of the default \fIobsparams\fR file +produced by MKIMSETS. +.le +.ls minmagerr = 0.001 +The error that will be assigned to a non-INDEF valued magnitude measurement +whose recorded error is less than \fIminmagerr\fR. +.le +.ls shifts = "" +The name of the text file specifying the x and y shifts to be ADDED to the x-y +positions of all objects in an image before position matching (the original x's +and y's are retained in the output). Shifts are listed for each image, 1 image +per line with the name of the image in column 1, followed by the x and y shifts +in columns 2 and 3 respectively. Image names must match those in \fIimsets\fR. +Images for which no shift is supplied are assigned x and y shifts of zero. +.le +.ls apercors = "" +The name of the text file specifying the aperture corrections to be ADDED to +the extracted magnitudes. Aperture corrections are listed for each image, 1 +image per line with the name of the image in column 1, followed by the aperture +correction in magnitudes in column 2. The image names must match those in +\fIimsets\fR. Images for which no aperture correction is supplied are assigned +a default value of zero. +.le +.ls normtime = no +Normalize the magnitudes to an exposure time of one time unit using the +exposure times in \fIphotfiles\fR. +.le +.ls tolerance = 5.0 +The tolerance in pixels for matching objects in the same observation, but +different images. OBSFILE extracts the x and y coordinates of each object +in each image of a given observation from \fIphotfiles\fR, adds the shift for +that image in \fIshifts\fR to the extracted x-y coordinates, and matches the +objects to within \fItolerance\fR pixels. Missing objects are assigned INDEF +entries in \fIobservations\fR. If \fItolerance\fR is less than or equal to 0 +no coordinate matching is done, and objects are matched in order of occurrence +with missing objects being assigned INDEF values. +.le +.ls allfilters = no +Output only objects which are successfully matched in all the filters specified +by \fIidfilters\fR? +.le +.ls verify = no +Verify interactive user input? This option is used only if any of \fIimsets\fR, +\fIobsparams\fR, \fIshifts\fR, or \fI apercors\fR are set to the standard input +"STDIN". +.le +.ls verbose = yes +Print messages about actions taken by the task or any warnings or errors +encountered? +.le + +.ih +DESCRIPTION + +OBSFILE takes a list of user generated text files \fIphotfiles\fR, where each +file contains observations of one or more objects taken through one or more +filters, and the image set file \fIimsets\fR, and prepares a single +observations file \fIobservations\fR. OBSFILE is intended for use with any +user digital stellar photometry program which writes its output in simple text +files format. + +OBSFILE performs the following functions: 1) extracts the quantities +image name or image id, x and y position, filter id, exposure time, airmass, +time of observation, magnitude, and magnitude error from +\fIphotfiles\fR, 2) corrects any erroneous or missing values of filter id, +exposure time, airmass, or time of observation in \fIphotfiles\fR, 3) associates each +field with one or more sets of images of that +field taken through different filters 4) matches individual objects within +a given observation by order of occurrence or x-y position, and +5) assigns a unique name to each object in each field. + +The parameter \fIincolumns\fR describes the format of \fIphotfiles\fR. +\fIIncolumns\fR is a list of ten numbers separated by commas or whitespace +which specify the columns containing the following fields: the +image name or id, +the x coordinate, the y coordinate, the filter id, the exposure time, +the airmass, the time of observation the instrumental magnitude, the +magnitude error, and the object id. +For example +if \fIincolumns\fR is "10 2 3 6 8 7 9 4 5 1", the object id is assumed to +be in column 1, the image id in column 10, the x and y positions in columns 2 and 3, the filter id, +exposure time, airmass, and time of observation in columns 6, 8, 7 and 9, +and the instrumental +magnitude and magnitude error in columns 4 and 5. The image names must +match those in \fIimsets\fR or the corresponding input data is skipped. +The columns image name, x coordinate, y coordinate, and magnitude +are mandatory and must be present in \fIphotfiles\fR. +Other missing columns in the data may be represented by a "0" in the +appropriate place in \fIincolumns\fR. +For example, if there is no magnitude error +column in \fIphotfiles\fR a value of INDEF will be written in the appropriate +column in \fIobservations\fR. +If there is no airmass column in \fIphotfiles\fR the value in +\fIobspararms\fR if any, or the value INDEF will be written to the appropriate +column in \fIobservations\fR. +If there is no filter id column in \fIphotfiles\fR the value in +\fIobspararms\fR if any, or one of the values in \fIidfilters\fR +will be written to the appropriate column in \fIobservations\fR. +If there is no exposure time column in \fIphotfiles\fR the value in +\fIobspararms\fR if any, or a value of one will be assumed. +If there is no time of observation time column in \fIphotfiles\fR the value in +\fIobspararms\fR if any, or a value of INDEF will be assumed. + +The image set file \fIimsets\fR assigns a name to each field. +For fields containing only a single standard star this name should +match the name of the standard star in the standard star catalog. +For fields containing more than one star, OBSFILE constructs a unique +name for each object in the field by adding a sequence number to the +field name in \fIimsets\fR, which if the star is a standard star, the +user must later edit. For example the fourth star in the field "M92" +will be assigned the name "M92-4" in \fIobservations\fR. +If this star is a standard star and its true name is "IX-10" in the +standard star catalog, then the user must change "M92-4" to "IX-10" +in \fIobservations\fR. +\fIImsets\fR also tells OBSFILE which images +in \fIphotfiles\fR are images of the same region of the sky belonging +to the same observation. +The format of \fIimsets\fR is described in detail below. +If the number of observations is small the user may wish to simply type +in \fIimsets\fR by hand. If the number of observations is large, a +separate task MKIMSETS is available to assist users in preparing +\fIimsets\fR. + +Values of the filter ids, exposure times, airmasses, and times of observation, +which are undefined or incorrect in \fIphotfiles\fR, +can be corrected by reading values listed in the columns \fIobscolumns\fR +in the file \fIobsparams\fR. The format of \fIobsparams\fR is described +in detail below. + +OBSFILE matches the objects in different images within the same observation +either +by order of occurrence if \fItolerance\fR is less than or equal to 0.0, +or by x-y position. Matching by position is done by identifying which objects +in each of the +images of a given field and observation set are within \fItolerance\fR +pixels of each other. The user may supply an optional file of x and y +shifts \fIshifts\fR to be added to the object positions prior to +matching. The format of \fIshifts\fR is described in detail below. +If the parameter \fIallfilters\fR is "yes", only objects which are matched +in all the filters \fIidfilters\fR are output to \fIobservations\fR. + +OBSFILE permits the user to supply +an optional file of aperture corrections \fIapercors\fR containing +magnitude corrections which are added to the instrumental +magnitudes in \fIphotfiles\fR. +The format of \fIapercors\fR is described in detail below. + +Each new observations file created by OBSFILE has an associated format +description file listing the column names and numbers in \fIobservations\fR, +of the fields extracted from \fIphotfiles\fR. This file, referenced +by its parent observations file name, can be used as input to the +MKCONFIG task. The actual name of the format description file on disk is +constructed by prepending the string "f" and appending the string ".dat" +to \fIobservations\fR. +For example if a new observations file called "nite1" is created by +OBSFILE, a format description file called "fnite1.dat" will also be +created. Any pre-existing format description file of that name, which does +not have an associated observations file, will be deleted. + + +THE IMSETS FILE + +The \fIimsets\fR file lists the +the observations of each field, assigns a name to each +field, and informs OBSFILE which images belong to the same +observation of that field. +Observations are listed in \fIimsets\fR, 1 observation +per line with the field name in column 1, a colon in column 2, +followed by the names of the +images of that field for that observation separated by whitespace. +Only data for image names in \fIimsets\fR which match those in +\fIphotfiles\fR will be extracted. + +The field name is used to generate the output object name in \fIobservations\fR. +If there is only a single measured object in the field, then the name +of that object in \fIobservations\fR will be the name of the field. If +the single object is a standard star, the user should edit \fIimsets\fR +so that the field name is the same as the name of the standard star in +the standard star catalog. If a stellar field contains more than one +measured object, OBSFILE generates names of the form "field-#" where +"field" is the field name and "#" is a sequence number. For example the +fourth star in the field "M92" will be assigned the name "M92-4" in +\fIobservations\fR. If the star is a standard star, the user must edit +the object names in \fIobservations\fR to match those in the standard +star catalog. + +Any number of observations may have the same field name. This normally occurs, +for example, when multiple observations of a single standard star of +standard star field are made at several airmasses. + +If there +are no filter ids in \fIphotfiles\fR or \fIobsparams\fR then the images in +each image set are assigned the filter ids in \fIidfilters\fR in order +of occurrence. + +The \fIimsets\fR file for a set of 50 UBV frames of fifteen standard star +fields is listed below. There is only a single bright star per field. +The name of star field in column 1 has been edited to be identical +to the name of the standard in the standard star catalog. Column 2 contains +a ':'. The U, B and V +images for each field are listed in columns 3, 4 and 5 respectively. +The missing U image for field "STD7" is represented by the name "INDEF". +Standard stars "STD1" and "STD2" were observed twice in the same night +at different airmasses. + +.nf + STD1 : nite001 nite002 nite003 + STD1 : nite045 nite046 nite047 + STD2 : nite004 nite005 nite006 + STD2 : nite048 nite049 nite050 + ... + STD7 : INDEF nite019 nite020 + ... + STD14 : nite039 nite040 nite041 + STD15 : nite042 nite043 nite044 +.fi + +THE OBSPARAMS FILE + +A sample corrections file \fIobsparams\fR for the previous set of +UBV standards observations is shown below. +The filter ids, exposure times, airmasses, and times of observation for all the images were +correctly read +from the image headers with the exception of the filter id, exposure time, +and airmass for the first "STD2" V frame. +The correct filter id, exposure time, airmass, and time of observation, is supplied +in \fIobsparams\fR and \fIobscolumns\fR is set to "2 3 4 5" + +.nf + nite006 3 8 1.256 14:30:02.3 +.fi + +Zero can be used as a place holder in \fIobscolumns\fR, +as in the following example where +the user only wants to correct the exposure time and the airmass and +leave the filter id alone. In this case \fIobscolumns\fR is "0 2 3 0" +and \fIobsparams\fR looks as follows. + +.nf + nite006 8 1.256 +.fi + +Only images listed in \fIimsets\fR can have their observing parameters +modified by \fIobsparams\fR. + +THE SHIFTS FILE + +The file \fIshifts\fR lists the shifts for each image, 1 shift per line, +with the image name in column 1 and the x and y shifts in columns 2 and +3 respectively. +The image names in \fIshifts\fR must match those in \fIimsets\fR. + +A sample shifts file for the previous set of UBV standards +observations is shown below. All the standards except for "STD14" are assumed +to have no significant shifts from filter to filter. The B and V frames +for "STD14" are shifted -10 pixels in x and -5 pixels +in y with respect to the U frame. Therefore +10 and +5 pixels should be +added to the "STD14" B and V frame positions respectively before +position matching. + +.nf + nite040 10.0 5.0 + nite041 10.0 5.0 +.fi + +An alternate way of listing the same observations would be the following. + +.nf + nite039 -10.0 -5.0 +.fi + +THE APERCORS FILE + +The file \fIapercors\fR lists the aperture corrections for each image, +1 aperture correction per line, +with the image name in column 1 and the aperture correction in magnitudes +in column 2 respectively. +The image names in \fIapercors\fR must match those in \fIimsets\fR. + +The \fIapercors\fR file for the previous set of UBV observations is shown +below. +The aperture corrections for all the standard stars are assumed to be +zero except for "STD14". + +.nf + nite039 -0.150 + nite040 -0.100 + nite041 -0.090 +.fi + +.ih +OUTPUT +For the previous set of UBV observations the output file +\fIobservations\fR produced by OBSFILE will look like the following. +The filter ids for the U,B,V filters are assumed to be 1,2,3. +Note that the exposure times are assumed to have been normalized either +prior to running OBSFILE or by OBSFILE itself, +and so are not included in \fIobservations\fR. + +.nf + # FIELD FILTER OTIME AIRMASS X Y MAG MERR + + STD1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STD1 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STD2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STD2 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + ........................................................ + STD7 INDEF INDEF INDEF INDEF INDEF INDEF INDEF + * 2 . . . . . . + * 3 . . . . . . + ....................................................... + STD14 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . + STD15 1 . . . . . . + * 2 . . . . . . + * 3 . . . . . . +.fi + +The accompanying format description file has the following form. + +.nf +# Declare the observations file variables + +observations + +X1 3 # airmass in filter 1 +T1 4 # time of observation in filter 1 +x1 5 # x coordinate in filter 1 +y1 6 # y coordinate in filter 1 +m1 7 # instrumental magnitude in filter 1 +error(m1) 8 # magnitude error in filter 1 + +X2 10 # airmass in filter 2 +T2 11 # time of observation in filter 2 +x2 12 # x coordinate in filter 2 +y2 13 # y coordinate in filter 2 +m2 14 # instrumental magnitude in filter 2 +error(m2) 15 # magnitude error in filter 2 + +X3 16 # airmass in filter 3 +T3 17 # time of observation in filter 3 +x3 18 # x coordinate in filter 3 +y3 19 # y coordinate in filter 3 +m3 20 # instrumental magnitude in filter 3 +error(m3) 21 # magnitude error in filter 3 +.fi + +.ih +EXAMPLES + +1. Prepare an observations file, from a set of standard star observations +in a file output by the user's own digital stellar photometry program, +for input to FITPARAMS. A sample of the file illustrating the format +is shown below. +Since there is only one star per field, position matching is not necessary. +The magnitudes have already been normalized to unit exposure time by the +user's program, and the filter ids and airmasses are correct. However the +observing time column is missing and represented by a zero in the incolumns +parameters. + +.nf + ph> head magsfile + + ... print out the first few lines of the photometry file + + std1u 40.4 50.3 18.059 0.043 U 1.030 1.0 + std1b 42.5 53.1 17.089 0.023 B 1.032 1.0 + std1v 43.8 56.9 16.023 0.020 V 1.034 1.0 + std2u 39.4 55.3 17.029 0.040 U 1.135 1.0 + std2b 41.5 57.3 15.905 0.020 B 1.140 1.0 + std2v 42.6 58.9 14.899 0.018 V 1.144 1.0 + ..... .... .... ...... ..... . ..... ... + ..... .... .... ...... ..... . ..... ... + + ph> type fields + + ... print out the corresponding image set file + + std1 : std1u std1b std1v + std2 : std2u std2b std2v + ..... ..... ..... ..... + ..... ..... ..... ..... + + ph> obsfile magsfile "1 2 3 6 8 7 0 4 5" "U,B,V" fields standards.obs\ + tol=0.0 + + ... create the observations file + + ph> edit standards.obs + + ... edit the observations file so that the object names + match those in the standard star catalog +.fi + +2. Prepare an observations file from a set of program star observations +of a crowded field in the globular cluster M92 computed by the same +digital photometry +program as above, for input to FITPARAMS. The 3 input files contain UBV +measurements of over 2000 stars in the M92 field. Since the same stars +were not measured in all filters position matching is necessary. + +.nf + ph> head m92umags,m92bmags,m92vmags + + ... print the first few lines of the input files on the + standard output + + m92u 80.4 42.3 17.046 0.046 U 1.056 1.0 + m92u .... .... ...... ..... U 1.056 1.0 + + m92b 62.6 81.1 18.071 0.041 B 1.030 1.0 + m92b .... .... ...... ..... B 1.030 1.0 + + m92v 33.8 26.9 16.023 0.022 V 1.034 1.0 + m92v .... .... ...... ..... V 1.034 1.0 + + ph> type fields + + ... print out the image set file + + m92 : m92u m92b m92v + + ph> obsfile m92umags,m92bmags,m92vmags "1 2 3 6 8 7 0 4 5" "U,B,V"\ + fields standards.obs tolerance=8.0 + +.fi + +.ih +TIME REQUIREMENTS +.ih +BUGS +.ih +SEE ALSO +mkimsets,mknobsfile,mkobsfile +.endhelp diff --git a/noao/digiphot/photcal/doc/pcintro.hlp b/noao/digiphot/photcal/doc/pcintro.hlp new file mode 100644 index 00000000..8a2287b1 --- /dev/null +++ b/noao/digiphot/photcal/doc/pcintro.hlp @@ -0,0 +1,727 @@ +.help pcintro Apr94 noao.digiphot.photcal +.ih +I. INTRODUCTION + +The photometric calibration package PHOTCAL, contains a set of tasks +for computing the transformation from the instrumental system to the standard +photometric system, and applying the computed transformations to +the observational data. + +PHOTCAL distinguishes between two types of objects: \fIstandard stars\fR, +and \fIprogram stars\fR. Standard stars have known instrumental and standard +photometric indices. Program stars have known instrumental photometric +indices, but unknown standard photometric indices. + +The standard indices of standard stars are contained in standard star +catalogs known as \fIcatalog files\fR. Each standard star catalog +contains only a single entry for a given standard star. The +instrumental indices of both standard and program stars are +contained in observations catalogs, known as \fIobservations files\fR. +There may be any number of observations per star in an observations +file. + +PHOTCAL uses a setup file called the \fIconfiguration file\fR to specify +the format of the input catalog and observations files and define the +transformation equations to be fit. + +Normally the user must perform the following logical steps to +complete their photometric calibrations with PHOTCAL. However not all types +of data require all the following steps. + +.ls [1] +Prepare a standard star catalog file using the MKCATALOG task. +.le +.ls [2] +Prepare a standard star observations file using the MKIMSETS and MKNOBSFILE +tasks or alternatively the MKOBSFILE task. +.le +.ls [3] +Create the configuration file using the MKCONFIG and CHKCONFIG tasks. +.le +.ls [4] +Fit the transformation equations with the FITPARAMS task. +.le +.ls [5] +Apply the transformations to the standard star observations file using +the EVALFIT or INVERTFIT tasks. +.le +.ls [6] +Prepare a program star observations file using the MKIMSETS and MKNOBSFILE +tasks or alternatively the MKOBSFILE tasks. +.le +.ls [7] +Apply the transformations to the program star observations file using the +EVALFIT or INVERTFIT tasks. +.le + +.ih +II. THE CATALOG AND OBSERVATIONS FILES FORMAT + +PHOTCAL catalog and observation files are simple text files containing any +number of columns. Columns are delimited by whitespace. +The first column is always reserved for the star id or +matching name, and the rest contain actual data such as positions, magnitudes, +colors, errors, air mass, or any other quantity of interest. +Comments can be inserted +as separate lines at any point in the catalog or observations files +by beginning the comment line with the character "#". + +The star id is used to +match observations with catalog entries, and to determine which objects +are standard and which are program stars. Star ids may contain any non-blank +characters, +but lower case letters are converted to upper case, and +characters not in the set [A-Z,0-9,+,-,_] are removed before +star id matching. Catalog files must contain only a single entry per star. +Observations files may contain multiple entries per star. +Missing or unknown data values should be set to INDEF not left blank. + +Normal catalog and observations files records are restricted in length to +the maximum size of a text +file line in IRAF, currently 161 characters including the newline. The maximum +record length can be extended by replacing the star id in column 1 +with the continuation character "*". + +Several preprocessors are provided to convert data coming from other +IRAF packages, such as APPHOT and DAOPHOT, into a format suitable for PHOTCAL. +If a preprocessor for a specific type of data does +not exist, then the user will have to use other IRAF facilities to convert it +to into the appropriate format, or write their own. + +.ih +III. PREPARE A STANDARD STAR CATALOG FILE + +A standard star catalog suitable for input to PHOTCAL may be prepared in +one of the following ways. The advantages and disadvantages of each +method are briefly discussed. + +.ls [1] +Use one of the standard star catalogs supported by PHOTCAL and maintained in +the directory "photcal$catalogs/". Each supported standard star catalog has +an associated catalog format description file defining the format of the +standard star catalog. The catalog format description file may be used as +input to the MKCONFIG task. A list of currently supported standard star +catalogs and their format files can be found in the file +"photcal$catalogs/README". + +The principal advantage of this option is that no data entry is +required on the part of the user. The principal disadvantage is that +PHOTCAL, in preparation for id matching, loads the entire standard +star catalog into memory, even though the number of observed +standard stars may have been only a few dozen. For typical standard +star catalogs containing a few hundred objects this is not a problem, +but very large standard star catalogs should be avoided. +.le +.ls [2] +Prepare a standard star catalog with the MKCATALOG task. MKCATALOG +prompts the user for the catalog title, the id column name and width, and the +names and widths of all the data columns. +When column definition is complete, MKCATALOG writes the catalog +definition information into the catalog header and the associated catalog +format file and prompts for data. +The catalog format description file created by MKCATALOG may be used +as input to MKCONFIG. +Type "help mkcatalog" for the details of task usage. + +The principal advantages of using MKCATALOG are that the task always +produces a PHOTCAL readable catalog and accompanying format description file, +and that the standard star catalog contains values only for those objects +that have actually been observed. +.le +.ls [3] +With a text file editor create or edit a standard star catalog which +conforms to the requirements of PHOTCAL as described in the previous section. + +The principal advantage of this option is that the user can take advantage +of any spread sheet capabilities that his/her favorite editor has. The +principal disadvantage is that a format description file is not +automatically created along with the catalog. +.le +.ls [4] +Reformat an existing standard star catalog until it conforms to the +requirements of photcal as described in the previous section. In some +case this may require writing a local preprocessor program. PHOTCAL users +should be aware of the PROTO package tasks JOIN and FIELDS, the LISTS +package tasks COLUMN, and the UTILITIES package task TRANSLIT. +.le + +The first few lines of a representative catalog file produced by MKCATALOG are +listed below. V, BV, and UB stand for the V magnitude, B-V color, +and U-B color respectively. The non-blank lines beginning with '#' at the +beginning of the file are for the internal use of the MKCATALOG task only, +and are ignored by other PHOTCAL tasks. + +.nf +# CATALOG: ubv.cat +# NCOLS: 7 +# HDRLENGTH: 68 +# +# ID V error(V) BV error(BV) UB error(UB) +# 8 8 8 8 8 8 8 + + 105-307 12.050 0.020 0.690 0.020 0.220 0.020 + 105-405 8.309 0.004 1.521 0.001 1.905 0.007 + 105-411 10.620 0.014 0.950 0.010 0.620 0.008 + 105-256 11.820 0.013 0.610 0.012 0.180 0.022 +.fi + +The accompanying format description file produced by MKCATALOG is listed below. +This file associates a column number with the column name and can be used +as input to MKCONFIG. The comments opposite +the column definitions were not produced by MKCATALOG but typed in later. + +.nf + +# Declare the catalog variables + +catalog + +V 2 # the V magnitude +error(V) 3 # the error in the V magnitude +BV 4 # the B-V color +error(BV) 5 # the error in the B-V color +UB 6 # the U-B color +error(UB) 7 # the error in the U-B color + +.fi + +.ih +IV. PREPARE A STANDARD STAR OBSERVATIONS FILE + +A standard star observations file suitable for input to PHOTCAL may be +prepared in one of the following ways. APPHOT and DAOPHOT users should +use options [1] or [2]. Other users must either enter their data by hand using +options [3] and [4], or write a local program to prepare their data +for input to PHOTCAL, option [5]. + +.ls [1] +If the standard star magnitudes were computed with APPHOT or DAOPHOT +and consist of many individual and repeated observations of standard star +fields, then use MKIMSETS +followed by MKNOBSFILE to create an observations file. MKIMSETS creates +an image set definition file, telling MKNOBSFILE which images taken +in which filters belong to the same observation of a given stellar field. +For each observations file written, MKNOBSFILE +creates an associated format description file defining the format of +the new observations file and suitable for input to +MKCONFIG. MKNOBSFILE is set up to run automatically once the image set file +is defined. Type "help mknobsfile" for details. +.le +.ls [2] +If the standard star magnitudes in one or more colors were computed with +APPHOT or DAOPHOT and all the standard stars are in one stellar field, +use the MKOBSFILE task to create an observations file. +For each observations file created, MKOBSFILE +creates an associated format description file defining the format of +the new observations file, and suitable for input to +MKCONFIG. MKOBSFILE prompts the user for all +the required input. Type "help mkobsfile" for details. +.le +.ls [3] +Prepare a standard star observations file with the MKCATALOG task. MKCATALOG +prompts the user for the observations file title, the id column name and +width, and the names and widths of all the data columns. +When column definition is complete, MKCATALOG writes the observations file +definition information into the observations file header and the associated +format description file and prompts for data. +The format description file created by MKCATALOG may be used as input +to MKCONFIG if the "catalog" keyword (see the example in the previous +section) is changed to "observations". +Type "help mkcatalog" for the details of task usage. +.le +.ls [4] +With the text editor create or edit a standard star observations file +which conforms to +the requirements of PHOTCAL as described in the previous section. +.le +.ls [5] +Write a local program to prepare the data for input to PHOTCAL. +.le + +A sample image set file produced by MKIMSETS is shown below. The labels +STD1, STD2, ..., STD7 stand for standard star fields 1, 2, ..., 7 and +the c0* labels are the names of images of each field taken through filters +U, B, and V respectively. + +.nf + STD1 : c023 c022 c021 + STD2 : c024 c025 c026 + STD3 : c029 c028 c027 + STD4 : c033 c031 c032 + STD5 : c061 c060 c059 + STD6 : c064 c063 c062 + STD7 : c069 c066 c065 +.fi + +The first few lines of the observations file produced by +MKNOBSFILE using the above image set file both before and after the user +has edited in the correct standard star ids is listed below. +Note that there is usually more than 1 star in the field. In fact the +data set above included 17 standard stars and 5 additional stars that +the automatic star finding algorithm picked up. +Note also that some known bad data points in the +original observations file have been replaced with the undefined value +INDEF. + +.nf + +before editing + +# FIELD FILTER OTIME AIRMASS XCENTER YCENTER MAG MERR + +STD1-1 1 INDEF 1.276 156.43 518.23 20.077 0.031 +* 2 INDEF 1.270 155.37 521.12 17.712 0.053 +* 3 INDEF 1.265 152.16 519.62 17.044 0.019 +STD1-2 1 INDEF 1.276 481.39 357.19 18.683 0.009 +* 2 INDEF 1.270 480.57 360.07 14.919 0.005 +* 3 INDEF 1.265 477.07 358.62 13.292 0.002 +STD1-3 1 INDEF 1.276 507.69 128.53 19.144 0.014 +* 2 INDEF 1.270 507.06 131.44 16.612 0.020 +* 3 INDEF 1.265 503.42 130.29 15.587 0.008 +STD2-1 1 INDEF 1.305 719.59 399.17 19.863 0.097 +* 2 INDEF 1.315 718.79 401.30 17.339 0.043 +* 3 INDEF 1.320 715.47 402.55 16.601 0.033 +STD2-2 1 INDEF 1.305 470.72 393.68 16.675 0.005 +* 2 INDEF 1.315 469.71 396.22 14.743 0.004 +* 3 INDEF 1.320 466.58 397.27 14.030 0.004 +STD2-3 1 INDEF 1.305 498.75 204.35 19.413 0.057 +* 2 INDEF 1.315 497.73 206.40 17.469 0.042 +* 3 INDEF 1.320 494.55 207.64 16.662 0.032 +STD2-4 1 INDEF 1.305 182.44 209.60 19.748 0.073 +* 2 INDEF 1.315 181.10 211.95 18.056 0.074 +* 3 INDEF 1.320 178.21 213.03 17.034 0.044 +STD3-1 1 INDEF 1.251 397.57 200.65 19.060 0.007 +* 2 INDEF 1.236 396.58 200.38 15.725 0.005 +* 3 INDEF 1.231 393.53 200.51 14.237 0.007 + +after editing + +# FIELD FILTER OTIME AIRMASS XCENTER YCENTER MAG MERR + +STD1-1 1 INDEF 1.276 156.43 518.23 20.077 0.031 +* 2 INDEF 1.270 155.37 521.12 17.712 0.053 +* 3 INDEF 1.265 152.16 519.62 17.044 0.019 +105-405 1 INDEF 1.276 481.39 357.19 18.683 0.009 +* 2 INDEF 1.270 480.57 360.07 14.919 0.005 +* 3 INDEF 1.265 477.07 358.62 13.212 0.002 +105-411 1 INDEF 1.276 507.69 128.53 19.144 0.014 +* 2 INDEF 1.270 507.06 131.44 16.612 0.020 +* 3 INDEF 1.265 503.42 130.29 15.487 0.008 +STD2-1 1 INDEF 1.305 719.59 399.17 19.863 0.097 +* 2 INDEF 1.315 718.79 401.30 17.339 0.043 +* 3 INDEF 1.320 715.47 402.55 16.601 0.033 +105-257 1 INDEF 1.305 470.72 393.68 16.675 0.005 +* 2 INDEF 1.315 469.71 396.22 14.743 0.004 +* 3 INDEF 1.320 466.58 397.27 14.030 0.004 +105-262 1 INDEF 1.305 498.75 204.35 INDEF 0.057 +* 2 INDEF 1.315 497.73 206.40 17.469 0.042 +* 3 INDEF 1.320 494.55 207.64 INDEF 0.032 +STD2-4 1 INDEF 1.305 182.44 209.60 19.748 0.073 +* 2 INDEF 1.315 181.10 211.95 18.056 0.074 +* 3 INDEF 1.320 178.21 213.03 17.034 0.044 +106-575 1 INDEF 1.251 397.57 200.65 19.060 0.007 +* 2 INDEF 1.236 396.58 200.38 15.725 0.005 +* 3 INDEF 1.231 393.53 200.51 14.237 0.007 +.fi + +The accompanying format description file produced by MKNOBSFILE +is listed below. This file associated column numbers with column +names. The filter numbers 1, 2, 3 were written into the image +headers by the data taking program, and subsequently picked up by the +APPHOT package tasks computed the magnitudes. They stand for filters U, B and +V respectively. + +.nf +# Declare the observations file variables + +observations + +T1 3 # time of observation in filter 1 +X1 4 # airmass in filter 1 +x1 5 # x coordinate in filter 1 +y1 6 # y coordinate in filter 1 +m1 7 # instrumental magnitude in filter 1 +error(m1) 8 # magnitude error in filter 1 + +T2 10 # time of observation in filter 2 +X2 11 # airmass in filter 2 +x2 12 # x coordinate in filter 2 +y2 13 # y coordinate in filter 2 +m2 14 # instrumental magnitude in filter 2 +error(m2) 15 # magnitude error in filter 2 + +T3 17 # time of observation in filter 3 +X3 18 # airmass in filter 3 +x3 19 # x coordinate in filter 3 +y3 20 # y coordinate in filter 3 +m3 21 # instrumental magnitude in filter 3 +error(m3) 22 # magnitude error in filter 3 +.fi + +.ih +V. PREPARE THE CONFIGURATION FILE + +The configuration file is a text file, created by the user, that specifies +both the format of the input data and the form of the transformation equations. +A detailed description of the grammar and syntax of the configuration file +can be obtained by typing the following command. +.nf + +ph> help config + +.fi +The configuration file can be prepared in one of the following ways. + +.ls [1] +Run the MKCONFIG task using the output of MKCATALOG or direct terminal input to +define the catalog file format, the output of the MKNOBSFILE +or MKOBSFILE tasks or direct terminal input to define the observations file +format, and one of the standard template transformation section files or +direct terminal input to define the transformation equations. +Users are urged to use MKCONFIG if they are new to PHOTCAL, +if the catalog file is one of the supported catalogs, or if the observations +file was made with one of the standard preprocessors MKNOBSFILE or +MKOBSFILE. +.le +.ls [2] +Use the text editor to make small corrections to an existing functioning +configuration file. This is the recommended method if the transformation +equations have changed from a previous PHOTCAL reduction session but the +format of the standard star and observations catalogs has not, or if +the user has become familiar with the PHOTCAL configuration file format. +.le +.ls [3] +Use the text editor to create a configuration file from scratch. +.le + +The grammar and syntax of the configuration file can be checked with the +CHKCONFIG task. If an error was found, the program will print the +line and the word where the error was detected and the user must reedit the +file until no errors are found. + +A sample configuration file is shown below. + +.nf + +# Declare the catalog file variables + +catalog + +V 2 +error(V) 3 +BV 4 +error(BV) 5 +UB 6 +error(UB) 7 + +# Declare the observations file variables + +observations + +T1 3 # time of observation in filter 1 +X1 4 # airmass in filter 1 +x1 5 # x coordinate in filter 1 +y1 6 # y coordinate in filter 1 +m1 7 # instrumental magnitude in filter 1 +error(m1) 8 # magnitude error in filter 1 + +T2 10 # time of observation in filter 2 +X2 11 # airmass in filter 2 +x2 12 # x coordinate in filter 2 +y2 13 # y coordinate in filter 2 +m2 14 # instrumental magnitude in filter 2 +error(m2) 15 # magnitude error in filter 2 + +T3 17 # time of observation in filter 3 +X3 18 # airmass in filter 3 +x3 19 # x coordinate in filter 3 +y3 20 # y coordinate in filter 3 +m3 21 # instrumental magnitude in filter 3 +error(m3) 22 # magnitude error in filter 3 + + +transformation + +fit u1 = 0.0, u2 = -.07, u3 = 0.70 +UFIT : m1 = V + BV + UB + u1 + u2 * UB + u3 * X1 + +fit b1 = 0.0, b2 = -.06, b3 = 0.30 +BFIT : m2 = V + BV + b1 + b2 * BV + b3 * X2 + +fit v1 = 0.0, v2 = 0.05, v3 = 0.20 +VFIT : mv = V + v1 + v2 * BV + v3 * Xv +.fi + +.ih +VI. FITTING THE PARAMETERS OF THE TRANSFORMATION EQUATIONS + +The heart of the PHOTCAL package is the parameter fitting task FITPARAMS. +A detailed description of this task and its parameters can be obtained by +typing the following command. +.nf + +ph> help fitparams + +.fi +FITPARAMS takes the observation files, catalog files, and configuration file, +and computes the value of the fit parameters for each of the +transformation equations specified in the configuration file. Equations will +be processed in the same order in which they occur in the configuration file. +The output of FITPARAMS is a text database file containing one record, +identified by the transformation equation label, for each equation fit. +Successive fits are appended to the end of the database file. If more than +one fit has the same label the last fit performed will be used by the +evaluation tasks. + +Only standard stars with known instrumental magnitudes and photometric +indices are used to compute the parameters of each transformation +equation. Standard stars are identified by matching the id in the observations +catalog against the list of ids in the standard star catalog. + +The fitting process can be either interactive or non-interactive. Interactive +fitting is the default. In interactive mode, the user +is presented with plots of the data and the fit, can reject points +automatically using a k-sigma rejection algorithm, delete points interactively +with the cursor, change which parameters are to be fit and which are to be +held constant, and so on. A detailed description of +all the interactive options and colon commands can be obtained by typing +the following command. +.nf + +ph> help inlfit + +.fi + +The database file produced by FITPARAMS for the catalog and +observations files listed in sections III and IV and configuration file +listed in section V is shown below. + +.nf +# Mon 10:41:04 06-May-91 +begin UFIT + status 0 (Solution converged) + variance 4.965303E-4 + stdeviation 0.02228296 + avsqerror 1. + averror 1. + avsqscatter 0. + avscatter 0. + chisqr 4.965303E-4 + msq 3.901309E-4 + rms 0.01975173 + reference mu + fitting V+BV+UB+u1+u2*UB+u3*Xu + weights uniform + parameters 3 + u1 (fit) + u2 (fit) + u3 (fit) + derivatives 3 + 0.1 + 0.1 + 0.1 + values 3 + 6.108767 + -0.04842735 + 0.7180178 + errors 3 + 0.05704632 + 0.008730207 + 0.04209311 + +# Mon 10:41:14 06-May-91 +begin BFIT + status 0 (Solution converged) + variance 0.002550806 + stdeviation 0.0505055 + avsqerror 1. + averror 1. + avsqscatter 0. + avscatter 0. + chisqr 0.002550806 + msq 0.00207253 + rms 0.04552504 + reference mb + fitting V+BV+b1+b2*BV+b3*Xb + weights uniform + parameters 3 + b1 (fit) + b2 (fit) + b3 (fit) + derivatives 3 + 0.1 + 0.1 + 0.1 + values 3 + 4.826268 + -0.08220235 + 0.275757 + errors 3 + 0.1189408 + 0.02718129 + 0.08517767 + +# Mon 10:41:21 06-May-91 +begin VFIT + status 0 (Solution converged) + variance 9.547584E-4 + stdeviation 0.03089917 + avsqerror 1. + averror 1. + avsqscatter 0. + avscatter 0. + chisqr 9.547584E-4 + msq 7.501673E-4 + rms 0.02738918 + reference mv + fitting V+v1+v2*BV+v3*Xv + weights uniform + parameters 3 + v1 (fit) + v2 (fit) + v3 (fit) + derivatives 3 + 0.1 + 0.1 + 0.1 + values 3 + 4.632307 + 0.02190715 + 0.1877689 + errors 3 + 0.07831987 + 0.01721398 + 0.0573602 +.fi + +.ih +VII. APPLYING THE TRANSFORMATIONS TO THE STANDARD STARS + +This step is optional since the goodness of fit can be assessed more +efficiently from within the FITPARAMS task. However in some cases +the user may want a record of the fitted photometric indices for the +standard stars and the residuals from the fit. + +There are two tasks for evaluating the transformation equations +and which one the user must select depends on how he/she has +defined the transformations equations. + +If all references to the catalog file variables are on the left-hand side +of the transformation equations +and the right-hand side is a function of the observations file +variables only, then the user should use EVALFIT. The transformation equations +used for reducing photoelectric photometry are often written in this manner. + +If the left-hand side +of the transformation equation is a function of the observations file +variables and all references to the catalog files variables are on +the right-hand side of the transformation equations +then the user must use INVERTFIT. The transformation equations +for reducing CCD photometry are usually written in this manner. + +The full output of INVERTFIT for the partial catalog and observations +files listed in section III and IV and the configuration file +shown in section V are listed below. +Only observations which were successively matched +with objects in the standard star catalog files are shown. The fits for +objects with undefined observational variables could not be successfully +inverted producing a row of INDEF values. + +.nf +# Tue 15:50:37 14-May-91 +# List of observations files: +# ubv.std +# Number of catalog files: +# ubv.cat +# Config: ubv.cfg +# Parameters: ubv.fit +# +# Computed indices for standard objects only +# +# Columns: +# 1 object id +# 2 V +# 3 error(V) +# 4 resid(V) +# 5 BV +# 6 error(BV) +# 7 resid(BV) +# 8 UB +# 9 error(UB) +# 10 resid(UB) + + +105-405 8.308 0.002 0.001 1.563 0.006 -0.042 1.878 0.011 0.027 +105-411 10.597 0.008 0.023 0.913 0.024 0.037 0.639 0.027 -0.019 +105-257 9.140 0.004 0.000 0.451 0.006 0.039 0.040 0.007 -0.020 +105-262 INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF +106-575 9.345 0.007 -0.004 1.322 0.010 -0.014 1.457 0.009 0.026 +106-728 INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF +107-998 10.399 0.010 0.041 0.602 0.018 0.028 0.217 0.020 -0.057 +107-991 INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF +107-990 9.555 0.005 0.005 0.455 0.009 0.035 0.047 0.009 -0.047 +114-473 8.514 0.004 0.006 1.005 0.007 0.005 0.832 0.008 -0.032 +114-353 INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF +114-151 10.708 0.005 -0.048 0.748 0.011 0.002 0.221 0.014 0.069 +114-236 10.446 0.005 0.034 0.687 0.010 -0.057 0.093 0.011 0.007 +111-775 INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF INDEF +111-773 8.980 0.005 -0.017 0.270 0.006 -0.064 -0.258 0.005 0.047 +111-1342 9.263 0.006 -0.043 1.702 0.009 -0.012 1.726 0.076 0.054 +111-733 9.219 0.006 -0.039 0.262 0.007 0.038 0.172 0.007 0.008 +.fi + +.ih +VIII. PREPARE A PROGRAM STAR OBSERVATIONS FILE + +A program star observations file is prepared in the identical manner to +the standard star observations file as described in section IV. +In fact there is no intrinsic reason why standard star and program +star observations cannot occupy the same observations file since +they can be separated later by the EVALFIT and INVERTFIT tasks. +In the sample observations +file shown in section IV objects with names like 105-411 are the actual +standard stars and those with names like STD* can, for the purpose +of illustration, be regarded as program stars. + +.ih +IX. APPLYING THE TRANSFORMATIONS TO THE PROGRAM STARS + +The transformation equations are applied to the program stars in the same +way they are applied to the standard stars ad described in section VII. + +The output of INVERTFIT for the partial catalog and observations +files listed in section III and IV and the configuration file +shown in section V are listed below. Only observations +which were not successfully matched +with objects in the standard star files are shown. +Note that the residuals from the fit cannot be computed for program +objects and are therefore not output. + +.nf +# Tue 16:17:11 14-May-91 +# List of observations files: +# ubv.obs +# Number of catalog files: +# ubv.cat +# Config: ubv.cfg +# Parameters: ubv.fit +# +# Computed indices for program objects only +# +# Columns: +# 1 object id +# 2 V +# 3 error(V) +# 4 BV +# 5 error(BV) +# 6 UB +# 7 error(UB) + + +STD1-3 12.165 0.019 0.403 0.063 0.508 0.069 +STD2-2 12.136 0.045 0.796 0.096 -0.242 0.115 +STD2-4 11.710 0.034 0.479 0.061 0.660 0.113 +STD6-3 10.589 0.006 0.619 0.016 -0.069 0.022 +STD7-5 11.852 0.059 0.406 0.069 0.981 0.129 +.fi +.endhelp |