Skip to main content

jinwu-swift

Swift/BAT instrument support for the jinwu analysis toolkit: BAT observation handling, attitude reconstruction and survey/posted data products.

pip install jinwu-swift

Import as jinwu.swift, e.g. from jinwu.swift.bat import BATObservation.

Optional extras

pip install "jinwu-swift[gdt]"     # gdt-swift: SAO/poshist 指向文件读取与天图
pip install "jinwu-swift[ukssdc]"  # swifttools: UKSSDC 目录查询与 Burst Analyser 下载
pip install "jinwu-swift[survey]"   # BatAnalysis + HEASARC query for BAT survey

Without the gdt extra the core BAT workflows work; SAO/poshist-based features degrade gracefully (jinwu.swift.bat.bat_observation.HAS_GDT_SWIFT is False).

BAT+XRT GRB pipeline (jinwu.swift.grb)

Resumable per-GRB pipeline ported from the swift_highz_grb research workflow, registered as "swift.grb" and built on jinwu.core.pipeline:

catalog → download → {lightcurve, prompt, galactic_absorption, bblocks}
        → spectra → fit → report
  • catalog — resolve the GRB in catalog/swift_grb_catalog_merged.csv (research merge of SDC/UK_XRT/BAT_GRB) with redshift priority selection and the NASA BAT duration windows (bat_t90_start_s/stop_s).
  • download — verify Burst Analyser parsed/ products; optionally fetch via SwiftBurstAnalyserFetcher (3-tier strategy, BadBin preservation, requires the ukssdc extra). Local XRT product directories are preferred. --request-xrt is the only switch that can submit an UKSSDC job; its saved state is resumed by --poll-xrt and an ambiguous submission is never sent a second time automatically.
  • lightcurve — BadBin-filtered BAT + XRT WT/PC flux series → NPZ + three-panel figure (flux / N_H / Γ) in the research styling.
  • prompt — strict prompt-stage judgment (XRT start inside the absolute BAT T90 window); missing inputs yield UNDECIDED.
  • galactic_absorption — weighted Galactic N_H via jinwu.core.galactic.resolve_galactic_absorption (cached per workspace).
  • bblocks — Bayesian blocks on XRT source/background events (WT per-GTI, PC per observation, GTI fallback), Li-Ma significance with SRCAREA/BGAREA alpha, and low-SNR merging. An absent area scale stops that segment rather than assuming alpha = 1.
  • spectra — XSELECT source/background PHA per segment (right edge +ε), grppha_hsp grouping with interval0 RMF/ARF links.
  • fit — jinwu.core.fit.fit_prepared per segment with the research model tbabs*ztbabs*cflux*powerlaw, frozen Galactic N_H, catalog redshift (requires a HEASoft/PyXspec environment).
  • report — grb_summary.json, summary.txt, and spectral_parameters.csv; the optional overlay is written as a separate report NPZ/PNG and never rewrites the lightcurve-stage NPZ.

SwiftGRB in jinwu.core.config is the public preset. Its BAT Burst Analyser product is SNR5_sinceT0:BATBand and BATBand is 15--50 keV; that product band is distinct from Swift/BAT's 15--150 keV instrument range. XRT fitting uses 0.3--10 keV, C-stat (reported as W-stat when a Poisson background is loaded), group 20, and Δstat=1 profile errors.

Run from the command line against a research-style workspace:

python -m jinwu.swift.grb \
    --root ~/research/swift_highz_grb/output \
    --grb 050904 --nh 0.09 --output-dir /tmp/grb050904_jinwu
# --until bblocks 只跑到某阶段;--no-resume 忽略缓存;缺失网络产品时该阶段
# 记为 needs_review,补齐数据后重跑即从断点继续

# Only with a registered UKSSDC XRT-product account:
python -m jinwu.swift.grb --root ~/research/swift_highz_grb/output --grb 050904 \
    --request-xrt --xrt-user "$SWIFT_XRT_USER"

Python API:

from jinwu.core.config import SwiftGRB
from jinwu.core.pipeline import pipeline
from jinwu.swift.grb import SwiftGRBInput

