Synopsis
Regrid an event file to a different tangent point
Syntax
reproject_events infile outfile match [aspect] [random] [geompar] [verbose] [clobber]
Description
`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.
With match=filename
The first version (with "match=matchfile" and "aspect=none") is helpful in preparing to merge event lists with slightly different aimpoints.
With match=none
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
Examples
Example 1
reproject_events acis0474.fits new0474.fits aspect=asol0474.fits match=none
Reapplies the aspect solution to an event file.
Example 2
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.
Example 3
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.
Example 4
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.
Example 5
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/.
Example 6
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.
Parameters
| name | type | ftype | def | min | max | reqd | stacks |
|---|---|---|---|---|---|---|---|
| infile | file | input | yes | no | |||
| outfile | file | output | yes | no | |||
| match | file | input | none | yes | |||
| aspect | file | input | no | yes | |||
| random | integer | -1 | no | ||||
| geompar | file | geom | |||||
| verbose | integer | 0 | 0 | 5 | no | ||
| clobber | boolean | no | no |
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.
This parameter can be one of the following:
match parameter options
- a filename, in which case the coordinate system in the file is used.
- "none" or a blank/empty string, in which case the coordinate system in the input file is used (useful when reapplying a new aspect file).
- celestial coordinates (RA and Dec) to use as the new tangent plane location.
The celestial coordinate can be supplied in any of the following formats:
Allowed coordinate syntax
| Example |
|---|
| 12.34, -56.78 |
| 12.34 -56.78 |
| 12:34:56, -56:7:8 |
| 12 3 4 -56 7 8 |
| 12h 3m 4s -56d 7' 8" |
Note that double quotes, ", used for arcsec can be input but will be translated into a single quote when written to the parameter file due to limitations of the parameter file interface.
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 "aspect=@asol.lis".
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)
Column metadata
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).
Bugs
-
All events are lost after reprojection /
The tool needs one good time interval per chip -
If the subspaces of the two files don't match - e.g. observation A was taken with S5 and that chip wasn't used in observation B - all the events are dropped from the output file (not just those on the chip that's missing).
The bug may also be described as: the tool needs one good time interval (GTI) per chip, otherwise the time for the other CCDs is set to zero.
- No error message with invalid match value.
Setting the match parameter to an invalid RA/Dec (eg RA < 0 or Dec > 90 value does not trigger a warning and the tool will run to completion with undetermined results.
- Running the tool on a spatially filtered file does not update the "region" subspace.
-
The spatial filter is recorded in the file subspace, but it is not reprojected when reproject_events is run. When reproject_events changes the sky tangent point, the region in the subspace is "shifted" in the reference frame.
In many cases, users run into this problem when they do the following order of events:
- Use a spatial filter to select certain ACIS chips (e.g. just the ACIS-I array)
- Run reproject_events on the filtered event file
- Attempt to extract spectra with a source list.
The final output has zero exposure and/or empty GTIs because the source list and the initial, unshifted region filter (stored in the file subspace) don't intersect.
-
Workaround:
Use the DM subspace-editing capabilities to delete the filter specification written in the file subspace:
unix% dmcopy "reprojected_file.fits[subspace -sky]" reprojected_file_fix.fits
An alternative is to run reproject_events before applying any spatial filtering.
Caveats
- match parameter cannot take image as match input.
-
The match parameter does not accept images as input. The warning message
# reproject_events (CIAO 4.5): Error: failed to open match file foo.img
does not make this clear to users.
See Also
- tools::coordinates
- fine_astro, reproject_aspect, sso_freeze, wcs_match, wcs_update