bpp-phyl  2.2.0
bpp::SubstitutionModelSet Class Reference

Substitution models manager for non-homogeneous / non-reversible models of evolution. More...

#include <Bpp/Phyl/Model/SubstitutionModelSet.h>

+ Inheritance diagram for bpp::SubstitutionModelSet:
+ Collaboration diagram for bpp::SubstitutionModelSet:

Public Member Functions

 SubstitutionModelSet (const Alphabet *alpha)
 Create a model set according to the specified alphabet. Stationarity is assumed. More...
 
 SubstitutionModelSet (const Alphabet *alpha, FrequenciesSet *rootFreqs)
 Create a model set according to the specified alphabet and root frequencies. Stationarity is not assumed. More...
 
void clear ()
 Resets all the information contained in this object. More...
 
void setRootFrequencies (FrequenciesSet *rootFreqs)
 Sets a given FrequenciesSet for root frequencies. More...
 
 SubstitutionModelSet (const SubstitutionModelSet &set)
 
SubstitutionModelSetoperator= (const SubstitutionModelSet &set)
 
virtual ~SubstitutionModelSet ()
 
SubstitutionModelSetclone () const
 
size_t getNumberOfStates () const throw (Exception)
 Get the number of states associated to this model set. More...
 
virtual void fireParameterChanged (const ParameterList &parameters)
 
size_t getNumberOfModels () const
 
bool hasMixedSubstitutionModel () const
 
const SubstitutionModelgetModel (size_t i) const throw (IndexOutOfBoundsException)
 Get one model from the set knowing its index. More...
 
SubstitutionModelgetModel (size_t i) throw (IndexOutOfBoundsException)
 
size_t getModelIndexForNode (int nodeId) const throw (Exception)
 Get the index in the set of the model associated to a particular node id. More...
 
const SubstitutionModelgetModelForNode (int nodeId) const throw (Exception)
 Get the model associated to a particular node id. More...
 
SubstitutionModelgetModelForNode (int nodeId) throw (Exception)
 
const std::vector< int > & getNodesWithModel (size_t i) const throw (IndexOutOfBoundsException)
 Get a list of nodes id for which the given model is associated. More...
 
std::vector< int > getNodesWithParameter (const std::string &name) const throw (ParameterNotFoundException)
 
void addModel (SubstitutionModel *model, const std::vector< int > &nodesId)
 Add a new model to the set, and set relationships with nodes and params. More...
 
void replaceModel (size_t modelIndex, SubstitutionModel *model) throw (Exception)
 Replace a model in the set, and all corresponding parameters. The replaced model deleted. More...
 
void listModelNames (std::ostream &out=std::cout) const
 
const FrequenciesSetgetRootFrequenciesSet () const
 
std::vector< double > getRootFrequencies () const
 
ParameterList getRootFrequenciesParameters () const
 Get the parameters corresponding to the root frequencies. More...
 
ParameterList getNodeParameters () const
 Get the parameters corresponding attached to the nodes of the tree. More...
 
ParameterList getModelParameters (size_t modelIndex) const
 Get the parameters attached to a Model. More...
 
const Alphabet * getAlphabet () const
 
virtual const std::vector< int > & getAlphabetStates () const
 
virtual const StateMapgetStateMap () const
 
virtual std::vector< size_t > getModelStates (int code) const
 
virtual std::vector< size_t > getModelStates (const std::string &code) const
 
virtual int getAlphabetStateAsInt (size_t index) const
 
virtual std::string getAlphabetStateAsChar (size_t index) const
 
bool isFullySetUpFor (const Tree &tree, bool throwEx=true) const throw (Exception)
 Check if the model set is fully specified for a given tree. More...
 

Protected Member Functions

void updateRootFrequencies ()
 
Check function.
bool checkOrphanModels (bool throwEx) const throw (Exception)
 
bool checkOrphanNodes (const Tree &tree, bool throwEx) const throw (Exception)
 
