Class SequencePropertiesStorage

java.lang.Object
com.biomatters.geneious.publicapi.implementations.sequence.SequencePropertiesStorage
All Implemented Interfaces:
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.
  • 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)
    • 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:
    • 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:
    • toXML

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

      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)
    • 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)