Package com.biomatters.geneious.publicapi.documents.sequence

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)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ValueAndFrequencyDistribution.ValueAndFrequency	Represents a value and the number of occurrences of the value

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
ValueAndFrequencyDistribution()	Construct a new empty distribution.
ValueAndFrequencyDistribution(ValueAndFrequencyDistribution distribution1, ValueAndFrequencyDistribution distribution2)	Constructs a new distribution by adding 2 distributions together
ValueAndFrequencyDistribution(org.jdom.Element e)	Construct a new empty distribution from some previously serialized data.

Method Summary

Modifier and Type	Method	Description
void	addValue(long value, long frequency)	Adds a new value.
void	finishedAddingValues(ProgressListener progressListener)	Called to finalize and sort the data.
void	fromXML(org.jdom.Element element)	Restore the object from the JDOM Element returned by XMLSerializable.toXML().
long	getMax()
double	getMean()
double	getMedian()
long	getMin()
long	getNumberOfUniqueValues()	Get the number of unique values (the number of different values passed to addValue(long, long)
long	getNumberOfValues()	Get the number of values added (the sum of the frequencies passed to addValue(long, long)
Iterable<ValueAndFrequencyDistribution.ValueAndFrequency>	getValues()	Gets a sorted list of values and their frequencies.
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.
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.

Methods inherited from class java.lang.Object

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

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,
 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(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()

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:

• getNumberOfUniqueValues()

getValues

public Iterable<ValueAndFrequencyDistribution.ValueAndFrequency> 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.