org.biojava.bio.dist
Class DistributionTools

java.lang.Object
  org.biojava.bio.dist.DistributionTools

public final class DistributionTools
extends Object

A class to hold static methods for calculations and manipulations using Distributions.

Since:

1.2

Author:

Mark Schreiber, Matthew Pocock

Method Summary

static boolean	areEmissionSpectraEqual(Distribution[] a, Distribution[] b) Compares the emission spectra of two distribution arrays.
static boolean	areEmissionSpectraEqual(Distribution a, Distribution b) Compares the emission spectra of two distributions.
static Distribution	average(Distribution[] dists) Averages two or more distributions.
static double	bitsOfInformation(Distribution observed) Calculates the total bits of information for a distribution.
static Distribution	countToDistribution(Count c) Make a distribution from a count.
static Distribution[]	distOverAlignment(Alignment a) Equivalent to distOverAlignment(a, false, 0.0).
static Distribution[]	distOverAlignment(Alignment a, boolean countGaps) Creates an array of distributions, one for each column of the alignment.
static Distribution[]	distOverAlignment(Alignment a, boolean countGaps, double nullWeight) Creates an array of distributions, one for each column of the alignment.
protected static Sequence	generateOrderNSequence(String name, OrderNDistribution d, int length) Deprecated. use generateSequence() or generateSymbolList() instead.
static Sequence	generateSequence(String name, Distribution d, int length) Produces a sequence by randomly sampling the Distribution.
static SymbolList	generateSymbolList(Distribution d, int length) Produces a SymbolList by randomly sampling a Distribution.
static Distribution	jointDistOverAlignment(Alignment a, boolean countGaps, double nullWeight, int[] cols) Creates a joint distribution.
static HashMap	KLDistance(Distribution observed, Distribution expected, double logBase) A method to calculate the Kullback-Liebler Distance (relative entropy).
static void	randomizeDistribution(Distribution d) Randomizes the weights of a Distribution.
static Distribution	readFromXML(InputStream is) Read a distribution from XML.
static HashMap	shannonEntropy(Distribution observed, double logBase) A method to calculate the Shannon Entropy for a Distribution.
static double	totalEntropy(Distribution observed) Calculates the total Entropy for a Distribution.
static void	writeToXML(Distribution d, OutputStream os) Writes a Distribution to XML that can be read with the readFromXML method.

Methods inherited from class java.lang.Object

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

Method Detail

writeToXML

public static void writeToXML(Distribution d,
                              OutputStream os)
                       throws IOException

Writes a Distribution to XML that can be read with the readFromXML method.

Parameters:

d - the Distribution to write.

os - where to write it to.

Throws:

IOException - if writing fails

readFromXML

public static Distribution readFromXML(InputStream is)
                                throws IOException,
                                       SAXException

Read a distribution from XML.

Parameters:

is - an InputStream to read from

Returns:

a Distribution parameterised by the xml in is

Throws:

IOException - if is failed

SAXException - if is could not be processed as XML

randomizeDistribution

public static void randomizeDistribution(Distribution d)
                                  throws ChangeVetoException

Randomizes the weights of a Distribution.

Parameters:

d - the Distribution to randomize

Throws:

ChangeVetoException - if the Distribution is locked

countToDistribution

public static Distribution countToDistribution(Count c)

Make a distribution from a count.

Parameters:

c - the count

Returns:

a Distrubution over the same FiniteAlphabet as c and trained with the counts of c

areEmissionSpectraEqual

public static final boolean areEmissionSpectraEqual(Distribution a,
                                                    Distribution b)
                                             throws BioException

Compares the emission spectra of two distributions.

Parameters:

a - A Distribution with the same Alphabet as b

b - A Distribution with the same Alphabet as a

Returns:

true if alphabets and symbol weights are equal for the two distributions.

Throws:

BioException - if one or both of the Distributions are over infinite alphabets.

Since:

1.2

areEmissionSpectraEqual

public static final boolean areEmissionSpectraEqual(Distribution[] a,
                                                    Distribution[] b)
                                             throws BioException

Compares the emission spectra of two distribution arrays.

Parameters:

a - A Distribution[] consisting of Distributions over a FiniteAlphabet

b - A Distribution[] consisting of Distributions over a FiniteAlphabet

Returns:

true if alphabets and symbol weights are equal for each pair of distributions. Will return false if the arrays are of unequal length.

Throws:

BioException - if one of the Distributions is over an infinite alphabet.

Since:

1.3

KLDistance

public static final HashMap KLDistance(Distribution observed,
                                       Distribution expected,
                                       double logBase)

A method to calculate the Kullback-Liebler Distance (relative entropy).

Parameters:

logBase - - the log base for the entropy calculation. 2 is standard.

observed - - the observed frequence of Symbols .

expected - - the excpected or background frequency.

Returns:

