Usage

You can integrate PSOS into your application either via direct API calls to the REST service (see Rest Api) or you can integrate it via the javascript library psos.js as described in the following sections.

The psos.js library contains the following actions:

  • init the library with server locations

  • submit a job

  • retrieve job information

  • retrieve job files

  • listen to job changes

  • redirect to the psos visualization page

psos.js depends on the following libraries:

  • jquery (for rest api calls)

  • vertx-web-client, sockjs (for push notifications)

Submit job and visualize it with PSOS

Step 1 - Include dependencies

Include the required libraries into your application. For convenience reasons you can use cdn versions and psos.js hosted by us.

<script src="https://cdnjs.cloudflare.com/ajax/libs/sockjs-client/1.3.0/sockjs.min.js" integrity="sha256-hA6gdrQ9v1ZKkJuwgtwod0CpbzxEg/zAJPcXYwba7Mc=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/vertx/3.7.0/vertx-eventbus.min.js" integrity="sha256-MaQLuO1T3KhNPwU21XB4KJgavikjmlLDqwCsGeje00Y=" crossorigin="anonymous"></script>
<script src="https://psos-staging.computational.bio/api/v1/psos.js"></script>

Step 2 - Initialize psos.js

psos.js does not come with a preconfigured server, so you have to initialize it with appropriate server locations.

// initialize api endpoint
psos.init('https://psos-staging.computational.bio/api/v1')

If you want to redirect to the PSOS job result page automatically, then you should not only initialize the api endpoint, but also the webserver location.

// initialize api endpoint and psos webserver location
psos.init('https://psos-staging.computational.bio/api/v1', 'https://psos-staging.computational.bio')

Step 3 - Submit a job

You need either the raw sequence of your protein or a fasta entry of your protein and you need to know the profile you want to execute.

Available (public) profiles are:

  • bacteria-gram+

  • bacteria-gram-

  • eukaryote

  • eukaryote-plant

var request = {
  'configuration': {'profile': 'bacteria-gram+'},
  'sequence': `>tr|Q189L9|Q189L9_PEPD6 Extracytoplasmic function (ECF) sigma factor csfT OS=Peptoclostridium difficile (strain 630) OX=272563 GN=csfT PE=3 SV=1
     MDKTTFTNNILESEQTLYRVSKSILGNDQDCEDAVNNAILKAYEKLDSLKEEQYFKTWLI
     RIVINECNSLRRKRLKSLSFEDVFKNKKIDEKDDYSDLYTAIQSLPKKIKIPIVLYYIEG
     YSVDEVKEILDIPQGTVKSRLSRGRRLLKTKLENTEVII`
}
psos.submit(request,
   function (job) {
     // replace with your code when the job was sumitted successfully
     console.log(job)
   },
   function (error) {
     // replace with your code when an error occured in the job submission
     console.log(error)
   }
 )

If you would like to use the default PSOS visualization, you can use the predefined psos.redirect function to automatically redirect to the visualization. Be sure that you initialized the library with both, the api endpoint and the webapplication url.

psos.submit(request,
   psos.redirect,
   function (error) {
     // replace with your code when an error occured in the job submission
     console.log(error)
   }
 )

Integrate the results in your application

If the default visualization does not fit your needs, you can implement your own visualization based on the PSOS results. In this section you will see how to listen to job changes and how to list and retrieve the result files.

Listen to job changes

You can get notifications about job changes. Therefore you need to register a success and an error function for a job id.

var my_jobid = '...'
psos.listen(my_jobid,
   function (job_message) {
     // replace with your code that handles the message or job
     console.log(job_message.data) // log the job
   },
   function (error) {
     // replace with your code that handles errors
     console.log(error)
   }
 )

List job files

The psos job object has references to all available files for the job. You can access them via the files array.

var my_jobid = '...'
psos.job(my_jobid,
   function (job) {
     console.log(job.files) // list available files
   },
   function (error) {
     // replace with your code that handles errors
     console.log(error)
   }
 )

Each file object has a type and a name. Available type are:

  • Input - For input data

  • TemporaryResult - For intermediate results (contains only result for a single tool)

  • Result - For final results

Retrieve file content

To access a file you can call the psos.file method.

var my_jobid = '...'
var my_file = '...'
psos.file(my_jobid,
   my_file,
   function (content) {
     console.log(content) // log file content
   },
   function (error) {
     // replace with your code that handles errors
     console.log(error)
   }
 )

Delete a job

To delete a job you can call the psos.delete method.

var my_jobid = '...'
psos.delete(my_jobid,
   function (content) {
     // replace with your code that handles success
     console.log(content)
   },
   function (error) {
     // replace with your code that handles errors
     console.log(error)
   }
 )