bool checkUnknownNodes (const Tree &tree, bool throwEx) const throw (Exception)
 

Protected Attributes

const Alphabet * alphabet_
 A pointer toward the common alphabet to all models in the set. More...
 
size_t nbStates_
 
std::vector< SubstitutionModel * > modelSet_
 Contains all models used in this tree. More...
 

Private Attributes

std::auto_ptr< FrequenciesSetrootFrequencies_
 Root frequencies. More...
 
std::map< int, size_t > nodeToModel_
 Contains for each node in a tree the index of the corresponding model in modelSet_. More...
 
std::map< size_t, std::vector< int > > modelToNodes_
 
std::vector< ParameterList > modelParameters_
 Parameters for each model in the set. More...
 
bool stationarity_
 

Detailed Description

Substitution models manager for non-homogeneous / non-reversible models of evolution.

This class contains a set of substitution models, and their assigment toward the branches of a phylogenetic tree. Each branch in the tree corresponds to a model in the set, but a susbstitution model may correspond to several branches. The particular case where all branches point toward a unique model is the homogeneous case.

This class also deals with the parameters associated to the models. In the homogeneous case, the parameter list is the same as the list in susbstitution model. When two models at least are specified, these models may have their own parameters or share some of them. To deal with this issue, the SubstitutionModelSet class contains its own parameter list, where parameters are numbered according to the model they belong to.

The user only act on parameters_, the fireParameterChanged function, automatically called, will update the modelParameters_ field.

In the non-homogeneous and homogeneous non-reversible cases, the likelihood depends on the position of the root. The states frequencies at the root of the tree are hence distinct parameters. Theses are accounted by a FrequenciesSet objet, managed by the SubstitutionModelSet class. The corresponding parameters, if any, are added at the begining of the global parameter list.

If the heterogenity of the model does not affect the equilibrium frequencies, the model can be considered as stationary. In such a model, the process is supposed to be at equilibrium all along the trees, including at the root. Whether a model should be considered as stationary or not is left to the user. If the "asumme stationarity" option is set when building the set, then no FrequenciesSet object is used, but the frequencies are taken to be the same as the one at the first model in the set. Nothing hence prevents you to build a "supposingly stationary model which actually is not", so be careful!!

This class provides several methods to specify which model and/or which parameter is associated to which branch/clade. Several check points are provided, but some are probably missing due to the large set of possible models that this class allows to build, so be carefull!

See also
SubstitutionModelSetTools for methods that provide instances of the SubstitutionModelSet for general cases.

Definition at line 104 of file SubstitutionModelSet.h.

Constructor & Destructor Documentation

◆ SubstitutionModelSet() [1/3]

bpp::SubstitutionModelSet::SubstitutionModelSet ( const Alphabet *  alpha)
inline

Create a model set according to the specified alphabet. Stationarity is assumed.

Parameters
alphaThe alphabet to use for this set.

Definition at line 150 of file SubstitutionModelSet.h.

Referenced by clone().

◆ SubstitutionModelSet() [2/3]

bpp::SubstitutionModelSet::SubstitutionModelSet ( const Alphabet *  alpha,
FrequenciesSet rootFreqs 
)
inline

Create a model set according to the specified alphabet and root frequencies. Stationarity is not assumed.

Parameters
alphaThe alphabet to use for this set.
rootFreqsThe frequencies at root node. The underlying object will be owned by this instance.

Definition at line 170 of file SubstitutionModelSet.h.

References setRootFrequencies().

◆ SubstitutionModelSet() [3/3]

SubstitutionModelSet::SubstitutionModelSet ( const SubstitutionModelSet set)

Definition at line 49 of file SubstitutionModelSet.cpp.

References modelSet_.

◆ ~SubstitutionModelSet()

virtual bpp::SubstitutionModelSet::~SubstitutionModelSet ( )
inlinevirtual

