001    package calhoun.analysis.crf;
002    
003    /** used to pass feature evaluations from a FeatureManager to the Conrad engine during an <code>evaluate</code> call.
004     * A <code>FeatureList</code> is always the last argument passed to an <code>evaluate</code> call on <code>FeatureManager</code>.
005     * It allows the feature to add in evaluations or declare the given node or edge invalid.  This interface is present so that
006     * new memory does not have to be allocated during the evaluation process and so that a given FeatureManager can return any
007     * arbitrary number of feature evaluations from an <code>evaluate</code> call.
008     * 
009    */
010    public interface FeatureList {
011            /** returns a feature value for this evaluation.  Since a <code>FeatureManager</code> can provide evaluations for more than one
012             * feature, it is necessary to identify the specific feature by passing its <code>index</code>.<p>
013             * If an <code>evaluate</code> call is made and <code>addFeature</code> is not called for a given feature index, then the value for
014             * that feature is assumed to be zero.  This makes it very efficient to evaluate sparse features.<p> 
015             * The value can be any real number, and passing zero is allowed but unnecessary.
016             * @param index the index of the feature which has been evaluated
017             * @param value the value of the feature.
018             */ 
019            void addFeature(int index, double value);
020            
021            /** specifies that node, edge, or segment specified in the <code>evaluate</code> call is invalid.  When invalid nodes or edges are found
022             * the engine will exclude all hidden state paths including that node, edge, or segment from both training and inference.  This is very
023             * different from returning zero for a given feature.  Note that if even one <code>FeatureManager</code> invalidates a node or edge, then
024             * no feature evaluations at that position will be used.  This is very different from returning zero, which simply means that the path is 
025             * valid, but the feature doesn't provide any information.
026             */
027            void invalidate();
028    
029            /** checks if the current node, edge, or segment is valid.  This can be used to speed up processing in more complicated FeatureManagers, 
030             * since once invalidate has been called during an <code>evaluate</code> function there is no point in adding any new feature values.  
031             * @return true if the <code>FeatureList</code> is still valid.
032             */
033            boolean isValid();
034    }