13c-metabolic-flux

炭素13代謝フラックス推定

レビュー済みの炭素マップ、明示的なトレーサー混合物、補正済み標識測定値から、 実行可能なフラックス推定値と、実験によってどのフラックスが制約されるかを示す エビデンスを導きます。同位体収支を再構築したり、各反応を個別にフィッティングしたり せず、同梱のソルバーを使用してください。mfapy の EMU 順方向シミュレーターを実行し、 SciPy を用いて質量収支を満たす実行可能領域内でフラックスをフィッティングします。 FBA の目的関数は使用しません。

対象範囲と必要なエビデンス

この実装が対応するのは、代謝定常状態および同位体定常状態、1 つ以上のトレーサー 実験で共有される単一のフラックス状態、非負の一方向反応フラックス、 および炭素部分集合の質量分布です。可逆反応は、別々にマッピングされた 2 つの方向として 扱います。測定誤差は、与えられた共分散、または開示された対角近似に従うガウス分布です。

フィッティングの前に、以下を取得してください。

• 炭素ネットワークと各原子の割り当て元。化学量論だけでは、標識原子の行き先は 特定できません。区画ごとに別の代謝物 ID を記録してください。
• どちらの定常状態仮定についても、エビデンスを取得してください。代謝物量が安定していても、 同位体定常状態が確立されたことにはなりません。時間経過に伴う標識測定には、プールサイズと 初期標識を含む INST-MFA が必要です。このソルバーで平均化しないでください。
• 同化される場合は、非標識の補充物、重炭酸塩／CO2、およびトレーサー不純物を含む、 すべての炭素入力の位置異性体分布。
• フラグメントの炭素割り当て、天然存在比補正の履歴、および報告された平均値の 不確実性。生のピーク強度、誘導体化スペクトル、MS/MS 遷移を入力として構築するには、 検証済みの前処理が必要です。
• フラックスの単位、細胞外速度の測定値または明記された相対フラックスの基準、および 生物学的に妥当な上下限。標識割合だけでは絶対速度を設定できません。

必要な情報が不足している場合は、その内容を明示して入力テンプレートを用意してください。 フラグメント割り当て、原子マップ、同位体補正、測定誤差を捏造しないでください。 入力の準備時には references/input-contract.md を参照してください。 実際のフィッティング結果を解釈する前に references/inference.md を 参照してください。

テスト済みエンジンのインストール

ユーザーの解析ディレクトリで実行してください。SKILL_DIR には、このスキルが インストールされているディレクトリの実際に解決されたパスを設定してください。 環境と生成された結果は、スキルの外部に保管してください。

uv venv --python 3.11 .venv-mfa
uv pip install --python .venv-mfa/bin/python -r "$SKILL_DIR/assets/requirements.txt"

以下のコマンドでは .venv-mfa/bin/python を使用します。Windows では、環境の Scripts/python.exe を使用してください。mfapy は PyPI で配布されていないため、 変更不可能な Git リビジョンからインストールします。インストール時には依存関係の ビルドコードが実行されます。モデル入力はデータであり、ユーザーが指定する Python コードではありません。アダプターは、mfapy が内部生成する数値関数に渡る前に、 識別子と原子マップの構文を制限します。

ワークフロー

1. 入力を明示的に準備します。 関連するモデル資産を解析ディレクトリにコピーし、 科学的な内容を、レビュー済みの根拠に基づいてのみ置き換えます。同梱モデルは デモ用であり、検証済みの生物種固有の再構成ではありません。生物学的条件ごとに 別々のデータセットを使用します。トレーサーの反復測定を同時にフィッティングするのは、 生物学的フラックス状態が妥当に共通すると判断できる場合に限ります。

2. 仕様と実行可能性を確認します。

   .venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" check \
     --model model.json --data measurements.json --output input-check.json
   

   これにより、原子数と保存則、フラグメント、トレーサーの合計、不確実性行列、 境界、および定常状態の物質収支の実行可能性を確認できます。化学的に整合した 原子マップが生物学的に正しいことや、サンプルが定常状態に達したことまでは 検証できません。

3. 順方向モデルを実行します。 宣言した単位で、物質収支が釣り合ったフラックスベクトルを 1 つ入力します。予測された標識を、参照値または独立に導出した限界値と比較します。

   .venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" simulate \
     --model model.json --data measurements.json --fluxes fluxes.json \
     --output simulated-mdvs.json
   

