Regrid an event file to a different tangent point
reproject_events infile outfile match [aspect] [random] [geompar] [verbose] [clobber]
`reproject_events' changes the sky coordinate tangent point in an event file.
There are two primary modes of operation:
- the easy version in which the new sky coordinates are evaluated assuming the old aspect solution was correct, and
- the serious version in which the user supplies a new aspect solution and the sky coordinates are calculated from scratch, independent of the original aspect solution.
It is also possible to run the tool with both a matchfile and a list of aspect files provided.
The first version (with "match=matchfile" and "aspect=none") is helpful in preparing to merge event lists with slightly different aimpoints.
The second version (with "match=none" and "aspect=@aspectfiles") is helpful when you need to fix an old event list which was processed with a bad aspect solution, and you have somehow obtained (or hacked together) a new aspect solution file.
Each event in the input file is copied to the output. If aspect=none, its sky pixel coordinates are recalculated by evaluating the corresponding celestial coordinates using the old sky pixel values and the coordinate system in the header, then calculating new sky pixel coordinates using the tangent point from the match file (or the tangent point values explicitly supplied in the parameter string, see examples). Note that this won't give you good results if the positions in the file were wrong to start with, but it's fine if you want to say "make this event file compatible with that one".
If an aspect solution file, or stack of aspect solution files, is supplied in the aspect parameter, the new focal plane DETX,DETY and sky X,Y pixel coordinates are calculated from the CHIPX, CHIPY coordinates using the aspect solution. The DETX,DETY depend on the SIM offsets, which change with time due to telescope bending and which are provided in the aspect solution file as determined from observations of the instrument fiducial lights. The X,Y are calculated from DETX,DETY using the telescope pointing direction supplied in the aspect file. If a match parameter is supplied, the X,Y are evaluated relative to the specified match tangent point; if match=none, the original tangent point in the input file is used.
With match=filename and aspect=@aspectfiles
In this mode, rather than reprojecting the existing sky(X,Y) coordinates, the tool begins at the chip coordinates, recomputes the detector coordinates and then uses them to computer a new sky(X,Y).
Special Case: No Input Time Column
If the input event file does not have a time column, reproject_events takes the time range covered by the aspect solution (intersected with GTIs from the match file) and shifts and expands it to cover the time range in the background dataset. Then a random time within the range of the background data subspace is selected and assigned to the event. Note that they time is not recorded in the output file; it is only used for the reprojection. This allows users to reproject the ACIS blank-sky background event files, which do not contain TIME information.
Running the Tool Twice
If the tool is run on an event file which was created by reproject_events, the aspect solution file should be provided in the aspect parameter. Otherwise, the second projection may fail because of the changes that reproject_events makes in trying to go from sky to celestial coordinates with the reprojected WCS, and then celestial to sky with the matched WCS. If you provide the aspect solution file, the tool starts at chip coordinates and goes forward, which works.
Solar System Objects
reproject_events is *not* meant to be used on solar system objects to remove orbital motion. The sso_freeze tool should be used for this purpose
reproject_events acis0474.fits new0474.fits aspect=asol0474.fits match=none
Reapplies the aspect solution to an event file.
reproject_events acis0474.fits new0474.fits aspect=none match=acis1055.fits
Regrids the sky pixel coordinates of file 0474 to match the tangent point of file acis1055.fits.
reproject_events acis0474.fits new0474.fits aspect=asol0474.fits match=acis1055.fits
As with the previous example, but this time we also use the aspect solution to recalculate the focal plane (DETX,DETY) coordinates and improve the sky pixel calculation.
reproject_events acis0474.fits new0474.fits aspect=asol0474.fits match="98.9430 -75.2317" random="0"
Regrids the sky pixel coordinates of file 0474 to match the given RA and Dec in degrees, using the aspect solution to improve the DET and SKY coordinate systems. The 0.5-pixel randomization is applied, using the TIME value of each event as the randomization seed.
reproject_events "blank_sky.fits" bkgrd_my_obs.fits my_obs.fits aspect=my_obs.aspect random=0
Regrids the blank sky pixel coordinates of blank_sky.fits to match the tangent point of file my_obs.fits. The aspect file provides the aspect solution for the events. This reprojection is particularly useful for the case where diffuse emission covers the CCD so that a separate background local to the observation can not be obtained. A description of the use of blank sky observations is available at: https://cxc.harvard.edu/ciao/threads/acisbackground/.
reproject_events @input.lis @output.lis aspect=none match=acis1055.fits
Regrids the sky pixel coordinates of each file listed in input.lis to match the tangent point of file acis1055.fits. No aspect files used in this case.
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=no)
Input dataset/block specification
Input event filename.
Parameter=outfile (file required filetype=output stacks=no)
Output dataset filename.
Parameter=match (file required filetype=input default=none)
Coordinate system to match to. Can be (1) a filename, in which case the coordinate system in the file is used; (2) "none", in which case the coordinate system in the input file is used (useful when reapplying a new aspect file); (3) a pair of numbers separated by space or comma, interpreted as the new tangent point RA and Dec in degrees.
Parameter=aspect (file not required filetype=input stacks=yes)
Aspect file, value can be "none" or a stack.
The aspect solution files for Chandra have names like pcadNNNasol1.fits. There may be more than one asol1 file for an observation, in which case use an ascii file asol.lis in which each line is the name of one of the asol1 files and set "firstname.lastname@example.org".
If present, the program uses the aspect file stack to recalculate the DETX,DETY and X,Y values. DETX,DETY (focal plane coordinates) are calculated using the fiducial light-derived SIM offsets to determine the position of the mirror relative to the chips, and the PIXLIB parameters to determine the locations of the chips on the SIM. X,Y (sky pixel coordinates) are then calculated from DETX,DETY using the RA, Dec and roll for the appropriate event time and the grid point specified by the "match" parameter.
Parameter=random (integer not required default=-1)
Random seed for 0.5-pixel randomization.
Any positive integer value is allowed. Also, random = 0 will use the time taken from the system clock, and random = -1 will disable randomization.
The CXC standard data processing (SDP) applies the EDSER sub-pixel algorithm to event locations; this option is not currently available in reproject_events. User should be aware of this limitation when comparing the output of this tool to data produced by the standard pipeline.
Parameter=geompar (file default=geom)
The name of the Pixlib Geometry parameter file.
Parameter=verbose (integer not required default=0 min=0 max=5)
Controls screen output information, value is 0 (no info) to 5 (most info).
Parameter=clobber (boolean not required default=no)
Overwrite output if it exists? (yes/no)
The range of the X and Y columns - the TLMIN/TLMAX keyword values for each column - are increased to match the min and max values in the reprojected output. This addresses the problem where data are being mosaiced such that the new X and Y values exceed the standard limits (eg for ACIS these go from 0.5 to 8192.5 in both X and Y).
See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.
Refer to the CIAO bug pages for an up-to-date listing of known issues.