NAME

USAGE

DESCRIPTION

ixpeproduct is a wrapper for a number of HEASoft FTOOLS. It extracts spectra from source and background regions specified in [srcregfile] and [bgregfile] files, respectively, and light curves with HEASoft's extractor from Level 2 event FITS files located in the directory given by the indir parameter. Light curve time bin size is specified by [binlc] and bins whose exposure is less than [lcthresh] times the binsize are ignored. ixpeproduct also calculates Stokes parameters and their derivatives using ixpepolarization. ixpeproduct also generates (or retrieves) the corrected instrument response files corresponding to each of the Stokes spectra extracted from the source region(s) specified in the [srcregfile] file using ixpecalcarf. The resulting background and response file names are added to the BACKFILE, RESPFILE, and ANCRFILE header keywords in the spectral files as appropriate. ixpeproduct also generates XSPEC and PyXspec command files named [xcmname] that help simplify initializing spectral analysis sessions. All products are placed in the directory specified by the outdir parameter.

ixpeproduct is used to prepare data for spectropolarimetric analysis using, e.g., the data analysis package XSPEC or its python-based version, PyXspec, to perform model-independent statistical analysis of Stokes parameters and their derivatives using ixpepolarization, and to generate tables (light curves) of the time history of the source intensity. Because of IXPE's imaging capability, typical usage is to first define a source spatial region in sky coordinates and, optionally, a nearby background region of interest using a data visualization application such as ds9. Then, ixpeproduct is used to generate data products and instrument response files for these regions correctly accounting for, e.g., spacecraft dither, data weighting scheme, and the latest calibration database (CALDB) products. See ixpecalcarf for further details of response file generation, extractor for details of the data extraction, and ixpepolarization for details of the derivation of Stokes parameters and related quantaties.

ixpeproduct is highly versatile. Typically, a source region file, [srcregfile], is specified and the contents of the IXPE archive have been obtained from the HEASARC and placed in the indir directory. The archive contains the level 2 event list and level 1 housekeeping attitude files needed for ixpeproduct to extract spectra and light curves and to generate instrument response files. When [srcregfile] is specified, pointing map files(s) are used to generate the instrument response files. ixpeproduct will generate pointing maps automatically generated using the ixpeexpmap FTOOL, unless the user provides the [pmapfiles] parameter specifically. Alternatively, for point-like, on-axis sources, the user can choose to specify the [radius] of a circular region that ixpeproduct will generate. If neither [srcregfile] file nor [radius] are specified, ixpeproduct will generate products using data from the entirety of each detector unit.

PARAMETERS

indir="" [pathname]

Name of the path to Level 2 event lists and attitude housekeeping files of an IXPE observation retrieved from HEASARC. For instance, "/path_to_ixpe_data/01000001". Required.

outdir="" [pathname]

Name of the path to store the output files generated. For instance, "/path_to_ixpe_data/01000001/products". Required.

(weight=0) [integer]

Choice of weighting scheme to apply to extracted spectra. Available options are 0 (unweighted), 1 (neff weighting), and 2 (simple weighting). Used by extractor, ixpepolarization and ixpecalcarf. More information on IXPE event weighting can be found in Sec. 3.2 of the IXPE Quick Start Guide.

(srcregfile=-) [filename]

Path to the ds9-style region file defining the region(s) for filtering source events. Used by extractor, ixpepolarization and ixpecalcarf.

(bgregfile=-) [filename]

Path to the ds9 region file defining the region(s) for filtering background events. Used by extractor and ixpecalcarf.

(radius=-1) [real]

Radius of the region of interests to be used for creating a circular DS9 region, for filtering source events. Used for creating a source region file in lieu of [srcregfile]. Only applicable for on-axis point-like sources.

(en_lo=2.0) [real]

Lower Energy Bound for filtering events (not applied to spectral extraction). Used by ixpepolarization.

(en_up=8.0) [real]

Upper Energy Bound for filtering events (not applied to spectral extraction). Used by ixpepolarization.

(backrej=no) [boolean]

If true (yes), particle background events flagged in the Level 2 event files will not be included in extracted data products. Currently, this is only effective for observations obtained after 2024/12/18. The particle background flags will be included for all observations after reprocessing as planned by the IXPE SOC.

(pmapfiles="") [filename]

Names of pointing map files given as a comma-separated list or within a text file given by @filename. Pointing maps may be generated using ixpeexpmap given a valid region file and Level 1 attitude file(s). See the ixpeexpmap help page for details. Used by ixpecalcarf.

(evtfiles="") [filename]

Names of event list files given as a comma-separated list or within a text file given by @filename. Needed if Level 2 event FITS files in path indir do not conform to standard IXPE naming syntax.

(pmapseg=yes) [boolean]

Process pointmap on a per-segment basis (recommended for observations processed by IXPE SOC before 2025/01/01).

(pi_lo=-1) [integer]

Lower PI bound for filtering events. Overrides en_lo if pi_lo > 0. Used by ixpepolarization.

(pi_up=-1) [integer]

Upper PI bound for filtering events. Overrides en_up if pi_up > 0. Used by ixpepolarization.

(binlc=100.0) [real]

Time bin size for light curve creation with extractor. See HEASoft extractor documentation for details. Used by extractor.

(lcthresh=0.2) [real]

Fractional time bin size below which the data are ignored. See HEASoft extractor documentation for details. Used by extractor.

(xcmname="ixpexspec.xcm") [string]

Optional name of the xspec file to be generated. The accompanying PyXspec command file name is _pyxipexspec.xcm. Used by extractor.

clobber="no") [boolean]

Flag to overwrite existing output fits and region files.

EXAMPLES

The following ixpeproduct command is an example for extracting spectra, and polarization measurements for IXPE Obsid 03250701. The output files will be saved under ixpeproduct_03250701 (the product folder will be generated automatically if necessary).

ixpeproduct indir=./03250701 outdir=ixpeproduct_03250701 backrej=yes srcregfile=./3c273_ixpe_src.reg \ bgregfile=./3c273_ixpe_bg.reg weight=1 clobber=yes backrej=yes

BUGS

SEE ALSO

ixpecalcarf, extractor, ixpepolarization

LAST MODIFIED