QUASAR Tutorial - How to extend Quasar

Since almost everyone uses a different alignment format it might be important to extend Quasar with new alignment parsers. To add a new alignment parser to the system you have to implement a class that extends the abstract class quasar.parser.QuasarParser. The purpose of every class that extends the QuasarParser class is to translate an alignment file into the internal alignment representation of Quasar which consists of Alignments and AminoAcids. To find out more about the details of the implementation please read the Java documentation of Quasar.

The graphical user interface of Quasar again uses a XML-like configuration file that provides the meta information to represent a parser class (and all other Quasar entities like scoring schemes...) within the graphical user interface. The configuration file can be found in the quasar/gui/config directory and is called guiConfig.xml. To add a new alignment parser, you have to add an XML-configuration tag that looks like this (example from the configuration file, definition of Parser1):

  <alignmentParser>
        <name>Parser 1</name>
        <parserClass>quasar.parser.AlignmentParserFormatOne</parserClass>
        <informationDimension>1D 2D</informationDimension>
        <description>
                <p>Provided (required) information: <b>1D and 2D</b><br>
                Required file format:</p>
                <pre>
                 > templatePDBFileName<br>
                 QA QUER-Y---ALIGNMENT<br>
                 TA T-EMPLATEALIGNMENT<br>
 
                 QS HHHH-H---SSSSSSSSS<br>
                 TS C-HHHHHCCSSSSSSSSS<br><br>
 
                 > nextAlignment<br>
                </pre>
        </description>
  </alignmentParser>
 

• alignmentParser: embedding tag, indicating that the definition within defines an alignment parser
• name: trivial name of the parser that will be shown in the drop down list of the graphical user interface
• parserClass: java package and class name where to find the parser
• informationDimension: Within this tag you can define which information is provided when alignments are parsed with this parser. To indicate that for example 1D and 2D information is available please write 1D 2D (seperated by a space charakter, 3D is also a valid dimension).
• description: description of the parser, should contain the provided dimension parsed by the parser as well as short description of the alignment format. The description may contain HTML tags to make it easier to format the description.

DEPRECATED: Please notice, that in the current Quasar version, there is a much simpler way to add a matrix using the FileMatrixScoringScheme class. Examples of such files can be found in the matrices/ directory of the official Quasar distribution. An example can also be found here. Nevertheless, the way described below does still work.

Scoring matrices can be defined to be used in for example the MatrixScoringScheme of the Quasar system. To be usable in such a scoring scheme you have to wrap your matrix in a Java class that extends the abstract class quasar.scoring.matrices.ScoringMatrix. For details about this please see the Java documentation of Quasar.

Again, you have to define the meta information for the scoring matrix in the configuration file of the graphical user interface. To add your scoring matrix please add the following tag structure to the configuration file (example shows the configuration of the PAM250 matrix), of course with your own content.

  <scoringMatrix>
       <name>PAM 250</name>
       <matrixClass>quasar.scoring.matrices.PAM250Matrix</matrixClass>
       <requiredDimension>1D</requiredDimension>
       <description>Log odds PAM 250 scoring matrix as described by Dayhoff et al., 1978</description>
  </scoringMatrix>
 

• scoringMatrix: embedding tag, indicating that the definition within defines a scoring matrix
• name: trivial name of the scoring matrix, shown within the graphical user interface
• matrixClass: java package and class name where to find the scoring matrix
• requriredDimension: This tag is used to tell the graphical user interface which protein information dimension is required for the matrix to run properly. Possible are 1D, 2D and 3D seperated by a space charakter.
• description: description of the scoring matrix, may contain HTML tags.

The purpose of scoring schemes is to take an alignment that provides the information required by the scoring scheme (for example the secondary structure assignment = 2D), to calculate the score defined by this scoring scheme (for example a Q3 score) for the alignment and to return the calculated value to the score conductor that used this scoring scheme. Of course it is possible here that a scoring scheme is just a simple wrapper class around a for example C - program. To implement a new scoring scheme all you have to do is to implement the Java interface quasar.scoring.schemes.ScoringScheme. For details of this interface please see the Java documentation of Quasar.