4. 問いに関連するフラックスをフィッティングし、プロファイルします。

   .venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
     --model model.json --data measurements.json --starts 12 --seed 2026 \
     --profile v3 --profile v7 --profile-points 31 --profile-starts 6 \
     --output fit.json
   

   v3 と v7 を実際の反応 ID に置き換えます。各プロファイル点では、その反応を固定し、 nuisance フラックスを再最適化します。非線形ネットワークでは、プロファイルを解釈する前に、 別のシードとより多くの初期値で繰り返します。残差が小さいことは、識別可能性を示す結果では ありません。

5. 根拠を精査します。 失敗した初期値、残差パターン、物質収支、 有効な境界、局所感度ランク、プロファイルの状態を確認します。しきい値をまたぐ区間は、 実際のグリッド分解能で報告します。粗すぎる場合はグリッドを細分化します。 プロファイルでベースラインより良い解が見つかった場合は、フィットを再実行します。 古い区間を公開してはいけません。プロファイル点の失敗は未知であり、データによって 除外されたことを意味しません。

6. 範囲を限定した科学的結果を提示します。 モデルとデータのハッシュ、パッケージの バージョン、ソース／補正の来歴、単位と参照フラックス、フィッティングされた予測、 残差診断、プロファイル図または表、および未解決のフラックスの組み合わせを含めます。 JSON アーティファクトを保持します。データに裏付けられた点推定値と、平坦な方向に沿った 最適化器の任意の選択を区別します。その方向に沿って予測標識が変化することを検証してから、 追加測定を提案します。

実行例

これらの実行可能な例では、合成したトレーサーのみのデータを使用します。隠れた自然存在比補正は なく、トレーサーの割合には非標識物質がすでに含まれています。

経路の分岐比を推定し、その後、情報量のある測定を取り除く

解析用の 2 経路モデルでは、2 炭素基質が、炭素を保持する経路または炭素を入れ替える経路の いずれかを通ります。取り込み量は 100 に固定されています。炭素 1 が 80％標識された供給物と、 M+1 = 0.56 の炭素 1 フラグメントによって、炭素を保持する経路は 70、炭素を入れ替える経路は 30 と定まります。

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
  --model "$SKILL_DIR/assets/branch-model.json" \
  --data "$SKILL_DIR/assets/branch-identifiable.json" \
  --profile straight --profile-points 41 --output branch-fit.json

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
  --model "$SKILL_DIR/assets/branch-model.json" \
  --data "$SKILL_DIR/assets/branch-unresolved.json" \
  --profile straight --output unresolved-fit.json

最初のフィットでは、およそ 70/30 が得られます。宣言されたガウス誤差モデルでは、 straight の解析的な 95％区間は約 67.55～72.45 です。スクリプトは、しきい値をまたぐ位置を 囲むグリッド区間を報告します。2 回目のフィットには分子全体の分布しかなく、これは 2 つの経路で 同一です。局所ランクはゼロとなり、unresolved_within_bounds が返されることを想定してください。 返される分岐比は任意の最適解です。

assets/branch-fluxes.json には、順方向シミュレーション用の 70/30 フラックスベクトルが 含まれています。

公開済みの環状ネットワーク計算を再現する

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" simulate \
  --model "$SKILL_DIR/assets/tca-model.json" \
  --data "$SKILL_DIR/assets/tca-tracer.json" \
  --fluxes "$SKILL_DIR/assets/tca-fluxes.json" --output tca-simulation.json

.venv-mfa/bin/python "$SKILL_DIR/scripts/mfa.py" fit \
  --model "$SKILL_DIR/assets/tca-model.json" \
  --data "$SKILL_DIR/assets/tca-reference-mdv.json" \
  --profile v3 --profile v7 --output tca-fit.json

最初のコマンドでは、公開済みの丸められたグルタミン酸 MDV [0.3464, 0.2695, 0.2708, 0.0807, 0.0286, 0.0039] を再現します。 2 つ目のコマンドでは、合成した参照測定値を使って、フマル酸／オキサロ酢酸の交換は この標識では解決できないことを認識しつつ、グルタミン酸の分岐フラックスを約 50 に 推定します。制約によって生じる上限端は、交換区間が測定によって決まったことを示す根拠では ありません。

