/ ciao4.16 / ahelp / reproject_aspect.html

Jump to: Description · Examples · Parameters · Changes in CIAO 4.15 · Bugs · See Also

AHELP for CIAO 4.16

reproject_aspect

Synopsis

Modify aspect solution file RA, Dec, and roll or updfile WCS to minimize position differences between two source lists.

Syntax

reproject_aspect  infile refsrcfile updfile outfile [wcsfile] [logfile]
[radius] [residlim] [residtype] [residfac] [method] [clobber] [verbose]

Description

reproject_aspect compares two sets of source lists from the same sky region. If three or more sources are found to be a close match in position, reproject_aspect will update either an aspect solution file or the WCS of a FITS image or table file to minimize position differences between the input (infile) sources and the reference (refsrcfile) sources. Options allow the user to specify how close sources from each list must be to each other to be considered as possible matches (radius) and to limit the acceptable error between reference source positions and updated input source positions (residlim, residtype and residfac).

WCS parameters specifying a tangent point must be provided. This can be done by specifying either a FITS image or table file containing a WCS in the wcsfile input parameter. Alternately, if wcsfile is left blank, first the input and then the reference source file will be checked for a WCS. The first one found will be used. When a wcsfile is specified, it should contain a WCS that identifies a tangent point that is relatively close to the sources to be matched.

If updfile is an aspect solution file, changes are applied to the input RA, Dec, and roll columns and a new aspect solution file (outfile) is output with these columns modified. If updfile contains an image or table with a WCS ("EQPOS" for images, "EQPOS" or "EQSRC" tables), changes are applied to the WCS elements within the same file.

reproject_aspect is a script which runs two tools: wcs_match and wcs_update. These two tools may also be run individually instead of through reproject_aspect, allowing for slightly more flexibility.

Update Calculation Controls

reproject_aspect calculates a transformation matrix which minimizes (in a least squares sense) the error between tangent plane projections of the reference sources and the transformed input sources. With method="rst" (rotate, scale, translate), the transformation matrix specifies a 2-D translation, a rotation about the tangent point, and a scale factor. With method="trans" (translate only), the transformation matrix only includes a translation. Applying this matrix to the input sources results in the best attempt at aligning the reference and transformed input source positions.

A transformation matrix is initially calculated using data from all matched input and reference source positions (source pairs). The transformation matrix is then applied to the input source positions and the updated positions are compared to the positions of the reference sources. The differences between these source positions (the residuals) are used to determine whether the transformation matrix is sufficient, or whether certain source pairs should be excluded (e.g., mismatched sources) and the transformation calculation repeated. Running reproject_aspect with verbose=1 shows details of the residuals during successive calculations of the transformation matrix.

If residlim is greater than 0, the transform calculation stops when the largest residual is smaller than residlim. If the largest residual is greater than residlim, the source pair with this residual is excluded from the matched set of sources and the transformation matrix is recalculated. This continues iteratively until all residuals are less than the specified value of residlim.

If residfac is greater than 0, the residual-to-source pair position error ratio is examined. This ratio is determined by dividing a residual by the sum in quadrature of its reference and input source position errors. A comparison is made to residfac and if residfac is exceeded, the source pair with the largest ratio is excluded from the matched set of sources and the transformation matrix is recalculated. This continues iteratively until residfac is no longer exceeded. Two different comparisons can be made with residfac. If residtype = 0, the transform calculation stops when all ratios are less than residfac. If residtype = 1, the calculation stops when the average of all ratios is less than residfac.

Examples

Example 1

reproject_aspect infile=src1.fits refsrcfile=src2.fits
wcsfile=image.fits updfile=src1_asol.fits outfile=new_asol.fits
radius=2 residlim=1 verbose=1

Match sources from src1.fits and src2.fits that are within 2 arcseconds. Eliminate any source pairs with a position difference greater than 1 arcsecond from the transform calculation. Apply RA, Dec and roll modifications to src1_asol.fits values and output result in new_asol.fits. Use the WCS provided in image.fits. Display the intermediate and final position errors for all matched sources (verbose=1).

Example 2

reproject_aspect infile=src1.fits refsrcfile=src2.fits
updfile=src1_image.fits outfile="" residlim=0 residtype=1 residfac=2.5
verbose=1

Match sources from src1.fits and src2.fits. Do not use the absolute value of the residual to limit source pairs to include in the transform calculation (residlim set to 0), but do use the residual-to-source pair position error ratio to limit source pairs in the transform (residfac > 0). Eliminate source pairs with the largest ratios until the average of all ratios (residtype=1) is less than 2.5. Use the transform values to update the WCS in src1_image.fits. Since no separate wcsfile is provided, use the WCS in src1.fits, or in src2.fits if one is not found in src1.fits. Display the intermediate and final position errors for all matched sources (verbose=1).

Example 3

reproject_aspect infile=src1.fits refsrcfile=src2.fits
updfile=src1_asol.fits outfile=new_asol.fits residlim=0 residtype=0
residfac=1.5

