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}