Synopsis
Correct a Chandra aspect solution for temporal drift calculated from a fit of the drift in the sky positions of the events in a supplied circle region.
Syntax
correct_periscope_drift infile evtfile outfile [corr_plot_root] [x] [y] [radius] [src_min_counts] [corr_poly_degree] [verbose] [clobber]
Description
Thermal cycling on the spacecraft can result in an apparent temporal drift of the sky position of an X-ray source during an observation. This appears as a drift of up to about 0.5 arcsec in X-ray event sky X, Y coordinates over time. Because of the thermal variation time scales, this effect is usually most prominent in long observations (more than about 50 ksec).
As of DS 8.4, a drift correction is applied to the aspect solution using the periscope gradients telemetry. However, temporal drifts have continued to increase with thermal variation of the spacecraft. Therefore the Aspect team suggests that to accomplish science related to sub-arcsec source structure, users should follow this thread to correct residual drift induced by the periscope. This requires a relatively bright, on-axis source (within a few arcmin off-axis angle) to perform a "self-calibration" of the aspect solution.
This tool takes as input a source aspect solution and event files and returns a new/corrected aspect solution that may be applied to the events to correct residual temporal drift.
WARNING: do not apply without review
The tool creates four plots as part of the output (they end in _yag.png and _zag.png). These must be reviewed before the correction is used, to ensure that the automatic fitting process has not produced invalid results.
Example
% correct_periscope_drift pcadf537654279N001_asol1.fits.gz acisf16659N001_evt2.fits.gz driftcorr_asol1.fits x=4133.76 y=4078.74 radius=6 verbose=2
Running: correct_periscope_drift
version = 6 Feb 2020
with parameters:
infile=pcadf537654279N001_asol1.fits.gz
evtfile=acisf16659N001_evt2.fits.gz
outfile=driftcorr_asol1.fits
verbose=2
and ASCDS_INSTALL is /soft/ciao-4.12
------------------------------------------------------------
Fitting a line to the data to get reduced stat errors
Fitting a polynomial of degree 2 to the data
Fitting a line to the data to get reduced stat errors
Fitting a polynomial of degree 2 to the data
------------------------------------------------------------
Fit results
Events show drift range of 0.24 arcsec in yag axis
Max absolute correction of 0.14 arcsec for yag axis
Events show drift range of 0.20 arcsec in zag axis
Max absolute correction of 0.11 arcsec for zag axis
------------------------------------------------------------
Writing out corrected aspect solution file to driftcorr_asol1.fits
You *must* review the following plots before using this correction:
corr_fit_yag.png
corr_data_yag.png
corr_fit_zag.png
corr_data_zag.png
Adding HISTORY record for correct_periscope_drift (6 Feb 2020)
Adding history to driftcorr_asol1.fits
Running tool dmhistory using:
>>> dmhistory driftcorr_asol1.fits correct_periscope_drift action=put
Parameters
| name | type | ftype | def | min | max | reqd | stacks |
|---|---|---|---|---|---|---|---|
| infile | file | input | yes | no | |||
| evtfile | file | input | yes | no | |||
| outfile | file | output | yes | no | |||
| corr_plot_root | string | output | no | no | |||
| x | float | 1 | |||||
| y | float | 1 | |||||
| radius | float | 0 | |||||
| src_min_counts | float | 250 | 0 | ||||
| corr_poly_degree | integer | 2 | 1 | 8 | |||
| verbose | integer | 1 | 0 | 5 | |||
| clobber | boolean | no |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=no)
Input Chandra aspect solution.
Parameter=evtfile (file required filetype=input stacks=no)
Input Chandra event file (evt1 or evt2).
The event file should have been made with/processed with the aspect solution supplied with infile (evtfile ASOLFILE header key value should match infile)
Parameter=outfile (file required filetype=output stacks=no)
Output filename for corrected aspect solution file
Parameter=corr_plot_root (string not required filetype=output stacks=no)
Output prefix for fit and data plots.
The output prefix for fit and data plots. The output names will look like ${corr_plot_root}_fit_${axis}.png and ${corr_plot_root}_data_${axis}.png where ${axis} will be 'yag' or 'zag'.
Parameter=x (float min=1)
Sky X position of center of circle region used to extract events to fit correction.
Parameter=y (float min=1)
Sky Y position of center of circle region used to extract events to fit correction.
Parameter=radius (float min=0)
Radius in pixels of circle region used to extract events to fit correction.
Parameter=src_min_counts (float default=250 min=0)
Minimum number of counts required in extracted source region (below which the tool will complain and not fit).
Parameter=corr_poly_degree (integer default=2 min=1 max=8)
Degree of polynomial used in the fit model to fit and correct drift in the two Aspect Camera axes.
Parameter=verbose (integer default=1 min=0 max=5)
Amount of tool chatter level.
Parameter=clobber (boolean default=no)
Overwrite output files if they already exist?
Caveats
Bad fits
This tool provides output plots of the fits of the events. The user must evaluate those plots to determine if a correction is warranted and if the output fit is reasonable. This tool *should not* be blindly applied to observations.
Counts needed for good fit
The tool is not intended for short observations (less than 50ks) and will not work well for observations well without a bright point-like source.
Multiple aspect solutions files
This tool is only intended for observations with single aspect solution files.
Changes in the scripts 4.15.2 (April 2023) release
Updated to work when no DISPLAY environment variable is set.
Changes in the scripts 4.12.2 (April 2020) release
The script will now run when the verbose parameter is 0.
Changes in the scripts 4.11.4 (2019) release
Matlotlib support
The plots now use the chosen Sherpa plotting backend, rather than always using ChIPS. To use Matplotlib, change the plot_pkg line in your ~/.sherpa.rc file so that it reads:
plot_pkg : pylab
Note that making this change will also change any new Sherpa sessions to use Matplotlib!
Using Matplotlib rather than ChIPS, will allow the script to be run when there is no X Display, over a remote connection, or on recent macOS releases. It also means that the plot windows will no longer briefly appear on the screen when the script is run.
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.
See Also
- tools::aspect
- asp_offaxis_corr, asphist, dither_region
- tools::coordinates
- reproject_aspect, reproject_image, reproject_image_grid, sky2tdet
- tools::region
- skyfov