J.R. Green, M.J. Korenberg and M.O. Aboul-Magd

About PCI-SS

PCI-SS is a protein secondary structure prediction engine developed by J.R. Green, M.J. Korenberg and M.O. Aboul-Magd. The tool relies on Parallel Cascade Identification (PCI) to make predictions from primary sequence data. To learn more about PCI-SS, please consult the Official PCI-SS page.

How to interact with the PCI-SS API

Endpoints

The actions currently supported are listed below:

Actions
Action Endpoint HTTP Method
Retrieve a prediction http://bioinf.sce.carleton.ca/api/pciss/jobs/<Job ID>?format=<xml or json> GET
Submit a prediction request http://bioinf.sce.carleton.ca/api/pciss/jobs/ POST

Both actions return a job object described in the following section.

Response Schema

Since earlier versions of the PCI-SS API served predictions in the XML format, support for XML responses was preserved. Note, however, that the default format has been changed to JSON, the de facto standard for RESTful APIs.

{
  "jobID": "example",
  "status": "completed",
  "secondaryStructure": {
  "sequenceName": "mySequence",
  "length": "60",
  "data":
    [{
      "position": "1",
      "aminoAcid": "M",
      "prediction": "other",
      "eDistance": "4.79",
      "tDistance": "0.03",
      "hDistance": "8.42"
     },
    ...,
    {
      "position": "60",
      "aminoAcid": "G",
      "prediction": "other",
      "eDistance": "3.98",
      "tDistance": "0.00",
      "hDistance": "6.64"
    }]
  }
}
<?xml version='1.0'?>
<job>
  <jobID>example</jobID>
  <status>completed</status>
  <secondaryStructure>
    <sequenceName>mySequence</sequenceName>
    <length>60</length>
    <data>
        <position>1</position>
        <aminoAcid>M</aminoAcid>
        <prediction>other</prediction>
        <eDistance>4.79</eDistance>
        <tDistance>0.03</tDistance>
        <hDistance>8.42</hDistance>
    </data>
    ...
    <data>
        <position>60</position>
        <aminoAcid>G</aminoAcid>
        <prediction>other</prediction>
        <eDistance>3.98</eDistance>
        <tDistance>0.00</tDistance>
        <hDistance>6.64</hDistance>
    </data>
  </secondaryStructure>
</job>

Responses to unsucessful requests only contain the fields status and reason. In such cases, the field status will take the value "failed", allowing you to check whether a request was successful in your code.

Note: We ask that you kindly store the Job IDs of processed submissions. This way, the prediction will be accessible via a GET request, should you need to retrieve the prediction at a later time.

Submitting a prediction request

To submit a prediction request, you must send a POST request to the appropriate URI endpoint (see above). The parameters that can be provided within a request are tabulated below.

POST Request Parameters
Parameter Type Required/Optional Description Acceptable values
sequenceName String Required The name of the protein sequence Any non-empty string
sequence String Required The amino sequence of the protein An amino acid sequence of at least 25 amino acids. PCI-SS supports the 20 standard amino acids and "X" to denote an unknown amino acid. (Note: FASTA tags are ignored)
format String Optional The response format "json" (default) or "xml"

Here are a couple of examples for Python3 and Perl users:

import urllib.request
import urllib.parse


if __name__ == '__main__':

    # Define the request URI
    REQUEST_URI = 'http://bioinf.sce.carleton.ca/api/pciss/jobs/'
    DATA = {'sequenceName':'mySequence',\
            'sequence':'MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHG',\
            'format':'json'}

    # Encode the data
    DATA = urllib.parse.urlencode(DATA).encode('utf-8')

    # Make the request and do something
    with urllib.request.urlopen(REQUEST_URI, DATA) as response:
        result = response.read().decode(encoding='utf-8')

        # Use the result
        print(result)
#!/usr/local/bin/perl

use LWP::UserAgent;

# Create a user agent
my $ua = LWP::UserAgent->new;

# Define the URI and the data
my $URI = "http://bioinf.sce.carleton.ca/api/pciss/jobs/";

my $DATA = '{"sequenceName":"mySequence",
"sequence":"MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHG",
"format":"json"}';

# Instantiate the POST request and append the data
my $req = HTTP::Request->new(POST => $URI);
$req->header('content-type' => 'application/json');
$req->content($DATA);

# Send the request
my $resp = $ua->request($req);
if ($resp->is_success) {
    my $result = $resp->decoded_content;

    # Use the result
    print $result;
}
else {
    # Handle the error
    print "ERROR: ", $resp->code, "\n";
}

Retrieving a prediction

To retrieve a recent prediction, you simply need to make a GET request and specify the desired Job ID in the URI and the desired format (XML or JSON) in the query string via the optional parameter format (the default format is JSON). Here is an example in Python3 and Perl.

import urllib.request

if __name__ == '__main__':

    # Define the request URI
    ENDPOINT = 'http://bioinf.sce.carleton.ca/api/pciss/jobs/{}?format={}'
    JOB_ID = 'example'
    FORMAT = 'xml'
    REQUEST_URI = ENDPOINT.format(JOB_ID, FORMAT)

    # Make the request and do something
    with urllib.request.urlopen(REQUEST_URI) as response:
        result = response.read().decode(encoding='utf-8')

        # Use the result
        print(result)
#!/usr/local/bin/perl

use LWP::Simple;

# Define the parameters (job id and format)
$jobID = "example";
$format = "json";

# Make the GET request
$result = get("http://bioinf.sce.carleton.ca/api/pciss/jobs/$jobID?format=$format");

# Use the result
print $content;