jinko-vpop

Jinkō Vpop SDK ワークフロー

SDK を通じて技術的な vpop および vpop-design ワークフローを実行する際に、このスキルを使用します。assets/distrib.json にある許可された分布形式を使用し、より詳細な分布設計については、利用可能な場合は専用の分布スキルに委ねてください。

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

基本ルール

• vpop を直接アップロードするには、client.create_vpop_from_csv() または client.create_vpop_from_dataframe() を使用します。
• 周辺分布を使った vpop 設計には、client.create_vpop_design_from_design() を使用します。
• design.generate_vpop() を使用して、VpopDesign から変更不可の Vpop を生成します。
• 生成する前に design.diagnostics（または design.get_sanity()）を確認し、報告されたエラーを先に修正します。
• 既存の設計の記述子／相関を編集するには、raw payload を置き換えるのではなく、design.descriptors（create*／set_distribution*）と design.correlations を使用します。
• Vpop プロジェクト項目は、編集箇所での変更ができない生成済み／アップロード済みアーティファクトとして扱います。
• 生成済みの vpop ではなく vpop 設計を編集し、その後、新しい vpop を再生成します。
• プロジェクト項目を作成または更新する前に、明示的な確認を得るか、スクリプトに --apply を指定します。
• vpop をそのモデルで使用する場合、CSV ヘッダーと周辺分布設計の記述子 ID は、実際のモデルコンポーネント ID と一致させる必要があります。
• 周辺分布リスト内の重複した記述子 ID は拒否します。マッピングに変換すると、先行する項目が暗黙に破棄されるためです。
• LogUniform、LogNormal、LogNormalTruncated の各ペイロードには、必ず以下の「対数スケール分布」に従い、Mixture の重みには「混合分布」に従います。

プロジェクトフォルダーの整理

• vpop と vpop 設計は、プロジェクトのルートではなく、専用の Jinkō フォルダー内に作成することを推奨します。ワークフローの開始時に、YYYY-MM-DD-<experiment-name> などのフォルダー名をユーザーに尋ねるか、提案してください。
• 可能な場合は、完全一致する既存のフォルダーを再利用します：client.get_folder_by_name(name, exact_match_only=True)。
• フォルダーが存在しない場合は、ユーザーの確認後、または --apply を付けてスクリプトを実行した場合にのみ作成します。
• フォルダーオブジェクトまたはフォルダー ID を 1 つ解決し、対応する SDK 作成呼び出しに folder=folder を渡します。

同梱アセット

• assets/toy_vpop.csv：トイモデルの記述子 Dose と k_elim を使用した、2 人分の vpop CSV。
• assets/toy_marginals.json：Dose と k_elim の周辺分布リスト形式の vpop 設計。
• assets/distrib.json：許容される周辺分布形式の信頼できる情報源。

SDK スクリプト

長い Python の例をチャットに埋め込むのではなく、スクリプトを使用します。SDK のインストール後、これらはコンソールスクリプトとして PATH から実行でき、以下のように python -m を使っても実行できます。

• jinko.cli.create_vpop_from_csv：CSV を直接アップロードします。--method dataframe を指定すると、pandas DataFrame 経由でアップロードします。
• jinko.cli.create_vpop_design_from_design：一意な { "id": ..., "distribution": ... } エントリーのリストから vpop 設計を作成し、診断に合格した後に vpop を生成することもできます。
• jinko.cli.inspect_vpop：既存の vpop の内容、説明、または統計情報を調べます。
• jinko.cli.edit_vpop_design：記述子を順次更新または追加し、後続の編集に失敗した場合は適用済み ID を報告し、成功前に編集後の診断を実行します。

例：

python -m jinko.cli.create_vpop_from_csv --csv skills/jinko-vpop/assets/toy_vpop.csv
python -m jinko.cli.create_vpop_from_csv --csv skills/jinko-vpop/assets/toy_vpop.csv --apply
python -m jinko.cli.create_vpop_from_csv --csv skills/jinko-vpop/assets/toy_vpop.csv --folder 2026-06-15-vpop-study --create-folder --apply
python -m jinko.cli.create_vpop_design_from_design --design skills/jinko-vpop/assets/toy_marginals.json --model-sid cm-... --apply --generate
python -m jinko.cli.inspect_vpop --vpop-sid vp-... --statistics --correlations
python -m jinko.cli.edit_vpop_design --vpop-design-sid vd-... --design skills/jinko-vpop/assets/toy_marginals.json --apply

CSV アップロードのパターン

最小限の CSV 形式では、患者ごとに 1 行を使用します：

patientIndex,Dose,k_elim
1,1.0,0.08
2,1.2,0.12

