Usage
=====

You can integrate PSOS into your application either via direct API calls to the
REST service (see :ref:`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.

.. code-block:: html

   <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.

.. code-block:: javascript
   
   // 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.

.. code-block:: javascript
   
   // 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``

.. code-block:: javascript

   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.

.. code-block:: javascript

   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.

.. code-block:: javascript

   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.

.. code-block:: javascript

   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.

.. code-block:: javascript

   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.

.. code-block:: javascript

   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)
      }
    )