Definition at line 203 of file SubstitutionModelSet.h.

References modelSet_.

Member Function Documentation

◆ addModel()

void SubstitutionModelSet::addModel ( SubstitutionModel model,
const std::vector< int > &  nodesId 
)

Add a new model to the set, and set relationships with nodes and params.

Parameters
modelA pointer toward a susbstitution model, that will added to the set. Warning! The set will now be the owner of the pointer, and will destroy it if needed! Copy the model first if you don't want it to be lost!
nodesIdthe set of nodes in the tree that points toward this model. This will override any previous affectation.
Exceptions
Exceptionin case of error:
  • if the new model does not match the alphabet
  • if the new model does not have the same number of states than existing ones
  • etc.

Definition at line 135 of file SubstitutionModelSet.cpp.

References alphabet_, bpp::SubstitutionModel::clone(), bpp::SubstitutionModel::getAlphabet(), bpp::SubstitutionModel::getNumberOfStates(), modelParameters_, modelSet_, modelToNodes_, nbStates_, and nodeToModel_.

Referenced by bpp::SubstitutionModelSetTools::createHomogeneousModelSet(), bpp::SubstitutionModelSetTools::createNonHomogeneousModelSet(), and bpp::PhylogeneticsApplicationTools::setSubstitutionModelSet().

◆ checkOrphanModels()

bool SubstitutionModelSet::checkOrphanModels ( bool  throwEx) const
throw (Exception
)
protected

Definition at line 249 of file SubstitutionModelSet.cpp.

Referenced by isFullySetUpFor().

◆ checkOrphanNodes()

bool SubstitutionModelSet::checkOrphanNodes ( const Tree tree,
bool  throwEx 
) const
throw (Exception
)
protected

Definition at line 264 of file SubstitutionModelSet.cpp.

Referenced by isFullySetUpFor().

◆ checkUnknownNodes()

bool SubstitutionModelSet::checkUnknownNodes ( const Tree tree,
bool  throwEx 
) const
throw (Exception
)
protected

Definition at line 280 of file SubstitutionModelSet.cpp.

Referenced by isFullySetUpFor().

◆ clear()

void SubstitutionModelSet::clear ( )

◆ clone()

SubstitutionModelSet* bpp::SubstitutionModelSet::clone ( ) const
inline

Definition at line 213 of file SubstitutionModelSet.h.

References SubstitutionModelSet().

◆ fireParameterChanged()

void SubstitutionModelSet::fireParameterChanged ( const ParameterList &  parameters)
virtual

To be called when a parameter has changed. Depending on parameters, this will actualize the _initialFrequencies vector or the corresponding models in the set.

Parameters
parametersThe modified parameters.

Reimplemented in bpp::MixedSubstitutionModelSet.

Definition at line 231 of file SubstitutionModelSet.cpp.

References modelParameters_, modelSet_, and updateRootFrequencies().

Referenced by bpp::MixedSubstitutionModelSet::fireParameterChanged().

◆ getAlphabet()

const Alphabet* bpp::SubstitutionModelSet::getAlphabet ( ) const
inline

◆ getAlphabetStateAsChar()

virtual std::string bpp::SubstitutionModelSet::getAlphabetStateAsChar ( size_t  index) const
inlinevirtual
Parameters
indexThe model state.
Returns
The corresponding alphabet state as character code.

Definition at line 445 of file SubstitutionModelSet.h.

References bpp::SubstitutionModel::getAlphabetStateAsChar(), and getModel().

Referenced by bpp::AbstractNonHomogeneousTreeLikelihood::getAlphabetStateAsChar().

◆ getAlphabetStateAsInt()

virtual int bpp::SubstitutionModelSet::getAlphabetStateAsInt ( size_t  index) const
inlinevirtual
Parameters
indexThe model state.
Returns
The corresponding alphabet state as character code.

Definition at line 437 of file SubstitutionModelSet.h.

