Adding the stat and file handlers.

To output information about your newly implemented trait or LCE, you will have to add stat and/or file handlers to the trait prototype.

The StatHandler interface has two specialized classes; the TraitStatHandler and the EventStatHandler template classes. Each implements the StatHandler interface and declares a link to either the TraitPrototype or LCE using it. For the Trait version, the TraitStatHandler also stores the trait's index. These can be accessed within each class by the TraitStatHandler::_SHLinkedTrait, TraitStatHandler::_SHLinkedTraitIndex and EventStatHandler::_SHLinkedEvent members. These member variables are set during construction.

The same is true for the FileHandler interface and its two derivatives: the TraitFileHandler and EventFileHandler template classes. They also declare the links to the trait prototype and LCE like this: TraitFileHandler::_FHLinkedTrait, TraitFileHandler::_FHLinkedTraitIndex and EventFileHandler::_FHLinkedEvent.

The only thing the implementer has to do then is to define the StatHandlerBase::setStatRecorders() and FileHandler::FHwrite() virtual functions and define the file extension in the FileHandler constructor (see below).

The handlers must then be attach to their respective service handler (i.e. StatServices or FileServices) to be called at runtime and actually do their job. This is done through the SimComponent interface of the TraitPrototype or LifeCycleEvent interfaces. The stat handlers are loaded into the stat service handler by the SimComponent::loadStatServices() function. The file handlers will be loaded by a call to SimComponent::loadFileServices(). This is done during the initialization process of the simulation, after having initialized the Trait Prototypes or LCEs (i.e. after those components parameters have been set). It is thus the responsibility of these two types of components to take care of the allocation and loading of the various handlers.

Here is an example of an implementation of a TraitStatHandler:

In mytrait.h, you will have to add:

#include "stathandler.h"
 
//forward declaration of the stat handler:
class MyTraitSH;
 
//-------------------------------------------------
// MyTraitProto
//-------------------------------------------------
class MyTraitProto : public TraitPrototype {
 
private:
 
  MyTraitSH *_stats;
 
public:
 
  //SimComponent implementation:
  virtual void loadStatServices ( StatServices* loader );
};
 
//-------------------------------------------------
// MyTraitSH
//-------------------------------------------------
class MyTraitSH : public StatHandler < MyTraitProto, MyTraitSH >; {
 
public:
 
  //constructor: explicitly call the TraitStatHandler cstor with
  // the pointer to the trait prototype as argument:
  MyTraitSH ( MyTraitProto *T ) : TraitStatHandler< MyTraitProto, MyTraitSH >(T) { }
 
  virtual ~MyTraitSH ( ) { }
 
  //StatHandlerBase implementation:
  virtual bool setStatRecorders (std::string& token);
 
  //declare your stat function,
  //will be passed to the StatRecorder as pointer
  //and used to fetch the results during the simulation.
  double getMyStatValue ( );
 
};

Modifications and additions to mytrait.cpp:

#include "stathandler.cc"
 
//-------------------------------------------------
// MyTraitPrototype implementation
//-------------------------------------------------
//Constructor modification
MyTraitProto ( ) : _nb_locus(0), _nb_allele(0), _mutation_rate(0), _stats(0)
{ ... }
 
//add definition of loadStatServices
void MyTraitProto::loadStatServices  ( StatServices* loader )
{
  //allocate the stat handler
  if(_stats == NULL)
    _stats = new MyTraitSH( this ); //note that we pass the pointer to 'this' here.
  if(_stats != NULL)
    loader->attach( _stats );
}
 
//-------------------------------------------------
// MyTraitSH implementation
//-------------------------------------------------
//we have to define the setStatRecorders method
//this is the place where we define the stat option as it will be read in the init file
//and create the StatRecorder that contains the function pointers.
bool MyTraitSH::setStatRecorders(std::string& token)
{
 
  if( token.compare( "my_stat_option" ) == 0 ) {
 
    //use the StatHandler interface to add a new stat recorder to the StatHandler:
    add( "My stat long description", "stat.short", FLAT, OFFSPRG, 0, &MyTraitSH::getMyStatValue, 0, 0, 0 );
 
  } else
    return false;
 
  return true;
}
 
//implementation of the stat function:
double MyTraitSH::getMyStatValue ( )
{
  //compute the mean of the trait's phenotype in the pop and return it:
  double mean = 0;
 
  //the metapop is accessed the _pop member of the base class,
  for(unsigned int i = 0; i < _pop->getPatchNbr(); i++)
     //this allows to access the trait value through the metapop interface:
     mean += _pop->getPatch(i)->get(SEX, AGE, at)->getTraitValue( _SHLinkedTraitIndex );
 
  [...]
 
  return mean;
}

The process of adding a Trait/EventFileHandler is quite similar. It is also added in the trait prototype and declares one pure abstract method, the FHWrite() method used to write the file as specified by your implementation. The difference with the TraitStatHandler is that it takes only one template argument, the trait prototype type and the FileHandler constructor require the file extension as argument in addition to the pointer to the trait prototype.

Here is a simple example of an implementation of a TraitFileHandler:

class MyTraitFH : public TraitFileHandler < MyTraitProto > {
 
public:
 
  MyTraitFH (MyTraitProto* TP) : TraitFileHandler< MyTraitProto > (".ext", TP) {}
 
  virtual void FHwrite();
}

Within the MyTraitFH class, the population (and its members) is also accessed through the FileHandler::_pop base-class member and the trait's parameters are accessed through the TraitFileHandler::_FHLinkedTrait pointer. The trait value (or phenotype) of an individual is also accessed through the TraitFileHandler::_FHLinkedTraitIndex value as in the TraitStatHandler class.

The procedure to declare the LCE-linked versions of these handlers is exactly the same, the only difference is that there is only one member variable, the _FH/_SHLinkedEvent pointer to the LCE.

<<prev | –t o p– | next>>