Event Display

New in version 29.4.0: ixpeobssim includes a single event display to render the track images shipped with publicly distributed the level-1 files.

As of version 29.4.0 ixpeobssim include a new small application, xpevtdisplay, that allows to display the track images shipped with the standard IXPE level-1 publicily distributed through HEASARC.

_images/ixpe_track_display.png

Sample display of a track image—note that mileage may vary depending on the setting (i.e., command-line switches) used in xpevtdisplay.

While the help coming with the program should be largely self-explaining, a few remarks are in order, here. First of all, xpevtdisplay operates on level-1 files, which are the only ones containing the track images by default, and whom most user are probably not terribly familiar with. In constrast to the more widely used level-2 files, level-1 files are significantly larger (which means: do not be surprised if firing up the event display on a particular file takes a few seconds), and contain all the event recorded through the observation—no matter whether they correspond to actual GTI, or to periods when the source was occulted by the Earth (and, possibly, with one of the calibration sources in use). As a consequence, just firing up the event display on a level-1 file

xpevtdisplay path_to_my_level1_file

is not terribly useful, in general: you have no control on which events you are actually displaying—that is, they might very well be from one of the onboard calibration sources, rather than from the celestial source being observed.

For this very reason, xpevtdisplay features a --evtlist command line flag that allows to feed into the application a level-2 file in addition to the level-1 main file (it goes without saying, the two generally need to correspond to the same observation).

xpevtdisplay path_to_my_level1_file --evtlist path_to_the_fellow_level2_file

When you pass this additional file to the event display, a few things happen behind the scenes, namely:

  • the display will loop over the level-2 file, one event at a time, and retrieve all the relevant high-level information (time, energy, sky position and Stokes parameters);

  • for each event, a binary search is run over the level-1 file to identify the corresponding raw event data;

  • the actual event in the level-1 file gets displayed, along with all the high-level info from the level-2 data.

This is where things get interesting: since you can run xpeselect natively over any level-2 file, this provides a convenient mechanism to select small subsamples of event (e.g., in energy or sky position) and get them displayed.

Now, when you start looking at track images, you will probably get bored quite quickly: as the IXPE effective area is sharply peaked around 2.2 keV, most of the events will probably look quite similar to each other. This is fine if you are interested in an unbiased sample of tracks, but it will take you lots of luck to stumble across a high-energy track such as the one shown at the top of the page. For this reason, the --resample command-line swicht provides a mechanism to resample in energy the input level-2 file using a power law with the specified index—if you use, e.g., --resample 3 you should see a large variety of event topologies.

Warning

Be mindful that, since the event time is the only quantity that we can use to keep in synch level-2 and level-1 data, the event list functionality does not play well with any analysis tool (e.g., the barycorr FTOOL) that change the event time—for the purpose of the event display you want to use event file as distributed, without further processing.

Also, when reading a Level-1 files and passing at the same time an event list in the form of a Level-2 file, you should make sure that the former covers the entire time span of the latter, otherwise the MET bisection will fail. If the Level-2 file covers a longer time span wrt. the Level-1 file, you can simply trim the former with the standard tools.

Observation animations

Building on top of the single event display, ixpeobssim provides a separate application, xpobsdisplay, that allows to create complex animations starting from the standard observation products distributed through HEASARC by jut adding to the track images accumulating histograms of the relevant science quantities: energy, sky position, and Stokes parameters.

The xpobsdisplay is fairly similar to that of xpevtdisplay. We won’t describe the meaning of all the command-line switches here, but the following command

xpobsdisplay path_to_my_level1_file --evtlist path_to_the_fellow_level2_file \
    --resample 2 --autostop 200 --targetname "The name of the source" --autosave True \
    --imgdpi 200 --batch True

will read in the target files and write to file 200 still track images in batch mode (i.e., no matplotlib canvas will be displayed on the screen).

The user can then combine the still frames into an actual animation by using any of the countless tools available on the market, one possible example being

ffmpeg -framerate 1 -i path_to_frames_%04d.png -c:v libx264  -s 1920x1080 -r 30 \
    -pix_fmt yuv420p animation.mp4

For completeness, a succinct and yet informative resource about using ffmpeg to create slideshows is here.