annotation file format updated to take idColour and specify single colour groups...
authorjprocter <Jim Procter>
Fri, 18 Jul 2008 12:32:02 +0000 (12:32 +0000)
committerjprocter <Jim Procter>
Fri, 18 Jul 2008 12:32:02 +0000 (12:32 +0000)
help/html/features/annotationsFormat.html
src/jalview/io/AnnotationFile.java

index 5a289c9..b029e96 100755 (executable)
-<html>\r
-\r
-<head>\r
-<title>The Alignment Annotations File</title>\r
-</head>\r
-\r
-<body>\r
-<p><strong>The Alignment Annotations File</strong></p>\r
-<p>Alignment annotations can be imported onto an alignment since\r
-version 2.08 of Jalview, via an annotations file. It is a simple ASCII\r
-text file consisting of tab delimited records similar to the <a\r
-       href="featuresFormat.html">Sequence Features File</a>, and introduced\r
-primarily for use with the Jalview applet.</p>\r
-<p>Alignment annotations files are imported into Jalview in the\r
-following ways:<br>\r
-<ul>\r
-       <li>from the command line<strong><pre>\r
- -annotations &lt;<em>Annotations filename</em>&gt;</pre></strong></li>\r
-       <li>Dragging an annotations file onto an alignment window</li>\r
-       <li>Via the &quot;Load Features / Annotations&quot; entry in the <strong>File</strong>\r
-       menu of an alignment window.</li>\r
-</ul>\r
-</p>\r
-<p><strong>Annotations File Format</strong></p>\r
-<p>The File consists of lines containing an instruction followed by\r
-tab delimited fields, and any lines starting with &quot;#&quot; are\r
-ignored. The first non-commented out line of a valid Annotations file\r
-must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>\r
-<p>A row of annotation is added with a line like <strong><pre><em>GRAPH_TYPE</em>&#9;<em>Label</em>&#9;<em>Values</em></pre></strong></p>\r
-<p>The <em>GRAPH_TYPE</em> field, which appears first, defines the\r
-appearance of the annotation row when rendered by Jalview. The next field is the row label for the annotation. The final <em>Values</em> field contains a series of &quot;|&quot;\r
-separated value fields. Each value field is itself a comma separated list of fields of a particular type defined by the annotation row's\r
-GRAPH_TYPE. The allowed values of GRAPH_TYPE and the format of their respective value fields (with the trailing &quot;<strong>|</strong>&quot; symbol) are shown below:<ul>\r
-       <li>BAR_GRAPH<br>\r
-       Plots a histogram with labels below each bar.<br>\r
-       <em>number</em>,<em>text character</em></li>\r
-       <li>LINE_GRAPH<br>\r
-       Draws a line between values on the annotation row.<br>\r
-       <em>number</em></li>\r
-       <li>NO_GRAPH<br>\r
-       For a row consisting of text labels and/or secondary structure symbols.<br>\r
-       <em>{Secondary Structure Symbol}</em>,<em>text label</em><br>\r
-       Currently supported secondary structure structure symbols are <em>H</em> (for   helix) and <em>E</em> (for strand)</li>\r
-</ul>\r
-Any or all value fields may be left empty, as well as the BAR_GRAPH's\r
-text character field, and either or both of the text-label and secondary\r
-structure symbol fields of the NO_GRAPH type annotation rows.\r
-</p>\r
-<p>You can associate an annotation with a sequence by preceding its\r
-definition with the line: \r
-<pre>SEQUENCE_REF&#9;<em>seq_name</em>&#9;<em>[startIndex]</em></pre>\r
-All Annotations defined after a SEQUENCE_REF command will then be\r
-associated with that sequence, and the first field in the Value field\r
-list will (optionally) be placed at the <em>startIndex</em>'th column.</p>\r
-<p>Sequence associations are turned off for subsequent annotation\r
-definitions by: \r
-<pre>SEQUENCE_REF&#9;ALIGNMENT</pre>\r
-</p>\r
-<p><em>LINE_GRAPH</em> type annotations can be given a colour\r
-(specified as 24 bit RGB triplet in hexadecimal or comma separated\r
-values), combined onto the same vertical axis, and have ordinate lines\r
-(horizontal lines at a particular vertical axis value) using the\r
-following commands (respectively): \r
-<pre>COLOUR&#9;<em>graph_name</em>&#9;<em>colour</em>\r
-COMBINE&#9;<em>graph_1_name</em>&#9;<em>graph_2_name</em>\r
-GRAPHLINE&#9;<em>graph_name</em>&#9;<em>value</em>&#9;<em>label</em>&#9;<em>colour</em><strong><em>\r
-</em></strong></pre>\r
-<h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.2.1) SEQUENCE_GROUP</font></h3>\r
-<p>Groups of sequences can be defined using the tab delimited line</p>\r
-<pre>SEQUENCE_GROUP    Group_Name      Group_Start     Group_End       Sequences</pre>\r
-<p>The sequences can be defined by alignment index and a range of sequences can \r
-  be defined in a comma delimited field such as</p>\r
-<p>2-5,8-15,20,22</p>\r
-<p>Enter * to select all groups. </p>\r
-<p>If the alignment indices are not known, enter -1 then a tab delimited list \r
-  of sequence ids. </p>\r
-<p>If the SEQUENCE_REF has been defined, the group_start and group_end will be \r
-  relative to the sequence residue numbering, otherwise the group_start and group_end \r
-  will be the alignment column indices. </p>\r
-<p>The group can (optionally) be assigned various visualisation properties via \r
-  another tab delimited line thus:</p>\r
-<pre>PROPERTIES        Group_name      tab_delimited_key_value_pairs\r
-</pre>\r
-<p>The key_value_pairs allow you to define a description and to colour the group \r
-  in various ways. All, none or some of the following values could be used for \r
-  a group:</p>\r
-<p>description=Text <br>\r
-  colour=Helix Propensity<br>\r
-  pidThreshold=0<br>\r
-  consThreshold=0<br>\r
-  outlineColour=red <br>\r
-  displayBoxes=true<br>\r
-  displayText=false<br>\r
-  colourText=false<br>\r
-  textCol1=black<br>\r
-  textCol2=black<br>\r
-  textColThreshold=0</p>\r
-<p> </p>\r
-<p>An example Annotation file is given below:\r
-<pre>#Comment lines follow the hash symbol\r
-JALVIEW_ANNOTATION\r
-SEQUENCE_REF&#9;FER1_MESCR&#9;5\r
-BAR_GRAPH&#9;Bar Graph 1&#9;||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+\r
-LINE_GRAPH&#9;Green Values&#9;1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2\r
-LINE_GRAPH&#9;Red Values&#9;2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2\r
-BAR_GRAPH&#9;Bar Graph&#9;2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4\r
-NO_GRAPH&#9;Icons &#9;||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||\r
-NO_GRAPH&#9;Purple Letters&#9;m|y|p|r|o|t|e|i|n\r
-COLOUR&#9;Bar Graph 2&#9;blue\r
-COLOUR&#9;Red Values&#9;255,0,0\r
-COLOUR&#9;Green Values&#9;green\r
-COLOUR&#9;Purple Letters&#9;151,52,228\r
-COMBINE&#9;Green Values&#9;Red Values\r
-GRAPHLINE&#9;Red Values&#9;2.6&#9;threshold&#9;black\r
-\r
-SEQUENCE_GROUP Group_A 30 50 *\r
-SEQUENCE_GROUP Group_B 1 351 2-5\r
-SEQUENCE_GROUP Group_C 12 14 -1 seq1   seq2    seq3\r
-PROPERTIES Group_A description=This is the description colour=Helix Propensity pidThreshold=0 outlineColour=red displayBoxes=true displayText=false    colourText=false textCol1=black textCol2=black textColThreshold=0\r
-PROPERTIES Group_B outlineColour=red\r
-PROPERTIES Group_C colour=Clustal\r
-</pre>\r
-</p>\r
-</body>\r
-</html>\r
+<html>
+
+<head>
+<title>The Alignment Annotations File</title>
+</head>
+
+<body>
+<p><strong>The Alignment Annotations File</strong></p>
+<p>Alignment annotations can be imported onto an alignment since
+version 2.08 of Jalview, via an annotations file. It is a simple ASCII
+text file consisting of tab delimited records similar to the <a
+       href="featuresFormat.html">Sequence Features File</a>, and introduced
+primarily for use with the Jalview applet.</p>
+<p>Alignment annotations files are imported into Jalview in the
+following ways:<br>
+<ul>
+       <li>from the command line<strong><pre>
+ -annotations &lt;<em>Annotations filename</em>&gt;</pre></strong></li>
+       <li>Dragging an annotations file onto an alignment window</li>
+       <li>Via the &quot;Load Features / Annotations&quot; entry in the <strong>File</strong>
+       menu of an alignment window.</li>
+</ul>
+</p>
+<p><strong>Annotations File Format</strong></p>
+<p>The File consists of lines containing an instruction followed by
+tab delimited fields, and any lines starting with &quot;#&quot; are
+ignored. The first non-commented out line of a valid Annotations file
+must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>
+<p>A row of annotation is added with a line like <strong><pre><em>GRAPH_TYPE</em>&#9;<em>Label</em>&#9;<em>Values</em></pre></strong></p>
+<p>The <em>GRAPH_TYPE</em> field, which appears first, defines the
+appearance of the annotation row when rendered by Jalview. The next field is the row label for the annotation. The final <em>Values</em> field contains a series of &quot;|&quot;
+separated value fields. Each value field is itself a comma separated list of fields of a particular type defined by the annotation row's
+GRAPH_TYPE. The allowed values of GRAPH_TYPE and the format of their respective value fields (with the trailing &quot;<strong>|</strong>&quot; symbol) are shown below:<ul>
+       <li>BAR_GRAPH<br>
+       Plots a histogram with labels below each bar.<br>
+       <em>number</em>,<em>text character</em></li>
+       <li>LINE_GRAPH<br>
+       Draws a line between values on the annotation row.<br>
+       <em>number</em></li>
+       <li>NO_GRAPH<br>
+       For a row consisting of text labels and/or secondary structure symbols.<br>
+       <em>{Secondary Structure Symbol}</em>,<em>text label</em><br>
+       Currently supported secondary structure structure symbols are <em>H</em> (for   helix) and <em>E</em> (for strand)</li>
+</ul>
+Any or all value fields may be left empty, as well as the BAR_GRAPH's
+text character field, and either or both of the text-label and secondary
+structure symbol fields of the NO_GRAPH type annotation rows.
+</p>
+<p>You can associate an annotation with a sequence by preceding its
+definition with the line: 
+<pre>SEQUENCE_REF&#9;<em>seq_name</em>&#9;<em>[startIndex]</em></pre>
+All Annotations defined after a SEQUENCE_REF command will then be
+associated with that sequence, and the first field in the Value field
+list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
+<p>Sequence associations are turned off for subsequent annotation
+definitions by: 
+<pre>SEQUENCE_REF&#9;ALIGNMENT</pre>
+</p>
+<p><em>LINE_GRAPH</em> type annotations can be given a colour
+(specified as 24 bit RGB triplet in hexadecimal or comma separated
+values), combined onto the same vertical axis, and have ordinate lines
+(horizontal lines at a particular vertical axis value) using the
+following commands (respectively): 
+<pre>COLOUR&#9;<em>graph_name</em>&#9;<em>colour</em>
+COMBINE&#9;<em>graph_1_name</em>&#9;<em>graph_2_name</em>
+GRAPHLINE&#9;<em>graph_name</em>&#9;<em>value</em>&#9;<em>label</em>&#9;<em>colour</em><strong><em>
+</em></strong></pre>
+<h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.2.1) SEQUENCE_GROUP</font></h3>
+<p>Groups of sequences can be defined using the tab delimited line</p>
+<pre>SEQUENCE_GROUP    Group_Name      Group_Start     Group_End       Sequences</pre>
+<p>The sequences can be defined by alignment index and a range of sequences can 
+  be defined in a comma delimited field such as</p>
+<p>2-5,8-15,20,22</p>
+<p>Enter * to select all groups. </p>
+<p>If the alignment indices are not known, enter -1 then a tab delimited list 
+  of sequence ids. </p>
+<p>If the SEQUENCE_REF has been defined, the group_start and group_end will be 
+  relative to the sequence residue numbering, otherwise the group_start and group_end 
+  will be the alignment column indices. </p>
+<p>The group can (optionally) be assigned various visualisation properties via 
+  another tab delimited line thus:</p>
+<pre>PROPERTIES        Group_name      tab_delimited_key_value_pairs
+</pre>
+<p>The key_value_pairs allow you to define a description and to colour the group 
+  in various ways. All, none or some of the following values could be used for 
+  a group:</p>
+<p>description=Text <br>
+  colour=Helix Propensity<br>
+  pidThreshold=0<br>
+  consThreshold=0<br>
+  outlineColour=red <br>
+  displayBoxes=true<br>
+  displayText=false<br>
+  colourText=false<br>
+  textCol1=black<br>
+  textCol2=black<br>
+  textColThreshold=0<br>
+  idColour=ff3322</p>
+<em>New Features in 2.4:</em><ul><li>if the <strong>idColour</strong> property
+is given without specifying a colour scheme with the <strong>colour</strong>
+property, then the idColour will also be used to colour the sequence.</li>
+<li>the <strong>colour</strong> property can take either a colour scheme name,
+ or a single colour specification (either a colour name like 'red' or an RGB
+ triplet like 'ff0066'). If a single colour is specified, then the group
+ will be coloured with that colour.</li>
+</ul>
+<p> </p>
+<p>An example Annotation file is given below:
+<pre>#Comment lines follow the hash symbol
+JALVIEW_ANNOTATION
+SEQUENCE_REF&#9;FER1_MESCR&#9;5
+BAR_GRAPH&#9;Bar Graph 1&#9;||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
+LINE_GRAPH&#9;Green Values&#9;1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2
+LINE_GRAPH&#9;Red Values&#9;2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2
+BAR_GRAPH&#9;Bar Graph&#9;2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4
+NO_GRAPH&#9;Icons &#9;||||E,Sheet1|E|E||||H,Sheet 2|H|H|H||||||
+NO_GRAPH&#9;Purple Letters&#9;m|y|p|r|o|t|e|i|n
+COLOUR&#9;Bar Graph 2&#9;blue
+COLOUR&#9;Red Values&#9;255,0,0
+COLOUR&#9;Green Values&#9;green
+COLOUR&#9;Purple Letters&#9;151,52,228
+COMBINE&#9;Green Values&#9;Red Values
+GRAPHLINE&#9;Red Values&#9;2.6&#9;threshold&#9;black
+
+SEQUENCE_GROUP Group_A 30 50 *
+SEQUENCE_GROUP Group_B 1 351 2-5
+SEQUENCE_GROUP Group_C 12 14 -1 seq1   seq2    seq3
+PROPERTIES Group_A description=This is the description colour=Helix Propensity pidThreshold=0 outlineColour=red displayBoxes=true displayText=false    colourText=false textCol1=black textCol2=black textColThreshold=0
+PROPERTIES Group_B outlineColour=red
+PROPERTIES Group_C colour=Clustal
+</pre>
+</p>
+</body>
+</html>
index 6285cf1..d5039de 100755 (executable)
@@ -312,6 +312,10 @@ public class AnnotationFile
       {\r
         text.append("textColThreshold=" + sg.thresholdTextColour);\r
       }\r
+      if (sg.idColour!=null)\r
+      {\r
+        text.append("idColour="+jalview.util.Format.getHexString(sg.idColour)+"\t");\r
+      }\r
 \r
       text.append("\n\n");\r
 \r
@@ -816,6 +820,8 @@ public class AnnotationFile
     if (sg != null)\r
     {\r
       String keyValue, key, value;\r
+      ColourSchemeI def = sg.cs;\r
+      sg.cs = null;\r
       while (st.hasMoreTokens())\r
       {\r
         keyValue = st.nextToken();\r
@@ -878,9 +884,16 @@ public class AnnotationFile
         {\r
           sg.thresholdTextColour = Integer.parseInt(value);\r
         }\r
-\r
+        else if (key.equalsIgnoreCase("idColour"))\r
+        {\r
+          sg.setIdColour((def = new UserColourScheme(value)).findColour('A'));\r
+        }\r
         sg.recalcConservation();\r
       }\r
+      if (sg.cs==null)\r
+      {\r
+        sg.cs = def;\r
+      }\r
     }\r
   }\r
 \r