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 }