jinko-task-from-nonmem

Jinkō Task：NONMEM からの変換

NONMEM の実行を、動作する Jinkō トライアルに変換します。

前提条件： このスキルには、初期化済みの jinko-sdk 接続と、metadata.requires_sdk の範囲を満たす SDK が必要です。jinko-sdk-setup スキル（../jinko-sdk-setup/SKILL.md）を実行し、チェックに合格してから先に進んでください。セッションコードは一度しか交換できないため、このスキル独自の SDK プロセスを開始する前に、再度 get_session_code を呼び出してください。このスキルが見つからない場合は、novainsilico/jinko-skills からインストールしてください。

このスキルには、SDK に既定ではインストールされないコンバーターの追加パッケージも必要です。

pip install "jinko-sdk[nonmem2jinko]"

コンバーターは nonmem2jinko パッケージです。jinko-sdk に同梱されていますが、個別にインポートします。この追加パッケージにより、数値チェックで参照解を積分するための scipy が追加されます。これがなくてもすべてのスクリプトは実行できますが、--check solve を実行すると追加パッケージを示すメッセージが表示されます。

基本ルール

• スクリプトを実行してください。$PK を手作業で翻訳してはいけません。検証対象となるのはスクリプトの出力のみです。
• 必ず数値をチェックし、測定した一致度を報告してください。一致度を確認せずに変換が成功したと主張してはいけません。また、結果を含まない判定のレポートを公開してはいけません。
• 数値の参照元を明記してください。--reference scipy はプラットフォームの影響を切り分けます。rxode2 は読み取りの影響も含みます。nonmem は元の実行が出力した $TABLE と比較するもので、ライセンスは不要ですが、そのファイルが必要です。これらは相互に置き換えられません。現時点では、共変量の上書きが必要なモデルに対して、入力条件が揃わない比較を避けるため、rxode2 の数値参照は処理を拒否します。
• ブロッキングエラーがある場合は停止してください。失われるものをユーザーに伝えずに --allow-issues を指定してはいけません。
• 適用する前にレポートを読んでください。単位や名前は推定されるため、特定のデータセットでは推定が誤っている場合があります。
• 時間単位が誤っていると、速度論が予告なく変わります。Jinkō は任意の時間単位を受け入れますが、結果を秒単位で計算して返します。データセットに照らして、量、体積、時間を確認してください。
• プラットフォーム独自の時間グリッドで比較してください。Time はリクエスト可能な系列なので、リクエストしてください。記録されたイベントによって独自の点が追加されるため、tMin／tStep の組からグリッドを再構築すると、値と時刻の対応が誤ります。

スクリプト

スクリプト	内容
convert_model.py	コントロールストリームを計算モデルに変換
convert_trial.py	モデルに vpop、プロトコル、出力セットを加え、トライアルを作成
compare_against_reference.py	数値チェック。省略不可
upload_data_tables.py	母集団をデータテーブルに変換し、トライアルに紐付けて viz に重ね合わせ
render_equivalence_report.py	測定した比較結果から Markdown レポートを作成
publish_equivalence_report.py	レポートを Jinkō ドキュメントに変換

プロジェクトへの書き込みは既定でドライランとなり、--apply を指定した場合のみ実行されます。ローカル成果物の出力先は明示的なパス引数で指定し、スクリプトが --overwrite に対応している場合は、既存ファイルを保持します。

オーケストレーション

1. .ext、.phi、およびデータセットを依頼します。それぞれ変換の精度を高めますが、制御ストリームだけでも開始できます。
2. ドライランで変換します。レポートで指摘された内容を解決します：--time-unit、 --amount-unit、--volume-unit、--unit SYMBOL=unit、 --rename NONMEM=jinkoId。
3. 適用してから実行します。
4. 変換時と同じ --time-unit を使って数値を確認します。ソルブがスキップされた場合は失敗であり、根拠にはなりません。数値とその参照元を報告します。
5. 変換を実行した本人以外がモデルを利用する場合は、レンダリングして同等性レポートを提示します。

