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.

Usage:

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

where

     
       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.

The "coofiles" must have lines which look exactly like this:
```
#  ID     xc        yc     peak     FWHM     round    sharp
    1    6.24    575.46     858    2.471     0.046    0.860 
    2    7.10    217.70    1341    2.610     0.015    0.620 
    3   21.73   1747.02    1304    1.784     0.355    0.867 
    4   24.94   1471.74    3970    2.259     0.154    0.834 
```
The columns must contain
1. an ID number
2. row position of star on CCD
3. col position of star on CCD
4. peak pixel value
5. FWHM of stellar image
6. roundness parameter (basically, ratio of width in one direction to width in another)
7. sharpness parameter (basically, a ratio of peak pixel value to surrounding pixel values)
At the moment, the ID, FWHM, roundness, and sharpness values are stored in a data structure for each star, and the other values are ignored. In addition, the program doesn't use the stored values at the moment ... but future versions might allow the user to place limits on these parameters for accepting stars as valid.
The "astfiles" must have lines which look like this:
```
#  ID     RA          Dec    sky  skyerr    mag   magerr  qual
    1  228.50650    0.76982  364  10.27    15.630 0.059    1
    2  228.50063    0.00148  384  12.47    14.370 0.020    0
    3  228.48867    3.28749  355   8.72    15.659 0.060    3
    4  228.47779    2.69573  355   9.50    14.152 0.017    0
```
The columns must contain
1. an ID number (which matches ID of star in the "coofile")
2. Right Ascension of star, in decimal degrees
3. Declination of star, in decimal degrees
4. sky value near star on CCD
5. uncertainty in sky value for star
6. instrumental magnitude
7. uncertainty in instrumental magnitude
8. quality flag: zero for a normal measurement, non-zero (combination of bitflags) to indicate some problem(s)
The ID, RA, Dec, mag, magerr, and quality values for each star are stored in a structure, and all of them are used by the program. The sky and skyerr fields are read, but then discarded.

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:

star ID number, from the input files
RA, in decimal degrees
Declination, in decimal degrees
Julian Date of measurement
airmass of measurement
first passband name
first passband instrumental magnitude
uncertainty in first passband instrumental magnitude
second passband name
second passband instrumental magnitude
uncertainty in second passband instrumental magnitude
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.