Merge remote-tracking branch 'origin/tasks/JAL-3035_remove_dasobert_dependency' into...
[jalview.git] / src / jalview / analysis / AnnotationSorter.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.analysis;
22
23 import jalview.datamodel.AlignmentAnnotation;
24 import jalview.datamodel.AlignmentI;
25 import jalview.datamodel.SequenceI;
26
27 import java.util.Arrays;
28 import java.util.Comparator;
29 import java.util.HashMap;
30 import java.util.Map;
31
32 /**
33  * A helper class to sort all annotations associated with an alignment in
34  * various ways.
35  * 
36  * @author gmcarstairs
37  *
38  */
39 public class AnnotationSorter
40 {
41
42   /**
43    * enum for annotation sort options. The text description is used in the
44    * Preferences drop-down options. The enum name is saved in the preferences
45    * file.
46    * 
47    * @author gmcarstairs
48    *
49    */
50   public enum SequenceAnnotationOrder
51   {
52     // Text descriptions surface in the Preferences Sort by... options
53     SEQUENCE_AND_LABEL("Sequence"), LABEL_AND_SEQUENCE("Label"),
54     NONE("No sort");
55
56     private String description;
57
58     private SequenceAnnotationOrder(String s)
59     {
60       description = s;
61     }
62
63     @Override
64     public String toString()
65     {
66       return description;
67     }
68
69     public static SequenceAnnotationOrder forDescription(String d)
70     {
71       for (SequenceAnnotationOrder order : values())
72       {
73         if (order.toString().equals(d))
74         {
75           return order;
76         }
77       }
78       return null;
79     }
80   }
81
82   // the alignment with respect to which annotations are sorted
83   private final AlignmentI alignment;
84
85   // user preference for placement of non-sequence annotations
86   private boolean showAutocalcAbove;
87
88   // working map of sequence index in alignment
89   private final Map<SequenceI, Integer> sequenceIndices = new HashMap<SequenceI, Integer>();
90
91   /**
92    * Constructor given an alignment and the location (top or bottom) of
93    * Consensus and similar.
94    * 
95    * @param alignmentI
96    * @param showAutocalculatedAbove
97    */
98   public AnnotationSorter(AlignmentI alignmentI,
99           boolean showAutocalculatedAbove)
100   {
101     this.alignment = alignmentI;
102     this.showAutocalcAbove = showAutocalculatedAbove;
103   }
104
105   /**
106    * Default comparator sorts as follows by annotation type within sequence
107    * order:
108    * <ul>
109    * <li>annotations with a reference to a sequence in the alignment are sorted
110    * on sequence ordering</li>
111    * <li>other annotations go 'at the end', with their mutual order
112    * unchanged</li>
113    * <li>within the same sequence ref, sort by label (non-case-sensitive)</li>
114    * </ul>
115    */
116   private final Comparator<? super AlignmentAnnotation> bySequenceAndLabel = new Comparator<AlignmentAnnotation>()
117   {
118     @Override
119     public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
120     {
121       if (o1 == null && o2 == null)
122       {
123         return 0;
124       }
125       if (o1 == null)
126       {
127         return -1;
128       }
129       if (o2 == null)
130       {
131         return 1;
132       }
133
134       // TODO how to treat sequence-related autocalculated annotation
135       boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
136       boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
137       /*
138        * Ignore label (keep existing ordering) for
139        * Conservation/Quality/Consensus etc
140        */
141       if (o1auto && o2auto)
142       {
143         return 0;
144       }
145
146       /*
147        * Sort autocalculated before or after sequence-related.
148        */
149       if (o1auto)
150       {
151         return showAutocalcAbove ? -1 : 1;
152       }
153       if (o2auto)
154       {
155         return showAutocalcAbove ? 1 : -1;
156       }
157       int sequenceOrder = compareSequences(o1, o2);
158       return sequenceOrder == 0 ? compareLabels(o1, o2) : sequenceOrder;
159     }
160
161     @Override
162     public String toString()
163     {
164       return "Sort by sequence and label";
165     }
166   };
167
168   /**
169    * This comparator sorts as follows by sequence order within annotation type
170    * <ul>
171    * <li>annotations with a reference to a sequence in the alignment are sorted
172    * on label (non-case-sensitive)</li>
173    * <li>other annotations go 'at the end', with their mutual order
174    * unchanged</li>
175    * <li>within the same label, sort by order of the related sequences</li>
176    * </ul>
177    */
178   private final Comparator<? super AlignmentAnnotation> byLabelAndSequence = new Comparator<AlignmentAnnotation>()
179   {
180     @Override
181     public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
182     {
183       if (o1 == null && o2 == null)
184       {
185         return 0;
186       }
187       if (o1 == null)
188       {
189         return -1;
190       }
191       if (o2 == null)
192       {
193         return 1;
194       }
195
196       // TODO how to treat sequence-related autocalculated annotation
197       boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
198       boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
199       /*
200        * Ignore label (keep existing ordering) for
201        * Conservation/Quality/Consensus etc
202        */
203       if (o1auto && o2auto)
204       {
205         return 0;
206       }
207
208       /*
209        * Sort autocalculated before or after sequence-related.
210        */
211       if (o1auto)
212       {
213         return showAutocalcAbove ? -1 : 1;
214       }
215       if (o2auto)
216       {
217         return showAutocalcAbove ? 1 : -1;
218       }
219       int labelOrder = compareLabels(o1, o2);
220       return labelOrder == 0 ? compareSequences(o1, o2) : labelOrder;
221     }
222
223     @Override
224     public String toString()
225     {
226       return "Sort by label and sequence";
227     }
228   };
229
230   /**
231    * noSort leaves sort order unchanged, within sequence- and autocalculated
232    * annotations, but may switch the ordering of these groups. Note this is
233    * guaranteed (at least in Java 7) as Arrays.sort() is guaranteed to be
234    * 'stable' (not change ordering of equal items).
235    */
236   private Comparator<? super AlignmentAnnotation> noSort = new Comparator<AlignmentAnnotation>()
237   {
238     @Override
239     public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
240     {
241       // TODO how to treat sequence-related autocalculated annotation
242       boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
243       boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
244       // TODO skip this test to allow customised ordering of all annotations
245       // - needs a third option: place autocalculated first / last / none
246       if (o1 != null && o2 != null)
247       {
248         if (o1auto && !o2auto)
249         {
250           return showAutocalcAbove ? -1 : 1;
251         }
252         if (!o1auto && o2auto)
253         {
254           return showAutocalcAbove ? 1 : -1;
255         }
256       }
257       return 0;
258     }
259
260     @Override
261     public String toString()
262     {
263       return "No sort";
264     }
265   };
266
267   /**
268    * Sort by the specified ordering of sequence-specific annotations.
269    * 
270    * @param alignmentAnnotations
271    * @param order
272    */
273   public void sort(AlignmentAnnotation[] alignmentAnnotations,
274           SequenceAnnotationOrder order)
275   {
276     if (alignmentAnnotations == null)
277     {
278       return;
279     }
280     // cache 'alignment sequence position' for the annotations
281     saveSequenceIndices(alignmentAnnotations);
282
283     Comparator<? super AlignmentAnnotation> comparator = getComparator(
284             order);
285
286     if (alignmentAnnotations != null)
287     {
288       synchronized (alignmentAnnotations)
289       {
290         Arrays.sort(alignmentAnnotations, comparator);
291       }
292     }
293   }
294
295   /**
296    * Calculate and save in a temporary map the position of each annotation's
297    * sequence (if it has one) in the alignment. Faster to do this once than for
298    * every annotation comparison.
299    * 
300    * @param alignmentAnnotations
301    */
302   private void saveSequenceIndices(
303           AlignmentAnnotation[] alignmentAnnotations)
304   {
305     sequenceIndices.clear();
306     for (AlignmentAnnotation ann : alignmentAnnotations)
307     {
308       SequenceI seq = ann.sequenceRef;
309       if (seq != null)
310       {
311         int index = AlignmentUtils.getSequenceIndex(alignment, seq);
312         sequenceIndices.put(seq, index);
313       }
314     }
315   }
316
317   /**
318    * Get the comparator for the specified sort order.
319    * 
320    * @param order
321    * @return
322    */
323   private Comparator<? super AlignmentAnnotation> getComparator(
324           SequenceAnnotationOrder order)
325   {
326     if (order == null)
327     {
328       return noSort;
329     }
330     switch (order)
331     {
332     case NONE:
333       return this.noSort;
334     case SEQUENCE_AND_LABEL:
335       return this.bySequenceAndLabel;
336     case LABEL_AND_SEQUENCE:
337       return this.byLabelAndSequence;
338     default:
339       throw new UnsupportedOperationException(order.toString());
340     }
341   }
342
343   /**
344    * Non-case-sensitive comparison of annotation labels. Returns zero if either
345    * argument is null.
346    * 
347    * @param o1
348    * @param o2
349    * @return
350    */
351   private int compareLabels(AlignmentAnnotation o1, AlignmentAnnotation o2)
352   {
353     if (o1 == null || o2 == null)
354     {
355       return 0;
356     }
357     String label1 = o1.label;
358     String label2 = o2.label;
359     if (label1 == null && label2 == null)
360     {
361       return 0;
362     }
363     if (label1 == null)
364     {
365       return -1;
366     }
367     if (label2 == null)
368     {
369       return 1;
370     }
371     return label1.toUpperCase().compareTo(label2.toUpperCase());
372   }
373
374   /**
375    * Comparison based on position of associated sequence (if any) in the
376    * alignment. Returns zero if either argument is null.
377    * 
378    * @param o1
379    * @param o2
380    * @return
381    */
382   private int compareSequences(AlignmentAnnotation o1,
383           AlignmentAnnotation o2)
384   {
385     SequenceI seq1 = o1.sequenceRef;
386     SequenceI seq2 = o2.sequenceRef;
387     if (seq1 == null && seq2 == null)
388     {
389       return 0;
390     }
391     /*
392      * Sort non-sequence-related before or after sequence-related.
393      */
394     if (seq1 == null)
395     {
396       return showAutocalcAbove ? -1 : 1;
397     }
398     if (seq2 == null)
399     {
400       return showAutocalcAbove ? 1 : -1;
401     }
402     // get sequence index - but note -1 means 'at end' so needs special handling
403     int index1 = sequenceIndices.get(seq1);
404     int index2 = sequenceIndices.get(seq2);
405     if (index1 == index2)
406     {
407       return 0;
408     }
409     if (index1 == -1)
410     {
411       return -1;
412     }
413     if (index2 == -1)
414     {
415       return 1;
416     }
417     return Integer.compare(index1, index2);
418   }
419 }