# HOW-TO Inspect an astrometric solution¶

Astrometric solutions are created as a result of the AstrometricParametersTask and the GAstromTask. To determine the quality of the astrometric solution, several methods can be used. The primary method is to inspect the astrometric solution with the AstrometricParameters inspect() method. An alternate qualitative method is to view a calibrated catalog overlayed on the image.

Please Note, not all inspection methods are currently available in the AWBASE checkout, but are in the current checkout. These methods have been noted. To use them, see the Getting Started section in the for details on using a different checkout.

## AstrometricParameters and GAstrometric inspect() methods¶

### The Plots¶

An AstrometricParameters object can be inspected by plotting the residuals of the solution versus themselves and versus position. This is exactly what the inspect() method does. For a single chip (AstrometricParameters), one figure is created with 5 panels. These five panels plot (from top down):

• DDEC versus DRA with line-connected histograms of their distributions
• DRA versus RA
• DDEC versus DEC
• DRA versus XPOS
• DDEC versus YPOS

where DRA is $$RA_{reference} - RA_{extracted}$$ in arc-seconds, DDEC is $$Dec_{reference} - Dec_{extracted}$$ in arc-seconds, RA is in degrees, DEC is in degrees, XPOS is the X pixel position of the extracted source, and YPOS is the Y pixel position of the extracted source.

Also included at the top of the figure is the DATE_OBS of the source ReducedScienceFrame; the mean RA () and mean Dec (), both calculated from the distribution plotted; the number of pairs plotted–the same as the number of pairs used in the astrometric solution (N); the chip name of the source ReducedScienceFrame (CHIP:); the mean RA residual (), mean Dec residual (), and sample standard deviation of each distribution (values following the +-), all based on the distribution plotted; the RMS (root-mean-square) value of the distance of the residual pairs with respect to the DDEC/DRA origin (0,0); and the maximum distance of any residual pair from the DDEC/DRA origin (Max). There are also RMS and N values within the first panel. Their significance will be clear when seen in the context of the multi-chip solution.

The multi-chip case (GAstrometric) plots exactly the same information, but with multiple pointings per chip, one figure per chip. Each pointing has a different color to distinguish it from the other pointings. Also, the first panel includes the RMS and N values for each pointing individually. The values above the first panel are all calculated with respect to ALL the data plotted.

In addition to the multi-chip reference residuals, an entire set of overlap residuals figures is created. Instead of DRA being $$RA_{reference} - RA_{extracted}$$, it is $$RA_{1} - RA_{2}$$, both extracted from their respective frames. $$RA_{1}$$ and $$RA_{2}$$ will never be from the same chip and pointing. The Dec values are similar. There is no other difference between the previous multi-reference figures and these multi-overlap figures.

Lastly, two more figures are created: all reference residuals and all overlap residuls. These figures simply show all the data from all the chips of their respective data set. Each pointing is color-coded identically to the individual chip figures. The reference figure in this multi-chip, multi-pointing case is directly equivalent to the single-chip figure.

### The Methods¶

There are currently two ways to run the inspect method for either case. The most straight-forward of these is to simply set the inspect switch in either the AstrometericParametersTask or in the GAstromTask when either is run:

awe> task = AstrometricParametersTask(red_filenames=['Sci-USER-WFI-#877-red-536
64.5.fits'],
...                                   inspect=1, commit=0)

or

...                     inspect=1, commit=0)


In the other method, an AstrometricParameters or GAstrometric object is instantiated from the database, and its inspect() invoked:

