/*
* Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
* Copyright (C) $$Year-Rel$$ The Jalview Authors
*
* This file is part of Jalview.
*
* Jalview is free software: you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation, either version 3
* of the License, or (at your option) any later version.
*
* Jalview is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE. See the GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with Jalview. If not, see .
* The Jalview Authors are detailed in the 'AUTHORS' file.
*/
package jalview.analysis;
import jalview.api.AlignViewportI;
import jalview.datamodel.AlignmentAnnotation;
import jalview.datamodel.AlignmentI;
import jalview.datamodel.SequenceI;
import java.util.Arrays;
import java.util.Comparator;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
/**
* A helper class to sort all annotations associated with an alignment in
* various ways.
*
* @author gmcarstairs
*
*/
public class AnnotationSorter
{
/**
* A special comparator for use when reloading from project, that supports
* reordering annotations to match their order in the project. It incorporates
* special handling of autocalculated annotations, that are recreated on load:
*
* - these are matched based on autocalc flag and label ("Consensus") etc
* rather than object identity
* - on successful match, visibility and height settings are applied from
* those saved in the project
*
*/
private final class ReloadComparator
implements Comparator
{
private List order;
ReloadComparator(List theOrder)
{
order = theOrder;
}
@Override
public int compare(AlignmentAnnotation o1,
AlignmentAnnotation o2)
{
int i1 = findPosition(o1);
int i2 = findPosition(o2);
return Integer.compare(i1, i2);
}
/**
* A helper method that returns the position of the annotation in the
* {@code order} list, by object identity, or failing that, by matched
* autocalc label ("Consensus" etc). Returns -1 if not found. This can
* happen if, for example, Consensus was saved but since turned off in
* Preferences.
*
* @param aa
* @return
*/
private int findPosition(AlignmentAnnotation aa)
{
int i = order.indexOf(aa);
if (i == -1 && aa.autoCalculated && aa.label != null)
{
for (int j = 0; j < order.size(); j++)
{
AlignmentAnnotation ann = order.get(j);
if (aa.label.equals(ann.label))
{
i = j;
aa.visible = ann.visible;
if (ann.graphHeight >= 0)
{
aa.graphHeight = ann.graphHeight;
}
break;
}
}
}
return i;
}
}
/**
* enum for annotation sort options. The text description is used in the
* Preferences drop-down options. The enum name is saved in the preferences
* file.
*
* @author gmcarstairs
*
*/
public enum SequenceAnnotationOrder
{
// Text descriptions surface in the Preferences Sort by... options
SEQUENCE_AND_LABEL("Sequence"), LABEL_AND_SEQUENCE("Label"),
NONE("No sort"),
/**
* custom is set if user drags to reorder annotations
*/
CUSTOM("Customised");
private String description;
private SequenceAnnotationOrder(String s)
{
description = s;
}
@Override
public String toString()
{
return description;
}
public static SequenceAnnotationOrder forDescription(String d)
{
for (SequenceAnnotationOrder order : values())
{
if (order.toString().equals(d))
{
return order;
}
}
return null;
}
}
/*
* the alignment with respect to which annotations are sorted
*/
private final AlignmentI alignment;
/*
* if true, autocalculated are sorted first, if false, last
*/
private boolean showAutocalcAbove;
/*
* working map of sequence index in alignment
*/
private final Map sequenceIndices = new HashMap<>();
/*
* if true, sort only repositions auto-calculated annotation (to top or bottom)
*/
private boolean autocalcOnly;
/**
* Constructor
*
* @param av
*/
public AnnotationSorter(AlignViewportI av)
{
this.alignment = av.getAlignment();
this.showAutocalcAbove = av.isShowAutocalculatedAbove();
}
/**
* Default comparator sorts as follows by annotation type within sequence
* order:
*
* - annotations with a reference to a sequence in the alignment are sorted
* on sequence ordering
* - other annotations go 'at the end', with their mutual order
* unchanged
* - within the same sequence ref, sort by label (non-case-sensitive)
*
*/
private final Comparator super AlignmentAnnotation> bySequenceAndLabel = new Comparator()
{
@Override
public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
{
if (o1 == null && o2 == null)
{
return 0;
}
if (o1 == null)
{
return -1;
}
if (o2 == null)
{
return 1;
}
// TODO how to treat sequence-related autocalculated annotation
boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
/*
* Ignore label (keep existing ordering) for
* Conservation/Quality/Consensus etc
*/
if (o1auto && o2auto)
{
return 0;
}
/*
* Sort autocalculated before or after sequence-related.
*/
if (o1auto)
{
return showAutocalcAbove ? -1 : 1;
}
if (o2auto)
{
return showAutocalcAbove ? 1 : -1;
}
if (autocalcOnly)
{
return 0; // don't reorder other annotations
}
int sequenceOrder = compareSequences(o1, o2);
return sequenceOrder == 0 ? compareLabels(o1, o2) : sequenceOrder;
}
@Override
public String toString()
{
return "Sort by sequence and label";
}
};
/**
* This comparator sorts as follows by sequence order within annotation type
*
* - annotations with a reference to a sequence in the alignment are sorted
* on label (non-case-sensitive)
* - other annotations go 'at the end', with their mutual order
* unchanged
* - within the same label, sort by order of the related sequences
*
*/
private final Comparator super AlignmentAnnotation> byLabelAndSequence = new Comparator()
{
@Override
public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
{
if (o1 == null && o2 == null)
{
return 0;
}
if (o1 == null)
{
return -1;
}
if (o2 == null)
{
return 1;
}
// TODO how to treat sequence-related autocalculated annotation
boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
/*
* Ignore label (keep existing ordering) for
* Conservation/Quality/Consensus etc
*/
if (o1auto && o2auto)
{
return 0;
}
/*
* Sort autocalculated before or after sequence-related.
*/
if (o1auto)
{
return showAutocalcAbove ? -1 : 1;
}
if (o2auto)
{
return showAutocalcAbove ? 1 : -1;
}
if (autocalcOnly)
{
return 0; // don't reorder other annotations
}
int labelOrder = compareLabels(o1, o2);
return labelOrder == 0 ? compareSequences(o1, o2) : labelOrder;
}
@Override
public String toString()
{
return "Sort by label and sequence";
}
};
/**
* noSort leaves sort order unchanged, within sequence- and autocalculated
* annotations, but may switch the ordering of these groups. Note this is
* guaranteed (at least in Java 7) as Arrays.sort() is guaranteed to be
* 'stable' (not change ordering of equal items).
*/
private Comparator super AlignmentAnnotation> noSort = new Comparator()
{
@Override
public int compare(AlignmentAnnotation o1, AlignmentAnnotation o2)
{
// TODO how to treat sequence-related autocalculated annotation
boolean o1auto = o1.autoCalculated && o1.sequenceRef == null;
boolean o2auto = o2.autoCalculated && o2.sequenceRef == null;
// TODO skip this test to allow customised ordering of all annotations
// - needs a third option: place autocalculated first / last / none
if (o1 != null && o2 != null)
{
if (o1auto && !o2auto)
{
return showAutocalcAbove ? -1 : 1;
}
if (!o1auto && o2auto)
{
return showAutocalcAbove ? 1 : -1;
}
}
return 0;
}
@Override
public String toString()
{
return "No sort";
}
};
/**
* Sorts by the specified ordering. If order is {@code CUSTOM}, meaning
* annotations have been manually ordered by the user, no sort is performed.
*
* @param sortBy
* the sort order to apply
* @param autoCalcOnly
* if true, only autocalculated annotations are repositioned (to top
* or bottom), others are left in their current order
*/
public void sort(SequenceAnnotationOrder sortBy, boolean autoCalcOnly)
{
if (sortBy == null || sortBy == SequenceAnnotationOrder.CUSTOM)
{
return;
}
this.autocalcOnly = autoCalcOnly;
/*
* cache 'alignment sequence positions' if required for sorting
*/
if (sortBy == SequenceAnnotationOrder.SEQUENCE_AND_LABEL
|| sortBy == SequenceAnnotationOrder.LABEL_AND_SEQUENCE)
{
saveSequenceIndices();
}
Comparator super AlignmentAnnotation> comparator = getComparator(
sortBy);
AlignmentAnnotation[] annotations = alignment.getAlignmentAnnotation();
synchronized (annotations)
{
Arrays.sort(annotations, comparator);
}
}
/**
* Calculates and saves in a temporary map the position of each annotation's
* associated sequence (if it has one) in the alignment. Faster to do this
* once than for every annotation comparison.
*/
private void saveSequenceIndices()
{
sequenceIndices.clear();
Map seqPositions = alignment.getSequencePositions();
AlignmentAnnotation[] alignmentAnnotations = alignment
.getAlignmentAnnotation();
for (AlignmentAnnotation ann : alignmentAnnotations)
{
SequenceI seq = ann.sequenceRef;
if (seq != null)
{
Integer index = seqPositions.get(seq);
if (index != null)
{
sequenceIndices.put(seq, index);
}
}
}
}
/**
* Get the comparator for the specified sort order.
*
* @param order
* @return
*/
private Comparator super AlignmentAnnotation> getComparator(
SequenceAnnotationOrder order)
{
if (order == null)
{
return noSort;
}
switch (order)
{
case NONE:
return this.noSort;
case SEQUENCE_AND_LABEL:
return this.bySequenceAndLabel;
case LABEL_AND_SEQUENCE:
return this.byLabelAndSequence;
default:
throw new UnsupportedOperationException(order.toString());
}
}
/**
* Non-case-sensitive comparison of annotation labels. Returns zero if either
* argument is null.
*
* @param o1
* @param o2
* @return
*/
private int compareLabels(AlignmentAnnotation o1, AlignmentAnnotation o2)
{
if (o1 == null || o2 == null)
{
return 0;
}
String label1 = o1.label;
String label2 = o2.label;
if (label1 == null && label2 == null)
{
return 0;
}
if (label1 == null)
{
return -1;
}
if (label2 == null)
{
return 1;
}
return label1.toUpperCase().compareTo(label2.toUpperCase());
}
/**
* Comparison based on position of associated sequence (if any) in the
* alignment
*
* @param o1
* @param o2
* @return
*/
private int compareSequences(AlignmentAnnotation o1,
AlignmentAnnotation o2)
{
SequenceI seq1 = o1.sequenceRef;
SequenceI seq2 = o2.sequenceRef;
if (seq1 == null && seq2 == null)
{
return 0;
}
/*
* Sort non-sequence-related before or after sequence-related
*/
if (seq1 == null)
{
return showAutocalcAbove ? -1 : 1;
}
if (seq2 == null)
{
return showAutocalcAbove ? 1 : -1;
}
/*
* else sort by associated sequence position
*/
Integer index1 = sequenceIndices.get(seq1);
Integer index2 = sequenceIndices.get(seq2);
if (index1 == null)
{
return index2 == null ? 0 : -1;
}
if (index2 == null)
{
return 1;
}
return Integer.compare(index1.intValue(), index2.intValue());
}
/**
* Sort annotations to match the order of the provided list. This is intended
* only for use when reloading a project, in order to set the saved order
* after constructing a viewport (which might sort differently based on user
* preferences for sort order).
*
* There is some special handling specific to auto-calculated annotations.
* These are saved in the project, to preserve their visibility and height
* properties, but are recalculated when the viewport is reconstructed.
*
* - Autocalculated annotations are matched to the list by label
* "Consensus/Quality/Conservation/Occupancy"
* - those that are matched have their visibility and height set
*
*
* @param addedAnnotation
*/
public void sort(List annotations)
{
Arrays.sort(alignment.getAlignmentAnnotation(),
new ReloadComparator(annotations));
}
}