Application reference

Here is the synopsis of all the applications in the IXPE observation simulation framework, along with the complete, up-to-date summary of the corresponding command-line switches.

Simulation facilities

xpobssim

...

usage: xpobssim.py [-h] [--outfile OUTFILE] --configfile CONFIGFILE
                   [--irfname IRFNAME] [--duration DURATION]
                   [--gtiminduration GTIMINDURATION]
                   [--gtistartpad GTISTARTPAD] [--gtistoppad GTISTOPPAD]
                   [--emin EMIN] [--emax EMAX] [--startdate DATE]
                   [--objname OBJNAME] [--seed SEED]
                   [--vignetting {True,False}] [--dithering {True,False}]
                   [--ditherampl DITHERAMPL] [--ditherpa DITHERPA]
                   [--ditherpx DITHERPX] [--ditherpy DITHERPY]
                   [--grayfilter {True,False}] [--charging {True,False}]
                   [--chrgnside CHRGNSIDE] [--chrgtstep CHRGTSTEP]
                   [--chrgmaps CHRGMAPS [CHRGMAPS ...]]
                   [--chrgparams CHRGPARAMS [CHRGPARAMS ...]]
                   [--deadtime DEADTIME] [--roll ROLL] [--saa {True,False}]
                   [--occult {True,False}] [--onorbitcalib {True,False}]
                   [--onorbitcaldemult ONORBITCALDEMULT]
                   [--onorbitcalminduration ONORBITCALMINDURATION]
                   [--onorbitcalstartpad ONORBITCALSTARTPAD]
                   [--onorbitcalstoppad ONORBITCALSTOPPAD]
                   [--onorbitcalrate ONORBITCALRATE]
                   [--timelinedata {True,False}] [--scdata {True,False}]
                   [--scdatainterval SCDATAINTERVAL] [--lv1a {True,False}]
                   [--lv1version LV1VERSION] [--overwrite {True,False}]

Run the ixpeobssim fast simulator.

This the main application in the package, and produces a set of event files
(a.k.a. photon lists), given a source model and a set of instrument response
functions, for a given observation time.

Internally the source spectral, temporal, morphological and polarimetric
characteristics are convolved with the instrument response functions to produce
a realistic, simulated IXPE observation.

optional arguments:
  -h, --help            show this help message and exit
  --outfile OUTFILE     path to the output file (default: None)
  --configfile CONFIGFILE
                        path to the input configuration file (default: None)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)
  --duration DURATION   duration of the observation in s (default: 1000)
  --gtiminduration GTIMINDURATION
                        minimum GTI duration in s (default: 0.0)
  --gtistartpad GTISTARTPAD
                        time padding at the start of each GTI in s (default:
                        0.0)
  --gtistoppad GTISTOPPAD
                        time padding at the stop of each GTI in s (default:
                        0.0)
  --emin EMIN           minimum energy in keV (default: 1.0)
  --emax EMAX           maximum energy in keV (default: 12.0)
  --startdate DATE      observation start date %Y-%m-%d or
                        %Y-%m-%dT%H:%M:%S.%f (default: 2022-04-21)
  --objname OBJNAME     name of the observed object (default: None)
  --seed SEED           random seed for the simulation (default: None)
  --vignetting {True,False}
                        apply MMA vignetting (default: True)
  --dithering {True,False}
                        apply the dithering pattern (default: True)
  --ditherampl DITHERAMPL
                        the dithering amplitude in arcmin (default: 1.6)
  --ditherpa DITHERPA   the dithering main period in s (default: 907.0)
  --ditherpx DITHERPX   the dithering x period in s (default: 101.0)
  --ditherpy DITHERPY   the dithering y period in s (default: 449.0)
  --grayfilter {True,False}
                        enable the gray filter (default: False)
  --charging {True,False}
                        apply the GEM charging (default: False)
  --chrgnside CHRGNSIDE
                        number of spatial bins for the charging model
                        (default: 200)
  --chrgtstep CHRGTSTEP
                        time step for the charging model [s] (default: 30)
  --chrgmaps CHRGMAPS [CHRGMAPS ...]
                        maps of the initial charging (default: None)
  --chrgparams CHRGPARAMS [CHRGPARAMS ...]
                        path to the files of the charging parameters (default:
                        None)
  --deadtime DEADTIME   average dead time per event in s (default: 0.00108)
  --roll ROLL           telescope roll angle in decimal degrees (default: 0.0)
  --saa {True,False}    consider the SAA for the GTI calculation (default:
                        False)
  --occult {True,False}
                        consider the Earth occultations for the GTI
                        calculation (default: False)
  --onorbitcalib {True,False}
                        activate the onboard calibration sources where
                        appropriate (default: False)
  --onorbitcaldemult ONORBITCALDEMULT
                        demultiplier for onboard calibration, i.e., do a DU
                        every n orbit(s) (default: 1)
  --onorbitcalminduration ONORBITCALMINDURATION
                        minimum duration of the onboard calibration runs
                        (default: 600.0)
  --onorbitcalstartpad ONORBITCALSTARTPAD
                        time padding for starting calibration runs in s
                        (default: 30.0)
  --onorbitcalstoppad ONORBITCALSTOPPAD
                        time padding for stopping calibration runs in s
                        (default: 30.0)
  --onorbitcalrate ONORBITCALRATE
                        average rate in Hz for the onboard Cal C source
                        (default: 100.0)
  --timelinedata {True,False}
                        write the observation timeline into the output file
                        (default: True)
  --scdata {True,False}
                        write the spacecraft data into the output file
                        (default: True)
  --scdatainterval SCDATAINTERVAL
                        time interval for the spacecraft data in s (default:
                        5.0)
  --lv1a {True,False}   create a pseudo-Lv1a file (default: False)
  --lv1version LV1VERSION
                        version number for the pseudo-Lv1a support (default:
                        5)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpphotonlist

...

usage: xpphotonlist.py [-h] [--outfile OUTFILE] --configfile CONFIGFILE
                       [--irfname IRFNAME] [--duration DURATION]
                       [--gtiminduration GTIMINDURATION]
                       [--gtistartpad GTISTARTPAD] [--gtistoppad GTISTOPPAD]
                       [--emin EMIN] [--emax EMAX] [--startdate DATE]
                       [--objname OBJNAME] [--seed SEED]
                       [--vignetting {True,False}] [--dithering {True,False}]
                       [--ditherampl DITHERAMPL] [--ditherpa DITHERPA]
                       [--ditherpx DITHERPX] [--ditherpy DITHERPY]
                       [--grayfilter {True,False}] [--roll ROLL]
                       [--saa {True,False}] [--occult {True,False}]
                       [--scdata {True,False}]
                       [--scdatainterval SCDATAINTERVAL]
                       [--overwrite {True,False}]

Create a photon list to be fed into ixpesim.

This is a rough equivalent to xpobssim, except for the fact that the output FITS
file(s) represent a list of photons at the top of the GPD window, as opposed to
a list of photoelectron tracks. This allows the list to be fed into xpsim, where
the photons are propagated through the detector, and the complete information
for all the events that trigger, including the track images, is written to file.

In conjunction with ixpesim, this small application allows for a full end-to-end
workflow where arbitrarily complex source models can be simulated with the
ultimate fidelity.

optional arguments:
  -h, --help            show this help message and exit
  --outfile OUTFILE     path to the output file (default: None)
  --configfile CONFIGFILE
                        path to the input configuration file (default: None)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)
  --duration DURATION   duration of the observation in s (default: 1000)
  --gtiminduration GTIMINDURATION
                        minimum GTI duration in s (default: 0.0)
  --gtistartpad GTISTARTPAD
                        time padding at the start of each GTI in s (default:
                        0.0)
  --gtistoppad GTISTOPPAD
                        time padding at the stop of each GTI in s (default:
                        0.0)
  --emin EMIN           minimum energy in keV (default: 1.0)
  --emax EMAX           maximum energy in keV (default: 12.0)
  --startdate DATE      observation start date %Y-%m-%d or
                        %Y-%m-%dT%H:%M:%S.%f (default: 2022-04-21)
  --objname OBJNAME     name of the observed object (default: None)
  --seed SEED           random seed for the simulation (default: None)
  --vignetting {True,False}
                        apply MMA vignetting (default: True)
  --dithering {True,False}
                        apply the dithering pattern (default: True)
  --ditherampl DITHERAMPL
                        the dithering amplitude in arcmin (default: 1.6)
  --ditherpa DITHERPA   the dithering main period in s (default: 907.0)
  --ditherpx DITHERPX   the dithering x period in s (default: 101.0)
  --ditherpy DITHERPY   the dithering y period in s (default: 449.0)
  --grayfilter {True,False}
                        enable the gray filter (default: False)
  --roll ROLL           telescope roll angle in decimal degrees (default: 0.0)
  --saa {True,False}    consider the SAA for the GTI calculation (default:
                        False)
  --occult {True,False}
                        consider the Earth occultations for the GTI
                        calculation (default: False)
  --scdata {True,False}
                        write the spacecraft data into the output file
                        (default: True)
  --scdatainterval SCDATAINTERVAL
                        time interval for the spacecraft data in s (default:
                        5.0)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

Warning

xpphotonlist is designed to generate list of photons at the top of the focal plane, to be fed into the full simulation of the focal-plane detectors—which we are not planning to release to the public. This application is, therefore, of limited use for the Community; yet, it can be used as an inspiration for a useful feature that could be adapted to different applications.

xpcalib

...

usage: xpcalib.py [-h] [--outfile OUTFILE] --configfile CONFIGFILE
                  [--irfname IRFNAME] [--duration DURATION] [--emin EMIN]
                  [--emax EMAX] [--startdate DATE] [--seed SEED]
                  [--charging {True,False}] [--chrgnside CHRGNSIDE]
                  [--chrgtstep CHRGTSTEP] [--chrgmaps CHRGMAPS [CHRGMAPS ...]]
                  [--chrgparams CHRGPARAMS [CHRGPARAMS ...]]
                  [--deadtime DEADTIME] [--lv1a {True,False}]
                  [--overwrite {True,False}]

Create photon lists from IXPE calibration runs, either on ground or in orbit.

optional arguments:
  -h, --help            show this help message and exit
  --outfile OUTFILE     path to the output file (default: None)
  --configfile CONFIGFILE
                        path to the input configuration file (default: None)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)
  --duration DURATION   duration of the observation in s (default: 1000)
  --emin EMIN           minimum energy in keV (default: 1.0)
  --emax EMAX           maximum energy in keV (default: 12.0)
  --startdate DATE      observation start date %Y-%m-%d or
                        %Y-%m-%dT%H:%M:%S.%f (default: 2022-04-21)
  --seed SEED           random seed for the simulation (default: None)
  --charging {True,False}
                        apply the GEM charging (default: False)
  --chrgnside CHRGNSIDE
                        number of spatial bins for the charging model
                        (default: 200)
  --chrgtstep CHRGTSTEP
                        time step for the charging model [s] (default: 30)
  --chrgmaps CHRGMAPS [CHRGMAPS ...]
                        maps of the initial charging (default: None)
  --chrgparams CHRGPARAMS [CHRGPARAMS ...]
                        path to the files of the charging parameters (default:
                        None)
  --deadtime DEADTIME   average dead time per event in s (default: 0.00108)
  --lv1a {True,False}   create a (pseudo) Lv1a file (default: False)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

Sensitivity estimation

xpmdp

...

usage: xpmdp.py [-h] [--outfile OUTFILE] --configfile CONFIGFILE
                [--srcid SRCID] [--irfname IRFNAME] [--duration DURATION]
                [--deadtime DEADTIME] [--eef EEF] [--phasemin PHASEMIN]
                [--phasemax PHASEMAX] [--emin EMIN] [--emax EMAX]
                [--ebinalg {FILE,LIN,LOG,LIST}] [--ebins EBINS]
                [--ebinfile EBINFILE] [--ebinning EBINNING]
                [--overwrite {True,False}]

Calculate the minimum detectable polarization (MDP) for a given source model.

The program takes the same python configuration modules that can be fed
into xpobbsim and calculates the MDP at the 99% CL by direct numerical
integration of the input spectrum (i.e., there are no event lists involved).
As a consequence, part of the richness of the detector response (most
notably, the energy dispersion and the vignetting) is not captured here.

For use cases beyond simple stationary point sources, the use of xpobbsim and
xpbin mode are recommended, as that approach offers the maximum flexibility.

optional arguments:
  -h, --help            show this help message and exit
  --outfile OUTFILE     path to the output file (default: None)
  --configfile CONFIGFILE
                        path to the input configuration file (default: None)
  --srcid SRCID         the source identifier in the ROITABLE extension
                        (default: 0)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)
  --duration DURATION   duration of the observation in s (default: 10000.0)
  --deadtime DEADTIME   average dead time per event in s (default: 0.00108)
  --eef EEF             encircled-energy-fraction factor (default: 1.0)
  --phasemin PHASEMIN   minimum phase for periodic sources (default: 0.0)
  --phasemax PHASEMAX   maximum phase for periodic sources (default: 1.0)
  --emin EMIN           minimum energy in keV (default: 2.0)
  --emax EMAX           maximum energy in keV (default: 8.0)
  --ebinalg {FILE,LIN,LOG,LIST}
                        energy binning specification (default: LOG)
  --ebins EBINS         number of bins for LIN/LOG energy binning (default: 4)
  --ebinfile EBINFILE   path to the energy bin definition file (default: None)
  --ebinning EBINNING   list containing the bin edges (default: None)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xppimms

...

