iPE::Model::Emission(3)

NAME
iPE::Model::Emission - The base class for all emission models in iParameterEstimation.

DESCRIPTION
This serves to initialize the common variables in emission models and serves as a skeleton to all emission models.

CONSTANTS

MODEL (), DEFAULT_MODEL (), FIXED_MODEL (), SUBMODEL (), FIXED_SUBMODEL ()
    These functions act as static constants to the class. One of these is assigned the type member variable and indicate what kind of model this is.

LITERAL (), LEXICAL (), PENALTY ()
    These functions define how to treat a wildcard (see the wildcard member). If it is LITERAL, the wildcard is to be scored as another character in the alphabet. If it is LEXICAL, it is to be treated as all possible letters in the alphabet (besides itself). If it is PENALTY, then the wildcard is to be penalized wherever it is seen.

FUNCTIONS

getClassname(modelName)
    This function gets the classname for a model type after checking if it exists. If the class does not exist, it dies. This is not an object method.

new (tag, attributes, data, element)
    The constructor here initializes based on the attributes. If you are interested in further initialization based on the XML attributes, your new code should call this superclass constructor as follows:

        sub new {
            my $class = shift;
            my ($tag, $att, $data, $element) = @_;
            my $this = $class->SUPER::new(@_);

            #initialization here.
        }

name (), source (), seqClass (), interval (), zModel (), zLength (), zFocus (), zSymbols (), ambiguate (), data (), type (), fixedData (), ordinal ()
    These are accessor methods to the class. None are valid lvalues.

    name, source and model indicate the name of the region, for example "Acceptor," the source of the model, e.g. "dna" or "cons", and the type of model, respectively. These are used for outputting routines, except the model which is also used to indicate the kind of model upon instantiation. seqClass is the class name of the sequence type that this model will be predicted on.

    interval is an iPE::Util::Interval defining the boundaries within the parent region where the model will be estimated. (A parent region is just the interval itself if the model is not a submodel, otherwise it is the region one generation up.) The coordinates are given relative to the beginning parent region. Length is th length of the model defined by this interval.

    zName, zModel, zLength, zFocus and zSymbols are present entirely for the sake of outputting to Zoe forrmatted parameter files. zModel is only present if the model name outputted in zoe format differs from the name given in XML format.

    ambiguate indicates whether the ambiguous wildcard character should be used in the model. wildcard will be set to one of three things, LEXICAL, LITERAL, or PENALTY. If it is LEXICAL, that indicates that the wildcard could be treated as all four possible characters, and the counts for all characters in each wildcard position should be added together. This can be accomplished with the included function lexicalAmbiguateMarkovChain. If it is LITERAL, all the counts for the wildcard character, as observed, should be computed to probabilities, and nothing needs to be done. If it is PENALTY, then the function penalizeAmbiguousNmers should be used to change the scores when scoring.

    nullModel refers to whether an analogous null model is automatically added in as a log-odds ratio. If it is not, then the countNullRegion () method will never be called (see below), and no null counts will be found. This will affect the way a region deals with the null region. If nullParams is true, then the model acts as a null region, and all its parameters are set to 0 (log(Pr(+)/Pr(-)) = 0).

    data is a model-specific optional member variable which indicates something about the model which is meaningful to the model.

    type is indicates the type of model (see above constant definitions).

    fixedData is an optional member variable which is present if the model is a fixed model and is not estimated.

    ordinal refers to submodel ordinality. If a parent model requires that the submodels have an order, the ordinal refers to its position in the ordered group of submodels.

countable ()
    Indicates if the model is suitible for counting. A model that shouldn't be counted might be a FIXED_MODEL.

submodels ()
    Accessor function for the array of submodels. lvalue is returned.

handle_submodel (tag, att, data, element)
    Callback function for start tags within an (fixed_)?string_(sub)?model. This would indicate that the model is a submodel.

logScore (pos [, null] )
    This function will return the log-odds score of a ratio of frequencies. This is intended as a utility function for all models. If there is no null model, a log score is returned instead.

lexicalAmbiguateMarkovChain (href, order)
    This function will take a hash ref and add the counts of all contexts with wildcard characters (e.g. "N") in them to the counts.

penalizeAmbiguousNmers (href, order)
    This function will take a hash ref and put the wildcard penalty (stored in wildcardPenalty) in each nmer (n=order+1) which includes the wildcard character.

STUB FUNCTIONS
The following functions are partially or not implemented in the base class and are necessary for constructing a new model.

numZoeModels ()
    This function simply indicates how many zoe-type submodels your model will output. The normal verion returns the number of submodels. In general this does not have to be overridden. The SDT and CDS model are special cases where one model implies several models.

init ()
    This function is actually defined in the XML::Object superclass. Its meaning in the context of the model is to initialize any variables which are not initialized by default. Generelly these fall under the "data" field, which are specific to the model.

clear ()
    This function is intended to clear all values of all parameters to 0. It is called immediately after initialization. Pseudocounting should not be done here, as it is handled by the object's smoother.

countRegion (region)
    This is completely unimplemented in the base class. When a model is asked to count a region, it is expected to either put it in the counts for the appropraite class or delegate the region to the appropriate submodel depending on the region that it is counting. See iPE::Region for more information about regions.

countNullRegion (region)
    Null regions are added to the transcripts as a post-processing step to the annotation. When counting, the Estimator finds these null regions and counts all the models against this region. When you count this region, you are expected to count exactly the same as you would the positive region, but in separate arrays. When you score, you will take the log of all the normalized values and use them for an odds ratio.

smooth ()
    Here you should use your Smoother class (via $this->smoother from iPE::Model) to smooth the counts of your distribution.

normalize ()
    Take all the parameters you have counted and normalize them.

score ()
    Take all the normalized scores and take the log-odds ratio of the positive model over the null model.

getZoeHeader ()
    This function returns the generic Zoe-format header for the output string. If additional things need to be printed out for the zoe header, you may override the getZoeHeaderEnd () function. This function need not be overridden.

getSSHeader (counts, order, numContexts)
    Retrieves a default significant statistics header for this model.

    You need to pass the total counts observed in this model in counts, the order of the model, and the total number of distinct contexts observed in the estimation.

getZoeHeaderEnd ()
    This function should be overridden if there is additional data about the model in order for it to be interpreted by the Zoe input. For example, the WAM header requires the order be printed at the end of the line. This should be done here.

hasSettings ()
    If true (1), the model has the new settings=value formatted data attribute. This is deprecated on arrival, but present temporarily while transitioning to the new format.

settings ()
    Returns a hash of settings and their values.

outputPrepare (out, mode)
    This function is called before outputting occurs. You should set the parameter string here. You can set the parameter string with the setParamString () method. It is necessary to do it this way in order to be able to output your model in XML format. Use the out object (iPE::Util::Output) with the 'floatf' functions and the 'intf' functions.

    The mode string will indicate one of the "count", "prob", or "score" modes. Depending on which it is, your parameter string should be prepared as such.

outputZoe (out, mode)
    This method should print out the parameters that were estimated. Use the getParamString () method of this class to get the parameter string and print it.

    If you wish not to construct the header to your model, you may use the one in iPE::Model::Emission by calling getZoeHeader ().

    You must put a newline character in before your parameters are output.

    The mode string will indicate one of the "count", "prob", or "score" modes.

SEE ALSO
iPE::Model, iPE::XML::Object, iPE::gHMM

AUTHOR
Bob Zimmermann (rpz@cse.wustl.edu).