photometry files containing observations of objects in one or more fields
obsfile photfiles incolumns idfilters imsets observations
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.
Photfiles 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 incolumns.
incolumns
A list of nine numbers separated by commas or whitespace specifying
which columns in photfiles contain the following fields: the image name
or id, x coordinate, y coordinate, filter id, exposure time, airmass, time of observation,
instrumental magnitude, and magnitude error, respectively.
idfilters
The list of filter ids separated by whitespace or
commas which define a complete observation. The filter ids must
correspond to those in photfiles.
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 imsets
will be extracted from photfiles.
Observations are listed in imsets, 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 imsets is described in detail below.
observations
The output observations file suitable for input to FITPARAMS or
EVALFIT/INVERTFIT.
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 photfiles. The observing parameters for each image are
listed in the file obsparams, 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 obscolumns. The image names must match those in
imsets. Images which have no
entries in obsparams are assigned the values stored in photfiles.
obscolumns = 2 3 4 5
The list of numbers separated by commas or whitespace specifying which columns
in the text file obsparams 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 photfiles airmass
values, obscolumns should be set to "0 0 column 0", where column is
the airmass column number.
The default value of obscolumns corresponds to
the format of the default obsparams file produced by MKIMSETS.
minmagerr = 0.001
The error that will be assigned to a non-INDEF valued magnitude
measurement whose recorded error is less than minmagerr.
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
and output to observations.
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
imsets. Images for which
no shift is supplied are assigned x and y shifts of zero.
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
imsets. Images for which
no aperture correction is supplied are assigned a default value of zero.
normtime = no
Normalize the magnitudes to an exposure time of one time unit using the
exposure times in photfiles.
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 photfiles, adds the shift for that image in
shifts to the extracted x-y coordinates,
and matches the objects to within tolerance pixels.
Missing objects are assigned INDEF entries in observations.
If tolerance 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.
allfilters = no
Output only objects which are sucessfully matched in all the filters
specified by idfilters?
verify = no
Verify interactive user input? This option is used only if any of imsets,
obsparams, shifts, or apercors are set to the
standard input "STDIN".
verbose = yes
Print messages about actions taken by the task or any warnings or errors
encountered?
OBSFILE takes a list of user generated text files photfiles, where each file contains observations of one or more objects taken through one or more filters, and the image set file imsets, and prepares a single observations file observations. 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 photfiles, 2) corrects any erroneous or missing values of filter id, exposure time, airmass, or time of observation in photfiles, 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 occurence or x-y position, and 5) assigns a unique name to each object in each field.
The parameter incolumns describes the format of photfiles. Incolumns is a list of nine 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 and the magnitude error. For example if incolumns is "1 2 3 6 8 7 9 4 5", the image name is assumed to be in column 1, 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 imsets or the corresponding input data is skipped. The columns image name, x coordinate, y coordinate, and magnitude are mandatory and must be present in photfiles. Other missing columns in the data may be represented by a "0" in the appropriate place in incolumns. For example, if there is no magnitude error column in photfiles a value of INDEF will be written in the appropriate column in observations. If there is no airmass column in photfiles the value in obspararms if any, or the value INDEF will be written to the appropriate column in observations. If there is no filter id column in photfiles the value in obspararms if any, or one of the values in idfilters will be written to the appropriate column in observations. If there is no exposure time column in photfiles the value in obspararms if any, or a value of one will be assumed. If there is no time of observation time column in photfiles the value in obspararms if any, or a value of INDEF will be assumed.
The image set file imsets 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 imsets, 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 observations. 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 observations. Imsets also tells OBSFILE which images in photfiles are images of the same region of the sky belonging to the same observation. The format of imsets is described in detail below. If the number of observations is small the user may wish to simply type in imsets by hand. If the number of observations is large, a separate task MKIMSETS is available to assist users in preparing imsets.
Values of the filter ids, exposure times, airmasses, and times of observation, which are undefined or incorrect in photfiles, can be corrected by reading values listed in the columns obscolumns in the file obsparams. The format of obsparams is described in detail below.
OBSFILE matchs the objects in different images within the same observation either by order of occurrence if tolerance 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 tolerance pixels of each other. The user may supply an optional file of x and y shifts shifts to be added to the object positions prior to matching. The format of shifts is described in detail below. If the parameter allfilters is "yes", only objects which are matched in all the filters idfilters are output to observations.
OBSFILE permits the user to supply an optional file of aperture corrections apercors containing magnitude corrections which are added to the instrumental magnitudes in photfiles. The format of apercors 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 observations, of the fields extracted from photfiles. 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 observations. 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 imsets 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 imsets, 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 imsets which match those in photfiles will be extracted.
The field name is used to generate the output object name in observations. If there is only a single measured object in the field, then the name of that object in observations will be the name of the field. If the single object is a standard star, the user should edit imsets 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 observations. If the star is a standard star, the user must edit the object names in observations 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 photfiles or obsparams then the images in each image set are assigned the filter ids in idfilters in order of occurrence.
The imsets 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.
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
THE OBSPARAMS FILE
A sample corrections file obsparams 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 obsparams and obscolumns is set to "2 3 4 5"
nite006 3 8 1.256 14:30:02.3
Zero can be used as a place holder in obscolumns, 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 obscolumns is "0 2 3" and obsparams looks as follows.
nite006 8 1.256
Only images listed in imsets can have their observing parameters modified by obsparams.
THE SHIFTS FILE
The file shifts 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 shifts must match those in imsets.
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.
nite040 10.0 5.0 nite041 10.0 5.0
An alternate way of listing the same observations would be the following.
nite039 -10.0 -5.0
THE APERCORS FILE
The file apercors 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 apercors must match those in imsets.
The apercors 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".
nite039 -0.150 nite040 -0.100 nite041 -0.090
For the previous set of UBV obervations the output file observations 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 observations.
# 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 . . . . . .
The accompanying format description file has the following form.
# 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
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.
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
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.
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
mkimsets, mknobsfile, mkobsfile,