JAL-3676 Documentation in Help for Java Console, Logging and Reporting Bugs
[jalview.git] / src / jalview / schemes / FeatureColour.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.schemes;
22
23 import jalview.api.FeatureColourI;
24 import jalview.datamodel.SequenceFeature;
25 import jalview.datamodel.features.FeatureMatcher;
26 import jalview.util.ColorUtils;
27 import jalview.util.Format;
28 import jalview.util.MessageManager;
29
30 import java.awt.Color;
31 import java.util.StringTokenizer;
32
33 /**
34  * A class that represents a colour scheme for a feature type. Options supported
35  * are currently
36  * <ul>
37  * <li>a simple colour e.g. Red</li>
38  * <li>colour by label - a colour is generated from the feature description</li>
39  * <li>graduated colour by feature score</li>
40  * <ul>
41  * <li>minimum and maximum score range must be provided</li>
42  * <li>minimum and maximum value colours should be specified</li>
43  * <li>a colour for 'no value' may optionally be provided</li>
44  * <li>colours for intermediate scores are interpolated RGB values</li>
45  * <li>there is an optional threshold above/below which to colour values</li>
46  * <li>the range may be the full value range, or may be limited by the threshold
47  * value</li>
48  * </ul>
49  * <li>colour by (text) value of a named attribute</li> <li>graduated colour by
50  * (numeric) value of a named attribute</li> </ul>
51  */
52 public class FeatureColour implements FeatureColourI
53 {
54   private static final String I18N_LABEL = MessageManager
55           .getString("label.label");
56
57   private static final String I18N_SCORE = MessageManager
58           .getString("label.score");
59
60   private static final String ABSOLUTE = "abso";
61
62   private static final String ABOVE = "above";
63
64   private static final String BELOW = "below";
65
66   /*
67    * constants used to read or write a Jalview Features file
68    */
69   private static final String LABEL = "label";
70
71   private static final String SCORE = "score";
72
73   private static final String ATTRIBUTE = "attribute";
74
75   private static final String NO_VALUE_MIN = "noValueMin";
76
77   private static final String NO_VALUE_MAX = "noValueMax";
78
79   private static final String NO_VALUE_NONE = "noValueNone";
80
81   static final Color DEFAULT_NO_COLOUR = null;
82
83   private static final String BAR = "|";
84
85   final private Color colour;
86
87   final private Color minColour;
88
89   final private Color maxColour;
90
91   /*
92    * colour to use for colour by attribute when the 
93    * attribute value is absent
94    */
95   final private Color noColour;
96
97   /*
98    * if true, then colour has a gradient based on a numerical 
99    * range (either feature score, or an attribute value)
100    */
101   private boolean graduatedColour;
102
103   /*
104    * if true, colour values are generated from a text string,
105    * either feature description, or an attribute value
106    */
107   private boolean colourByLabel;
108
109   /*
110    * if not null, the value of [attribute, [sub-attribute] ...]
111    *  is used for colourByLabel or graduatedColour
112    */
113   private String[] attributeName;
114
115   private float threshold;
116
117   private float base;
118
119   private float range;
120
121   private boolean belowThreshold;
122
123   private boolean aboveThreshold;
124
125   private boolean isHighToLow;
126
127   private boolean autoScaled;
128
129   final private float minRed;
130
131   final private float minGreen;
132
133   final private float minBlue;
134
135   final private float deltaRed;
136
137   final private float deltaGreen;
138
139   final private float deltaBlue;
140
141   /**
142    * Parses a Jalview features file format colour descriptor
143    * <p>
144    * <code>
145    * [label|score|[attribute|attributeName]|][mincolour|maxcolour|
146    * [absolute|]minvalue|maxvalue|[noValueOption|]thresholdtype|thresholdvalue]</code>
147    * <p>
148    * 'Score' is optional (default) for a graduated colour. An attribute with
149    * sub-attribute should be written as (for example) CSQ:Consequence.
150    * noValueOption is one of <code>noValueMin, noValueMax, noValueNone</code>
151    * with default noValueMin.
152    * <p>
153    * Examples:
154    * <ul>
155    * <li>red</li>
156    * <li>a28bbb</li>
157    * <li>25,125,213</li>
158    * <li>label</li>
159    * <li>attribute|CSQ:PolyPhen</li>
160    * <li>label|||0.0|0.0|above|12.5</li>
161    * <li>label|||0.0|0.0|below|12.5</li>
162    * <li>red|green|12.0|26.0|none</li>
163    * <li>score|red|green|12.0|26.0|none</li>
164    * <li>attribute|AF|red|green|12.0|26.0|none</li>
165    * <li>attribute|AF|red|green|noValueNone|12.0|26.0|none</li>
166    * <li>a28bbb|3eb555|12.0|26.0|above|12.5</li>
167    * <li>a28bbb|3eb555|abso|12.0|26.0|below|12.5</li>
168    * </ul>
169    * 
170    * @param descriptor
171    * @return
172    * @throws IllegalArgumentException
173    *           if not parseable
174    */
175   public static FeatureColourI parseJalviewFeatureColour(String descriptor)
176   {
177     StringTokenizer gcol = new StringTokenizer(descriptor, BAR, true);
178     float min = Float.MIN_VALUE;
179     float max = Float.MAX_VALUE;
180     boolean byLabel = false;
181     boolean byAttribute = false;
182     String attName = null;
183     String mincol = null;
184     String maxcol = null;
185
186     /*
187      * first token should be 'label', or 'score', or an
188      * attribute name, or simple colour, or minimum colour
189      */
190     String nextToken = gcol.nextToken();
191     if (nextToken == BAR)
192     {
193       throw new IllegalArgumentException(
194               "Expected either 'label' or a colour specification in the line: "
195                       + descriptor);
196     }
197     if (nextToken.toLowerCase().startsWith(LABEL))
198     {
199       byLabel = true;
200       // get the token after the next delimiter:
201       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
202       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
203     }
204     else if (nextToken.toLowerCase().startsWith(SCORE))
205     {
206       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
207       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
208     }
209     else if (nextToken.toLowerCase().startsWith(ATTRIBUTE))
210     {
211       byAttribute = true;
212       attName = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
213       attName = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
214       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
215       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
216     }
217     else
218     {
219       mincol = nextToken;
220     }
221
222     /*
223      * if only one token, it can validly be label, attributeName,
224      * or a plain colour value
225      */
226     if (!gcol.hasMoreTokens())
227     {
228       if (byLabel || byAttribute)
229       {
230         FeatureColourI fc = new FeatureColour();
231         fc.setColourByLabel(true);
232         if (byAttribute)
233         {
234           fc.setAttributeName(
235                   FeatureMatcher.fromAttributeDisplayName(attName));
236         }
237         return fc;
238       }
239
240       Color colour = ColorUtils.parseColourString(descriptor);
241       if (colour == null)
242       {
243         throw new IllegalArgumentException(
244                 "Invalid colour descriptor: " + descriptor);
245       }
246       return new FeatureColour(colour);
247     }
248
249     /*
250      * continue parsing for min/max/no colour (if graduated)
251      * and for threshold (colour by text or graduated)
252      */
253
254     /*
255      * autoScaled == true: colours range over actual score range
256      * autoScaled == false ('abso'): colours range over min/max range
257      */
258     boolean autoScaled = true;
259     String tok = null, minval, maxval;
260     String noValueColour = NO_VALUE_MIN;
261
262     if (mincol != null)
263     {
264       // at least four more tokens
265       if (mincol.equals(BAR))
266       {
267         mincol = null;
268       }
269       else
270       {
271         gcol.nextToken(); // skip next '|'
272       }
273       maxcol = gcol.nextToken();
274       if (maxcol.equals(BAR))
275       {
276         maxcol = null;
277       }
278       else
279       {
280         gcol.nextToken(); // skip next '|'
281       }
282       tok = gcol.nextToken();
283
284       /*
285        * check for specifier for colour for no attribute value
286        * (new in 2.11, defaults to minColour if not specified)
287        */
288       if (tok.equalsIgnoreCase(NO_VALUE_MIN))
289       {
290         tok = gcol.nextToken();
291         tok = gcol.nextToken();
292       }
293       else if (tok.equalsIgnoreCase(NO_VALUE_MAX))
294       {
295         noValueColour = NO_VALUE_MAX;
296         tok = gcol.nextToken();
297         tok = gcol.nextToken();
298       }
299       else if (tok.equalsIgnoreCase(NO_VALUE_NONE))
300       {
301         noValueColour = NO_VALUE_NONE;
302         tok = gcol.nextToken();
303         tok = gcol.nextToken();
304       }
305
306       gcol.nextToken(); // skip next '|'
307       if (tok.toLowerCase().startsWith(ABSOLUTE))
308       {
309         minval = gcol.nextToken();
310         gcol.nextToken(); // skip next '|'
311         autoScaled = false;
312       }
313       else
314       {
315         minval = tok;
316       }
317       maxval = gcol.nextToken();
318       if (gcol.hasMoreTokens())
319       {
320         gcol.nextToken(); // skip next '|'
321       }
322       try
323       {
324         if (minval.length() > 0)
325         {
326           min = Float.valueOf(minval).floatValue();
327         }
328       } catch (Exception e)
329       {
330         throw new IllegalArgumentException(
331                 "Couldn't parse the minimum value for graduated colour ('"
332                         + minval + "')");
333       }
334       try
335       {
336         if (maxval.length() > 0)
337         {
338           max = Float.valueOf(maxval).floatValue();
339         }
340       } catch (Exception e)
341       {
342         throw new IllegalArgumentException(
343                 "Couldn't parse the maximum value for graduated colour ("
344                         + descriptor + ")");
345       }
346     }
347     else
348     {
349       /*
350        * dummy min/max colours for colour by text
351        * (label or attribute value)
352        */
353       mincol = "white";
354       maxcol = "black";
355       byLabel = true;
356     }
357
358     /*
359      * construct the FeatureColour!
360      */
361     FeatureColour featureColour;
362     try
363     {
364       Color minColour = ColorUtils.parseColourString(mincol);
365       Color maxColour = ColorUtils.parseColourString(maxcol);
366       Color noColour = noValueColour.equals(NO_VALUE_MAX) ? maxColour
367               : (noValueColour.equals(NO_VALUE_NONE) ? null : minColour);
368       featureColour = new FeatureColour(maxColour, minColour, maxColour,
369               noColour, min, max);
370       featureColour.setColourByLabel(minColour == null);
371       featureColour.setAutoScaled(autoScaled);
372       if (byAttribute)
373       {
374         featureColour.setAttributeName(
375                 FeatureMatcher.fromAttributeDisplayName(attName));
376       }
377       // add in any additional parameters
378       String ttype = null, tval = null;
379       if (gcol.hasMoreTokens())
380       {
381         // threshold type and possibly a threshold value
382         ttype = gcol.nextToken();
383         if (ttype.toLowerCase().startsWith(BELOW))
384         {
385           featureColour.setBelowThreshold(true);
386         }
387         else if (ttype.toLowerCase().startsWith(ABOVE))
388         {
389           featureColour.setAboveThreshold(true);
390         }
391         else
392         {
393           if (!ttype.toLowerCase().startsWith("no"))
394           {
395             System.err.println(
396                     "Ignoring unrecognised threshold type : " + ttype);
397           }
398         }
399       }
400       if (featureColour.hasThreshold())
401       {
402         try
403         {
404           gcol.nextToken();
405           tval = gcol.nextToken();
406           featureColour.setThreshold(Float.valueOf(tval).floatValue());
407         } catch (Exception e)
408         {
409           System.err.println("Couldn't parse threshold value as a float: ("
410                   + tval + ")");
411         }
412       }
413       if (gcol.hasMoreTokens())
414       {
415         System.err.println(
416                 "Ignoring additional tokens in parameters in graduated colour specification\n");
417         while (gcol.hasMoreTokens())
418         {
419           System.err.println(BAR + gcol.nextToken());
420         }
421         System.err.println("\n");
422       }
423       return featureColour;
424     } catch (Exception e)
425     {
426       throw new IllegalArgumentException(e.getMessage());
427     }
428   }
429
430   /**
431    * Default constructor
432    */
433   public FeatureColour()
434   {
435     this((Color) null);
436   }
437
438   /**
439    * Constructor given a simple colour. This also 'primes' a graduated colour
440    * range, where the maximum colour is the given simple colour, and the minimum
441    * colour a paler shade of it. This is for convenience when switching from a
442    * simple colour to a graduated colour scheme.
443    * 
444    * @param c
445    */
446   public FeatureColour(Color c)
447   {
448     /*
449      * set max colour to the simple colour, min colour to a paler shade of it
450      */
451     this(c, c == null ? Color.white : ColorUtils.bleachColour(c, 0.9f),
452             c == null ? Color.black : c, DEFAULT_NO_COLOUR, 0, 0);
453
454     /*
455      * but enforce simple colour for now!
456      */
457     setGraduatedColour(false);
458   }
459
460   /**
461    * Copy constructor
462    * 
463    * @param fc
464    */
465   public FeatureColour(FeatureColour fc)
466   {
467     graduatedColour = fc.graduatedColour;
468     colour = fc.colour;
469     minColour = fc.minColour;
470     maxColour = fc.maxColour;
471     noColour = fc.noColour;
472     minRed = fc.minRed;
473     minGreen = fc.minGreen;
474     minBlue = fc.minBlue;
475     deltaRed = fc.deltaRed;
476     deltaGreen = fc.deltaGreen;
477     deltaBlue = fc.deltaBlue;
478     base = fc.base;
479     range = fc.range;
480     isHighToLow = fc.isHighToLow;
481     attributeName = fc.attributeName;
482     setAboveThreshold(fc.isAboveThreshold());
483     setBelowThreshold(fc.isBelowThreshold());
484     setThreshold(fc.getThreshold());
485     setAutoScaled(fc.isAutoScaled());
486     setColourByLabel(fc.isColourByLabel());
487   }
488
489   /**
490    * Constructor that sets both simple and graduated colour values. This allows
491    * alternative colour schemes to be 'preserved' while switching between them
492    * to explore their effects on the visualisation.
493    * <p>
494    * This sets the colour scheme to 'graduated' by default. Override this if
495    * wanted by calling <code>setGraduatedColour(false)</code> for a simple
496    * colour, or <code>setColourByLabel(true)</code> for colour by label.
497    * 
498    * @param myColour
499    * @param low
500    * @param high
501    * @param noValueColour
502    * @param min
503    * @param max
504    */
505   public FeatureColour(Color myColour, Color low, Color high,
506           Color noValueColour, float min, float max)
507   {
508     if (low == null)
509     {
510       low = Color.white;
511     }
512     if (high == null)
513     {
514       high = Color.black;
515     }
516     colour = myColour;
517     minColour = low;
518     maxColour = high;
519     setGraduatedColour(true);
520     noColour = noValueColour;
521     threshold = Float.NaN;
522     isHighToLow = min >= max;
523     minRed = low.getRed() / 255f;
524     minGreen = low.getGreen() / 255f;
525     minBlue = low.getBlue() / 255f;
526     deltaRed = (high.getRed() / 255f) - minRed;
527     deltaGreen = (high.getGreen() / 255f) - minGreen;
528     deltaBlue = (high.getBlue() / 255f) - minBlue;
529     if (isHighToLow)
530     {
531       base = max;
532       range = min - max;
533     }
534     else
535     {
536       base = min;
537       range = max - min;
538     }
539   }
540
541   @Override
542   public boolean isGraduatedColour()
543   {
544     return graduatedColour;
545   }
546
547   /**
548    * Sets the 'graduated colour' flag. If true, also sets 'colour by label' to
549    * false.
550    */
551   public void setGraduatedColour(boolean b)
552   {
553     graduatedColour = b;
554     if (b)
555     {
556       setColourByLabel(false);
557     }
558   }
559
560   @Override
561   public Color getColour()
562   {
563     return colour;
564   }
565
566   @Override
567   public Color getMinColour()
568   {
569     return minColour;
570   }
571
572   @Override
573   public Color getMaxColour()
574   {
575     return maxColour;
576   }
577
578   @Override
579   public Color getNoColour()
580   {
581     return noColour;
582   }
583
584   @Override
585   public boolean isColourByLabel()
586   {
587     return colourByLabel;
588   }
589
590   /**
591    * Sets the 'colour by label' flag. If true, also sets 'graduated colour' to
592    * false.
593    */
594   @Override
595   public void setColourByLabel(boolean b)
596   {
597     colourByLabel = b;
598     if (b)
599     {
600       setGraduatedColour(false);
601     }
602   }
603
604   @Override
605   public boolean isBelowThreshold()
606   {
607     return belowThreshold;
608   }
609
610   @Override
611   public void setBelowThreshold(boolean b)
612   {
613     belowThreshold = b;
614     if (b)
615     {
616       setAboveThreshold(false);
617     }
618   }
619
620   @Override
621   public boolean isAboveThreshold()
622   {
623     return aboveThreshold;
624   }
625
626   @Override
627   public void setAboveThreshold(boolean b)
628   {
629     aboveThreshold = b;
630     if (b)
631     {
632       setBelowThreshold(false);
633     }
634   }
635
636   @Override
637   public float getThreshold()
638   {
639     return threshold;
640   }
641
642   @Override
643   public void setThreshold(float f)
644   {
645     threshold = f;
646   }
647
648   @Override
649   public boolean isAutoScaled()
650   {
651     return autoScaled;
652   }
653
654   @Override
655   public void setAutoScaled(boolean b)
656   {
657     this.autoScaled = b;
658   }
659
660   /**
661    * {@inheritDoc}
662    */
663   @Override
664   public void updateBounds(float min, float max)
665   {
666     if (max < min)
667     {
668       base = max;
669       range = min - max;
670       isHighToLow = true;
671     }
672     else
673     {
674       base = min;
675       range = max - min;
676       isHighToLow = false;
677     }
678   }
679
680   /**
681    * Returns the colour for the given instance of the feature. This may be a
682    * simple colour, a colour generated from the feature description or other
683    * attribute (if isColourByLabel()), or a colour derived from the feature
684    * score or other attribute (if isGraduatedColour()).
685    * <p>
686    * Answers null if feature score (or attribute) value lies outside a
687    * configured threshold.
688    * 
689    * @param feature
690    * @return
691    */
692   @Override
693   public Color getColor(SequenceFeature feature)
694   {
695     if (isColourByLabel())
696     {
697       String label = attributeName == null ? feature.getDescription()
698               : feature.getValueAsString(attributeName);
699       return label == null ? noColour : ColorUtils
700               .createColourFromName(label);
701     }
702
703     if (!isGraduatedColour())
704     {
705       return getColour();
706     }
707
708     /*
709      * graduated colour case, optionally with threshold
710      * may be based on feature score on an attribute value
711      * Float.NaN, or no value, is assigned the 'no value' colour
712      */
713     float scr = feature.getScore();
714     if (attributeName != null)
715     {
716       try
717       {
718         String attVal = feature.getValueAsString(attributeName);
719         scr = Float.valueOf(attVal);
720       } catch (Throwable e)
721       {
722         scr = Float.NaN;
723       }
724     }
725     if (Float.isNaN(scr))
726     {
727       return noColour;
728     }
729
730     if (isAboveThreshold() && scr <= threshold)
731     {
732       return null;
733     }
734
735     if (isBelowThreshold() && scr >= threshold)
736     {
737       return null;
738     }
739     if (range == 0.0)
740     {
741       return getMaxColour();
742     }
743     float scl = (scr - base) / range;
744     if (isHighToLow)
745     {
746       scl = -scl;
747     }
748     if (scl < 0f)
749     {
750       scl = 0f;
751     }
752     if (scl > 1f)
753     {
754       scl = 1f;
755     }
756     return new Color(minRed + scl * deltaRed, minGreen + scl * deltaGreen,
757             minBlue + scl * deltaBlue);
758   }
759
760   /**
761    * Returns the maximum score of the graduated colour range
762    * 
763    * @return
764    */
765   @Override
766   public float getMax()
767   {
768     // regenerate the original values passed in to the constructor
769     return (isHighToLow) ? base : (base + range);
770   }
771
772   /**
773    * Returns the minimum score of the graduated colour range
774    * 
775    * @return
776    */
777   @Override
778   public float getMin()
779   {
780     // regenerate the original value passed in to the constructor
781     return (isHighToLow) ? (base + range) : base;
782   }
783
784   @Override
785   public boolean isSimpleColour()
786   {
787     return (!isColourByLabel() && !isGraduatedColour());
788   }
789
790   @Override
791   public boolean hasThreshold()
792   {
793     return isAboveThreshold() || isBelowThreshold();
794   }
795
796   @Override
797   public String toJalviewFormat(String featureType)
798   {
799     String colourString = null;
800     if (isSimpleColour())
801     {
802       colourString = Format.getHexString(getColour());
803     }
804     else
805     {
806       StringBuilder sb = new StringBuilder(32);
807       if (isColourByAttribute())
808       {
809         sb.append(ATTRIBUTE).append(BAR);
810         sb.append(
811                 FeatureMatcher.toAttributeDisplayName(getAttributeName()));
812       }
813       else if (isColourByLabel())
814       {
815         sb.append(LABEL);
816       }
817       else
818       {
819         sb.append(SCORE);
820       }
821       if (isGraduatedColour())
822       {
823         sb.append(BAR).append(Format.getHexString(getMinColour()))
824                 .append(BAR);
825         sb.append(Format.getHexString(getMaxColour())).append(BAR);
826         
827         /*
828          * 'no value' colour should be null, min or max colour;
829          * if none of these, coerce to minColour
830          */
831         String noValue = NO_VALUE_MIN;
832         if (maxColour.equals(noColour))
833         {
834           noValue = NO_VALUE_MAX;
835         }
836         if (noColour == null)
837         {
838           noValue = NO_VALUE_NONE;
839         }
840         sb.append(noValue).append(BAR);
841         if (!isAutoScaled())
842         {
843           sb.append(ABSOLUTE).append(BAR);
844         }
845       }
846       else
847       {
848         /*
849          * colour by text with score threshold: empty fields for
850          * minColour and maxColour (not used)
851          */
852         if (hasThreshold())
853         {
854           sb.append(BAR).append(BAR).append(BAR);
855         }
856       }
857       if (hasThreshold() || isGraduatedColour())
858       {
859         sb.append(getMin()).append(BAR);
860         sb.append(getMax()).append(BAR);
861         if (isBelowThreshold())
862         {
863           sb.append(BELOW).append(BAR).append(getThreshold());
864         }
865         else if (isAboveThreshold())
866         {
867           sb.append(ABOVE).append(BAR).append(getThreshold());
868         }
869         else
870         {
871           sb.append("none");
872         }
873       }
874       colourString = sb.toString();
875     }
876     return String.format("%s\t%s", featureType, colourString);
877   }
878
879   @Override
880   public boolean isColourByAttribute()
881   {
882     return attributeName != null;
883   }
884
885   @Override
886   public String[] getAttributeName()
887   {
888     return attributeName;
889   }
890
891   @Override
892   public void setAttributeName(String... name)
893   {
894     attributeName = name;
895   }
896
897   @Override
898   public boolean isOutwithThreshold(SequenceFeature feature)
899   {
900     if (!isGraduatedColour())
901     {
902       return false;
903     }
904     float scr = feature.getScore();
905     if (attributeName != null)
906     {
907       try
908       {
909         String attVal = feature.getValueAsString(attributeName);
910         scr = Float.valueOf(attVal);
911       } catch (Throwable e)
912       {
913         scr = Float.NaN;
914       }
915     }
916     if (Float.isNaN(scr))
917     {
918       return false;
919     }
920
921     return ((isAboveThreshold() && scr <= threshold)
922             || (isBelowThreshold() && scr >= threshold));
923   }
924
925   @Override
926   public String getDescription()
927   {
928     if (isSimpleColour())
929     {
930       return "r=" + colour.getRed() + ",g=" + colour.getGreen() + ",b="
931               + colour.getBlue();
932     }
933     StringBuilder tt = new StringBuilder();
934     String by = null;
935
936     if (getAttributeName() != null)
937     {
938       by = FeatureMatcher.toAttributeDisplayName(getAttributeName());
939     }
940     else if (isColourByLabel())
941     {
942       by = I18N_LABEL;
943     }
944     else
945     {
946       by = I18N_SCORE;
947     }
948     tt.append(MessageManager.formatMessage("action.by_title_param", by));
949
950     /*
951      * add threshold if any
952      */
953     if (isAboveThreshold() || isBelowThreshold())
954     {
955       tt.append(" (");
956       if (isColourByLabel())
957       {
958         /*
959          * Jalview features file supports the combination of 
960          * colour by label or attribute text with score threshold
961          */
962         tt.append(I18N_SCORE).append(" ");
963       }
964       tt.append(isAboveThreshold() ? "> " : "< ");
965       tt.append(getThreshold()).append(")");
966     }
967
968     return tt.toString();
969   }
970
971 }