HOW-TO Troubleshoot astrometry quality problems and improve solutions

Astrometry, like photometry, requires good data to get a good result. The process to derive an astrometric solution is a complex one and is described in brief in , and in detail in the LDAC pipeline documentation and many other astrometry references.

The scope of this document is to describe specific things that can go wrong in an astrometric solution and approaches to improve the astrometric solution, both in the context of the Astro-WISE Environment.

If a correction method below refers to a parameter to be set, it can be set through the . In short:

> pars = Pars(AstrometricPatameters)
> pars.process_params.SOME_VALUE = 100
> ...
> AstrometricParametersTask(..., pars=pars.get()).execute()

As with any aspect of data reduction, a good rule of thumb if you have any problem with astrometry, inspect the data if no obvious error presents itself. Please take a look at to see how this is done in the Astro-WISE Environment.

Errors in LDAC

LDAC is the software suite used to create the astrometric solution, whose steps are given in . Despite (or because of) the best efforts of programmers, software can always have problems or can exit for very specific reasons. To help make the error messages less cryptic, LDAC’s Python wrapper has been upgraded to output an ordered list of debugging information in case of a software failure. All individual programs linked by a common instance of the LDAC class (e.g., preastrom, associate, aplastrom, astrom, etc.) will have their output logged where it normally would have been supressed so that any warnings preceeding the failure can be seen.

The normal output of an individual LDAC program will show only the command-line, the program version, and program description. If an error occurs, the configuration file, warnings, and errors are also added to this output. If there are programs run from the same LDAC instance, those that have run will have their full output preceeding the output of the failed program. The bottom line is that errors should be easier to diagnose for both the user and the programmer.

Viewing the log output is the best way to try and troubleshoot any astrometry error. The LDAC class instance has verbosity set to NORMAL by default which gives the minimum of information when all is well, and everything when there is a problem. By setting the individual routine settings to VERBOSE (or even DEBUG) instead:

> pars = Pars(AstrometricPatameters)
> pars.preastromconf.VERBOSE = 'VERBOSE'
> ...
> AstrometricParametersTask(..., pars=pars).execute()

will increase the verbosity in the event of an error. If you need even more and want as much information as LDAC can produce, you can set the LDAC class verbosity in the code to VERBOSE or DEBUG:

ldac = LDAC.LDAC(verbose='DEBUG')

This latter method is recommended only if it is absolutly necessary, as it involves code changes and a very large amount of program output to go through.

Specific conditions from LDAC log output

If the solution fails with a software exception, deciphering the output is the only way to figure out what happened. The terminal Exception (the very last error message) should contain some indication of what happened. If there is no help there, a perusal of the previous log messages can be helpful. If they are not, posting the output to the Issues list is the quickest way to get expert help.

Below are included some very common log messages that may indicate specific problems. Some terms are defined for this section only for clarity:

  • num_ext is the number of extracted objects, found in the line containing the text: “objects of field”
  • num_ref is the number of reference objects from the extracted region, found in the line containing the text: “objects from reference catalog”

The first term is the program where a specific error occurs. This is followed by criteria, a possible cause, and a course of action:

  • preastrom \(-\) if num_ext is low (on the order of 10) and num_ref is high (on the order of 100), there are still more objects to be extracted, lower extraction threshold:
  • preastrom \(-\) if num_ext and num_ref are higher (on the order of 100, 1000, respectively, or both of the order of 100), it is possible the AstrometricCorrection is bad or was not run, check the alignment with the reference catalog, see

  • preastrom \(-\) if num_ext and num_ref are swapped in magnitude (on the order of 1000, 100, respectively), there may be a cluster where the reference catalog is necessarily incomplete, try using the .

  • preastrom \(-\) if num_ext is about a factor of 2 larger than num_ref, there may have been an error in the pointing where the sources are doubled, inspect the image as described in HOW-TO Inspect Astrometry (see above)

Quality Control (QC) Values Exceeded

Astrometric solutions in Astro-WISE, like all other calfiles, have QC limits to determine if the calfile has the required quality. If these limits are exceeded, the solution is marked as bad and there may be methods to help improve the quality. This section addresses specific cases where quality may be improved.

