Class ValueAndFrequencyDistribution

java.lang.Object
com.biomatters.geneious.publicapi.documents.sequence.ValueAndFrequencyDistribution
All Implemented Interfaces:
XMLSerializable, XMLSerializable.OldVersionCompatible

public final class ValueAndFrequencyDistribution extends Object implements XMLSerializable, XMLSerializable.OldVersionCompatible
Provides a sorted distribution of longs and the frequency of each of them. Large data sets will not be fully loaded into memory

This class is not thread safe until finishedAddingValues(jebl.util.ProgressListener) has completed, after which it is thread safe.

Since:
API 4.40 (Geneious 5.4.0)
  • Constructor Details

    • ValueAndFrequencyDistribution

      public ValueAndFrequencyDistribution()
      Construct a new empty distribution.
    • ValueAndFrequencyDistribution

      public ValueAndFrequencyDistribution(ValueAndFrequencyDistribution distribution1, ValueAndFrequencyDistribution distribution2) throws IOException
      Constructs a new distribution by adding 2 distributions together
      Parameters:
      distribution1 - the first distribution to add
      distribution2 - the second distribution to add
      Throws:
      IOException - if we can't write the data to disk.
    • ValueAndFrequencyDistribution

      public ValueAndFrequencyDistribution(org.jdom.Element e) throws XMLSerializationException
      Construct a new empty distribution from some previously serialized data.
      Parameters:
      e - the element returned frmo a previous call to toXML()
      Throws:
      XMLSerializationException - if it can't be deserialized.
  • Method Details

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

      public void fromXML(org.jdom.Element element) 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:
      element - representation from a previous call to XMLSerializable.toXML()
      Throws:
      XMLSerializationException - if the Element can't be converted into this type of object
    • addValue

      public void addValue(long value, long frequency) throws IOException
      Adds a new value. finishedAddingValues(jebl.util.ProgressListener) must be called once all values have been added.
      Parameters:
      value - the value to add
      frequency - the number of occurrences of the value to add
      Throws:
      IOException - if we can't write the data to disk.
      IllegalStateException - if finishedAddingValues(jebl.util.ProgressListener) has already been called.
    • finishedAddingValues

      public void finishedAddingValues(jebl.util.ProgressListener progressListener) throws IOException
      Called to finalize and sort the data. This method must be called after adding values using addValue(long, long) before many of the getter methods can be used.
      Parameters:
      progressListener - for handling progress and cancelling.
      Throws:
      IOException - if we can't write the data to disk or if the progress listener requests we cancel
      IllegalStateException - if this method is called more than once
    • getMin

      public long getMin()
      Returns:
      the minimum value in this distribution, or 0 if there are no values
    • getMax

      public long getMax()
      Returns:
      the maximum value in this distribution, or 0 if there are no values
    • getMedian

      public double getMedian()
      Returns:
      the median value in this distribution, or 0 if there are no values. This method calculates the median each time it is called, so may not be fast on large data sets
      Since:
      API 4.1020 (Geneious 10.2.0)
    • getMean

      public double getMean()
      Returns:
      the mean value in this distribution, or 0 if there are no values. This method calculates the mean each time it is called, so may not be fast on large data sets
      Since:
      API 4.1020 (Geneious 10.2.0)
    • getNumberOfUniqueValues

      public long getNumberOfUniqueValues()
      Get the number of unique values (the number of different values passed to addValue(long, long)
      Returns:
      the number of unique values (the number of different values passed to addValue(long, long)
      See Also:
    • getNumberOfValues

      public long getNumberOfValues()
      Get the number of values added (the sum of the frequencies passed to addValue(long, long)
      Returns:
      the number of values added (the sum of the frequencies passed to addValue(long, long)
      See Also:
    • getValues

      Gets a sorted list of values and their frequencies.
      Returns:
      a sorted list of values and their frequencies.
      Throws:
      IllegalStateException - if finishedAddingValues(jebl.util.ProgressListener) has not yet been called.