API Reference#

This page documents the public API of JinWu, auto-generated from docstrings.

Core Package#

jinwu.core Package#

autohea.core#

Core utilities for OGIP FITS IO and helpers.

This package layer exposes: - Submodules such as file, heasoft, plot, time. - Numpy-first OGIP readers in core.file for ARF/RMF/PHA/LC/EVT, returning

concrete dataclasses with kind and path fields.

Typical usage#

from autohea.core import readfits, guess_ogip_kind from autohea.core import read_arf, read_pha, OgipPhaReader from autohea.core import band_from_arf_bins, ChannelBand

Functions#

band_from_arf_bins(arf_path[, bin_lo, bin_hi])

channel_mask_from_ebounds(ebounds, band[, ...])

guess_ogip_kind(path)

readfits(...)

read_arf(path)

read_rmf(path)

read_pha(path)

read_lc(path)

read_evt(path)

write_arf(data, outpath, *[, overwrite])

write_rmf(data, outpath, *[, overwrite])

write_pha(data, outpath, *[, overwrite])

write_lc(data, outpath, *[, overwrite])

write_evt(data, outpath, *[, overwrite])

writefits(-> ~pathlib.Path  -> ~pathlib.Path)

slice_lightcurve(lc[, tmin, tmax])

按时间范围筛选光变曲线，返回新实例。

rebin_lightcurve(lc, binsize[, method, ...])

光变曲线时间重采样（rebinning）。

slice_pha(pha, *[, emin, emax, ch_lo, ch_hi])

按能量或道范围筛选 PHA，返回新实例。

rebin_pha(pha, *[, factor, min_counts])

道聚合（rebinning）：按固定因子或最小计数阈值合并道。

slice_events(evt[, tmin, tmax, pi_min, ...])

按时间和/或能量范围筛选事件，返回新实例。

rebin_events_to_lightcurve(evt, binsize, *)

从事件数据生成分 bin 光变曲线。

netdata(source[, background, ratio, ...])

计算净光变曲线（源 - 背景）

Classes#

EnergyBand(emin, emin_unit, emax, emax_unit)

ChannelBand(ch_lo, ch_hi)

RegionArea(role, shape, area, component)

RegionAreaSet(src, bkg, unk)

HduHeader(name, ver, header)

FitsHeaderDump(primary, extensions)

OgipMeta(telescop, instrume, detnam, ...)

ArfBase(path, header, Any], meta, ...)

Pure field-only base dataclass for ARF response data.

RmfBase(path, header, Any], meta, ...)

Pure field-only base dataclass for RMF response data.

PhaBase(path, header, Any], meta, ...)

Pure field-only base dataclass for PHA spectrum data.

ArfData(path, header, Any], meta, ...)

Concrete ARF data class with local behavior implementation.

RmfData(path, header, Any], meta, ...)

Concrete RMF data class with local behavior implementation.

PhaData(path, header, Any], meta, ...)

Concrete PHA data class with local behavior implementation.

LightcurveDataBase(path, header, meta, ...)

Pure field-only base dataclass for lightcurve data.

LightcurveData(path, header, meta, headers_dump)

Concrete lightcurve data class with local behavior implementation.

EventDataBase(path, header, Any], meta, ...)

Pure field-only base dataclass for event data.

EventData(path, header, Any], meta, ...)

Concrete event data class with local behavior implementation.

timescale(source, *[, background, alpha, ...])

事件时标分析器（独立于 EventData.plot）。

LightcurveDataset(data[, labels])

光变曲线容器类（支持多条曲线统一绘图）

SpectrumDataset(data[, label, background])

High-level spectral dataset container.

JointDataset(lightcurves, spectra)

A simple container for multiple datasets.

OgipArfReader(path)

OgipRmfReader(path)

OgipPhaReader(path)

OgipLightcurveReader(path)

OgipEventReader(path)

ArfReader(path)

RmfReader(path)

RspReader(path)

LightcurveReader(path)

PhaWriter(data, outpath)

ArfWriter(data, outpath)

RmfWriter(data, outpath)

LightcurveWriter(data, outpath)

EventWriter(data, outpath)

Variables#

OgipData

__version__

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Datasets & Net Data#

jinwu.core.datasets Module#

High-level dataset containers.

