JAL-3676 Documentation in Help for Java Console, Logging and Reporting Bugs
[jalview.git] / src / jalview / schemes / AnnotationColourGradient.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.AlignViewportI;
24 import jalview.datamodel.AlignmentAnnotation;
25 import jalview.datamodel.AlignmentI;
26 import jalview.datamodel.AnnotatedCollectionI;
27 import jalview.datamodel.Annotation;
28 import jalview.datamodel.GraphLine;
29 import jalview.datamodel.SequenceCollectionI;
30 import jalview.datamodel.SequenceI;
31 import jalview.renderer.AnnotationRenderer;
32 import jalview.util.Comparison;
33
34 import java.awt.Color;
35 import java.util.IdentityHashMap;
36 import java.util.Map;
37
38 public class AnnotationColourGradient extends FollowerColourScheme
39 {
40   public static final int NO_THRESHOLD = -1;
41
42   public static final int BELOW_THRESHOLD = 0;
43
44   public static final int ABOVE_THRESHOLD = 1;
45
46   private final AlignmentAnnotation annotation;
47
48   private final int aboveAnnotationThreshold;
49
50   public boolean thresholdIsMinMax = false;
51
52   private GraphLine annotationThreshold;
53
54   private int redMin;
55
56   private int greenMin;
57
58   private int blueMin;
59
60   private int redRange;
61
62   private int greenRange;
63
64   private int blueRange;
65
66   private boolean predefinedColours = false;
67
68   private boolean seqAssociated = false;
69
70   /**
71    * false if the scheme was constructed without a minColour and maxColour used
72    * to decide if existing colours should be taken from annotation elements when
73    * they exist
74    */
75   private boolean noGradient = false;
76
77   private IdentityHashMap<SequenceI, AlignmentAnnotation> seqannot = null;
78
79   @Override
80   public ColourSchemeI getInstance(AlignViewportI view,
81           AnnotatedCollectionI sg)
82   {
83     AnnotationColourGradient acg = new AnnotationColourGradient(annotation,
84             getColourScheme(), aboveAnnotationThreshold);
85     acg.thresholdIsMinMax = thresholdIsMinMax;
86     acg.annotationThreshold = (annotationThreshold == null) ? null
87             : new GraphLine(annotationThreshold);
88     acg.redMin = redMin;
89     acg.greenMin = greenMin;
90     acg.blueMin = blueMin;
91     acg.redRange = redRange;
92     acg.greenRange = greenRange;
93     acg.blueRange = blueRange;
94     acg.predefinedColours = predefinedColours;
95     acg.seqAssociated = seqAssociated;
96     acg.noGradient = noGradient;
97     return acg;
98   }
99
100   /**
101    * Creates a new AnnotationColourGradient object.
102    */
103   public AnnotationColourGradient(AlignmentAnnotation annotation,
104           ColourSchemeI originalColour, int aboveThreshold)
105   {
106     if (originalColour instanceof AnnotationColourGradient)
107     {
108       setColourScheme(((AnnotationColourGradient) originalColour)
109               .getColourScheme());
110     }
111     else
112     {
113       setColourScheme(originalColour);
114     }
115
116     this.annotation = annotation;
117
118     aboveAnnotationThreshold = aboveThreshold;
119
120     if (aboveThreshold != NO_THRESHOLD && annotation.threshold != null)
121     {
122       annotationThreshold = annotation.threshold;
123     }
124     // clear values so we don't get weird black bands...
125     redMin = 254;
126     greenMin = 254;
127     blueMin = 254;
128     redRange = 0;
129     greenRange = 0;
130     blueRange = 0;
131
132     noGradient = true;
133     checkLimits();
134   }
135
136   /**
137    * Creates a new AnnotationColourGradient object.
138    */
139   public AnnotationColourGradient(AlignmentAnnotation annotation,
140           Color minColour, Color maxColour, int aboveThreshold)
141   {
142     this.annotation = annotation;
143
144     aboveAnnotationThreshold = aboveThreshold;
145
146     if (aboveThreshold != NO_THRESHOLD && annotation.threshold != null)
147     {
148       annotationThreshold = annotation.threshold;
149     }
150
151     redMin = minColour.getRed();
152     greenMin = minColour.getGreen();
153     blueMin = minColour.getBlue();
154
155     redRange = maxColour.getRed() - redMin;
156     greenRange = maxColour.getGreen() - greenMin;
157     blueRange = maxColour.getBlue() - blueMin;
158
159     noGradient = false;
160     checkLimits();
161   }
162
163   private void checkLimits()
164   {
165     aamax = annotation.graphMax;
166     aamin = annotation.graphMin;
167     if (annotation.isRNA())
168     {
169       // reset colour palette
170       ColourSchemeProperty.resetRnaHelicesShading();
171       ColourSchemeProperty.initRnaHelicesShading(1 + (int) aamax);
172     }
173   }
174
175   @Override
176   public void alignmentChanged(AnnotatedCollectionI alignment,
177           Map<SequenceI, SequenceCollectionI> hiddenReps)
178   {
179     super.alignmentChanged(alignment, hiddenReps);
180
181     if (seqAssociated && annotation.getCalcId() != null)
182     {
183       if (seqannot != null)
184       {
185         seqannot.clear();
186       }
187       else
188       {
189         seqannot = new IdentityHashMap<>();
190       }
191       // resolve the context containing all the annotation for the sequence
192       AnnotatedCollectionI alcontext = alignment instanceof AlignmentI
193               ? alignment
194               : alignment.getContext();
195       boolean f = true, rna = false;
196       for (AlignmentAnnotation alan : alcontext
197               .findAnnotation(annotation.getCalcId()))
198       {
199         if (alan.sequenceRef != null
200                 && (alan.label != null && annotation != null
201                         && alan.label.equals(annotation.label)))
202         {
203           if (!rna && alan.isRNA())
204           {
205             rna = true;
206           }
207           seqannot.put(alan.sequenceRef, alan);
208           if (f || alan.graphMax > aamax)
209           {
210             aamax = alan.graphMax;
211           }
212           if (f || alan.graphMin < aamin)
213           {
214             aamin = alan.graphMin;
215           }
216           f = false;
217         }
218       }
219       if (rna)
220       {
221         ColourSchemeProperty.initRnaHelicesShading(1 + (int) aamax);
222       }
223     }
224   }
225
226   float aamin = 0f, aamax = 0f;
227
228   public AlignmentAnnotation getAnnotation()
229   {
230     return annotation;
231   }
232
233   public int getAboveThreshold()
234   {
235     return aboveAnnotationThreshold;
236   }
237
238   public float getAnnotationThreshold()
239   {
240     if (annotationThreshold == null)
241     {
242       return 0;
243     }
244     else
245     {
246       return annotationThreshold.value;
247     }
248   }
249
250   public Color getMinColour()
251   {
252     return new Color(redMin, greenMin, blueMin);
253   }
254
255   public Color getMaxColour()
256   {
257     return new Color(redMin + redRange, greenMin + greenRange,
258             blueMin + blueRange);
259   }
260
261   /**
262    * DOCUMENT ME!
263    * 
264    * @param n
265    *          DOCUMENT ME!
266    * 
267    * @return DOCUMENT ME!
268    */
269   @Override
270   public Color findColour(char c)
271   {
272     return Color.red;
273   }
274
275   /**
276    * Returns the colour for a given character and position in a sequence
277    * 
278    * @param c
279    *          the residue character
280    * @param j
281    *          the aligned position
282    * @param seq
283    *          the sequence
284    * @return
285    */
286   @Override
287   public Color findColour(char c, int j, SequenceI seq)
288   {
289     /*
290      * locate the annotation we are configured to colour by
291      */
292     AlignmentAnnotation ann = (seqAssociated && seqannot != null
293             ? seqannot.get(seq)
294             : this.annotation);
295
296     /*
297      * if gap or no annotation at position, no colour (White)
298      */
299     if (ann == null || ann.annotations == null
300             || j >= ann.annotations.length || ann.annotations[j] == null
301             || Comparison.isGap(c))
302     {
303       return Color.white;
304     }
305
306     Annotation aj = ann.annotations[j];
307     // 'use original colours' => colourScheme != null
308     // -> look up colour to be used
309     // predefined colours => preconfigured shading
310     // -> only use original colours reference if thresholding enabled &
311     // minmax exists
312     // annotation.hasIcons => null or black colours replaced with glyph
313     // colours
314     // -> reuse original colours if present
315     // -> if thresholding enabled then return colour on non-whitespace glyph
316
317     /*
318      * if threshold applies, and annotation fails the test - no colour (white)
319      */
320     if (annotationThreshold != null)
321     {
322       if ((aboveAnnotationThreshold == ABOVE_THRESHOLD
323               && aj.value <= annotationThreshold.value)
324               || (aboveAnnotationThreshold == BELOW_THRESHOLD
325                       && aj.value >= annotationThreshold.value))
326       {
327         return Color.white;
328       }
329     }
330
331     /*
332      * If 'use original colours' then return the colour of the annotation
333      * at the aligned position - computed using the background colour scheme
334      */
335     if (predefinedColours && aj.colour != null
336             && !aj.colour.equals(Color.black))
337     {
338       return aj.colour;
339     }
340
341     Color result = Color.white;
342     if (ann.hasIcons && ann.graph == AlignmentAnnotation.NO_GRAPH)
343     {
344       /*
345        * secondary structure symbol colouring
346        */
347       if (aj.secondaryStructure > ' ' && aj.secondaryStructure != '.'
348               && aj.secondaryStructure != '-')
349       {
350         if (getColourScheme() != null)
351         {
352           result = getColourScheme().findColour(c, j, seq, null, 0f);
353         }
354         else
355         {
356           if (ann.isRNA())
357           {
358             result = ColourSchemeProperty.rnaHelices[(int) aj.value];
359           }
360           else
361           {
362             result = ann.annotations[j].secondaryStructure == 'H'
363                     ? AnnotationRenderer.HELIX_COLOUR
364                     : ann.annotations[j].secondaryStructure == 'E'
365                             ? AnnotationRenderer.SHEET_COLOUR
366                             : AnnotationRenderer.STEM_COLOUR;
367           }
368         }
369       }
370       else
371       {
372         return Color.white;
373       }
374     }
375     else if (noGradient)
376     {
377       if (getColourScheme() != null)
378       {
379         result = getColourScheme().findColour(c, j, seq, null, 0f);
380       }
381       else
382       {
383         if (aj.colour != null)
384         {
385           result = aj.colour;
386         }
387       }
388     }
389     else
390     {
391       result = shadeCalculation(ann, j);
392     }
393
394     return result;
395   }
396
397   /**
398    * Returns a graduated colour for the annotation at the given column. If there
399    * is a threshold value, and it is used as the top/bottom of the colour range,
400    * and the value satisfies the threshold condition, then a colour
401    * proportionate to the range from the threshold is calculated. For all other
402    * cases, a colour proportionate to the annotation's min-max range is
403    * calulated. Note that thresholding is _not_ done here (a colour is computed
404    * even if threshold is not passed).
405    * 
406    * @param ann
407    * @param col
408    * @return
409    */
410   Color shadeCalculation(AlignmentAnnotation ann, int col)
411   {
412     float range = 1f;
413     float value = ann.annotations[col].value;
414     if (thresholdIsMinMax && ann.threshold != null
415             && aboveAnnotationThreshold == ABOVE_THRESHOLD
416             && value >= ann.threshold.value)
417     {
418       range = ann.graphMax == ann.threshold.value ? 1f
419               : (value - ann.threshold.value)
420               / (ann.graphMax - ann.threshold.value);
421     }
422     else if (thresholdIsMinMax && ann.threshold != null
423             && aboveAnnotationThreshold == BELOW_THRESHOLD
424             && value <= ann.threshold.value)
425     {
426       range = ann.graphMin == ann.threshold.value ? 0f
427               : (value - ann.graphMin)
428                       / (ann.threshold.value - ann.graphMin);
429     }
430     else
431     {
432       if (ann.graphMax != ann.graphMin)
433       {
434         range = (value - ann.graphMin) / (ann.graphMax - ann.graphMin);
435       }
436       else
437       {
438         range = 0f;
439       }
440     }
441
442     int dr = (int) (redRange * range + redMin);
443     int dg = (int) (greenRange * range + greenMin);
444     int db = (int) (blueRange * range + blueMin);
445
446     return new Color(dr, dg, db);
447   }
448
449   public boolean isPredefinedColours()
450   {
451     return predefinedColours;
452   }
453
454   public void setPredefinedColours(boolean predefinedColours)
455   {
456     this.predefinedColours = predefinedColours;
457   }
458
459   public boolean isSeqAssociated()
460   {
461     return seqAssociated;
462   }
463
464   public void setSeqAssociated(boolean sassoc)
465   {
466     seqAssociated = sassoc;
467   }
468
469   public boolean isThresholdIsMinMax()
470   {
471     return thresholdIsMinMax;
472   }
473
474   public void setThresholdIsMinMax(boolean minMax)
475   {
476     this.thresholdIsMinMax = minMax;
477   }
478
479   @Override
480   public String getSchemeName()
481   {
482     return ANNOTATION_COLOUR;
483   }
484
485   @Override
486   public boolean isSimple()
487   {
488     return false;
489   }
490 }