Merge remote-tracking branch 'origin/tasks/JAL-3035_remove_dasobert_dependency' into...
[jalview.git] / src / jalview / renderer / ResidueShader.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.renderer;
22
23 import jalview.analysis.Conservation;
24 import jalview.api.ViewStyleI;
25 import jalview.datamodel.AnnotatedCollectionI;
26 import jalview.datamodel.ProfileI;
27 import jalview.datamodel.ProfilesI;
28 import jalview.datamodel.SequenceCollectionI;
29 import jalview.datamodel.SequenceI;
30 import jalview.schemes.ColourSchemeI;
31 import jalview.util.ColorUtils;
32 import jalview.util.Comparison;
33
34 import java.awt.Color;
35 import java.util.Map;
36
37 /**
38  * A class that computes the colouring of an alignment (or subgroup). Currently
39  * the factors that may influence residue colouring are
40  * <ul>
41  * <li>the colour scheme that provides a colour for each aligned residue</li>
42  * <li>any threshold for colour, based on percentage identity with
43  * consensus</li>
44  * <li>any graduation based on conservation of physico-chemical properties</li>
45  * </ul>
46  * 
47  * @author gmcarstairs
48  *
49  */
50 public class ResidueShader implements ResidueShaderI
51 {
52   private static final int INITIAL_CONSERVATION = 30;
53
54   /*
55    * the colour scheme that gives the colour of each residue
56    * before applying any conservation or PID shading
57    */
58   private ColourSchemeI colourScheme;
59
60   /*
61    * the consensus data for each column
62    */
63   private ProfilesI consensus;
64
65   /*
66    * if true, apply shading of colour by conservation
67    */
68   private boolean conservationColouring;
69
70   /*
71    * the physico-chemical property conservation scores for columns, with values
72    * 0-9, '+' (all properties conserved), '*' (residue fully conserved) or '-' (gap)
73    * (may be null if colour by conservation is not selected)
74    */
75   private char[] conservation;
76
77   /*
78    * minimum percentage identity for colour to be applied;
79    * if above zero, residue must match consensus (or joint consensus)
80    * and column have >= pidThreshold identity with the residue
81    */
82   private int pidThreshold;
83
84   /*
85    * if true, ignore gaps in percentage identity calculation
86    */
87   private boolean ignoreGaps;
88
89   /*
90    * setting of the By Conservation slider
91    */
92   private int conservationIncrement = INITIAL_CONSERVATION;
93
94   public ResidueShader(ColourSchemeI cs)
95   {
96     colourScheme = cs;
97   }
98
99   /**
100    * Default constructor
101    */
102   public ResidueShader()
103   {
104   }
105
106   /**
107    * Constructor given view style settings
108    * 
109    * @param viewStyle
110    */
111   public ResidueShader(ViewStyleI viewStyle)
112   {
113     // TODO remove duplicated storing of conservation / pid thresholds?
114     this();
115     setConservationApplied(viewStyle.isConservationColourSelected());
116     // setThreshold(viewStyle.getThreshold());
117   }
118
119   /**
120    * Copy constructor
121    */
122   public ResidueShader(ResidueShader rs)
123   {
124     this.colourScheme = rs.colourScheme;
125     this.consensus = rs.consensus;
126     this.conservation = rs.conservation;
127     this.conservationColouring = rs.conservationColouring;
128     this.conservationIncrement = rs.conservationIncrement;
129     this.ignoreGaps = rs.ignoreGaps;
130     this.pidThreshold = rs.pidThreshold;
131   }
132
133   /**
134    * @see jalview.renderer.ResidueShaderI#setConsensus(jalview.datamodel.ProfilesI)
135    */
136   @Override
137   public void setConsensus(ProfilesI cons)
138   {
139     consensus = cons;
140   }
141
142   /**
143    * @see jalview.renderer.ResidueShaderI#conservationApplied()
144    */
145   @Override
146   public boolean conservationApplied()
147   {
148     return conservationColouring;
149   }
150
151   /**
152    * @see jalview.renderer.ResidueShaderI#setConservationApplied(boolean)
153    */
154   @Override
155   public void setConservationApplied(boolean conservationApplied)
156   {
157     conservationColouring = conservationApplied;
158   }
159
160   /**
161    * @see jalview.renderer.ResidueShaderI#setConservation(jalview.analysis.Conservation)
162    */
163   @Override
164   public void setConservation(Conservation cons)
165   {
166     if (cons == null)
167     {
168       conservationColouring = false;
169       conservation = null;
170     }
171     else
172     {
173       conservationColouring = true;
174       conservation = cons.getConsSequence().getSequenceAsString()
175               .toCharArray();
176     }
177
178   }
179
180   /**
181    * @see jalview.renderer.ResidueShaderI#alignmentChanged(jalview.datamodel.AnnotatedCollectionI,
182    *      java.util.Map)
183    */
184   @Override
185   public void alignmentChanged(AnnotatedCollectionI alignment,
186           Map<SequenceI, SequenceCollectionI> hiddenReps)
187   {
188     if (colourScheme != null)
189     {
190       colourScheme.alignmentChanged(alignment, hiddenReps);
191     }
192   }
193
194   /**
195    * @see jalview.renderer.ResidueShaderI#setThreshold(int, boolean)
196    */
197   @Override
198   public void setThreshold(int consensusThreshold, boolean ignoreGaps)
199   {
200     pidThreshold = consensusThreshold;
201     this.ignoreGaps = ignoreGaps;
202   }
203
204   /**
205    * @see jalview.renderer.ResidueShaderI#setConservationInc(int)
206    */
207   @Override
208   public void setConservationInc(int i)
209   {
210     conservationIncrement = i;
211   }
212
213   /**
214    * @see jalview.renderer.ResidueShaderI#getConservationInc()
215    */
216   @Override
217   public int getConservationInc()
218   {
219     return conservationIncrement;
220   }
221
222   /**
223    * @see jalview.renderer.ResidueShaderI#getThreshold()
224    */
225   @Override
226   public int getThreshold()
227   {
228     return pidThreshold;
229   }
230
231   /**
232    * @see jalview.renderer.ResidueShaderI#findColour(char, int,
233    *      jalview.datamodel.SequenceI)
234    */
235   @Override
236   public Color findColour(char symbol, int position, SequenceI seq)
237   {
238     if (colourScheme == null)
239     {
240       return Color.white; // Colour is 'None'
241     }
242
243     /*
244      * get 'base' colour
245      */
246     ProfileI profile = consensus == null ? null : consensus.get(position);
247     String modalResidue = profile == null ? null
248             : profile.getModalResidue();
249     float pid = profile == null ? 0f
250             : profile.getPercentageIdentity(ignoreGaps);
251     Color colour = colourScheme.findColour(symbol, position, seq,
252             modalResidue, pid);
253
254     /*
255      * apply PID threshold and consensus fading if in force
256      */
257     if (!Comparison.isGap(symbol))
258     {
259       colour = adjustColour(symbol, position, colour);
260     }
261
262     return colour;
263   }
264
265   /**
266    * Adjusts colour by applying thresholding or conservation shading, if in
267    * force. That is
268    * <ul>
269    * <li>if there is a threshold set for colouring, and the residue doesn't
270    * match the consensus (or a joint consensus) residue, or the consensus score
271    * is not above the threshold, then the colour is set to white</li>
272    * <li>if conservation colouring is selected, the colour is faded by an amount
273    * depending on the conservation score for the column, and the conservation
274    * colour threshold</li>
275    * </ul>
276    * 
277    * @param symbol
278    * @param column
279    * @param colour
280    * @return
281    */
282   protected Color adjustColour(char symbol, int column, Color colour)
283   {
284     if (!aboveThreshold(symbol, column))
285     {
286       colour = Color.white;
287     }
288
289     if (conservationColouring)
290     {
291       colour = applyConservation(colour, column);
292     }
293     return colour;
294   }
295
296   /**
297    * Answers true if there is a consensus profile for the specified column, and
298    * the given residue matches the consensus (or joint consensus) residue for
299    * the column, and the percentage identity for the profile is equal to or
300    * greater than the current threshold; else answers false. The percentage
301    * calculation depends on whether or not we are ignoring gapped sequences.
302    * 
303    * @param residue
304    * @param column
305    *          (index into consensus profiles)
306    * 
307    * @return
308    * @see #setThreshold(int, boolean)
309    */
310   protected boolean aboveThreshold(char residue, int column)
311   {
312     if (pidThreshold == 0)
313     {
314       return true;
315     }
316     if ('a' <= residue && residue <= 'z')
317     {
318       // TO UPPERCASE !!!
319       // Faster than toUpperCase
320       residue -= ('a' - 'A');
321     }
322
323     if (consensus == null)
324     {
325       return false;
326     }
327
328     ProfileI profile = consensus.get(column);
329
330     /*
331      * test whether this is the consensus (or joint consensus) residue
332      */
333     if (profile != null
334             && profile.getModalResidue().contains(String.valueOf(residue)))
335     {
336       if (profile.getPercentageIdentity(ignoreGaps) >= pidThreshold)
337       {
338         return true;
339       }
340     }
341
342     return false;
343   }
344
345   /**
346    * Applies a combination of column conservation score, and conservation
347    * percentage slider, to 'bleach' out the residue colours towards white.
348    * <p>
349    * If a column is fully conserved (identical residues, conservation score 11,
350    * shown as *), or all 10 physico-chemical properties are conserved
351    * (conservation score 10, shown as +), then the colour is left unchanged.
352    * <p>
353    * Otherwise a 'bleaching' factor is computed and applied to the colour. This
354    * is designed to fade colours for scores of 0-9 completely to white at slider
355    * positions ranging from 18% - 100% respectively.
356    * 
357    * @param currentColour
358    * @param column
359    * 
360    * @return bleached (or unmodified) colour
361    */
362   protected Color applyConservation(Color currentColour, int column)
363   {
364     if (conservation == null || conservation.length <= column)
365     {
366       return currentColour;
367     }
368     char conservationScore = conservation[column];
369
370     /*
371      * if residues are fully conserved (* or 11), or all properties
372      * are conserved (+ or 10), leave colour unchanged
373      */
374     if (conservationScore == '*' || conservationScore == '+'
375             || conservationScore == (char) 10
376             || conservationScore == (char) 11)
377     {
378       return currentColour;
379     }
380
381     if (Comparison.isGap(conservationScore))
382     {
383       return Color.white;
384     }
385
386     /*
387      * convert score 0-9 to a bleaching factor 1.1 - 0.2
388      */
389     float bleachFactor = (11 - (conservationScore - '0')) / 10f;
390
391     /*
392      * scale this up by 0-5 (percentage slider / 20)
393      * as a result, scores of:         0  1  2  3  4  5  6  7  8  9
394      * fade to white at slider value: 18 20 22 25 29 33 40 50 67 100%
395      */
396     bleachFactor *= (conservationIncrement / 20f);
397
398     return ColorUtils.bleachColour(currentColour, bleachFactor);
399   }
400
401   /**
402    * @see jalview.renderer.ResidueShaderI#getColourScheme()
403    */
404   @Override
405   public ColourSchemeI getColourScheme()
406   {
407     return this.colourScheme;
408   }
409
410   /**
411    * @see jalview.renderer.ResidueShaderI#setColourScheme(jalview.schemes.ColourSchemeI)
412    */
413   @Override
414   public void setColourScheme(ColourSchemeI cs)
415   {
416     colourScheme = cs;
417   }
418 }