NREF too low

Low NREF (number of output reference pairs) can be caused by a number of situations, from low SNR data (low EXPTIME), to very sparce fields, to large differences in filter band between the extracted and reference catalogs. There are two ways that too low an NREF can harm a solution:

  1. AstrometricParameters.process_params.MIN_NREF sets a limit in preastrom (MIN_OBJ) where it refuses to process catalogs with fewer than this number of extracted or reference objects in the defined region. An LDAC error will result from this.
  2. AstrometricParameters.process_params.MIN_NREF also sets a limit for successful solutions from astrom (i.e., solutions not affected by the previous point) to be flagged as poor. In this case, it is the final number of reference pairs used in the solution. Only a flag will be set in this case.

To improve a solution with an NREF too low where either of these situations occurred, more reference pairs are necessary. There are a few ways to accomplish this. One method would involve decreasing the extraction threshold:

  • AstrometricParameters.sexconf.DETECT_THRESH

below the default of 10.0 to increase the number of extracted sources that can be considered for pairing. Another method involves the use of a global solution and requires a dithered set of observations via the . One last method involves adding more chips from the same exposure, but it is not formalized in Astro-WISE except during ingestion (the method is called AstrometricCorrection).

NREF too high

Usually, more reference pairs are better, but only to a certain limit. If the density of sources is too high (e.g., greater than approximately 1200 in a 2k\(\times\)4k CCD chip at 0.238 arcsec/pixel, i.e., the case with WFI) and the association radius too high (e.g., greater than approximately 3 arcsec), false solutions due to random associations can occur. Also, attempting to solve astrometry using data taken in a significantly different filter from reference catalog can add confusion if density is high. For these reasons, a QC limit has been established for this condition.

Very little can be done to help this kind of data other than trying to decrease the number of reference pairs by decreasing the number of extracted sources. This can be done by increasing the extraction threshold:

  • AstrometricParameters.sexconf.DETECT_THRESH

Please note, this does nothing to decrease the number of reference sources! As such, the helpfullness off this method is limited. In addition to reducing the number of extracted objects, the association radius between the extracted and reference catalogs:

  • AstrometricParameters.associateconf.INTER_COLOR_TOL

should be decreased to reduce the chance of false associations. An associated parameter, ISO_COLOR_TOL, has no effect for local solutions involving only onechip. Changing it in this case is unnecessary.

SIG_DRA or SIG_DDEC, or RMS too high

If the standard deviation of \(\Delta\)RA or \(\Delta\)DEC, or the RMS of the solution is outside of the QC limits, the solution is considered poor. To improve this, decreasing the number of reference pairs (NREF) might help, assuming those removed were of poorer quality (e.g., fainter). A better method is to decrease the radius over which associations can occur. Adjusting:

  • AstrometricParameters.associateconf.ISO_COLOR_TOL

to lower values will do just this with respect to sources in a reference catalog, and adjusting:

  • AstrometricParameters.associateconf.INTER_COLOR_TOL

will affect only overlapping sources in the same catalog (e.g., global solutions).

What is being adjusted here is the factor of the object’s size (actually an ellipse as set by the source extraction parameters RA, DEC, a, b, \(\Theta\)). Only objects whose position overlaps the ellipse of another object will be associated with it. These settings should be used with care as setting these values too low can result in too few reference pairs very quickly.

Problems with the Solution

In addition to software exceptions and QC limit issues, the data can be of such a type to prevent a solution from converging. This section describes some specific configurations that can be adjusted to fix certain problems.


The first step of solving astrometry in Astro-WISE is running preastrom to solve the translation, rotation, and scaling of the input data.

The recommendations below have been incorporated into the AstrometricParameters routines as a fallback in case preastrom fails with the basic settings. If there are still preastrom failures at the more conservative settings, inspect the data to make sure there is nothing unusual, and proceed carfully.


The first step of preastrom is measuring distances between all objects and examining the (\(\Delta\)X, \(\Delta\)Y) parameter space. The total area that goes into the distance determination is the area covered by the input catalog plus a border of MAX_OFFSET pixels around the catalog area. Thus, if there is a pointing offset greater than MAX_OFFSET pixels, preastrom will never find the proper solution.