Different to scoring matrices and alignment parsers, scoring schemes can have their own configuration files that provide additional user information for the scoring scheme at Quasar runtime. For example the MatrixScoringScheme requires a xml like configuration information that provides the matrix class that should be used as well as the open and extend gap penalties. Therefore the meta information representation for the graphical user interface does not only have to contain the information about where to find the scoring scheme, ... but it also has to know what information is required by the scoring scheme to configure the scoring scheme. First of all we show you the general skeleton how to add a scoring scheme to the GUI before we tell you how you can add additional information about the specific scoring scheme configuration to the meta information.

The general configuration information scheme that is equal for every scoring scheme looks like this (by the example of the Q3 scoring scheme):

  <scoringScheme>
        <name>Q3 measurement</name>
        <schemeClass>quasar.scoring.schemes.Q3ScoringScheme</schemeClass>
        <requiredDimension>2D</requiredDimension>
        <description>
               Scores the secondary structure match between target and template due to the  Q3 measurement, that is the percentage of correctly predicted secondary structure assignments. <b>Requires 2D information</b>!
        </description>
        <config></config>
  </scoringScheme>
 

• scoringScheme: embedding tag, indicating that the definition within defines a scoring scheme
• name: trivial name of the scoring scheme, shown within the graphical user interface
• schemeClass: java package and class name where to find the scoring scheme
• requriredDimension: This tag is used to tell the graphical user interface which protein information dimension is required for the scoring scheme to run properly. Possible are 1D, 2D and 3D seperated by a space charakter.
• description: description of the scoring scheme, may contain HTML tags.
• config: Different to the definitions we have seen so far, the scoring scheme meta information contains an additional tag called config. Within this tag you may define additional information that is required to configure the scoring scheme (see below). In the case of the Q3 scoring scheme no additional configuration is required, that's why the config tag is simply empty.

How to define additional configuration information of a scoring scheme

Within the config tag you may define the meta information of a tag. This tag is later translated into a xml representation and used by the scoring scheme to configure itself. The structure of a tag looks as follows (example: definition of an extend gap attribute):



  <tag>
     <tagName>extendGap</tagName>
     <tagMultiplicity>1</tagMultiplicity>
     <tagContent>Double</tagContent>
     <tagDescription>
          Extend gap penalty used to score the alignment, you have to use negative values to penalize gaps
     </tagDescription>
     <tagAttributes></tagAttributes>
  </tag>
 

• tag: embedding tag, inidicating that within the open and close tag a new configuration tag is defined
• tagName: scoring scheme configuration file name of the tag (what will be the name of the configuration tag in the xml file)
• tagMultiplicity: defines if the tag is has to occur exactly once in the configuration file for the scoring scheme (value: 1) or if the tag may occur multiple times (but at least once, value: n).
• tagContent: this one tells the graphical user interface what value is expected as a valid value for the tag. For scoring scheme tags this may be one of the following key words: Double (double number), Integer (integer number), Boolean (boolean value), String (string value) and scoringMatrix (scoring matrix class).
• tagDescription: short description of the tag (shown as tooltip for the input component of the tag), HTML is not accepted here.
• tagAttributes: for scoring schemes: the information within this tag is ignored!

Example: Meta information and configuration file for the MatrixScoringScheme

To finish this part we want to give a final example showing the configuration file read by the MatrixScoringScheme and the corresponding information provided in the graphical user interface meta information file. The configuration file required to configure a MatrixScoringScheme instance looks like this:

  <matrix>quasar.scoring.matrices.PAM250Matrix</matrix>
  <openGap>-12</openGap>
  <extendGap>-3</extendGap>
 

