Last modified: September 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/correct_periscope_drift.html
AHELP for CIAO 4.16

correct_periscope_drift

Context: Tools::Aspect

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.16.0 (December 2023) release

The script has been updated to support changes to Sherpa plotting in this release.

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