jinko-trial

Jinkō トライアル SDK ワークフロー

トライアルのセットアップ、健全性チェック、実行とポーリング、結果のダウンロードには、このスキルを使用してください。上流アセットの作成には、それぞれ専用のスキルを使用してください：jinko-model、jinko-vpop、jinko-protocol、jinko-data-table、jinko-output-set（シンプルおよび高度な出力セット）。

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

最小限のトライアル

最小限のトライアルは、次の要素で構成されます。

• 計算モデル。
• 解法オプション。明示的なオーバーライドが指定されていない場合は、モデルのデフォルトを使用します。
• 保存して可視化するコンポーネントの時系列のリストとして定義される、シンプルな出力セット。ユーザーが ID を指定していない場合は、デフォルトの出力 ID として model.time_dependent_ids() を使用してください。

任意のトライアル入力：

• Vpop。
• プロトコル設計。
• データテーブル設計（複数可）。
• 高度な出力セット／スコアリング設計。

健全性の制約

トライアルの健全性チェックでエラーが報告されている間は、実行を開始しないでください。必ず trial.sanity() を呼び出して確認してください。上流スキルのスタンドアロンチェック（validate_scoring_formula、client.validate_scoring_condition、scoring_design.diagnostics など）を再実行して確認してはいけません。 これらのチェックで検証できるのはアセット単体の状態だけであり、この具体的なトライアルに紐付けたときの動作は確認できません。trial.sanity() は、実行前に Jinkō UI が行うトライアルコンテキストのチェックと同じであり、実行可能かどうかの判断基準です。実行前のワークフローとトラブルシューティングの「スタンドアロン検証に合格した後のエラー」については、references/trial-setup.md を参照してください。

トライアルの健全性チェックで検出される一般的な制約：

• 計算モデルに健全性エラーがあってはなりません。
• プロトコル内のすべての記述子が、モデルのコンポーネントに対応している必要があります。
• Vpop 内のすべての記述子が、モデルのコンポーネントに対応している必要があります。
• データテーブルの obsId 列内のすべての記述子が、モデルのコンポーネントに対応している必要があります。
• プロトコルを使用する場合、データテーブルのすべての armScope 値が、プロトコルのアームに対応している必要があります。
• 高度な出力セット（スコアリング設計）が、このトライアルのモデル出力とシンプルな出力セットに対して正しく解決される必要があります。jinko-output-set のスタンドアロン検証に合格していても、ここで失敗する場合があります（ADVANCED_OUTPUTS_ERRORS）。

健全性エラーが報告された場合は、その内容を示し、上流アセットの修正を手伝う必要があるかユーザーに尋ねてください。

コア SDK メソッド

• シンプルな出力セットを作成します。明示的な出力 ID が要求されていない場合は、client.create_simple_output_set(model, model.time_dependent_ids()) を使用します。測定値の形状と高度な出力セット（制約／スカラー／目的関数）については、jinko-output-set を参照してください。
• トライアルを作成します。client.create_trial(model, data_tables=..., vpop=..., protocol=..., simple_output_set=..., advanced_output_set=...) を使用します。
• 作成後に、trial.edit_solving_options({...}) に変更するオプションのみを渡して、ソルブオプションを編集します。作成時に一部の solving_* 引数だけを渡すと、ValueError が発生します。生の ISO 8601 期間文字列を確認するには trial.get_solving_options() を、timedelta 値を確認するには trial.get_solving_options(duration_format="timedelta") を使用します。対象を絞って編集する場合は、いずれかの表記を使って trial.set_solving_times(t_max=timedelta(days=28), t_step="P1D") を使用します。
• 起動前の健全性チェック（run() の前に必須）：trial.sanity() — 生の dict（型付きオブジェクトではなく JSON レスポンス）を返します。各キー（model、protocol、vpop、シンプルな出力セットの outputSet、高度な出力セットの scorings、dataTables、solvingTimes）にはコンポーネントレポートが含まれ、それぞれに ["sanity"]["errors"]／["sanity"]["warnings"] と、コンポーネントごとの詳細を示す ["sanity"]["componentsSanity"] が含まれます。
• トライアルを実行します。trial.run() を使用します。
• 完了するまでポーリングします。trial.wait_until_completed(timeout=1800) を使用します。
• 時系列を検索します。trial.output_ids() を使用します。
• スカラーとアームを検索します。trial.results.summary() を使用します。
• pandas が利用可能な場合は、時系列を pandas としてダウンロードします。trial.results.timeseries({...}).to_dataframe() を使用します。
• pandas が利用可能な場合は、スカラーを pandas としてダウンロードします。trial.results.scalars([...]).to_dataframe() を使用します。
• pandas を使用しない場合は、TabularDownload.raw_bytes を使用します。結果のペイロードは CSV または ZIP 形式の CSV の場合があります。
• 読み取り専用で型付きの計算済みプロットデータ：trial.results.aggregate_scalars(...)、aggregate_timeseries(...)、tornado_sensitivity(...)、survival_analysis(...)、scalars_per_population(...)（散布図）。フィルターとグループはどちらも記述子ハンドル（age.gte(18)、sex.in_levels([...])、auc.group_by_quantiles(4)、sex.group_by_levels()）と trial.results.group_by_arm() から取得します。JinkoClient 以外のインポートは不要です。データを読み取るためだけに TrialVisualization を作成せず、トライアルを直接クエリしてください。各レスポンスには to_dataframe() メソッドがあり（pandas が必要）、整然とした形式のデータフレームを返します。デフォルトでは、Jinkō のプロットスタイル（jinko.plotting。アクティブな Python 環境に matplotlib と pandas が必要）を使ってデータフレームを描画します。これはウェブアプリのプロットと一致します。references/trial-plots.md を参照してください。同じフィルターとグループの構文を使って、jinko-trial-viz に保存するビジュアライゼーションを設定できます。
• ID が __jinko で始まる時系列とスカラーはすべて無視してください。これらは __jinkoSolvingTime、__jinkoAllocationMiB、__jinkoNumSteps などのプラットフォームテレメトリーです。同一トライアルのどの 2 回の実行間でも値が異なり、科学的な意味はないため、結果の比較、一致度の報告、指標の計算を行う前に除外してください。

