Package com.biomatters.geneious.publicapi.implementations.sequence

Class SequencePropertiesStorage

java.lang.Object

com.biomatters.geneious.publicapi.implementations.sequence.SequencePropertiesStorage

All Implemented Interfaces:

NucleotideGraph, XMLSerializable, XMLSerializable.OldVersionCompatible, SequenceTrack.Manager.Provider

public class SequencePropertiesStorage
extends Object
implements NucleotideGraph, XMLSerializable, XMLSerializable.OldVersionCompatible, SequenceTrack.Manager.Provider

Provides supporting functionality for sequence classes that need to store various sequence properties and serialise those to XML. As at 2008-01-22, this class implements EditableSequenceDocument, EditableNucleotideGraphSequenceDocument EXCEPT that getSequenceString() and getCharSequence() may return null. For consistency the methods should remain named the same way as those in the SequenceDocuments, however because of the above difference an object of this class should never be passed anywhere as a SequenceDocument.

Nested Class Summary

Nested classes/interfaces inherited from interface com.biomatters.geneious.publicapi.documents.sequence.NucleotideGraph

NucleotideGraph.ImmutableGraphProvider

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
SequencePropertiesStorage()	Default constructor with no arguments.
SequencePropertiesStorage(org.jdom.Element element)	Constructs a SequencePropertiesStorage object from a JDOM XML Element.

Method Summary

Modifier and Type	Method	Description
static byte[]	byteArrayFromXML(org.jdom.Element element)	Converts some xml created from a preious call to byteArrayToXML(String, byte[]) (String, int[])} back to a byte array.
static org.jdom.Element	byteArrayToXML(String elementName, byte[] values)	Converts a byte array to xml, storing them in a compact way if possible.
void	fromXML(org.jdom.Element root)	Restore the object from the JDOM Element returned by XMLSerializable.toXML().
void	fromXML(org.jdom.Element root, NucleotideGraph overriddenGraph)	Deprecated.
SequenceCharSequence	getCharSequence()
int	getChromatogramLength()	The number of points for which this graph has values, which is typically larger than the length of the nucleotide sequence because a base isn't called at every position in the graph.
int	getChromatogramPositionForResidue(int residueIndex)	The graph position (can be used as an argument to NucleotideGraph.getChromatogramValue(int, int)) where the nucleotide at the specified residue index has been called.
int	getChromatogramValue(int nucleotideStateNumber, int residuePosition)	Returns the graph value for the specified nucleotide and at the specified position.
Date	getCreationDate()	This method is not implemented.
String	getDescription()
List<DocumentField>	getDisplayableFields()	This method is not implemented.
Object	getFieldValue(String fieldCodeName)	This method is not implemented.
NucleotideGraph	getGraph()
String	getName()
String	getProperty(String propertyKey)	Returns a value from the internal properties object.
List<SequenceAnnotation>	getSequenceAnnotations()
int	getSequenceLength()	The length of the nucleotide sequence that can be annotated with this graph.
int	getSequenceQuality(int residueIndex)	Returns a measurement of confidence in the residue reported at the specified residueIndex in the sequence.
final String	getSequenceString()
SequenceTrack.Manager	getTrackManager(boolean mayReturnNullIfNoTracks)	Gets a SequenceTrack.Manager associated with this sequence for providing sequence tracks.
URN	getURN()	This method is not implemented.
Geneious.MajorVersion	getVersionSupport(XMLSerializable.VersionSupportType versionType)	Gets either the latest version this class can serialize to via XMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener) or the most recent version in which the XML returned from XMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener) last changed.
boolean	hasChromatogramPositionsForResidues()	Tests whether this NucleotideGraph contains information about the position of the base calls, i.e.
boolean	hasChromatogramValues(int nucleotideStateNumber)	Specifies whether it is legal to call NucleotideGraph.getChromatogramValue(int, int) for the specified nucleotide.
boolean	hasGraph()
boolean	hasSequenceQualities()	Tests whether this graph contains information about the confidence in the associated sequence's residues, i.e.
boolean	hasSetCircular()	Returns true if setCircular(boolean) has ever been called on this storage properties
static int[]	integerArrayFromXML(org.jdom.Element element)	Converts some xml created from a preious call to integerArrayToXML(String, int[]) back to an integer array.
static org.jdom.Element	integerArrayToXML(Geneious.MajorVersion version, String elementName, int[] values)	Converts an integer array to xml, storing them in a compact way if possible.
static org.jdom.Element	integerArrayToXML(String elementName, int[] values)	Converts an integer array to xml, storing them in a compact way if possible.
boolean	isCircular()
void	setAnnotations(List<SequenceAnnotation> annotations)	See SequenceDocumentWithEditableAnnotations.setAnnotations(java.util.List)
void	setCircular(boolean circular)
void	setDescription(String description)	Set the human-readable graph description.
void	setName(String name)	Set the name of the graph.
void	setProperty(String propertyKey, String value)	Sets a value on the internal properties object.
void	setSequenceAndAnnotations(CharSequence sequence, List<SequenceAnnotation> annotations)	Equivalent to EditableSequenceDocument.setSequenceAndAnnotations(CharSequence,java.util.List).
void	setSequenceAndAnnotationsAndGraph(CharSequence sequence, List<SequenceAnnotation> annotations, NucleotideGraph graph)	Same as EditableNucleotideGraphSequenceDocument.setSequenceAndAnnotationsAndGraph(CharSequence, java.util.List, com.biomatters.geneious.publicapi.documents.sequence.NucleotideGraph) except that sequence may be null.
String	toHTML()	This method is not implemented.
org.jdom.Element	toXML()	Convert object to a JDOM element.
org.jdom.Element	toXML(Geneious.MajorVersion majorVersion, ProgressListener progressListener)	Serializes this class to XML format, potentially to a format readable by an earlier version of Geneious.
org.jdom.Element	toXML(String elementName)	Convert object to a JDOM Element with the given name as the name of the root element.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.biomatters.geneious.publicapi.documents.sequence.NucleotideGraph

