How-To Use CanRisk Web-Services

Owned by Tim Carver
Last updated: Nov 14, 2024
2 min read

These are the web-services:

  1. auth-token; retrieve an authentication token (for use with the other web-services).

  2. boadicea; calculates risks and mutation carrier probabilities for breast cancer.

  3. ovarian; calculates risks and mutation carrier probabilities for ovarian cancer.

  4. vcf2prs; takes a VCF file and returns a PRS (alpha and z-score) for use in the breast and ovarian cancer web-services.

The following describes auth-token and boadicea.

All requests to the web-services are made over HTTPS. An authentication token can be requested using the ‘auth-token’ web-service and added to the request authorization headers. Data is sent to and from the web-service in JSON format.

Patient identifiable data is not needed to run the risk calculations and the client software should remove this to de-identify the data before submitting the request to the web-service.

The web-service supports the pedigree data submitted in the CanRisk file format and BOADICEA pedigree data format v4 (see the BOADICEA documentation Appendix). It can be sent either as a ‘pedigree_data’ field in the JSON request or posted as a file. See the example usage below.

Instructions

The following examples use the curl command to send requests to each of the web-services.

  1. Obtaining Authentication Token (replace URL with the CanRisk website address):

    curl -k 'https://{URL}/auth-token/' \
    -d '{"username": "XYZ", "password": "ABC"}' \
    -H "Content-Type: application/json"

  2. Running a breast cancer risk calculation with pedigree data as a JSON parameter (replace with the authentication token):

    CanRisk v2 format
    curl -k -XPOST -H "Content-Type: application/json" -d '{"mut_freq":"UK","cancer_rates":"UK","user_id":"end_user_id","pedigree_data":"##CanRisk 2.0\n##menarche=14\n##parity=1\n##first_live_birth=23\n##oc_use=N\n##mht_use=N\n##BMI=21.8\n##alcohol=22.4\n##height=177.8\n##TL=N\n##endo=N\n##FamID\tName\tTarget\tIndivID\tFathID\tMothID\tSex\tMZtwin\tDead\tAge\tYob\tBC1\tBC2\tOC\tPRO\tPAN\tAshkn\tBRCA1\tBRCA2\tPALB2\tATM\tCHEK2\tBARD1\tRAD51D\tRAD51C\tBRIP1\tER:PR:HER2:CK14:CK56\nDATA4\t0\t0\tm21\t0\t0\tM\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0:0:0:0\nDATA4\t1\t0\tf21\t0\t0\tF\t0\t0\t66\t1955\t0\t0\t65\t0\t0\t0\tS:N\tS:N\tS:N\tS:N\tS:N\tS:P\tS:N\tS:N\tS:N\t0:0:0:0:0\nDATA4\t2\t1\tch1\tm21\tf21\tF\t0\t0\t44\t1977\t0\t0\t0\t0\t0\t0\tS:P\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0:0:0:0\nDATA4\t3\t0\tHGkX\tMERR\tch1\tF\t0\t0\t19\t2000\t0\t0\t0\t0\t0\t0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0:0:0:0\nDATA4\t4\t0\tMERR\t0\t0\tM\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0\t0:0:0:0:0\n"}' https://URL/boadicea/ -H "Authorization: Token <TOKEN>"

    or with a pedigree file POSTed as a form
    curl -k -XPOST -F "mut_freq=UK" -F "cancer_rates=UK" -F "user_id=end_user_id" -F "pedigree_data=@/home/xxxx/d10.canrisk" https://{URL}/boadicea/ -H "Authorization: Token <TOKEN>" -H "Accept: application/json"

  3. Running a ovarian cancer risk calculation with a pedigree file POSTed as a form:
    curl -k -XPOST -F "mut_freq=UK" -F "cancer_rates=UK" \
    -F "user_id=end_user_id" \
    -F "pedigree_data=@/home/xxx/bwa4_pedigree_data.txt" \
    https://{URL}/ovarian/ -H 'Authorization: Token <TOKEN>' -H "Accept: application/json"

  4. Obtaining a PRS for breast cancer:
    curl -k -XPOST -F "bc_prs_reference_file=BCAC_313_PRS.prs" -F "sample_name=SampleA" \
    -F "vcf_file=@/home/xxx/sample_BCAC_313.vcf" \
    https://{URL}/vcf2prs/ \
    -H 'Authorization: Token <TOKEN>' -H "Accept: application/json"

 

Related articles