Skip to main content

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 Measures 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 then attached to the trial.

The format for creating a measure is described in the Jinko API documentation. For more details on setting up measures, check out the guide.

Example Request to Create a Measure​

Here’s an example to create a dummy measure:

import jinko_helpers as jinko

measures = {
    "measures": [
        {
            "name": "x-at-P10D",
            "timeseriesId": "x",
            "origin": "OnEachArm",
            "function": {"PointAtTime": {"At": "P10D"}},
        }
    ]
}

response = jinko.make_request(
    path="/core/v2/scorings_manager/measure_design",
    method="POST",
    json=measures,
    options={
        "name": "Dummy Measure Design", 
        "folder_id": "folder-id-123"
    }
)

This example creates a measure named "x-at-P10D," which tracks a timeseries value at 10 days for each arm of the protocol.

Creating a Trial​

To create a trial, you need to provide the computational model, protocol design, virtual population, and any measures you want to track.

Example Request to Create a Trial​

import jinko_helpers as jinko

trial_design = {
    "computationalModelId": {
        "coreItemId": "model-core-id-123",
        "snapshotId": "model-snapshot-id-123"
    },
    "protocolDesignId": {
        "coreItemId": "protocol-core-id-123",
        "snapshotId": "protocol-snapshot-id-123"
    },
    "vpopId": {
        "coreItemId": "vpop-core-id-123",
        "snapshotId": "vpop-snapshot-id-123"
    },
    "measureDesignId": {
        "coreItemId": "measure-core-id-123",
        "snapshotId": "measure-snapshot-id-123"
    },
}

response = jinko.make_request(
    path='/core/v2/trial_manager/trial',
    method='POST',
    json=trial_design,
    options={
        "name": "Test Trial",
        "folder_id": "folder-id-123"
    }
)

project_item_info = jinko.get_project_item_info_from_response(response)
trial_core_item_id = project_item_info["coreItemId"]["id"]
trial_snapshot_id = project_item_info["coreItemId"]["snapshotId"]

This request creates a trial using a specified computational model, protocol, and virtual population.

Running a Trial​

Once a trial is created, you can run it using the following request:

import jinko_helpers as jinko

jinko.make_request(
    path='/core/v2/trial_manager/trial/{trial-core-item-id}/snapshots/{trial-snapshot-id}/run',
    method='POST'
)

Monitoring Trial Status​

You can monitor the trial's status using the monitor_trial_until_completion function:

import jinko_helpers as jinko

jinko.monitor_trial_until_completion(
    trial_core_item_id='trial-core-item-id-123',
    trial_snapshot_id='trial-snapshot-id-123'
)

This function will continuously check the trial's progress until it is completed.

Additional Resources​

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