path: root/noao/digiphot/photcal/doc/mkphotcors.hlp

.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