Photom -- calculate and apply a photometric solution to astronomical data

The basic idea is to calculate a photometric solution for a night, given a set of catalog stars with known magnitudes and a set of detected stars with instrumental magnitudes.

Usage:

        photom   catalog_file  racol deccol cat_nfilt  V=4 B=6 
                 detected_file racol deccol jdcol aircol flagcol
                 det_nfilt a,b,c d,e,f
                 [ det_files ... ]
                 [radius=] [outfile=]

       catalog_file   is name of the ASCII data file containing catalog
                            of standard star data

       racol          is the column of the catalog file in which are the
                            RA values (decimal degrees, J2000)

       deccol         is the column of the catalog file in which are the
                            Dec values (decimal degrees, J2000)

       cat_nfilt      is the number of "filter=column" pairs for the
                            reference catalog, immediately following.
                            Must be >= 1

       V=4            is a "filter=column" pair; here, "V" is the name
                            of a filter, and "4" is the index of the
                            column containing magnitudes in that filter
                            in the catalog

                      There must be exactly "cat_nfilt" such arguments
                            denoting passbands in the catalog file.


       detected_file  is the name of the ASCII data file containing
                            stars detected in some image, with instr. mags

       racol          is the column of the detected file in which are the
                            RA values (decimal degrees, J2000)

       deccol         is the column of the detected file in which are the
                            Dec values (decimal degrees, J2000)

       jdcol          is the column of the detected file in which are the
                            Julian Date values

       aircol         is the column of the detected file in which are the
                            airmass values

       flagcol        is the column of the detected file in which are the
                            "quality flag" values

       det_nfilt      is the number of "filter=magcol,magerrcol" pairs 
                            for the detected files, immediately following.
                            Must be >= 2

       a,b,c          denotes some passband in the detected file:
                            The values a,b,c are integers, where
                                     a   =   column with passband name
                                     b   =   column with magnitude val
                                     c   =   column with magerr val;
				               negative value means a
					       saturated star
                            A comma "," separates the integers.

                      There must be "det_nfilt" such arguments denoting
                      the passbands in the detected file.


       det_files ...  are optional additional names of files with data
                            on stars detected in other images.
                            They are assumed to have the same arrangement
                            of data columns and filter names as the
                            first file

       radius         (optional) radius (in arcseconds) to use when 
                            matching stars in catalog against the
                            detected stars
      
       outfile        (optional) base name of file into which to 
                            write diagnostic output.  

Note that all column numbers should be supplied by the user in 0-indexed form -- this, the first column of data in a file is "0", the second "1", and so forth.

Input files

Here's an example of the input file formats. Lines which start with a pound character "#" will be ignored. One can use input files which have a different number of columns of data, or columns in different order, as long as the command-line arguments to photom correctly describe the required data columns.

• The reference catalog "refcat" has lines which might look like this:

  #    RA           Dec      B      V      I
    222.41015     1.50449  9.577  7.751  5.973 
    221.77236     0.97097  6.685  6.702  6.671 
    221.85685     2.03581  6.928  6.827  6.684 
    221.75830     1.39323  9.965  8.751  7.553 
  

  Column 0 contains the RA, column 1 the Dec, column 2 the B-band magnitude, column 3 the V-band magnitude, column 4 the I-band magnitude.

• The measured instrumental magnitudes are placed in a file called "rawmags", with lines which might look like this:

  #ID   RA         Dec         JD    air  band  mag    err  band  mag    err flag
   0  222.41015  1.50449  6542.2334  1.33  V  7.929  0.009   I  5.973  0.010   0
   1  221.77236  0.97097  6542.2334  1.34  V  6.705  0.005   I  6.671  0.004   0
   2  221.85685  2.03581  6542.2334  1.40  V  6.841  0.006   I  6.684  0.006   1
   3  221.75830  1.39323  6542.2334  1.33  V  8.871  0.010   I  7.553  0.012 257
  

  In this example, the Right Ascension is in column 1, the Dec in column 2, the Julian Date of the measurement in column 3, the airmass of the measurement in column 4, columns 5, 6, 7 contain the name, mag, and magerr for the first passband (which happens to be V), columns 8, 9, 10 contain the name, mag, and magerr for the second passband (which happens to be I), and column 11 (the last one) holds the "quality flag" for each star.

  The "quality flag" contains information on detections of the star in all passbands. Each passband has a value which is the logical OR of

           0         no problems 
  	 1         star may be saturated 
  	 2         star is close to a bad region of the image 
  	 4         star is close to an edge of the image
  

  The values for each passband are combined as follows:

          flag for passband   0      is not changed
  	flag for passband   1      is shifted left by  8 bits (<< 8)
  	flag for passband   2      is shifted left by 16 bits (<< 16)
  	flag for passband   3      is shifted left by 24 bits (<< 24)
  

  The values are then OR'ed together logically. The resulting 32-bit value is the "quality flag" for the star. In the example above, stars 0 and 1 are okay; star 2 was possibly saturated in V-band; and star 3 was possibly saturated in both V-band and I-band images.

