Skip to content

Vidjil APIs⚓︎

These APIs were first released in 2022, and continue to improve as of 2023. Please contact us for additional details.

Vidjil server API⚓︎

This API and the Python Vidjil library allows to interact with a Vidjil server, notably:

  • to automate parts of your workflows (patient/sample/run creation, data upload, analysis launch),
  • and to perform batch analysis of data.

Code examples can be found in tools/api_demo.py, and first steps are below.

Warning

When interacting with a production server (such as Vidjil public servers), please be very careful on requests you send, especially when updating or deleting data. Do not spam the Vidjil public servers.

First steps⚓︎

Install required libraries

pip install requests bs4 tabulate requests-toolbelt urllib3

Download SSL certificate of target Vidjil server.

SERVERNAME=localhost # adapt it to your need
echo -n | openssl s_client -connect $SERVERNAME:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ./cert_$SERVERNAME.pem

You can then use the API.

from api_vidjil import Vidjil

ssl_pem="path/cert_SERVERNAME.pem"

vidjil = Vidjil(server_url, ssl=ssl_pem)
vidjil.login(user, password)

A confirmation is displayed with your user name. You can now interact with the server to get some data, for example of the demo patient Lil-l3.

sample_set_id = 25736  # Demo lil L3
config_id     = 25     # multi+inc+xxx

### Get a set from server by his id and set type
sets_demo = vidjil.getSetById(sample_set_id, vidjil.PATIENT)
vidjil.infoSets("Set %s" % sample_set_id, sets_demo, set_type=vidjil.PATIENT, verbose=True)

Further use⚓︎

The api_demo.py has more examples, especially in the demoWriteRunOnServerfunction.

Vidjil-algo analyze API⚓︎

This API runs vidjil-algo with the default parameters to compute V(D)J assignations on DNA sequences. It takes a limited number of Fasta sequence (up to 10) and returns a .vidjil file with the analysis of these sequences, such as here:

import requests
import json

# Subset of sequences from demo/Demo-X5.fa
sequences = '''>seq1
CCCAGGCTCCTCATCTATGATGCATCCACCAGGGCCACTAGCATCCCAGCCAGGTTCAGTGGCAGTGGGTCTGGGACAGACTTCACTCTCACCATCAGCAGCCTGCAGCCTGAAGATTTTGCAGTTTATTACTGTCAGCAGGATTATAACTTACCTCGTGGAGGCAGCCCAGGGCGACTCCTCATGAGTCTGCAGCTGCATTTTTGCCATATCCACTATTTGGAGTCTGACCTCCCTAGGAAGCCTCCCTGCTCCCTAGGACAACCTGCTCTGACCTCTGAGG
>seq2
AACGGTGTAGTGGATGATTCACAGTTGCCTAAGGATCGATTTTCTGCAGAGAGGCTCAAAGGAGTAGACTCCACTCTCAAGATCCAGCCTGCAAAGCTTGAGGACTCGGCCGTGTATCTCTGTGCCAGCAGCTTAGGTCCCTCGTACGAGCAGTACTTCGGGCCGGGCACCAGGCTC
>seq3
AGCGGGTGGTGATGGCAAAGTGCCAAGGAAAGGGAAAAAGGAAGAAGAGGGTTTTTATACTGATGTGTTTCATTGTGCCTTCCTATGGCAGTGCTACAAAACCTACAGAGACCTGTACAAAAACTGCAGGGGCAAAAGTGCCATTTCCCTGGGATATCCTCACCCTGGGTCCCATGCCTCAGGAGACAAACACAGCAAGCAGCTTCCCTC
'''

# POST url of the server
url_post = "https://db.vidjil.org/vidjil/segmenter"

r = requests.post(url_post, data={'sequences': sequences})
print(r.status_code) # Should be 200 if everything is Ok

vidjil = r.json() # Convert raw text data into json
print(f"Vidjil-algo found {len(vidjil['clones'])} clonotypes.")

for clone in vidjil["clones"]:
    print( f"\t{clone['germline']}; {clone['name']};")

To perform analyses on more data from the command line, please install and use vidjil-algo.