usage: xppimms.py [-h] [--outfile OUTFILE] [--irfname IRFNAME] [--norm NORM]
                  [--index INDEX] [--nH NH] [--redshift REDSHIFT]
                  [--duration DURATION] [--deadtime DEADTIME] [--eef EEF]
                  [--emin EMIN] [--emax EMAX] [--ebinalg {FILE,LIN,LOG,LIST}]
                  [--ebins EBINS] [--ebinfile EBINFILE] [--ebinning EBINNING]
                  [--overwrite {True,False}]

Calculate the minimum detectable polarization (MDP) for simple stationary
point sources with a power-law spectrum, according to the source parameters
provided through the command-line switches.

(Note the default power-law normalization and index and the default duration
correspond to the setup for the IXPE level-1 polarization requirement).

The program calculates the MDP at the 99% CL by direct numerical integration of
the input spectrum and  response functions (i.e., there are no event lists
involved). As a consequence, part of the richness of the detector response
(most notably, the energy dispersion and the effective area vignetting) is not
captured.

For use cases beyond simple stationary point sources, the use of xpobbsim,
xpselect and xpbin are recommended, as that approach offers the maximum
flexibility.

optional arguments:
  -h, --help            show this help message and exit
  --outfile OUTFILE     path to the output file (default: None)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)
  --norm NORM           the power-law normalization for energy spectrum
                        (default: 0.0045023)
  --index INDEX         the power-law index for energy spectrum (default: 2.0)
  --nH NH               the hydrogen column density (cm^{-2}) (default: 0.0)
  --redshift REDSHIFT   the cosmological redshift (default: 0.0)
  --duration DURATION   duration of the observation in s (default: 864000.0)
  --deadtime DEADTIME   average dead time per event in s (default: 0.00108)
  --eef EEF             encircled-energy-fraction factor (default: 1.0)
  --emin EMIN           minimum energy in keV (default: 2.0)
  --emax EMAX           maximum energy in keV (default: 8.0)
  --ebinalg {FILE,LIN,LOG,LIST}
                        energy binning specification (default: LOG)
  --ebins EBINS         number of bins for LIN/LOG energy binning (default: 4)
  --ebinfile EBINFILE   path to the energy bin definition file (default: None)
  --ebinning EBINNING   list containing the bin edges (default: None)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpvisibility

...

usage: xpvisibility.py [-h] (--srcname NAME | --srccoords RA DEC)
                       [--startdate DATE] [--stopdate DATE]
                       [--sun {True,False}] [--overwrite {True,False}]

Simple IXPE visibility tool.

optional arguments:
  -h, --help            show this help message and exit
  --srcname NAME        name of the target source
  --srccoords RA DEC    coordinates of the target source
  --startdate DATE      observation start date %Y-%m-%d or
                        %Y-%m-%dT%H:%M:%S.%f (default: 2022-04-21)
  --stopdate DATE       observation stop date %Y-%m-%d or %Y-%m-%dT%H:%M:%S.%f
  --sun {True,False}    plot the Sun constraints (default: True)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

Analysis facilities

xpbin

...

usage: xpbin.py [-h] --algorithm
                {PHA1,PHA1Q,PHA1U,PHA1QN,PHA1UN,CMAP,MDPMAP,MDPMAPCUBE,PCUBE,PMAP,PMAPCUBE,PP,ARMAP,EFLUX,LC,LTCUBE}
                [--suffix SUFFIX] [--irfname IRFNAME]
                [--grayfilter {True,False}] [--acceptcorr {True,False}]
                [--weights {True,False}] [--weightcol WEIGHTCOL]
                [--tbinalg {FILE,LIN,LOG}] [--tmin TMIN] [--tmax TMAX]
                [--tbins TBINS] [--tbinfile TBINFILE] [--phasebins PHASEBINS]
                [--npix NPIX] [--pixsize PIXSIZE] [--xref XREF] [--yref YREF]
                [--proj {AIT,ZEA,ARC,CAR,GLS,MER,NCP,SIN,STG,TAN}]
                [--emin EMIN] [--emax EMAX]
                [--ebinalg {FILE,LIN,LOG,EQP,LIST}] [--ebins EBINS]
                [--ebinfile EBINFILE] [--ebinning EBINNING]
                [--phibins PHIBINS] [--thetabins THETABINS]
                [--mc {True,False}] [--overwrite {True,False}]
                filelist [filelist ...]

Basic event binning interface.

This application allows to bin event files (i.e., photon lists) in a fairly
generic fashion, creating count spectra, light curves, maps and more advances
data products such as those for storing the Stokes parameters.

Supported binning algorithms
* PHA1: count spectrum
   --mc, weights, weightcol, grayfilter, overwrite, suffix
* PHA1Q: Stokes Q spectrum
   --mc, weights, weightcol, grayfilter, overwrite, suffix
* PHA1U: Stokes U spectrum
   --mc, weights, weightcol, grayfilter, overwrite, suffix
* PHA1QN: normalized Stokes Q spectrum (Q/I)
   --mc, weights, weightcol, grayfilter, overwrite, suffix
* PHA1UN: normalized Stokes U spectrum (U/I)
   --mc, weights, weightcol, grayfilter, overwrite, suffix
* CMAP: count map in sky coordinates
   --mc, npix, pixsize, proj, xref, yref, overwrite, suffix
* MDPMAP: MDP map in sky coordinates
   --mc, acceptcorr, weights, weightcol, grayfilter, emin, emax, npix, pixsize, proj, xref, yref, overwrite, suffix
* MDPMAPCUBE: MDP map cube in sky coordinates and energy layers
   --mc, acceptcorr, weights, weightcol, grayfilter, npix, pixsize, proj, xref, yref, emin, emax, ebins, ebinalg, ebinning, ebinfile, overwrite, suffix
* PCUBE: polarization cube (in energy layers)
   --mc, acceptcorr, weights, weightcol, grayfilter, emin, emax, ebins, ebinalg, ebinning, ebinfile, overwrite, suffix
* PMAP: polarization map in sky coordinates
   --mc, acceptcorr, weights, weightcol, grayfilter, emin, emax, npix, pixsize, proj, xref, yref, overwrite, suffix
* PMAPCUBE: polarization map cube in sky coordinates and energy layers
   --mc, acceptcorr, weights, weightcol, grayfilter, npix, pixsize, proj, xref, yref, emin, emax, ebins, ebinalg, ebinning, ebinfile, overwrite, suffix
* PP: pulse profile
   --phasebins, overwrite, suffix
* ARMAP: rate per unit area map in detector coordinates
   --npix, overwrite, suffix
* EFLUX: energy-flux map in detector coordinates
   --npix, overwrite, suffix
* LC: light curve
   --tmin, tmax, tbins, tbinalg, tbinfile, overwrite, suffix
