From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 noao/digiphot/photcal/doc/mkobsfile.hlp | 519 ++++++++++++++++++++++++++++++++
 1 file changed, 519 insertions(+)
 create mode 100644 noao/digiphot/photcal/doc/mkobsfile.hlp

(limited to 'noao/digiphot/photcal/doc/mkobsfile.hlp')

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
-- 
cgit 

