acis_clear_status_bits

Context: Tools::ACIS

Synopsis

Clear (set to 0) ACIS status bits before reprocessing with acis_process_events

Syntax

acis_clear_status_bits evtfile

Description

This script clears out several ACIS status bits that are set by the Chandra pipeline and that need to be cleared before using acis_process_events. This is needed to support the bad-pixel/afterglow pipeline. Please see the Reprocessing Data to Create a New Level=2 Event File thread for more information.

Unlike most CIAO scripts and tools, this script does not have a parameter file as there is only one argument, the file name of the event file to change. This change happens "in place", so ensure you either have a backup copy of the event file, or can re-create it, before using this script.

Example

unix% acis_clear_status_bits evt1.fits
unix% dmkeypar evt1.fits CLSTBITS echo+
11111111011000000011111111000001

The status bits are cleared from the file evt1.fits. The CLSTBITS keyword is described in the "What bits are cleared?" section below.

What bits are cleared?

The ACIS status column is a 32-bit value. This scripts clears - sets to 0 - bit numbers 1 to 5, 14 to 20, and 23. The numbering here matches that used in the Status dictionary entry on the CIAO web site.

The scripts adds the CLSTBITS keywords to the file, with a value showing the bit mask that was and-ed against each entry (so 0 means the bit was cleared and 1 means that the initial setting is retained). The example above shows the value used for this keyword.

Changes in the scripts 4.6.6 (September 2014) release

Invalid CLSTBITS keyword on 32-bit machines

The CLSTBITS keyword is now correct on 32-bit machines. This problem only affected this header keyword; the STATUS column changes were correct.

The invalid keyword setting was:

CLSTBITS= '-100111111100000000111111' / 0 means clear STATUS bit

which is now:

CLSTBITS= '11111111011000000011111111000001' / 0 means clear STATUS bit

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.

Bugs

Files must have read and write access.

This tool requires that the files have read and write access. It will quietly fail if it is not.

In addition to normal file system permisison one may set with chmod, it also requires the file be uncompressed and not have any filters applied.

# OK
unix% /bin/ls -l acis_evt.fits
-rw-r--r--  1 user group  5209 Jan 31 08:20 acis_evt.fits
unix% acis_clear_status_bits acis_evt.fits

# BAD
unix% acis_clear_status_bits acis_evt1.fits.gz
unix% acis_clear_status_bits acis_evt1.fits[ccd_id=3]
unix% chmod a-w acis_evt.fits
unix% acis_clear_status_bits acis_evt.fits

To verify that the tool has worked properly, users can check for the CLSTBITS keyword. If it was not present in the input file then it will be present in the output file if the tool ran correctly.

unix% dmkeypar acis_evt.fits CLSTBITS echo+
11111111011000000011111111000001