001/**
002 * Copyright (C) 2007 - 2016, Jens Lehmann
003 *
004 * This file is part of DL-Learner.
005 *
006 * DL-Learner is free software; you can redistribute it and/or modify
007 * it under the terms of the GNU General Public License as published by
008 * the Free Software Foundation; either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * DL-Learner is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU General Public License for more details.
015 *
016 * You should have received a copy of the GNU General Public License
017 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
018 */
019package org.dllearner.core;
020
021import java.util.List;
022
023import org.semanticweb.owlapi.model.OWLIndividual;
024
025/**
026 * 
027 * An oracle can be used by a learning algorithm to interactively ask for the
028 * classification of an individual. Note that an oracle can either be a user or
029 * an automatic method, which means that the implementation of an oracle can
030 * reach from simple checks to more complex user interaction processes.
031 * 
032 * Usually, an oracle should be instantiated by passing a learning problem
033 * to its constructor.
034 * 
035 * @author Jens Lehmann
036 *
037 */
038public interface Oracle {
039
040        /**
041         * This method should be called by a learning algorithm if it wants a list of individuals
042         * (including the special case of a single individual) to be classified by the oracle.
043         * 
044         * For each of the individuals, which are specified in the parameter, the oracle must
045         * return a value in the obvious order. (The first element in the returned list classifies the first element
046         * of the list of individuals, the second element in the returned list classifies the
047         * second element of the individual list etc.) The following values should be used:
048         * 
049         * <ul>
050         * <li>-1.0: Indicates that the individual does not belong to the learned class.</li>
051         * <li>Values between -1.0 and 1.0 indicate the degree to which an individual belongs to the class.</li>
052         * <li>1.0: The individual does belong to the learned class.</li>
053         * <li>-2.0: The oracle does not know how to classify the individual (e.g. no feedback given by a user).</li>
054         * </ul>
055         * 
056         * Note that the most common case is that the individuals list contains a single element, which
057         * is answered by 1.0 or -1.0 by the oracle. However, the oracle interface is designed with a 
058         * higher degree of flexibility in mind, which is required for some use cases.
059         * 
060         * @param individuals A list of individuals, which should be classified by the oracle.
061         * @return For each element of the list, a classification value as explained above is
062         * returned.
063         *
064         */
065        List<Double> classifyIndividuals(List<OWLIndividual> individuals);
066        
067}