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

.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