nmrglue

nmrglue：经过校准的一维 FID 处理

使用场景

适用于均匀采样的复数一维 FID，且其采集参数和复数频率约定已知的情况。该辅助工具会生成按降序排列的 ppm 谱图、正峰候选、带符号的区域积分以及可复现的处理报告。它不识别化合物，也不指认共振信号。

该可执行程序接受包含恰好一个复数 fid 数组的 NumPy .npz，或规范的一维复数时域 NMRPipe 文件。NMRPipe 读取已通过合成写入/读取往返测试、已知谱图恢复测试，以及一个小型上游 NMRPipe 生成的二进制测试样本进行验证。实验性的 Bruker、Varian 和 JEOL 导入未经此测试套件验证。对于这些格式，请先检查相应的 nmrglue 读取器和采集元数据。打开转换后的文件并不能验证原始采集解码是否正确。 阅读 references/acquisition-and-validation.md 了解转换边界、轴校准和定量限制。

工作流

1. 保留原始 FID。确定以 Hz 为单位的谱宽、以 MHz 为单位的正观测频率、以 ppm 为单位的载波、观测核素，以及来自采集或已知参考的符号约定。判断是否已经执行过数字滤波器/群延迟去除。不要根据数组长度或典型仪器默认值推断这些参数。
2. 复制 assets/processing.json，并将其中的合成示例值替换为实测参数和明确的处理选择。其符号 -i 表示偏移为 f = (ppm - carrier_ppm) * observation_mhz 的共振信号具有时间依赖关系 exp(-2*pi*i*f*t)。只有在采用相反约定时才选择 +i；辅助工具会在处理前对其取共轭。使用已知参考峰进行验证。
3. 选择非负的指数线展宽（Hz）、不小于已采集 FID 大小的偶数补零大小、首点缩放和相位角。 补零可改善插值，而非提高已采集的谱分辨率。 首点缩放 0.5 适用于所提供的因果合成示例； 采集和先前的预处理可能需要其他值。
4. 运行辅助工具，检查实部和虚部谱图，必要时修正手动相位。phase0_deg + phase1_deg * index / zero_fill_points 在 FT 之后应用；索引零位于高 ppm 边缘。不存在隐式枢轴点或自动相位估计。
5. 仅在明确提供的 ppm 区域无信号时，才拟合线性基线。将 baseline 设为 linear，并添加至少包含两个区域的 baseline_regions_ppm。检查残差和宽峰；穿过信号进行拟合会使积分产生偏差。
6. 将峰位置与参考进行比较，检查峰候选是否为伪影，并对指定区域进行积分。将重叠峰报告为重叠。保留负面积作为相位/基线问题的诊断证据，而不是取绝对值。

执行

已使用 Python 3.12、nmrglue 0.12、NumPy 2.5.3 和 SciPy 1.18.1 测试：

uv run --no-project --python 3.12 --with nmrglue==0.12 --with numpy==2.5.3 --with scipy==1.18.1 \
  python skills/nmrglue/scripts/process_1d.py fid.npz processing.json nmr-result

路径假定为集合根目录。安装在其他位置时请相应调整。输出目录必须是新的，这样重复处理时仍可审查之前的结果。

对于已有的 1D NMRPipe FID，请添加 --input-format nmrpipe，并提供其路径以代替 fid.npz。该辅助工具要求规范的 FDF2 直接维度、复数正交检测、时域标志，并且头信息与 JSON 的光谱宽度、观测频率和载波必须一致。JSON 设置保持显式；不一致时将失败，而不是静默重新校准。FDF2TDSIZE 必须等于存储的复数点数量，且 FDF2CENTER / FDF2ORIG 必须描述规范的居中轴。此前经过补零、截断或重新居中的文件需要单独的采集感知工作流。核种/复数符号以及此前的数字滤波校正仍需要采集证据。仅凭时域标志并不能确认这是未处理的 FID。

这个可执行的合成示例与所提供的设置相匹配，在 3 和 7 ppm 处生成共振峰，幅度比为 1:2，并不代表实验样品：

import numpy as np

t = np.arange(8192) / 4000.0
fid = sum(a * np.exp(-np.pi * 2.0 * t)
          * np.exp(-2j * np.pi * (ppm - 5.0) * 400.0 * t)
          for ppm, a in [(3.0, 1.0), (7.0, 2.0)])
np.savez("fid.npz", fid=fid)

使用 assets/processing.json 作为设置参数运行它。仓库测试套件会执行该信号和 CLI，检查两个峰位置是否在 0.001 ppm 以内，检查积分比与解析面积，并检查相位和基线恢复。NMRPipe 往返测试使用 ng.pipe.create_dic/ng.pipe.write 写入此 FID，通过 CLI 读取它，并验证恢复的峰和积分比。已处理的频域文件和冲突的校准元数据会被拒绝。

2,176 字节的上游夹具使用由 NMRPipe 的 simTimeND / SET 工具生成的文件，检查复数采样顺序和头信息校准。这些原生工具并未在本次审查中运行；这是夹具兼容性检查，而非实时 NMRPipe 处理比较。

交付物与解释

• spectrum.csv：ppm 降序、基线校正后的实信号、经相位调整的虚信号，以及拟合的实基线。绘制 NMR 图时，高 ppm 端位于左侧。
• report.json：输入/设置的 SHA-256、软件包版本、所有设置、采集时长、补零后的数字间隔、正峰候选，以及带符号的区域面积。

积分使用端点插值并沿递增 ppm 方向进行梯形积分；面积单位是任意信号乘以 ppm，与显示方向无关。超出采样 ppm 轴范围的区域会失败，而不是被静默裁剪。峰显著度是最大正实强度的一个分数；它不是由噪声推导出的检测限。在默认阈值下，强溶剂信号可能掩盖弱候选峰。

对于定量 NMR，还需确定弛豫延迟、脉冲角、饱和、接收机行为、内标/外标用量以及积分不确定度。该辅助工具不计算浓度，也不校正不等的弛豫。请将这些限制与结果一并保留，而不要将任意面积转换为分子数量。

上游契约

• 处理函数： 指数切趾、补零、FFT 和相位操作。
• 文件和轴工具： 单位转换使用以 Hz 为单位的谱宽、以 MHz 为单位的观测频率、以 Hz 为单位的载波。
• NMRPipe 读取器/写入器： 经验证的摄取路径是合成的规范 1D 时域往返。
• nmrglue 项目：上游源代码和格式读取器。

托管在 latest 的文档在检查时自称为 0.9-dev；实际测试的是 0.12 包的 API 和数值行为。其 proc_base.fft 使用负指数 NumPy FFT 后接 fftshift；NMRPipe 的 FT 约定对应 fft_positive，因此不要在不重新审视 FID 符号和相位的情况下替换它。 参见 v0.12 处理源代码。 多维处理、非均匀采样、自动指认和实验性厂商导入仍在此辅助工具的经验证范围之外。