ixpecalcarf help file

NAME

ixpecalcarf -- Constructs an on-axis ARF or MRF from component files that correctly accounts for off-axis vignetting and source extraction radius.

USAGE

ixpecalcarf.py evtfile attfiles [radius] [specfile] [arfout] [resptype] [weight] [detfilter] [ox] [oy]
[vignfile] [reeffile] [uvfilt] [grfilt] [modfact] [qefile] [axeffa]
[arfin] [clobber]

ixpecalcarf.py evtfile regfile pmapfile [specfile] [arfout] [resptype] [weight] [detfilter]
 [vignfile] [reeffile] [uvfilt] [grfilt] [modfact] [qefile] [axeffa]
[arfin] [clobber]

ixpecalcarf.py evtfile offarcmin [radius] [specfile] [arfout] [resptype] [weight] [detfilter]
 [vignfile] [reeffile] [uvfilt] [grfilt] [modfact] [qefile] [axeffa]
 [arfin] [clobber]

DESCRIPTION

ixpecalcarf reads the components from the CALDB to construct on-axis instrument response files suitable for the observation date as determined by keywords in the header of the file given by evtfile. The response file type, MRF or ARF, is determined by the resptype parameter or from keywords in the file given by specfile. The transmission of the optional GRAY filter can be included by setting the detfilter parameter to 1. The weighting scheme is assigned by setting the weight parameter. The instrument response file is written to the value of arfout, if present, or to a file with a name determined from resptype and specfile or evtfile. If specfile is given, then the ANCRFILE keyword value in that file is updated to the name of this new instrument response file.

Optional corrections to the instrument response files include vignetting due to dithering, by specifying attfiles, and encircled energy fraction (EEF) due to the finite source extraction radius by specifying either radius or regfile. These corrections are based on the vignetting and EEF CALDB files and an exposure-weighted distribution of off-axis angle values.

Three different approaches are available for defining the off-axis angle distribution:

the user may specify a fixed off-axis angle value and a point-like region with the offarcmin parameter. The on-axis instrument response is obtained by setting offarcmin=0.
the user may specify the Level 1 attitude files by providing the attfiles parameter to calculate the off-axis angle distributions due to vignetting. In this case, an optional offset from the optical axis can be specified with the ox and oy parameters.
the user may specify a valid regfile parameter value to calculate the off-axis angle distribution using the pointing map values within the ds9 regions defined by regfile. The pointing map is specified by pmapfile, which is the output of a separate IXPE FTOOLS task, ixpeexpmap. A valid pmapfile parameter value must exist if regfile is given.

ixpecalcarf applies the vignetting correction to the on-axis response using the mirror vignetting file from CALDB (averaged over azimuthal angle and interpolated over off-axis angle and energy) to create a weighted vignetting correction vs. energy array. The EEF corrections can be enabled by providing a positive source extraction radius (radius in arcminute) or a regfile with only one circular region. For the EEF corrections, ixpecalcarf uses the same off-axis angle distribution with the radial EEF file from CALDB to create an EEF correction vs. energy array. Though rarely invoked, the user has the option to manually specify calibration files used by ixpecalcarf, including the transmission of the detector UV filter (uvfilt), transmission of the GRAY filter (grfilt), the detector modulation factor if calculating polarization response (modfact), the detector quantum efficiency (qefile), and the mirror axial effective area (axeffa). Vignetting and EEF can also be manually specified by vignfile and reeffile, respectively.

PARAMETERS

evtfile* (str): Input FITS Level 2 Event file, necessary for detector-specific keywords and the GTI information.
attfiles (str): Full path name of an input Level 1 attitude file. Or, a list of attitude files given as a comma-separated list or within a text file given by @filename. Used to determine the distribution of off-axis pointing angle. Not used if a regfile is provided or offarcmin >= 0, but required if offarcmin < 0. (default: none)
radius (float): Radius of circular source region in arc minutes. 0 indicates no aperture correction is to be applied. (default: 0)
detfilter (int): Detector filter. (0 = Open, 1 = Gray, default: 0)
specfile (str): Input FITS spectrum file. If not none, and its header has a valid ANCRFILE value, it will override resptype and arfin, and the content of ANCRFILE will be modified by ixpecalcarf. If the specfile's ANCRFILE value is not a valid file, ixpecalcarf will generated one and update the ANCRFILE with the name of the new response file. (none or path name, default: none)
regfile (str): Input DS9 region file. The off-axis observing angle distribution will be calculated for the region using the pmapfile. (none or path name, default: none)
pmapfile (str): Input pointing map file (which can be created by the ixpeexpmap tool). Used along with regfile to calculate the off-axis observing angle distribution for a source region. Overrides radius, ox, oy, offarcmin. (none or path name, default: none)
arfin (str): Input on-axis ancillary response CALDB file name, for backward compatibility only (see NOTE below). If used, overrides uvfilt, resptype, and weight. (none, caldb, or path name, default: none, indicating not used)
arfout (str): File name of output file, which is the ancillary response file of type resptype. If not specified, ixpecalcarf will save the output file automatically using the filename from evtfile or specfile with a different extension specified by resptype.
weight (int): For "mrf" files, the weighting scheme used for calculating Stokes parameters. (default: 1); 0 = unweighted, 1 = N-effective (neff), 2 = simple
resptype (str): Response function type. (arf or mrf, default: arf).
offarcmin (float): Fixed off-axis observing angle in arc minutes. If >= 0, overrides attfile. (< 0 to disable: default = -1.0, indicating disabled)
ox (float): X-axis offset in pixels of optical axis from the origin of the attitude TXYDZ column. (default: 0)
oy (float): Y-axis offset in pixels of optical axis from the origin of the attitude TXYDZ column. (default: 0)
clobber (Boolean): Overwrite existing output file? (default: no)