Match sources from src1.fits and src2.fits. Do not use the absolute value of the residual to limit source pairs to include in the transform calculation (residlim set to 0), but do use the residual-to-source pair position error ratio to limit source pairs in the transform (residfac > 0). Eliminate source pairs with ratios larger than 1.5 (residtype=0). Apply RA, Dec and roll modifications to src1_asol.fits values and output result in new_asol.fits. Use the WCS present in src1.fits, and if one is not present, look for one in src2.fits.

Example 4

reproject_aspect infile=src1.fits refsrcfile=src2.fits
wcsfile=image.fits updfile="src1_asol_a.fits,src1_asol_b.fits"
outfile="src1_asol_a_new.fits,src1_asol_b_new.fits"

Match sources from src1.fits and src2.fits, using the WCS information from image.fits for the transformation. Two aspect solutions files are given in the updfile parameter, so two new aspect solution files (src1_asol_a_new.fits and src1_asol_b_new.fits) will be created with the RA, Dec, and roll changes applied.

Example 5

unix% cat optical.dat
#RA RA_ERR DEC DEC_ERR
246.8147625543 1.6359623089102e-05 -24.55049151732 1.7897900878694e-05
246.8861311412 1.3138809151769e-05 -24.55677209605 9.1986712043024e-06
246.8794236861 1.4607012701617e-05 -24.56762593616 1.0942152091076e-05
246.8747572911 2.1446620706911e-05 -24.56022597575 1.4661890684664e-05
...
unix% reproject_aspect infile=chandra_src.fits refsrcfile=optical.dat
wcsfile=chandra_image.fits method=trans updfile=chandra_asol.fits
outfile=chandra_asol_new.fits

The input reference source list can be a simple ASCII file with RA and DEC columns. If RA_ERR and DEC_ERRs are present, then they will be used in the computation of the residfac test.

This example also illustrates using the method parameter to force the algorithm to compute a translation-only solution.

Parameters

name	type	ftype	def	min	max	units	reqd	stacks
infile	file	input					yes
refsrcfile	file	input					yes
updfile	file	input					yes	yes
outfile	file	output					yes	yes
wcsfile	file	input					no
logfile	file	output	STDOUT				no
radius	real	input	12			arcseconds	no
residlim	real	input	5			arcseconds	no
residtype	integer	input	0				no
residfac	real	input	2.0				no
method	string	input	rst				no
clobber	boolean	input	no				no
verbose	integer	input	0	0	5		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

File with input sources.

The source list must contain the columns RA and Dec in decimal degrees (not sexigesimal) format. The source list can be generated by CIAO (e.g. the Detect tools), created with another data analysis program, or be obtained from a catalog. The source list from the archive (src2.fits file) is not accurate enough for use with this tool.

With method="rst", at least 3 input sources must be found to be a match for 3 reference sources. With method="trans", only 1 source must match between the input and reference source lists. residfac parameter will only be useful if columns RA_err and Dec_err are present in infile and refsrcfile.

Parameter=refsrcfile (file required filetype=input)

File of reference sources

At least 3 input sources must be found to be a match for 3 reference sources. residfac parameter will only be useful if columns RA_err and Dec_err are present in infile and refsrcfile.

Matching Other Wavelengths

The reference source list can be in any format supported by the CXC Datamodel. This includes various ASCII format that make it easy to input data from catalogs of sources derived from different wavelengths. See the dmascii help file for more information on supported ASCII formats.

Parameter=updfile (file required filetype=input stacks=yes)

Input file to be updated, either asol or FITS image or table.

If this input file is an asol file, the RA, Dec., and roll columns of each row will be updated and written to the outfile. If this input file is either a FITS image or table, the WCS in this file will be updated.

If there are multiple aspect solution files for the observation, all the files may be given as a stack in this parameter; see "ahelp stack" for more information. In this case, a stack of output files containing the same number of elements must be supplied in the outfile parameter.

Parameter=outfile (file required filetype=output stacks=yes)

Output aspect solution file.

This file is created when the input file is an aspect solution file. All data are copied from the aspect solution file and the RA, Dec, and roll are modified by values calculated by reproject_aspect. If the input file is not an aspect solution file, outfile must still be specified but is not used and can be blank.

If a stack of aspect solution files is given in the updfile parameter, a stack of output filenames containing the same number of elements must be supplied in this parameter. See "ahelp stack" for more information on working with stacks of files.

Parameter=wcsfile (file not required filetype=input)

World Coordinate System (WCS) file.

The WCS file must contain WCS coordinate transform data with a tangent point near the sources of the infile and refsrcfile. It can be either a FITS image file with a "EQPOS" WCS, or a FITS table file with "EQPOS" or "EQSRC" WCS. A WCS file must be specified unless a WCS is present in either the input or reference source file. If a wcsfile is provided and a WCS is present in either source file, the WCS from the wcsfile will be used.

Parameter=logfile (file not required filetype=output default=STDOUT)

Debug log file.

Allowable values are either a filename - to send the output to a given file - or one of stdout or STDOUT, which sends the information to the standard output (normally the screen).

