Merge branch 'features/JAL-2446NCList' into features/JAL-2574findFeaturesByColumn
[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.util.ColorUtils;
26 import jalview.util.Format;
27
28 import java.awt.Color;
29 import java.util.StringTokenizer;
30
31 /**
32  * A class that wraps either a simple colour or a graduated colour
33  */
34 public class FeatureColour implements FeatureColourI
35 {
36   private static final String BAR = "|";
37
38   final private Color colour;
39
40   final private Color minColour;
41
42   final private Color maxColour;
43
44   private boolean graduatedColour;
45
46   private boolean colourByLabel;
47
48   private float threshold;
49
50   private float base;
51
52   private float range;
53
54   private boolean belowThreshold;
55
56   private boolean aboveThreshold;
57
58   private boolean thresholdIsMinOrMax;
59
60   private boolean isHighToLow;
61
62   private boolean autoScaled;
63
64   final private float minRed;
65
66   final private float minGreen;
67
68   final private float minBlue;
69
70   final private float deltaRed;
71
72   final private float deltaGreen;
73
74   final private float deltaBlue;
75
76   /**
77    * Parses a Jalview features file format colour descriptor
78    * [label|][mincolour|maxcolour
79    * |[absolute|]minvalue|maxvalue|thresholdtype|thresholdvalue] Examples:
80    * <ul>
81    * <li>red</li>
82    * <li>a28bbb</li>
83    * <li>25,125,213</li>
84    * <li>label</li>
85    * <li>label|||0.0|0.0|above|12.5</li>
86    * <li>label|||0.0|0.0|below|12.5</li>
87    * <li>red|green|12.0|26.0|none</li>
88    * <li>a28bbb|3eb555|12.0|26.0|above|12.5</li>
89    * <li>a28bbb|3eb555|abso|12.0|26.0|below|12.5</li>
90    * </ul>
91    * 
92    * @param descriptor
93    * @return
94    * @throws IllegalArgumentException
95    *           if not parseable
96    */
97   public static FeatureColour parseJalviewFeatureColour(String descriptor)
98   {
99     StringTokenizer gcol = new StringTokenizer(descriptor, "|", true);
100     float min = Float.MIN_VALUE;
101     float max = Float.MAX_VALUE;
102     boolean labelColour = false;
103
104     String mincol = gcol.nextToken();
105     if (mincol == "|")
106     {
107       throw new IllegalArgumentException(
108               "Expected either 'label' or a colour specification in the line: "
109                       + descriptor);
110     }
111     String maxcol = null;
112     if (mincol.toLowerCase().indexOf("label") == 0)
113     {
114       labelColour = true;
115       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
116       // skip '|'
117       mincol = (gcol.hasMoreTokens() ? gcol.nextToken() : null);
118     }
119
120     if (!labelColour && !gcol.hasMoreTokens())
121     {
122       /*
123        * only a simple colour specification - parse it
124        */
125       Color colour = ColorUtils.parseColourString(descriptor);
126       if (colour == null)
127       {
128         throw new IllegalArgumentException("Invalid colour descriptor: "
129                 + descriptor);
130       }
131       return new FeatureColour(colour);
132     }
133
134     /*
135      * autoScaled == true: colours range over actual score range
136      * autoScaled == false ('abso'): colours range over min/max range
137      */
138     boolean autoScaled = true;
139     String tok = null, minval, maxval;
140     if (mincol != null)
141     {
142       // at least four more tokens
143       if (mincol.equals("|"))
144       {
145         mincol = "";
146       }
147       else
148       {
149         gcol.nextToken(); // skip next '|'
150       }
151       maxcol = gcol.nextToken();
152       if (maxcol.equals("|"))
153       {
154         maxcol = "";
155       }
156       else
157       {
158         gcol.nextToken(); // skip next '|'
159       }
160       tok = gcol.nextToken();
161       gcol.nextToken(); // skip next '|'
162       if (tok.toLowerCase().startsWith("abso"))
163       {
164         minval = gcol.nextToken();
165         gcol.nextToken(); // skip next '|'
166         autoScaled = false;
167       }
168       else
169       {
170         minval = tok;
171       }
172       maxval = gcol.nextToken();
173       if (gcol.hasMoreTokens())
174       {
175         gcol.nextToken(); // skip next '|'
176       }
177       try
178       {
179         if (minval.length() > 0)
180         {
181           min = new Float(minval).floatValue();
182         }
183       } catch (Exception e)
184       {
185         throw new IllegalArgumentException(
186                 "Couldn't parse the minimum value for graduated colour ("
187                         + descriptor + ")");
188       }
189       try
190       {
191         if (maxval.length() > 0)
192         {
193           max = new Float(maxval).floatValue();
194         }
195       } catch (Exception e)
196       {
197         throw new IllegalArgumentException(
198                 "Couldn't parse the maximum value for graduated colour ("
199                         + descriptor + ")");
200       }
201     }
202     else
203     {
204       // add in some dummy min/max colours for the label-only
205       // colourscheme.
206       mincol = "FFFFFF";
207       maxcol = "000000";
208     }
209
210     /*
211      * construct the FeatureColour
212      */
213     FeatureColour featureColour;
214     try
215     {
216       Color minColour = ColorUtils.parseColourString(mincol);
217       Color maxColour = ColorUtils.parseColourString(maxcol);
218       featureColour = new FeatureColour(minColour, maxColour, min, max);
219       featureColour.setColourByLabel(labelColour);
220       featureColour.setAutoScaled(autoScaled);
221       // add in any additional parameters
222       String ttype = null, tval = null;
223       if (gcol.hasMoreTokens())
224       {
225         // threshold type and possibly a threshold value
226         ttype = gcol.nextToken();
227         if (ttype.toLowerCase().startsWith("below"))
228         {
229           featureColour.setBelowThreshold(true);
230         }
231         else if (ttype.toLowerCase().startsWith("above"))
232         {
233           featureColour.setAboveThreshold(true);
234         }
235         else
236         {
237           if (!ttype.toLowerCase().startsWith("no"))
238           {
239             System.err.println("Ignoring unrecognised threshold type : "
240                     + ttype);
241           }
242         }
243       }
244       if (featureColour.hasThreshold())
245       {
246         try
247         {
248           gcol.nextToken();
249           tval = gcol.nextToken();
250           featureColour.setThreshold(new Float(tval).floatValue());
251         } catch (Exception e)
252         {
253           System.err.println("Couldn't parse threshold value as a float: ("
254                   + tval + ")");
255         }
256       }
257       if (gcol.hasMoreTokens())
258       {
259         System.err
260                 .println("Ignoring additional tokens in parameters in graduated colour specification\n");
261         while (gcol.hasMoreTokens())
262         {
263           System.err.println("|" + gcol.nextToken());
264         }
265         System.err.println("\n");
266       }
267       return featureColour;
268     } catch (Exception e)
269     {
270       throw new IllegalArgumentException(e.getMessage());
271     }
272   }
273
274   /**
275    * Default constructor
276    */
277   public FeatureColour()
278   {
279     this((Color) null);
280   }
281
282   /**
283    * Constructor given a simple colour
284    * 
285    * @param c
286    */
287   public FeatureColour(Color c)
288   {
289     minColour = Color.WHITE;
290     maxColour = Color.BLACK;
291     minRed = 0f;
292     minGreen = 0f;
293     minBlue = 0f;
294     deltaRed = 0f;
295     deltaGreen = 0f;
296     deltaBlue = 0f;
297     colour = c;
298   }
299
300   /**
301    * Constructor given a colour range and a score range
302    * 
303    * @param low
304    * @param high
305    * @param min
306    * @param max
307    */
308   public FeatureColour(Color low, Color high, float min, float max)
309   {
310     if (low == null)
311     {
312       low = Color.white;
313     }
314     if (high == null)
315     {
316       high = Color.black;
317     }
318     graduatedColour = true;
319     colour = null;
320     minColour = low;
321     maxColour = high;
322     threshold = Float.NaN;
323     isHighToLow = min >= max;
324     minRed = low.getRed() / 255f;
325     minGreen = low.getGreen() / 255f;
326     minBlue = low.getBlue() / 255f;
327     deltaRed = (high.getRed() / 255f) - minRed;
328     deltaGreen = (high.getGreen() / 255f) - minGreen;
329     deltaBlue = (high.getBlue() / 255f) - minBlue;
330     if (isHighToLow)
331     {
332       base = max;
333       range = min - max;
334     }
335     else
336     {
337       base = min;
338       range = max - min;
339     }
340   }
341
342   /**
343    * Copy constructor
344    * 
345    * @param fc
346    */
347   public FeatureColour(FeatureColour fc)
348   {
349     graduatedColour = fc.graduatedColour;
350     colour = fc.colour;
351     minColour = fc.minColour;
352     maxColour = fc.maxColour;
353     minRed = fc.minRed;
354     minGreen = fc.minGreen;
355     minBlue = fc.minBlue;
356     deltaRed = fc.deltaRed;
357     deltaGreen = fc.deltaGreen;
358     deltaBlue = fc.deltaBlue;
359     base = fc.base;
360     range = fc.range;
361     isHighToLow = fc.isHighToLow;
362     setAboveThreshold(fc.isAboveThreshold());
363     setBelowThreshold(fc.isBelowThreshold());
364     setThreshold(fc.getThreshold());
365     setAutoScaled(fc.isAutoScaled());
366     setColourByLabel(fc.isColourByLabel());
367   }
368
369   /**
370    * Copy constructor with new min/max ranges
371    * 
372    * @param fc
373    * @param min
374    * @param max
375    */
376   public FeatureColour(FeatureColour fc, float min, float max)
377   {
378     this(fc);
379     graduatedColour = true;
380     updateBounds(min, max);
381   }
382
383   @Override
384   public boolean isGraduatedColour()
385   {
386     return graduatedColour;
387   }
388
389   /**
390    * Sets the 'graduated colour' flag. If true, also sets 'colour by label' to
391    * false.
392    */
393   void setGraduatedColour(boolean b)
394   {
395     graduatedColour = b;
396     if (b)
397     {
398       setColourByLabel(false);
399     }
400   }
401
402   @Override
403   public Color getColour()
404   {
405     return colour;
406   }
407
408   @Override
409   public Color getMinColour()
410   {
411     return minColour;
412   }
413
414   @Override
415   public Color getMaxColour()
416   {
417     return maxColour;
418   }
419
420   @Override
421   public boolean isColourByLabel()
422   {
423     return colourByLabel;
424   }
425
426   /**
427    * Sets the 'colour by label' flag. If true, also sets 'graduated colour' to
428    * false.
429    */
430   @Override
431   public void setColourByLabel(boolean b)
432   {
433     colourByLabel = b;
434     if (b)
435     {
436       setGraduatedColour(false);
437     }
438   }
439
440   @Override
441   public boolean isBelowThreshold()
442   {
443     return belowThreshold;
444   }
445
446   @Override
447   public void setBelowThreshold(boolean b)
448   {
449     belowThreshold = b;
450     if (b)
451     {
452       setAboveThreshold(false);
453     }
454   }
455
456   @Override
457   public boolean isAboveThreshold()
458   {
459     return aboveThreshold;
460   }
461
462   @Override
463   public void setAboveThreshold(boolean b)
464   {
465     aboveThreshold = b;
466     if (b)
467     {
468       setBelowThreshold(false);
469     }
470   }
471
472   @Override
473   public boolean isThresholdMinMax()
474   {
475     return thresholdIsMinOrMax;
476   }
477
478   @Override
479   public void setThresholdMinMax(boolean b)
480   {
481     thresholdIsMinOrMax = b;
482   }
483
484   @Override
485   public float getThreshold()
486   {
487     return threshold;
488   }
489
490   @Override
491   public void setThreshold(float f)
492   {
493     threshold = f;
494   }
495
496   @Override
497   public boolean isAutoScaled()
498   {
499     return autoScaled;
500   }
501
502   @Override
503   public void setAutoScaled(boolean b)
504   {
505     this.autoScaled = b;
506   }
507
508   /**
509    * Updates the base and range appropriately for the given minmax range
510    * 
511    * @param min
512    * @param max
513    */
514   @Override
515   public void updateBounds(float min, float max)
516   {
517     if (max < min)
518     {
519       base = max;
520       range = min - max;
521       isHighToLow = true;
522     }
523     else
524     {
525       base = min;
526       range = max - min;
527       isHighToLow = false;
528     }
529   }
530
531   /**
532    * Returns the colour for the given instance of the feature. This may be a
533    * simple colour, a colour generated from the feature description (if
534    * isColourByLabel()), or a colour derived from the feature score (if
535    * isGraduatedColour()).
536    * 
537    * @param feature
538    * @return
539    */
540   @Override
541   public Color getColor(SequenceFeature feature)
542   {
543     if (isColourByLabel())
544     {
545       return ColorUtils
546               .createColourFromName(feature.getDescription());
547     }
548
549     if (!isGraduatedColour())
550     {
551       return getColour();
552     }
553
554     // todo should we check for above/below threshold here?
555     if (range == 0.0)
556     {
557       return getMaxColour();
558     }
559     float scr = feature.getScore();
560     if (Float.isNaN(scr))
561     {
562       return getMinColour();
563     }
564     float scl = (scr - base) / range;
565     if (isHighToLow)
566     {
567       scl = -scl;
568     }
569     if (scl < 0f)
570     {
571       scl = 0f;
572     }
573     if (scl > 1f)
574     {
575       scl = 1f;
576     }
577     return new Color(minRed + scl * deltaRed, minGreen + scl * deltaGreen,
578             minBlue + scl * deltaBlue);
579   }
580
581   /**
582    * Returns the maximum score of the graduated colour range
583    * 
584    * @return
585    */
586   @Override
587   public float getMax()
588   {
589     // regenerate the original values passed in to the constructor
590     return (isHighToLow) ? base : (base + range);
591   }
592
593   /**
594    * Returns the minimum score of the graduated colour range
595    * 
596    * @return
597    */
598   @Override
599   public float getMin()
600   {
601     // regenerate the original value passed in to the constructor
602     return (isHighToLow) ? (base + range) : base;
603   }
604
605   /**
606    * Answers true if the feature has a simple colour, or is coloured by label,
607    * or has a graduated colour and the score of this feature instance is within
608    * the range to render (if any), i.e. does not lie below or above any
609    * threshold set.
610    * 
611    * @param feature
612    * @return
613    */
614   @Override
615   public boolean isColored(SequenceFeature feature)
616   {
617     if (isColourByLabel() || !isGraduatedColour())
618     {
619       return true;
620     }
621
622     float val = feature.getScore();
623     if (Float.isNaN(val))
624     {
625       return true;
626     }
627     if (Float.isNaN(this.threshold))
628     {
629       return true;
630     }
631
632     if (isAboveThreshold() && val <= threshold)
633     {
634       return false;
635     }
636     if (isBelowThreshold() && val >= threshold)
637     {
638       return false;
639     }
640     return true;
641   }
642
643   @Override
644   public boolean isSimpleColour()
645   {
646     return (!isColourByLabel() && !isGraduatedColour());
647   }
648
649   @Override
650   public boolean hasThreshold()
651   {
652     return isAboveThreshold() || isBelowThreshold();
653   }
654
655   @Override
656   public String toJalviewFormat(String featureType)
657   {
658     String colourString = null;
659     if (isSimpleColour())
660     {
661       colourString = Format.getHexString(getColour());
662     }
663     else
664     {
665       StringBuilder sb = new StringBuilder(32);
666       if (isColourByLabel())
667       {
668         sb.append("label");
669         if (hasThreshold())
670         {
671           sb.append(BAR).append(BAR).append(BAR);
672         }
673       }
674       if (isGraduatedColour())
675       {
676         sb.append(Format.getHexString(getMinColour())).append(BAR);
677         sb.append(Format.getHexString(getMaxColour())).append(BAR);
678         if (!isAutoScaled())
679         {
680           sb.append("abso").append(BAR);
681         }
682       }
683       if (hasThreshold() || isGraduatedColour())
684       {
685         sb.append(getMin()).append(BAR);
686         sb.append(getMax()).append(BAR);
687         if (isBelowThreshold())
688         {
689           sb.append("below").append(BAR).append(getThreshold());
690         }
691         else if (isAboveThreshold())
692         {
693           sb.append("above").append(BAR).append(getThreshold());
694         }
695         else
696         {
697           sb.append("none");
698         }
699       }
700       colourString = sb.toString();
701     }
702     return String.format("%s\t%s", featureType, colourString);
703   }
704
705 }