/ ciao4.16 / ahelp / tgsplit.html

Jump to: Description · Examples · Parameters · Caveats · Background and BACKSCAL · ONTIME, LIVETIME, EXPOSURE keywords · Changes in the scripts 4.12.2 (April 2020) release · Changes in the scripts 4.12.1 (December 2019) release · Changes in the scripts 4.10.3 (October 2018) release · Changes in the scripts 4.9.2 (April 2017) release · Change in script 4.8.4 (September 2016) release · Changes in September 2015 Release · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.16

tgsplit

Context: Tools::Gratings

Synopsis

Split a TYPE:II grating PHA file into several TYPE:I files

Syntax

tgsplit  infile arffile rmffile outroot [verbose] [clobber]

Description

Chandra grating spectrum files are by default created in 'TYPE:II' format. This is a standard FITS format in which each row has a different spectrum representing the grating arm and order. This format is generally easy to read into Sherpa, ISIS and XSPEC, however, some generic utilities cannot process such files.

tgsplit takes a TYPE:II pha file as input and converts it to a stack of TYPE:I files. If a stack of ARF and RMF are provided, it also associates the correct response file to each individual TYPE:I spectrum based on matching the metadata in the various files.

Grating TYPE:II pha files created with either tgextract or tgextract2 can be split using this script.

This script can also be used to split the background spectrum from a TYPE:I grating pha file if the background is stored in a column.

Examples

Example 1

% tgsplit acis_pha2.fits outroot=myobs

tgsplit
          infile = acis_pha2.fits
         arffile = 
         rmffile = 
         outroot = myobs
         verbose = 1
         clobber = no
            mode = ql

Created source spectrum: myobs_leg_m3.pha[SPECTRUM]
Created source spectrum: myobs_leg_m2.pha[SPECTRUM]
Created source spectrum: myobs_leg_m1.pha[SPECTRUM]
Created source spectrum: myobs_leg_p1.pha[SPECTRUM]
Created source spectrum: myobs_leg_p2.pha[SPECTRUM]
Created source spectrum: myobs_leg_p3.pha[SPECTRUM]
Created background spectrum: myobs_leg_m3_bkg.pha
Created background spectrum: myobs_leg_m2_bkg.pha
Created background spectrum: myobs_leg_m1_bkg.pha
Created background spectrum: myobs_leg_p1_bkg.pha
Created background spectrum: myobs_leg_p2_bkg.pha
Created background spectrum: myobs_leg_p3_bkg.pha

This command splits the input TYPE:II pha file into a series of source and background spectrum files -- one each for every row in the input file.

The example is for an ACIS+LETG observation which contains 1 grating arm (leg) and 6 grating orders: plus and minus each first, second, and third order. The output is 12 TYPE:I pha files: 6 source and 6 background.

Each source specturm contains an updated BACKFILE keyword that points to the correct background file. By default, the background is loaded automatically with the source file in Sherpa, ISIS, and XSPEC.

Example 2

% tgsplit "acis_pha2.fits[tg_m=-1,1]" outroot=myobs

Same as above, but select only plus and minus first order spectra.

Example 3

% tgsplit acisf05422_repro_pha2.fits "tg/*.arf" "tg/*.rmf" HETG_obs
clob+