result = pipeline(
    SwiftGRB(),
    SwiftGRBInput(target_id="050904", root=workspace,
                  output_root="/tmp/grb050904_jinwu",
                  xrt_products_dir=workspace / "xrt_product_requests_maybe/downloads/GRB_050904"),
).run()

BAT survey 单目标管线 (jinwu.swift.bat.survey)

该入口处理一个已知位置的 Swift/BAT survey 目标,流程为:

预检 → 观测发现 → 可选下载 → survey → 光变 → 可选 mosaic → PHA/响应 → 拟合或上限 → 报告
from jinwu.core.config import BATSurvey
from jinwu.swift.bat.survey import BATSurveyInput, BATSurveyPipeline

job = BATSurveyInput(
    target_id="NGC4253",
    root="/data/swift/batdata",
    output_root="/tmp/ngc4253_bat_survey",
    source_name="NGC4253",
    coord=(183.5625, 29.8125),       # ICRS degrees
    obsids=("00098092002",),
    time_windows=(("2024-07-16T12:00:00", "2024-07-16T13:00:00"),),
    download=False,                  # local-first; explicit opt-in
    mosaic=False,
)
result = BATSurveyPipeline(job, config=BATSurvey()).run()
print(result.science_status, result.products["report"])

命令行等价用法:

python -m jinwu.swift.bat.survey NGC4253 \
  --root /data/swift/batdata --output /tmp/ngc4253_bat_survey \
  --source-name NGC4253 --ra 183.5625 --dec 29.8125 \
  --obsid 00098092002 \
  --window 2024-07-16T12:00:00 2024-07-16T13:00:00

更多参数及公共 Python 接口见BAT survey 指南。 命令行支持本地 survey/mosaic 路径,以及显式查询、下载、并行和超时选项。

已有结果可用 --survey-products 或 --mosaic-products 直接接入;原始单观测目录 可用 --raw-products 指定。--until 和 --no-resume 分别控制阶段停止和缓存恢复。

--query 和 --download 分别显式启用在线发现和下载,--mosaic 启用时间窗 mosaic,--profile lmjagn 使用参考项目的 8000/0.01 筛选配置,默认配置仍为 10000/0.05。survey 率保留 CENT_RATE 的正负号,优先使用 RATE_ERR,并保留 BKG_VAR 供产品定义的 SNR 和缺失误差回退;它们是 Gaussian count/s/fully illuminated detector 测量,不是能流。请求窗口 和实际完整指向曝光分开写入报告,短窗口不会把完整指向 PHA 按比例缩放。 每个 survey CAT 的八个原生能道会保留,并在没有附带总能段时按误差平方和推导一个 第九个总能段;已有第九列不会再次累加。RATE_ERR 优先作为源率误差,只有缺失时 才回退到 BKG_VAR,而 Flux/ECF 推导的结果会标记为计数率来源。仅有 batsurvey.pickle 或完成标记的目录不会被当作可用科学产品;PHA、响应和处理状态 会在光谱阶段重新核验。兼容的 QDP 光变会标记为 native_qdp_rate,但因其只给出 单点时间误差,不会被当作完整指向曝光参与窗口谱选择。 若结果树含有逐指向 *.gti,光变选择会记录真实 GTI 重叠;该重叠只用于窗口覆盖 判定,完整 survey 曝光和 PHA 不会按重叠比例缩放。

BAT survey 光谱的上限使用带符号 RATE 的 Gaussian profile:STAT_ERR 是统计误差, OGIP SYS_ERR 只转换并加入一次,BKG_VAR 只用于原生 TOTSNR 的灵敏度校准,不会 混入光谱拟合误差。响应模板用同一 PHA/RSP 通过 fakeit(applyStats=False) 生成,默认 固定 Γ=2、Δχ²=9(单侧高斯等效置信度 0.9986501019683699)。每个结果分别保存 observed_upper_bound(本次观测的条件 profile)和 detection_sensitivity(空白控制 样本加固定位置注入的 90% 检出灵敏度);没有足够控制尾部时后者明确为 calibration_status=unavailable,不会用人工 nσ×BKG_VAR PHA 代替。