データテーブルを添付する場合は、サポートされている data_tables= 引数を通じて渡してください。トライアルを作成する前に、各データテーブルの metadata.public.validForFitnessFunction が True であることを確認してください。False、値の欠落、不正な形式は拒否してください。

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

• プロジェクトルートではなく、専用の Jinkō フォルダー内に出力セットとトライアルを作成することを推奨します。ワークフローの開始時に、フォルダー名を尋ねるか、YYYY-MM-DD-<experiment-name> のような名前を提案してください。
• 可能であれば、完全一致する既存のフォルダーを再利用します。client.get_folder_by_name(name, exact_match_only=True) を使用します。
• フォルダーが存在しない場合は、ユーザーの確認後、またはスクリプトを --apply 付きで実行した場合にのみ作成してください。
• フォルダーオブジェクトまたはフォルダー ID を 1 つ解決し、トライアルの作成時に folder=folder を渡してください。シンプルな出力セットは、先に作成してから output_set.move_to_folder(folder) で移動してください。

再試行と再利用の衛生管理

• 1 件のユーザーリクエストでは、名前付きのローカルセットアップスクリプトを 1 つ使用し、run_v2.py、run_v3.py などのコピーを作成せずに更新してください。
• 試行または出力セットの検証に失敗した場合は、まず既存の項目を調査して修正してください。修正後に trial.sanity() を再実行してください。
• 独立したシナリオをユーザーが要求した場合、既存の項目が変更不可または互換性がない場合、あるいは修正によってユーザーが保持を求めた結果が失われる場合に限り、新しい試行または出力セットを作成してください。置き換えを作成する場合は、その理由を明記してください。

SDK スクリプト

SDK をインストールすると、これらはコンソールスクリプトとして PATH 上で使用でき、以下の例のように python -m でも実行できます。

• jinko.cli.find_completed_trial_results：試行の一覧を表示し、最初に完了した試行を見つけて、その概要を出力し、TimeSeries と Scalar の結果を pandas DataFrame にダウンロードします。
• jinko.cli.setup_and_run_trial：シンプルな出力セットを作成し、モデルと任意のアセットから試行を作成して、サニティチェックを行い、任意で実行とポーリングを行い、必要に応じて結果をダウンロードします。

例：

python -m jinko.cli.find_completed_trial_results --limit 20 --output-dir trial-results
python -m jinko.cli.setup_and_run_trial --model-sid cm-...
python -m jinko.cli.setup_and_run_trial --model-sid cm-... --output-id Drug
python -m jinko.cli.setup_and_run_trial --model-sid cm-... --output-id Drug --folder 2026-06-15-trial-run --create-folder --apply --run
python -m jinko.cli.setup_and_run_trial --model-sid cm-... --output-id Drug --vpop-sid vp-... --protocol-design-sid pd-... --data-table-sid dt-... --apply --run --download-results

リファレンスの参照先

• 試行の作成、安全な起動前サニティチェックのワークフロー、および ADVANCED_OUTPUTS_ERRORS／「The following advanced outputs have errors」のトラブルシューティングについては、references/trial-setup.md を参照してください。
• 完了した試行の検出と結果のダウンロードについては、references/trial-results.md を参照してください。
• Jinkō スタイルの図としてプロットデータを描画する方法（時系列、スカラー分布、トルネード、サバイバル、散布図）については、references/trial-plots.md を参照してください。