書き込みを行う各ステップでは、1回の実行に関連する項目をまとめるための --folder NAME --create-folder と、次のステップに SID を渡すための --json-out FILE を指定します。説明文から SID を抜き出してはいけません。

--parent-folder NAME を指定すると、そのフォルダーが別のフォルダーの中に配置されます。1つのプロジェクトで変換を複数回行う場合に使います。日付を名前にしたフォルダーの中にモデルごとのサブフォルダーを作成すれば、各実行の証拠をまとめられ、実行が時系列順に並びます。指定しない場合、プロジェクトのルートがモデル名で埋まり、どの実行に属するかが分からなくなります。

判断事項

母集団（convert_trial.py）。--population design（デフォルト）は、後から Jinkō で編集できます。phi はフィッティング済みの被験者を再現します。sampled は $OMEGA が表す完全な多変量正規分布からサンプルを生成します。有限サンプルで実現する共分散にはサンプリング誤差があるため、正確だと見なすのではなく測定する必要があります。

ランダム効果（両方のコンバーター）。--vpop-mode etas（デフォルト）は、ETA の周辺分布と相関を通じて目標の $OMEGA 共分散を表します。parameters は、代わりに導出されたパラメーターに周辺分布を設定します。UI では読みやすくなりますが、共変量効果がない場合に限り同等です。

投与（convert_trial.py）。--dosing auto（デフォルト）は、データセットに投与群の構造があれば投与群を使い、なければ患者ごとのスロットを使います。新生児のフェノバルビタール投与や体重区分ごとの単回投与など、すべての被験者が個別化された履歴を持つ試験には投与群の構造がありません。per-patient を指定すると、各患者固有の投与時刻と投与量が vpop に設定されます。投与スケジュールは患者テーブルに含まれるため、--population phi または sampled が必要です。

不確実性（convert_trial.py）。--eps-clones N は、患者ごとの予測コーンを生成します。--population phi または sampled が必要です。VPC ではありません。詳しくは references/residual-error.md を参照してください。

拒否されるもの（対象レコードを明記）： 定常状態（SS）投与、$MIX、ネストされたランダム効果、SD として指定された $OMEGA／$SIGMA、相関またはコレスキー形式、$PRED のみのモデル、読み取れない省略コード（MPAST、変数による ETA() の添字、CALL、include）、DV や EVID などのレコードレベルのデータ項目を読み取る、動態に必要なパラメーター、および IF(AMT.GT.0) TDOS = TIME。最後の式が拒否されるのは、シミュレーション時刻で置き換えると正しく見えてしまい、投与後経過時間が意図せずゼロになるためです。

拒否されず、報告されるもの： $PRIOR と $NONPARAMETRIC は推定に影響しますが、順方向モデルには影響しないため、推定値はそのまま変換されます。

近似を明示して変換されるもの： DOSE = AMT はモデルの投与パラメーターを参照するため、投与量が異なる被験者では最初の投与量だけが読み込まれます。時間変化する共変量はベースライン値のみを保持します。どのランダム効果を適用するかを選択する共変量は、1つの vpop 周辺分布にはできません。重みを介して記述された複合誤差モデル（Y = F + W*EPS(1)、W = F*θ + θ）は係数を診断しますが、残差誤差なしで観測値が出力されます。

参考資料

• references/workflow.md — コマンド、フラグ、作業手順
• references/validation.md — 数値チェックと、それぞれが証明する内容
• references/reporting.md — 同等性レポート、データテーブル、オーバーレイ
• references/conversion-map.md — NONMEM の各構成要素の変換先
• references/residual-error.md — $ERROR、$SIGMA、クローンによる近似

一般的な仕組みについては、下位レベルのスキルを参照してください。コンポーネントは jinko-model、母集団は jinko-vpop、群は jinko-protocol、実行は jinko-trial、テーブルは jinko-data-table、可視化は jinko-trial-viz、ドキュメントは jinko-document です。