** The remaining parameters are path names. Most users will want to leave them as the default value "caldb".

vignfile (str): Path to the off-axis mirror vignetting CALDB file. (default: caldb, indicating lookup from CALDB)
reeffile (str): Path to the mirror radial encircled-energy CALDB file. (default: caldb, indicating lookup from CALDB)
uvfilt (str): Path to the detector UV filter CALDB file. ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)
grfilt (str): Path to the detector gray filter CALDB file. ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)
modfact (str): Path to the detector modulation factor CALDB file. ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)
qefile (str): Path to the detector quantum efficiency CALDB file. ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)
axeffa (str): Path to the mirror axial effective area CALDB file. ({none, caldb, or full path name} default: caldb, indicating lookup from CALDB)

NOTE

Support for "arfin" files is for backward compatibility only. Production of new on-axis arf files has ceased. Users are therefore encouraged to use the component files that make up the on-axis response which will continue to be updated through the remainder of the mission.

EXAMPLES

Case A: IXPE observations for a point source

Scenario 1: Calculate the corrected ARF and MRF for the on-axis point source with a 1 arcmin spectral extraction radius. In the scenario, the user provides a specfile generated from xselect, and ixpecalcarf will save the output response file to the same name as specfile except for the file extension (arf for the I spectrum, mrf for the Q or U spectrum). The ANCRFILE keywords in specfile will be updated accordingly by ixpecacarf.

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="./hk/ixpe02001001_det1_att_v01.fits.gz,./hk/ixpe02001002_det1_att_v01.fits.gz" radius=1.0 specfile="ixpe02001099_DU1I.pi" clobber=yes regfile=none pmapfile=none

Scenario 2: Similar to Scenario 1, but the user provided a circular DS9 region centered at the source. ixpecalcarf will use the radius from the region file for EEF corrections.

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="none" specfile="ixpe02001099_DU1I.pi" clobber=yes regfile="02001099_circular.reg" pmapfile=./hk/ixpe02001001_det1_pntmap.fits

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="none" specfile="ixpe02001099_DU1Q.pi" clobber=yes regfile="02001099_circular.reg" pmapfile=./hk/ixpe02001001_det1_pntmap.fits

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="none" specfile="ixpe02001099_DU1U.pi" clobber=yes regfile="02001099_circular.reg" pmapfile=./hk/ixpe02001001_det1_pntmap.fits

Case B: IXPE observations for an extended source based on a user-provided region file

Scenario 1: User provides a polygon DS9 region file. The syntax is the same as that of Case A-Scenario 2. In this case, ixpecalcarf does not apply aperture correction since it is a non-circular region.

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="none" specfile="ixpe02001099_DU1U.pi" clobber=yes regfile="02001099_polygon.reg" pmapfile=./hk/ixpe02001001_det1_pntmap.fits

Case C: IXPE response functions at a fixed off-axis angle

This example is for users who want to obtain response functions corrected for vignetting effects at a fixed off-axis angle (set offarcmin=0.0 would turn off the vignetting correction).

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="none" specfile="ixpe02001099_DU1U.pi" clobber=yes regfile=none pmapfile=none offarcmin=2.0

Case D: Backward compatibility for spectra and response files generated by non-HEASoft packages.

These examples are for users who want to modify the response functions geenrated by external software packages such as ixpeobssim.

Scenario 1: the user wants to apply vignetting and aperture corrections to a pre-generated response function from a non-HEASoft software package. Warning: this will modify the file parsed via arfin.

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="./hk/ixpe02001001_det1_att_v01.fits.gz,./hk/ ixpe02001002_det1_att_v01.fits.gz" radius=1.0 specfile=none arfin=ixpe_obssim_02001099_DU1.arf arfout=ixpe_obssim_02001099_DU1.arf clobber=yes regfile=none pmapfile=none

Scenario 2: similar to Scenario 1, but the user use a externally generated spectral file with a response function specifed by the ANCRFILE keyword of the spectrum. Warning: this will modify the file specified by the ANCRFILE keyword of the file parsed as specfile.

ixpecalcarf evtfile=./event_l2/ixpe02001099_det1_evt2_v02.fits attfiles="./hk/ixpe02001001_det1_att_v01.fits.gz,./hk/ixpe02001002_det1_att_v01.fits.gz" radius=1.0 specfile=ixpe_obssim_02001099_DU1.pha clobber=yes regfile=none pmapfile=none

BUGS

LAST MODIFIED

Feb 2024