References bpp::SubstitutionModel::getAlphabetStateAsInt(), and getModel().

Referenced by bpp::AbstractNonHomogeneousTreeLikelihood::getAlphabetStateAsInt().

◆ getAlphabetStates()

virtual const std::vector<int>& bpp::SubstitutionModelSet::getAlphabetStates ( ) const
inlinevirtual
Returns
The supported states of the model set, as a vector of int codes.
See also
Alphabet

Definition at line 417 of file SubstitutionModelSet.h.

References bpp::SubstitutionModel::getAlphabetStates(), and getModel().

Referenced by bpp::AbstractNonHomogeneousTreeLikelihood::getAlphabetStates().

◆ getModel() [1/2]

◆ getModel() [2/2]

SubstitutionModel* bpp::SubstitutionModelSet::getModel ( size_t  i)
throw (IndexOutOfBoundsException
)
inline

Definition at line 257 of file SubstitutionModelSet.h.

References modelSet_.

◆ getModelForNode() [1/2]

const SubstitutionModel* bpp::SubstitutionModelSet::getModelForNode ( int  nodeId) const
throw (Exception
)
inline

Get the model associated to a particular node id.

Parameters
nodeIdThe id of the query node.
Returns
A pointer toward the corresponding model.
Exceptions
ExceptionIf no model is found for this node.

Definition at line 285 of file SubstitutionModelSet.h.

References modelSet_, and nodeToModel_.

Referenced by bpp::RNonHomogeneousMixedTreeLikelihood::computeTransitionProbabilitiesForNode(), bpp::AbstractNonHomogeneousTreeLikelihood::computeTransitionProbabilitiesForNode(), bpp::AbstractNonHomogeneousTreeLikelihood::getNewBranchModelIterator(), bpp::AbstractNonHomogeneousTreeLikelihood::getSubstitutionModelForNode(), and bpp::NonHomogeneousSequenceSimulator::init().

◆ getModelForNode() [2/2]

SubstitutionModel* bpp::SubstitutionModelSet::getModelForNode ( int  nodeId)
throw (Exception
)
inline

Definition at line 292 of file SubstitutionModelSet.h.

References modelSet_, and nodeToModel_.

◆ getModelIndexForNode()

size_t bpp::SubstitutionModelSet::getModelIndexForNode ( int  nodeId) const
throw (Exception
)
inline

Get the index in the set of the model associated to a particular node id.

Parameters
nodeIdThe id of the query node.
Returns
The index of the model associated to the given node.
Exceptions
ExceptionIf no model is found for this node.

Definition at line 270 of file SubstitutionModelSet.h.

References nodeToModel_.

Referenced by bpp::RNonHomogeneousMixedTreeLikelihood::computeTransitionProbabilitiesForNode().

◆ getModelParameters()

ParameterList bpp::SubstitutionModelSet::getModelParameters ( size_t  modelIndex) const

Get the parameters attached to a Model.

Parameters
modelIndexthe index of the model in the set
Returns
The parameters attached to the model.

◆ getModelStates() [1/2]

virtual std::vector<size_t> bpp::SubstitutionModelSet::getModelStates ( int  code) const
inlinevirtual

Definition at line 425 of file SubstitutionModelSet.h.

References getModel(), and bpp::SubstitutionModel::getModelStates().

◆ getModelStates() [2/2]

virtual std::vector<size_t> bpp::SubstitutionModelSet::getModelStates ( const std::string &  code) const
inlinevirtual

Definition at line 429 of file SubstitutionModelSet.h.

References getModel(), and bpp::SubstitutionModel::getModelStates().

◆ getNodeParameters()

ParameterList bpp::SubstitutionModelSet::getNodeParameters ( ) const
inline

Get the parameters corresponding attached to the nodes of the tree.

That is, all the parameters without the root frequencies.

Returns
The parameters attached to the nodes of the tree.