* LTCUBE: Livetime map cube in sky coordinates and off axis angle bins
   --npix, pixsize, proj, xref, yref, overwrite, suffix

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --algorithm {PHA1,PHA1Q,PHA1U,PHA1QN,PHA1UN,CMAP,MDPMAP,MDPMAPCUBE,PCUBE,PMAP,PMAPCUBE,PP,ARMAP,EFLUX,LC,LTCUBE}
                        the binning algorithm (default: None)
  --suffix SUFFIX       suffix for the output files (default: None)
  --irfname IRFNAME     name of the response functions to be used (default:
                        None)
  --grayfilter {True,False}
                        enable the gray filter (default: False)
  --acceptcorr {True,False}
                        enable/disable the acceptance correction for
                        polarization cubse and maps (default: True)
  --weights {True,False}
                        Use weights for the analysis (default: False)
  --weightcol WEIGHTCOL
                        name of the weight column to be used (default: W_MOM)
  --tbinalg {FILE,LIN,LOG}
                        time binning specification (default: LIN)
  --tmin TMIN           minimum time in s (default: None)
  --tmax TMAX           maximum tims in s (default: None)
  --tbins TBINS         number of bins for LIN/LOG time binning (default: 100)
  --tbinfile TBINFILE   path to the optional time bin definition file
                        (default: None)
  --phasebins PHASEBINS
                        number of bins for phase binning (default: 50)
  --npix NPIX           number of pixels per side in the output image
                        (default: 200)
  --pixsize PIXSIZE     the pixel size of the output image in arcseconds
                        (default: None)
  --xref XREF           the horizontal position of the image center (default:
                        None)
  --yref YREF           the vertical position of the image center (default:
                        None)
  --proj {AIT,ZEA,ARC,CAR,GLS,MER,NCP,SIN,STG,TAN}
                        coordinate projection (default: TAN)
  --emin EMIN           minimum energy in keV (default: 2.0)
  --emax EMAX           maximum energy in keV (default: 8.0)
  --ebinalg {FILE,LIN,LOG,EQP,LIST}
                        energy binning specification (default: LOG)
  --ebins EBINS         number of bins for LIN/LOG energy binning (default: 4)
  --ebinfile EBINFILE   path to the energy bin definition file (default: None)
  --ebinning EBINNING   list containing the bin edges (default: None)
  --phibins PHIBINS     number of bins for LIN/LOG phi binning (default: 75)
  --thetabins THETABINS
                        number of bins for off-axis angle binning (default:
                        17)
  --mc {True,False}     use Monte Carlo information (default: False)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpeselect

...

usage: xpselect.py [-h] [--suffix SUFFIX] [--tmin TMIN] [--tmax TMAX]
                   [--tinvert {True,False}] [--phasemin PHASEMIN]
                   [--phasemax PHASEMAX] [--phaseinvert {True,False}]
                   [--emin EMIN] [--emax EMAX] [--einvert {True,False}]
                   [--ra RA] [--dec DEC] [--rad RAD] [--innerrad INNERRAD]
                   [--regfile REGFILE] [--reginvert {True,False}]
                   [--mask MASK] [--mcsrcid MCSRCID] [--mc {True,False}]
                   [--ltimeupdate {True,False}] [--ltimealg {LTSUM,LTSCALE}]
                   [--overwrite {True,False}]
                   filelist [filelist ...]

Basic data selection interface. This utility can process IXPE event files
(i.e., photon lists) and apply a generic selection on sky-position, time,
phase, energy, etc., producing smaller event files. In conjunction with
xpbin this is handy to, e.g., energy- or phase-resolved polarization
measurements.

xpselect supports spatial selections from a ds9 region file thorough the
--regfile command-line switch.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --suffix SUFFIX       suffix for the output files (default: None)
  --tmin TMIN           minimum time in s (default: None)
  --tmax TMAX           maximum tims in s (default: None)
  --tinvert {True,False}
                        invert the time selection (default: False)
  --phasemin PHASEMIN   minimum phase for periodic sources (default: None)
  --phasemax PHASEMAX   maximum phase for periodic sources (default: None)
  --phaseinvert {True,False}
                        invert the phase selection (default: False)
  --emin EMIN           minimum energy in keV (default: None)
  --emax EMAX           maximum energy in keV (default: None)
  --einvert {True,False}
                        invert the energy selection (default: False)
  --ra RA               RA of acceptance cone in decimal degrees (default:
                        None)
  --dec DEC             Dec of acceptance cone in decimal degrees (default:
                        None)
  --rad RAD             ROI radius in arcminutes (default: None)
  --innerrad INNERRAD   ROI inner radius in arcminutes (for selecting annuli)
                        (default: None)
  --regfile REGFILE     path to a ds9 region file (default: None)
  --reginvert {True,False}
                        invert the ds9 region file selection (default: False)
  --mask MASK           path to .npy file with a saved boolean event mask
                        (default: None)
  --mcsrcid MCSRCID     the Monte Carlo source ID to select (default: [])
  --mc {True,False}     use Monte Carlo information (default: False)
  --ltimeupdate {True,False}
                        update the livetime-related keywords in the output
                        files (default: False)
  --ltimealg {LTSUM,LTSCALE}
                        algorithm to be used to update the livetime (default:
                        LTSCALE)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpxspec

...

usage: xpxspec.py [-h] --model MODEL [--params PARAMS]
                  [--fixpars FIXPARS [FIXPARS ...]] [--statmethod {}]
                  [--niterations NITERATIONS] [--emin EMIN] [--emax EMAX]
                  [--fit {True,False}] [--error {True,False}]
                  [--plot {True,False}] [--figname FIGNAME]
                  [--overwrite {True,False}]
                  filelist [filelist ...]

Minimal interface to perform a spectro-polarimetric fit in XSPEC, via the
Python bindings.

This is primarily designed to fit a spectral and polarimetric model to a series
of I, Q and U Stokes spectra (typically nine input files---three spectra for
each detector unit) or a purely polarimetric fit to a series of normalized
Q/I and U/I spectra (typically six input files).

Although only a small part of the flexibility provided by a real XSPEC session
is currently exposed, this simple application is a sensible mean to get started
with the use of the ixpeobssim polarimetric local models within XSPEC.

Note that the application fully supports purely spectral or polarimetric fits
in a transparent fashion.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --model MODEL         the spectral model for the fit (default: None)
  --params PARAMS       the initial values of the fit parameters (default:
                        None)
  --fixpars FIXPARS [FIXPARS ...]
                        freeze one or more fit-parameter value(s) (default:
                        [])
  --statmethod {}       the fit statistics to be used (default: chi)
  --niterations NITERATIONS
                        maximum number of fit iterations (default: 25)
  --emin EMIN           minimum energy in keV (default: 2.0)
  --emax EMAX           maximum energy in keV (default: 8.0)
  --fit {True,False}    fit the data (default: True)
  --error {True,False}  calculate confidence intervals for fit parameters
                        (default: True)
  --plot {True,False}   plot the fit results (default: True)
  --figname FIGNAME     base name for the output figures (default: XSPEC fit)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpphase

...

