    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    }