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 viaSwiftBurstAnalyserFetcher(3-tier strategy, BadBin preservation, requires theukssdcextra). Local XRT product directories are preferred.--request-xrtis the only switch that can submit an UKSSDC job; its saved state is resumed by--poll-xrtand 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_hspgrouping with interval0 RMF/ARF links. - fit —
jinwu.core.fit.fit_preparedper segment with the research modeltbabs*ztbabs*cflux*powerlaw, frozen Galactic N_H, catalog redshift (requires a HEASoft/PyXspec environment). - report —
grb_summary.json,summary.txt, andspectral_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
同样的参数也可直接运行带注释的
examples/bat_survey_pipeline.py;它支持
--until、--no-resume、本地 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jinwu_swift-0.3.0.tar.gz | 136.2 kB | Without provenance | Details for jinwu_swift-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jinwu_swift-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for jinwu_swift-0.3.0-py3-none-any.whl |
Total release size: 254.5 kB
Release files / jinwu_swift-0.3.0.tar.gz
| Download URL | jinwu_swift-0.3.0.tar.gz |
|---|---|
| Size | 136.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1df63272a4c34b886be4b47b0eac4d8cf59d7e30c282aebd0a81e89f8e77c742
|
|
BLAKE2b-256 checksum How to use checksums |
31239c5b0e1f830c56256e0f108e564e463f03667d3eaa72b4fb2dda6d39a62f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / jinwu_swift-0.3.0-py3-none-any.whl
| Download URL | jinwu_swift-0.3.0-py3-none-any.whl |
|---|---|
| Size | 118.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5283308f65e9e5c36d5ff7c941621220e622600deb6c3517aea2cda4e9f4424f
|
|
BLAKE2b-256 checksum How to use checksums |
65e798b46de627afdba84eb624c8736c47696524f63589dca54bf2ad65339a54
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Security for jinwu-swift 0.3.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.