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.Map;
022import java.util.Set;
023import java.util.SortedSet;
024
025import org.dllearner.utilities.datastructures.SortedSetTuple;
026import org.semanticweb.owlapi.model.OWLClass;
027import org.semanticweb.owlapi.model.OWLClassExpression;
028import org.semanticweb.owlapi.model.OWLDataProperty;
029import org.semanticweb.owlapi.model.OWLIndividual;
030import org.semanticweb.owlapi.model.OWLLiteral;
031import org.semanticweb.owlapi.model.OWLObjectProperty;
032
033/**
034 * Reasoning requests/queries related to individuals in the knowledge base.
035 * 
036 * @author Jens Lehmann
037 *
038 */
039public interface IndividualReasoner {
040
041        /**
042         * Returns types of an individual, i.e. those classes where the individual
043         * is instance of. For instance, the individual eric could have type Person. 
044         * 
045         * @param individual An individual in the knowledge base.
046         * @return Types this individual is instance of.
047         */
048        Set<OWLClass> getTypes(OWLIndividual individual);
049        
050        /**
051         * Checks whether <code>individual</code> is instance of <code>description</code>.
052         * For instance, "Leipzig" may be an instance of "City".
053         * 
054         * @param description An OWL class description.
055         * @param individual An individual.
056         * @return True if the instance has the OWLClassExpression as type and false otherwise.
057         */
058        boolean hasType(OWLClassExpression description, OWLIndividual individual);
059        
060        /**
061         * Performs instance checks on a set of instances (reasoners might be more
062         * efficient than handling each check separately).
063         * @param description An OWL class description.
064         * @param individuals An individual.
065         * @return The subset of those instances, which have the given type.
066         */
067        SortedSet<OWLIndividual> hasType(OWLClassExpression description, Set<OWLIndividual> individuals);
068        
069        /**
070         * Gets all instances of a given class expression in the knowledge base.
071         * @param description An OWL class description.
072         * @return All instances of the class description.
073         */
074        SortedSet<OWLIndividual> getIndividuals(OWLClassExpression description);
075        
076        /**
077         * Performs a query for all instances of the given class expression and
078         * its negation. (Note that in OWL it is possible that the reasoner can
079         * neither deduce that an individual is instance of a class nor its 
080         * negation.) This method might be more efficient that performing a 
081         * two retrievals.
082         * 
083         * @param description An OWL class description.
084         * @return All instances of the class OWLClassExpression and its negation.
085         */
086        SortedSetTuple<OWLIndividual> doubleRetrieval(OWLClassExpression description);
087        
088        /**
089         * Returns the set of individuals, which are connect to the given individual
090         * with the specified object property.
091         * @param individual An individual, e.g. eric.
092         * @param objectProperty An object property, e.g. hasChild.
093         * @return A set of individuals, e.g. {anna, maria}.
094         */
095        Set<OWLIndividual> getRelatedIndividuals(OWLIndividual individual,
096                                                                                         OWLObjectProperty objectProperty);
097        
098        /**
099         * Returns the set of individuals, which are connect to the given individual
100         * with the specified data property.
101         * @param individual An individual, e.g. eric.
102         * @param datatypeProperty A data property, e.g. hasIncome.
103         * @return A set of individuals, e.g. {48000^^xsd:int}.
104         */
105        Set<OWLLiteral> getRelatedValues(OWLIndividual individual, OWLDataProperty datatypeProperty);
106        
107        /**
108         * A map of properties related to an individual, e.g. 
109         * {hasChild => {eric,anna}, hasSibling => {sebastian}}.
110         * 
111         * @param individual An individual.
112         * @return A map of of properties connected to the individual as keys and the individuals
113         * they point to as values.
114         */
115        Map<OWLObjectProperty,Set<OWLIndividual>> getObjectPropertyRelationships(OWLIndividual individual);
116        
117        /**
118         * Computes and returns all connections between individuals through the specified
119         * property, e.g. {eric => {maria, anna}, anna => {eric}}.
120         * @param objectProperty An object property.
121         * @return The mapping of individuals to other individuals through this object property.
122         */
123        Map<OWLIndividual, SortedSet<OWLIndividual>> getPropertyMembers(OWLObjectProperty objectProperty);
124
125        /**
126         * Computes and returns all connections between individuals and values through the
127         * specified property, e.g. {eric => {48000^^xsd:int}, sarah => {56000^^xsd:int}}.
128         * @param datatypeProperty  A data property.
129         * @return The mapping between individuals and values through the given property.
130         */
131        Map<OWLIndividual, SortedSet<OWLLiteral>> getDatatypeMembers(OWLDataProperty datatypeProperty);
132        
133        /**
134         * Convenience method, which can be used if it is known that the property has 
135         * values which can be parsed as double.
136         * @see #getDatatypeMembers(OWLDataProperty)
137         * @see Double#valueOf(String)
138         * @param datatypeProperty A data property.
139         * @return The mapping between individuals and double values through the given property.
140         */
141        Map<OWLIndividual, SortedSet<Double>> getDoubleDatatypeMembers(OWLDataProperty datatypeProperty);
142        
143        /**
144         * Convenience method, which can be used if it is known that the property has 
145         * values which can be parsed as integer.
146         * @see #getDatatypeMembers(OWLDataProperty)
147         * @see Integer#valueOf(String)
148         * @param datatypeProperty A data property.
149         * @return The mapping between individuals and integer values through the given property.
150         */
151        Map<OWLIndividual, SortedSet<Integer>> getIntDatatypeMembers(OWLDataProperty datatypeProperty);
152        
153        /**
154         * Convenience method, which can be used if it is known that the property has 
155         * values which can be parsed as given Number class.
156         * @see #getDatatypeMembers(OWLDataProperty)
157         * @param datatypeProperty A data property.
158         * @param clazz a Java Number subtype.
159         * @return The mapping between individuals and numeric values of given type through the given property.
160         */
161        <T extends Number> Map<OWLIndividual, SortedSet<T>> getNumericDatatypeMembers(OWLDataProperty datatypeProperty, Class<T> clazz);
162
163        /**
164         * Computes and returns all connections between individuals and numeric values through the
165         * specified property, e.g. {eric => {48000^^xsd:int}, sarah => {56000^^xsd:int}}.
166         * @param datatypeProperty  A data property.
167         * @return The mapping between individuals and numeric values through the given property.
168         */
169        <T extends Number & Comparable<T>> Map<OWLIndividual, SortedSet<T>> getNumericDatatypeMembers(OWLDataProperty datatypeProperty);
170
171        /**
172         * Convenience method, which can be used if it is known that the property has 
173         * values which can be parsed as boolean value. Only "true" or "false" are 
174         * accepted. If other values occur, a warning will be issued.
175         * @see #getDatatypeMembers(OWLDataProperty)
176         * @param datatypeProperty A data property.
177         * @return The mapping between individuals and boolean values through the given property.
178         */
179        Map<OWLIndividual, SortedSet<Boolean>> getBooleanDatatypeMembers(OWLDataProperty datatypeProperty);
180
181        /**
182         * Convenience method, which can be used to get all individuals, which have value
183         * "true" for the given property. Usually, data properties can have several values
184         * for a given individual, but this method will throw a runtime exception if this
185         * is the case (i.e. the set of values is {"true", "false"}). 
186         * @see #getDatatypeMembers(OWLDataProperty)
187         * @param datatypeProperty A data property.
188         * @return The set of individuals for which the boolean property holds.
189         */
190        SortedSet<OWLIndividual> getTrueDatatypeMembers(OWLDataProperty datatypeProperty);
191        
192        /**
193         * Convenience method, which can be used to get all individuals, which have value
194         * "false" for the given property. Usually, data properties can have several values
195         * for a given individual, but this method will throw a runtime exception if this
196         * is the case (i.e. the set of values is {"true", "false"}).
197         * @see #getDatatypeMembers(OWLDataProperty)
198         * @param datatypeProperty A data property.
199         * @return The set of individuals for which the boolean property does not hold.
200         */
201        SortedSet<OWLIndividual> getFalseDatatypeMembers(OWLDataProperty datatypeProperty);
202
203        /**
204         * Convenience method, which can be used which returns the property values as
205         * strings (note that any literal can be represented as string, even numbers).
206         * @see #getDatatypeMembers(OWLDataProperty)
207         * @param datatypeProperty A data property.
208         * @return The mapping between individuals and string values through the given property.
209         */
210        Map<OWLIndividual, SortedSet<String>> getStringDatatypeMembers(OWLDataProperty datatypeProperty);
211
212        /**
213         * A map of data properties related to values, e.g.
214         * {birthDate => {eric, "1980-10-10"^^xsd:date}, height => {Mount_Everest, 8880}}.
215         *
216         * @param individual An individual.
217         * @return A map of of data properties connected to the individual as keys and the literals
218         * they point to as values.
219         */
220        Map<OWLDataProperty, Set<OWLLiteral>> getDataPropertyRelationships(OWLIndividual individual);
221
222}