clean_spec

Synopsis

Mask out events from unrelated astrophysical sources in HETG grating spectra observed in fields with multiple, bright X-ray sources. This tool is currently only used with crisscross output files.

Syntax

clean_spec  infile conf_file [spec_root] arf_file [resp_dir] [clobber]
[verbose]

Description

CrissCross and its helper tool clean_spec allow users to analyze Chandra High Energy Transmission Grating (HETG) spectra that are extracted from a field of view with multiple other astrophysical X-ray sources. The HETG instrument will disperse events onto the ACIS CCDs from all sources in a field of view and if there are several sufficiently-bright X-ray sources, the dispersed spectra can overlap on the detector with a potential to 'confuse' the extracted spectra. Confusion is a term used here for special scenarios where standard HETG spectral extraction of a source may erroneously assign events (counts) from a different astrophysical source in the field of view to the extracted source. This can result in events from an unrelated astrophysical source 'confusing' the spectrum of an extracted source.

CrissCross is used to identify where spectral confusion occurs for a list of input sources (or a single source) and generates 'confusion tables' which identify the wavelength in each source's spectrum that are likely to include X-ray events from unrelated field astrophysical sources. The user can then run clean_spec to deal with all events from the source spectrum in the wavelength range where this confusion occurs. The CrissCross helper program clean_spec uses the CrissCross output confusion tables and input HETG PHA spectra to generate 'cleaned' spectra and matching ARFs where these events are removed. CrissCross and clean_spec are especially useful for crowded X-ray fields with multiple observations such as stellar clusters.

Try the jupyter notebook tutorial!

Users are encouraged to try CrissCross and clean_spec using the jupyter notebook tutorial. As shown in the tutorial, Sherpa provides a useful interface for checking the results of the confusion assessment by viewing HETG spectra before and after cleaning. More examples can also be found in the crisscross ahelp page.

To utilize clean_spec, users are expected to have already extracted HETG source spectra from the observation of interest using standard grating CIAO tools and run crisscross to produce confusion tables for each HETG spectrum. Please see the crisscross ahelp page for more info.

The examples below highlight some of the ways to use clean_spec with associated crisscross output files. Please see the crisscross ahelp for creating confusion tables.

Examples

Example 1

unix% punlearn chandra_repro
unix% chandra_repro indir=3 outdir=3/custom_hetg_extraction
root=tet1oriE \
tg_zo_position='83.8156671,-5.3861617'
unix% punlearn crisscross
unix% crisscross
infile=3/custom_hetg_extraction/tet1oriE_repro_evt2.fits \
outdir=cc_singlesrc_outdir main_list=all_srcs.fits
single_src_pos='83.8156671,-5.3861617' \
single_src_root='tet1oriE' mode=a
unix% punlearn clean_spec
unix% clean_spec
infile=3/custom_hetg_extraction/tet1oriE_repro_pha2.fits \
conf_file=cc_singlesrc_outdir/output_dir_obsid_3/confusion_output_files/
table_fits_data/confused_tet1oriE_consolidated_obsID_3.fits \
spec_root=tet1oriE resp_dir=3/custom_hetg_extraction/tg mode=a

Run crisscross to assess confusion for a single source and clean the spectrum with clean_spec. To run this example verbatim, see the crisscross ahelp page for creating the necessary main_list 'all_srcs.fits' file. This example utilizes the chandra_repro tg_zo_position parameter which allows users to pick an RA and DEC to extract a specific source's HETG spectra. This runs the standard tg_extract tools and produces PHA files and ARFs and RMFs. The chandra_repro tg_orders parameter can be used to specify more orders than the default +1/-1. Users can assess confusion for a single source by utilizing the single_src_pos parameter. Running crisscross with a single RA and DEC will create a single confusion table for that source as long as it matches a source in the main_list input file. The main_list sources still need to be provided as they are the sources of potential confusion. See the jupyter notebook tutorial for more info about comparing cleaned vs uncleaned spectra.

