nmrglue

nmrglue: 校正済み 1D FID 処理

使用する場面

取得パラメータと複素周波数の規約が利用可能な、均一にサンプリングされた複素 1D FID に使用します。このヘルパーは、降順の ppm スペクトル、正のピーク候補、符号付きの領域積分値、および再現可能な処理レポートを生成します。化合物の同定や共鳴の帰属は行いません。

この実行ファイルは、正確に 1 つの複素 fid 配列を含む NumPy .npz、または正規の 1D 複素時間領域 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 後に適用されます。 インデックス 0 は高 ppm 側の端です。暗黙のピボットや自動位相推定はありません。
5. 明示的に指定された ppm 領域がシグナルフリーである場合にのみ、線形ベースラインをフィッティングします。 baseline を linear に設定し、少なくとも 2 つの領域を含む 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 であることを立証できません。

この実行可能な合成例は、指定された設定に一致し、1:2 の振幅比で 3 ppm と 7 ppm に共鳴を生成します。実験試料を表すものではありません:

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 の処理ソースを参照してください。 多次元処理、非等間隔サンプリング、自動帰属、および実験的なベンダーインポートは、 このヘルパーの検証済みスコープ外のままです。