2 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3 * Copyright (C) $$Year-Rel$$ The Jalview Authors
5 * This file is part of Jalview.
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.
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.
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.
21 package jalview.analysis;
23 import java.util.Locale;
25 import jalview.datamodel.AlignmentAnnotation;
26 import jalview.datamodel.AlignmentI;
27 import jalview.datamodel.SequenceI;
29 import java.util.Arrays;
30 import java.util.Comparator;
31 import java.util.HashMap;
35 * A helper class to sort all annotations associated with an alignment in
41 public class AnnotationSorter
45 * enum for annotation sort options. The text description is used in the
46 * Preferences drop-down options. The enum name is saved in the preferences
52 public enum SequenceAnnotationOrder
54 // Text descriptions surface in the Preferences Sort by... options
55 SEQUENCE_AND_LABEL("Sequence"), LABEL_AND_SEQUENCE("Label"),
58 private String description;
60 private SequenceAnnotationOrder(String s)
66 public String toString()
71 public static SequenceAnnotationOrder forDescription(String d)
73 for (SequenceAnnotationOrder order : values())
75 if (order.toString().equals(d))
84 // the alignment with respect to which annotations are sorted
85 private final AlignmentI alignment;
87 // user preference for placement of non-sequence annotations
88 private boolean showAutocalcAbove;
90 // working map of sequence index in alignment
91 private final Map<SequenceI, Integer> sequenceIndices = new HashMap<SequenceI, Integer>();
94 * Constructor given an alignment and the location (top or bottom) of
95 * Consensus and similar.
98 * @param showAutocalculatedAbove
100 public AnnotationSorter(AlignmentI alignmentI,
101 boolean showAutocalculatedAbove)
103 this.alignment = alignmentI;
104 this.showAutocalcAbove = showAutocalculatedAbove;
108 * Default comparator sorts as follows by annotation type within sequence
111 * <li>annotations with a reference to a sequence in the alignment are sorted
112 * on sequence ordering</li>
113 * <li>other annotations go 'at the end', with their mutual order
115 * <li>within the same sequence ref, sort by label (non-case-sensitive)</li>
118 private final Comparator<? super AlignmentAnnotation> bySequenceAndLabel = new Comparator<AlignmentAnnotation>()
121 public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
123 if (o1 == null && o2 == null)
136 // TODO how to treat sequence-related autocalculated annotation
137 boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
138 boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
140 * Ignore label (keep existing ordering) for
141 * Conservation/Quality/Consensus etc
143 if (o1auto && o2auto)
149 * Sort autocalculated before or after sequence-related.
153 return showAutocalcAbove ? -1 : 1;
157 return showAutocalcAbove ? 1 : -1;
159 int computedOrder = compareSequences(o1, o2);
160 if (computedOrder == 0)
162 computedOrder = compareLabels(o1, o2);
164 if (computedOrder == 0)
166 computedOrder = compareDescriptions(o1, o2);
168 return computedOrder;
172 public String toString()
174 return "Sort by sequence and label";
179 * This comparator sorts as follows by sequence order within annotation type
181 * <li>annotations with a reference to a sequence in the alignment are sorted
182 * on label (non-case-sensitive)</li>
183 * <li>other annotations go 'at the end', with their mutual order
185 * <li>within the same label, sort by order of the related sequences</li>
188 private final Comparator<? super AlignmentAnnotation> byLabelAndSequence = new Comparator<AlignmentAnnotation>()
191 public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
193 if (o1 == null && o2 == null)
206 // TODO how to treat sequence-related autocalculated annotation
207 boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
208 boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
210 * Ignore label (keep existing ordering) for
211 * Conservation/Quality/Consensus etc
213 if (o1auto && o2auto)
219 * Sort autocalculated before or after sequence-related.
223 return showAutocalcAbove ? -1 : 1;
227 return showAutocalcAbove ? 1 : -1;
229 int labelOrder = compareLabels(o1, o2);
230 return labelOrder == 0 ? compareSequences(o1, o2) : labelOrder;
234 public String toString()
236 return "Sort by label and sequence";
241 * noSort leaves sort order unchanged, within sequence- and autocalculated
242 * annotations, but may switch the ordering of these groups. Note this is
243 * guaranteed (at least in Java 7) as Arrays.sort() is guaranteed to be
244 * 'stable' (not change ordering of equal items).
246 private Comparator<? super AlignmentAnnotation> noSort = new Comparator<AlignmentAnnotation>()
249 public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
251 // TODO how to treat sequence-related autocalculated annotation
252 boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
253 boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
254 // TODO skip this test to allow customised ordering of all annotations
255 // - needs a third option: place autocalculated first / last / none
256 if (o1 != null && o2 != null)
258 if (o1auto && !o2auto)
260 return showAutocalcAbove ? -1 : 1;
262 if (!o1auto && o2auto)
264 return showAutocalcAbove ? 1 : -1;
271 public String toString()
278 * Sort by the specified ordering of sequence-specific annotations.
280 * @param alignmentAnnotations
283 public void sort(AlignmentAnnotation[] alignmentAnnotations,
284 SequenceAnnotationOrder order)
286 if (alignmentAnnotations == null)
290 // cache 'alignment sequence position' for the annotations
291 saveSequenceIndices(alignmentAnnotations);
293 Comparator<? super AlignmentAnnotation> comparator = getComparator(
296 if (alignmentAnnotations != null)
298 synchronized (alignmentAnnotations)
300 Arrays.sort(alignmentAnnotations, comparator);
306 * Calculate and save in a temporary map the position of each annotation's
307 * sequence (if it has one) in the alignment. Faster to do this once than for
308 * every annotation comparison.
310 * @param alignmentAnnotations
312 private void saveSequenceIndices(
313 AlignmentAnnotation[] alignmentAnnotations)
315 sequenceIndices.clear();
316 for (AlignmentAnnotation ann : alignmentAnnotations)
318 SequenceI seq = ann.sequenceRef;
321 int index = AlignmentUtils.getSequenceIndex(alignment, seq);
322 sequenceIndices.put(seq, index);
328 * Get the comparator for the specified sort order.
333 private Comparator<? super AlignmentAnnotation> getComparator(
334 SequenceAnnotationOrder order)
344 case SEQUENCE_AND_LABEL:
345 return this.bySequenceAndLabel;
346 case LABEL_AND_SEQUENCE:
347 return this.byLabelAndSequence;
349 throw new UnsupportedOperationException(order.toString());
354 * Non-case-sensitive comparison of annotation labels. Returns zero if either
361 private int compareLabels(AlignmentAnnotation o1, AlignmentAnnotation o2)
363 if (o1 == null || o2 == null)
367 String label1 = o1.label;
368 String label2 = o2.label;
369 return compareString(label1, label2);
373 * Non-case-sensitive comparison of annotation descriptions. Returns zero if
374 * either argument is null.
380 private int compareDescriptions(AlignmentAnnotation o1,
381 AlignmentAnnotation o2)
383 if (o1 == null || o2 == null)
387 String label1 = o1.description;
388 String label2 = o2.description;
389 return compareString(label1, label2);
392 private int compareString(String label1, String label2)
394 if (label1 == null && label2 == null)
406 return label1.toUpperCase(Locale.ROOT)
407 .compareTo(label2.toUpperCase(Locale.ROOT));
411 * Comparison based on position of associated sequence (if any) in the
412 * alignment. Returns zero if either argument is null.
418 private int compareSequences(AlignmentAnnotation o1,
419 AlignmentAnnotation o2)
421 SequenceI seq1 = o1.sequenceRef;
422 SequenceI seq2 = o2.sequenceRef;
423 if (seq1 == null && seq2 == null)
428 * Sort non-sequence-related before or after sequence-related.
432 return showAutocalcAbove ? -1 : 1;
436 return showAutocalcAbove ? 1 : -1;
438 // get sequence index - but note -1 means 'at end' so needs special handling
439 int index1 = sequenceIndices.get(seq1);
440 int index2 = sequenceIndices.get(seq2);
441 if (index1 == index2)
453 return Integer.compare(index1, index2);