usage: xpphase.py [-h] [--suffix SUFFIX] [--parfile PARFILE] [--met0 MET0]
                  [--nu0 NU0] [--nudot0 NUDOT0] [--nuddot NUDDOT]
                  [--phi0 PHI0] [--overwrite {True,False}]
                  filelist [filelist ...]

Utility to build phase column into event file.

The program generates a phase array using pulsar time and ephemeris
and builds a new event FITS file with the new PHASE column.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --suffix SUFFIX       suffix for the output files (default: phase)
  --parfile PARFILE     path to the input parameter file (default: None)
  --met0 MET0           reference MET of the ephemeris in s (default: None)
  --nu0 NU0             frequency at t0 in Hz (default: None)
  --nudot0 NUDOT0       time first derivative of frequency at t0 in 1/(s^2)
                        (default: None)
  --nuddot NUDDOT       time second derivative of frequency in 1/(s^3)
                        (default: None)
  --phi0 PHI0           phase zero value (default: 0.0)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

Warning

When using xpphase from command line, since the derivatives of the frequence are typically (small) negative numbers, it is customary to bump into an odd corner of the Python argparse module, where the “e” character of the exponent specifier, in conjunction with the leading minus sign, tricks Python into thinking that the value for the nudot0 and/or the nuddot command line arguments are actually a separate option. The deal, here, is to use, e.g., the nudot0=-1.e13 form of the options specification, with the equal sign.

See this issue for more details.

xpophase

...

usage: xpophase.py [-h] [--suffix SUFFIX] --parfile PARFILE [--ra RA]
                   [--dec DEC] [--phi0 PHI0] [--bary {True,False}]
                   [--overwrite {True,False}]
                   filelist [filelist ...]

Utility to build orbital phase column into event file.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --suffix SUFFIX       suffix for the output files (default: ophase)
  --parfile PARFILE     path to the input parameter file (default: None)
  --ra RA               source right ascension in deg (default: None)
  --dec DEC             source declination in deg (default: None)
  --phi0 PHI0           phase zero value (default: 0.0)
  --bary {True,False}   apply or not barycentric time correction (default:
                        False)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpstokesalign

...

usage: xpstokesalign.py [-h] --mode {RAD,TAN,QU,PDA}
                        [--modelfiles MODELFILES [MODELFILES ...]] [--ra RA]
                        [--dec DEC] [--suffix SUFFIX] [--mc {True,False}]
                        [--overwrite {True,False}]
                        filelist [filelist ...]

Align the reconstructed Stokes parameters to a given polarization model.

This is an application processing a photon list and `rotating` the Stokes parameters
so that, on an event-by-event basis, the zero for the measurement of the
photoelectron direction is aligned to a given input model at the position of the
event.

In the simplest form the alignment can be either radial or tangential, which is
achieved by selecting the RAD or TAN modes, respectively, and optionally passing
the right ascension and the declination of the center for the rotation via the
--ra and --dec command-line switches.

Additionally, the user can feed into tha application pair of FITS images
(in either the Q/U, X/Y components of the polarization vector or polarization
degree/angle) in the same exact fashion of the machinery used for simulating
complex polarization patterns for extended sources in ixpeobssim. This is
achieved via a combination of the QU, XY of PDA modes, along with the proper
model files passed to the --modelfiles command-line switch.

Supported alignment algorithms:
- RAD: radial
- TAN: tangential
- QU : generic polarization model (from FITS maps of U and Q)
- XY : generic polarization model (from FITS maps of polarization components)
- PDA: generic polarization angle model (from a single FITS map)

Known limitations:
- the applications is currently not supporting Stokes sky-cubes, i.e., models
  where the polarization angle is energy-dependent (although this can be
  implemented if there is need for);
- when running in PDA mode, although in principle the map of the polarization
  angle would be enough to operate the rotation, for techincal reasons having
  to do with the internals of the code, we still need to pass the maps of both
  the polarization degree and angle (and, again, this is a nuisance that we
  can overcome if there is really need for).

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --mode {RAD,TAN,QU,PDA}
                        the alignment mode
  --modelfiles MODELFILES [MODELFILES ...]
                        path to the input model file(s) (default: None)
  --ra RA               RA of the model center in decimal degrees (default:
                        None)
  --dec DEC             Dec of the model center in decimal degrees (default:
                        None)
  --suffix SUFFIX       suffix for the output files (default: None)
  --mc {True,False}     use Monte Carlo information (default: False)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpstokesrandom

...

usage: xpstokesrandom.py [-h] [--seed SEED] [--suffix SUFFIX]
                         [--overwrite {True,False}]
                         filelist [filelist ...]

Process a level-2 file and replace the Q and U column with random values sampled
according to a fully unpolarized simulation.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --seed SEED           random seed for the simulation (default: 1)
  --suffix SUFFIX       suffix for the output files (default: stokesrandom)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpstokesshuffle

...

usage: xpstokesshuffle.py [-h] [--seed SEED] [--suffix SUFFIX]
                          [--overwrite {True,False}]
                          filelist [filelist ...]

Process a level-2 file and shuffle the value of the Q and U columns across the
events.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --seed SEED           random seed for the simulation (default: 1)
  --suffix SUFFIX       suffix for the output files (default: stokesshuffle)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpstokessmear

...

usage: xpstokessmear.py [-h] [--innersigma INNERSIGMA]
                        [--outersigma OUTERSIGMA] [--innerradius INNERRADIUS]
                        [--nside NSIDE] [--suffix SUFFIX] [--seed SEED]
                        [--interactive {True,False}]
                        [--overwrite {True,False}]
                        filelist [filelist ...]

Smear the event-by-event Stokes parameters with a gaussian probability density
function with zero average.

This is supposed to be a cheap shortcut to test the effect of the correction for
the spurious modulation in realistic analysis without having to simulate the
effect to start with---we assume that the actual correction gets the average
right, and we are just introducing the statistical fluctuations of the
correction, here, in such a way that the output Stokes parameters are not
properly normalized, as will happen for real level-2 files.

The smearing is done over a fixed grid of pixels, with sigma values different in
the center of the detector and on the borders, and in a single energy band.
While this is defintely not capturing the entire richness of the phenomenology
of the spurious modulation, it is a sensible zero-order approximation to test
possible biases of the correction on actual science analysis.

For reference, the spurious modulation maps in the IXPE CALDB are mapped onto
300 x 300 bins on the detector surface, and across 6 energy bands. The typical
errors on Q and U are 0.025 in the inner 50 pixel (or 2.5 mm) radius circle,
and 0.10 in the outer portion of the detector.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --innersigma INNERSIGMA
                        the standard deviation for the Q and U gaussian
                        smearing in the center (default: 0.025)
  --outersigma OUTERSIGMA
                        the standard deviation for the Q and U gaussian
                        smearing on the border (default: 0.1)
  --innerradius INNERRADIUS
                        the inner radius in mm, defining the region of the
                        high-statistics calibration (default: 2.5)
  --nside NSIDE         the size of the binning grid in DETX and DETY
                        (default: 300)
  --suffix SUFFIX       suffix for the output files (default: stokessmear)
  --seed SEED           random seed for the simulation (default: None)
  --interactive {True,False}
                        plot some diagnostic plot (default: False)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpexposure

...

usage: xpexposure.py [-h] --cmapfiles CMAPFILES [CMAPFILES ...]
                     [--irfname IRFNAME] [--irftype {arf,mrf,both}]
                     [--expunits {None,cm2s,s}] [--overwrite {True,False}]
                     filelist [filelist ...]

Read a series of binned livetime cubes and perform the PSF convolution,
exposure calculation and correction for the effective area and/or the
modulation response functions.

The modified response files can be used, e.g., for spectro-polarimetric fitting
within XSPEC. (Note ixpeobssim offers the xpancrkey.py script to set the
ANCRFILE header keywords in the event files.)

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --cmapfiles CMAPFILES [CMAPFILES ...]
                        path(s) to the CMAP file(s) (default: None)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)
  --irftype {arf,mrf,both}
                        type of irf to correct and save (default: both)
  --expunits {None,cm2s,s}
                        flag to save the exposure cube using the required
                        units (default: None)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

Visualization facilities

xpbinview

...

usage: xpbinview.py [-h] [--outfile OUTFILE] [--overwrite {True,False}]
                    [--stretch STRETCH] [--vmin VMIN] [--vmax VMAX]
                    [--zlabel ZLABEL] [--dpi DPI] [--mjd {True,False}]
                    filelist [filelist ...]

Generic display interface to ixpeobssim binned data products.

This application allows to display the content of xpbin output files in all
the possible flavors. It is equipped to recognize automagically the binning
algotithm used to create the FITS file and use the proper facilty for the
display, i.e., you should be able to pass any binned product coming out of
xpbin and xpbinview should do the right thing to display that file to you.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --outfile OUTFILE     path to the output file (default: None)
  --overwrite {True,False}
                        overwrite existing output files (default: True)
  --stretch STRETCH     The stretch function for image color normalization
                        {'log', 'sqrt', 'linear', 'asinh', 'power'} (default:
                        linear)
  --vmin VMIN           minimum data range for colormaps (default: None)
  --vmax VMAX           maximum data range for colormaps (default: None)
  --zlabel ZLABEL       the color map laber for count maps (default: None)
  --dpi DPI             resolution of the output image in dot per inches
                        (default: 100)
  --mjd {True,False}    Show light curves in MJD time (as opposed to MET)
                        (default: False)

xpradialprofile

...

usage: xpradialprofile.py [-h] [--ra RA] [--dec DEC] [--rmin RMIN]
                          [--rmax RMAX] [--rcore RCORE] [--rbins RBINS]
                          [--autocenter {True,False}] [--psf {True,False}]
                          [--residuals {True,False}]
                          [--interactive {True,False}] [--irfname IRFNAME]
                          filelist [filelist ...]

Create a radial profile plot, in sky coordinates, for a given observation.

This program takes a level-2 file as an input and creates a radial histogram of
the event counts, weighted with 1. / r to correct for the solid angle. This is
a useful diagnostics to gauge the background level in a given observation.

In order to provide more context to the plots, the PSF radial profile for the
relevant DU is overlayied, and the estimated fraction of source events outside
a circle of radius r is annotated over the PSF line for a discrete set of values
of r.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --ra RA               RA of the center of the radial plot in decimal degrees
                        (default: None)
  --dec DEC             Dec of the center of the radial plot in decimal
                        degrees (default: None)
  --rmin RMIN           minimum radial distance in arcminutes (default: 0.0)
  --rmax RMAX           maximum radial distance in arcminutes (default: 10.0)
  --rcore RCORE         core radius for the psf fit in arcminutes (default:
                        0.5)
  --rbins RBINS         number of bins for the radial profile (default: 200)
  --autocenter {True,False}
                        recenter the image based on the count map (default:
                        True)
  --psf {True,False}    overimpose the PSF radial profile (default: True)
  --residuals {True,False}
                        plot the estimated residual background (default:
                        False)
  --interactive {True,False}
                        plot some diagnostic plot (default: False)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)

xpevtdisplay

...

usage: IXPE single event display.

This application provides visualization support for track images contained in
Level-1 IXPE files.

       [-h] [--evtlist EVTLIST] [--targetname TARGETNAME] [--emin EMIN]
       [--emax EMAX] [--seed SEED] [--clustering {True,False}]
       [--numclusters NUMCLUSTERS] [--clumindensity CLUMINDENSITY]
       [--cluminsize CLUMINSIZE] [--resample RESAMPLE]
       [--absorption {True,False}] [--barycenter {True,False}]
       [--direction {True,False}] [--pixpha {True,False}]
       [--indices {True,False}] [--cmap CMAP] [--cmapoffset CMAPOFFSET]
       [--minaxside MINAXSIDE] [--autostop AUTOSTOP] [--batch {True,False}]
       [--autosave {True,False}] [--outfolder OUTFOLDER]
       [--imgformat IMGFORMAT] [--imgdpi IMGDPI] [--timestamp TIMESTAMP]
       file

positional arguments:
  file                  path to the input file

optional arguments:
  -h, --help            show this help message and exit
  --evtlist EVTLIST     path to the auxiliary (Level-2 file) event list
                        (default: None)
  --targetname TARGETNAME
                        name of the celestial target (default: N/A)
  --emin EMIN           minimum energy in keV (default: 2.0)
  --emax EMAX           maximum energy in keV (default: 8.0)
  --seed SEED           random seed for the simulation (default: 1)
  --clustering {True,False}
                        run the DBscan clustering on the events (default:
                        True)
  --numclusters NUMCLUSTERS
                        the number of clusters to be displayed for each event
                        (default: 2)
  --clumindensity CLUMINDENSITY
                        the minimum density point for the DBscan clustering
                        (default: 5)
  --cluminsize CLUMINSIZE
                        the minimum cluster size for the DBscan clustering
                        (default: 6)
  --resample RESAMPLE   the power-law index for resampling events in energy
                        (default: None)
  --absorption {True,False}
                        draw the reconstructed absorption_point (default:
                        True)
  --barycenter {True,False}
                        draw the reconstructed barycenter (default: True)
  --direction {True,False}
                        draw the reconstructed track direction (default: True)
  --pixpha {True,False}
                        indicate the pixel PHA values (default: False)
  --indices {True,False}
                        draw the row and column indices of the readout matrix
                        (default: False)
  --cmap CMAP           the color map for the pixel values (default: Reds)
  --cmapoffset CMAPOFFSET
                        the PHA offset for the color map (default: 10)
  --minaxside MINAXSIDE
                        the axis side for the event display (default: 2.0)
  --autostop AUTOSTOP   stop automatically after a given number of events
                        (default: None)
  --batch {True,False}  run in batch mode (default: False)
  --autosave {True,False}
                        save the event displays automatically (default: False)
  --outfolder OUTFOLDER
                        path to the output folder (default:
                        /home/docs/ixpeobssimdata)
  --imgformat IMGFORMAT
                        the image format for the output files when autosave is
                        True (default: png)
  --imgdpi IMGDPI       resolution of the output image in dot per inches
                        (default: 250)
  --timestamp TIMESTAMP
                        timestamp of a single specific event to be displayed
                        (default: None)