Example 2

unix% punlearn clean_spec
unix% clean_spec
infile=3/custom_hetg_extraction/tet1oriE_repro_pha2.fits \
conf_file=cc_singlesrc_outdir/output_dir_obsid_3/confusion_output_files/
table_fits_data/confused_tet1oriE_consolidated_obsID_3.fits \
spec_root=tet1oriE_ex2 mode=a

The clean_spec tool will automatically find the associated ARFs when provided with an HETG pha2 spectrum and the arf_file parameter left blank. It will produce cleaned spectra for all the orders associated with the found ARF files. Note, even though the default PHA2 HETG files include all 12 orders, chandra_repro only produces arfs for +1/-1 orders by default unless the chandra_repro tg_orders parameter is used. The clean_spec tool will produce a new 'cleaned' pha2 file that includes all 12 orders but ONLY the orders with matching arfs will be cleaned. If the arfs are not correctly found, the 'resp_dir' parameter can be set to point to the arfs.

Example 3

unix% punlearn stk_build
unix% stk_build infile=
'3/custom_hetg_extraction/tg/tet1oriE_repro_heg_p1.arf \
3/custom_hetg_extraction/tg/tet1oriE_repro_heg_m1.arf' outfile=arf.lis
clobber=yes
unix% punlearn clean_spec
unix% clean_spec
infile=3/custom_hetg_extraction/tet1oriE_repro_pha2.fits \
conf_file=cc_singlesrc_outdir/output_dir_obsid_3/confusion_output_files/
table_fits_data/confused_tet1oriE_consolidated_obsID_3.fits \
spec_root=tet1oriE_heg_spec arf_file=@arf.lis mode=a

To produce cleaned spectra for only specific orders such as heg +1 and heg -1 clean_spec can be used with a stack file of arfs and the input PHA2 spectrum. This also works with an individual arf (order) without stacks.

Parameters

name	type	ftype	def	reqd	stacks
infile	file	input		yes	no
conf_file	file	input		yes	no
spec_root	string			no
arf_file	file	input		yes	yes
resp_dir	string			no
clobber	boolean		no
verbose	integer		1

Detailed Parameter Descriptions

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

The PHA1 or PHA2 HETG spectrum file to be cleaned.

This file is typically produced via chandra_repro or running tg_extract and associated ciao tools for extracting HETG spectra. Note, many HETG PHA2 spectra include all 12 orders but only the orders with matching arfs will be cleaned. The output cleaned PHA2 file may include all 12 orders even if only some of the orders have been cleaned. The remaining orders will not be modified.

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

Confusion fits table produced by the ciao tool crisscross.

This table is the output of the ciao tool crisscross and indicates the portions of a spectrum with confusion. Each crisscross table is unique to a particular source and obsID and its output depends on the parameters used when running crisscross.

Parameter=spec_root (string not required)

A root name for naming the output cleaned spectra.

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

Chandra HETG ARF file(s) associated with each HETG order.

If this parameter is left blank then the ARFs associated with the PHA1 or PHA2 file will be looked-up using keywords in the PHA2 file. Only ARFs identified with a matching order will be used to clean the spectra. If a stack is used then only orders matched to the included ARFs will be cleaned even though all spectra may be included in the cleaned output PHA2 file.

Parameter=resp_dir (string not required)

Path to ARFs associated with the input PHA1 or PHA2 HETG spectrum file.

A path to the ARFs can be provided if the auto-lookup feature does not automatically identify the ARFs or if the user has ARFs located in a non-default location.

Parameter=clobber (boolean default=no)

Specifies if an existing output file should be overwritten.

Parameter=verbose (integer default=1)

Specifies the level of verbosity (0-5) in displaying diagnostic messages.

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

See the bug pages on the CIAO website for an up-to-date listing of known bugs.

Refer to the CIAO bug pages for an up-to-date listing of known issues.