awe> ap = (AstrometricParameters.reduced.filename == 'Sci-USER-WFI-#877-red-536
64.5.fits')[0]
awe> DataObject(pathname=ap.residuals).retrieve()
awe> ap.inspect()

or

awe> gas = (GAstrometric.gasslist.filename == 'GAS-2df_I_5-53760.5784035')[0]
awe> DataObject(pathname=gas.residuals).retrieve()
awe> gas.inspect()


### Modifying the Default Output¶

The inspection figures described above are displayed to the screen and written to PNG files. This behavior can be modified, but explaination of these techniques is beyond the scope of this HOW-TO. For the latest documentation for attempting these modifications, simply view the online help (docstrings) of the inspect method(s) and plot class(es) used to create these figures:

awe> help(AstrometricParameters.inspect)
awe> from astro.plot.AstrometryPlot import AstromResidualsPlot
awe> help(AstromResidualsPlot)


## Applied inspection methods¶

The previous sections described the built-in inspection methods showing predicted results of the derived solutions in AstrometricParameters and GAstrometric objects. This section describes extended inspection methods of the derived solutions applied to RegriddedFrames and CoaddedRegriddedFrames. All these inspection methods deliver a plot in the same 5-panel form as the built-in inspect() methods, but using different source catalogs for the residuals. Also, the details and latest usage information can be found in the methods’ docstrings accessed via the help() command.

### AstrometricParameters plot_residuals_to_usno() method¶

• Temporarily in current checkout only.

This plot displays source position residuals between the corrected catalog positions performed by LDAC or sources positions extracted from a RegriddedFrame corrected with the same parameters and the USNO-A2.0 reference catalog. Setting the source parameter to ‘solution’ or ‘applied’ selects either the catalog used in the solution or a catalog extracted from a RegriddedFrame to which the solution parameters have been applied, respectively.

### AstrometricParameters plot_residuals_to_regrid() method¶

• Temporarily in current checkout only.

This plot displays source position residuals between the corrected catalog positions performed by either LDAC or SExtractor and sources extracted from a RegriddedFrame corrected with the same parameters. Setting the derived_type parameter to ‘solution’ or ‘sextractor’ selects either the catalog used in the solution or a catalog extracted from a ReducedScienceFrame by SExtractor to which the solution parameters have been applied to the header, respectively.

• Temporarily in current checkout only.

This plot displays source position residuals between a given RegriddedFrame and all other overlapping frames, all that participate in a CoaddedRegriddedFrame. Setting the use_coadd switch (use_coadd=True) displays source position residuals between the CoaddedRegriddedFrame and all RegriddedFrames that went into its creation. It plots a given RegriddedFrame source position against the average source position from the CoaddedRegriddedFrame.

## Image inspection method¶

• Temporarily in current checkout only.

The multi-purpose inspect() method used by all frames inheriting from BaseFrame can create a plot that can be used to display the qualitative residuals on the pixel level by using either difference images or multi-color images using the same mechanism for inspecting individual frames. The detailed usage of this method can be found in . The general idea for this purpose is to inspect one RegriddedFrame, setting the compare parameter (compare=True) and specifying the other RegriddedFrame with the other parameter. The routine automatically compares only the overlapping region of the two frames.

awe> reg0 = RegriddedFrame(pathname=filename0)
awe> reg1 = RegriddedFrame(pathname=filename1)
awe> reg0.inspect(compare=True, other=reg1)  # common region of reg0-reg1


## Overlaying a calibrated catalog¶

This method requires a RegriddedFrame obtained from the RegridTask. It needs to be first loaded into SkyCat:

awe> q = RegriddedFrame.reduced.filename == 'filename.reduced.fits'
awe> os.system('skycat %s' % (q[0].filename))


First, set the desired cut level via the “Auto Set Cut Levels” button, or with “View:Cut Levels…”. Next, overlay the catalog by choosing “Data-Servers”, then “Catalogs”, then “USNO at ESO” [1]. In the dialog that comes up, choose “Search” and all the sources known to the USNO survey will be plotted in circled cross-hairs. They can now be compared directly with the sources on the underlying frame. When inspecting the corellation, remember that the USNO catalog is accurate only to about 0.3 arc-sec.

If the RegriddedFrame was not created from the ReducedScienceFrame, it will need to be regridded with the RegridTask before the inspection above can be carried out. This is because there exist projection effects (distortions) in the ReducedScienceFrame. The RegridTask can be run via the DPUor locally as shown in the example below:

awe> dpu.run('Regrid', i='WFI', d='2001-01-01', f='#845', o='Science2', C=0)

awe> regrid = RegridTask(date='2000-01-01', chip='ccd50', filter='#845',
...                      object='Science2', commit=0)
awe> regrid.execute()


## Examine the AstrometricParameters values¶

To look at the AstrometricParameters for a given ReducedScienceFrame, the AstrometricParameters objects of interest must first be located in the database:

awe> q = AstrometricParameters.reduced.filename == 'WFI.2001-02-16T01:42:31.289
_1.calibrated.fits'
awe> len(q)
1

awe> dt = datetime.datetime(2005,1,1)
awe> q  = (AstrometricParameters.instrument.name == 'WFI')
awe> q &= (AstrometricParameters.filter.name == '#845')
awe> q &= (AstrometricParameters.chip.name == 'ccd50')
awe> q &= (AstrometricParameters.creation_date > dt)
awe> len(q)
1199


The first example shows the a query for an AstromtricParameters object by its source ReducedScienceFrame’s filename. The second shows a more general search based on instrument, filter, chip, and date.

NOTE: Dates and times in the Astro-WISE database environment are generally in the form of datetime objects. Therefore, when querying for them, a datetime object must be used. The main exception is the select() method, but this method is not universally implemented at this time.
 [1] There are other catalogs available, but the USNO catalog was used in the astrometric solution and should fit well.