JAL-3676 Documentation in Help for Java Console, Logging and Reporting Bugs
[jalview.git] / src / jalview / schemes / ResidueColourScheme.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.datamodel.AnnotatedCollectionI;
24 import jalview.datamodel.SequenceCollectionI;
25 import jalview.datamodel.SequenceGroup;
26 import jalview.datamodel.SequenceI;
27
28 import java.awt.Color;
29 import java.util.Map;
30
31 /**
32  * Base class for residue-based colour schemes
33  */
34 public abstract class ResidueColourScheme implements ColourSchemeI
35 {
36   public static final String NONE = "None";
37
38   /*
39    * default display name for a user defined colour scheme
40    */
41   public static final String USER_DEFINED = "User Defined";
42
43   /*
44    * name for (new) "User Defined.." colour scheme menu item
45    */
46   public static final String USER_DEFINED_MENU = "*User Defined*";
47
48   /*
49    * the canonical name of the annotation colour scheme 
50    * (may be used to identify it in menu items)
51    */
52   public static final String ANNOTATION_COLOUR = "Annotation";
53
54   /*
55    * lookup up by character value e.g. 'G' to the colors array index
56    * e.g. if symbolIndex['K'] = 11 then colors[11] is the colour for K
57    */
58   final int[] symbolIndex;
59
60   /*
61    * colour for residue characters as indexed by symbolIndex
62    */
63   Color[] colors = null;
64
65   /* Set when threshold colouring to either pid_gaps or pid_nogaps */
66   protected boolean ignoreGaps = false;
67
68   /**
69    * Creates a new ResidueColourScheme object.
70    * 
71    * @param final
72    *          int[] index table into colors (ResidueProperties.naIndex or
73    *          ResidueProperties.aaIndex)
74    * @param colors
75    *          colours for symbols in sequences
76    */
77   public ResidueColourScheme(int[] aaOrnaIndex, Color[] colours)
78   {
79     symbolIndex = aaOrnaIndex;
80     this.colors = colours;
81   }
82
83   /**
84    * Creates a new ResidueColourScheme object with a lookup table for indexing
85    * the colour map
86    */
87   public ResidueColourScheme(int[] aaOrNaIndex)
88   {
89     symbolIndex = aaOrNaIndex;
90   }
91
92   /**
93    * Creates a new ResidueColourScheme object - default constructor for
94    * non-sequence dependent colourschemes
95    */
96   public ResidueColourScheme()
97   {
98     symbolIndex = null;
99   }
100
101   /**
102    * Find a colour without an index in a sequence
103    */
104   public Color findColour(char c)
105   {
106     Color colour = Color.white;
107
108     if (colors != null && symbolIndex != null && c < symbolIndex.length
109             && symbolIndex[c] < colors.length)
110     {
111       colour = colors[symbolIndex[c]];
112     }
113
114     return colour;
115   }
116
117   /**
118    * Default is to call the overloaded method that ignores consensus. A colour
119    * scheme that depends on consensus (for example, Blosum62), should override
120    * this method instead.
121    */
122   @Override
123   public Color findColour(char c, int j, SequenceI seq,
124           String consensusResidue, float pid)
125   {
126     return findColour(c, j, seq);
127   }
128
129   /**
130    * Default implementation looks up the residue colour in a fixed scheme, or
131    * returns White if not found. Override this method for a colour scheme that
132    * depends on the column position or sequence.
133    * 
134    * @param c
135    * @param j
136    * @param seq
137    * @return
138    */
139   protected Color findColour(char c, int j, SequenceI seq)
140   {
141     return findColour(c);
142   }
143
144   @Override
145   public void alignmentChanged(AnnotatedCollectionI alignment,
146           Map<SequenceI, SequenceCollectionI> hiddenReps)
147   {
148   }
149
150   /**
151    * Answers false if the colour scheme is nucleotide or peptide specific, and
152    * the data does not match, else true. Override to modify or extend this test
153    * as required.
154    */
155   @Override
156   public boolean isApplicableTo(AnnotatedCollectionI ac)
157   {
158     if (!isPeptideSpecific() && !isNucleotideSpecific())
159     {
160       return true;
161     }
162     if (ac == null)
163     {
164       return true;
165     }
166     /*
167      * pop-up menu on selection group before group created
168      * (no alignment context)
169      */
170     // TODO: add nucleotide flag to SequenceGroup?
171     if (ac instanceof SequenceGroup && ac.getContext() == null)
172     {
173       return true;
174     }
175
176     /*
177      * inspect the data context (alignment) for residue type
178      */
179     boolean nucleotide = ac.isNucleotide();
180
181     /*
182      * does data type match colour scheme type?
183      */
184     return (nucleotide && isNucleotideSpecific())
185             || (!nucleotide && isPeptideSpecific());
186   }
187
188   /**
189    * Answers true if the colour scheme is normally only for peptide data
190    * 
191    * @return
192    */
193   public boolean isPeptideSpecific()
194   {
195     return false;
196   }
197
198   /**
199    * Answers true if the colour scheme is normally only for nucleotide data
200    * 
201    * @return
202    */
203   public boolean isNucleotideSpecific()
204   {
205     return false;
206   }
207
208   /**
209    * Default method returns true. Override this to return false in colour
210    * schemes that are not determined solely by the sequence symbol.
211    */
212   @Override
213   public boolean isSimple()
214   {
215     return true;
216   }
217
218   /**
219    * Default method returns false. Override this to return true in colour
220    * schemes that have a colour associated with gap residues.
221    */
222   @Override
223   public boolean hasGapColour()
224   {
225     return false;
226   }
227 }