Definition at line 389 of file SubstitutionModelSet.h.

References rootFrequencies_, and stationarity_.

Referenced by bpp::DRNonHomogeneousTreeLikelihood::fireParameterChanged(), bpp::RNonHomogeneousTreeLikelihood::fireParameterChanged(), and bpp::RNonHomogeneousMixedTreeLikelihood::fireParameterChanged().

◆ getNodesWithModel()

const std::vector<int>& bpp::SubstitutionModelSet::getNodesWithModel ( size_t  i) const
throw (IndexOutOfBoundsException
)
inline

Get a list of nodes id for which the given model is associated.

Parameters
iThe index of the model in the set.
Returns
A vector with the ids of the node associated to this model.
Exceptions
IndexOutOfBoundsExceptionIf the index is not valid.

Definition at line 307 of file SubstitutionModelSet.h.

References modelSet_, and modelToNodes_.

Referenced by bpp::AbstractNonHomogeneousTreeLikelihood::ConstNonHomogeneousSiteModelIterator::ConstNonHomogeneousSiteModelIterator(), bpp::SubstitutionMappingTools::getNormalizationsPerBranch(), bpp::RNonHomogeneousMixedTreeLikelihood::init(), and bpp::PhylogeneticsApplicationTools::printParameters().

◆ getNodesWithParameter()

std::vector< int > SubstitutionModelSet::getNodesWithParameter ( const std::string &  name) const
throw (ParameterNotFoundException
)
Parameters
nameThe name of the parameter to look for.
Returns
The list of nodes with a model containing the specified parameter.
Exceptions
ParameterNotFoundExceptionIf no parameter with the specified name is found.

Definition at line 115 of file SubstitutionModelSet.cpp.

Referenced by bpp::DRNonHomogeneousTreeLikelihood::fireParameterChanged(), bpp::RNonHomogeneousTreeLikelihood::fireParameterChanged(), and bpp::RNonHomogeneousMixedTreeLikelihood::fireParameterChanged().

◆ getNumberOfModels()

◆ getNumberOfStates()

size_t bpp::SubstitutionModelSet::getNumberOfStates ( ) const
throw (Exception
)
inline

Get the number of states associated to this model set.

Returns
The number of states.
Exceptions
Exceptionif no model is associated to the set.

Definition at line 222 of file SubstitutionModelSet.h.

References nbStates_.

Referenced by bpp::AbstractNonHomogeneousTreeLikelihood::getNumberOfStates().

◆ getRootFrequencies()

◆ getRootFrequenciesParameters()

ParameterList bpp::SubstitutionModelSet::getRootFrequenciesParameters ( ) const
inline

Get the parameters corresponding to the root frequencies.

Returns
The parameters corresponding to the root frequencies.

Definition at line 374 of file SubstitutionModelSet.h.

References rootFrequencies_, and stationarity_.

Referenced by bpp::AbstractNonHomogeneousTreeLikelihood::getRootFrequenciesParameters().

◆ getRootFrequenciesSet()

const FrequenciesSet* bpp::SubstitutionModelSet::getRootFrequenciesSet ( ) const
inline
Returns
The set of root frequencies.

Definition at line 356 of file SubstitutionModelSet.h.

References rootFrequencies_.

Referenced by bpp::PhylogeneticsApplicationTools::printParameters().

◆ getStateMap()

virtual const StateMap& bpp::SubstitutionModelSet::getStateMap ( ) const
inlinevirtual

Definition at line 421 of file SubstitutionModelSet.h.

References getModel(), and bpp::SubstitutionModel::getStateMap().

◆ hasMixedSubstitutionModel()

bool SubstitutionModelSet::hasMixedSubstitutionModel ( ) const

◆ isFullySetUpFor()

bool bpp::SubstitutionModelSet::isFullySetUpFor ( const Tree tree,
bool  throwEx = true 
) const
throw (Exception
)
inline

