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