001: /*
002: * This program is free software; you can redistribute it and/or modify
003: * it under the terms of the GNU General Public License as published by
004: * the Free Software Foundation; either version 2 of the License, or
005: * (at your option) any later version.
006: *
007: * This program is distributed in the hope that it will be useful,
008: * but WITHOUT ANY WARRANTY; without even the implied warranty of
009: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
010: * GNU General Public License for more details.
011: *
012: * You should have received a copy of the GNU General Public License
013: * along with this program; if not, write to the Free Software
014: * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
015: */
016:
017: /*
018: * Associator.java
019: * Copyright (C) 1999 University of Waikato, Hamilton, New Zealand
020: *
021: */
022:
023: package weka.associations;
024:
025: import weka.core.Capabilities;
026: import weka.core.CapabilitiesHandler;
027: import weka.core.Instances;
028: import weka.core.SerializedObject;
029: import weka.core.Utils;
030:
031: import java.io.Serializable;
032:
033: /**
034: * Abstract scheme for learning associations. All schemes for learning
035: * associations implemement this class
036: *
037: * @author Eibe Frank (eibe@cs.waikato.ac.nz)
038: * @version $Revision: 1.9 $
039: */
040: public abstract class Associator implements Cloneable, Serializable,
041: CapabilitiesHandler {
042:
043: /** for serialization */
044: private static final long serialVersionUID = -3017644543382432070L;
045:
046: /**
047: * Generates an associator. Must initialize all fields of the associator
048: * that are not being set via options (ie. multiple calls of buildAssociator
049: * must always lead to the same result). Must not change the dataset
050: * in any way.
051: *
052: * @param data set of instances serving as training data
053: * @exception Exception if the associator has not been
054: * generated successfully
055: */
056: public abstract void buildAssociations(Instances data)
057: throws Exception;
058:
059: /**
060: * Creates a new instance of a associator given it's class name and
061: * (optional) arguments to pass to it's setOptions method. If the
062: * associator implements OptionHandler and the options parameter is
063: * non-null, the associator will have it's options set.
064: *
065: * @param associatorName the fully qualified class name of the associator
066: * @param options an array of options suitable for passing to setOptions. May
067: * be null.
068: * @return the newly created associator, ready for use.
069: * @exception Exception if the associator name is invalid, or the options
070: * supplied are not acceptable to the associator
071: */
072: public static Associator forName(String associatorName,
073: String[] options) throws Exception {
074:
075: return (Associator) Utils.forName(Associator.class,
076: associatorName, options);
077: }
078:
079: /**
080: * Creates a deep copy of the given associator using serialization.
081: *
082: * @param model the associator to copy
083: * @return a deep copy of the associator
084: * @exception Exception if an error occurs
085: */
086: public static Associator makeCopy(Associator model)
087: throws Exception {
088: return (Associator) new SerializedObject(model).getObject();
089: }
090:
091: /**
092: * Creates copies of the current associator. Note that this method
093: * now uses Serialization to perform a deep copy, so the Associator
094: * object must be fully Serializable. Any currently built model will
095: * now be copied as well.
096: *
097: * @param model an example associator to copy
098: * @param num the number of associators copies to create.
099: * @return an array of associators.
100: * @exception Exception if an error occurs
101: */
102: public static Associator[] makeCopies(Associator model, int num)
103: throws Exception {
104:
105: if (model == null) {
106: throw new Exception("No model associator set");
107: }
108: Associator[] associators = new Associator[num];
109: SerializedObject so = new SerializedObject(model);
110: for (int i = 0; i < associators.length; i++) {
111: associators[i] = (Associator) so.getObject();
112: }
113: return associators;
114: }
115:
116: /**
117: * Returns the Capabilities of this associator. Derived associators have to
118: * override this method to enable capabilities.
119: *
120: * @return the capabilities of this object
121: * @see Capabilities
122: */
123: public Capabilities getCapabilities() {
124: return new Capabilities(this );
125: }
126:
127: /**
128: * runs the associator with the given commandline options
129: *
130: * @param associator the associator to run
131: * @param options the commandline options
132: */
133: protected static void runAssociator(Associator associator,
134: String[] options) {
135: try {
136: System.out.println(AssociatorEvaluation.evaluate(
137: associator, options));
138: } catch (Exception e) {
139: if ((e.getMessage() != null)
140: && (e.getMessage().indexOf("General options") == -1))
141: e.printStackTrace();
142: else
143: System.err.println(e.getMessage());
144: }
145: }
146: }
|