Parameter=radius (real not required filetype=input default=12 units=arcseconds)

Source match radius

Source positions from the two source files can only match each other if they are no farther apart than the value specified as the source match radius. Only a single reference source can be within the source match radius of a input source, and only a single input source can be within the source match radius of a reference source. If multiple sources are found in either case, the source pair is not used to calculate the transform.

Parameter=residlim (real not required filetype=input default=5 units=arcseconds)

Residual Limit

After the transform is calculated and initially applied to the input source positions, if the largest source pair position error exceeds the value of residlim, then that pair is eliminated from the transform calculation and the calculation is repeated. This process of eliminating the source pair with the largest residual and repeating the calculation continues until all remaining source pair position errors are less than the residlim value.

Set residlim to 0 to disable this feature and prevent source pairs from being removed based on absolute residual value. Residlim takes precedence over residfac if both are nonzero.

Parameter=residtype (integer not required filetype=input default=0 units=)

Residual ratio limit type

Two different options can be used to eliminate source pairs from the transform calculation when the residual ratio limit factor (residfac) is specified. If residtype is set to 0, residfac is interpreted as an upper limit on the residual-to-source pair position error ratio. Any source pairs with ratios above residfac will be eliminated from the transform calculation. If residtype is set to 1, residfac is interpreted as an upper limit on the average of all ratios. Source pairs with the highest ratios will be incrementally removed from the transform calculation until the average of all ratios drops below residfac.

Parameter=residfac (real not required filetype=input default=2.0 units=)

Residual ratio limit factor

After the transform is calculated and initially applied to the input source positions, if either the largest residual-to-source pair position error ratio exceeds the value of residfac (when residtype=0), or the average of all ratios exceeds the value of residfac (when residtype = 1) then the source pair with the largest ratio is eliminated from the transform calculation and the calculation is repeated. This process of eliminating a source pair and repeating the calculation continues until the appropriate ratio test is met.

Set residfac to 0 to disable this feature and prevent source pairs from being removed based on the residual-to-source pair position error ratio. Residlim takes precedence over residfac if both are nonzero.

Parameter=method (string not required filetype=input default=rst units=)

Method used to generate transformation matrix

The transformation matrix used to align input source positions with reference source positions can be caculated in two ways. If method='rst', the transformation matrix includes a rotation, scale factor, and translation. To limit the transformation matrix to provide only a translation, method can be set to 'trans'.

Parameter=clobber (boolean not required filetype=input default=no)

Overwrite existing asol output dataset with same name?

Parameter=verbose (integer not required filetype=input default=0 min=0 max=5)

Level of debug detail.

Increasing amounts of debug information are printed to "logfile" as the value of verbose is increased from 0 to 5. Setting verbose=1 shows details of the source pair errors after applying the transform to the input source positions.

Changes in CIAO 4.15

The header of the new file (the outfile parameter) will now contain the parameter settings for this tool. It can be retrieved with the dmhistory tool or the get_history_records method of the pycrates python library.

Bugs

Caveats

Using method=rst (default) may change the pixel size/scale which introduces problems for some down-stream analysis.

When running reproject_aspect with the default parameter setting: method=rst (rotate, scale, translate), it may compute an astorometric solution that includes a change to the pixel size (scale). Typically this is then applied to the Level2 event file. The updated event list may then have a non-standard pixel size which is propagated into images created by binning the event file.

However, some data products such as exposure maps, are always created using the standard pixel sizes. This mismatch in pixel size can then trigger errors or unexpected results when trying to use the two data products together.

There are two types of errors. (1) Using the same grid to bin the event file and create the exposure map may result in different image axis lengths; typically they will be off by 1 pixel. (2) Attempting to use the exposure map as a Datamodel mask() filter, will result in an error since it requires the mask and the image being filtered to have the same pixel size; this type of filtering is done with merge_obs when creating a combined PSF map.

Workaround:

Users should only run reproject_aspect using method=trans which forces the astrometric solution to only include linear translations.

Using method=rst (default) may result in a non-physical astrometric solution.

When running reproject_aspect with the default parameter setting: method=rst (rotate, scale, translate), it may compute an astorometric solution that is non-physical. Examples of non-physical solutions include large translation offsets which are compensated for with large rotation offsets in the opposite direction. The Correcting Absolute Astrometry thread has example of how to interpret wcs_match's output transform file. Given the accuracy of the Chandra pointing, offsets larger than a few pixels are highly suspicious. In addition, since the aspect camera field of view is much larger than the instruments' field of view, rotation adjustments larger than a fraction of a degree are unlikely physical.

This is caused by having relatively few matching sources and/or all the matching sources are clustered together on one side of the tangent point. Mathematically, to use method=rst requires at least 3 source pairs, however, in practice users should have dozens of matching sources dispersed throughout the entire field of view. With few sources, the under-constrained "rst" solution may be mathematically optimal, but physically impossible.

Workaround:

Users should only run reproject_aspect using method=trans which forces the astrometric solution to only include linear translations.