JAL-2843 help text for colour by attribute, feature filters

diff --git a/help/html/features/featuresFormat.html b/help/html/features/featuresFormat.html
index fd6b99f..171a3d0 100755 (executable)
--- a/help/html/features/featuresFormat.html
+++ b/help/html/features/featuresFormat.html
@@ -60,7 +60,10 @@
     contains tab separated text fields. <strong>No comments are
       allowed</strong>.
   </p>
-  <p>The first set of lines contain type definitions:
+  <p>
+    <strong>Feature Colours</strong>
+  </p>
+  <p>The first set of lines contain feature type definitions and their colours:
   <pre>
 <strong><em>Feature label</em>&#9;<em>Feature Colour</em>
 <!-- &#9;<em>Feature links</em>  --></strong>
@@ -72,21 +75,37 @@
   <ul>
     <li>A single colour specified as either a red,green,blue 24 bit
       triplet in hexadecimal (eg. 00ff00) or as comma separated numbers
-      (ranging from 0 to 255))</li>
+      (ranging from 0 to 255))<br>
+      (For help with colour values, see <a href="https://www.w3schools.com/colors/colors_converter.asp">https://www.w3schools.com/colors/colors_converter.asp</a>.)</li>
 
     <li>A <a href="featureschemes.html">graduated colourscheme</a>
       specified as a "|" separated list of fields: <pre>
-[label|]&lt;mincolor&gt;|&lt;maxcolor&gt;|[absolute|]&lt;minvalue&gt;|&lt;maxvalue&gt;[|&lt;thresholdtype&gt;|[&lt;threshold value&gt;]]
+[label <em>or</em> score<em> or</em> attribute|attName|]&lt;mincolor&gt;|&lt;maxcolor&gt;|[absolute|]&lt;minvalue&gt;|&lt;maxvalue&gt;[|&lt;novalue&gt;][|&lt;thresholdtype&gt;|[&lt;threshold value&gt;]]
 </pre> The fields are as follows:
 
       <ul>
-        <li><em>label</em><br> Indicate that the feature
+        <li><em>label</em><br> Indicates that the feature
           description should be used to create a colour for features of
           this type.<br> <em>Note: if no threshold value is
-            needed then the final '|' may be omitted.<br> This
+            needed then only 'label' is required.<br> This
             keyword was added in Jalview 2.6
         </em></li>
 
+        <li><em>score</em><br> Indicates that the feature
+          score should be used to create a graduated colour for features of
+          this type, in conjunction with mincolor, maxcolor.<br><em>This keyword was added in Jalview 2.11.
+          It may be omitted (score is the default) if mincolor and maxcolor are specified.
+        </em></li>
+
+        <li><em>attribute|attName</em><br> Indicates that the value of feature
+          attribute 'attName' should be used to create a colour for features of
+          this type.
+          <br>For example, <em>attribute|clinical_significance</em> to colour by clinical_significance.
+          <br>To colour by range of a numeric attribute, include <em>mincolor</em> and <em>maxcolor</em>, or omit to colour by text (category).
+          <br>(Note: the value of the attribute used for colouring will also be shown in the tooltip as you mouse over features.)
+          <br>A sub-attribute should be written as, for example, CSQ:IMPACT.
+          <br><em>This keyword was added in Jalview 2.11</em></li>
+
         <li><em>mincolor</em> and <em>maxcolor</em><br> Colour
           triplets specified as hexadecimal or comma separated values
           (may be left blank for a <em>label</em> style colourscheme,
@@ -99,10 +118,15 @@
 
         <li><em>minvalue</em> and <em>maxvalue</em><br>
           Minimum and maximum values defining the range of scores for
-          which the colour range will be defined over. If minvalue is
+          which the colour range will be defined over.<br>If minvalue is
           greater than maxvalue then the linear mapping will have
           negative gradient.</li>
 
+        <li><em>novalue</em> <br>
+          Specifies the colour to use if colouring by attribute, when the attribute is absent.
+          Valid options are <em>novaluemin, novaluemax, novaluenone</em>, to use mincolor, maxcolor, or no colour.
+          <br>If not specified this will default to novaluemin.</li>
+
         <li><em>thresholdtype</em><br> Either
           &quot;none&quot;, &quot;below&quot;, or &quot;above&quot;. <em>below</em>
           and <em>above</em> require an additional <em>threshold
@@ -113,12 +137,45 @@
   </ul>
   </p>
 
+  <p>
+    <strong>Feature Filters</strong>
+  </p>
+  <p>This section is optional, and allows one or more filters to be defined for each feature type.
+     <br>Only features that satisfy the filter conditions will be displayed.
+     <br>Begin with a line which is just STARTFILTERS, and end with a line which is just ENDFILTERS.
+     <br>Each line has the format:
+     <pre>featureType <em>&lt;tab&gt;</em> (filtercondition1) [and|or] (filtercondition2) [and|or]...<br></pre>
+     The parentheses are not needed if there is only one condition. 
+     Combine multiple conditions with either <em>and</em> or <em>or</em> (but not a mixture).
+     <br>Each condition is written as:
+     <pre>Label|Score|AttributeName condition [value]</pre>
+     where <em>condition</em> is not case sensitive, and should be one of
+     <ul>
+     <li><em>Contains</em> - value should contain the given text (not case sensitive); example <em>clinical_significance contains Pathogenic</em></li> 
+     <li><em>NotContains</em> - value should not contain the given text</li> 
+     <li><em>Matches</em> - value should match the given text (not case sensitive)</li> 
+     <li><em>NotMatches</em> - value should not match the given text (not case sensitive)</li> 
+     <li><em>Present</em> - specified attribute is present on the feature (no value required); example <em>CSQ:SIFT present</em></li> 
+     <li><em>NotPresent</em> - specified attribute is not present on the feature (no value required)</li> 
+     <li><em>EQ</em> - feature score, or specified attribute, is equal to the (numeric) value</li> 
+     <li><em>NE, LT, LE, GT, GE</em> - tests for not equal to / less than / less than or equal to / greater than / greater than or equal to the value</li> 
+     </ul>
+     A non-numeric value always fails a numeric test.<br>If either attribute name, or value to compare, contains spaces, then enclose in single quotes:
+     <em>'mutagenesis site' contains 'decreased affinity'</em>
+     <br>Tip: to see examples of valid syntax, first configure colours and filters in Jalview, then <em>File | Export Features</em> to Textbox in Jalview Format.
+     <br><em>Feature filters were added in Jalview 2.11</em>
+  </p>
+
+  <p>
+    <strong>Feature Instances</strong>
+  </p>
+
   <p>The remaining lines in the file are the sequence annotation
     definitions, where the now defined features are attached to regions
     on particular sequences. Each feature can optionally include some
     descriptive text which is displayed in a tooltip when the mouse is
-    near the feature on that sequence (and can also be used to generate
-    a colour the feature).</p>
+    near the feature on that sequence (and may also be used to generate
+    a colour for the feature).</p>
 
   <p>
     If your sequence annotation is already available in <a href="http://gmod.org/wiki/GFF2">GFF2</a> (http://gmod.org/wiki/GFF2) or
@@ -204,6 +261,13 @@ signal peptide&#9;0,155,165
 helix&#9;ff0000
 strand&#9;00ff00
 coil&#9;cccccc
+kdHydrophobicity&#9;ccffcc|333300|-3.9|4.5|above|-2.0
+
+STARTFILTERS
+metal ion-binding site&#9;Label Contains sulfur
+kdHydrophobicity&#9;(Score LT 1.5) OR (Score GE 2.8)
+ENDFILTERS
+
 Your Own description here&#9;FER_CAPAA&#9;-1&#9;3&#9;93&#9;domain
 Your Own description here&#9;FER_CAPAN&#9;-1&#9;48&#9;144&#9;chain
 Your Own description here&#9;FER_CAPAN&#9;-1&#9;50&#9;140&#9;domain
@@ -211,10 +275,16 @@ Your Own description here&#9;FER_CAPAN&#9;-1&#9;136&#9;136&#9;modified residue
 Your Own description here&#9;FER1_LYCES&#9;-1&#9;1&#9;47&#9;transit peptide
 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;1&#9;48&#9;signal peptide
 Your Own description here&#9;Q93XJ9_SOLTU&#9;-1&#9;49&#9;144&#9;chain
-startgroup&#9;secondarystucture
+
+STARTGROUP&#9;secondarystucture
 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;52&#9;59&#9;strand
 PDB secondary structure annotation&#9;FER1_SPIOL&#9;-1&#9;74&#9;80&#9;helix
-endgroup&#9;secondarystructure
+ENDGROUP&#9;secondarystructure
+
+STARTGROUP&#9;kd
+Hydrophobicity score by kD     Q93XJ9_SOLTU    -1      48      48      kdHydrophobicity        1.8
+ENDGROUP&#9;kd
+
 GFF
 FER_CAPAA&#9;GffGroup&#9;domain&#9;3&#9;93&#9;.&#9;.
 </pre>

diff --git a/src/jalview/schemes/FeatureColour.java b/src/jalview/schemes/FeatureColour.java
index 7d14662..51e7645 100644 (file)
--- a/src/jalview/schemes/FeatureColour.java
+++ b/src/jalview/schemes/FeatureColour.java
@@ -321,8 +321,8 @@ public class FeatureColour implements FeatureColourI
       } catch (Exception e)
       {
         throw new IllegalArgumentException(
-                "Couldn't parse the minimum value for graduated colour ("
-                        + descriptor + ")");
+                "Couldn't parse the minimum value for graduated colour ('"
+                        + minval + "')");
       }
       try
       {

diff --git a/test/jalview/schemes/FeatureColourTest.java b/test/jalview/schemes/FeatureColourTest.java
index 2eb718b..a96caec 100644 (file)
--- a/test/jalview/schemes/FeatureColourTest.java
+++ b/test/jalview/schemes/FeatureColourTest.java
@@ -523,11 +523,60 @@ public class FeatureColourTest
     assertFalse(fc.hasThreshold());
     assertEquals(Color.RED, fc.getMinColour());
     assertEquals(Color.GREEN, fc.getMaxColour());
+    assertEquals(Color.RED, fc.getNoColour());
     assertEquals(10f, fc.getMin());
     assertEquals(20f, fc.getMax());
     assertTrue(fc.isAutoScaled());
 
     /*
+     * the same, with 'no value colour' specified as max
+     */
+    fc = FeatureColour
+            .parseJalviewFeatureColour("red|green|novaluemax|10.0|20.0");
+    assertEquals(Color.RED, fc.getMinColour());
+    assertEquals(Color.GREEN, fc.getMaxColour());
+    assertEquals(Color.GREEN, fc.getNoColour());
+    assertEquals(10f, fc.getMin());
+    assertEquals(20f, fc.getMax());
+
+    /*
+     * the same, with 'no value colour' specified as min
+     */
+    fc = FeatureColour
+            .parseJalviewFeatureColour("red|green|novalueMin|10.0|20.0");
+    assertEquals(Color.RED, fc.getMinColour());
+    assertEquals(Color.GREEN, fc.getMaxColour());
+    assertEquals(Color.RED, fc.getNoColour());
+    assertEquals(10f, fc.getMin());
+    assertEquals(20f, fc.getMax());
+
+    /*
+     * the same, with 'no value colour' specified as none
+     */
+    fc = FeatureColour
+            .parseJalviewFeatureColour("red|green|novaluenone|10.0|20.0");
+    assertEquals(Color.RED, fc.getMinColour());
+    assertEquals(Color.GREEN, fc.getMaxColour());
+    assertNull(fc.getNoColour());
+    assertEquals(10f, fc.getMin());
+    assertEquals(20f, fc.getMax());
+
+    /*
+     * the same, with invalid 'no value colour'
+     */
+    try
+    {
+      fc = FeatureColour
+              .parseJalviewFeatureColour("red|green|blue|10.0|20.0");
+      fail("expected exception");
+    } catch (IllegalArgumentException e)
+    {
+      assertEquals(
+              "Couldn't parse the minimum value for graduated colour ('blue')",
+              e.getMessage());
+    }
+
+    /*
      * graduated colour (explicitly by 'score') (no threshold)
      */
     fc = FeatureColour