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