Skip to main content

05. Protocol

How to create a Protocol in Jinko​

A protocol in Jinko represents a set of experimental conditions that can be applied to a virtual population (VPOP) to simulate different scenarios. This section explains how to create a protocol using the Jinko API.

What is a Protocol?​

A protocol allows you to test different experimental conditions such as varying doses of a drug or treatment regimens. Each protocol arm is applied to all patients in the VPOP, and all patients in the same arm will have identical values for the protocol inputs.

More details are available in the protocol guide.

Posting a Protocol​

You can create a protocol design from a list of scenario arms using create_protocol_design. The example below creates a protocol with two arms, each with a different treatment dose.

from jinko import JinkoClient

client = JinkoClient()

arms = [
    {
        "armName": "arm_1",
        "armOverrides": [
            {"formula": "10", "key": "dose"},
        ],
    },
    {
        "armName": "arm_2",
        "armOverrides": [
            {"formula": "20", "key": "dose"},
        ],
    },
]

protocol_design = client.create_protocol_design(
    arms,
    name="Test Protocol",
    description="A protocol with two arms",
    folder="folder-id-123",
)

If you're binding the protocol to a specific model, pass it as model=... — this can also be called as model.create_protocol_design(arms) directly.

Posting a Protocol from raw content​

There's no typed CSV-arms helper for protocol designs. If you're loading arms from a CSV file, convert them into the arms list shown above and use create_protocol_design.

If you already have a full protocol-design payload built elsewhere (for example ported from an existing script), you can post it as-is with client.create_protocol_design_from_json(payload):

from jinko import JinkoClient

client = JinkoClient()

protocol_payload = {"scenarioArms": arms}

protocol_design = client.create_protocol_design_from_json(protocol_payload, name="Test Protocol")

Additional Resources​

For more information about setting up protocol arms, refer to the community guide on protocols.