These classes wrap lower-level OGIP data structures (e.g. LightcurveData, PhaData, EventData) and provide a uniform, higher-level interface for selection, slicing, merging, and background handling.

The API is intentionally minimal at this stage and can be extended as more concrete analysis needs arise.

Functions#

netdata(source[, background, ratio, ...])

计算净光变曲线（源 - 背景）

Classes#

LightcurveDataset(data[, labels])

光变曲线容器类（支持多条曲线统一绘图）

SpectrumDataset(data[, label, background])

High-level spectral dataset container.

JointDataset(lightcurves, spectra)

A simple container for multiple datasets.

Lightcurve Analysis#

jinwu.lightcurve Package#

Light-curve evaluation and trigger decision utilities.

This module provides tools for light-curve analysis including: - SNR evaluation using Li & Ma statistics - Bayesian blocks and peak detection - Trigger decision logic (sliding, head, cumulative) - Light-curve synthesis and fake data generation

Main Classes:

  • LightcurveSNREvaluator: Compute SNR against time windows

  • TriggerDecider: Determine trigger decisions

  • LightcurveFaker: Generate synthetic light curves

Functions:

  • li_ma_snr: Compute Li & Ma SNR statistic

Example:
>>> from jinwu.lightcurve import LightcurveSNREvaluator, li_ma_snr
>>> evaluator = LightcurveSNREvaluator(lightcurve, background_prior)
>>> snr = li_ma_snr(n_on=100, n_off=50, alpha=1.0)

Functions#

li_ma_snr(n_on, n_off, alpha, *[, signed])

