FAST Data Processor

FAST Data Processor 是一个用于 FAST PSRFITS 数据预处理的 Python 工具包。它可以从 filelist.txt 读取 FITS 文件列表，完成频谱绘图、偏振合并、频率通道裁剪、TBIN 行裁剪、频率下采样，并将处理后的 FITS 文件合并为一个最终 FITS 文件。

完整使用文档：

• 中文文档
• English Documentation

功能概览

• 读取 filelist.txt，支持空行和 # 注释。
• 相对路径会按 filelist.txt 所在目录解析。
• 自动跳过损坏或无法读取的 FITS 文件，并在输出目录写入 skipped_files.txt。
• 绘图阶段默认并行执行。
• process 和 pipeline 的逐文件处理阶段默认并行执行，最终 FITS 合并阶段串行执行。
• 默认输出 tot 偏振产品，将前两个偏振流归一化后平均为总强度 I。

项目结构

fast-data-processor/
├── fast_data/
│   ├── cli.py                  # 命令行入口
│   ├── config.py               # 配置定义
│   ├── core/processor.py       # 核心流程编排
│   ├── io/fits_handler.py      # FITS 读写与 header 处理
│   ├── operations/
│   │   ├── downsample.py       # 裁剪、偏振合并、频率下采样
│   │   └── merge.py            # FITS 合并与自动命名
│   ├── utils/parallel.py       # 并行处理辅助
│   └── visualization/plotter.py # 频谱图生成
├── docs/
│   ├── README_zh.md            # 中文完整文档
│   └── README_en.md            # English user guide
├── requirements.txt
├── setup.py
└── README.md

安装

建议在 Python 虚拟环境中安装：

python -m venv .venv
source .venv/bin/activate
pip install -e .

安装后可以使用命令行入口：

fast-process --help

也可以直接从源码目录运行：

python -m fast_data.cli --help

输入文件列表

filelist.txt 每行写一个 FITS 文件路径：

PSRJ0002+6216_swiftcalibration-M18_0069.fits
PSRJ0002+6216_swiftcalibration-M18_0070.fits
PSRJ0002+6216_swiftcalibration-M18_0071.fits

如果 filelist.txt 位于 /obs/run1/filelist.txt，其中的相对路径 data/a.fits 会解析为 /obs/run1/data/a.fits。

命令

当前命令行提供三个子命令：

fast-process plot --help
fast-process process --help
fast-process pipeline --help

plot

只生成频谱图，不生成处理后的 FITS：

fast-process plot \
  --filelist filelist.txt \
  --output-dir plots/ \
  --ncpus 8

常见输出：

<input_stem>_all_pols.png
plotted_files.txt
skipped_files.txt

process

不绘图，只执行偏振合并、裁剪、下采样和最终合并：

fast-process process \
  --filelist filelist.txt \
  --output-dir processed/ \
  --fdsamp 4 \
  --ncpus 8

指定最终合并文件路径：

fast-process process \
  --filelist filelist.txt \
  --output-dir processed/ \
  --output processed/merged.fits \
  --ncpus 8

pipeline

先绘图，再执行完整处理和最终合并：

fast-process pipeline \
  --filelist filelist.txt \
  --output-dir results/ \
  --plot-start-freq 400 \
  --plot-downsample 64 \
  --ncpus 8

默认裁剪规则

处理阶段如果没有显式指定 --start-freq 或 --end-freq：

• OBSNCHAN = 4096 时使用历史默认范围：start_freq = 408，end_freq = 3687。
• 其他通道数会在上下频带边缘各裁掉 10%。

处理阶段如果没有显式指定 --start-time 或 --end-time：

• NAXIS2 = 128 时使用历史默认范围：start_time = 0，end_time = 127。
• 其他行数默认保留全部 TBIN 行。

输出命名

如果没有指定 --output，最终合并文件会根据 filelist.txt 中第一个和最后一个有效文件名自动生成。例如：

PSRJ0002+6216_swiftcalibration-M18_0069.fits
PSRJ0002+6216_swiftcalibration-M18_0073.fits

会生成：

PSRJ0002+6216_swiftcalibration-M18_0069-0073.fits

更多参数、输出说明和偏振处理细节请查看 中文完整文档。