Metadata-Version: 2.4
Name: heapyx
Version: 0.2.3
Summary: High-energy (X-ray and gamma-ray) astronomical data analysis tools
Home-page: https://github.com/jyangch/heapy
Author: Jun Yang
Author-email: jyang@smail.nju.edu.cn
License: GPLv3
Project-URL: Source Code, https://github.com/jyangch/heapy
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.4
Requires-Dist: pandas>=1.4.2
Requires-Dist: scipy>=1.8.0
Requires-Dist: astropy>=5.2.2
Requires-Dist: matplotlib>=3.2.1
Requires-Dist: tqdm>=4.64.1
Requires-Dist: plotly>=5.22.0
Requires-Dist: kaleido>=0.2.1
Requires-Dist: pybaselines>=1.1.0
Requires-Dist: pycwt>=0.3.0a22
Requires-Dist: scikit-learn>=1.0
Requires-Dist: healpy>=1.16
Requires-Dist: cartopy>=0.21
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<h1 align="center">HEAPY</h1>

<p align="center">
  <strong>A Python toolkit for data reduction, temporal analysis, and spectral extraction of X-ray and gamma-ray transients.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/heapyx/"><img alt="PyPI" src="https://img.shields.io/pypi/v/heapyx?color=4F46E5&labelColor=1f2937&logo=pypi&logoColor=white"></a>
  <a href="https://github.com/jyangch/heapy/tree/main/examples"><img alt="Examples" src="https://img.shields.io/badge/docs-examples-06B6D4?labelColor=1f2937"></a>
  <a href="https://www.gnu.org/licenses/gpl-3.0"><img alt="License GPL-3.0" src="https://img.shields.io/badge/license-GPL--3.0-9CA3AF?labelColor=1f2937"></a>
</p>

---

`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`](https://gammaray.nsstc.nasa.gov/gbm/)/GBM, GECAM, GRID,
[`Einstein Probe`](https://ep.bao.ac.cn/) (WXT/FXT), and
[`Swift`](https://swift.gsfc.nasa.gov/) (XRT/BAT). It bridges to
[`HEASoft`](https://heasarc.gsfc.nasa.gov/docs/software/heasoft/) and
[`gbm_drm_gen`](https://github.com/grburgess/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:

```bash
pip install heapyx
```

### Optional: `HEASoft`

For some missions (e.g., `Swift`), `heapy` invokes `HEASoft` tools such as
`xselect` and `ximage`. Ensure
[`HEASoft`](https://heasarc.gsfc.nasa.gov/docs/software/heasoft/#install) is
installed, along with the
[`Calibration Database`](https://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/install.html)
(CALDB) for the mission you are processing.

### Optional: Fermi GBM response generator

To build response matrices for Fermi/GBM, `heapy` calls
[`gbm_drm_gen`](https://github.com/grburgess/gbm_drm_gen). The forked
packages below are fine-tuned for newer `numpy`/`astropy` and use TTE
instead of CSPEC data:

```bash
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](https://github.com/jyangch/heapy/tree/main/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](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

```bibtex
@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](https://www.gnu.org/licenses/gpl-3.0-standalone.html) license.