We could run the program with a command line like this:

        photom refcat 0 1 2 V=3 I=4 rawmags 1 2 3 4 11 2 5,6,7 8,9,10

Output files

We create three types of output file:

• a very small file containing summary statistics: number of stars in solution, photometric parameters in solution and their uncertainty. Goes in file with basename given by "outfile" arg (or uses "photom" as default), and extension ".coeff"

             photom.coeff        by default
             Jun04.coeff         if outfile="Jun04"
  

• a large file(s) containing information on all stars used in the photometric solution; both their raw input mags, and the catalog mags, and differences. Used for diagnostics and debugging. There is one such file per calibrated passband, with a filename given by the "outfile" arg (or "photom" by default), followed by an underscore "_" and the name of the passband, and extension ".comp".

             photom_V.comp           for passband V by default
             photom_I.comp           for passband I by default
             Jun04_V.comp            for passband V if outfile="Jun04"
             Jun04_I.comp            for passband I if outfile="Jun04"
  

• one big output file containing the magnitudes of all detected stars (not just those used to make solution) after calibration has been applied. Goes in file with basename given by "outfile" arg (or uses "photom" by default) with extension ".cal".

             photom.cal              by default
             Jun04.cal               if outfile="Jun04"
  

Here are examples of the output file formats. Continuing the example used to illustrate the input file formats (using data files with hundreds of stars), we create the following files:

• photom.coeff This contains the summary statistics of the photometric solution. There is one line per image, since each image is given an individual zero-point offset in the solution. The example below shows a solution for a dataset with two pairs of V and I images (and, hence, two input files).

      V=V,(V-I)  N    656  a  0  18.235  0.012  b  -0.091  0.008   RMS  0.025 
      V=V,(V-I)  N    656  a  1  18.240  0.010  b  -0.091  0.008   RMS  0.022 
      I=I,(I-V)  N    656  a  0  19.773  0.021  b   0.183  0.012   RMS  0.055 
      I=I,(I-V)  N    656  a  1  19.709  0.024  b   0.183  0.012   RMS  0.059 
  

  The V-band solution is based on the (V-I) color. There are two lines, one for each pair of V/I frames. The first V-band frame has a zero-point offset of 18.235 mag, with uncertainty 0.012 mag; the second V-band frame has a zero-point offset of 18.240 mag, with uncertainty 0.10 mag. All the V-band frames share a common color term of -0.091, with uncertainty 0.008. The RMS between the magnitudes of stars in the reference catalog and the calibrated magnitudes of matching measured stars in the first V-band frame is 0.025 magnitudes, and 0.022 mag in the second V-band frame.

  Note that the I-band solution is based on the (I-V) color, not the (V-I) color!

  The numbers in the solution shown above are not those actually produced by running the program on the input files I used to illustrate the file formats. Those were faked-up files in which the input and output values were nearly identical, and so the offset, color term and RMS were all perfectly zero. The values shown above are more likely to resemble those produced with real observations.

• photom_V.comp and photom_I.comp. These files provide a star-by-star comparison of the reference catalog magnitudes against the calibrated measured magnitudes. The file photom_V.comp has lines which are a bit too long to fit nicely on the screen, so I'll split a single line from the output file to cover two lines below.

        0      3  221.7583    1.3932  1.000   8.871  7.553  1.318   
                         8.751  -0.120   8.751  0.010  -0.000 
  

  The columns show
  1. an internal identification number, used only for debugging
  2. the star ID number given in the "rawmags" file
  3. RA
  4. Dec
  5. airmass
  6. raw magnitude in primary passband ("V" in this example)
  7. raw magnitude in secondary passband ("I" in this example)
  8. raw color ("V-I" in this example)
  9. reference catalog magnitude in primary passband ("V")
  10. difference between reference and raw magnitude
  11. calibrated primary magnitude ("V")
  12. uncertainty in primary magnitude
  13. difference between reference and calibrated magnitude
  One can plot various columns in this file against others to check for systematic trends in the residuals.

• photom.cal This file contains the calibrated magnitudes for each measured star. Several lines from a sample file are shown below:

       34  221.6462   3.0349  100.0   V  9.080  0.010 0     I  7.397 0.010 0
        3  221.7583   1.3932  100.0   V  8.751  0.010 0     I  7.553 0.010 0
       25  221.7712   4.4628  100.0   V  8.778  0.010 0     I  8.296 0.010 0 
  

  The columns show
  1. the star ID number given in the "rawmags" file
  2. RA
  3. Dec
  4. Julian Date of measurement
  5. name of first calibrated passband ("V" in this example)
  6. calibrated magnitude in first passband
  7. uncertainty in magnitude in first passband
  8. flags for first measurement (see below)
  9. name of second calibrated passband passband ("I" in this example)
  10. calibrated magnitude in second passband
  11. uncertainty in magnitude in second passband
  12. flags for second measurement (see below)

  The flag column has value zero to indicate no known problems, and non-zero to indicate a possible problem. See the section about input-file format for the meaning of bits in this flag.

Last modified Feb 28, 2002, by MWR.