tgsplit
          infile = acisf05422_repro_pha2.fits
         arffile = tg/*.arf
         rmffile = tg/*.rmf
         outroot = HETG_obs
         verbose = 1
         clobber = yes
            mode = ql

Created source spectrum: HETG_obs_heg_m3.pha[SPECTRUM]
Created source spectrum: HETG_obs_heg_m2.pha[SPECTRUM]
Created source spectrum: HETG_obs_heg_m1.pha[SPECTRUM]
Created source spectrum: HETG_obs_heg_p1.pha[SPECTRUM]
Created source spectrum: HETG_obs_heg_p2.pha[SPECTRUM]
Created source spectrum: HETG_obs_heg_p3.pha[SPECTRUM]
Created source spectrum: HETG_obs_meg_m3.pha[SPECTRUM]
Created source spectrum: HETG_obs_meg_m2.pha[SPECTRUM]
Created source spectrum: HETG_obs_meg_m1.pha[SPECTRUM]
Created source spectrum: HETG_obs_meg_p1.pha[SPECTRUM]
Created source spectrum: HETG_obs_meg_p2.pha[SPECTRUM]
Created source spectrum: HETG_obs_meg_p3.pha[SPECTRUM]
Created background spectrum: HETG_obs_heg_m3_bkg.pha
Created background spectrum: HETG_obs_heg_m2_bkg.pha
Created background spectrum: HETG_obs_heg_m1_bkg.pha
Created background spectrum: HETG_obs_heg_p1_bkg.pha
Created background spectrum: HETG_obs_heg_p2_bkg.pha
Created background spectrum: HETG_obs_heg_p3_bkg.pha
Created background spectrum: HETG_obs_meg_m3_bkg.pha
Created background spectrum: HETG_obs_meg_m2_bkg.pha
Created background spectrum: HETG_obs_meg_m1_bkg.pha
Created background spectrum: HETG_obs_meg_p1_bkg.pha
Created background spectrum: HETG_obs_meg_p2_bkg.pha
Created background spectrum: HETG_obs_meg_p3_bkg.pha

In this ACIS+HETG example, there are 12 spectrum in the TYPE:II pha file which is split into 24 individual TYPE:I files. Since the stack of ARF and RMF files is provided, they are matched to the appropriate order and grating arm and the source spectrum file is updated to point to the correct location.

% dmlist HETG_obs_heg_m3.pha header,clean | grep FILE
BACKFILE             HETG_obs_heg_m3_bkg.pha        Background file name
CORRFILE             none                           Correction file name
RESPFILE             tg/acisf05422_repro_heg_m3.rmf Grating Redistribution (LSF) file n
ANCRFILE             tg/acisf05422_repro_heg_m3.arf Ancillary response file name (ARF)
AREASCAL                     1.0                    Area scaling factor, if ANCRFILE needs a correc

Example 4

% tgsplit acisf05422_repro_pha2.fits "tg/*.arf" "tg/*.rmf" tg/HETG_obs
clob+

Same as above but outroot is now the same as the root name of the ARF and RMF files. In this case the directory name is omitted from the TYPE:I file keywords

% dmlist tg/HETG_obs_heg_m3.pha header,clean | grep FILE
BACKFILE             HETG_obs_heg_m3_bkg.pha        Background file name
CORRFILE             none                           Correction file name
RESPFILE             acisf05422_repro_heg_m3.rmf    Grating Redistribution (LSF) file name
ANCRFILE             acisf05422_repro_heg_m3.arf    Ancillary response file name (ARF)
AREASCAL                     1.0                    Area scaling factor, if ANCRFILE needs a correc

Example 5

% tgsplit obs_7435_tgid_4053/heg_1.pha.gz
obs_7435_tgid_4053/heg_1.arf.gz \
obs_7435_tgid_4053/heg_1.rmf.gz tgcat_obs7435 clob+

In this example a single TYPE:I PHA file from the TGCat catalog is split into its source and background files. The ARF and RMF files are provided so that the ANCRFILE and RESPFILE keywords get updated correctly.

The file 'obs_7435_tgid_4053/heg_1.pha.gz' does not appear to be a TYPE:II spectrum.  The 'COUNTS' column is not an array column.
Created source spectrum: tgcat_obs7435_heg_p1.pha[SPECTRUM]
Created background spectrum: tgcat_obs7435_heg_p1_bkg.pha

Parameters

name	type	ftype	def	min	max	reqd	stacks
infile	file	input				yes	no
arffile	file	input				yes	yes
rmffile	file	input				yes	yes
outroot	file	output				yes	no
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=no)

Input Chandra grating pha file.

The TYPE:II pha files created by tgextract or tgextract2 can be split using this tool.

It may also be a single TYPE:I pha file that contains both the source and background spectra (ie created by dmtype2split or retrieved from TGCat).

Parameter=arffile (file required filetype=input stacks=yes)

Input stack of grating ARF files.

If provided, the meta-data in the ARF files will be examined and used to match to the correct grating arm and order. The file name of the ARF will be added to the source spectrum file (ANCRFILE).

The script only uses the arffile specified. If it cannot find the ARF for some grating arm/order combinations, but can for others it will do so without complaint. Likewise, the script will not complain if there are ARFs supplied that do no match any of the grating spectra.

The ARFs are necessary to match the RMFs.

Parameter=rmffile (file required filetype=input stacks=yes)

Input stack of grating RMF files.

If provided, the meta-data in the RMF files will be examined and used to match to the correct grating arm and order. The file name of the RMF will be added to the source spectrum file (RESPFILE) .

The script only uses the rmffile specified. If it cannot find the RMF for some grating arm/order combinations, but can for others it will do so without complaint. Likewise, the script will not complain if there are RMFs supplied that do no match any of the grating spectra.

The ARFs are necessary to match the RMFs.

Parameter=outroot (file required filetype=output stacks=no)

Output root file name

The output root file name. The output names will look like ${outroot}_${part}${order}.pha where ${part} will be 'heg', 'meg', or 'leg' and ${order} is the signed order number 'p' for plus side and 'm' for the minus side.

The background will are named ${outroot}_${part}${order}_bkg.pha

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

Multiple Sources

The tool will likely not find the correct ARF and RMF file if the spectrum was extracted from multiple sources. The 'TG_SRCID' column in the input PHA file cannot be used to match the response files.

Non-Chandra / Non-Gratings

The tool only knows about Chandra datasets. For generic conversion of a TYPE:II file to TYPE:I please see the dmtype2split tool, which is also used by this script.

dmextract can produce TYPE:II pha file appropriate for non-grating analysis. Those files are not compatible with this script.

Zero Order

The grating 0 order is not extracted in the same way as the dispersed spectrum; it is (typically) not stored in a TYPE:II pha file.

Background and BACKSCAL

The UP and DOWN background in the tgextract output are summed to create the TYPE:I file. Similarly the BACKSCUP and BACKSDN are added to set the BACKSCAL keyword.

ONTIME, LIVETIME, EXPOSURE keywords

For ACIS gratings data, the ONTIME, LIVETIME, and EXPOSURE keywords should be the average value of the per-chip values rather than simply the value for the aimpoint-chip. This script will update the keywords appropriate for the set of chips each order falls on.

Changes in the scripts 4.12.2 (April 2020) release

Fix problem with TYPE:II PHA files created with the tgextract2 tool. The background BACKSCAL column was incorrectly copied from the source region.

Changes in the scripts 4.12.1 (December 2019) release

A bug fix to work with TYPE:II PHA files created with the tgextract2 tool.

Changes in the scripts 4.10.3 (October 2018) release

Recognizes when outroot is a directory and adjusts file names so they no longer begin with an underscore or period.

Changes in the scripts 4.9.2 (April 2017) release

Updated to copy the [REGION] extension to the individual TYPE:I pha files which are needed by mkgrmf.

Change in script 4.8.4 (September 2016) release

Fix for tgextract2 output format when using error=gehrels.

Changes in September 2015 Release

Added a work around for ACIS continuous clocking (CC) mode datasets that prevented the ARF and RMF from being automatically associated with the corresponding PHA files.

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.