Python Library

Prerequisites

Recommended Python version: 3.7 <= version <= 3.10

Installation

The python client can be installed in two ways:

From our public Python package registry

pip install --extra-index-url https://us-python.pkg.dev/cyrus-containers/levitate-py-public/simple engine-client

# Installing a specific version

pip install --extra-index-url https://us-python.pkg.dev/cyrus-containers/levitate-py-public/simple/ engine-client==<VERSION>

Using the .whl file

Navigate to https://api-authorization.levitate.bio and click on ‘Get Files’. Download the latest python client .whl file.

Run the following command to install:

pip install path/to/<file>.whl

Initializing your client

Jobs can be submitted and results retrieved using a python 3 client library. The client object can be constructed on one of two ways:

1a) Use values in your ~/.engine_config.json (Recommended)

If you construct the client with no arguments, the config values stored in an existing configuration file at $HOME/.engine_config.json

from engine import EngineClient

client = EngineClient()

1b) Create configuration file when constructing client

If you do not have a configuration file yet, when you construct your client you can create a new configuration file by passing in the server address and setting create_config to True.

If you do not set create_config, credentials will not be cached to the configuration file.

from engine import EngineClient

client = EngineClient(
  server="engine.<CODENAME>.levitate.bio"
  create_config=True
)

1c) Manually configure client using client ID and client secret (Deprecated)

Alternately, you may configure the client manually.

NOTE: This is not recommended. This method is deprecated and will be removed in future versions. Please follow the recommended method to minimize issues

client_id — The client ID obtained from https://api-authorization.levitate.bio
client secret — The secret obtained from https://api-authorization.levitate.bio
server — The address of your Cyrus API server. This will be provided to you during onboarding (I.E. engine.<given-codename>.levitate.bio)
port — The Cyrus API server port, you should use port 443 unless otherwise instructed during onboarding.

from engine import EngineClient

client = EnglineClient(
  client_id="client_id",
  client_secret="client_secret",
  address="engine.codename.levitate.bio",
  port=443
)

Submitting Jobs

There for each API service, the client provides a submit_<servicename> method. For example, to submit an epitope scan job:

mhc_list = ["H-2-IAb"]
sequence = "NLYIQWLKDGGPSSGRPPPS"
job_id = client.submit_epitope_scan(alleles=mhc_list, sequence=sequence)

Retrieving job results

You can get the status of the job by running:

client.get_status(job_id)

where job_id is the object returned by the submit method

The client.get_results() method will not return your results until the job is complete. Once complete, this method will return an dictionary containing the results. The results object will have attributes for each file produced by the API job. For example, to download the “csv” artifact produced by the epitope scan API to the directory “output_dir/” you could use code like this:

results = client.get_results(job_id)
results["csv"].dump(“output_dir/”)