Models
Class Model

java.lang.Object
  extended by 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 a alphanumeric character 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:
1.0

Nested Class Summary
 class Model.ModelException
          Exception thrown when there is a problem with the model
 
Constructor Summary
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
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 Should it really be a method of Model rather than Rate
 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 ae 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 Should it really be a method of Model rather than Rate

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
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.

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 subsquent format of the rest of the file are:

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