toxCSM API


API - Documentation



Here we provide an API (Application Programming Interface) to help users in integrating toxCSM into their research pipelines. In a nutshell, all predictive jobs submitted to toxCSM's server are linked with a unique ID. This ID can be used to query the status of the job and to retrieve its results (after submission being processed).

Job Submission Via API - Single SMILES


You should always use the following URL to submit your jobs via API: http://biosig.lab.uq.edu.au/toxcsm/api/predict

POST

Arguments:

  • smiles_string - Single SMILES string.
  • email (optional) - Email for contact when the job is finished.
  • pred_type (optional) - The type of prediction to be done. Options are:.
    • stress_response
    • "nuclear_response
    • environmental
    • organic
    • human_dose_response
    • genomic
    • all (default)

Return:

  • job_id - ID used for uniquely identify each job

Examples (using curl):



curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F smiles_string="COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1"

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F smiles_string="COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1" -F pred_type="organic"

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F smiles_string="COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1" -F pred_type="nuclear_response" -F email_address="your_username@your_provider.com"

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F smiles_string="COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1" -F pred_type="all" -F email_address="your_username@your_provider.com"                  	
            

Examples (using python):

You can find the python sample code by clicking at: toxcsm_api_smiles_post.py . If you want to use it, you can provide to run python the same parameters described for curl:


python toxcsm_api_smiles_post.py --smiles_string "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1"

python toxcsm_api_smiles_post.py --smiles_string "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1" --pred_type "organic"   

python toxcsm_api_smiles_post.py --smiles_string "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1" --pred_type "nuclear_response" --email_address "your_username@your_provider.com" 

python toxcsm_api_smiles_post.py --smiles_string "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1" --pred_type "all" --email_address "your_username@your_provider.com" 
            

Example of Response from the toxCSM's Server:



HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 51
Server: Werkzeug/0.16.0 Python/2.7.17
Date: Wed, 17 Nov 2021 04:19:55 GMT

{
    "job_id": "nuclear_response_1637122795.02"
}			
			

GET

Arguments:

  • job_id - ID used for uniquely identify each job.

Return:

For jobs still being processed or waiting on queue, the message below will be returned from querying the respective sample(s):


{
    "status": "running"
}
			

Examples (using curl):



curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X GET -F job_id="nuclear_response_1637122795.02"            	
            

Examples (using python):

You can find the python sample code by clicking at: toxcsm_api_get.py . If you want to use it, you can retrieve your results in python using the same parameter described for curl:


python toxcsm_api_get.py --job_id nuclear_response_1637122795.02               
            

Example of Response from the toxCSM's Server:

After processed, users will get information for each predictive category chosen and its respective models. Information include the category of the model, the machine learning task, the unit, the processed SMILES, the prediction, the confidence score, and the interpretation for the prediction based on the confidence score.

Models are identified by molecule as users can submit a job containing several molecules at the same time into files (as shown bellow).


{
    "NR-AR [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.009, 
        "Interpretation": "High Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-AR-LBD [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.017, 
        "Interpretation": "High Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-AhR [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence_Score": 0.813, 
        "Interpretation": "Medium Toxicity", 
        "Prediction": "Toxic", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-Aromatase [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.034, 
        "Interpretation": "High Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-ER [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.498, 
        "Interpretation": "Low Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-ER-LBD [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.26, 
        "Interpretation": "Medium Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-GR [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.277, 
        "Interpretation": "Medium Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-PPAR-gamma [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.014, 
        "Interpretation": "High Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }, 
    "NR-TR [Molecule 1]": {
        "Category": "Nuclear Response", 
        "Confidence Score": 0.34, 
        "Interpretation": "Low Safety", 
        "Prediction": "Safe", 
        "SMILES": "COC1=C(O)C=C2C(OC(=O)C=C2C2=CC(O)=C(O)C=C2)=C1", 
        "Task": "Classification", 
        "Unit": "Category (Toxic/Safe)"
    }
}		
			


Job Submission Via API - SMILES File

A SMILES file can have several SMILES (at most 1000 for toxCSM's jobs). The only thing that differs from the documentation about using the API to submit a single SMILES is the POST method. Therefore, we will take only this part into consideration for sake of simplicity.

POST

Arguments:

  • smiles_file - Path for the SMILES file.
  • email (optional) - Email for contact when the job is finished.
  • pred_type (optional) - The type of prediction to be done. Options are: .
    • stress_response
    • "nuclear_response
    • environmental
    • organic
    • human_dose_response
    • genomic
    • all (default)

Return:

  • job_id - ID used for uniquely identify each job

Examples (using curl):



curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -X POST -i -F smiles_file=@"/home/user/sample.smi"

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F smiles_file=@"/home/user/sample.smi" -F pred_type="stress_response"

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F smiles_file=@"/home/user/sample.smi" -F pred_type="nuclear_response" -F email_address="your_username@your_provider.com" 

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F smiles_file=@"/home/user/sample.smi" -F pred_type="all" -F email_address="your_username@your_provider.com"              	
            

Examples (using python):

You can find the python sample code by clicking at: toxcsm_api_smiles_file_post.py . If you want to use toxCSM in python providing a SMILES file, use the same parameters described for curl:


python toxcsm_api_smiles_file_post.py --smiles_file "/home/user/sample.smi"

python toxcsm_api_smiles_file_post.py --smiles_file "/home/user/sample.smi" --pred_type "organic"   

python toxcsm_api_smiles_file_post.py --smiles_file "/home/user/sample.smi" --pred_type "nuclear_response" --email_address "your_username@your_provider.com" 

python toxcsm_api_smiles_file_post.py --smiles_file "/home/user/sample.smi" --pred_type "all" --email_address "your_username@your_provider.com" 
            


Job Submission Via API - SDF

An SDF (Structure Data File) can have several molecules (at most 1000 for toxCSM's jobs). Again, the only thing that differs from the documentation about using the API to submit a single SMILES is the POST method. Therefore, we will take only this part into consideration for sake of simplicity.

POST

Arguments:

  • sdf - Path for the SDF.
  • email (optional) - Email for contact when the job is finished.
  • pred_type (optional) - The type of prediction to be done. Options are: .
    • stress_response
    • "nuclear_response
    • environmental
    • organic
    • human_dose_response
    • genomic
    • all (default)

Return:

  • job_id - ID used for uniquely identify each job

Examples (using curl):



curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -X POST -i -F sdf=@"/home/user/sample.sdf"

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F sdf=@"/home/user/sample.sdf" -F pred_type="stress_response"

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F sdf=@"/home/user/sample.sdf" -F pred_type="nuclear_response" -F email_address="your_username@your_provider.com"  

curl  http://biosig.lab.uq.edu.au/toxcsm/api/predict -X POST -i -F sdf=@"/home/user/sample.sdf" -F pred_type="all" -F email_address="your_username@your_provider.com"
            

Examples (using python):

You can find the python sample code by clicking at: toxcsm_api_sdf_post.py . If you want to use toxCSM in python providing an SDF, use the same parameters described for curl:


python toxcsm_api_smiles_post.py --sdf "/home/user/sample.sdf"

python toxcsm_api_smiles_post.py --sdf "/home/user/sample.sdf" --pred_type "organic"   

python toxcsm_api_smiles_post.py --sdf "/home/user/sample.sdf" --pred_type "nuclear_response" --email_address "your_username@your_provider.com" 

python toxcsm_api_smiles_post.py --sdf "/home/user/sample.sdf" --pred_type "all" --email_address "your_username@your_provider.com"