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