xpobsdisplay

...

usage: IXPE composite carousel to display observations.

This application extends xpevtdisplay to include the most relevant cumulative
distributions for a given observation.

       [-h] [--evtlist EVTLIST] [--targetname TARGETNAME] [--emin EMIN]
       [--emax EMAX] [--seed SEED] [--clustering {True,False}]
       [--numclusters NUMCLUSTERS] [--clumindensity CLUMINDENSITY]
       [--cluminsize CLUMINSIZE] [--resample RESAMPLE]
       [--absorption {True,False}] [--barycenter {True,False}]
       [--direction {True,False}] [--pixpha {True,False}]
       [--indices {True,False}] [--cmap CMAP] [--cmapoffset CMAPOFFSET]
       [--minaxside MINAXSIDE] [--autostop AUTOSTOP] [--batch {True,False}]
       [--autosave {True,False}] [--outfolder OUTFOLDER]
       [--imgformat IMGFORMAT] [--imgdpi IMGDPI] [--irfname IRFNAME]
       [--pdmax PDMAX] [--pdstep PDSTEP] [--xref XREF] [--yref YREF]
       [--npix NPIX] [--pixsize PIXSIZE] [--subtitle SUBTITLE]
       file

positional arguments:
  file                  path to the input file

optional arguments:
  -h, --help            show this help message and exit
  --evtlist EVTLIST     path to the auxiliary (Level-2 file) event list
                        (default: None)
  --targetname TARGETNAME
                        name of the celestial target (default: N/A)
  --emin EMIN           minimum energy in keV (default: 2.0)
  --emax EMAX           maximum energy in keV (default: 8.0)
  --seed SEED           random seed for the simulation (default: 1)
  --clustering {True,False}
                        run the DBscan clustering on the events (default:
                        True)
  --numclusters NUMCLUSTERS
                        the number of clusters to be displayed for each event
                        (default: 2)
  --clumindensity CLUMINDENSITY
                        the minimum density point for the DBscan clustering
                        (default: 5)
  --cluminsize CLUMINSIZE
                        the minimum cluster size for the DBscan clustering
                        (default: 6)
  --resample RESAMPLE   the power-law index for resampling events in energy
                        (default: None)
  --absorption {True,False}
                        draw the reconstructed absorption_point (default:
                        True)
  --barycenter {True,False}
                        draw the reconstructed barycenter (default: True)
  --direction {True,False}
                        draw the reconstructed track direction (default: True)
  --pixpha {True,False}
                        indicate the pixel PHA values (default: False)
  --indices {True,False}
                        draw the row and column indices of the readout matrix
                        (default: False)
  --cmap CMAP           the color map for the pixel values (default: Reds)
  --cmapoffset CMAPOFFSET
                        the PHA offset for the color map (default: 10)
  --minaxside MINAXSIDE
                        the axis side for the event display (default: 2.0)
  --autostop AUTOSTOP   stop automatically after a given number of events
                        (default: None)
  --batch {True,False}  run in batch mode (default: False)
  --autosave {True,False}
                        save the event displays automatically (default: False)
  --outfolder OUTFOLDER
                        path to the output folder (default:
                        /home/docs/ixpeobssimdata)
  --imgformat IMGFORMAT
                        the image format for the output files when autosave is
                        True (default: png)
  --imgdpi IMGDPI       resolution of the output image in dot per inches
                        (default: 250)
  --irfname IRFNAME     name of the response functions to be used (default:
                        ixpe:obssim20240101:v13)
  --pdmax PDMAX         maximum polarization degree for the Stokes plot
                        (default: 0.2)
  --pdstep PDSTEP       polarization degree step for the Stokes plot grid
                        (default: 0.05)
  --xref XREF           the horizontal position of the image center (default:
                        None)
  --yref YREF           the vertical position of the image center (default:
                        None)
  --npix NPIX           number of pixels per side for the count map in sky
                        coordinates (default: 200)
  --pixsize PIXSIZE     pixel size in arcseconds for the count map in sky
                        coordinates (default: None)
  --subtitle SUBTITLE   subtitle for the animation (default: None)

xpirfview

...

usage: xpirfview.py [-h] [--save] [--outfolder OUTFOLDER] file

Generic display application for viewing response files.

This application allows to display the content of IXPE effective area,
point-spread-function, energy dispersion and modulation factor response files.

positional arguments:
  file                  path to the input file

optional arguments:
  -h, --help            show this help message and exit
  --save                save the output products (default: False)
  --outfolder OUTFOLDER
                        path to the output folder (default:
                        /home/docs/ixpeobssimdata)

xpobsview

...

usage: xpobsview.py [-h] filelist [filelist ...]

Observation timeline and spacecraft data quick look.

This application retrieves the TIMELINE, GTI and OCTI data from a series of
event lists and plot them as strip charts.

positional arguments:
  filelist    path(s) to the input file(s)

optional arguments:
  -h, --help  show this help message and exit

Miscellanea

xpsonify

...

xpevtstat

...

usage: xpevtstat.py [-h] [--emin EMIN] [--emax EMAX]
                    [--ebinalg {FILE,LIN,LOG,LIST}] [--ebins EBINS]
                    [--ebinfile EBINFILE] [--ebinning EBINNING]
                    [--mc {True,False}]
                    filelist [filelist ...]

Read a series of photon lists and print some basic statistics of the various
model components in the form of a simple text table.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --emin EMIN           minimum energy in keV (default: 2.0)
  --emax EMAX           maximum energy in keV (default: 8.0)
  --ebinalg {FILE,LIN,LOG,LIST}
                        energy binning specification (default: LOG)
  --ebins EBINS         number of bins for LIN/LOG energy binning (default: 3)
  --ebinfile EBINFILE   path to the energy bin definition file (default: None)
  --ebinning EBINNING   list containing the bin edges (default: None)
  --mc {True,False}     use Monte Carlo information (default: False)

xpgrppha

...

usage: xpgrppha.py [-h] [--suffix SUFFIX] --comm COMM [--chatter CHATTER]
                   [--overwrite {True,False}]
                   filelist [filelist ...]

Small Python wrapper around the HEASARC GRPPHA utility, see
https://heasarc.gsfc.nasa.gov/ftools/caldb/help/grppha.txt

In a nutshell, you should be able to pass any command that you would pass to
grppha interactively via the --comm command-line switch, e.g.