vpop をモデルに適用する場合は、age や weight などの生物学的なラベルではなく、実際のコンポーネント ID を使用してください。

周辺分布の設計パターン

スキルのアセットとスクリプトでは、周辺分布の項目のリストを使用します。

[
  {"id": "Dose", "distribution": {"tag": "Uniform", "lowBound": 0.8, "highBound": 1.2}},
  {"id": "k_elim", "distribution": {"tag": "NormalTruncated", "mean": 0.1, "stdev": 0.02, "lowBound": 0.01, "highBound": 0.3}}
]

このスクリプトは、このリストを create_vpop_design_from_design(marginal_distributions=...) が想定する SDK マッピングに変換します。

対数スケールの分布

エージェントは、記述子の物理的な最小値と最大値を LogUniform の lowBound と highBound に指定することがよくあります。Jinkō はその後、base**min から base**max の範囲をサンプリングします。物理範囲が 0.001～10 で base: 10 の場合、約 1～1e10 の値が得られます。設計の診断ではこのペイロードが受け入れられるため、誤りは生成された Vpop でのみ明らかになります。

フィールド	スケール	物理範囲 1e-4～1e-2、base: 10
LogUniform の lowBound、highBound	log_base(value)	-4、-2
LogNormal、LogNormalTruncated の mean、stdev	log_base(value)	中央値 1e-3：mean: -3
LogNormalTruncated の posLowBound、posHighBound	物理値	1e-4、1e-2

対数スケールのペイロードは、次の順序で作成します。

1. ソースから、記述子の単位で物理範囲または中央値を書き留めます。
2. 対数スケールのパラメーターは手計算せず、コードで計算します：math.log(value, base)。base: 10 の場合は math.log10(value) を使用します。物理境界が 0 以下の場合、対数は定義できません。正の下限を使用するか、別の分布を選択してください。
3. 設計を作成する前に、変換して得られる物理的な結果を返信に記載します：「LogUniform(lowBound=-4, highBound=-2, base=10) は 1e-4～1e-2 の値をサンプリングします。」
4. 変換後の範囲がソースの範囲と一致しない場合は中止します。対数フィールドに物理値を入力している典型的な兆候は、1 未満のパラメーターなのに lowBound と highBound が両方とも正の値であることです。

[
  {"id": "k_on", "distribution": {"tag": "LogUniform", "lowBound": -4, "highBound": -2, "base": 10}},
  {"id": "k_elim", "distribution": {"tag": "LogNormalTruncated", "mean": -1, "stdev": 0.3, "posLowBound": 0.01, "posHighBound": 1, "base": 10}}
]

k_on の項目は 1e-4～1e-2 の値をサンプリングします。k_elim の項目は、切り捨て前の中央値が 0.1 で、0.01～1 の値を保持します。

Jinkō の他のオブジェクトには、それぞれ異なる規則があります。log_transform=True を指定した CMA-ES キャリブレーションでは、mean と std に log10(x) を使用しますが、min_bound と max_bound には物理値を使用します（jinko-calibration-cmaes）。変換せずに、キャリブレーションの事前分布と vpop 設計の間で境界値をコピーしないでください。

対数スケールの周辺分布を使って Vpop を生成したら、記述子の統計を読み戻し、最小値、最大値、中央値を手順 1 の物理範囲と比較します。

python -m jinko.cli.inspect_vpop --vpop-sid vp-... --statistics

混合分布

各 mixture 項目は、[weight, distribution] のペアです。重みは相対的な重みであり、確率ではありません。合計が 1 である必要はありません。Jinkō が正規化します。読みやすい正の整数を使用してください。2:1 の比率なら、0.6666667 と 0.3333333 ではなく、2 と 1 を指定します。公表されているサブグループの割合が 13.5% の場合は、27 と 173 を指定するか、その精度で十分なら 1 と 6 に丸めてください。

{"id": "k_elim", "distribution": {"tag": "Mixture", "mixture": [
  [2, {"tag": "LogNormal", "mean": -1, "stdev": 0.2, "base": 10}],
  [1, {"tag": "LogNormal", "mean": -0.5, "stdev": 0.2, "base": 10}]
]}}

k_elim の項目では、患者の 3 分の 2 が最初の成分に割り当てられます。各成分には、上記の対数スケールの規則を含め、それぞれのスケール規則が適用されます。

参照先

• CSV/DataFrame の直接アップロードの詳細は、references/csv-vpop.md を参照してください。
• 周辺分布を使った vpop の設計と生成の詳細は、references/vpop-design.md を参照してください。
• 周辺分布の形状を追加または変更する前に、assets/distrib.json を参照してください。