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.12 .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 の内部生成される数値関数に到達する前にそれらを制限します。

固定されたコミットは 2026-09-30 時点で上流の master と一致していました。その README は 最新の変更を「064」と表記していますが、インストールされた配布物は依然として 0.6.3 を報告します。 解析記録には、パッケージのバージョンと併せて Git コミットを保持してください。更新された NumPy/SciPy の固定バージョンは Python 3.12 以降を必要とします。上記のコマンドはテスト済みの 3.12 環境を使用します。レビュー済みの順方向モデル契約については references/inference.md を参照してください。

ワークフロー

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. エビデンスを検査します。 失敗した開始点、残差パターン、物質収支、 有効な境界、局所感度のランク、プロファイルのステータスを確認します。閾値を横切る区間は、 実際のグリッド解像度で報告してください。粗すぎる場合はグリッドを細かくしてください。 要求された各プロファイルは、記載された誤差モデルの下での1つのフラックスの区間を与えます。 複数の 95% プロファイルは、ネットワーク全体に対する同時 95% 領域ではありません。 プロファイルがベースラインより良い解を見つけた場合は、フィットを再実行してください。古い区間を 公開しないでください。失敗したプロファイル点は不明であり、データによって除外されたわけではありません。

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

実例

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

経路の分岐を復元する。その後、情報量のある測定を除去する

解析的な2経路モデルは、2炭素の基質を、炭素を保持する経路か炭素を交換する経路の いずれかを通して送ります。取り込みは 100 に固定されています。80% の炭素1標識の フィードと、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: 13C ベースの代謝フラックス解析のためのオープンソース Python パッケージ。
• Antoniewicz, Kelleher, and Stephanopoulos (2007)、Elementary metabolite units (EMU): 同位体分布をモデル化するための新しいフレームワーク。
• TCA ネットワークは mfapy の MIT ライセンスのサンプルファイルから適応されています。帰属 と完全な通知は assets/mfapy-license.txt にあります。