Jinkō Trial Visualization Workflows
Use this skill for TrialVisualization project items: creating a visualization for a trial, configuring plot sections, retrieving the stored visualization payload, and running visualization sanity checks.
Keep trial execution and result downloads in jinko-trial. Use this skill after a trial exists and the user wants the Jinkō visualization artifact or its plot configuration.
PREREQUISITE: This skill needs an initialized jinko-sdk connection and an
SDK satisfying its metadata.requires_sdk range. Run the jinko-sdk-setup skill
(../jinko-sdk-setup/SKILL.md) and proceed only once its check passes. If that
skill is not found, install it from novainsilico/jinko-skills.
Core Workflow
- Resolve the trial:
trial = client.get_trial(trial_sid).
- After explicit user confirmation, create an empty visualization bound to the trial:
viz = trial.create_empty_trial_visualization(folder=..., name=..., description=...).
- Decide the plot sections needed and configure each through its typed subservice:
viz.timeseries for time-course outputs.viz.scalars for scalar result distributions and central-location plots.viz.scatter_plots for X-vs-X arms or X-vs-Y variables.viz.survival_analysis for time-to-event visualizations.viz.contribution_analysis for tornado-style sensitivity/contribution views.viz.data_overlay / viz.patients_overlay when observed data or patient-level data should appear.viz.filters / viz.groups for scoping and grouping.viz.set_selected_arms(...), viz.set_equate_baseline(...), viz.set_time_unit(...) for top-level options.
- Run and print
viz.sanity after every create or update. Return failure and fix the visualization when it reports errors.
- Reconfigure a section at any time by calling its setter again (e.g.
viz.timeseries.set_selectors([...])) — each call patches only that section.
SDK Surface
trial.create_empty_trial_visualization(folder=, name=, description=, version=) and trial.create_trial_visualization_from_json(data, ...) — creation, bound to a trial.client.list_trial_visualizations(...), client.iter_trial_visualizations(...), client.get_trial_visualization(sid) — metadata lookup.viz.content(revision=...) — full typed content; viz.sanity / viz.sanity_at(revision,> — diagnostics (.errors(), .warnings(), .has_errors(), .for_field(...), .by_field()).- Section subservices, each with
get()/clear() plus section-specific setters: viz.timeseries.set_selectors(...)/add_selectors(...), viz.scalars.set_selectors(...)/add_selectors(...), viz.survival_analysis.set_selectors(...)/set_observation_window_from_start_until_end(...)/set_observation_window_from_start_until_time(...)/set_confidence_interval(...), viz.contribution_analysis.set_selectors(...)/set_quantile(...)/set_input_baseline_only(...)/set_all_baseline(...)/set_custom_baseline(...), viz.scatter_plots.add_x_vs_x_plot(...)/add_x_vs_y_plot(...)/set_config(...)/set_regression(...), viz.data_overlay.add_table(...)/set_tables(...)/set_ranges_enabled(...), viz.filters.add_numeric(...)/add_categorical(...)/add_patient_list(...), viz.groups.set_group_by_arm(...)/add_scalar_*_grouping(...)/add_categorical_grouping(...).
Read references/trial-viz-typed-api.md for full examples of each subservice.
SDK Script
Use the script for repeatable create, update, get, list, and sanity operations
through the typed API. It is on PATH as a console script once the SDK is
installed, and also runnable via python -m as shown below.
python -m jinko.cli.trial_viz list --limit 20
python -m jinko.cli.trial_viz create --trial-sid tr-... --name "My trial viz" --timeseries Drug --scalar AUC
python -m jinko.cli.trial_viz create --trial-sid tr-... --name "My trial viz" --timeseries Drug --scalar AUC --apply
python -m jinko.cli.trial_viz get --trial-viz-sid tv-... --output-file viz.content.json
python -m jinko.cli.trial_viz update --trial-viz-sid tv-... --scatter-xvsy "AUC,Cmax,control,treated" --apply
python -m jinko.cli.trial_viz sanity --trial-viz-sid tv-... --only timeseries --only scatterPlots
For scatter, overlay, filter, or grouping configuration beyond the script's flags, use the typed subservices directly in Python (see references/trial-viz-typed-api.md).
Project Folder Hygiene
- Prefer creating trial visualizations in the same folder as the trial or in a dedicated analysis folder.
- Pass a folder id or exact folder name through the script's
--folder, or folder=folder on create_empty_trial_visualization(...) directly.
- Treat an explicit folder that cannot be resolved as an error; never silently create the visualization in the project root.
- Reuse existing trial visualizations when the user wants an additional plot on the same analysis; call the relevant section's setter instead of creating duplicates.
Reference Routing
- Read
references/trial-viz-typed-api.md for the typed subservice API.
Output Expectations
When creating or modifying a visualization, report:
- TrialVisualization SID, core item id, snapshot id, revision when available, and URL when available.
- Plot sections created or patched.
- Any sanity errors or warnings, preserving the backend field names so the next fix is direct.
When retrieving a visualization, return or save the full JSON content if the user needs to inspect, diff, or reuse plot settings.
1---2name: jinko-trial-viz3description: Create, update, inspect, sanity-check, and retrieve Jinkō TrialVisualization project items for completed or running trials. Use this skill whenever the user wants a trial visualization, trial viz, time-series plot setup, scalar result plots, scatter plots, contribution analysis, survival analysis, data overlays, or to fetch the current visualization JSON. The SDK exposes a typed TrialVisualization API: creation helpers plus a per-section subservice for every plot type.4license: MIT5---67# Jinkō Trial Visualization Workflows89Use this skill for TrialVisualization project items: creating a visualization for a trial, configuring plot sections, retrieving the stored visualization payload, and running visualization sanity checks.1011Keep trial execution and result downloads in `jinko-trial`. Use this skill after a trial exists and the user wants the Jinkō visualization artifact or its plot configuration.1213> **PREREQUISITE:** This skill needs an initialized `jinko-sdk` connection and an14> SDK satisfying its `metadata.requires_sdk` range. Run the `jinko-sdk-setup` skill15> (`../jinko-sdk-setup/SKILL.md`) and proceed only once its check passes. If that16> skill is not found, install it from `novainsilico/jinko-skills`.1718## Core Workflow19201. Resolve the trial: `trial = client.get_trial(trial_sid)`.212. After explicit user confirmation, create an empty visualization bound to the trial: `viz = trial.create_empty_trial_visualization(folder=..., name=..., description=...)`.223. Decide the plot sections needed and configure each through its typed subservice:23 - `viz.timeseries` for time-course outputs.24 - `viz.scalars` for scalar result distributions and central-location plots.25 - `viz.scatter_plots` for X-vs-X arms or X-vs-Y variables.26 - `viz.survival_analysis` for time-to-event visualizations.27 - `viz.contribution_analysis` for tornado-style sensitivity/contribution views.28 - `viz.data_overlay` / `viz.patients_overlay` when observed data or patient-level data should appear.29 - `viz.filters` / `viz.groups` for scoping and grouping.30 - `viz.set_selected_arms(...)`, `viz.set_equate_baseline(...)`, `viz.set_time_unit(...)` for top-level options.314. Run and print `viz.sanity` after every create or update. Return failure and fix the visualization when it reports errors.325. Reconfigure a section at any time by calling its setter again (e.g. `viz.timeseries.set_selectors([...])`) — each call patches only that section.3334## SDK Surface3536- `trial.create_empty_trial_visualization(folder=, name=, description=, version=)` and `trial.create_trial_visualization_from_json(data, ...)` — creation, bound to a trial.37- `client.list_trial_visualizations(...)`, `client.iter_trial_visualizations(...)`, `client.get_trial_visualization(sid)` — metadata lookup.38- `viz.content(revision=...)` — full typed content; `viz.sanity` / `viz.sanity_at(revision, only=[...])` — diagnostics (`.errors()`, `.warnings()`, `.has_errors()`, `.for_field(...)`, `.by_field()`).39- Section subservices, each with `get()`/`clear()` plus section-specific setters: `viz.timeseries.set_selectors(...)`/`add_selectors(...)`, `viz.scalars.set_selectors(...)`/`add_selectors(...)`, `viz.survival_analysis.set_selectors(...)`/`set_observation_window_from_start_until_end(...)`/`set_observation_window_from_start_until_time(...)`/`set_confidence_interval(...)`, `viz.contribution_analysis.set_selectors(...)`/`set_quantile(...)`/`set_input_baseline_only(...)`/`set_all_baseline(...)`/`set_custom_baseline(...)`, `viz.scatter_plots.add_x_vs_x_plot(...)`/`add_x_vs_y_plot(...)`/`set_config(...)`/`set_regression(...)`, `viz.data_overlay.add_table(...)`/`set_tables(...)`/`set_ranges_enabled(...)`, `viz.filters.add_numeric(...)`/`add_categorical(...)`/`add_patient_list(...)`, `viz.groups.set_group_by_arm(...)`/`add_scalar_*_grouping(...)`/`add_categorical_grouping(...)`.4041Read `references/trial-viz-typed-api.md` for full examples of each subservice.4243## SDK Script4445Use the script for repeatable create, update, get, list, and sanity operations46through the typed API. It is on `PATH` as a console script once the SDK is47installed, and also runnable via `python -m` as shown below.4849```bash50python -m jinko.cli.trial_viz list --limit 2051python -m jinko.cli.trial_viz create --trial-sid tr-... --name "My trial viz" --timeseries Drug --scalar AUC52python -m jinko.cli.trial_viz create --trial-sid tr-... --name "My trial viz" --timeseries Drug --scalar AUC --apply53python -m jinko.cli.trial_viz get --trial-viz-sid tv-... --output-file viz.content.json54python -m jinko.cli.trial_viz update --trial-viz-sid tv-... --scatter-xvsy "AUC,Cmax,control,treated" --apply55python -m jinko.cli.trial_viz sanity --trial-viz-sid tv-... --only timeseries --only scatterPlots56```5758For scatter, overlay, filter, or grouping configuration beyond the script's flags, use the typed subservices directly in Python (see `references/trial-viz-typed-api.md`).5960## Project Folder Hygiene6162- Prefer creating trial visualizations in the same folder as the trial or in a dedicated analysis folder.63- Pass a folder id or exact folder name through the script's `--folder`, or `folder=folder` on `create_empty_trial_visualization(...)` directly.64- Treat an explicit folder that cannot be resolved as an error; never silently create the visualization in the project root.65- Reuse existing trial visualizations when the user wants an additional plot on the same analysis; call the relevant section's setter instead of creating duplicates.6667## Reference Routing6869- Read `references/trial-viz-typed-api.md` for the typed subservice API.7071## Output Expectations7273When creating or modifying a visualization, report:7475- TrialVisualization SID, core item id, snapshot id, revision when available, and URL when available.76- Plot sections created or patched.77- Any sanity errors or warnings, preserving the backend field names so the next fix is direct.7879When retrieving a visualization, return or save the full JSON content if the user needs to inspect, diff, or reuse plot settings.
novainsilico