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:

If you construct the client with no arguments, the config values stored in $HOME/.engine_config.json when you ran lev init will be used

from engine import EngineClient

client = EngineClient()

1b) 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
)

2) Authorize your client

Once the client is constructed, you will want to authorize your client so it can be used to submit jobs and retrieve results:

client.authorize()

This will use the access token store in your configration file and check if it is valid. If it is not, it will try to update it. If you are having issues authenticating, run lev init again to reinitialize your configuration file.

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/”)

Updated: