[DL-Learner SVN] SF.net SVN: dl-learner:[2743] trunk/components-core/src/main/java/org/ dllearner

[<jen...@us...>]

Revision: 2743
          http://dl-learner.svn.sourceforge.net/dl-learner/?rev=2743&view=rev
Author:   jenslehmann
Date:     2011-04-01 09:38:11 +0000 (Fri, 01 Apr 2011)

Log Message:
-----------
continued design of learning algorithm interfaces, including better support for active learning

Modified Paths:
--------------
    trunk/components-core/src/main/java/org/dllearner/algorithms/BruteForceLearner.java
    trunk/components-core/src/main/java/org/dllearner/algorithms/ocel/OCEL.java
    trunk/components-core/src/main/java/org/dllearner/core/AbstractCELA.java
    trunk/components-core/src/main/java/org/dllearner/core/ClassExpressionLearningAlgorithm.java
    trunk/components-core/src/main/java/org/dllearner/core/FuzzyClassExpressionLearningAlgorithm.java
    trunk/components-core/src/main/java/org/dllearner/core/LearningAlgorithm.java
    trunk/components-core/src/main/java/org/dllearner/core/SparqlQueryLearningAlgorithm.java

Added Paths:
-----------
    trunk/components-core/src/main/java/org/dllearner/core/ActiveLearningAlgorithm.java
    trunk/components-core/src/main/java/org/dllearner/core/Oracle.java
    trunk/components-core/src/main/java/org/dllearner/core/ResumableLearningAlgorithm.java
    trunk/components-core/src/main/java/org/dllearner/core/StoppableLearningAlgorithm.java

Modified: trunk/components-core/src/main/java/org/dllearner/algorithms/BruteForceLearner.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/algorithms/BruteForceLearner.java	2011-03-31 06:40:53 UTC (rev 2742)
+++ trunk/components-core/src/main/java/org/dllearner/algorithms/BruteForceLearner.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -308,24 +308,6 @@
 	}
 
 	/* (non-Javadoc)
-	 * @see org.dllearner.core.LearningAlgorithm#pause()
-	 */
-	@Override
-	public void pause() {
-		// TODO Auto-generated method stub
-		
-	}
-
-	/* (non-Javadoc)
-	 * @see org.dllearner.core.LearningAlgorithm#resume()
-	 */
-	@Override
-	public void resume() {
-		// TODO Auto-generated method stub
-		
-	}
-
-	/* (non-Javadoc)
 	 * @see org.dllearner.core.LearningAlgorithm#isRunning()
 	 */
 	@Override

Modified: trunk/components-core/src/main/java/org/dllearner/algorithms/ocel/OCEL.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/algorithms/ocel/OCEL.java	2011-03-31 06:40:53 UTC (rev 2742)
+++ trunk/components-core/src/main/java/org/dllearner/algorithms/ocel/OCEL.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -487,18 +487,6 @@
 		return algorithm.getStartNode();
 	}
 
-	/** {@inheritDoc} */
-	@Override
-	public void pause() {
-		// TODO: not implemented
-	}
-
-	/** {@inheritDoc} */
-	@Override
-	public void resume() {
-		// TODO: not implemented
-	}
-
 	/* (non-Javadoc)
 	 * @see org.dllearner.core.LearningAlgorithm#isRunning()
 	 */

Modified: trunk/components-core/src/main/java/org/dllearner/core/AbstractCELA.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/AbstractCELA.java	2011-03-31 06:40:53 UTC (rev 2742)
+++ trunk/components-core/src/main/java/org/dllearner/core/AbstractCELA.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -39,10 +39,14 @@
  * may require addition reasoner queries, because the learning
  * algorithms usually use but do not necessarily store this information.
  * 
+ * Changes (March/April 2011): Learning algorithms no longer have to use
+ * this class, but it still serves as a prototypical template for class
+ * expression learning algorithms.
+ * 
  * @author Jens Lehmann
  *
  */
