lucabaldini
commented
1 year ago Hi Victor, thanks for reporting this.
This was actually the intended behavior, but I share you concerns about xpbin.py command-line arguments being overly complex and confusing, and I’ll be happy to discuss ways to make things better.
If you invoke the app with the --help command-line switch
[lbaldini@pclbaldini ixpeobssim]$ xpbin.py --help
Welcome to ixpeobssim 25.6.1 (built on Tue, 01 Mar 2022 10:09:07 +0100).
Copyright (C) 2015--2022, the ixpeobssim team.
ixpeobssim comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it under certain
conditions. See the LICENSE file for details.
Visit https://bitbucket.org/ixpesw/ixpeobssim for more information.
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]
[--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, overwrite, suffix
* PHA1Q: Stokes Q spectrum
--mc, weights, weightcol, overwrite, suffix
* PHA1U: Stokes U spectrum
--mc, weights, weightcol, overwrite, suffix
* PHA1QN: normalized Stokes Q spectrum (Q/I)
--mc, weights, weightcol, overwrite, suffix
* PHA1UN: normalized Stokes U spectrum (U/I)
--mc, weights, weightcol, 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, emin, emax, npix, pixsize, proj, xref, yref, overwrite, suffix
* MDPMAPCUBE: MDP map cube in sky coordinates and energy layers
--mc, acceptcorr, weights, weightcol, npix, pixsize, proj, xref, yref, emin, emax, ebins, ebinalg, ebinning, ebinfile, overwrite, suffix
* PCUBE: polarization cube (in energy layers)
--mc, acceptcorr, weights, weightcol, emin, emax, ebins, ebinalg, ebinning, ebinfile, overwrite, suffix
* PMAP: polarization map in sky coordinates
--mc, acceptcorr, weights, weightcol, emin, emax, npix, pixsize, proj, xref, yref, overwrite, suffix
* PMAPCUBE: polarization map cube in sky coordinates and energy layers
--mc, acceptcorr, weights, weightcol, 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)
--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)you will notice that, in the full help, the PP binning algorithm only supports a handful of arguments (those are listed at the top of the help for each algorithms separately).
All the energy-related command-line arguments are applicable to algorithms binning in energy, and are not intended for filtering---I guess what I always had in mind since the beginning was that one would use xpselect for that.
I see at least three things that could be done here:
- improve the help and the docs---and I’ll gladly accept suggestions; of course I am not holding my breath that this will prevent people to use the program in a way that was not intended 🙂
- exit with an error message whenever the you are passing a command-line option that is not applicable to a given algorithm; this, at least, would make it very clear that something is potentially wrong
- have all the algorithms supporting --emin and --emax in the filtering sense; I’d have to go back and look at the code, but my sense is that this would increase the complexity add more error-prone code paths for something that you might just do running xpselect upstream.
Of course what you write begs the question of whether we want to support pulse profiles and light curves binned in energy. This might actually be a sensible thing to do, and if you have a use case for that, I’d be happy to implement it. (In which case we might discuss the format.)
Feel free to continue commenting on this thread!
From the call sequence/doc string of xpbin, i..e
usage: xpbin [-h] --algorithm
{PHA1,PHA1Q,PHA1U,PHA1QN,PHA1UN,CMAP,MDPMAP,MDPMAPCUBE,PCUBE,PMAP,PMAPCUBE,PP,ARMAP,EFLUX,LC,LTCUBE}
[--suffix SUFFIX] [--irfname IRFNAME] [--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 ...]
xpbin: error: the following arguments are required: filelist, --algorithm
one could expect all keywords given to be respected, i.e. if one calls xpbin to make a pulse profile in a given energy range one would naively expect --ebins, --emin etc to be respected, but that’s not actually happening, i.e. xEventBinningBase only does binning but not filtering, so no matter which --emin --emax are supplied the xpbin call with --alghoritm=PP/CMAP/PCUBE etc no energy filtering actually takes place. I list this as a bug because that’s a major issue, we need either to update documentation to explicitly request all required filtering to be done before binning, or modify binning.base code to either do actual filtering or throw exception when incompatible arguments are supplied.
Original url: https://bitbucket.org/ixpesw/ixpeobssim/issues/577 Created on 2022-03-06T10:58:26.398814+00:00