Skip to content

WCSFit

Jump to bottom
Gary Bernstein edited this page Apr 30, 2017 · 2 revisions

WCSFit optimizes the parameters of an astrometric model to maximize the internal agreement between positions derived for distinct detections of objects on the sky. See the DECam astrometry paper for some deeper explanations of how this works and how our particular DECam models are chosen. This wiki page will document usage of the program.

The structure and usage of WCSFit are very similar to the photometric-fitting program PhotoFit, so this wiki page will just refer there for many details, and here we highlight the differences. The primary distinction is that WCSFit does not have the equivalent of a photometric prior - instead, it requires that we have a reference catalog of at least objects with known sky positions in each field, used to remove degeneracies.

Preparation

The primary input to WCSFit is a matched catalog, as prepared by configure.py operating on your Configuration files and then WCSFoF finding all spatially coincident detections. This <basename>.fof file only indexes the detections; WCSFit will still access the catalog files to read each detection's magnitude, position, and errors. If your astrometric model has chromatic terms, it will be necessary to have at least one color catalog matched with the detections. In the standard processing, WCSFit is run after PhotoFit and MagColor have established colors for each match and put these into an augmented matched catalog named <basename>.color.fof.

You also need to have file(s) specifying the astrometric model.

Functional description

WCSFit should be run to fit the solution for all bands simultaneously, since all bands should agree on the sky position of stars [Note: this is not the case for galaxies, whose photocenter can vary from band to band. See the discussion of affinities in ???] .

A rough outline of the WCSFit process is:

  1. Read and validate the program's parameters.

  2. Read the input .astro YAML files specifying the model structure.

  3. Read from the input fof file the tables describing all fields, instruments, exposures, and extensions. Determine which are relevant to the solution for the requested bands and ignore the remainder.

  4. For each useful input extension, deserialize the nominal WCS, which will be used to initialize the free parameters of the astrometric model.

  5. Build an initial PixelMap for each extension by looking up its EXPOSURE/DEVICE/base name in the input maps.

  6. Freeze the parameters of any model component matching the fixMaps parameter. An error results if any parameter to be frozen was initialized with default values.

  7. Examine the map structure to reveal possible degeneracies: are there composited maps that are degenerate with each other, e.g. is there a reference catalog in each field to prevent the solution from wandering? Are there degeneracies between the instrument and exposure portions of the solutions? If so it will attempt to break this by converting one or more exposure solutions to the Identity map.

  8. Initialize free parameters of maps by fitting them to the starting WCS provided for each extension.

  9. Read the input positions, errors for all Detections passing selection cuts. If there are color terms in the solution, also read the catalogs providing color information for each match.

  10. Purge any detections that are too noisy, matches that have too few detections or don't have needed color information, and exposures that have too few matched detections to be fit. Freeze the parameters of maps that refer solely to the purged elements.

  11. Randomly select the specified reserveFraction of the matches to be withheld from the fitting process, so that they can be used for validation of the fit.

  12. Begin the optimization loop by executing a Newton-method minimization of chi-squared. If this does not converge quickly, we switch to a Levenberg-Marquardt solution. Should the normal matrix of the solution have any all-zero rows, this indicates we have an unconstrained parameter. We freeze the parameter and continue. If the normal matrix is still degenerate, the nature of the degenerate eigenvector(s) is reported and the program halts.

  13. After the fit, look for outlier detections and clip them out of the solution. Iterate with (12) until sigma-clipping changes the chi-squared by less than chisqTolerance.

  14. Output the results of the fit: the astrometric solution itself to the outWcs, and a table of residuals to the fit for all detections to outCatalog. A table of the quality of fit to each exposure is printed at stdout.

Usage / Parameters

The command-line call for the program is

% WCSFit <match file> [parameter file] [parameter file...]  [-parameter[=]value...]

The parameters of the program can be specified either in one or more parameter files passed on the command line after the <basename>.fof file, or can be given individually on the command line. Parameter files are read in order, with later values overriding earlier; and any value given on the command line overrides those in the files.

Running the program with no arguments will dump all the parameters and their values. Here is the listing:

      INPUTS=                     ;
maxPixError = 0.1                 ;Cut objects with pixel posn uncertainty above this
sysErrorColumn=                     ;Extension table column holding systematic error, if any
sysError    = 0.01                ;Fixed systematic error for detections (pixels)
referenceSysError= 0.003               ;Fixed systematic error for reference objects (arcsec)
minMatch    = 2                   ;Minimum number of detections for usable match
minFitExposures= 200                 ;Minimum number of detections to fit exposure map
useInstruments= .*                  ;the instruments to include in fit
skipExposures=                     ;exposures to ignore during fitting
CLIPPING    =                     ;
clipThresh  = 5                   ;Clipping threshold (sigma)
clipEntireMatch= F                   ;Discard entire object if one outlier on later passes
skipFile    =                     ;optional file holding extension/object of detections to ignore
divideInPlace= F                   ;use in-place Cholesky to save memory but lose debug of degeneracies
FITTING     =                     ;
reserveFraction= 0                   ;Fraction of matches reserved from re-fit
seed        = 0                   ;seed for reserving randomizer, <=0 to seed with time
chisqTolerance= 0.001               ;Fractional change in chisq for convergence
inputMaps   =                     ;list of YAML files specifying maps
fixMaps     =                     ;list of map components or instruments to hold fixed
COLORS      =                     ;
colorExposures=                     ;exposures holding valid colors for stars
minColor    = -10                 ;minimum value of color to be used
maxColor    = 10                  ;maximum value of color to be used
OUTPUTS     =                     ;
outCatalog  = wcscat.fits         ;Output FITS binary catalog
outWcs      = wcsfit.wcs          ;Output serialized Wcs systems

Here are more details on the program parameters, where they differ from those in PhotoFit

  • maxPixError: Will not use detections with measurement error on the pixel coordinates. The error is taken from the column specified by ERR_KEY.
  • sysError, sysErrorColumn: The specified sysError will be added in quadrature to the position error listed in the catalogs for each object. If a sysErrorColumn is given, the systematic error for each exposure will instead be taken from the database attribute with the prescribed name. Units are pixels.
  • referenceSysError: A different systematic error is assigned to reference catalogs, i.e. those with positions already in RA/Dec coordinates. The value here is in arcseconds.
  • colorExposures: names(s) (or matching regexes) of catalog files that are considered to hold valid colors for the matches in their COLOR column. Important to set when doing any color-dependent solution.
  • outCatalog, outWcs: the names of the output files containing the fit residuals, and the model with best-fit parameters, respectively. Important

Potential pitfalls, subtle and otherwise

  • The most common source of failure, in particular obtaining singular normal matrices, is when the starting WCS for one or more catalogs was in error, leading to the exposure(s) having detections that match, and those that match being spurious. If the number of spurious detections is very low then the exposure will be rejected at the outset as degenerate or below the minDetection threshold. But degeneracies may arise after rounds of sigma clipping have removed many of the spuriously matched detections. And you may see many rounds of sigma-clipping while cleaning out the spurious matches.

Clone this wiki locally