解釈の境界

• 位置指定のアイソトポマー文字列は、左から右に炭素1から炭素Nを表します。 "100000"は炭素1が標識されたグルコースを意味します。質量分布だけでは、 その位置混合物を指定できません。アダプターは、mfapyの逆順の整数ビット順序に対応します。
• 天然存在比補正とトレーサー純度補正は異なる処理です。 入力は文書化されたトレーサーのみを基準とし、トレーサーの不純物は 供給源混合物に一貫して含める必要があります。同じ寄与を二重に補正しないでください。
• N炭素の質量分布には、合計が1になるため、独立成分は最大でN個です。 ツールは1つのビンを除外し、縮約共分散を使用します。利用可能な場合は、 ビン間の相関を保持してください。対角SEMによるフィッティングは、明示的に近似です。
• symmetricフラグは、同梱のフマル酸／コハク酸マップと同様に、恒等写像と 炭素順序の完全な逆転を等しく平均することを意味します。任意の分子対称性を意味するものではありません。 それ以外の置換には、明示的にサポートされたモデル表現が必要です。
• このCLIでサポートされない機能：非定常MFA、反応速度に対する同位体効果、 モデル化されていないプールまたは区画、MS/MS同時分布、複数元素の同位体補正、 炭素の分数化学量論／擬似反応、および生物全体規模での性能保証。これらには、 検証済みの専用モデル／エンジンを使用し、同じ入力／来歴および識別可能性の管理を維持してください。

実装と検証

scripts/mfa.pyはCLIです。scripts/_mfa_model.pyは入力を検証し、mfapy EMUシミュレーターに 適合させます。scripts/_mfa_fit.pyは実行可能なフラックス座標、マルチスタート最適化、 診断ランク、およびプロファイル計算を処理します。 エンジンのバージョンはassets/requirements.txtで固定されています。

tests/13c-metabolic-flux/のリポジトリテストスイートでは、公開済みの参照値、 解析的な分岐復元と尤度プロファイル、未解決の経路と交換、相関誤差がある場合の 除外ビン不変性、並列トレーサー、絶対速度のアンカリング、基質が繰り返される縮合、 対称性、無効なマップ、およびCLIの動作を確認します。これらの確認で確立されるのは テスト対象の数値的な動作であり、ユーザーのモデルの生物学的妥当性や、 特定の言語モデルに対する測定済みの優位性ではありません。

参考資料

• テスト対象リビジョンのmfapyソース、バージョン0.6.3；APIドキュメント。
• Matsuda et al.（2021）、mfapy: An open-source Python package for 13C-based metabolic flux analysis。
• Antoniewicz, Kelleher, and Stephanopoulos（2007）、Elementary metabolite units (EMU): A novel framework for modeling isotopic distributions。
• TCAネットワークは、mfapyのMITライセンス付きサンプルファイルをもとにしています。帰属表示と ライセンス全文はassets/mfapy-license.txtにあります。

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を特定します。 データまたはユーザーから、形式、識別子、パラメーターを確認します。結果を変える値を推測せず、不明な場合は質問します。
3. まず小規模に実行します。 最初に、小さなサブセット（1サンプル、1染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの識別情報、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の事項を明記します。

次の事態が発生した場合	対応
入力間でゲノムビルドまたは識別子が一致しない	作業を中断し、続行する前に整合させます（liftover、ID マッピング）。
インストールされているバージョンに、これらの手順に記載された関数、フラグ、エンドポイントがない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認して調整し、ユーザーに伝えます。API を決して捏造しないでください。
必須の入力、識別子、パラメーターが曖昧	ユーザーに質問するか、実行前に仮定を明示します。

整合性に関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できない場合は、その旨を明確に伝えます。
• 統計的な裏付けを超えて生物学的意義を解釈しないでください。多重検定補正について報告します。
• ここに記載されたバージョン固有の情報は古くなっている可能性があるため、インストール済みバージョンの公式ドキュメントで確認します。
• 費用が発生する、共有 GPU やクラウドのクォータを消費する、個人データまたは患者データに触れる、あるいは取り消せない操作を行う前に、ユーザーに確認します。

関連スキル

• cobrapy：SBML、JSON、YAML、MATLAB 形式のゲノムスケールモデルに対して、制約ベースの代謝モデリングを COBRApy（Python、import cobra）で実行します。