06. Run a Trial

How to run a trial in Jinko

After defining a virtual population (VPOP) and protocol, you can run a trial in Jinko to simulate different experimental conditions. This section explains how to create and run a trial using the Jinko API.

Creating an Output Set for Trial Endpoints

Before creating a trial, you need to define measures that represent the trial's endpoints. A measure represents a specific outcome or metric that will be tracked during the trial (e.g., survival rate, biomarker concentration). These measures are attached to the trial as a Simple Output Set or an Advanced Output Set.

For more details on setting up measures, check out the guide.

For the common case of tracking raw timeseries values, create_simple_output_set builds a Simple Output Set for you from a model and a list of timeseries ids:

from jinko import JinkoClient

client = JinkoClient()

model = client.get_model("cm-abc123def456")

output_set = client.create_simple_output_set(model, ["x"])

Example Request to Create a Custom Simple Output Set

create_simple_output_set also accepts richer measures. Pass a dict instead of a plain output id to set a custom name and a function such as a value at a specific time:

from jinko import JinkoClient

client = JinkoClient()

model = client.get_model("cm-abc123def456")

output_set = client.create_simple_output_set(
    model,
    [
        {
            "timeseriesId": "x",
            "name": "x-at-P10D",
            "function": {"PointAtTime": {"At": "P10D"}},
        }
    ],
    name="Dummy Output Set",
    folder="folder-id-123",
)

This example creates a measure named "x-at-P10D," which tracks the "x" timeseries at 10 days.

See create_simple_output_set's docstring in the SDK for the full set of supported function forms (point-in-time and across-time measures such as AUC, min/max, half-life, ...).

Advanced Output Sets

For constraints, objectives, and formula-based measures beyond what a Simple Output Set covers, use an Advanced Output Set instead: client.create_advanced_output_set_from_json(...) (or create_advanced_output_set(...) for typed constraint/scalar/objective entries).

Consult the API reference for its JSON schema.

Creating a Trial

To create a trial, you need the computational model and, typically, a protocol design, a virtual population, and an output set of measures to track.

Example Request to Create a Trial

from jinko import JinkoClient

client = JinkoClient()

model = client.get_model("cm-abc123def456")
vpop = client.get_vpop("vp-abc123def456")
protocol_design = client.get_protocol_design("pd-abc123def456")
output_set = client.get_simple_output_set("os-abc123def456")

trial = client.create_trial(
    model,
    vpop=vpop,
    protocol=protocol_design,
    simple_output_set=output_set,
    name="Test Trial",
    folder="folder-id-123",
)

print(trial.sid, trial.core_id, trial.snapshot_id)

This request creates a trial using a specified computational model, protocol, virtual population, and output set. model.create_trial(...) is equivalent and reads a little more naturally when you already have the model object at hand.

Running a Trial

Once a trial is created, you can run it with:

trial.run()

Monitoring Trial Status

You can poll the trial's status manually, or block until it reaches a terminal state with wait_until_completed:

status = trial.status()
print(status)

final_status = trial.wait_until_completed(timeout=3600, poll_interval=5)
print(final_status)

wait_until_completed polls the trial every poll_interval seconds until it completes, stops, or errors, and raises TimeoutError if timeout seconds elapse first.

Additional Resources

For more information about creating and running trials, check out the guide on trial creation.