EPTools

A Python package for Einstein Probe (EP) data analysis, also supporting other X-ray instruments (e.g., Swift-XRT).

Installation

Prerequisites

• Python >= 3.8
• Heasoft with PyXspec correctly configured in your $PYTHONPATH

Install via pip

git clone https://github.com/LAujust/EPTools.git
cd EPTools
pip install -r requirements.txt
pip install .

Required Python packages

The core dependencies (numpy, scipy, matplotlib, pandas, astropy, astroquery) will be installed automatically. For GW-related functionality, additional packages are listed in requirements.txt.

Quick Start

TA spectral + temporal analysis (recommended)

The EPTA class provides an object-oriented pipeline for spectral fitting and light-curve analysis. Defaults are loaded from the shipped ta_config.json; any keyword argument overrides them.

from EPTools.ta import EPTA, load, estimate_nh

# 1. Load defaults (optional)
cfg = load(ins="WXT")
print(cfg["energy_ranges"])

# 2. Estimate Galactic nH from source coordinates
ra, dec, dist = 141.32, 52.30, 500.0   # degrees, pc
reddening, nh = estimate_nh(ra, dec, dist)

# 3. Configure and run the pipeline
ta = EPTA(
    obsid="ep11908837634", snum="s1",
    root="path/to/data",
    ins="WXT", nH=nh,
    grp=True, group=20,
)
ok, msg = ta.run()
print(msg)

# 4. Verify results
files_ok, report = ta.check_files()
fit_ok,  report = ta.check_fit_results()
plot_ok, report = ta.check_plots()

The pipeline can also be executed step by step:

ta = EPTA(obsid="ep11908837634", snum="s1", root="path/to/data", ins="WXT")
ta.change_root()
ta.find_files()
ta.group_pha()           # runs grppha if grp=True
fitted, params = ta.fit_model("powerlaw")
ta.fit_all_models()
ta.plot_lightcurve()

Results from fit_all_models are saved as PNG plots and CSV tables. A timestamped log file ({obsid}_{snum}_ta.log) is created automatically.

WXT lightcurve and spectrum analysis (original API)

The original TA_quick function is still available for backward compatibility:

import EPTools

root = 'path/to/your/data'
obsid = 'ep01709201259wxt37'
snum = 's6'

EPTools.TA_quick(
    obsid, snum, root,
    binsize=100,
    grp=True,
    group=1,
    ins='WXT',
    plotstyle='line',
    chatter=0,
)

Lightcurve extraction

Use EPTools.analysis to extract source and background lightcurves from event files via xselect:

from EPTools.analysis import extract_curve_sh, subtract_curve

extract_curve_sh(
    evtfile='path/to/evt.fits',
    src_reg='src.reg',
    bkg_reg='bkg.reg',
    binsize=10,
)

subtract_curve('src.lc', 'bkg.lc', alpha=1/12.0, out_file='net.lc')

Spectral fitting with Xspec

from EPTools.fit import xspec_fitting

xspec_fitting(
    'src.pi', 'model_name',
    grp=True,
    rebin=2,
    stat='cstat',
    instrument='WXT',
    chatter=10,
)

Plotting

from EPTools.plot import lcurve_plot, xspec_plot

# Plot background-subtracted lightcurve
lcurve_plot('src.lc', 'bkg.lc', binsize=10, scale=1/12.0)

# Plot Xspec fit results
xspec_plot(data, save_dir='./plots', plotstyle='step')

Cross-matching

from EPTools.crossmatch import match_cat

result = match_cat('source.cat', 'catalog.cat', radius=5.0)

Unit conversions

from EPTools.utils import keV2erg, mag2flx, flx2lum

# Convert keV to erg
energy_erg = keV2erg([0.5, 2.0])

# Convert AB magnitude to flux
flux = mag2flx([20.0, 21.5])

# Convert flux to luminosity
lum = flx2lum(flux=1e-14, d=100)  # distance in Mpc

Modules

Module	Description
EPTools.ta	EPTA class — object-oriented TA pipeline (file discovery, grppha, XSPEC fitting, plotting, logging, success checks)
EPTools.utils	General utilities, unit conversions, GCN retrieval
EPTools.analysis	Lightcurve/spectrum extraction via xselect, response file generation
EPTools.fit	Xspec fitting, nH estimation, count-rate-to-flux conversion, dynesty Bayesian fitting
EPTools.plot	Lightcurve, spectrum, and FITS image plotting
EPTools.crossmatch	Source catalog cross-matching
EPTools.gw_em	Gravitational-wave EM counterpart tools, EP observation planning
EPTools.model	Physical models

Useful Links

• ASAS-SN forced photometry
• ATLAS forced photometry
• Alerce and Lasair for ZTF sources
• HEASARC High-Energy Source Portal — historical X-ray observations
• eROSITA DR1 Catalogue
• NH Column Density Tool
• RapidGBM — Fermi-GBM sky coverage
• DataFusion — EP coverage and ToO planning
• BAT Target Search Portal — Swift-BAT coverage
• Astro-Colibri — transient information aggregator
• Legacy Survey — deep optical imaging

Documentation

Full documentation is available at eptools.readthedocs.io.

---

© Runduo Liang (Aujust)