Compute Li & Ma significance (Eq.

Classes#

LightcurveSNREvaluator(time, counts, dt, ...)

Evaluate whether a binned lightcurve can reach a target SNR after T0.

TriggerDecider(time, counts, dt, bg)

Decide triggerability from a binned counts lightcurve or event times.

BackgroundSimple(area_ratio, t_off_ref, ...)

Minimal background configuration for Li & Ma significance.

Background Modeling#

jinwu.background Package#

Background modeling and priors for X-ray spectral fitting.

This module provides: - BackgroundPrior: Prior distributions for background parameters - BackgroundCountsPosterior: Posterior computation from observed counts - BackgroundSpectralPrior: Spectral priors for background modeling

Example:
>>> from jinwu.background import BackgroundPrior
>>> prior = BackgroundPrior(mean=10.0, std=2.0)

Classes#

BackgroundPrior(n_off_prior, t_off, area_ratio)

Background prior based on OFF-region total counts over a known exposure.

BackgroundCountsPosterior(a_total, b, area_ratio)

背景区域计数后验（聚合到选择能段之后）。

BackgroundSpectralPrior(a0, b0, area_ratio, ...)

考虑能谱的背景先验：对所选能道逐道建立 Gamma 先验 λ_k ~ Gamma(a0_k, b0)， 其中 b0=t_ref（FITS 中的总参考曝光），a0_k 是把“计/厘米^2”乘以 OFF 区域有效面积后、 在 t_ref 内的 OFF 区域先验计数（可理解为先验的等效观测计数）。

Spectral Analysis#

jinwu.spectrum Package#

Spectrum generation and synthesis utilities.

This module provides: - XspecKFactory: XSPEC-based spectrum synthesis factory - XspecSession: XSPEC wrapper for fakeit and model evaluation - KConfig: Configuration for spectral K (rate/flux) calculations

Example:
>>> from jinwu.spectrum import XspecKFactory
>>> factory = XspecKFactory()

Functions#

prepare_background_for_fakeit(src_pha, bkg_pha)

基于源/背景 PHA 的 BACKSCAL 比值，生成供 fakeit 使用的背景文件。

Classes#

KConfig(arf, rmf, background, model, params, ...)

K 计算所需的不可变配置对象。 Immutable config for K computation.

XspecSession()

一个轻量的 XSPEC 会话，提供 K 计算能力。 A lightweight XSPEC session that can compute K.

XspecKFactory()

K 计算工厂 + 缓存。

Response Matrix Utilities#

jinwu.response Package#

Response matrix and effective area utilities.

This module provides: - contgbmrsp: Continuous (unbinned) GBM response function

Submodules:

  • gbm: GBM-specific response handling

  • basic: Basic response utilities

Example:
>>> from jinwu.response import contgbmrsp

Classes#

contgbmrsp(ra, dec, start_time, end_time, ...)

用来生成连续观测的 GBM 响应文件，针对非触发情形。 需要通过网页安装的 GBM 响应生成的 Perl 程序，并且所有的数据应该满足特定的文件目录格式。 赤经，单位是度，天文坐标系下的坐标。 赤纬，单位是度，天文坐标系下的坐标。 开始时间, Fermi MET 时间，以秒为单位。 结束时间, Fermi MET 时间，以秒为单位。 探测器代号列表。 生成用于执行 GBM 响应生成的 Perl 脚本的命令字符串。 执行生成的命令字符串，并打印输出或错误信息。 获取赤经。 获取赤纬。 获取开始时间(Fermi MET)。 获取结束时间(Fermi MET)。 获取从探测器代号派生的探测器编号。 获取探测器代号。 设置赤经。 设置赤纬。 设置探测器代号。 设置开始时间(Fermi MET)。 设置结束时间(Fermi MET)。

Timing Analysis#

jinwu.timing Package#

Timing analysis utilities.

This module provides timing-related analysis tools for high-energy astrophysics.

Model Components#

jinwu.model Package#

Spectral and temporal model components with XSPEC-inspired architecture.

This module provides: - ModelBase: Abstract base class for all model components - AdditiveModel: Models that produce spectra to be summed - MultiplicativeModel: Models that modify spectra (absorption, etc.) - ConvolutionModel: Models that convolve input spectra

Example:
>>> from jinwu.model import AdditiveModel, MultiplicativeModel
>>> class PowerLaw(AdditiveModel):
...     def evaluate(self, energy, **kwargs):
...         return energy ** (-self.params['gamma'])

Classes#

ModelBase([name, params])

Common base class for all spectral model components.

AdditiveModel([name, params])

Additive component: returns a spectrum to be summed.

MultiplicativeModel([name, params])

Multiplicative component: returns a transmission factor.

ConvolutionModel([name, params])

Convolution component: transforms an input spectrum.

Physics Utilities#

jinwu.physics Package#

Physics models and utilities for astrophysics.

This module provides: - GeneralRelativity: GR effects (redshift, Doppler, etc.) - Radiation: Radiation transfer and related utilities

Example:
>>> from jinwu.physics import GeneralRelativity
>>> gr = GeneralRelativity()

Classes#

GeneralRelativity()

基础相对论/多普勒与辐射变换工具类

ftools (Pure-Python HEASOFT Equivalents)#

jinwu.ftools Package#

Lightweight Pure-Python HEASOFT ftools equivalents.

This package provides minimal Pure-Python implementations of common HEASOFT ftools functionality, designed to work within JinWu without external Fortran/C dependencies.

Modules:

  • fextract: Extract events into PHA spectra (fextract equivalent)

  • ftgrouppha: Group PHA by minimum counts (ftgrouppha equivalent)

  • ftrbnpha: Rebin PHA to desired channel count (ftrbnpha equivalent)

  • ftrbnrmf: Rebin ARF/RMF to new energy bins (ftrbnrmf equivalent)

  • ftselect: Simple expression filtering for event tables

  • region: DS9 region parsing and point-in-region filtering

  • grppha: Minimal grppha-like grouping

  • teldef: Teldef parsing and coordinate transformations

  • rmf_mapping: RMF to energy mapping

Example:
>>> from jinwu.ftools import fextract, ftgrouppha
>>> pha = fextract.extract(events_file, pha_file)
>>> grouped_pha = ftgrouppha.group_min_counts(pha, min_counts=10)

Einstein Probe#

jinwu.ep Package#

Einstein Probe (EP) mission-specific utilities.

This module provides mission-specific helpers for Einstein Probe observations.

Fermi/GBM#

jinwu.fermi Package#

Fermi mission utilities.

This module provides mission-specific helpers for Fermi observations, including GBM (Gamma-ray Burst Monitor) support.

Submodules:

  • gbm: GBM-specific observation handling

Swift#

jinwu.swift Package#

Application Layer#

jinwu.application Package#

Functions#

netdata(source[, background, ratio, ...])

计算净光变曲线（源 - 背景）