If inspection of the logs of failed preastrom runs reveals the number of extracted and reference objects are similar and number on the order of 100, there may be a shift beyond the default value of MAX_OFFSET. Inspect the frame as shown in to see if this is the case. If so, increase the value of MAX_OFFSET to larger than the offset observed. Be aware, however, that if the object density increases in parts of the border area (e.g., presence of a clutser), increasing MAX_OFFSET may have unpredictable results.


After the (\(\Delta\)X, \(\Delta\)Y) measuremnts have been made, preastrom runs a boxcar smoothing of the (\(\Delta\)X, \(\Delta\)Y) parameter space with a boxcar size of POS_ERROR pixels, using the peak of that distribution to define the set of data to triangulate on.

If excessive scaling or moderate rotation (\(\widetilde{>}\)2 degrees) might be causing preastrom to fail, increasing POS_ERROR can help if the density is not too high.


Once the subset of data is chosen, a triangulation method using angle and distance is used to determine the final rotation and scaling (affine transformation), and final offsets. If the RMS of the fit is above RMS_TOL, SEL_MIN will be increased to choose a larger number of sources and triangulation will proceed iteratively to try to reduce the RMS below RMS_TOL. In practice, this iteration seldom improves things due to the nature of the method and the quality of the input data. Setting a higher RMS_TOL is usually the only way to overcome this affine transformation determination error.

Increasing both RMS_TOL and SEL_MIN will allow a poorer quality preastrometric fit to continue through the pipeline, where the final solution may or may not be of good quality.


After the gross, linear corrections have been made, the reference and extracted sources can be associated using associate. associate has really only one parameter to help improve the precision of the solution. This is the distance within which objects will be associated, and are represented by the two parameters ISO_COLOR_TOL and INTER_COLOR_TOL.


The definitions and optimizations of these parameters was described in §[highrms] above. Repeating, INTER_COLOR_TOL is for associations between sources in different catalogs (e.g., extracted and reference catalogs), ISO_COLOR_TOL is for associations between sources in the same catalog (e.g., a joined extracted catalog). Setting these to lower values can result in a more precise fit, but should be used with care.


A 2-dimensional illustration of mapping of observed sky to idealized sky. The lowest plane (x,y) is the observed sky, and the middle plane (\(\zeta\),\(\eta\)) is the representation of the ideal sky mapped from a tangential (Gnomonic) projection denoted by TAN, the upper-most curved plane. The vertical line represents the radial direction with respect to the detector.


The PDEG parameter describes the polynomial degree used to map the observed sky, the pixel image, denoted by (x,y) to the idealized sky denoted by (\(\zeta\),\(\eta\)), see Fig. [astrom_mapping]. The required number of associations increases exponentially with degree. Also, the spatial uniformity of the associations becomes more critical with degree. PDEG is applicable for both single-chip and overlap solutions. When in overlap, however, the FDEG parameter will affect the solution as well.

The FDEG parameter is a list that describes how the mapping of the PDEG degree polynomial occurs from pointing to pointing. The first value in the list maps linear terms (order 1), the second, quadratic terms (order 2), etc. Only the first 3 can ever be changed. Based on the value of each list element, the polynomial coefficents of different pointings can be mapped to each other linearly (FDEG index 1), quadratically (FDEG index 2), etc., or held constant (FDEG index 0). For example, in the default case:

FDEG = [1, 0, 0]

indicates all first order terms will be mapped linearly between pointings and all higher order terms will be held constant. Similar to PDEG, as FDEG’s total value increases, so increases the number of associations and spatial uniformity required to converge.

For single chip fields, it is unlikely that a PDEG \(>\) 3 will result in a proper fit [1]. To enhance the number of associations over an area of one chip, multiple dithered observations should be used. This enhances both the number and spatial uniformity and allows greater PDEG and FDEG values to be used successfully. See for how to solve astrometry for dithered observations.

[1]Indeed, the number of values stored in the database (PV matrix coefficients) are currently only enough to properly store a solution of PDEG \(=\) 3.