Models

Class Model

java.lang.Object

Models.Model

All Implemented Interfaces:

java.lang.Iterable<RateCategory>

public class Model
extends java.lang.Object
implements java.lang.Iterable<RateCategory>

Represents an evolutionary model. May contain many different RateCategory.

Rates and frequencies within a model (including the frequency of the different rate classes) are represent by strings. These strings may contain "parameters" represented by a letter followed by alphanumeric characters which may later (see Parameter) be assigned a fixed value or optimised. They may also contain numbers and mathematical operations. See FunctionParser for more on how these rates are evaluated.

Version:

2.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Model.ModelException Exception thrown when there is a problem with the model

Constructor Summary

Constructors

Constructor and Description
Model(java.util.Map<RateCategory,java.lang.String> freq) Creates a new model with multiple rate classes
Model(RateCategory r) Creates a new model with a single rate class

Method Summary

Methods

Modifier and Type	Method and Description
static Model	fromFile(java.io.File f) Creates a new model from a file.
static Model	gammaRates(RateCategory r, java.lang.String gamma, int cats) Creates a new model with multiple rate classes distributed by a gamma distribution (see Yang 1993) based on a single rate class
double	getFreq(RateCategory r) Gets the frquency of a rate class
java.util.Map<java.lang.String,java.lang.Integer>	getMap() Gets a map from the rate name to its index in the rate matrix
int	getNumberStates() Get the number of states represented in the model
java.util.Set<RateCategory>	getRates() Gets a set of rate classes in the model
double	getScale() Gets the scale - the value the rate matrices need to be multiplied by to ensure an average rate of 1.
java.util.Set<java.lang.String>	getStates() Gets the set of all states in the model
boolean	hasSingleRate() Tests whether the model has a single rate class.
java.util.Iterator<RateCategory>	iterator()
void	setParameters(Parameters p) Sets the parameters of a model to the values contained in the Parameters data structure.
void	setRescale(boolean rescale) Sets whether the matrix should be rescaled so the average rate of change is one.

Methods inherited from class java.lang.Object

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

Constructor Detail

Model

public Model(RateCategory r)

Creates a new model with a single rate class

Parameters:

r - The single rate class

Model

public Model(java.util.Map<RateCategory,java.lang.String> freq)
      throws Model.ModelException

Creates a new model with multiple rate classes

Parameters:

freq - A map from the rate classes in the model to the frequency of the rate class (as a String - see the introduction to this class). Frequencies need not sum to one as they are rescaled to do so.

Throws:

Model.ModelException - If the states in each of the rate classes are not identical.

Method Detail

getNumberStates

public int getNumberStates()

Get the number of states represented in the model

Returns:

The number of states in the model

getMap

public java.util.Map<java.lang.String,java.lang.Integer> getMap()

Gets a map from the rate name to its index in the rate matrix

Returns:

Map from rate name to index

getStates

public java.util.Set<java.lang.String> getStates()

Gets the set of all states in the model

Returns:

The set of all states

getFreq

public double getFreq(RateCategory r)

Gets the frquency of a rate class

Parameters:

r - The rate class to get the frquency for

Returns:

The frequency of the rate class

setParameters

public void setParameters(Parameters p)
                   throws RateCategory.RateException,
                          Model.ModelException,
                          Parameters.ParameterException

Sets the parameters of a model to the values contained in the Parameters data structure.

Parameters:

p - The parameter values

Throws:

RateCategory.RateException - If there is an error while setting the parameter values for one of the rate classes.

Model.ModelException - If there is an error while setting the parameter values for the frequency of the rate classes.

Parameters.ParameterException - If a parameter that needs to be set for this model has not been passed

getScale

public double getScale()

Gets the scale - the value the rate matrices need to be multiplied by to ensure an average rate of 1.

Returns:

The scale

hasSingleRate

public boolean hasSingleRate()

Tests whether the model has a single rate class.

Returns:

Whether this model has a single rate class.

iterator

public java.util.Iterator<RateCategory> iterator()

Specified by:

iterator in interface java.lang.Iterable<RateCategory>

getRates

public java.util.Set<RateCategory> getRates()

Gets a set of rate classes in the model

Returns:

The set of rate classes in the model

setRescale

public void setRescale(boolean rescale)

Sets whether the matrix should be rescaled so the average rate of change is one. By default this is true as the rate will be confounded with branch lengths if both are being estimated, however if branch lengths are fixed rescaling may be inappropiate

Note: Particular care should be taken when deciding not to rescale to ensure that parameters you are estimating are not confounded.

Parameters:

rescale - Whether to rescale

gammaRates

public static Model gammaRates(RateCategory r,
               java.lang.String gamma,
               int cats)

Creates a new model with multiple rate classes distributed by a gamma distribution (see Yang 1993) based on a single rate class

Parameters:

r - The rate class to base the model on

gamma - The value of gamma as a string (as it will be evaluated)

cats - The number of categories, or rate classes, in the new model

Returns:

The model

fromFile

public static Model fromFile(java.io.File f)
                      throws InputException,
                             Model.ModelException,
                             RateCategory.RateException

Creates a new model from a file. The first line controls the type of model. Possible types and the subsequent format of the rest of the file are:

• Gamma distributed rate categories
  • First line should start "**G" (without the quotes) followed by a tab, followed by the parameter name the alpha value is to be called by. This should be followed a tab and the number of categories desired.
  • Second line should contain a file path to the RateCategory file that describes the basic model.
• Equally likely rate categories
  • First line should contain "**E" (without the quotes)
  • Subsequent lines should each contain a file path to a RateCategory file
• Given frequency rate categories
  • First line should contain "**F" (without the quotes)
  • Subsequent lines should each contain an equation describing the frequency of that ratecategory (see MathsParse for the format of this equation) followed by a tab followed by a file path to a RateCategoy file.

Parameters:

f - The input file

Returns:

The model

Throws:

InputException - If there is an exception reading a file

Model.ModelException - If there is a problem initialising the model

RateCategory.RateException - If there is a problem with one of the Rate Categories in the model