2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
5 * This file is part of Jalview.
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.
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.
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.
21 package jalview.renderer;
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;
34 import java.awt.Color;
38 * A class that computes the colouring of an alignment (or subgroup). Currently
39 * the factors that may influence residue colouring are
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
44 * <li>any graduation based on conservation of physico-chemical properties</li>
50 public class ResidueShader implements ResidueShaderI
52 private static final int INITIAL_CONSERVATION = 30;
55 * the colour scheme that gives the colour of each residue
56 * before applying any conservation or PID shading
58 private ColourSchemeI colourScheme;
61 * the consensus data for each column
63 private ProfilesI consensus;
66 * if true, apply shading of colour by conservation
68 private boolean conservationColouring;
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)
75 private char[] conservation;
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
82 private int pidThreshold;
85 * if true, ignore gaps in percentage identity calculation
87 private boolean ignoreGaps;
90 * setting of the By Conservation slider
92 private int conservationIncrement = INITIAL_CONSERVATION;
94 public ResidueShader(ColourSchemeI cs)
100 * Default constructor
102 public ResidueShader()
107 * Constructor given view style settings
111 public ResidueShader(ViewStyleI viewStyle)
113 // TODO remove duplicated storing of conservation / pid thresholds?
115 setConservationApplied(viewStyle.isConservationColourSelected());
116 // setThreshold(viewStyle.getThreshold());
122 public ResidueShader(ResidueShader rs)
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;
134 * @see jalview.renderer.ResidueShaderI#setConsensus(jalview.datamodel.ProfilesI)
137 public void setConsensus(ProfilesI cons)
143 * @see jalview.renderer.ResidueShaderI#conservationApplied()
146 public boolean conservationApplied()
148 return conservationColouring;
152 * @see jalview.renderer.ResidueShaderI#setConservationApplied(boolean)
155 public void setConservationApplied(boolean conservationApplied)
157 conservationColouring = conservationApplied;
161 * @see jalview.renderer.ResidueShaderI#setConservation(jalview.analysis.Conservation)
164 public void setConservation(Conservation cons)
168 conservationColouring = false;
173 conservationColouring = true;
174 conservation = cons.getConsSequence().getSequenceAsString()
181 * @see jalview.renderer.ResidueShaderI#alignmentChanged(jalview.datamodel.AnnotatedCollectionI,
185 public void alignmentChanged(AnnotatedCollectionI alignment,
186 Map<SequenceI, SequenceCollectionI> hiddenReps)
188 if (colourScheme != null)
190 colourScheme.alignmentChanged(alignment, hiddenReps);
195 * @see jalview.renderer.ResidueShaderI#setThreshold(int, boolean)
198 public void setThreshold(int consensusThreshold, boolean ignoreGaps)
200 pidThreshold = consensusThreshold;
201 this.ignoreGaps = ignoreGaps;
205 * @see jalview.renderer.ResidueShaderI#setConservationInc(int)
208 public void setConservationInc(int i)
210 conservationIncrement = i;
214 * @see jalview.renderer.ResidueShaderI#getConservationInc()
217 public int getConservationInc()
219 return conservationIncrement;
223 * @see jalview.renderer.ResidueShaderI#getThreshold()
226 public int getThreshold()
232 * @see jalview.renderer.ResidueShaderI#findColour(char, int,
233 * jalview.datamodel.SequenceI)
236 public Color findColour(char symbol, int position, SequenceI seq)
238 if (colourScheme == null)
240 return Color.white; // Colour is 'None'
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,
255 * apply PID threshold and consensus fading if in force
257 if (!Comparison.isGap(symbol))
259 colour = adjustColour(symbol, position, colour);
266 public int findColourInt(char symbol, int position, SequenceI seq)
268 if (colourScheme == null)
270 return -1;// Color.white; // Colour is 'None'
276 ProfileI profile = consensus == null ? null : consensus.get(position);
277 String modalResidue = profile == null ? null
278 : profile.getModalResidue();
279 float pid = profile == null ? 0f
280 : profile.getPercentageIdentity(ignoreGaps);
281 int colour = colourScheme
282 .findColour(symbol, position, seq, modalResidue, pid).getRGB();
285 * apply PID threshold and consensus fading if in force
287 if (!Comparison.isGap(symbol))
289 colour = adjustColourInt(symbol, position, colour);
296 * Adjusts colour by applying thresholding or conservation shading, if in
299 * <li>if there is a threshold set for colouring, and the residue doesn't
300 * match the consensus (or a joint consensus) residue, or the consensus score
301 * is not above the threshold, then the colour is set to white</li>
302 * <li>if conservation colouring is selected, the colour is faded by an amount
303 * depending on the conservation score for the column, and the conservation
304 * colour threshold</li>
312 protected Color adjustColour(char symbol, int column, Color colour)
314 if (!aboveThreshold(symbol, column))
316 colour = Color.white;
319 if (conservationColouring)
321 colour = applyConservation(colour, column);
326 protected int adjustColourInt(char symbol, int column, int colour)
328 if (!aboveThreshold(symbol, column))
330 colour = -1;// Color.white;
333 if (conservationColouring)
335 colour = applyConservationInt(colour, column);
341 * Answers true if there is a consensus profile for the specified column, and
342 * the given residue matches the consensus (or joint consensus) residue for
343 * the column, and the percentage identity for the profile is equal to or
344 * greater than the current threshold; else answers false. The percentage
345 * calculation depends on whether or not we are ignoring gapped sequences.
349 * (index into consensus profiles)
352 * @see #setThreshold(int, boolean)
354 protected boolean aboveThreshold(char residue, int column)
356 if (pidThreshold == 0)
360 if ('a' <= residue && residue <= 'z')
363 // Faster than toUpperCase
364 residue -= ('a' - 'A');
367 if (consensus == null)
372 ProfileI profile = consensus.get(column);
375 * test whether this is the consensus (or joint consensus) residue
378 && profile.getModalResidue().contains(String.valueOf(residue)))
380 if (profile.getPercentageIdentity(ignoreGaps) >= pidThreshold)
390 * Applies a combination of column conservation score, and conservation
391 * percentage slider, to 'bleach' out the residue colours towards white.
393 * If a column is fully conserved (identical residues, conservation score 11,
394 * shown as *), or all 10 physico-chemical properties are conserved
395 * (conservation score 10, shown as +), then the colour is left unchanged.
397 * Otherwise a 'bleaching' factor is computed and applied to the colour. This
398 * is designed to fade colours for scores of 0-9 completely to white at slider
399 * positions ranging from 18% - 100% respectively.
401 * @param currentColour
404 * @return bleached (or unmodified) colour
406 protected Color applyConservation(Color currentColour, int column)
408 if (conservation == null || conservation.length <= column)
410 return currentColour;
412 char conservationScore = conservation[column];
415 * if residues are fully conserved (* or 11), or all properties
416 * are conserved (+ or 10), leave colour unchanged
418 if (conservationScore == '*' || conservationScore == '+'
419 || conservationScore == (char) 10
420 || conservationScore == (char) 11)
422 return currentColour;
425 if (Comparison.isGap(conservationScore))
431 * convert score 0-9 to a bleaching factor 1.1 - 0.2
433 float bleachFactor = (11 - (conservationScore - '0')) / 10f;
436 * scale this up by 0-5 (percentage slider / 20)
437 * as a result, scores of: 0 1 2 3 4 5 6 7 8 9
438 * fade to white at slider value: 18 20 22 25 29 33 40 50 67 100%
440 bleachFactor *= (conservationIncrement / 20f);
442 return ColorUtils.bleachColour(currentColour, bleachFactor);
445 protected int applyConservationInt(int currentColour, int column)
447 if (conservation == null || conservation.length <= column)
449 return currentColour;
451 char conservationScore = conservation[column];
454 * if residues are fully conserved (* or 11), or all properties
455 * are conserved (+ or 10), leave colour unchanged
457 if (conservationScore == '*' || conservationScore == '+'
458 || conservationScore == (char) 10
459 || conservationScore == (char) 11)
461 return currentColour;
464 if (Comparison.isGap(conservationScore))
466 return -1;// Color.white;
470 * convert score 0-9 to a bleaching factor 1.1 - 0.2
472 float bleachFactor = (11 - (conservationScore - '0')) / 10f;
475 * scale this up by 0-5 (percentage slider / 20)
476 * as a result, scores of: 0 1 2 3 4 5 6 7 8 9
477 * fade to white at slider value: 18 20 22 25 29 33 40 50 67 100%
479 bleachFactor *= (conservationIncrement / 20f);
481 return ColorUtils.bleachColourInt(currentColour, bleachFactor);
485 * @see jalview.renderer.ResidueShaderI#getColourScheme()
488 public ColourSchemeI getColourScheme()
490 return this.colourScheme;
494 * @see jalview.renderer.ResidueShaderI#setColourScheme(jalview.schemes.ColourSchemeI)
497 public void setColourScheme(ColourSchemeI cs)