ProCKSI

= The ProCKSI "stand-alone" ''Core'' Application =

ProCKSI utilises a variety of similarity comparison methods (e.g. USM, MaxCMO, TMaling, ...) producing different similarity measures (e.g. Zscore, TMscore, 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- and post-processing methods, e.g. preparation of contact maps from structures, or clustering of similarity matrices, that have their own input parameters and produce different output.

The goal can be described as follows: [[br]]
Allow the ProCKSI "stand-alone" ''core'' application to
1. be developped independently from the ProCKSI ''framework'' (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.
2. 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.
3. 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'').
4. return its results in a standardised format that can easily be integrated into the ProCKSI database and thus resused be the ProCKSI framework and all other experiments "on the command line".



= Standardising Results with XML =

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

[[Image(ProCKSI-core-API.png)]]

One file in XML format is fed into the ProCKSI "stand-alone" ''core'' application, 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.

== Input Specifications ==
This is the latest proposal for the XML input file:

Optional tags: '''exclude''' (measure, result), '''log''' (no log is generated if not specified) [[BR]]
Optional attributes: '''description'''

{{{
<job id="ID" description="TEXT">
<log filename="FILENAME" />

<input type="structure|tree|contact map|similarity matrix">
<item id="ID" label="TEXT" filename="FILENAME" />
:::
<item id="ID" label="TEXT" filename="FILENAME" />
</input>

<method id="ID" name="TEXT">
<param name="TEXT">VALUE</param>
:::
<param name="TEXT">VALUE</param>

<exclude>
<measure>NAME</measure>
:::
<measure>NAME</measure>

<result>NAME</result>
:::
<result>NAME</result>
</exclude>
</method>
:::
<method ...>
...
</method>
</job>
}}}

The ''<job>'' might be renamed into ''<packages>>'', the ''<input>'' into ''<dataset>'', in order to be consistent with the [wiki:DataStorage Extended Database Design].

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.

== Output Specifications ==
This is the latest proposal for the XML output file:

Optional tags: '''log''', '''message''', '''similarity''' (used only if output is a ''comparison'') [[BR]]
Optional attributes: '''description''', '''node''', '''start''', '''end''', '''ref_id''' (only if output type is ''composition''), '''ref_id2''' (only if output type is not ''comparison'')

{{{
<job 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>

<input type="structure|tree|contact map|similarity matrix">
<item id="ID" label="TEXT" filename="FILENAME" />
:::
<item id="ID" label="TEXT" filename="FILENAME" />
</input>

<parameters>
<method id="ID" name="NAME">
<parameter name="TEXT">VALUE</parameter>
:::
<parameter name="TEXT">VALUE</parameter>
</method>
:::
<method ...>
...
</method>
</parameters>

<output type="transformation|comparison|composition" ref_id="" ref_id2=" ">
<method id="ID">
<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" />
<method>
</output>
:::
<output ...>
...
</output>
</job>
}}}

Message being an error, warning or additional information could be passed on a global or a method level. Input data and parameters defined in the input file could be repeated in the output 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. This yet to be decided.