Class SequenceSelection
- java.lang.Object
-
- com.biomatters.geneious.publicapi.plugin.SequenceSelection
-
- All Implemented Interfaces:
XMLSerializable
,XMLSerializable.OldVersionCompatible
public final class SequenceSelection extends java.lang.Object implements XMLSerializable, XMLSerializable.OldVersionCompatible
Specifies a selection of regions in a sequence, list of sequences, alignment or other sequence containing document. A SequenceSelection is provided toDocumentOperations
andSequenceAnnotationGenerators
to allow them to optionally make their behaviour depend on what the user has currently selected in the sequence/alignment viewer.DocumentViewers
are also informed of the current selection in other viewers viaDocumentViewerMessageHandler.setSequenceSelection
Each SequenceSelection consists of one or moreSelectionIntervals
. A SelectionInterval has a range of selected residues/bases (seeSelectionInterval.getResidueInterval()
) and an associatedSequenceSelection.SequenceIndex
. The SequenceIndex indicates which sequence in the set of sequences is selected. The index is relative to the first sequence in the first document. So for example if 2SequenceListDocuments
are selected, and the first sequence list has 5 sequences, then a SequenceIndex of 6 corresponds to the second sequence in the second list.SequenceIndex.getSequence
automatically applies this logic. For a slightly more complicated example, consider a set of 2 documents, the first of which is a SequenceDocument and the second is aCombinedAlignmentAndSequenceDocument
. Let [a,b] denote a SequenceIndex withSequenceSelection.SequenceIndex.getSequenceIndex()
==a andSequenceSelection.SequenceIndex.getSequenceDocumentType()
==b) Then:
[0,SequenceDocumentType.Sequence] refers to the sequence contained in the first document, the SequenceDocument
[1,SequenceDocumentType.Sequence] refers to the un-aligned sequence from the CombinedAlignmentAndSequenceDocument
[0,SequenceDocumentType.Alignment] refers to the first sequence in the alignment in the CombinedAlignmentAndSequenceDocument
[1,SequenceDocumentType.Alignment] refers to the second sequence in the alignment in the CombinedAlignmentAndSequenceDocument
[2,SequenceDocumentType.Alignment] refers to the third sequence in the alignment in the CombinedAlignmentAndSequenceDocument
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SequenceSelection.SelectedAnnotation
Represents a single selected annotationstatic class
SequenceSelection.SelectionInterval
A contiguous selection of residues in a sequence.static class
SequenceSelection.SequenceDocumentType
Used for identifying the type of view the selection applies for identifying which list the index applies to in aCombinedAlignmentAndSequenceDocument
static class
SequenceSelection.SequenceIndex
Represents the index of the selected sequence and the type (so that we can identify which list the index applies to inSequenceListDocuments
.-
Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
XMLSerializable.OldVersionCompatible, XMLSerializable.VersionSupportType
-
-
Field Summary
-
Fields inherited from interface com.biomatters.geneious.publicapi.documents.XMLSerializable
ROOT_ELEMENT_NAME
-
-
Constructor Summary
Constructors Constructor Description SequenceSelection(SequenceDocument sequence, SequenceAnnotation annotation)
SequenceSelection(SequenceSelection.SelectionInterval... intervals)
Create a SequenceSelectionSequenceSelection(SequenceSelection.SequenceIndex sequenceIndex, SequenceAnnotation annotation)
Construct for a selected SequenceAnnotation on the specified sequence.SequenceSelection(java.util.List<SequenceSelection.SelectionInterval> intervals)
Create a SequenceSelectionSequenceSelection(org.jdom.Element element)
Construct a SequenceSelection from the results oftoXML()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
equals(java.lang.Object o)
java.util.List<DefaultSequenceDocument>
extractIntervals()
Deprecated.static SequenceSelection
forAnnotations(java.util.List<SequenceSelection.SelectedAnnotation> annotations)
void
fromXML(org.jdom.Element element)
Restore the object from the JDOM Element returned byXMLSerializable.toXML()
.SequenceAnnotation
getAnnotation()
Get the selected annotation if there is one and only onejava.util.List<SequenceSelection.SelectedAnnotation>
getAnnotations()
SequenceSelection.SequenceIndex
getAnnotationSequenceIndex()
Get the sequence index of the selected annotation if there is single selected annotationjava.util.List<SequenceSelection.SelectionInterval>
getIntervals()
Deprecated.usegetIntervals(boolean)
insteadjava.util.List<SequenceSelection.SelectionInterval>
getIntervals(boolean splitMultiSequenceIntervalsIntoSingleSelectionIntervals)
Gets the intervals selectedjava.util.List<SequenceSelection.SelectionInterval>
getNonZeroLengthIntervals()
int
getSelectedSequenceCount()
Returns the number of sequences which have any residues selected (0 length selections are included).java.util.Set<SequenceSelection.SequenceIndex>
getSelectedSequenceIndices()
java.util.Set<SequenceDocument>
getSelectedSequences()
Deprecated.static SequenceSelection
getTotalSelection(java.util.List<AnnotatedPluginDocument> documents, jebl.evolution.sequences.SequenceType type, SequenceSelection.SequenceDocumentType sequenceDocumentType)
For a List of AnnotatedPluginDocument, creates a selection that represents a "Select all" on each of the documents.Geneious.MajorVersion
getVersionSupport(XMLSerializable.VersionSupportType versionType)
Gets either the latest version this class can serialize to viaXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
or the most recent version in which the XML returned fromXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
last changed.int
hashCode()
java.lang.String
toString()
org.jdom.Element
toXML()
Convert object to a JDOM element.org.jdom.Element
toXML(Geneious.MajorVersion version, jebl.util.ProgressListener progressListener)
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.SequenceSelection
withoutZeroLengthIntervals()
-
-
-
Constructor Detail
-
SequenceSelection
public SequenceSelection(java.util.List<SequenceSelection.SelectionInterval> intervals)
Create a SequenceSelection- Parameters:
intervals
- the intervals
-
SequenceSelection
public SequenceSelection(SequenceSelection.SelectionInterval... intervals)
Create a SequenceSelection- Parameters:
intervals
- the intervals
-
SequenceSelection
public SequenceSelection(SequenceSelection.SequenceIndex sequenceIndex, SequenceAnnotation annotation)
Construct for a selected SequenceAnnotation on the specified sequence. The intervals returned bygetIntervals()
will correspond to the intervals of this annotation. To create a selection of multiple annotations, useforAnnotations(List)
- Parameters:
sequenceIndex
- the index of the sequenceannotation
- the selected annotation, must not be null- Since:
- API 4.40 (Geneious 5.4.0)
-
SequenceSelection
@Deprecated public SequenceSelection(SequenceDocument sequence, SequenceAnnotation annotation)
Deprecated.Construct for a selected SequenceAnnotation on the specified sequence. The intervals returned bygetIntervals()
will correspond to the intervals of this annotation.- Parameters:
sequence
- the sequence in which the annotation is selected, must not be nullannotation
- the selected annotation, must not be null
-
SequenceSelection
public SequenceSelection(org.jdom.Element element) throws XMLSerializationException
Construct a SequenceSelection from the results oftoXML()
- Parameters:
element
- an element returned fromtoXML()
- Throws:
XMLSerializationException
- if XML does not conform to our unpublished specification- Since:
- API 4.40 (Geneious 5.4.0)
-
-
Method Detail
-
forAnnotations
public static SequenceSelection forAnnotations(java.util.List<SequenceSelection.SelectedAnnotation> annotations)
- Parameters:
annotations
- the annotations to be selected- Returns:
- a new SequenceSelection for a selection of annotations. The intervals for the created selection will correspond to the annotations provided.
- Since:
- API 4.1100 (Geneious 11.0.0)
-
withoutZeroLengthIntervals
public SequenceSelection withoutZeroLengthIntervals()
- Returns:
- an exact copy of this SequenceSelection but with any zero length SelectionIntervals removed.
- Since:
- API 4.50 (Geneious 5.5.0)
-
getAnnotation
public SequenceAnnotation getAnnotation()
Get the selected annotation if there is one and only one- Returns:
- the selected annotation or
null
if none or more than one annotation is selected - See Also:
getAnnotationSequenceIndex()
,getAnnotations()
-
getAnnotations
public java.util.List<SequenceSelection.SelectedAnnotation> getAnnotations()
- Returns:
- all the selected annotations
- Since:
- API 4.1100 (Geneious 11.0.0)
-
getAnnotationSequenceIndex
public SequenceSelection.SequenceIndex getAnnotationSequenceIndex()
Get the sequence index of the selected annotation if there is single selected annotation- Returns:
- the sequence index of the selected annotation.
- Throws:
java.lang.IllegalStateException
- If this SequenceSelection was deserialized from XML Created in Geneious 5.5 or earlier and the annotation had no intervals or if there is not a single selected annotation- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
getAnnotation()
-
getIntervals
@Deprecated public java.util.List<SequenceSelection.SelectionInterval> getIntervals()
Deprecated.usegetIntervals(boolean)
insteadEquivalent togetIntervals(true)
- Returns:
- the intervals
-
getIntervals
public java.util.List<SequenceSelection.SelectionInterval> getIntervals(boolean splitMultiSequenceIntervalsIntoSingleSelectionIntervals)
Gets the intervals selected- Parameters:
splitMultiSequenceIntervalsIntoSingleSelectionIntervals
- true to split rectangular SelectionIntervals (those that cover more than 1 sequence) into 1 SelectionInterval per sequence. When this is true ,SequenceSelection.SelectionInterval.getSequenceIndex()
may be called on the returned intervals.- Returns:
- the intervals selected, possibly including rectangular selections if splitMultiSequenceIntervalsIntoSingleSelectionIntervals is false (a range of sequences and a range of residues). Note that this may return empty intervals, for example to denote a cursor position. Using
getNonZeroLengthIntervals()
will return a list guaranteed to correspond exactly to the nonempty selections that a user has made. - Since:
- API 4.40 (Geneious 5.4.0)
-
getNonZeroLengthIntervals
public java.util.List<SequenceSelection.SelectionInterval> getNonZeroLengthIntervals()
- Returns:
- the (potentially ranged) intervals in this selection. Normally this will be a single element list unless the selection is discontiguous. The List of SelectionInterval that this method returns does not include any with zero length.
- Since:
- API 4.40 (Geneious 5.4.0)
-
getSelectedSequenceCount
public int getSelectedSequenceCount()
Returns the number of sequences which have any residues selected (0 length selections are included). If the same sequence occurs in multiple SelectionIntervals it will be counted once.- Returns:
- the number of sequences which have any residues selected (0 length selections are included)
-
getSelectedSequences
@Deprecated public java.util.Set<SequenceDocument> getSelectedSequences()
Deprecated.- Returns:
- set of sequences which have any residues selected (0 length selections are included)
-
getSelectedSequenceIndices
public java.util.Set<SequenceSelection.SequenceIndex> getSelectedSequenceIndices()
- Returns:
- set of sequence indices which have any residues selected (0 length selections are included)
- Since:
- API 4.40 (Geneious 5.4.0)
-
extractIntervals
@Deprecated public java.util.List<DefaultSequenceDocument> extractIntervals()
Deprecated.Extract the selected intervals as individual sequence documents. If multiple intervals are selected in a single sequence document then each of the intervals is extracted separately.- Returns:
- the selected intervals as individual sequence documents
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object o)
- Overrides:
equals
in classjava.lang.Object
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
getTotalSelection
public static SequenceSelection getTotalSelection(java.util.List<AnnotatedPluginDocument> documents, jebl.evolution.sequences.SequenceType type, SequenceSelection.SequenceDocumentType sequenceDocumentType)
For a List of AnnotatedPluginDocument, creates a selection that represents a "Select all" on each of the documents. This depends on the SequenceType and SequenceDocumentType passed in which determine whether to use the nucleotide or amino acid sequences from a List, and whether to use the stand-alone sequences or the aligned sequences from a document (which is ambiguous in the case of a CombinedAlignmentAndSequenceDocument). IfSequenceSelection.SequenceDocumentType.Sequence
is provided for sequenceDocumentType, then the sequences from SequenceListDocument, SequenceDocument and the stand-alone sequence from a CombinedAlignmentAndSequenceDocument will be included, or else ignored. IfSequenceSelection.SequenceDocumentType.Alignment
is provided, then the aligned sequences from a SequenceAlignmentDocument will be included, or else ignored.- Parameters:
documents
- the documents to create a total selection fortype
- the type of sequences (nucleotide or amino-acid) to select in each documentsequenceDocumentType
- whether to use the stand-alone sequences or the aligned sequences in each document. IfSequenceSelection.SequenceDocumentType.Sequence
is provided, then the sequences from SequenceListDocument, SequenceDocument and the stand-alone sequence from a CombinedAlignmentAndSequenceDocument will be included, or else ignored. IfSequenceSelection.SequenceDocumentType.Alignment
is provided, then the aligned sequences from a SequenceAlignmentDocument will be included, or else ignored.- Returns:
- the SequenceSelection representing the total selection.
- Since:
- API 4.40 (Geneious 5.4.0)
-
toXML
public org.jdom.Element toXML()
Description copied from interface:XMLSerializable
Convert object to a JDOM element. The representation should be complete so thatXMLSerializable.fromXML(org.jdom.Element)
can completely restore the object's representation. It is recommended that the returned element useXMLSerializable.ROOT_ELEMENT_NAME
as its name, in which case it must not define an attribute called "type". In this case, fromXML, will be called with an element whose name may differ from the element return from this function. This recommendation allows a more compact representation of the XML can be stored. This method generally should not be called directly. Instead, you should usually callXMLSerializer.classToXML(String, XMLSerializable)
which calls this method internally. PluginDocument implementations of this method may choose to throw anXMLSerializationException
, enclosed in aRuntimeException
.- Specified by:
toXML
in interfaceXMLSerializable
- Returns:
- object encoded as a JDOM element
-
getVersionSupport
public Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)
Description copied from interface:XMLSerializable.OldVersionCompatible
Gets either the latest version this class can serialize to viaXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
or the most recent version in which the XML returned fromXMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener)
last changed. Example implementation:switch (versionType) { case FormatLastExtended: //added a new tag to xml in 10.0 that can be safely ignored by older versions return Geneious.MajorVersion.Version10_0; case FormatLastChanged: //renamed a tag in 9.1 meaning that older versions can no longer read the xml from 9.1 return Geneious.MajorVersion.Version9_1; case OldestVersionSerializableTo: //this document class can export xml that is compatible with 9.0 return Geneious.MajorVersion.Version9_0; default: throw new IllegalArgumentException("Unrecognized VersionSupportType"); }
- Specified by:
getVersionSupport
in interfaceXMLSerializable.OldVersionCompatible
- Parameters:
versionType
- specifies which version property to return- Returns:
- the major version of Geneious corresponding to the versionType for this classes toXML method.
-
toXML
public org.jdom.Element toXML(Geneious.MajorVersion version, jebl.util.ProgressListener progressListener)
Description copied from interface:XMLSerializable.OldVersionCompatible
Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious. It is acceptable for the XML to include unnecessary tags that will be ignored by the earlier version. For example if the implementation has only extended the XML since the earlier version, then the XML returned may be identical to the XML returned for the current version. SeeXMLSerializable.toXML()
for a more detailed description of what it means to serialize to XML. All classes that implement this method must also implement XMLSerializable.toXML() and should delegate back to this method using Geneious.getMajorVersion() and ProgressListener.EMPTY as parameters.- Specified by:
toXML
in interfaceXMLSerializable.OldVersionCompatible
- Parameters:
version
- the major version of Geneious to serialize to XML for. For example "6.0" but not "6.0.0". This must be a version returned greater or equal to a version returned fromgetVersionSupport
(VersionSupportType.OldestVersionSerializableTo
) and must never be greater than the current version (Geneious.getMajorVersion())progressListener
- for reporting progress and cancelling- Returns:
- object encoded as a JDOM element
-
fromXML
public void fromXML(org.jdom.Element element) throws XMLSerializationException
Description copied from interface:XMLSerializable
Restore the object from the JDOM Element returned byXMLSerializable.toXML()
. This method generally should not be called directly. Instead, you should usually callXMLSerializer.classFromXML(org.jdom.Element)
orXMLSerializer.classFromXML(org.jdom.Element, Class)
which calls this method internally. It is optional to implement this method. Instead of implementing an empty constructor and implementing this method properly, the implementation may instead throw an UnsupportedOperationException and implement a constructor that takes a singleElement
as a parameter. This allows for cleaner code such as support for final fields in the XMLSerializable class. The element parameter should not be modified since it may be reused. If you need a modified version of it, take a copy withElement.clone()
.- Specified by:
fromXML
in interfaceXMLSerializable
- Parameters:
element
- representation from a previous call toXMLSerializable.toXML()
- Throws:
XMLSerializationException
- if the Element can't be converted into this type of object
-
-