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