The corresponding information of the scoring scheme meta information should look like this:

  </scoringScheme>
  ...
      <config>
          <tag>
               <tagName>matrix</tagName>
               <tagMultiplicity>1</tagMultiplicity>
               <tagContent>scoringMatrix</tagContent>
               <tagDescription>
                    Specify a quasar matrix that will be used for scoring
               </tagDescription>
               <tagAttributes></tagAttributes>
          </tag>
          <tag>
               <tagName>openGap</tagName>
               <tagMultiplicity>1</tagMultiplicity>
               <tagContent>Double</tagContent>
               <tagDescription>
                    Open gap penalty used to score the alignment,
                    you have to use negative values to penalize gaps
               </tagDescription>
               <tagAttributes></tagAttributes>
          </tag>
          <tag>
               <tagName>extendGap</tagName>
               <tagMultiplicity>1</tagMultiplicity>
               <tagContent>Double</tagContent>
               <tagDescription>
                    Extend gap penalty used to score the alignment, 
                    you have to use negative values to penalize gaps
               </tagDescription>
               <tagAttributes></tagAttributes>
          </tag>
      </config>
  </scoringScheme>
 

In the graphical user interface, the configuration dialog for the scoring scheme will look something like this (plus the additional information required by the score conductor, not shown here):

We hope that you are able now to implement your own scoring schemes now as well as to add your own scoring schemes to the graphical user interface afterwards. If you have any problems feel free to contact us.

The purpose of a benchmark score is to provide a more or less objective quality measurement like a RMSD, a contact matrix similarity score... for an alignment if the structure of template and query is known what should be the case in a benchmark situation. To act as a benchmark score your class has to extend the abstract class BenchmarkScore in the package quasar.benchmark.scores. For details about the required methods and their purpose, please read the Java documentation of Quasar.

To keep things easy, defining benchmark scores in the graphical user interface configuration file is pretty much equivalent to defining Scoring schemes as described above. Only the tag names are a little bit different. Here is the configuration information of the APDB benchmark score:

  <benchmarkScore>
        <name>APDB score</name>
        <scoreClass>quasar.benchmark.scores.APDBScore</scoreClass>
        <requiredDimension>2D</requiredDimension>
 
        <description>
                This score implements the APDB score as described by O'Sullivan
                et al. in Bioinformatics 19 Suppl. 1, 2003, pages i215 - i221
                and is basically a comparison of the two structural environments
                of the aligned residues in template and query.
        </description>
        <config></config>
  </benchmarkScore>
 

The purpose of score conductors is, that they connect one or more scoring schemes to a formula (like a weighted sum...) that is uses to score a number of alignments and to calculate the quality scores for the alignments. To implement a score conductor your class has to implement the interface quasar.scoring.conductors.ScoreConductor. For details about the required methods and their purpose, please read the Java documentation of Quasar.

Again, to make a score conductor available for selection in the graphical user interface you have to add the meta information of the score conductor to the gui configuration file. Score conductors are maybe the most complicated entities to be added to the graphical user interface, but most of the concepts used here were already introduced above. The general structure of the score conductor meta information looks almost the same as the information of a scoring scheme (example: WeightedSumConductor):

  <scoreConductor>
       <name>Weighted sum conductor</name>
       <conductorClass>quasar.scoring.conductors.WeightedSumConductor</conductorClass>   
       <requiredDimension></requiredDimension>
       <description>
            This conductor uses a weighted sum of scoring schemes...</ul>
       </description>
       <config>...</config>
  </scoreConductor>
 

• scoreConductor: embedding tag, indicating that the definition within defines a score conductor
• name: trivial name of the score conductor, shown within the graphical user interface
• conductorClass: java package and class name where to find the score conductor
• requriredDimension: This tag is used to tell the graphical user interface which protein information dimension is required for the scoring scheme to run properly. Possible are 1D, 2D and 3D seperated by a space charakter, or just an empty tag (for example if no dimension is required or if the dimension is unknown, which is here the case since any scoring scheme can be added to the conductor).
• description: description of the score conductor, may contain HTML tags.
• config: Again score conductor meta information contains an additional tag called config. See below for details to this tag.

Score conductor ... tag

