Synopsis
Filters input event file based on time spent in calibrated focal plane temperature ranges.
Syntax
acis_split_evt_by_fptemp infile outroot [mtlfile] [clobber] [verbose]
Description
This script automates the event filtering steps shown in the Extracting Spectra and Responses for ACIS Observations that Undergo Large Focal-plane Temperature Swings thread. The script will use the input event file to identify the set of mkacisrmf, i.e. the "P2_RESP" CALDB files. If there are multiple CALDB files, then the script will use the information in the headers of the "P2_RESP" calibration files to identify the calibrated focal-plane temperature ranges. The script constructs good time intervals based on the temperature ranges and FP_TEMP values stored in the mission time line file. For temperature ranges with non-zero good time, it will then filter the event file using those good time intervals. The output is a set of event files and a stack "list" file than can then be used with specextract to extract combined spectra.
Caveat
This script and the thread are not needed for most observations. Even if there is a significant temperature variation during an observation, most targets will not have enough counts to be able to differentiate between statistical uncertainty and temperature dependent calibration differences. Users should read the thread and associated documents carefully before using this script.
As of CIAO 4.18/CALDB 4.12.2, the only CCDs with temperature dependent RMF calibrations are ACIS 0, 1, 2,3, and 6. There is no temperature dependent calibrations available for the other CCDs. Therefore if your source is located on ACIS 4, 5, 7, 8 or 9, there is no reason to use this script.
Examples
Example 1
acis_split_evt_by_fptemp infile=primary/acisf30601N002_evt2.fits outroot=acisf30601N002 clob+
acis_split_evt_by_fptemp (13 April 2025)
infile = primary/acisf30601N002_evt2.fits
outroot = acisf30601N002
mtlfile = INDEF
clobber = yes
verbose = 1
mode = ql
FP_TEMP [K]: 165.96 - 178.16 : 0.00 [sec]
FP_TEMP [K]: 163.96 - 165.96 : 0.00 [sec]
FP_TEMP [K]: 161.96 - 163.96 : 1925.10 [sec]
FP_TEMP [K]: 159.96 - 161.96 : 3087.60 [sec]
FP_TEMP [K]: 157.96 - 159.96 : 3162.00 [sec]
FP_TEMP [K]: 155.96 - 157.96 : 3050.40 [sec]
FP_TEMP [K]: 153.96 - 155.96 : 4634.50 [sec]
FP_TEMP [K]: 152.96 - 153.96 : 1348.50 [sec]
Created the following event files:
acisf30601N002_161.96-163.96.evt
acisf30601N002_159.96-161.96.evt
acisf30601N002_157.96-159.96.evt
acisf30601N002_155.96-157.96.evt
acisf30601N002_153.96-155.96.evt
acisf30601N002_152.96-153.96.evt
Use '@acisf30601N002_evt.lis' to extract spectra and responses.
This example shows running the script with the event file for OBS_ID 30601 as input. The script used the event file to locate the set of P2_RESP CALDB files, extracted the FP_TEMP ranges, created good time intervals, and then filtered the event file into 6 segments consistent with the FP_TEMP ranges for the 6 non-zero good time intervals. The script was able to automatically locate the mission time line file (MTL) based on the MTLFILE keyword in the input event file.
The output list file, acisf30601N002_evt.lis, can then be used with spectract to create responses. For example:
specextract "@acisf30601N002_evt.lis[sky=region(source.reg)]" \ bkgfile="@acisf30601N002_evt.lis[sky=region(background.reg)]" \ ... combine=yes ...
Example 2
acis_split_evt_by_fptemp acisf00214N004_evt2.fits.gz out=obsid214
acis_split_evt_by_fptemp (13 April 2025)
infile = acisf00214N004_evt2.fits.gz
outroot = obsid214
mtlfile = INDEF
clobber = no
verbose = 1
mode = ql
# acis_split_evt_by_fptemp (13 April 2025): ERROR: P2_RESP files cannot be located in the CALDB for this event file
For OBS_ID 214 there are not P2_RESP calibration files. This observation was taken early in the mission and requires using the 'mkrmf' tool rather than the 'mkacisrmf' tool to create response matrix files (RMFs). There are no temperature dependent calibrations during this early mission time period.
Example 3
acis_split_evt_by_fptemp acisf00408N005_evt2.fits.gz out=obsid408
acis_split_evt_by_fptemp (13 April 2025)
infile = acisf00408N005_evt2.fits.gz
outroot = obsid408
mtlfile = INDEF
clobber = no
verbose = 1
mode = ql
FP_TEMP [K]: 165.96 - 178.16 : 0.00 [sec]
FP_TEMP [K]: 163.96 - 165.96 : 0.00 [sec]
FP_TEMP [K]: 161.96 - 163.96 : 0.00 [sec]
FP_TEMP [K]: 159.96 - 161.96 : 0.00 [sec]
FP_TEMP [K]: 157.96 - 159.96 : 0.00 [sec]
FP_TEMP [K]: 155.96 - 157.96 : 0.00 [sec]
FP_TEMP [K]: 153.96 - 155.96 : 0.00 [sec]
FP_TEMP [K]: 152.96 - 153.96 : 1465.20 [sec]
# acis_split_evt_by_fptemp (13 April 2025): ERROR: Only 1 FP_TEMP range has good time. No need to run this script.
For OBSID 408, the focal plane temperature was steady and falls within a single calibration focal plane temperature range. In this case, there is no reason to split the event file into multiple segments as the error message indicates.
Parameters
| name | type | ftype | def | min | max | reqd |
|---|---|---|---|---|---|---|
| infile | file | input | yes | |||
| outroot | file | output | yes | |||
| mtlfile | file | input | INDEF | |||
| clobber | boolean | no | ||||
| verbose | integer | 1 | 0 | 5 |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input)
Input event file
Parameter=outroot (file required filetype=output)
Output directory+root file name
The script will create output files with name like
${outroot}_${lo}-${hi}.evt
Where ${lo} is lower limit on the temperature range and ${hi} is the upper limit on the temperature range.
The script will also create an list file
${outroot}_evt.lis
Which can be used by tools like specextract to extract spectra and responses.
Parameter=mtlfile (file filetype=input default=INDEF)
Input Mission Time Line (MTL) file
The script uses the "FP_TEMP" column in the mission time line file to create good time intervals using the dmgti tool.
If the mtlfile value is blank or "INDEF", then the script will use the "MTLFILE" keyword in the header of the input event file to try to locate the mission time line file. It will look in several directories relative to the event file.
Parameter=clobber (boolean default=no)
Overwrite existing files?
Parameter=verbose (integer default=1 min=0 max=5)
Output verbosity.
The default verbosity value of 1 prints status messages as the script runs. Higher verbosity settings print the commands that are being run. Setting verbose=0 turns off most of the screen output (some output is currently unavoidable).
Background Information
For most of the Chandra mission the ACIS focal plane temperature has remained steady at/around -120C. However as the mission has progressed it has become difficult to maintain a steady temperature and at the same time preserve observing efficiency. As a result, the ACIS focal plane temperature is now allowed to vary during an some observations. Changes in focal plane temperature affect the spectral re-distribution; that is warmer temperatures produce wider observed spectral lines. The response matrix, RMF, has been calibrated for several temperature ranges for certain CCD_IDs (chips).
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 - such as how to ensure that the parameter file is available.
Bugs
There are no known bugs for this tool.