public class SequenceTrack extends Object
SequenceDocument.getSequenceAnnotations()).
A SequenceDocument may implement
SequenceTrack.Manager.Provider if it provides sequence tracks. The SequenceTrack.Manager allows tracks on the sequence to be added, edited and deleted. A
SequenceAlignmentDocument
may implement SequenceTrack.Manager.Provider if it provides sequence tracks on its consensus sequence. The recommended way to get existing tracks on a sequence is to use
getTrackManager(com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument) followed by
SequenceTrack.Manager.getTracks().
In addition to providing annotations, sequence tracks also have a list of SequenceAnnotationQualifiers (name/value pairs) associated with the entire track. See getQualifiers()
After any changes are made to a track, the SequenceDocument still needs to be saved via AnnotatedPluginDocument.saveDocument()
When an existing SequenceTrack.Manager is loaded, meta data for all tracks is loaded into memory, but annotations on each track are only loaded on demand via getSequenceAnnotations(jebl.util.ProgressListener)
The recommended way to create a track on a single sequence is to use new SequenceTrack ( TrackManager.getUniqueTrackName(namePrefix))
For sequence lists, in Geneious at the code level there isn't a concept of a track that spans multiple sequences. However, when viewing a sequence list, the sequence viewer makes all tracks that have the same getName()
appear as a single track to the user. This means that if the user edits the name or track qualifiers of a track, the sequence viewer will apply those changes to all tracks in that sequence list with the same id. To create a track spanning
multiple sequences, but with a unique name, pass the track managers from all sequences to Manager.getUniqueTrackName(managers, namePrefix).
Annotations of the following types must not be placed on sequence tracks or the sequence/alignment viewer may not work correctly with them:
TRIMMED , EDITING_HISTORY_DELETION,
EDITING_HISTORY_INSERTION, EDITING_HISTORY_REPLACEMENT,
OVERHANG, LIGATION,
CONCATENATED_SEQUENCE, EXTRACTED_REGION, TRANSLATED_REGION.
Instead those annotation types should only appear in the
annotations returned from SequenceDocument.getSequenceAnnotations. This list
is available in ANNOTATION_TYPES_NEVER_ON_TRACKS.
Unlike the annotations returned from SequenceDocument.getSequenceAnnotations, the
annotations in tracks are not duplicated inside alignments that store references to their ungapped sequence. Instead alignment implementations automatically fetch and insert gaps into track data
on demand. For example, consider an ungapped sequence GATTACA which has an annotation from bases 2->4. An alignment has this sequence as GA-TTACA but it doesn't store a copy of the track.
However, any code that calls getTrackManager on the alignment sequence will see a track with an annotation covering bases 2->5.
Any changes to this track will propagate back to the referenced sequence. The alignment sequence's implementation of getTrackManager will return a track manager created using
createGapInsertingManager
on the track manager obtained from the referenced sequence.| Modifier and Type | Class and Description |
|---|---|
static class |
SequenceTrack.Manager
Manages all the tracks on a single sequence, including allowing tracks to added or removed.
|
| Modifier and Type | Field and Description |
|---|---|
static List<String> |
ANNOTATION_TYPES_NEVER_ON_TRACKS
A list of annotation types that must not be places on sequence tracks.
|
static String |
DESCRIPTION_QUALIFIER
The name of a qualifier (whose value can be obtained from
getQualifiers() that describes this track. |
| Constructor and Description |
|---|
SequenceTrack(org.jdom.Element element)
Deserializes a track from XML.
|
SequenceTrack(String name)
Creates a new SequenceTrack.
|
| Modifier and Type | Method and Description |
|---|---|
void |
addQualifier(SequenceAnnotationQualifier qualifier)
Adds a new qualifier to this track.
|
void |
copyDataFrom(SequenceTrack sequenceTrack)
Copies all data from another track into this track so that this track contains identical data to the given one.
|
SequenceTrack |
createCopy()
Creates a copy of this sequence track.
|
SequenceTrack |
createCopyWithoutAnnotations()
Creates a new track which is equivalent to this track, but without any of the annotations.
|
String |
getAnnotationColoringQualifier()
Returns the name of a qualifier on each annotation in this track whose numeric value is used for determining the intensity of the color of that annotation is rendered in.
|
Map<String,Map<Double,Color>> |
getAnnotationColoringQualifierColors()
Gets all the color maps set by
setAnnotationColoringQualifierColors(String, java.util.Map) |
URN |
getDocumentVisibleByDefaultOn()
if this returns a not-null value then this track is only visible by default when viewed from within document with this URN.
|
String |
getName()
Returns the name of this track.
|
List<SequenceAnnotationQualifier> |
getQualifiers()
Returns qualifiers (name/value pairs) associated with this entire track
|
String |
getQualifierValue(String qualifierName)
Returns the value of the specified qualifier or empty String if this qualifier is not present on this track
|
int |
getSequenceAnnotationCount()
Returns the number of annotations on this track
|
List<SequenceAnnotation> |
getSequenceAnnotations(ProgressListener progressListener)
Gets the annotations for this track, loading them if necessary.
|
int |
getSequenceAnnotationTypeCount(String annotationType)
Get the total number of annotations of the given type present in this track
|
Set<String> |
getSequenceAnnotationTypes()
Gets a set consisting of each annotation type that is present at least once on this track
|
static String |
getSuggestedTrackNameSuffixForAlignmentWithReferenceSequence(AnnotatedPluginDocument document,
SequenceAlignmentDocument alignment)
Returns a suggested track name suffix to use for tracks created on an alignment with a reference sequence.
|
List<String> |
getTrackColoringQualifiers() |
static SequenceTrack.Manager |
getTrackManager(SequenceAlignmentDocument alignmentDocument)
Gets the track manager (if any) for the consensus sequence of an alignment.
|
static SequenceTrack.Manager |
getTrackManager(SequenceDocument sequenceDocument)
Gets the track manager (if any) for a sequence.
|
void |
setAnnotationColoringQualifier(String coloringQualifier)
Sets the name of a qualifier on each annotation in this track whose numeric value is used for determining the intensity of the color of that annotation is rendered in.
|
void |
setAnnotationColoringQualifierColors(String coloringQualifier,
Map<Double,Color> colorMap)
Sets the color gradient for use with
setAnnotationColoringQualifier(String). |
SequenceTrack |
setAnnotations(List<SequenceAnnotation> annotations)
Sets the annotations stored in this track
|
void |
setDocumentVisibleByDefaultOn(URN documentVisibleByDefaultOn)
Sets the document that this track is only visible by default on.
|
void |
setName(String name)
Changes the name of this track
|
void |
setQualifiers(List<SequenceAnnotationQualifier> qualifiers)
Replaces all existing qualifiers on this track with a new list of qualifiers
|
void |
setTrackColoringQualifiers(List<String> trackColoringQualifiers)
Store on this track a list of qualifiers that this track would like the Sequence Viewer to display as Track Colors.
|
org.jdom.Element |
toXML(String elementName)
Serializes this track to XML for use with
SequenceTrack(org.jdom.Element). |
public static final List<String> ANNOTATION_TYPES_NEVER_ON_TRACKS
SequenceTrack for what this list contains.public static final String DESCRIPTION_QUALIFIER
getQualifiers() that describes this track. The description may contain html, if it begins with <html>public SequenceTrack(org.jdom.Element element)
throws XMLSerializationException
element - and element returned from a previous call to toXML(String)XMLSerializationException - if the track can't be deserializedpublic SequenceTrack(String name)
name - the name for this track.
If you are creating a track inside a SequenceAnnotationGenerator, there is no need to make the name unique.
The sequence viewer and core Geneious will automatically ensure the name is unique in the document. For alignments/contigs with reference sequences it is a good idea to append a
suffix describing the sample name. See getSuggestedTrackNameSuffixForAlignmentWithReferenceSequence.
If you are manually adding tracks to sequences, it is a good idea to ensure the name is unique on this associated sequence by
calling SequenceTrack.Manager.getUniqueTrackName(String) or unique across a set of sequences by calling SequenceTrack.Manager.getUniqueTrackName(java.util.List, String).public static SequenceTrack.Manager getTrackManager(SequenceDocument sequenceDocument)
sequenceDocument - the sequence to get the track manager forpublic static SequenceTrack.Manager getTrackManager(SequenceAlignmentDocument alignmentDocument)
getTrackManager(com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument) on the sequences returned from SequenceAlignmentDocument.getSequence(int)alignmentDocument - the alignment to get the track manager forpublic org.jdom.Element toXML(String elementName)
SequenceTrack(org.jdom.Element). The returned XML may use PluginDocument.FILE_DATA_ATTRIBUTE_NAMEelementName - the name of the element to returnpublic SequenceTrack createCopy()
createCopyWithoutAnnotations()public SequenceTrack createCopyWithoutAnnotations()
createCopy()public void copyDataFrom(SequenceTrack sequenceTrack)
sequenceTrack - another track to copy.public Set<String> getSequenceAnnotationTypes()
getSequenceAnnotationTypeCount(String)public int getSequenceAnnotationTypeCount(String annotationType)
annotationType - the type of annotation (e.g. SequenceAnnotation.TYPE_CDS)getSequenceAnnotationTypes(),
getSequenceAnnotationCount()public String getName()
SequenceTrack.Manager must be unique.public void setName(String name)
name - the new name of this track. Must not be null. Names must not be the same as other tracks although this is not enforced here. Use SequenceTrack.Manager.getUniqueTrackName(String) to create a unique name.public int getSequenceAnnotationCount()
getSequenceAnnotationTypeCount(String)public List<SequenceAnnotation> getSequenceAnnotations(ProgressListener progressListener)
progressListener - for reporting progress as the annotations are loaded and allowing it to be cancelled.ProgressListener.isCanceled()RuntimeException - whose cause is an XMLSerializationException if there is insufficient memory to load the annotationspublic SequenceTrack setAnnotations(List<SequenceAnnotation> annotations)
annotations - the annotations stored in this trackpublic List<SequenceAnnotationQualifier> getQualifiers()
public String getQualifierValue(String qualifierName)
qualifierName - the name of the qualifier to getpublic void addQualifier(SequenceAnnotationQualifier qualifier)
qualifier - the new qualifierpublic void setQualifiers(List<SequenceAnnotationQualifier> qualifiers)
qualifiers - the new list of qualifiers for this track. Must not be null but may be empty.public String getAnnotationColoringQualifier()
public void setAnnotationColoringQualifier(String coloringQualifier)
coloringQualifier - the name of a qualifier on each annotation in this track or null to not color by a qualifiersetAnnotationColoringQualifierColors(String, java.util.Map)public void setAnnotationColoringQualifierColors(String coloringQualifier, Map<Double,Color> colorMap)
setAnnotationColoringQualifier(String).
For example: the coloring qualifier has a range of 50 -100. The map will include values for 50 and 100
and the annotation colors will be interpolated between these values. Optional additional value color
pairs can be provided and the gradient will move through them.coloringQualifier - the qualifier to apply this color map forcolorMap - Map from a particular value to the color used at that value for this qualifiersetAnnotationColoringQualifier(String)public Map<String,Map<Double,Color>> getAnnotationColoringQualifierColors()
setAnnotationColoringQualifierColors(String, java.util.Map)setAnnotationColoringQualifierColors(String, java.util.Map)public List<String> getTrackColoringQualifiers()
setTrackColoringQualifiers(java.util.List)public void setTrackColoringQualifiers(List<String> trackColoringQualifiers)
trackColoringQualifiers - the qualifiers to display as Track Colors.getTrackColoringQualifiers()public URN getDocumentVisibleByDefaultOn()
public void setDocumentVisibleByDefaultOn(URN documentVisibleByDefaultOn)
getDocumentVisibleByDefaultOn() for more information.
Note: As of Geneious 8.0.1, there is a known issue where this might not always work. When just a single track for a particular annotation type, then the visibility of that
track is linked with the annotation type visibility instead of stored as a preference for that track. The annotation type visibility preference is on a per 'document type' basis
unlike the track visibility which is on a per 'document' basis.documentVisibleByDefaultOn - the document that this track is only visible by default on or null.public static String getSuggestedTrackNameSuffixForAlignmentWithReferenceSequence(AnnotatedPluginDocument document, SequenceAlignmentDocument alignment)
document - the document the alignment or contig came from.alignment - the alignment or contig