jinko-model

Jinkō Model SDK ワークフロー

SDK を通じてモデルを技術的に構築・編集する際に、このスキルを使用してください。生物学的な妥当性ではなく、SDK の仕組みとモデルの妥当性に範囲を限定してください。まず jinko-sdk-setup で接続を初期化してください。

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

必須ワークフロー

1. すでにモデルが提供されている場合は、新規作成するよりも既存モデルの編集を優先してください。必要な場合に限り、専用フォルダー内に client.create_empty_model() で新規作成してください。

2. モデルを取得し、編集を提案する前に、そのコンポーネント、タグ、単位、求解オプション、診断情報を確認してください。model.get_unit_check() で単位チェックのモードを確認してください。

3. model.set_unit_check("UnitCheckAndConvertAllSpeciesToExtentUnits") で単位チェックのモードを設定してください。影響を説明したうえで人間が明示的に指示しない限り、別のモードを選択しないでください。

4. 直接宣言する数値には、すべて単位を設定してください。対象は、数値のパラメータ式、コンパートメントの体積、種の初期条件です。値が式から導出されるパラメータは、その式によって単位が決まる場合、宣言単位を省略できます。references/units_static_info.json と診断情報を参照し、単位が自明でない場合は妥当性を確認してください。

5. モデルを完成とみなす前に、組み込みのプラットフォームタグをすべて付与してください。

   • 仮想患者間で変動する入力には i::vpop を付与します。
   • プロトコル群またはシナリオ間で変動する入力には i::protocol を付与します。これには、投与イベントの用量、初回投与時刻、投与間隔、投与回数が含まれます。
   • 値を持つ入力のうち該当するものには、それぞれ根拠に基づくソースタグ s::knowledge、s::arbitrary、s::to-calibrate のいずれかを付与します。不確かな入力にはタグを付けず、確認が必要なものとして報告してください。構築中に s::calibrated を付与しないでください。これは、受け入れられたキャリブレーション結果を記録するタグです。
   • プロットまたはキャリブレーションの対象となる重要な時系列出力には output を付与します。

   これらのうち3つは、モデルを後続の処理で利用できるかどうかを左右するため、コンポーネント単位だけでなくモデル全体で確認してください。少なくとも1つのコンポーネントに output が付いていないと、プロット、測定、キャリブレーションの対象がなくなります。これはエラーとして扱ってください。i::protocol が付いたコンポーネントがない場合、モデルにプロトコル群を設定できません。また、i::vpop が付いたコンポーネントがない場合、モデルは仮想患者間で変動できません。それぞれ警告として報告し、単一群かつ決定論的なモデルを意図している場合に限り修正してください。 python -m jinko.cli.validate_model_readiness --model-sid cm-... は、これら3つのチェックをデフォルトで実行します。

6. s::knowledge が付いた値を持つ入力には、すべてトレーサビリティリンクを追加してください。優先順位は、値が記載された Extract、次にその Extract を含む Reference、最後に値を生成したその他のプロジェクト項目です。プロジェクト内に該当する項目がない場合に限り、外部 DOI または URL を使用し、外部リンクをすべて確認対象として報告してください。ソース PDF がない場合は、jinko-reference スキルを使用して PDF を Reference としてアップロードし、リンクする前に Extracts を作成してください。Reference は、プロジェクトのフォルダー規則で定められたフォルダーに配置してください。

7. 必要に応じて、モデルのナビゲーションや可視化のために、科学的なスコープタグを追加できます。

   • 生物学的または空間的スケールには granularity::* を付与し、タグの色を #0cd95e にします。
   • 表現する物理的または生物学的プロセスには phenomenon::* を付与し、タグの色を #f87171 にします。
   • 実装されたメカニズムまたはサブモデルには module::* を付与し、タグの色を #66c09c にします。
   • 観察レベルには readout::* を付与し、タグの色を #da1d1d にします。 確認済みのコンポーネント定義とソースの根拠を使用します。既存の タグを維持し、根拠のない分類は未割り当てのままにします。これらのカスタムタグは レディネスの要件ではありません。選択ルールとQSP、PBPK、PK/PDの サンプルカタログについては、科学分野別スコープタグをお読みください。 ファミリーカラーは model.create_tag(..., color=...) に渡します。既存の宣言に合わせる場合は、 tag.set_color(...) を使用します。タグファミリーの色は、グラフのコンポーネントタイプの色とは別です。

8. 関連するコンポーネントの変更には、高レベルのSDKメソッドと model.components.batch(version="...") を使用します。上記のプラットフォームタグはすでに存在するため、再作成しないでください。その他のカスタムタグについてのみ、宣言を作成します。

9. モデルを再取得し、エラーディアグノスティックがないことを確認して、代表的な output コンポーネントに対して simple_solve() を実行します。イベントについては、想定されるイベント前後の変化を検証します。

メソッドのシグネチャを確認するには、クライアントが返すオブジェクトに対して help() を呼び出します。たとえば、help(type(model)) または help(model.simple_solve) を使用します。SDKには jinko.model モジュールはありません。

長いアドホックなコードスニペットではなく、scripts/create_minimal_model.py、およびSDKの python -m jinko.cli.tag_model_components と python -m jinko.cli.validate_model_readiness を使用します。スクリプトはデフォルトでドライランを実行し、--apply を指定した場合にのみ変更を適用します。

ISO 8601の期間を明確に変換するには、たとえば Duration.parse("P1M").to_timedelta() のように from jinko.iso8601 import Duration を使用します。計算時間には timedelta またはISO文字列を指定できます。例：model.set_solving_times(t_max=timedelta(days=28), t_step="P1D", additional_periods=[{"t_max": "P7D", "t_step": timedelta(hours=1)}])。

参照先

• コンポーネントの一括処理、タグ、イベント、数式、代数ルールについては、references/model-components.md をお読みください。
• 単位の意味と変換の動作については、references/unit_docs.md をお読みください。
• ディアグノスティックとレディネスチェックについては、references/model-validation.md をお読みください。
• combine_with を使う前に、また model.conflicts を読み取る、または解決する際には、references/model-combination.md をお読みください。
• オプションのスケール、現象、モジュール、または読み出しタグを選択する際には、references/scientific-scoped-tags.md をお読みください。QSP、PBPK、PK/PDの幅広く拡張可能なサンプルカタログが含まれています。