ProCKSI

h1. The ProCKSI "stand-alone" applications

h2. ProCKSI/Comparison

ProCKSI/Comparison integrates a variety of similarity comparison methods (e.g. USM, MaxCMO, TM-align, ...) producing different similarity measures  (e.g. Z-score, TM-score, RMSD, ...) each. Each of the comparison methods produces output with different formats and additional content such as alignments, rotation matrix, etc. Some of them produce just one output file, others a set of linked HTML files.

Additionally, there are pre-processing methods, e.g. extracting models/chains from PDB structures, or preparing contact maps from structures/chains.

h2. ProCKSI/Consensus

ProCKSI/Consensus integrates a variety of post-processing methods that all deal with an etire dataset in form of similarity matrices or trees. The former can be clustered or combined in order to form a consensus using a Total Evidence approach, the latter can be combined using a Total Consensus approach. Each of these methods has its own input parameters and produces output in different format.

h1. Why is Data Standardisation necessary?

The goal is to allow the ProCKSI "stand-alone" applications to: 

* be developped independently from the ProCKSI/Server (incl. webserver/database), and allow collaborators to seamlessly integrate their own methods. One might even think of making the code publically available and allow the community to improve it.

* run on any (Linux) machine that has the necessary methods installed. This can be either a collaborator's desktop machine, the ProCKSI cluster, the University Cluster, or even a machine on the Grid.

* further distribute the given task using local machines, Grid and Web Service technology in order to obtain their results without the need to schedule everything from one central point (_Orchestration_ vs. _Choreography_).

* return its results in a standardised format that can easily be integrated into ProCKSI/Database and thus resused be the ProCKSI/Server and all other experiments "on the command line".

h1. Standardising Results with XML

The principle API for the ProCKSI "stand-alone" applications can be visualised as follows:

!ProCKSI-core-API.png!

One file in XML format is fed into the ProCKSI/Comparison and ProCKSI/Consensus applications, describing the entire dataset, all tasks and the necessary input parameters. At the end, one output file in XML format is written, which might link to further external files in specific format (e.g. PDF, CM, ...) if necessary.

h2. Input Specifications

These are the specifications for the XML input file:

In principle, all possible results from the requested methods are returned. All unnecessary results can be requested to be excluded. A log file is generated if a file name is provided.

Optional tags: *exclude* (measure, result), *log*

Optional attributes: *description*

<pre>

<package id="ID" description="TEXT">

  <log filename="FILENAME" />

  <dataset type="structure|tree|contact map|similarity matrix">

    <item id="ID" label="TEXT" filename="FILENAME" />

    :::

    <item id="ID" label="TEXT" filename="FILENAME" />

  </dataset>  

  <experiment id="ID" name="NAME">

    <method id="ID" name="NAME">

      <parameters>

        <param name="TEXT">VALUE</param>

        :::

        <param name="TEXT">VALUE</param>

      </parameters>

      <exclude>

        <measure>NAME</measure>

        :::

        <measure>NAME</measure>

        <result>NAME</result>

        :::

        <result>NAME</result>

      </exclude>

    </method>

    :::

    <method>

      ...

    </method>

  </experiment>

  :::

  <experiment>

    ...

  </experiment>

</package>

</pre>

The data used as an input could be protein structures, similarity trees, contact maps or similarity matrices. All specified methods should be able to operate on given data files. This dependency could be verified automatically using XML Schema.

h2. Output Specifications

These are the specifications for the XML output file:

Optional tags: *log*, *message*, *similarity* (used only if output is a _comparison_) 

Optional attributes: *description*, *node*, *start*, *end*, *ref_id* (only if output type is _composition_), *ref_id2* (only if output type is not _comparison_)

<pre>

<package id="ID" description="TEXT" node="TEXT" start="TIME" end="TIME">

  <log filename="FILENAME" />

  <message type="error|warning|info">TEXT</message>

  :::

  <message type="error|warning|info">TEXT</message>

  <dataset type="structure|tree|contact map|similarity matrix">

    <item id="ID" label="TEXT" filename="FILENAME" />

    :::

    <item id="ID" label="TEXT" filename="FILENAME" />

  </dataset>  

  <experiment id="ID" name="NAME">

    <method id="ID" name="NAME">

      <parameters>

        <parameter name="TEXT">VALUE</parameter>

        :::

        <parameter name="TEXT">VALUE</parameter>

      </parameters>

      <results type="transformation|comparison|composition" ref_id="" ref_id2=" ">

        <message type="error|warning|info">TEXT</message>

        :::

        <message type="error|warning|info">TEXT</message>

        <similarity measure="NAME">VALUE</similarity>

        :::

        <similarity measure="NAME">VALUE</similarity>

        <file type="TEXT" label="TEXT" name="FILENAME" />

        :::

        <file type="TEXT" label="TEXT" name="FILENAME" />

      </results>

      :::

      <results>

        ...

      </results>

    </method>

    :::

    <method>

      ...

    </method>

  </experiment>

  :::

  <experiment>

    ...

  </experiment>

</package>

</pre>

Message being an error, warning or additional information could be passed on a global or a method level. Dataset and parameterset defined in the input file (package) could be repeated in the output (results) if needed (self-contained output). Output could be a 1->1 transformation (e.g. structure -> contact map), a 2->1 comparison (e.g. 2*structure -> similarity measure) or N->1 composition (e.g. N*tree -> total tree or N*similarity matrix -> consensus similarity matrix). The results other than similarity measures for a pair of proteins are stored in external files and are just referenced from the XML file.

The alignment data could be described in the XML file, as there is no single format used by all programs.