PSIPRED REST API

The webserver supports REST access for automated job submission with calls to the URI http://bioinf.cs.ucl.ac.uk/psipred_new/api/

There are 3 main user endpoints.

jobtimes

endpoints

  • URI: http://bioinf.cs.ucl.ac.uk/psipred_new/api/endpoints/
  • Description: HTTP GET returns a JSON object which contains and array of URI options for each possible anaysis that can be requests. These details can be used to understand the submission details for each job type and how to construct the submission URIs and HTTP parameters needed for each job submission. See submission below for each job type.

submission

POST

  • URI: http://bioinf.cs.ucl.ac.uk/psipred_new/api/submissions/
  • Description: An HTTP multipart POST request to this URL can be used to submit data for analysis to the server. In order to do so the URI stub, http://bioinf.cs.ucl.ac.uk/psipred_new/api/, must be combined with the information requested from an "endpoints" GET.

    For instance Combining the main URI stub and the param information for a psipred job gives the following:

    http://bioinf.cs.ucl.ac.uk/psipred_new/api/submission/&job=psipred&submission_name=[STRING]&email=[EMAIL_STRING]&input_data=[FILE]

    You must also provide valid data for the HTTP parameters. Given the above example the params are:

    • job: A string indicating which analysis available you wish to run, and must match on of the options given when calling endpoints/
    • name: A user defined string which gives a human readable name for the data submission
    • email: API users are required to submit an email address
    • input_data: A file containing the data to be analysed, in this case a fasta formatted protein sequence or MSA

    These parameters are required for all submissions. Dompred, FFPred, Metsite, HSPred and MEMEMBED require additional parameters, described below

Job Specific http options

Dompred
  • psiblast_dompred_evalue: Positive real value number, we suggest one of 0.1, 0.01, 0.001, 0.0001. We advise 0.01
  • psiblast_dompred_iterations: Integer value for the number of PSI-BLAST iterations to run. typically 1 to 20, we advise 5
FFPred
  • ffpred_selection: string indicating where to make predictionos with either the human or fly SVMs. Accepted values 'human' or 'fly'
Metsite
  • metsite_checkchains_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. A
  • extract_fasta_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. A
  • seedSiteFind_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. A
  • seedSiteFind_metal: String indicating which metal ion to analyse must be one of CU, CA, FE, MG, MN, ZN
  • metpred_wrapper_fpr: Integer indicating the false positive rate value must be one of 0, 1, 2, 3.
  • metpred_wrapper_metal: String indicating which metal ion to analyse must be one of CU, CA, FE, MG, MN, ZN
  • metpred_wrapper_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. A
Note: Values for metsite_checkchains_chain, seedSiteFind_chain, extract_fasta_chain, metpred_wrapper_chain must all be the same Note 2: Value for seedSiteFind_metal and seedSiteFind_metal must be the same
HSPred
  • hspred_checkchains_chains: A string of 2 characters indicating the 2 chains that are to be analysed in the PDB file. e.g. AB
  • hs_pred_second_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. B
  • hs_pred_first_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. A
  • split_pdb_files_second_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. B
  • split_pdb_files_first_chain: The PDB Chain ID. Must be an upper case single alphanumeric character, e.g. A
Note: values of hs_pred_second_chain and split_pdb_files_second_chain must be the same Note: Values of hs_pred_first_chain and split_pdb_files_first_chain must be the same
MEMEMBED
  • memembed_termini: String indicating whether the n-termini is inside the cell or not. Must be one of 'in' or 'out'
  • memembed_barrel: String indicating whether the PDB file given is a beta barrels. One of 'true' or 'false'
  • memembed_algorithm: Integer indicating which minimisation algorithm to use. One of 0, 1, 2, 3. 0: Genetic Algorithm, 1 Grid Search, 2 Direct, 3 GA repeated 5 times

On successful submission the server will return a JSON object which contains the fields UUID, state, and message. If the state is an error the message will contain human readable information about what the data submission was rejected and the UUID field will be blank. If the state is 'submitted', the data will be posted to the job queue for processing and the UUID field will be filled in. You can use this UUID to poll the service to monitor job progress or job completing

SUBMISSION GET (job progress)

  • URI: http://bioinf.cs.ucl.ac.uk/psipred_new/api/submission/[UUID]
  • Description: If job submission was succesful and you have a valid UUID you can use this to poll the service for job completion by Combining the GET URI and the UUID as so, http://bioinf.cs.ucl.ac.uk/psipred_new/api/submission/06e8ebc2-2b8d-11e9-ba87-00163e100d53.

This will return a JSON object where the field 'state' informs you of the current state of the job:

  • Running: The job is still being analysed, you can check the "last_message" field for a human readable progress message
  • Complete: The job is complete and all results are available to download
  • Error: The job has ended and some component has crashed of failed to complete. Check the "last_message" field and send this informationto psipred@cs.ucl.ac.uk for further help

On complettion the data_path fields can be parsed to get the names of the results files

SUBMISSIONS GET (results files)

  • URI: http://bioinf.cs.ucl.ac.uk/psipred_new/api/submissions/[FILE_NAME]
  • Description: GET requests to this URL (note the difference in spelling) can be used to get each results file once a job has been completed. Combining the URI stub, http://bioinf.cs.ucl.ac.uk/psipred_new/api, with the contents of the data_path fields in the results JSO (above) allows you to get each results file in turn. i.e. http://bioinf.cs.ucl.ac.uk/psipred_new/api/submissions/06f03044_1.B99990001_CJ2d9kv.pdb Note the extra 's' in the spelling of submissions relative to the previous GETs

Example Script

You can download an example script python script which demonstrated submitting jobs from Here