001    /**
002     * 
003     */
004    package calhoun.analysis.crf;
005    
006    import calhoun.analysis.crf.io.InputSequence;
007    
008    /** an interface to inference algorithms for CRFs.  Given a model, a set of feature weights, and a set of input data, the
009     * algorithm selects a sequence of hidden states.  The Viterbi dynamic programming algorithm and its variants are usually used
010     * for this problem. 
011     */
012    public interface CRFInference {
013            
014            /** holder which contains the results of an inference run.  The indexes of the predict hidden states are stored in the 
015             * <code>hiddenStates</code> array.  The best scores array is a column major array of the best scores to each estate and position.
016             */
017            public static class InferenceResult {
018                    public int[] hiddenStates;
019                    public double[] bestScores;
020            }
021            
022            /** Return the labelling that maximizes the conditional probability P(y|x).
023             * @param mm            model to use for training  
024             * @param data          input sequence to label
025             * @param weights       array of feature weights.  Usually these will be derived from a training pass.
026             * @return inference result containing the hidden states which are predicted and the score outputs.
027             */
028            InferenceResult predict(ModelManager mm, InputSequence<?> data, double[] weights);
029    }