Check if the model set is fully specified for a given tree.

This include:

  • that each node as a model set up,
  • that each model in the set is attributed to a node,
  • that each parameter in the set actually correspond to a model.
  • all nodes ids in the set refer to an existing node in the tree.
Parameters
treeThe tree to check.
throwExTell if an exception have to be thrown in case of test not passed.

Definition at line 461 of file SubstitutionModelSet.h.

References checkOrphanModels(), checkOrphanNodes(), and checkUnknownNodes().

Referenced by bpp::RNonHomogeneousMixedTreeLikelihood::RNonHomogeneousMixedTreeLikelihood().

◆ listModelNames()

void SubstitutionModelSet::listModelNames ( std::ostream &  out = std::cout) const

Definition at line 218 of file SubstitutionModelSet.cpp.

References modelSet_, and modelToNodes_.

◆ operator=()

◆ replaceModel()

void SubstitutionModelSet::replaceModel ( size_t  modelIndex,
SubstitutionModel model 
)
throw (Exception
)

Replace a model in the set, and all corresponding parameters. The replaced model deleted.

Parameters
modelIndexThe index of the model in the set.
modelthe new model. This model will be owned by the Set.
Exceptions
Exceptionif a parameter becomes orphan because of the removal.

Definition at line 169 of file SubstitutionModelSet.cpp.

◆ setRootFrequencies()

void SubstitutionModelSet::setRootFrequencies ( FrequenciesSet rootFreqs)

◆ updateRootFrequencies()

void bpp::SubstitutionModelSet::updateRootFrequencies ( )
inlineprotected

Set rootFrequencies_ from parameters.

Definition at line 473 of file SubstitutionModelSet.h.

References rootFrequencies_, and stationarity_.

Referenced by fireParameterChanged().

Member Data Documentation

◆ alphabet_

const Alphabet* bpp::SubstitutionModelSet::alphabet_
protected

A pointer toward the common alphabet to all models in the set.

Definition at line 111 of file SubstitutionModelSet.h.

Referenced by addModel(), getAlphabet(), and operator=().

◆ modelParameters_

std::vector<ParameterList> bpp::SubstitutionModelSet::modelParameters_
private

Parameters for each model in the set.

The parameters_ field, inherited from AbstractSubstitutionModel contains all parameters, with unique names. To make the correspondance with parameters for each model in the set, we duplicate them in this array. In most cases, this is something like 'theta_1 <=> theta', 'theta_2 <=> theta', etc.

Definition at line 139 of file SubstitutionModelSet.h.

Referenced by addModel(), clear(), fireParameterChanged(), and operator=().

◆ modelSet_

std::vector<SubstitutionModel*> bpp::SubstitutionModelSet::modelSet_
protected

◆ modelToNodes_

std::map<size_t, std::vector<int> > bpp::SubstitutionModelSet::modelToNodes_
mutableprivate

Definition at line 130 of file SubstitutionModelSet.h.

Referenced by addModel(), getNodesWithModel(), listModelNames(), and operator=().

◆ nbStates_

size_t bpp::SubstitutionModelSet::nbStates_
protected

Definition at line 113 of file SubstitutionModelSet.h.

Referenced by addModel(), clear(), getNumberOfStates(), and operator=().

◆ nodeToModel_

std::map<int, size_t> bpp::SubstitutionModelSet::nodeToModel_
mutableprivate

Contains for each node in a tree the index of the corresponding model in modelSet_.

Definition at line 129 of file SubstitutionModelSet.h.

Referenced by addModel(), clear(), getModelForNode(), getModelIndexForNode(), and operator=().

◆ rootFrequencies_

std::auto_ptr<FrequenciesSet> bpp::SubstitutionModelSet::rootFrequencies_
private

◆ stationarity_

bool bpp::SubstitutionModelSet::stationarity_
private

The documentation for this class was generated from the following files: