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     /*
 239      * get 'base' colour
 240      */
 241     ProfileI profile = consensus == null ? null : consensus.get(position);
 242     String modalResidue = profile == null ? null
 243             : profile.getModalResidue();
 244     float pid = profile == null ? 0f
 245             : profile.getPercentageIdentity(ignoreGaps);
 246     Color colour = colourScheme == null ? Color.white
 247             : colourScheme.findColour(symbol, position, seq, modalResidue,
 248                     pid);
 249
 250     /*
 251      * apply PID threshold and consensus fading if in force
 252      */
 253     colour = adjustColour(symbol, position, colour);
 254
 255     return colour;
 256   }
 257
 258   /**
 259    * Adjusts colour by applying thresholding or conservation shading, if in
 260    * force. That is
 261    * <ul>
 262    * <li>if there is a threshold set for colouring, and the residue doesn't
 263    * match the consensus (or a joint consensus) residue, or the consensus score
 264    * is not above the threshold, then the colour is set to white</li>
 265    * <li>if conservation colouring is selected, the colour is faded by an amount
 266    * depending on the conservation score for the column, and the conservation
 267    * colour threshold</li>
 268    * </ul>
 269    *
 270    * @param symbol
 271    * @param column
 272    * @param colour
 273    * @return
 274    */
 275   protected Color adjustColour(char symbol, int column, Color colour)
 276   {
 277     if (!aboveThreshold(symbol, column))
 278     {
 279       colour = Color.white;
 280     }
 281
 282     if (conservationColouring)
 283     {
 284       colour = applyConservation(colour, column);
 285     }
 286     return colour;
 287   }
 288
 289   /**
 290    * Answers true if there is a consensus profile for the specified column, and
 291    * the given residue matches the consensus (or joint consensus) residue for
 292    * the column, and the percentage identity for the profile is equal to or
 293    * greater than the current threshold; else answers false. The percentage
 294    * calculation depends on whether or not we are ignoring gapped sequences.
 295    *
 296    * @param residue
 297    * @param column
 298    *          (index into consensus profiles)
 299    *
 300    * @return
 301    * @see #setThreshold(int, boolean)
 302    */
 303   protected boolean aboveThreshold(char residue, int column)
 304   {
 305     if (pidThreshold == 0)
 306     {
 307       return true;
 308     }
 309     if ('a' <= residue && residue <= 'z')
 310     {
 311       // TO UPPERCASE !!!
 312       // Faster than toUpperCase
 313       residue -= ('a' - 'A');
 314     }
 315
 316     if (consensus == null)
 317     {
 318       return false;
 319     }
 320
 321     ProfileI profile = consensus.get(column);
 322
 323     /*
 324      * test whether this is the consensus (or joint consensus) residue
 325      */
 326     if (profile != null
 327             && profile.getModalResidue().contains(String.valueOf(residue)))
 328     {
 329       if (profile.getPercentageIdentity(ignoreGaps) >= pidThreshold)
 330       {
 331         return true;
 332       }
 333     }
 334
 335     return false;
 336   }
 337
 338   /**
 339    * Applies a combination of column conservation score, and conservation
 340    * percentage slider, to 'bleach' out the residue colours towards white.
 341    * <p>
 342    * If a column is fully conserved (identical residues, conservation score 11,
 343    * shown as *), or all 10 physico-chemical properties are conserved
 344    * (conservation score 10, shown as +), then the colour is left unchanged.
 345    * <p>
 346    * Otherwise a 'bleaching' factor is computed and applied to the colour. This
 347    * is designed to fade colours for scores of 0-9 completely to white at slider
 348    * positions ranging from 18% - 100% respectively.
 349    *
 350    * @param currentColour
 351    * @param column
 352    *
 353    * @return bleached (or unmodified) colour
 354    */
 355   protected Color applyConservation(Color currentColour, int column)
 356   {
 357     if (conservation == null || conservation.length <= column)
 358     {
 359       return currentColour;
 360     }
 361     char conservationScore = conservation[column];
 362
 363     /*
 364      * if residues are fully conserved (* or 11), or all properties
 365      * are conserved (+ or 10), leave colour unchanged
 366      */
 367     if (conservationScore == '*' || conservationScore == '+'
 368             || conservationScore == (char) 10
 369             || conservationScore == (char) 11)
 370     {
 371       return currentColour;
 372     }
 373
 374     if (Comparison.isGap(conservationScore))
 375     {
 376       return Color.white;
 377     }
 378
 379     /*
 380      * convert score 0-9 to a bleaching factor 1.1 - 0.2
 381      */
 382     float bleachFactor = (11 - (conservationScore - '0')) / 10f;
 383
 384     /*
 385      * scale this up by 0-5 (percentage slider / 20)
 386      * as a result, scores of:         0  1  2  3  4  5  6  7  8  9
 387      * fade to white at slider value: 18 20 22 25 29 33 40 50 67 100%
 388      */
 389     bleachFactor *= (conservationIncrement / 20f);
 390
 391     return ColorUtils.bleachColour(currentColour, bleachFactor);
 392   }
 393
 394   /**
 395    * @see jalview.renderer.ResidueShaderI#getColourScheme()
 396    */
 397   @Override
 398   public ColourSchemeI getColourScheme()
 399   {
 400     return this.colourScheme;
 401   }
 402
 403   /**
 404    * @see jalview.renderer.ResidueShaderI#setColourScheme(jalview.schemes.ColourSchemeI)
 405    */
 406   @Override
 407   public void setColourScheme(ColourSchemeI cs)
 408   {
 409     colourScheme = cs;
 410   }
 411 }