In the config tag of the score conductor you may define the same tags as described above for the scoring scheme configuration tags (see above). Additionally there is one special tag content with the type scoringScheme. This type defines that the user is allowed to add a scoring scheme to the score conductor. The scoringScheme content type tag should look something like this:



  <tag>
    <tagName>scoringScheme</tagName>
    <tagContent><i><u>scoringScheme</u></i></tagContent>
    <tagMultiplicity>n<tagMultiplicity>
    <tagDescription>Represents scoring scheme...</tagDescription>
    <tagAttributes>
      <tag>
          <tagName>schemeClass</tagName> <tagContent><u><i>scoringScheme{class}</i></u></tagContent>
          <tagMultiplicity>1</tagMultiplicity>
          <tagDescription>...</tagDescription>
          <tagAttributes></tagAttributes>
      </tag>
      <tag>
          <tagName>weight</tagName>
          <tagContent>Double</tagContent>
          <tagMultiplicity>1</tagMultiplicity>
          <tagDescription>...</tagDescription>
          <tagAttributes></tagAttributes>
      </tag>
      <tag>
          <tagName>normalized</tagName>
          <tagContent>boolean</tagContent>
          <tagMultiplicity>1</tagMultiplicity>
          <tagDescription>...</tagDescription>
          <tagAttributes></tagAttributes>
      </tag>
      <tag>
          <tagName>config</tagName>             
          <tagContent><u><i>scoringScheme{config}</i></u></tagContent>
          <tagMultiplicity>1</tagMultiplicity>
          <tagDescription>...</tagDescription>
          <tagAttributes></tagAttributes>
      </tag>
    </tagAttributes>
  </tag>
 

As you can see, the tag has the type scoringScheme and has the same stucture as all the tags we've used so far. With one difference! In the tagAttributes tag you are now allowed to define additional information about the configuration dialog of the scoring scheme. This dialog has to contain two tags which are: scoringScheme{class} to allow the user with this tag to select a scoring scheme class and scoringScheme{config} that tells the input dialog to add the scoring scheme specific configuration information (defined in the config tag of the scoring scheme) here. Additionally to the scoring scheme class ... the scoringScheme tag may contain additional configuration information that has to be provided for every added scoring scheme (like the weight in this case).
If you define a score conductor exactly like this in the meta information this will translate in a graphical user interface that looks something like this:



Since the config tag we defined above contains exactly one tag with the content scoringScheme and additionally this tag has a multiplicity of n this translates into a list where one can add scoring schemes. If the user clicks on the Add button we get the following picture:



As you can see the scoringScheme{class} tag content translates into a drop down list where the user can select scoring schemes, a description of the currently selected scoring scheme is shown below. The tags weight and normalized translate into normal tags just like described in the scoringScheme configuration above. Since the SOVScoringScheme does not need any additional configuration information the tag scoringScheme{config} is not used, but it will be used as soon as the user selects a scoringScheme that requires additional configuration.

Finally the graphical user interface has only one main purpose: to allow any user to define its own configuration file. So here is the product, a valid Quasar configuration file:

  <parser>
        <parserClass>quasar.parser.AlignmentParserFormatOne</parserClass>
        <alignmentFile>globin.align</alignmentFile>
        <pdbFiles>pdb</pdbFiles>
        <pdbFilesExtension>pdb</pdbFilesExtension>
        <parse3DInformation>false</parse3DInformation>
  </parser>
  <scoreConductor>
      <conductorClass>quasar.scoring.conductors.WeightedSumConductor</conductorClass>   
      <conductorConfig>
          <scoringScheme>
              <schemeClass>quasar.scoring.schemes.SOVScoringScheme</schemeClass>
              <weight>1</weight>
              <normalized>false</normalized>
              <config></config>
          </scoringScheme>
          <scoringScheme>
              <schemeClass>quasar.scoring.schemes.MatrixScoringScheme</schemeClass>
              <weight>1</weight>
              <normalized>true</normalized>
              <config>
                  <matrix>quasar.scoring.matrices.PAM250Matrix</matrix>
                  <openGap>-12</openGap>
                  <extendGap>-3</extendGap>
              </config>
          </scoringScheme>
          <scoringScheme>
              <schemeClass>quasar.scoring.schemes.MatrixScoringScheme</schemeClass>     
              <weight>1</weight>
              <normalized>true</normalized>
              <config>
                  <matrix>quasar.scoring.matrices.SecondaryStructureMatrix</matrix>
                  <openGap>0</openGap>
                  <extendGap>0</extendGap>
              </config>
          </scoringScheme>
      </conductorConfig>
  </scoreConductor>