Quick Start

A quick guide for using EPTools as a Transient Advocate (TA) and for subsequent data analysis.

Installation

Prerequisites

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

From Source

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

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

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()

Step-by-step execution:

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()

The pipeline automatically creates a timestamped log file ({obsid}_{snum}_ta.log). Use ta.setup_logfile(path) to redirect it.

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