MagColor

Purpose

The MagColor program has the job of calculating colors of objects in the catalogs so that chromatic solutions can be derived [one can also have the colors in a pre-existing catalog that is supplied in the initial configuration and matched by WCSFoF ].

MagColor does several bits of bookkeeping:

• Reads all matches from the fof file, looks up all detections in the catalogs corresponding to the request filters, and applies the PixelMap and PhotoMap to each one to get calibrated mag, ra, and dec for each such detection.
• Calculates the mean ra and dec, and mean mag in each requested band, for all detections in each match.
• Calculates desired color(s) for each match having valid data in both bands comprising the color(s). These are written into the output color catalog, typically named basename.color.cat.
• The input fof match file is augmented with information on the color catalog. It becomes a new "exposure" and extension, and the entries in the color catalog are added to the lists of detections for all matches having a color. This augmented match list is output as the match file out which is typically named basename.color.fof. It is this file that is passed on to PhotoFit and WCSFit for derivation of chromatic solutions.
• The mean magnitudes and positions of every match with useful data in the requested bands are written to the mag out file as a binary FITS table, typically basename.mags.cat

Usage

Here is the help output from MagColor (run with no arguments to get this). The program shares with the other C++ programs (`PhotoFit, WCSFit, WCSFof, ...) the same options for specifying parameters, either via parameter files or command-line arguments.

usage: MagColor <match file in> <match file out> <mag file out> [parameter file...]
   [-parameter[=]value...]
      <match file in>:  FITS file with binary tables produced by WCSFoF
      <match file out>:  FITS file with binary tables, augmented with match and color info
      <mag file out>: Name of output FITS catalog file to hold magnitudes
      Program parameters specified as command-line options or read from
          parameter file(s) specified on cmd line
#---- Parameter defaults: ----
maxMagError = 0.05                ;Only output mags with errors below this level
sysError    = 0.001               ;Systematic added in quadrature to mag error
clipThresh  = 5                   ;Magnitude clipping threshold (sigma)
skipFile    =                     ;Optional file containing extension,object pairs to ignore
bands       =                     ;bands to output and instruments they come from
colors      =                     ;colors to tabulate and files they go into
useInstruments= .*                  ;list of instruments to use for mags
wcsFiles    =                     ;files holding WCS maps to override starting WCSs
photoFiles  =                     ;files holding single-band photometric solutions for input catalogs

The non-obvious parameters are:

• sysError is added in quadrature to each detection's tabulated magError, and the results are used to construct weighted mean measures of magnitude for the outputs.
• bands should be a comma-separated list of the bands for which you want mean magnitudes in the mag file out.
• colors determines what color(s) is written to what file(s). The value of the parameter should look like g-i@base.color.cat, which means that the g-i color will be stored in binary FITS table in a file named base.color.cat. More than one such entry can be given, separated by commas.
• useInstruments can be used to constrain which instruments' data are used. Of course only the instruments in the requested bands will be used.
• wcsFiles, photoFiles give the names of .astro and .photo files that specify the position/magnitude transformations that will be applied to the detections before they are averaged. Each is a comma-separated list. The photoFiles are essential; the whole point is to calculate object mags/colors using the well-fit calibration files we have generated. The wcsFiles will be only rarely used, since the starting WCS that is encoded in the fof files are sufficient unless one is trying to produce a high-precision astrometric listing in the mag file out table.

Finally, a word about clipThresh: the sigma-clipping is done assuming that the input magnitude errors and specified sysError value are an accurate description of magnitude errors. If this is not true, e.g. if the chi-squared of the PhotoFit is >1, then the default clipThresh=5 could be more like 2-sigma clipping instead of 5-sigma, and you will clip way too many objects. It may be wise to inflate clipThresh.