1   /*
2    *  Copyright (c) 1998-2005, The University of Sheffield.
3    *
4    *  This file is part of GATE (see http://gate.ac.uk/), and is free
5    *  software, licenced under the GNU Library General Public License,
6    *  Version 2, June 1991 (in the distribution as file licence.html,
7    *  and also available at http://gate.ac.uk/gate/licence.html).
8    *
9    *  Valentin Tablan 21/11/2002
10   *
11   *  $Id: MLEngine.java,v 1.6 2005/01/11 13:51:32 ian Exp $
12   *
13   */
14  package gate.creole.ml;
15  
16  import java.util.List;
17  
18  import org.jdom.Element;
19  
20  import gate.ProcessingResource;
21  import gate.creole.ExecutionException;
22  import gate.util.GateException;
23  
24  /**
25   * This interface is used for wrappers to Machine Learning engines.
26   * All classes implementing this interface should have a public constructor
27   * that takes no parameters.
28   */
29  public interface MLEngine {
30  
31    /**
32     * Sets the options from an XML JDom element.
33     * @param options the JDom element containing the options from the
34     * configuration.
35     */
36    public void setOptions(Element options);
37  
38    /**
39     * Adds a new training instance to the dataset.
40     * @param attributes the list of attributes describing the instance. The
41     * elements in the list are String values that need to be interpreted
42     * according to the dataset definition: for nominal attributes the values will
43     * used as they are; for numeric attributes the values will be converted to
44     * double.
45     */
46    public void addTrainingInstance(List attributes)throws ExecutionException;
47  
48    /**
49     * Sets the definition for the dataset used.
50     * @param definition
51     */
52    public void setDatasetDefinition(DatasetDefintion definition);
53  
54    /**
55     * Classifies a new instance.
56     * @param attributes the list of attributes describing the instance. The
57     * elements in the list are Object values that need to be interpreted
58     * according to the dataset definition. The value for the class element will
59     * be arbitrary.
60     * @return a String value for nominal and boolean attributes and a Double
61     * value for numeric attributes.
62     */
63    public Object classifyInstance(List attributes)throws ExecutionException;
64  
65    /**
66     * Like classify instances, but take a list of instances instead of a single
67     * instance, and return a list of results (one for each instance) instead of
68     * a single result.
69     *
70     * @param instances A list of lists of attributes describing the instance. The
71     * value for all of the class elements will be arbitrary.
72     * @return A list of values predicted for the class attribute, which will be
73     * Strings when the class in nominal or boolean, and a Double values
74     * otherwise.
75     * @throws ExecutionException
76     */
77    public List batchClassifyInstances(List instances) throws ExecutionException;
78  
79    /**
80     * This method will be called after an engine is created and has its dataset
81     * and options set. This allows the ML engine to initialise itself in
82     * preparation of being used.
83     *
84     * @throws GateException
85     */
86    public void init() throws GateException;
87  
88    /**
89     * Registers the PR using the engine with the engine itself.
90     * @param pr the processing resource that owns this engine.
91     */
92    public void setOwnerPR(ProcessingResource pr);
93  
94    /**
95     * Cleans up any resources allocated by the Engine when it is destroyed.
96     * (Generally this is most likely to be needed by those wrappers that
97     * call native code.)
98     */
99    public void cleanUp();
100 }