> xpgrppha.py --comm "group min 100" pha1.fits

will (loosely) map to:

> grppha infile="pha1.fits" outfile="pha1_grppha.fits" comm="group min 100 & write & exit" chatter=5 clobber=yes

(Note that "& write & exit" are automatically added at the end.)

While this is supposed to be as faithful as possible to the original, underlying
application, there are some notable differences you should keep in mind:

* you can provide an arbitrary number of input files as command-line
  arguments, and the wrapper will happily iterate over them;
* sticking to the ixpeobssim convensions, the name of the output file is
  programmatically built from the input, and you can (at least partially)
  control that via the --suffix command-line switch;
* the wrapper, as all the other ixpeobssim applications, offers a --overwrite
  command-line option that is similar in spirit to the grppha clobber
  option (for technical reasons grppha is always run with the clobber option
  set to "yes" and the check on the output file is done independently).

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --suffix SUFFIX       suffix for the output files (default: grppha)
  --comm COMM           the GRPPHA command string (default: None)
  --chatter CHATTER     value of the GRPPHA chatter commad-line switch
                        (default: 5)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpsrccoords

...

xpancrkey

...

usage: xpancrkey.py [-h] [--arffiles ARFFILES [ARFFILES ...]]
                    [--suffix SUFFIX] [--overwrite {True,False}]
                    filelist [filelist ...]

Update the ANCRFILE keyword in the primary header of the target binned file.

This is germane to what the fparkey FTOOL
https://heasarc.gsfc.nasa.gov/lheasoft/ftools/fhelp/fparkey.html
is doing, except for the much more limited scope. On the plus side, this small
app will perform some basic check on the value being written in the header in
order to avoid common pitfalls.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --arffiles ARFFILES [ARFFILES ...]
                        path(s) to the new .arf files to use. (default: [])
  --suffix SUFFIX       suffix for the output files (default: ancrkey)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpchrgmap

...

usage: xpchrgmap.py [-h] [--outfolder OUTFOLDER] [--overwrite {True,False}]
                    filelist [filelist ...]

Extract charging maps from an observation file.

This application is meant to open an observation file, read the CHRG_MAP
extension and copy it in a different FITS file, adding the proper header to
the PRIMARY extension so that the format is the same as the actual charging map
files.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --outfolder OUTFOLDER
                        path to the output folder (default:
                        /home/docs/ixpeobssimdata)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xppicorr

...

usage: xppicorr.py [-h] [--offset OFFSET] [--slope SLOPE]
                   [--corrfile CORRFILE] [--deterministic {True,False}]
                   [--seed SEED] [--suffix SUFFIX] [--overwrite {True,False}]
                   filelist [filelist ...]

Correct the PI column in a level-2 file, given either a constant scale factor
and/or offset, or a proper FITS file with a time-dependent correction.

In order to avoid steps in the output corrected files, a floating-point smearing
factor in the [-0.5, 0.5] interval is added to the original PI before the
correction. When run in deterministic mode this factor is determined by the
event time (more precisely, using the fractional part of the timestamps), otherwise
we just throw a random number with a uniform distribution.

Note this is mainly intended for debugging purposes---you are changing the
actual data, so you'd better know what you are doing :-)

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --offset OFFSET       global offset for the PI column (default: 0.0)
  --slope SLOPE         global scale factor for the PI column (default: 1.0)
  --corrfile CORRFILE   path to the FITS file for a time-dependent correction
                        (default: None)
  --deterministic {True,False}
                        run in deterministic mode (default: True)
  --seed SEED           random seed for the simulation (default: None)
  --suffix SUFFIX       suffix for the output files (default: picorr)
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpsimfmt

...

usage: xpsimfmt.py [-h] [--suffix SUFFIX] [--weightname WEIGHTNAME]
                   [--auxversion AUXVERSION] [--mc {True,False}]
                   [--detphiname DETPHINAME] [--stripmode {FULL,L2}]
                   [--overwrite {True,False}]
                   filelist [filelist ...]

Format reconstructed event lists generated with ixpesim to make them
interoperable with ixpeobssim (e.g., for spectro-polarimetric fits in XSPEC).
Phrased in a slightly different way, this is tranforming the rough equivalent
of Level-1 files produced by ixpesim into the rough equivalent of Level-2 files.

This is adding all the necessary keywords to the relevant headers, as well as
a few columns in the EVENTS extensions that are necessary for the
spectro-polarimetric analysis in XSPEC, most notably:
- PI
- Q
- U
- RA, DEC
- X, Y
- W_MOM

Additionally, the script allows to strip off useless columns, producing smaller
output files that easier to exchange in several different context. This
functionality is controlled by the --stripmode command-line switch and, more
specifically:

* --stripmode FULL preserves the entire content of the ixpesim output files;
* --stripmode L2 produces a smaller file that is genermane to Level 2 files and
  can be effectively used to test a spectro-polarimetric analysis with the
  photon-list workflow;

Note this requires the input files to be processed with a recent enough gpdsw
version (13.10.0 or later) in order for the conversion to be supported.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --suffix SUFFIX       suffix for the output files (default: simfmt)
  --weightname WEIGHTNAME
                        name of the weights to be used (default: alpha075)
  --auxversion AUXVERSION
                        target version for the auxiliary files (default: 3)
  --mc {True,False}     use Monte Carlo information (default: False)
  --detphiname DETPHINAME
                        The column name for the azimuthal angle (default:
                        DETPHI2)
  --stripmode {FULL,L2}
  --overwrite {True,False}
                        overwrite existing output files (default: True)

xpsimspec

...

usage: xpsimspec.py [-h] [--emin EMIN] [--emax EMAX] [--ebins EBINS]
                    [--index INDEX] [--nH NH]

Write a text file to be fed as an input custom spectrum to ixpesim to
simulate a realistic astrophysical spectrum.

At the moment the spectrum is limited to a power law with an adjustable index,
and the H column density can be controlled via command line. The effect of the
mirror effective area and the transparency of the UV filter are taken into
account.

The output is a simple text file with two columns---the energy in MeV and the
flux in arbitrary units.

optional arguments:
  -h, --help     show this help message and exit
  --emin EMIN    minimum energy in keV (default: 1.0)
  --emax EMAX    maximum energy in keV (default: 12.0)
  --ebins EBINS  number of energy bins (default: 250)
  --index INDEX  the power-law index for energy spectrum (default: 2.0)
  --nH NH        the hydrogen column density (cm^{-2}) (default: 0.0)

xpstripmc

...

usage: xpstripmc.py [-h] [--suffix SUFFIX] [--overwrite {True,False}]
                    filelist [filelist ...]

Remove all the Monte Carlo information from ixpeobssim photon lists.

positional arguments:
  filelist              path(s) to the input file(s)

optional arguments:
  -h, --help            show this help message and exit
  --suffix SUFFIX       suffix for the output files (default: nomc)
  --overwrite {True,False}
                        overwrite existing output files (default: True)