diff options
Diffstat (limited to 'noao/digiphot/photcal/doc/mknobsfile.hlp')
| -rw-r--r-- | noao/digiphot/photcal/doc/mknobsfile.hlp | 516 |
1 files changed, 516 insertions, 0 deletions
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 |