HEAPY

A Python toolkit for data reduction, temporal analysis, and spectral extraction of X-ray and gamma-ray transients.

Heapy is a Python toolkit for data reduction, temporal analysis, and spectral extraction of X-ray and gamma-ray transients. It pulls event and response data from mission archives, reduces time-tagged-event (TTE) and image data into light curves and OGIP spectra, separates burst signals from fitted backgrounds, and measures durations, spectral lags, and source localizations — across Fermi/GBM, GECAM, GRID, Einstein Probe (WXT/FXT), and Swift (XRT/BAT). It bridges to HEASoft and gbm_drm_gen for mission-specific reduction and response generation.

Features

• Data retrieval. Pull event, position, and response files straight from mission archives by burst ID, UTC window, or observation ID (gbmRetrieve, gecamRetrieve, gridRetrieve, epRetrieve, swiftRetrieve).
• Multi-mission event reduction. One Event interface across Fermi/GBM TTE, GECAM, GRID, Einstein Probe (WXT/FXT), and Swift (XRT/BAT).
• Light curves. Extract and rebin light curves with automatic background fitting.
• Signal detection. Bayesian-block signal/background separation with three noise regimes — Poisson + polynomial background (pgSignal), Poisson + supplied background (ppSignal), and Gaussian (ggSignal).
• OGIP spectra. Generate source and background PHA/PHA2 spectra, and — for Fermi/GBM — response matrices via gbm_drm_gen.
• Timing analysis. Duration measurements (T90/Txx) and spectral-lag estimation.
• Localization & geometry. Detector geometry, sky maps, and source localization.

Installation

Heapy requires Python 3.10 or later and is available on PyPI:

pip install heapyx

Optional: HEASoft

For some missions (e.g., Swift), heapy invokes HEASoft tools such as xselect and ximage. Ensure HEASoft is installed, along with the Calibration Database (CALDB) for the mission you are processing.

Optional: Fermi GBM response generator

To build response matrices for Fermi/GBM, heapy calls gbm_drm_gen. The forked packages below are fine-tuned for newer numpy/astropy and use TTE instead of CSPEC data:

git clone https://github.com/jyangch/responsum.git
pip3 install ./responsum

git clone https://github.com/jyangch/gbmgeometry.git
pip3 install ./gbmgeometry

git clone https://github.com/jyangch/gbm_drm_gen.git
pip3 install ./gbm_drm_gen

Documentation

Browse the examples for typical workflows end to end.

Citation

If you use HEAPY in your research, please include a software citation in your reference list and state the version used in your methods section. Citation metadata are available in CITATION.cff.

Until a DOI-backed release is available, the repository can be cited as:

Yang, J. HEAPY: A Python toolkit for data reduction, temporal analysis, and spectral extraction of X-ray and gamma-ray transients [Computer software]. https://github.com/jyangch/heapy

@software{heapy,
  author = {Yang, Jun},
  title = {{HEAPY}: A Python toolkit for data reduction, temporal analysis, and
           spectral extraction of X-ray and gamma-ray transients},
  url = {https://github.com/jyangch/heapy}
}

License

Heapy is distributed under the GPL-3.0 license.