# 明确提供空白 survey 控制表后才会估计固定位置灵敏度
python -m jinwu.swift.bat.survey AT20G_J182338-345412 \
  --root /data/swift/batdata --survey-products /data/swift/00097302084_surveyresult \
  --sensitivity-controls /data/swift/blank_sky_sources.fits \
  --output /tmp/at20g_bat --obsid 00097302084 \
  --window 2024-07-16T12:06:10 2024-07-16T12:19:58

--sensitivity-controls 必须来自源不活跃、质量筛选一致的八能道 survey 产品;其 BKG_VAR 是局部天空噪声,不与 PHA STAT_ERR 相加。--profile lmjagn 只改变参考项目 确认过的 8000/0.01 筛选和 0.01 mosaic 部分编码门槛,不改变能段或上限统计契约。

需要控制资源时,可在命令行追加 --processes N、--internal-threads 1 和 --task-timeout SECONDS。网络阶段可分别用 --network-timeout、--retries、 --retry-wait 和 --query-margin 调整;每个阶段仍会在工作区下使用独立的 PFILES 和日志位置。

HEASoft/XSPEC 测试应在 hea 环境中运行。conda run 不会自动 source HEASoft 的初始化脚本,因此管线在可选的 Swift 后端边界补齐 heainit.sh 所需的 HEADAS、Perl/PGPLOT 运行变量,并为每个阶段建立可写的 HOME、PFILES 和临时目录;核心配置导入仍不会加载 BatAnalysis 或发起网络请求。

# 纯离线契约测试
PYTHONPATH=$PWD/packages/jinwu/src:$PWD/packages/jinwu-swift/src \
  conda run --no-capture-output -n hea python -m pytest \
  packages/jinwu-swift/tests/test_bat_survey.py -q -p no:cacheprovider

# 本地 AT20G PHA/RSP 的 XSPEC 上限验收(显式 opt-in)
JINWU_RUN_REAL_DATA=1 \
  PYTHONPATH=$PWD/packages/jinwu/src:$PWD/packages/jinwu-swift/src \
  conda run --no-capture-output -n hea python -m pytest \
  packages/jinwu-swift/tests/test_bat_survey_heasoft.py -q -p no:cacheprovider

真实观测查询、下载和在线 mosaic 均默认关闭;只有显式加入 --query、 --download 或 --mosaic 才会启用相应阶段。未设置注册的 Swift/UKSSDC 账号时, 不要提交在线产品请求。

Metadata

Release files for jinwu-swift 0.3.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jinwu-swift 0.3.3
File Size Uploaded Provenance Actions
jinwu_swift-0.3.3.tar.gz 136.3 kB With provenance Details for jinwu_swift-0.3.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jinwu-swift 0.3.3
File Interpreter ABI Platform Actions
jinwu_swift-0.3.3-py3-none-any.whl Python 3 none any Details for jinwu_swift-0.3.3-py3-none-any.whl

Total release size: 254.7 kB

Release files / jinwu_swift-0.3.3.tar.gz

Download URL jinwu_swift-0.3.3.tar.gz
Size 136.3 kB
Tags Source
SHA-256 checksum
How to use checksums
0204ce4c286133d82e883824d2271b8e53c84d922cb8512e68e379034f514aee
BLAKE2b-256 checksum
How to use checksums
6f048e130e0ee54761c3cbec1f14b9cfadc63dd07610688a6f86af452905e60f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / jinwu_swift-0.3.3-py3-none-any.whl

Download URL jinwu_swift-0.3.3-py3-none-any.whl
Size 118.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0d753bd0955ed6c31bd234a1175926fa8831aa23f76a16faa1fc5b491031c848
BLAKE2b-256 checksum
How to use checksums
fe044f9b2b38af09464326b92c44911591a533eb97c37101a24bd4c885b2d6bf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for jinwu-swift 0.3.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for jinwu_swift-0.3.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page