- A HashMap mapping Symbol to (Double) relative entropy.

Since:

1.2

shannonEntropy

public static final HashMap shannonEntropy(Distribution observed,
                                           double logBase)

A method to calculate the Shannon Entropy for a Distribution.

Parameters:

logBase - - the log base for the entropy calculation. 2 is standard.

observed - - the observed frequence of Symbols .

Returns:

- A HashMap mapping Symbol to (Double) entropy.

Since:

1.2

totalEntropy

public static double totalEntropy(Distribution observed)

Calculates the total Entropy for a Distribution. Entropies for individual Symbols are weighted by their probability of occurence.

Parameters:

observed - the observed frequence of Symbols .

Returns:

the total entropy of the Distribution .

bitsOfInformation

public static final double bitsOfInformation(Distribution observed)

Calculates the total bits of information for a distribution.

Parameters:

observed - - the observed frequence of Symbols .

Returns:

the total information content of the Distribution .

Since:

1.2

distOverAlignment

public static Distribution[] distOverAlignment(Alignment a)
                                        throws IllegalAlphabetException

Equivalent to distOverAlignment(a, false, 0.0).

Parameters:

a - the Alignment

Returns:

an array of Distribution instances representing columns of the alignment

Throws:

IllegalAlphabetException - if the alignment alphabet is not compattible

jointDistOverAlignment

public static final Distribution jointDistOverAlignment(Alignment a,
                                                        boolean countGaps,
                                                        double nullWeight,
                                                        int[] cols)
                                                 throws IllegalAlphabetException

Creates a joint distribution.

Parameters:

a - the Alignment to build the Distribution[] over.

countGaps - if true gaps will be included in the distributions (NOT YET IMPLEMENTED!!, CURRENTLY EITHER OPTION WILL PRODUCE THE SAME RESULT)

nullWeight - the number of pseudo counts to add to each distribution

cols - a list of positions in the alignment to include in the joint distribution

Returns:

a Distribution

Throws:

IllegalAlphabetException - if all sequences don't use the same alphabet

Since:

1.2

distOverAlignment

public static final Distribution[] distOverAlignment(Alignment a,
                                                     boolean countGaps,
                                                     double nullWeight)
                                              throws IllegalAlphabetException

Creates an array of distributions, one for each column of the alignment.

Parameters:

a - the Alignment to build the Distribution[] over.

countGaps - if true gaps will be included in the distributions

nullWeight - the number of pseudo counts to add to each distribution, pseudo counts will not affect gaps, no gaps, no gap counts.

Returns:

a Distribution[] where each member of the array is a Distribution of the Symbols found at that position of the Alignment .

Throws:

IllegalAlphabetException - if all sequences don't use the same alphabet

Since:

1.2

distOverAlignment

public static final Distribution[] distOverAlignment(Alignment a,
                                                     boolean countGaps)
                                              throws IllegalAlphabetException

Creates an array of distributions, one for each column of the alignment. No pseudo counts are used.

Parameters:

countGaps - if true gaps will be included in the distributions

a - the Alignment to build the Distribution[] over.

Returns:

a Distribution[] where each member of the array is a Distribution of the Symbols found at that position of the Alignment .

Throws:

IllegalAlphabetException - if the alignment is not composed from sequences all with the same alphabet

Since:

1.2

average

public static final Distribution average(Distribution[] dists)

Averages two or more distributions. NOTE the current implementation ignore the null model.

Parameters:

dists - the Distributions to average

Returns:

a Distribution were the weight of each Symbol is the average of the weights of that Symbol in each Distribution .

Since:

1.2

generateSequence

public static final Sequence generateSequence(String name,
                                              Distribution d,
                                              int length)

Produces a sequence by randomly sampling the Distribution.

Parameters:

name - the name for the sequence

d - the distribution to sample. If this distribution is of order N a seed sequence is generated allowed to 'burn in' for 1000 iterations and used to produce a sequence over the conditioned alphabet.

length - the number of symbols in the sequence.

Returns:

a Sequence with name and urn = to name and an Empty Annotation.

generateSymbolList

public static final SymbolList generateSymbolList(Distribution d,
                                                  int length)

Produces a SymbolList by randomly sampling a Distribution.

Parameters:

d - the distribution to sample. If this distribution is of order N a seed sequence is generated allowed to 'burn in' for 1000 iterations and used to produce a sequence over the conditioned alphabet.

length - the number of symbols in the sequence.

Returns:

a SymbolList or length length

generateOrderNSequence

protected static final Sequence generateOrderNSequence(String name,
                                                       OrderNDistribution d,
                                                       int length)

Deprecated. use generateSequence() or generateSymbolList() instead.

Generate a sequence by sampling a distribution.

Parameters:

name - the name of the sequence

d - the distribution to sample

length - the length of the sequence

Returns:

a new sequence with the required composition