Collate -- combine raw instrumental magnitudes in different passbands

This program converts a set of files containing raw instrumental magnitude measurements (one instrumental magnitude per file) into a single file, in which measurements of the same star (in different passbands) have been merged.

The positions of stellar detections in each passband are compared to each other, and any objects which are within matchrad arcseconds are considered a match. If there are several objects within this radius, the one closest to the detection in the first passband is chosen. By default, in order for stars to appear in the merged output file, they must have valid measurements in all passbands. A value of "99" for magnitude or uncertainty in magnitude, in any passband, disqualifies a star. However, the user may permit "orphan" stars to be retained in the output by using the orphans option on the command line; see instructions below.

The result of the collate program is a set of stars with good measurements in all passbands. These may then be fed as input to the photom program for calibration.


        collate  passband= coofile astfile passband= coofile astfile [...]
                 matchrad= jd= lat= long= exptime= [orphans=] [outfile=]


       passband       is name of a passband, such as V or I
                            The two following args are required:

       coofile        is the name of a ".coo" data file for that passband
                            contains info on each detected star's shape

       astfile        is the name of a ".ast" data file for that passband
                            contains (RA, Dec) and instrumental mag 
                            for each detected star 

                      (there can be 2-4 sets of "passband= coofile astfile" 
		       args, each describing data in a different passband)

       matchrad       radius (in arcseconds) to use when 
                            matching stars detected in each passband
                            against those in other passbands
       jd             Julian Date when image was taken

       lat            latitude of observations (degrees North of equator)

       long           longitude of observations (degrees West of Greenwich)

       exptime        exposure time (in seconds).  Is assumed to be
                            the same for all passbands

       orphans        (optional) what should we do with stars not detected
                            in all passbands?  By default, or if orphans=0,
                            we discard them.  But if orphans=1, we retain 
                            them and pass them through to output. 

       outfile        (optional) name of output file
                            stdout used by default

Input files

Here's an example of the input file formats. Lines which start with a pound character "#" will be ignored. Unlike the photom program, which takes command-line arguments to describe the format of the input files, the collate program currently demands that the input files have formats which adhere strictly to the descriptions below. Future versions of the program may have a mechanism which allows some flexibility.

We could run the program with a command line like this (I've split the line to keep it from wrapping around):

        photom passband=V field1v.coo field1v.ast 
	       passband=I field1i.coo field1i.ast
	       matchrad=5 jd=2451659.826 lat=43.43 long=92.33 
          exptime=60.0 outfile=field1

Output files

We create a single output file. If the user doesn't provide an outfile= argument on the command line, the output is sent to stdout. If he does supply an outfile= argument, the output is placed in a file of the given name. It has a format like this:

# ID     RA        Dec         JD       air      mag   magerr     mag   magerr  qual
  88  224.25832  0.46297  2451659.8260 1.402  V 17.897  0.047  I 17.008  0.031     0
 148  224.26077  1.97270  2451659.8260 1.369  V 18.336  0.068  I 16.672  0.023     1
  94  224.27842  1.56057  2451659.8260 1.378  V 17.981  0.050  I 16.651  0.022   257
  32  224.26298  1.00923  2451659.8260 1.333  V 19.304  0.126  I 99.000 99.000  2048

The columns have the following meanings:

  1. star ID number, from the input files
  2. RA, in decimal degrees
  3. Declination, in decimal degrees
  4. Julian Date of measurement
  5. airmass of measurement
  6. first passband name
  7. first passband instrumental magnitude
  8. uncertainty in first passband instrumental magnitude
  9. second passband name
  10. second passband instrumental magnitude
  11. uncertainty in second passband instrumental magnitude
  12. quality flag for all passbands combined (8 lowest bits for first passband, 8 next-lowest bits for next passband, etc.)

Note that the final star in the list above was detected only in the V passband. The user must have given the command-line option orphans=1 in order for this star to be passed through to the output.

There may be up to 4 different passbands included in the merged output. Each passband has three columns of data.

Last modified Mar 27, 2005, by MWR.