STScI Logo

mknobsfile noao.digiphot.photcal


NAME · USAGE · PARAMETERS · DESCRIPTION · OUTPUT · EXAMPLES
TIME_REQUIREMENTS · BUGS · SEE_ALSO

NAME

mknobsfile -- prepare an observations file from a list of APPHOT/DAOPHOT files containing observations of objects in one or more fields

USAGE

mknobsfile photfiles idfilters imsets observations

PARAMETERS

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.
idfilters
The list of filter ids separated by whitespace or commas which define a complete observation.
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 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 the names of the images of that field which belong to that observation. The format of imsets is described in detail below.
observations
The output observation file suitable for input to FITPARAMS or EVALFIT/INVERTFIT.
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.
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 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, 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 = "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 ob 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 if its recorded magnitude 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 (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 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 0.0.
aperture = 1
The aperture number in photfiles 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.
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 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 any data entered interactively by the user ?
verbose = yes
Print status, warning, and error messages ?

DESCRIPTION

MKNOBSFILE takes a list of APPHOT or DAOPHOT database files photfiles , where each file contains observations of 1 or more objects taken through 1 or more filters, and the image set file imsets and prepares an observations file observations . 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 photfiles , 2) corrects any erroneous or missing values of filter id, exposure time, and airmass in photfiles , 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 occurence or x-y position, 5) assigns a unique name to each object in each field.

The image set file imsets 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 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 MKNOBSFILE 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 exposure times which are missing 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.

MKNOBSFILE 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 .

MNOBSFILE 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 MKNOBSFILE 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 observations file name observations 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 imsets file lists the observations of each field which are to be extracted from photfiles , assigns a name to each field, and informs MKNOBSFILE 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 images in imsets which match those in photfiles 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 observations . If there is only a single measured object in a 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, 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 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 or 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, 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.

	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

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, airmass, and time of observation for the first "STDFIELD2" V frame. The correct filter id, exposure time, and airmass is supplied in obsparams and obscolumns is set to "2 3 4 5"

	nite006    3 8 1.256 05:34:03.2

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 0" 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 "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.

	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 "STDFIELD14".

	nite039    -0.150
	nite040    -0.100
	nite041    -0.090

OUTPUT

For the previous set of UBV observations the output file observations 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 obsparams file, and so are not included in observations .

	# 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       .       .        .     .     .     .

The accompanying format description file has the following form.

# 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

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.

	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

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.

	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

3. Prepare an observatons 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.

	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

TIME REQUIREMENTS

BUGS

SEE ALSO

mkimsets,mkphotcors,mkobsfile


Search Form · STSDAS