State Functions

#State Functions State functions are user-defined functions that are called within a state to get a probability to apply to the scoring. The functions can be called at either evaluation of an emission or transition.

The function passed to assigned in a StateFunc class object and passed to the model import function. Only a single StateFunc can be passed to the model import. If multiple functions need to be passed to the model, the functions need to be assigned to a single StateFunc object.

###Creating and Assigning StateFunc

StateFunc stFunc;

#Assigning a transition function
stFunc.assignTransitionFunction( const char* <Name of Function>, <pointer to transition function>);

#Assigning a emission function
stFunc.assignTransitionFunction( const char* <Name of Function>, <pointer to emission function>);

#Assigning a univariate probability density function
stFunc.assignPDFFunction( const char* <Name of Function>, <pointer to probability density function>);

#Assigning a multivariate probability density function
stFunc.assignMultivariatePdfFunction( const char* <Name of Function>, <pointer to multivariate probability density function>);

##Emission Functions Emission functions can be defined and called on any State emission. The return value of this function will be applied to the standard emission probability as a natural logarithmic value. This allows the user to either use a function to calculate the emission probability or use a function to weight the emissions based on some other criteria.

###Definition Emission functions need to return a double and take the parameters (const std::string*, size_t). The std::string the function will receive is the sequence for the defined track. The size_t will be the position within the string being evaluated by the emission.

Any function of the form double myFunctionName (const std::string*, const size_t) can be used for an emission function.

###Assigning Function to StateFunc object

StateFunc stFunc;

//Assigning a emission function
stFunc.assignEmissionFunction( "MyFunction", &myFunctionName);

###Calling within the Model Within the model the function will be called at any emission where Emission Tag is placed.

####Example

EMISSION:	SEQ: P(X)	[FUNCTION: MyFunction	TRACK: SEQ	SCALE: 0]
	ORDER:	0
@A	C	G	T	
0.1	0.1	0.1	0.1

When evaluating this emission, the function "MyFunction" will be called and passed the track labeled "SEQ". The returned score will be scaled by a value 0 or any be the corresponding SCALING Function that was defined in the model.

Note: The SCALE is optional in Emission TAG. If SCALE is left out the value will be passed, directly to the model and not scaled by any value, which is equivalent to SCALE: 0

##Transition Functions A transition function is called anytime the corresponding transition is evaluated. The return value of this function will be applied to the standard transition probability as a natural logarithmic value. When the transition is evaluated the function can traceback through the trellis and pass the corresponding sequence to the function for evaluation.

###Definition The transition function returns a double and must have the form double MyFunctionName (const std::string*, const size_t, const std::string*, const size_t). The first string corresponds to the complete sequence. The first size_t corresponds to the current position within the sequence that is being evaluated. The second std::string is determined by a traceback and combining paramenters set in the tag. The second size_t corresponds to the traceback lenght of the traceback.

###Transition TAG FUNCTION: Function Name to use TRACK: Name of Track to use SCALE: (optional) Scaling parameter to use to scale the score TRACEBACK LABELS: see valid Traceback Labels below COMBINE TAG: see valid Combine tags below

####Traceback Labels: (Alternate TAG separated by "/")

TO_LABEL / TB->LABEL: Traceback through trellis until the specified State PATH_LABEL is reached

TO_GFF / TB->GFF: Traceback through trellis until the specified State GFF_DESC is reached

TO_STATE / TB->STATE: Traceback through trellis until the specified State NAME is reached

TO_START / TB->START: Traceback through trellis until the start is reached

DIFF_STATE: Traceback through trellis until a different State is reached.

####Combine Tags: Combine sequence according to specified criteria

COMBINE_LABEL: Combine the sequence where the traceback State's PATH_LABEL is equal to specified value

COMBINE_GFF: Combine the sequence where the traceback State's GFF_DESC is equal to specified value

COMBINE_STATE: Combine the sequence where the traceback State's NAME is equal to specified value

NO_COMBINE: Don't combine the sequence in any manner. Will return the sequence corresponding to the traceback.

###Assigning Function to StateFunc object

StateFunc stFunc;

//Assigning a transition function
stFunc.assignTransitionFunction( "MyFunction", &myFunctionName);

###Calling within the Model Within the model the function will be called at any transition where Transition Tag is placed. Tags are surrounded by square brackets [...]

####Example

TRANSITION:	STANDARD:	P(X)
ACCEPTOR2: 1	[FUNCTION:	HMMER	TRACK:	SEQ	COMBINE_LABEL:	E	TO_LABEL:	N	SCALE:	0.4	]

Anytime the ACCEPTOR2 transition was evaluated, it would also traceback to any State with a PATH_LABEL of "N". Then the sequence from track SEQ which corresponded to any States with the PATH_LABEL "E" would be combined. The function HMMER would then be called and be passed the complete SEQ sequence, the current position within the trellis being evaluated, the combined sequence and the total length of the traceback.
The returned value of the function would be scaled and that value would be applied(added in log space) to the set probability for transition to ACCEPTOR2 state of P(X) = 1;