getChromatogramPositionsForResidues, getChromatogramValues, getSequenceQualities

Constructor Details

SequencePropertiesStorage

public SequencePropertiesStorage()

Default constructor with no arguments.

SequencePropertiesStorage

public SequencePropertiesStorage(org.jdom.Element element)
                          throws XMLSerializationException

Constructs a SequencePropertiesStorage object from a JDOM XML Element.

Parameters:

element - a JDOM XML Element representing a SequencePropertiesStorage object

Throws:

XMLSerializationException - if the SequencePropertiesStorage can't be reconstructed from the specified element for some reason

Method Details

setSequenceAndAnnotations

public void setSequenceAndAnnotations(CharSequence sequence,
 List<SequenceAnnotation> annotations)

Equivalent to EditableSequenceDocument.setSequenceAndAnnotations(CharSequence,java.util.List). except that null sequences or a null list of annotations are allowed.

setAnnotations

public void setAnnotations(List<SequenceAnnotation> annotations)

See SequenceDocumentWithEditableAnnotations.setAnnotations(java.util.List)

setName

public void setName(String name)

Set the name of the graph.

Parameters:

name - the name of the graph

setDescription

public void setDescription(String description)

Set the human-readable graph description.

Parameters:

description - the human-readable graph description

getName

public String getName()

getProperty

public String getProperty(String propertyKey)

Returns a value from the internal properties object.

Parameters:

propertyKey - key whose associated value is to be returned

Returns:

the value to which this map maps the specified key, or null if the map contains no mapping for this key

See Also:

• Map.get(Object)

setProperty

public void setProperty(String propertyKey,
 String value)

Sets a value on the internal properties object.

Parameters:

propertyKey - key with which the specified value is to be associated

value - value to be associated with the specified key

getDescription

public String getDescription()

getSequenceString

public final String getSequenceString()

getCharSequence

public SequenceCharSequence getCharSequence()

getSequenceAnnotations

public List<SequenceAnnotation> getSequenceAnnotations()

Returns:

the annotations stored by this class using setAnnotations(java.util.List) or null if setAnnotations(java.util.List) has not been called.

getVersionSupport

public Geneious.MajorVersion getVersionSupport(XMLSerializable.VersionSupportType versionType)

Description copied from interface: XMLSerializable.OldVersionCompatible

Gets either the latest version this class can serialize to via XMLSerializable.OldVersionCompatible.toXML(Geneious.MajorVersion, ProgressListener) or the most recent version in which the XML returned from XMLSerializable.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 interface XMLSerializable.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(String elementName)

Convert object to a JDOM Element with the given name as the name of the root element.

Parameters:

elementName - the name of the root element

Returns:

object encoded as a JDOM XML element or possibly null if there is no data to store.

See Also:

• XMLSerializable.toXML()

toXML

public org.jdom.Element toXML(Geneious.MajorVersion majorVersion,
 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.

See XMLSerializable.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 interface XMLSerializable.OldVersionCompatible

Parameters:

majorVersion - 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 from getVersionSupport(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

integerArrayToXML

public static org.jdom.Element integerArrayToXML(String elementName,
 int[] values)

Converts an integer array to xml, storing them in a compact way if possible.

Parameters:

elementName - the name of the element to return.

values - the values to serialize to xml. Must not be null.

Returns:

an element that can be converted back to an integer array using integerArrayArrayFromXML(org.jdom.Element).

Since:

API 4.11 (Geneious 5.0)

integerArrayToXML

public static org.jdom.Element integerArrayToXML(Geneious.MajorVersion version,
 String elementName,
 int[] values)

Converts an integer array to xml, storing them in a compact way if possible.

Parameters:

version - the version number of Geneious that must be able to deserialize this. All versions of Geneious from 6.0 onwards are and always will be supported.

elementName - the name of the element to return.

values - the values to serialize to xml. Must not be null.

Returns:

an element that can be converted back to an integer array using integerArrayArrayFromXML(org.jdom.Element).

Since:

API 4.600 (Geneious 6.0.0)

byteArrayToXML

public static org.jdom.Element byteArrayToXML(String elementName,
 byte[] values)

Converts a byte array to xml, storing them in a compact way if possible.

Parameters:

elementName - the name of the element to return.

values - the values to serialize to xml. Must not be null.

Returns:

an element that can be converted back to an integer array using byteArrayFromXML(org.jdom.Element)

Since:

API 4.11 (Geneious 5.0)

integerArrayFromXML

public static int[] integerArrayFromXML(org.jdom.Element element)

Converts some xml created from a preious call to integerArrayToXML(String, int[]) back to an integer array.

Parameters:

element - the element to convert to an array. May be null, in which case this method returns null.

Returns:

an integer array or null if element was null.

Since:

API 4.11 (Geneious 5.0)

byteArrayFromXML

public static byte[] byteArrayFromXML(org.jdom.Element element)

Converts some xml created from a preious call to byteArrayToXML(String, byte[]) (String, int[])} back to a byte array.

Parameters:

element - the element to convert to an array. May be null, in which case this method returns null.

Returns:

a byte array or null if element was null.

Since:

API 4.11 (Geneious 5.0)

fromXML

@Deprecated
public void fromXML(org.jdom.Element root,
 NucleotideGraph overriddenGraph)
             throws XMLSerializationException

Deprecated.

Backwards compatibility XML deserialization of SequencePropertiesStorage which overrides another NucleotideGraph and which was stored by Geneious 3.5.x or earlier. In these versions, it was possible to override only certain aspects of a NucleotideGraph, so that when those aspects are missing in the XML File they must be read from the overriden chromatogram instead. New code introduced for Geneious 3.6 or later (which will only encounter XML serialized by version 3.6 or later) should never need to call this method, and should instead just call fromXML(org.jdom.Element).

Parameters:

root - Element from which to XML deserialize (same as in fromXML(org.jdom.Element)

overriddenGraph - The graph from which to take chromatogram and sequence lengths if they are not specified in the XML. May be null if these properties override no other graph and root must contain specification of a legal graph by itself.

Throws:

XMLSerializationException - If the Element passed in (plus optionally overriddenGraph) is not a valid serialization of a NucleotideGraph

fromXML

public void fromXML(org.jdom.Element root)
             throws XMLSerializationException

Description copied from interface: XMLSerializable

Restore the object from the JDOM Element returned by XMLSerializable.toXML().

This method generally should not be called directly. Instead, you should usually call XMLSerializer.classFromXML(org.jdom.Element) or XMLSerializer.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 single Element 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 with Element.clone().

Specified by:

fromXML in interface XMLSerializable

Parameters:

root - representation from a previous call to XMLSerializable.toXML()

Throws:

XMLSerializationException - if the Element can't be converted into this type of object

hasChromatogramPositionsForResidues

public boolean hasChromatogramPositionsForResidues()

Description copied from interface: NucleotideGraph

Tests whether this NucleotideGraph contains information about the position of the base calls, i.e. whether it is legal to call NucleotideGraph.getChromatogramPositionForResidue(int).

Specified by:

hasChromatogramPositionsForResidues in interface NucleotideGraph

Returns:

true if this NucleotideGraph contains information about the position of the base calls.

getChromatogramPositionForResidue

public int getChromatogramPositionForResidue(int residueIndex)

Description copied from interface: NucleotideGraph

The graph position (can be used as an argument to NucleotideGraph.getChromatogramValue(int, int)) where the nucleotide at the specified residue index has been called. This method may only be called if NucleotideGraph.hasChromatogramPositionsForResidues() returns true. The graph sites are guaranteed to have the same order as the sequence nucleotides. Therefore, any implementation must ensure that if i < j, then getChromatogramPositionForResidue(i) <= getChromatogramPositionForResidue(j).

Specified by:

getChromatogramPositionForResidue in interface NucleotideGraph

Parameters:

residueIndex - A value 0 <= residueIndex < NucleotideGraph.getSequenceLength() specifying the index in the nucleotide sequence for which to calculate the corresponding position in the graph.

Returns:

A value in the range 0 <= value < NucleotideGraph.getChromatogramLength(), specifiying the graph position where the nucleotide that is at position residueIndex has been called. For positions residueIndex where the sequence length consisting of values between 0 and getChromatogramLength()-1 inclusive. For a residueIndex where the sequence holds a '-', the returned site position must always be Integer.MIN_VALUE.

getSequenceLength

public int getSequenceLength()

Description copied from interface: NucleotideGraph

The length of the nucleotide sequence that can be annotated with this graph. If a class implements both this interface and SequenceDocument, then the return value of this method must be equal to getCharSequence().length() Also if NucleotideGraph.hasChromatogramPositionsForResidues() or NucleotideGraph.hasSequenceQualities() is true, the return value indicates the range of legal values to pass to NucleotideGraph.getChromatogramPositionForResidue(int) and NucleotideGraph.getSequenceQuality(int).

Specified by:

getSequenceLength in interface NucleotideGraph

Returns:

length of the nucleotide sequence belonging to this graph.

hasSequenceQualities

public boolean hasSequenceQualities()

Description copied from interface: NucleotideGraph

Tests whether this graph contains information about the confidence in the associated sequence's residues, i.e. whether it is legal to call NucleotideGraph.getSequenceQuality(int).

Specified by:

hasSequenceQualities in interface NucleotideGraph

Returns:

true if it is legal to call NucleotideGraph.getSequenceQuality(int) on this graph.

getSequenceQuality

public int getSequenceQuality(int residueIndex)

Description copied from interface: NucleotideGraph

Returns a measurement of confidence in the residue reported at the specified residueIndex in the sequence. The measure is on a logaritmic scale: P(call correct) = 1 - 10^(-v/10) where v is the quality returned from this method.

If the sequence contains a gap at the specified position, this method should return Integer.MIN_VALUE if it is an end gap. If it is an internal gap, it should return the average quality of the non-gap positions on either side of the gap.

This method may only be called if NucleotideGraph.hasSequenceQualities() returns true.

Specified by:

getSequenceQuality in interface NucleotideGraph

Parameters:

residueIndex - A value 0 <= residueIndex < NucleotideGraph.getSequenceLength() specifying the index in the nucleotide sequence for which to calculate the quality of the graph.

Returns:

The quality score v for the residue at the specified index in the nucleotide sequence, which indicates the reliability of the nucleotide on a logarithmic scale as described above. For all positions other than end-gaps, this must be non-negative (since below 0 would imply a negative probability)

getChromatogramLength

public int getChromatogramLength()

Description copied from interface: NucleotideGraph

The number of points for which this graph has values, which is typically larger than the length of the nucleotide sequence because a base isn't called at every position in the graph.

Specified by:

getChromatogramLength in interface NucleotideGraph

Returns:

the length of this graph, or 0 if this graph has no graph values for any nucleotide (i.e. 0 if NucleotideGraph.hasChromatogramPositionsForResidues() is false).

hasChromatogramValues

public boolean hasChromatogramValues(int nucleotideStateNumber)

Description copied from interface: NucleotideGraph

Specifies whether it is legal to call NucleotideGraph.getChromatogramValue(int, int) for the specified nucleotide.

Specified by:

hasChromatogramValues in interface NucleotideGraph

Parameters:

nucleotideStateNumber - A nucleotide state number encoded in the same way as for NucleotideGraph.getChromatogramValue(int, int), i.e. 0 = A, 1 = C, 2 = G, 3 = T

Returns:

true if is legal to call NucleotideGraph.getChromatogramValue(int, int) for the specified nucleotide

getChromatogramValue

public int getChromatogramValue(int nucleotideStateNumber,
 int residuePosition)

Description copied from interface: NucleotideGraph

Returns the graph value for the specified nucleotide and at the specified position. If the graph is a chromatogram, this is a measure of the support for the specified nucleotide at this position. May only be called if NucleotideGraph.hasChromatogramValues(int) returns true for the specified nucleotide.

Specified by:

getChromatogramValue in interface NucleotideGraph

Parameters:

nucleotideStateNumber - The nucleotide for which to retrieve the graph value, encoded as 0 = A, 1 = C, 2 = G, 3 = T (alphabetic order, same as in Nucleotides)

residuePosition - The position in the sequence for which to query the graph value, with 0 <= graphPosition < graph length

Returns:

the graph value for the specified nucleotide and at the specified position.

getGraph

public NucleotideGraph getGraph()

setSequenceAndAnnotationsAndGraph

public void setSequenceAndAnnotationsAndGraph(CharSequence sequence,
 List<SequenceAnnotation> annotations,
 NucleotideGraph graph)

Same as EditableNucleotideGraphSequenceDocument.setSequenceAndAnnotationsAndGraph(CharSequence, java.util.List, com.biomatters.geneious.publicapi.documents.sequence.NucleotideGraph) except that sequence may be null.

getDisplayableFields

public List<DocumentField> getDisplayableFields()

This method is not implemented. It always throws an UnsupportedOperationException.

Returns:

never returns. Always throws UnsupportedOperationException.

Throws:

UnsupportedOperationException - always

getFieldValue

public Object getFieldValue(String fieldCodeName)

This method is not implemented. It always throws an UnsupportedOperationException.

Parameters:

fieldCodeName - ignored

Returns:

never returns. Always throws UnsupportedOperationException.

Throws:

UnsupportedOperationException - always

getURN

public URN getURN()

This method is not implemented. It always throws an UnsupportedOperationException.

Returns:

never returns. Always throws UnsupportedOperationException.

Throws:

UnsupportedOperationException - always

getCreationDate

public Date getCreationDate()

This method is not implemented. It always throws an UnsupportedOperationException.

Returns:

never returns. Always throws UnsupportedOperationException.

Throws:

UnsupportedOperationException - always

toHTML

public String toHTML()

This method is not implemented. It always throws an UnsupportedOperationException.

Returns:

never returns. Always throws UnsupportedOperationException.

Throws:

UnsupportedOperationException - always

toXML

public org.jdom.Element toXML()

Description copied from interface: XMLSerializable

Convert object to a JDOM element. The representation should be complete so that XMLSerializable.fromXML(org.jdom.Element) can completely restore the object's representation.

It is recommended that the returned element use XMLSerializable.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 call XMLSerializer.classToXML(String, XMLSerializable) which calls this method internally.

PluginDocument implementations of this method may choose to throw an XMLSerializationException, enclosed in a RuntimeException.

Specified by:

toXML in interface XMLSerializable

Returns:

object encoded as a JDOM element

setCircular

public void setCircular(boolean circular)

isCircular

public boolean isCircular()

hasSetCircular

public boolean hasSetCircular()

Returns true if setCircular(boolean) has ever been called on this storage properties

Returns:

true if setCircular(boolean) has ever been called on this storage properties.

hasGraph

public boolean hasGraph()

getTrackManager

public SequenceTrack.Manager getTrackManager(boolean mayReturnNullIfNoTracks)

Description copied from interface: SequenceTrack.Manager.Provider

Gets a SequenceTrack.Manager associated with this sequence for providing sequence tracks. For detailed information on sequence tracks, see SequenceTrack. If this method is called on an alignment, the track manager is for the consensus sequence. Individual sequences in the alignment may also implement SequenceTrack.Manager.Provider if they provide tracks.

Specified by:

getTrackManager in interface SequenceTrack.Manager.Provider

Parameters:

mayReturnNullIfNoTracks - 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 or possibly null if mayReturnNullIfNoTracks is true

Since:

API 4.900 (Geneious 9.0.0)