JAL-1233 tidy up and use same RNA helix colours in colour by annotation and RNA helix...
[jalview.git] / src / jalview / datamodel / SearchResults.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.datamodel;
22
23 import java.util.ArrayList;
24 import java.util.Arrays;
25 import java.util.List;
26
27 /**
28  * Holds a list of search result matches, where each match is a contiguous
29  * stretch of a single sequence.
30  * 
31  * @author gmcarstairs
32  *
33  */
34 public class SearchResults
35 {
36
37   private List<Match> matches = new ArrayList<Match>();
38
39   /**
40    * One match consists of a sequence reference, start and end positions.
41    * Discontiguous ranges in a sequence require two or more Match objects.
42    */
43   public class Match
44   {
45     SequenceI sequence;
46
47     /**
48      * Start position of match in sequence (base 1)
49      */
50     int start;
51
52     /**
53      * End position (inclusive) (base 1)
54      */
55     int end;
56
57     /**
58      * Constructor
59      * 
60      * @param seq
61      *          a sequence
62      * @param start
63      *          start position of matched range (base 1)
64      * @param end
65      *          end of matched range (inclusive, base 1)
66      */
67     public Match(SequenceI seq, int start, int end)
68     {
69       sequence = seq;
70       this.start = start;
71       this.end = end;
72     }
73
74     public SequenceI getSequence()
75     {
76       return sequence;
77     }
78
79     public int getStart()
80     {
81       return start;
82     }
83
84     public int getEnd()
85     {
86       return end;
87     }
88
89     /**
90      * Returns the string of characters in the matched region, prefixed by the
91      * start position, e.g. "12CGT" or "208K"
92      */
93     @Override
94     public String toString()
95     {
96       final int from = Math.max(start - 1, 0);
97       String startPosition = String.valueOf(from);
98       return startPosition + getCharacters();
99     }
100
101     /**
102      * Returns the string of characters in the matched region.
103      */
104     public String getCharacters()
105     {
106       char[] chars = sequence.getSequence();
107       // convert start/end to base 0 (with bounds check)
108       final int from = Math.max(start - 1, 0);
109       final int to = Math.min(end, chars.length + 1);
110       return String.valueOf(Arrays.copyOfRange(chars, from, to));
111     }
112
113     public void setSequence(SequenceI seq)
114     {
115       this.sequence = seq;
116     }
117
118     /**
119      * Hashcode is the hashcode of the matched sequence plus a hash of start and
120      * end positions. Match objects that pass the test for equals are guaranteed
121      * to have the same hashcode.
122      */
123     @Override
124     public int hashCode()
125     {
126       int hash = sequence == null ? 0 : sequence.hashCode();
127       hash += 31 * start;
128       hash += 67 * end;
129       return hash;
130     }
131
132     /**
133      * Two Match objects are equal if they are for the same sequence, start and
134      * end positions
135      */
136     @Override
137     public boolean equals(Object obj)
138     {
139       if (obj == null || !(obj instanceof Match))
140       {
141         return false;
142       }
143       Match m = (Match) obj;
144       return (this.sequence == m.sequence && this.start == m.start && this.end == m.end);
145     }
146   }
147
148   /**
149    * This method replaces the old search results which merely held an alignment
150    * index of search matches. This broke when sequences were moved around the
151    * alignment
152    * 
153    * @param seq
154    *          Sequence
155    * @param start
156    *          int
157    * @param end
158    *          int
159    */
160   public void addResult(SequenceI seq, int start, int end)
161   {
162     matches.add(new Match(seq, start, end));
163   }
164
165   /**
166    * Quickly check if the given sequence is referred to in the search results
167    * 
168    * @param sequence
169    *          (specific alignment sequence or a dataset sequence)
170    * @return true if the results involve sequence
171    */
172   public boolean involvesSequence(SequenceI sequence)
173   {
174     SequenceI ds = sequence.getDatasetSequence();
175     for (Match m : matches)
176     {
177       if (m.sequence != null
178               && (m.sequence == sequence || m.sequence == ds))
179       {
180         return true;
181       }
182     }
183     return false;
184   }
185
186   /**
187    * This Method returns the search matches which lie between the start and end
188    * points of the sequence in question. It is optimised for returning objects
189    * for drawing on SequenceCanvas
190    */
191   public int[] getResults(SequenceI sequence, int start, int end)
192   {
193     if (matches.isEmpty())
194     {
195       return null;
196     }
197
198     int[] result = null;
199     int[] tmp = null;
200     int resultLength, matchStart = 0, matchEnd = 0;
201     boolean mfound;
202     for (Match m : matches)
203     {
204       mfound = false;
205       if (m.sequence == sequence)
206       {
207         mfound = true;
208         // locate aligned position
209         matchStart = sequence.findIndex(m.start) - 1;
210         matchEnd = sequence.findIndex(m.end) - 1;
211       }
212       else if (m.sequence == sequence.getDatasetSequence())
213       {
214         mfound = true;
215         // locate region in local context
216         matchStart = sequence.findIndex(m.start) - 1;
217         matchEnd = sequence.findIndex(m.end) - 1;
218       }
219       if (mfound)
220       {
221         if (matchStart <= end && matchEnd >= start)
222         {
223           if (matchStart < start)
224           {
225             matchStart = start;
226           }
227
228           if (matchEnd > end)
229           {
230             matchEnd = end;
231           }
232
233           if (result == null)
234           {
235             result = new int[]
236             { matchStart, matchEnd };
237           }
238           else
239           {
240             resultLength = result.length;
241             tmp = new int[resultLength + 2];
242             System.arraycopy(result, 0, tmp, 0, resultLength);
243             result = tmp;
244             result[resultLength] = matchStart;
245             result[resultLength + 1] = matchEnd;
246           }
247         }
248         else
249         {
250           // debug
251           // System.err.println("Outwith bounds!" + matchStart+">"+end +"  or "
252           // + matchEnd+"<"+start);
253         }
254       }
255     }
256     return result;
257   }
258
259   public int getSize()
260   {
261     return matches.size();
262   }
263
264   public SequenceI getResultSequence(int index)
265   {
266     return matches.get(index).sequence;
267   }
268
269   /**
270    * Returns the start position of the i'th match in the search results.
271    * 
272    * @param i
273    * @return
274    */
275   public int getResultStart(int i)
276   {
277     return matches.get(i).start;
278   }
279
280   /**
281    * Returns the end position of the i'th match in the search results.
282    * 
283    * @param i
284    * @return
285    */
286   public int getResultEnd(int i)
287   {
288     return matches.get(i).end;
289   }
290
291   /**
292    * Returns true if no search result matches are held.
293    * 
294    * @return
295    */
296   public boolean isEmpty()
297   {
298     return matches.isEmpty();
299   }
300
301   /**
302    * Returns the list of matches.
303    * 
304    * @return
305    */
306   public List<Match> getResults()
307   {
308     return matches;
309   }
310
311   /**
312    * Return the results as a string of characters (bases) prefixed by start
313    * position(s). Meant for use when the context ensures that all matches are to
314    * regions of the same sequence (otherwise the result is meaningless).
315    * 
316    * @return
317    */
318   @Override
319   public String toString()
320   {
321     StringBuilder result = new StringBuilder(256);
322     for (Match m : matches)
323     {
324       result.append(m.toString());
325     }
326     return result.toString();
327   }
328
329   /**
330    * Return the results as a string of characters (bases). Meant for use when
331    * the context ensures that all matches are to regions of the same sequence
332    * (otherwise the result is meaningless).
333    * 
334    * @return
335    */
336   public String getCharacters()
337   {
338     StringBuilder result = new StringBuilder(256);
339     for (Match m : matches)
340     {
341       result.append(m.getCharacters());
342     }
343     return result.toString();
344   }
345
346   /**
347    * Hashcode is has derived from the list of matches. This ensures that when
348    * two SearchResults objects satisfy the test for equals(), then they have the
349    * same hashcode.
350    */
351   @Override
352   public int hashCode()
353   {
354     return matches.hashCode();
355   }
356
357   /**
358    * Two SearchResults are considered equal if they contain the same matches in
359    * the same order.
360    */
361   @Override
362   public boolean equals(Object obj)
363   {
364     if (obj == null || !(obj instanceof SearchResults))
365     {
366       return false;
367     }
368     SearchResults sr = (SearchResults) obj;
369     return ((ArrayList<Match>) this.matches).equals(sr.matches);
370   }
371 }