Class SequenceTrack
- java.lang.Object
-
- com.biomatters.geneious.publicapi.implementations.sequence.SequenceTrack
-
public class SequenceTrack extends java.lang.Object
A Sequence Track is a list of annotations that is associated with a sequence (in addition to those supplied bySequenceDocument.getSequenceAnnotations()
). ASequenceDocument
may implementSequenceTrack.Manager.Provider
if it provides sequence tracks. TheSequenceTrack.Manager
allows tracks on the sequence to be added, edited and deleted. ASequenceAlignmentDocument
may implementSequenceTrack.Manager.Provider
if it provides sequence tracks on its consensus sequence. The recommended way to get existing tracks on a sequence is to usegetTrackManager(com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument)
followed bySequenceTrack.Manager.getTracks()
. In addition to providing annotations, sequence tracks also have a list ofSequenceAnnotationQualifier
s (name/value pairs) associated with the entire track. SeegetQualifiers()
After any changes are made to a track, the SequenceDocument still needs to be saved viaAnnotatedPluginDocument.saveDocument()
When an existingSequenceTrack.Manager
is loaded, meta data for all tracks is loaded into memory, but annotations on each track are only loaded on demand viagetSequenceAnnotations(jebl.util.ProgressListener)
The recommended way to create a track on a single sequence is to usenew 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 samegetName()
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 toManager.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 fromSequenceDocument.getSequenceAnnotations
. This list is available inANNOTATION_TYPES_NEVER_ON_TRACKS
. Unlike the annotations returned fromSequenceDocument.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 callsgetTrackManager
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 usingcreateGapInsertingManager
on the track manager obtained from the referenced sequence.- Since:
- API 4.50 (Geneious 5.5.0)
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SequenceTrack.Manager
Manages all the tracks on a single sequence, including allowing tracks to added or removed.
-
Field Summary
Fields Modifier and Type Field Description static java.util.List<java.lang.String>
ANNOTATION_TYPES_NEVER_ON_TRACKS
A list of annotation types that must not be places on sequence tracks.static java.lang.String
DESCRIPTION_QUALIFIER
The name of a qualifier (whose value can be obtained fromgetQualifiers()
that describes this track.static java.lang.String
NO_TRACK
The text used to display the track name for annotations which are not in a track.
-
Constructor Summary
Constructors Constructor Description SequenceTrack(java.lang.String name)
Creates a new SequenceTrack.SequenceTrack(org.jdom.Element element)
Deserializes a track from XML.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addQualifier(SequenceAnnotationQualifier qualifier)
Adds a new qualifier to this track.void
addTrackDataFile(java.lang.String identifier, java.io.File dataFile)
Add a data file to be associated with this track, a copy of which will be stored in the local database and it will not be loaded upon track load.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.java.lang.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.java.util.Map<java.lang.String,java.util.Map<java.lang.Double,java.awt.Color>>
getAnnotationColoringQualifierColors()
Gets all the color maps set bysetAnnotationColoringQualifierColors(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.java.lang.String
getName()
Returns the name of this track.java.util.List<SequenceAnnotationQualifier>
getQualifiers()
Returns qualifiers (name/value pairs) associated with this entire trackjava.lang.String
getQualifierValue(java.lang.String qualifierName)
Returns the value of the specified qualifier or empty String if this qualifier is not present on this trackint
getSequenceAnnotationCount()
Returns the number of annotations on this trackjava.util.List<SequenceAnnotation>
getSequenceAnnotations(jebl.util.ProgressListener progressListener)
Gets the annotations for this track, loading them if necessary.java.util.List<SequenceAnnotation>
getSequenceAnnotationsOfType(java.lang.String type, jebl.util.ProgressListener progressListener)
Gets the annotations of a given type for this track, loading them if necessary.int
getSequenceAnnotationTypeCount(java.lang.String annotationType)
Get the total number of annotations of the given type present in this trackjava.util.Set<java.lang.String>
getSequenceAnnotationTypes()
Gets a set consisting of each annotation type that is present at least once on this trackstatic java.lang.String
getSuggestedTrackNameSuffixForAlignmentWithReferenceSequence(AnnotatedPluginDocument document, SequenceAlignmentDocument alignment)
Returns a suggested track name suffix to use for tracks created on an alignment with a reference sequence.static SequenceTrack
getTrack(SequenceDocument sequence, java.lang.String trackName)
Gets a track by name from a sequencejava.util.List<java.lang.String>
getTrackColoringQualifiers()
java.io.File
getTrackDataFile(java.lang.String identifier)
Return the data file associated with this track identified byidentifier
.static SequenceTrack.Manager
getTrackManager(SequenceAlignmentDocument alignmentDocument)
Equivalent togetTrackManager(sequenceAlignmentDocument, true)
static SequenceTrack.Manager
getTrackManager(SequenceAlignmentDocument alignmentDocument, boolean mayReturnNullIfNoTracks)
Gets the track manager (if any) for the consensus sequence of an alignment.static SequenceTrack.Manager
getTrackManager(SequenceDocument sequenceDocument)
Equivalent togetTrackManager(sequenceDocument, true)
static SequenceTrack.Manager
getTrackManager(SequenceDocument sequenceDocument, boolean mayReturnNullIfNoTracks)
Gets the track manager (if any) for a sequence.static java.util.List<SequenceTrack>
getTracks(SequenceDocument sequence)
Gets all tracks from a sequencevoid
setAnnotationColoringQualifier(java.lang.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(java.lang.String coloringQualifier, java.util.Map<java.lang.Double,java.awt.Color> colorMap)
Sets the color gradient for use withsetAnnotationColoringQualifier(String)
.SequenceTrack
setAnnotations(java.util.List<SequenceAnnotation> annotations)
Sets the annotations stored in this trackvoid
setDocumentVisibleByDefaultOn(URN documentVisibleByDefaultOn)
Sets the document that this track is only visible by default on.void
setName(java.lang.String name)
Changes the name of this trackvoid
setQualifiers(java.util.List<SequenceAnnotationQualifier> qualifiers)
Replaces all existing qualifiers on this track with a new list of qualifiersvoid
setTrackColoringQualifiers(java.util.List<java.lang.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(java.lang.String elementName)
Serializes this track to XML for use withSequenceTrack(org.jdom.Element)
.
-
-
-
Field Detail
-
ANNOTATION_TYPES_NEVER_ON_TRACKS
public static final java.util.List<java.lang.String> ANNOTATION_TYPES_NEVER_ON_TRACKS
A list of annotation types that must not be places on sequence tracks. SeeSequenceTrack
for what this list contains.
-
NO_TRACK
public static final java.lang.String NO_TRACK
The text used to display the track name for annotations which are not in a track. Tracks may not have this name. Annotations not in a track are available viaSequenceDocument.getSequenceAnnotations()
- Since:
- API 4.1000 (Geneious 10.0.0)
- See Also:
- Constant Field Values
-
DESCRIPTION_QUALIFIER
public static final java.lang.String DESCRIPTION_QUALIFIER
The name of a qualifier (whose value can be obtained fromgetQualifiers()
that describes this track. The description may contain html, if it begins with <html>- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
- Constant Field Values
-
-
Constructor Detail
-
SequenceTrack
public SequenceTrack(org.jdom.Element element) throws XMLSerializationException
Deserializes a track from XML.- Parameters:
element
- and element returned from a previous call totoXML(String)
- Throws:
XMLSerializationException
- if the track can't be deserialized
-
SequenceTrack
public SequenceTrack(java.lang.String name)
Creates a new SequenceTrack.- Parameters:
name
- the name for this track. If you are creating a track inside aSequenceAnnotationGenerator
, 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. SeegetSuggestedTrackNameSuffixForAlignmentWithReferenceSequence
. If you are manually adding tracks to sequences, it is a good idea to ensure the name is unique on this associated sequence by callingSequenceTrack.Manager.getUniqueTrackName(String)
or unique across a set of sequences by callingSequenceTrack.Manager.getUniqueTrackName(java.util.List, String)
.
-
-
Method Detail
-
addTrackDataFile
public void addTrackDataFile(java.lang.String identifier, java.io.File dataFile)
Add a data file to be associated with this track, a copy of which will be stored in the local database and it will not be loaded upon track load.- Parameters:
identifier
- Unique string to identify the data filedataFile
- Data file to identify with this track- Throws:
java.lang.IllegalArgumentException
- when attempting to add an empty file- Since:
- API 4.900 (Geneious 9.0.0)
- See Also:
getTrackDataFile(String)
-
getTrackDataFile
public java.io.File getTrackDataFile(java.lang.String identifier)
Return the data file associated with this track identified byidentifier
.- Parameters:
identifier
- Unique string to identify the data file- Returns:
- the data file associated with this track identified by
identifier
or null if no data file identified by this string - Since:
- API 4.900 (Geneious 9.0.0)
- See Also:
addTrackDataFile(String, File)
-
getTrackManager
public static SequenceTrack.Manager getTrackManager(SequenceDocument sequenceDocument)
Equivalent togetTrackManager(sequenceDocument, true)
-
getTrackManager
public static SequenceTrack.Manager getTrackManager(SequenceDocument sequenceDocument, boolean mayReturnNullIfNoTracks)
Gets the track manager (if any) for a sequence.- Parameters:
sequenceDocument
- the sequence to get the track manager formayReturnNullIfNoTracks
- to save on memory usage when dealing with lots of small sequences, some implementations may not wish to construct a TrackManager unless necessary. If this parameter is true the implementation may return null rather than an empty track manager if is has no tracks- Returns:
- a track manager for this sequence, or null if it doesn't have one. Even if mayReturnNullIfNoTracks==false this method may return null on sequences that don't support tracks.
- Since:
- API 4.1000 (Geneious 10.0.0)
-
getTrackManager
public static SequenceTrack.Manager getTrackManager(SequenceAlignmentDocument alignmentDocument)
Equivalent togetTrackManager(sequenceAlignmentDocument, true)
-
getTrackManager
public static SequenceTrack.Manager getTrackManager(SequenceAlignmentDocument alignmentDocument, boolean mayReturnNullIfNoTracks)
Gets the track manager (if any) for the consensus sequence of an alignment. To get the track manager for sequences in the alignment, usegetTrackManager(com.biomatters.geneious.publicapi.documents.sequence.SequenceDocument)
orgetTrackManager(SequenceDocument, boolean)
on the sequences returned fromSequenceAlignmentDocument.getSequence(int)
- Parameters:
alignmentDocument
- the alignment to get the track manager formayReturnNullIfNoTracks
- to save on memory usage when dealing with lots of small sequences, some implementations may not wish to construct a TrackManager unless necessary. If this parameter is true the implementation may return null rather than an empty track manager if is has no tracks- Returns:
- a track manager for this alignments consensus sequence, or null if it doesn't have one. Even if mayReturnNullIfNoTracks==false this method may return null on sequences that don't support tracks.
- Since:
- API 4.1000 (Geneious 10.0.0)
-
toXML
public org.jdom.Element toXML(java.lang.String elementName)
Serializes this track to XML for use withSequenceTrack(org.jdom.Element)
. The returned XML may usePluginDocument.FILE_DATA_ATTRIBUTE_NAME
- Parameters:
elementName
- the name of the element to return- Returns:
- this track serialized to XML
-
createCopy
public SequenceTrack createCopy()
Creates a copy of this sequence track.- Returns:
- a copy of this sequence track.
- See Also:
createCopyWithoutAnnotations()
-
createCopyWithoutAnnotations
public SequenceTrack createCopyWithoutAnnotations()
Creates a new track which is equivalent to this track, but without any of the annotations.- Returns:
- a new track which is equivalent to this track, but without any of the annotations.
- See Also:
createCopy()
-
copyDataFrom
public void copyDataFrom(SequenceTrack sequenceTrack)
Copies all data from another track into this track so that this track contains identical data to the given one.- Parameters:
sequenceTrack
- another track to copy.
-
getSequenceAnnotationTypes
public java.util.Set<java.lang.String> getSequenceAnnotationTypes()
Gets a set consisting of each annotation type that is present at least once on this track- Returns:
- a set consisting of each annotation type that is present at least once on this track
- See Also:
getSequenceAnnotationTypeCount(String)
-
getSequenceAnnotationTypeCount
public int getSequenceAnnotationTypeCount(java.lang.String annotationType)
Get the total number of annotations of the given type present in this track- Parameters:
annotationType
- the type of annotation (e.g.SequenceAnnotation.TYPE_CDS
)- Returns:
- the number of annotations of this type
- See Also:
getSequenceAnnotationTypes()
,getSequenceAnnotationCount()
-
getName
public java.lang.String getName()
Returns the name of this track. The names of each track in a singleSequenceTrack.Manager
must be unique.- Returns:
- the name of this track. Will not be null.
-
setName
public void setName(java.lang.String name)
Changes the name of this track- Parameters:
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. UseSequenceTrack.Manager.getUniqueTrackName(String)
to create a unique name.
-
getSequenceAnnotationCount
public int getSequenceAnnotationCount()
Returns the number of annotations on this track- Returns:
- the number of annotations on this track
- See Also:
getSequenceAnnotationTypeCount(String)
-
getSequenceAnnotations
public java.util.List<SequenceAnnotation> getSequenceAnnotations(jebl.util.ProgressListener progressListener)
Gets the annotations for this track, loading them if necessary. returned annotations must not be modified.- Parameters:
progressListener
- for reporting progress as the annotations are loaded and allowing it to be cancelled.- Returns:
- the annotations. May only be null if the
ProgressListener.isCanceled()
- Throws:
java.lang.RuntimeException
- whose cause is anXMLSerializationException
if there is insufficient memory to load the annotations
-
getSequenceAnnotationsOfType
public java.util.List<SequenceAnnotation> getSequenceAnnotationsOfType(java.lang.String type, jebl.util.ProgressListener progressListener)
Gets the annotations of a given type for this track, loading them if necessary.- Parameters:
type
- type of annotations to getprogressListener
- for reporting progress as the annotations are loaded and allowing it to be cancelled.- Returns:
- all annotations on this track matching the type. May only be null if the
ProgressListener.isCanceled()
- Throws:
java.lang.RuntimeException
- whose cause is anXMLSerializationException
if there is insufficient memory to load the annotations- Since:
- API 4.1000 (Geneious 10.0)
-
setAnnotations
public SequenceTrack setAnnotations(java.util.List<SequenceAnnotation> annotations)
Sets the annotations stored in this track- Parameters:
annotations
- the annotations stored in this track- Returns:
- this (for convenience)
-
getQualifiers
public java.util.List<SequenceAnnotationQualifier> getQualifiers()
Returns qualifiers (name/value pairs) associated with this entire track- Returns:
- qualifiers (name/value pairs) associated with this entire track. Will not be null but may be empty.
-
getQualifierValue
public java.lang.String getQualifierValue(java.lang.String qualifierName)
Returns the value of the specified qualifier or empty String if this qualifier is not present on this track- Parameters:
qualifierName
- the name of the qualifier to get- Returns:
- the value of the specified qualifier or empty String if this qualifier is not present on this track
- Since:
- API 4.801 (Geneious 8.0.1)
-
addQualifier
public void addQualifier(SequenceAnnotationQualifier qualifier)
Adds a new qualifier to this track.- Parameters:
qualifier
- the new qualifier
-
setQualifiers
public void setQualifiers(java.util.List<SequenceAnnotationQualifier> qualifiers)
Replaces all existing qualifiers on this track with a new list of qualifiers- Parameters:
qualifiers
- the new list of qualifiers for this track. Must not be null but may be empty.
-
getAnnotationColoringQualifier
public java.lang.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.- Returns:
- name of a qualifier on each annotation in this track whose value is used for determining the intensity of the color of that annotation is rendered in or null to not color by a qualifier
-
setAnnotationColoringQualifier
public void setAnnotationColoringQualifier(java.lang.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.- Parameters:
coloringQualifier
- the name of a qualifier on each annotation in this track or null to not color by a qualifier- See Also:
setAnnotationColoringQualifierColors(String, java.util.Map)
-
setAnnotationColoringQualifierColors
public void setAnnotationColoringQualifierColors(java.lang.String coloringQualifier, java.util.Map<java.lang.Double,java.awt.Color> colorMap)
Sets the color gradient for use withsetAnnotationColoringQualifier(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.- Parameters:
coloringQualifier
- the qualifier to apply this color map forcolorMap
- Map from a particular value to the color used at that value for this qualifier- Since:
- API 4.801 (Geneious 8.0.1)
- See Also:
setAnnotationColoringQualifier(String)
-
getAnnotationColoringQualifierColors
public java.util.Map<java.lang.String,java.util.Map<java.lang.Double,java.awt.Color>> getAnnotationColoringQualifierColors()
Gets all the color maps set bysetAnnotationColoringQualifierColors(String, java.util.Map)
- Returns:
- all the color maps set by
setAnnotationColoringQualifierColors(String, java.util.Map)
- Since:
- API 4.801 (Geneious 8.0.1)
-
getTrackColoringQualifiers
public java.util.List<java.lang.String> getTrackColoringQualifiers()
- Returns:
- Returns the list of qualifiers that this track would like the Sequence Viewer to display as Track Colors. If the Sequence Viewer hasn't already been told to display (or not display) these qualifiers for a document with that track on it, then they will be displayed for that document. Does not return null.
- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
setTrackColoringQualifiers(java.util.List)
-
setTrackColoringQualifiers
public void setTrackColoringQualifiers(java.util.List<java.lang.String> trackColoringQualifiers)
Store on this track a list of qualifiers that this track would like the Sequence Viewer to display as Track Colors. If the Sequence Viewer hasn't already been told to display (or not display) these qualifiers for a document with that track on it, then they will be displayed for that document.- Parameters:
trackColoringQualifiers
- the qualifiers to display as Track Colors.- Since:
- API 4.60 (Geneious 5.6.0)
- See Also:
getTrackColoringQualifiers()
-
getDocumentVisibleByDefaultOn
public 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. The URN may be either that returned fromAnnotatedPluginDocument.getURN()
orPluginDocument.getURN()
. This is used for example on tracks added to contig documents. The track forwards to the referenced document and won't be visible by default when viewing the referenced document and instead will only be visible by default when viewed from that contig.- Returns:
- if this is not-null then this track is only visible by default when viewed from within document with this URN
-
setDocumentVisibleByDefaultOn
public void setDocumentVisibleByDefaultOn(URN documentVisibleByDefaultOn)
Sets the document that this track is only visible by default on. SeegetDocumentVisibleByDefaultOn()
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.- Parameters:
documentVisibleByDefaultOn
- the document that this track is only visible by default on or null.
-
getSuggestedTrackNameSuffixForAlignmentWithReferenceSequence
public static java.lang.String getSuggestedTrackNameSuffixForAlignmentWithReferenceSequence(AnnotatedPluginDocument document, SequenceAlignmentDocument alignment)
Returns a suggested track name suffix to use for tracks created on an alignment with a reference sequence. This is usually the name of the sample assembled to the reference sequence). For example the variant finder appends this suffix to the text "Variants" to form the track name- Parameters:
document
- the document the alignment or contig came from.alignment
- the alignment or contig- Returns:
- a suggested track name suffix or an empty string if the alignment doesn't have a reference sequence
- Since:
- API 4.600 (Geneious 6.0.0)
-
getTracks
public static java.util.List<SequenceTrack> getTracks(SequenceDocument sequence)
Gets all tracks from a sequence- Parameters:
sequence
- the sequence to get all tracks from- Returns:
- all the tracks, or an empty list if this sequence doesn't have any tracks. Will never return null.
- Since:
- API 4.202020 (Geneious 2020.2.0)
-
getTrack
public static SequenceTrack getTrack(SequenceDocument sequence, java.lang.String trackName)
Gets a track by name from a sequence- Parameters:
sequence
- the sequence which contains the tracktrackName
- the name of the track (@linkgetName()
)- Returns:
- the track or null if this sequence does not have a track with this name
- Since:
- API 4.202020 (Geneious 2020.2.0)
-
-