-public abstract class AbstractCELA extends Component {
+public abstract class AbstractCELA extends Component implements ClassExpressionLearningAlgorithm, StoppableLearningAlgorithm {
 
 	/**
 	 * The learning problem variable, which must be used by
@@ -102,43 +106,8 @@
 	 * choose to store results.)
 	 */
 	public static final int MAX_NR_OF_RESULTS = 100;
-	
+		
 	/**
-	 * Starts the algorithm. It runs until paused, stopped, or
-	 * a termination criterion has been reached.
-	 */
-	public abstract void start();
-	
-	/**
-	 * Pauses the algorithm (not all algorithms need to implement
-	 * this operation).
-	 */
-	public void pause() { };	
-	
-	/**
-	 * Resumes the algorithm (not all algorithms need to implement
-	 * this operation). You can use this method to continue
-	 * an algorithm run even after a termination criterion has been
-	 * reached. It will run until paused, stopped, or terminated
-	 * again.
-	 */
-	public void resume() { };
-	
-	/**
-	 * Stops the algorithm gracefully. A stopped algorithm cannot be resumed anymore.
-	 * Use this method for cleanup and freeing memory.
-	 */
-	public abstract void stop();
-	
-	/**
-	 * Returns whether the learning algorithm is running. Implementation
-	 * should use a boolean status variable in their implementations of
-	 * the start and resume methods.
-	 * @return True if the algorithm is running, false otherwise.
-	 */
-	public abstract boolean isRunning();
-	
-	/**
 	 * Every algorithm must be able to return the score of the
 	 * best solution found.
 	 * 

Added: trunk/components-core/src/main/java/org/dllearner/core/ActiveLearningAlgorithm.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/ActiveLearningAlgorithm.java	                        (rev 0)
+++ trunk/components-core/src/main/java/org/dllearner/core/ActiveLearningAlgorithm.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -0,0 +1,38 @@
+/**
+ * Copyright (C) 2007-2011, Jens Lehmann
+ *
+ * This file is part of DL-Learner.
+ * 
+ * DL-Learner is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * DL-Learner is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+package org.dllearner.core;
+
+
+/**
+ * Active Learning algorithms are those, which can use feedback from an oracle.
+ * 
+ * @author Jens Lehmann
+ *
+ */
+public interface ActiveLearningAlgorithm {
+
+	/**
+	 * In order to separate/hide the implementation of an oracle from the active learning algorithm itself,
+	 * an oracle object is passed to the algorithm.
+	 * @param oracle The oracle to be used by the learning algorithm.
+	 */
+	public void setOracle(Oracle oracle);
+	
+}

Modified: trunk/components-core/src/main/java/org/dllearner/core/ClassExpressionLearningAlgorithm.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/ClassExpressionLearningAlgorithm.java	2011-03-31 06:40:53 UTC (rev 2742)
+++ trunk/components-core/src/main/java/org/dllearner/core/ClassExpressionLearningAlgorithm.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -19,6 +19,10 @@
  */
 package org.dllearner.core;
 
+import java.util.List;
+
+import org.dllearner.core.owl.Description;
+
 /**
  * Basic interface for algorithms learning OWL/DL class expressions.
  * 
@@ -27,4 +31,19 @@
  */
 public interface ClassExpressionLearningAlgorithm extends LearningAlgorithm {
 
+	/**
+	 * @see #getCurrentlyBestEvaluatedDescriptions(int)
+	 * @param nrOfDescriptions Limit for the number or returned descriptions.
+	 * @return The best class descriptions found by the learning algorithm so far.
+	 */
+	public List<Description> getCurrentlyBestDescriptions(int nrOfDescriptions);
+		
+	/**
+	 * Return the best currently found concepts up to some maximum
+	 * count (no minimality filter used).
+	 * @param nrOfDescriptions Maximum number of descriptions returned.
+	 * @return Return value is getCurrentlyBestDescriptions(nrOfDescriptions, 0.0, false).
+	 */
+	public List<? extends EvaluatedDescription> getCurrentlyBestEvaluatedDescriptions(int nrOfDescriptions);
+	
 }

Modified: trunk/components-core/src/main/java/org/dllearner/core/FuzzyClassExpressionLearningAlgorithm.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/FuzzyClassExpressionLearningAlgorithm.java	2011-03-31 06:40:53 UTC (rev 2742)
+++ trunk/components-core/src/main/java/org/dllearner/core/FuzzyClassExpressionLearningAlgorithm.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -19,12 +19,33 @@
  */
 package org.dllearner.core;
 
+import java.util.List;
+
+import org.dllearner.core.owl.Description;
+
 /**
  * Basic interface for algorithms learning fuzzy OWL/DL class expressions.
  * 
+ * TODO: Probably needs to be adapted.
+ * 
  * @author Jens Lehmann
  *
  */
 public interface FuzzyClassExpressionLearningAlgorithm extends LearningAlgorithm {
 
+	/**
+	 * @see #getCurrentlyBestEvaluatedDescriptions(int)
+	 * @param nrOfDescriptions Limit for the number or returned descriptions.
+	 * @return The best class descriptions found by the learning algorithm so far.
+	 */
+	public List<Description> getCurrentlyBestDescriptions(int nrOfDescriptions);
+	
+	/**
+	 * Return the best currently found concepts up to some maximum
+	 * count (no minimality filter used).
+	 * @param nrOfDescriptions Maximum number of descriptions returned.
+	 * @return Return value is getCurrentlyBestDescriptions(nrOfDescriptions, 0.0, false).
+	 */
+	public List<? extends EvaluatedDescription> getCurrentlyBestEvaluatedDescriptions(int nrOfDescriptions);	
+	
 }

Modified: trunk/components-core/src/main/java/org/dllearner/core/LearningAlgorithm.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/LearningAlgorithm.java	2011-03-31 06:40:53 UTC (rev 2742)
+++ trunk/components-core/src/main/java/org/dllearner/core/LearningAlgorithm.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -19,6 +19,7 @@
  */
 package org.dllearner.core;
 
+
 /**
  * Basic interface for all DL-Learner learning algorithms.
  * 
@@ -27,4 +28,10 @@
  */
 public interface LearningAlgorithm {
 
+	/**
+	 * Starts the algorithm. It runs until paused, stopped, or
+	 * a termination criterion has been reached.
+	 */
+	public abstract void start();	
+	
 }

Added: trunk/components-core/src/main/java/org/dllearner/core/Oracle.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/Oracle.java	                        (rev 0)
+++ trunk/components-core/src/main/java/org/dllearner/core/Oracle.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -0,0 +1,65 @@
+/**
+ * Copyright (C) 2007-2011, Jens Lehmann
+ *
+ * This file is part of DL-Learner.
+ * 
+ * DL-Learner is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * DL-Learner is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+package org.dllearner.core;
+
+import java.util.List;
+
+import org.dllearner.core.owl.Individual;
+
+/**
+ * 
+ * An oracle can be used by a learning algorithm to interactively ask for the
+ * classification of an individual. Note that an oracle can either be a user or
+ * an automatic method, which means that the implementation of an oracle can
+ * reach from simple checks to more complex user interaction processes.
+ * 
+ * @author Jens Lehmann
+ *
+ */
+public interface Oracle {
+
+	/**
+	 * This method should be called by a learning algorithm if it wants a list of individuals
+	 * (including the special case of a single individual) to be classified by the oracle.
+	 * 
+	 * For each of the individuals, which are specified in the parameter, the oracle must
+	 * return a value in the obvious order. (The first element in the returned list classifies the first element
+	 * of the list of individuals, the second element in the returned list classifies the
+	 * second element of the individual list etc.) The following values should be used:
+	 * 
+	 * <ul>
+	 * <li>-1.0: Indicates that the individual does not belong to the learned class.</li>
+	 * <li>Values between -1.0 and 1.0 indicate the degree to which an individual belongs to the class.</li>
+	 * <li>1.0: The individual does belong to the learned class.</li>
+	 * <li>-2.0: The oracle does not know how to classify the individual (e.g. no feedback given by a user).</li>
+	 * </ul>
+	 * 
+	 * Note that the most common case is that the individuals list contains a single element, which
+	 * is answered by 1.0 or -1.0 by the oracle. However, the oracle interface is designed with a 
+	 * higher degree of flexibility in mind, which is required for some use cases.
+	 * 
+	 * @param individuals A list of individuals, which should be classified by the oracle.
+	 * @return For each element of the list, a classification value as explained above is
+	 * returned.
+	 *
+	 */
+	public List<Double> classifyIndividuals(List<Individual> individuals);
+		
+}
\ No newline at end of file

Added: trunk/components-core/src/main/java/org/dllearner/core/ResumableLearningAlgorithm.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/ResumableLearningAlgorithm.java	                        (rev 0)
+++ trunk/components-core/src/main/java/org/dllearner/core/ResumableLearningAlgorithm.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -0,0 +1,45 @@
+/**
+ * Copyright (C) 2007-2011, Jens Lehmann
+ *
+ * This file is part of DL-Learner.
+ * 
+ * DL-Learner is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * DL-Learner is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+package org.dllearner.core;
+
+/**
+ * Interface for learning algorithms, which can be paused and later continued.
+ * 
+ * @author Jens Lehmann
+ *
+ */
+public interface ResumableLearningAlgorithm {
+
+	/**
+	 * Pauses the algorithm (not all algorithms need to implement
+	 * this operation).
+	 */
+	public void pause();	
+	
+	/**
+	 * Resumes the algorithm (not all algorithms need to implement
+	 * this operation). You can use this method to continue
+	 * an algorithm run even after a termination criterion has been
+	 * reached. It will run until paused, stopped, or terminated
+	 * again.
+	 */
+	public void resume();
+	
+}

Modified: trunk/components-core/src/main/java/org/dllearner/core/SparqlQueryLearningAlgorithm.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/SparqlQueryLearningAlgorithm.java	2011-03-31 06:40:53 UTC (rev 2742)
+++ trunk/components-core/src/main/java/org/dllearner/core/SparqlQueryLearningAlgorithm.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -19,12 +19,24 @@
  */
 package org.dllearner.core;
 
+import java.util.List;
+
 /**
  * Basic interface for algorithms learning SPARQL queries.
  * 
+ * TODO: Check whether it is necessary to have a "real" SPARQL query class instead of 
+ * only a string.
+ * 
  * @author Jens Lehmann
  *
  */
 public interface SparqlQueryLearningAlgorithm extends LearningAlgorithm {
 
+	/**
+	 * @see #getCurrentlyBestEvaluatedDescriptions(int)
+	 * @param nrOfDescriptions Limit for the number or returned descriptions.
+	 * @return The best SPARQL queries found by the learning algorithm so far.
+	 */
+	public List<String> getCurrentlyBestDescriptions(int nrOfDescriptions);
+	
 }

Added: trunk/components-core/src/main/java/org/dllearner/core/StoppableLearningAlgorithm.java
===================================================================
--- trunk/components-core/src/main/java/org/dllearner/core/StoppableLearningAlgorithm.java	                        (rev 0)
+++ trunk/components-core/src/main/java/org/dllearner/core/StoppableLearningAlgorithm.java	2011-04-01 09:38:11 UTC (rev 2743)
@@ -0,0 +1,47 @@
+/**
+ * Copyright (C) 2007-2011, Jens Lehmann
+ *
+ * This file is part of DL-Learner.
+ * 
+ * DL-Learner is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * DL-Learner is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+package org.dllearner.core;
+
+/**
+ * 
+ * Interface for algorithms, which can be stopped and checked whether they are
+ * running. This allows learning algorithms to be run in separate threads or
+ * be terminated by the user.
+ * 
+ * @author Jens Lehmann
+ *
+ */
+public interface StoppableLearningAlgorithm extends LearningAlgorithm {
+
+	/**
+	 * Stops the algorithm gracefully. A stopped algorithm cannot be resumed anymore.
+	 * Use this method for cleanup and freeing memory.
+	 */
+	public abstract void stop();
+	
+	/**
+	 * Returns whether the learning algorithm is running. Implementation
+	 * should use a boolean status variable in their implementations of
+	 * the start and resume methods.
+	 * @return True if the algorithm is running, false otherwise.
+	 */
+	public abstract boolean isRunning();
+	
+}


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.