| MLEngine.java |
1 /*
2 * Copyright (c) 1998-2004, 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.5 2004/07/21 17:10:05 akshay 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 }