ixpepolarization help file

NAME

ixpepolarization -- Calculates overall Stokes parameters for a user-defined region.

USAGE

ixpepolarization.py infile1 infile2 infile3 regfile outfile t_lo t_up pi_lo pi_up modfact1 modfact2 modfact3 weight_scheme color clobber

DESCRIPTION

ixpepolarization computes the overall Stokes parameters Q and U for a sky region defined by the user (e.g., using the display program ds9) using the selected weighting scheme over a user-defined time interval and a user-defined PI energy range. The program outputs a display region file to indicate the polarization position angle on the sky computed from the Q and U. If the region file contains sub-regions, then polarization magnitudes and angles will be computed for each sub-region. Additionally, the program outputs a FITS that contains a separate HDU for each input file, each containing rows for each sub-region with the Q, U, Q std error, U std error, Number of events, Minimum detectable polarization (MDP99), polarization magnitude, polarization angle, and the computed modulation factor.

The tool requires at least one input IXPE event FITS file (infile1, infile2, or infile3), and up to two additional IXPE event FITS files (infile1, infile2, infile3), an optional sky region file (regfile), optional time interval (t_lo, t_up), optional energy bounds (pi_lo, pi_up), optional user-defined modulation factor files corresponding to each input file (modfact1, modfact2, modfact3), an optional Stokes parameter weighting scheme (weight_scheme), an optional output region line color (color), and an optional output file name base for the output FITS polarization data and region files. The default is to compute the Stokes parameters from all events in the file.

It is highly recommended that a region file be provided to ixpepolarization. From the Stokes parameters Q and U, the polarization fraction and the position angle of the polarization vector are also computed. The output region file includes the original defined region(s) and an additional line region for each, which indicate the magnitude and orientation of the polarization vector.

PARAMETERS

infile1* (str): Input FITS EVENTS file.
infile2 (str): Optional second input FITS EVENTS file.
infile3 (str): Optional third input FITS EVENTS file.
regfile (str): Path to ASCII region definition file. (default: -, which is no region file)
t_lo (str): ISOT date/time of lower time bound. (default: -, which is t_lo = TSTART)
t_up (str): ISOT date/time of upper time bound. (default: -, which is t_up = TSTOP)
pi_lo (str): Lower PI bound for event filtering. (default: -, which is pi_lo = TLMIN = 0)
pi_up (str): Upper PI bound for event filtering. (default: -, which is pi_up = TLMAX = 374)
modfact1 (str): Modulation factor CALDB file used to process infile1. (default: -, meaning file is looked up in CALDB from DU, filter, and weighting scheme)
modfact2 (str): Modulation factor CALDB file used to process infile2. (default: -, meaning file is looked up in CALDB from DU, filter, and weighting scheme)
modfact3 (str): Modulation factor CALDB file used to process infile3. (default: -, meaning file is looked up in CALDB from DU, filter, and weighting scheme)
weight_scheme (str): Weighting scheme for polarization calculation, may be "unweighted" (or "u"), "simple" (or "s"), or "neff" (or "n"). (default: "neff")
color (str): Polarization vector display color. (default: green)
outfile (str): Path to output file. (default: is none)
clobber (Boolean): Flag to overwrite existing output fits and region files. (default: no)

EXAMPLES

BUGS

LAST MODIFIED

May 2023