ProtegeReasonerAPI

Protege-OWL Reasoning API

This page describes the Protege-OWL Reasoner API that provides programmatic access to a direct or a DIG-compliant reasoner. It provides methods for consistency checking, classification, etc. of an ontology as well as methods for getting the inferred information for a particular OWL entity.

This page is an updated version of the Reasoning API documentation and describes the reasoner API for Protege 3.4.1 and later (available since Protege 3.4 beta 120). The original version is available here.

The previous reasoner API has been deprecated and should not be used anymore.

The Reasoning API

The following sections provide a rough outline of how to use the Protégé-OWL reasoning API.

A new plugin type, the reasoner plugin, has been added that allows the integration of other reasoners into Protege. A reasoner implementing the reasoner plugin interface will be accessible through the Protege user interface the same way that the built-in reasoners are.

The examples on this page use an ontology that describes pizzas, which can be downloaded from here.

The inference package

The reasoning API is encapsulated in the edu.stanford.smi.protegex.owl.inference package. The main classes that will be used are the ReasonerManager (used to obtain a reasoner) and ProtegeReasoner (an interface to the direct or DIG reasoner).

The Reasoner Manager

In general, the first step when using the reasoning API is to obtain an instance of ProtegeReasoner for an OWL model. This instance of the reasoner can then be used to obtain inferred information about the model such as inferred superclasses, inferred equivalent classes, and inferred types for individuals. The ProtegeReasoner manages communication with the direct or DIG reasoner, ensuring that it is always properly synchronized with the internal Protégé-OWL model.

In order to get an instance of ProtegeReasoner for an OWL model, the ReasonerManager, which is found in the edu.stanford.smi.protegex.owl.inference.protegeowl package, must be used. The ReasonerManager is a singleton class (a class with only one instance), whose instance can be obtained by using the static method getInstance() .

To obtain an instance of a reasoner, the method createProtegeReasoner(OWLModel owlModel, Class reasonerJavaClass) should be used. The second argument, reasonerJavaCode, is the Java class of the reasoner for which you would like to obtain an instance.

The Protege full installation comes with three reasoner implementations:

• DefaultProtegeDIGReasoner : provides a connection to an external DIG compliant reasoner
• ProtegePelletJenaReasoner: provides a direct connection to the Pellet reasoner accessed through the Jena API
• ProtegePelletOWLAPIReasoner: provides a direct connection to the Pellet reasoner accessed through the OWL-API

Each of the above reasoner implement the ProtegeReasoner interface. If you would like to use a direct connection to Pellet in your application, it is recommended that you use the ProtegePelletOWLAPIReasoner.

In the following we will provide some code snippets that show how to obtain reasoner instances for the reasoners mentioned above.

Getting a DIG reasoner instance

The following code snippet shows how to get a DIG reasoner instance:

public DefaultProtegeDIGReasoner createDIGReasoner(OWLModel owlModel) {
 	final String REASONER_URL = "http://localhost:8081";

	// Get the reasoner manager instance
	ReasonerManager reasonerManager = ReasonerManager.getInstance();

	DefaultProtegeDIGReasoner reasoner = (DefaultProtegeDIGReasoner) reasonerManager.createProtegeReasoner(owlModel, reasonerManager.getDefaultDIGReasonerClass());			 

	// Set the reasoner URL and test the connection
	reasoner.setURL(REASONER_URL);

	if (!reasoner.isConnected()) {
		System.out.println("Reasoner not connected!");		
	}

	return reasoner;
}

Getting a Pellet reasoner instance (accessed through Jena)

The ProtegePelletJenaReasoner implementation converts a Protege-OWL model into a Jena model and then it uses the existing Pellet reasoner connection available in Jena for the inference.

The following code snippet shows how to get a Pellet reasoner instance that is accessed through Jena:

public ProtegeReasoner createPelletJenaReasoner(OWLModel owlModel) {

	// Get the reasoner manager instance
	ReasonerManager reasonerManager = ReasonerManager.getInstance();

	//Get an instance of the Protege Pellet reasoner
	ProtegeReasoner reasoner = reasonerManager.createProtegeReasoner(owlModel, ProtegePelletJenaReasoner.class);

	return reasoner;
}

Getting a Pellet reasoner instance (accessed through OWL-API)

The ProtegePelletOWLAPIReasoner implementation converts a Protege-OWL model into an OWL-API model and then it uses the existing Pellet reasoner connection available in OWL-API for the inference.

The following code snippet shows how to get a Pellet reasoner instance that is accessed through OWL-API:

public ProtegeReasoner createPelletOWLAPIReasoner(OWLModel owlModel) {

	// Get the reasoner manager instance
	ReasonerManager reasonerManager = ReasonerManager.getInstance();

	//Get an instance of the Protege Pellet reasoner
	ProtegeReasoner reasoner = reasonerManager.createProtegeReasoner(owlModel, ProtegePelletOWLAPIReasoner.class);

	return reasoner;
}

To get access to the internal Pellet reasoner and Pellet KB, you can use the methods from the ProtegePelletOWLAPIReasoner interface:

public Reasoner getPelletReasoner()

public KnowledgeBase getPelletKB()

To get access to the converted OWL-API model, you can call from the ProtegePelletOWLAPIReasoner interface:

public OWLOntology getOwlApiOntology() throws ProtegeReasonerException

Note. Even if these functionalities are available in Protege 3.x, we do recommend to use Protege-4 that accesses the OWL-API directly and has much more advanced reasoning capabilities.

Querying the reasoner for inferred information

Once a reasoner instance has been obtained, the reasoner can be queried for information about the ontology. The ProtegeReasoner interface contains several methods to obtain inferred information about classes and individuals. For example, there are methods to get the inferred superclasses and subclasses of a given class. The example below shows how to get the inferred subclasses for a specific class, in this case VegetarianPizza, which is a named class in the Pizza ontology. First, the asserted named subclasses of VegetarianPizza are retrieved via the OWLModel using vegetarianPizza.getNamedSubclasses(). In the case of this example, the number of asserted subclasses should be zero. Next, the inferred subclasses of VegetarianPizza are retrieved by querying the reasoner, and are then are printed out.

// Get the VegetarianPizza OWLNamedClass from the OWLModel 
OWLNamedClass vegetarianPizza = owlModel.getOWLNamedClass("VegetarianPizza"); 

if(vegetarianPizza != null) { 
	// Get the number of asserted subclasses of VegetarianPizza 
	Collection assertedSubclasses = vegetarianPizza.getNamedSubclasses(); 
	System.out.println("Number of asserted VegetarianPizzas: " + assertedSubclasses.size()); 

	// Now get the inferred subclasses of VegetarianPizza 
	Collection inferredSubclasses = reasoner.getSubclasses(vegetarianPizza); 
	System.out.println("Number of inferred VegetarianPizzas: " + inferredSubclasses.size()); 
	System.out.println("VegetarianPizzas:"); 
	for(Iterator it = inferredSubclasses.iterator(); it.hasNext();) { 
		OWLNamedClass curClass = (OWLNamedClass) it.next(); 
		System.out.println("\t" + curClass.getName()); 
} 

Updating Protégé-OWL with inferred information

Some of the methods on ProtegeReasoner query the reasoner to obtain inferred information and then insert this information into the OWLModel. This means that the model can be examined "offline" from the reasoner. An example of this is shown below. The classifyTaxonomy method queries the reasoner for the consistency, inferred superclasses, and equivalent classes of every class in the ontology and then inserts this information into the Protégé-OWL model. The model can then be queried for the stored inferred information.

// We can classify the whole ontology, which will put the
// inferred class hierarchy information directly into the Protégé-OWL model. 
System.out.println("Classifying taxonomy..."); 
reasoner.classifyTaxonomy(); 
System.out.println("...Classified taxonomy!"); 

// We can then use the methods on OWLNamedClass for getting inferred
// information, without having to make separate queries to the
// reasoner, as this information is now in the OWLModel. 
System.out.println("Inferred subclasses of VegetarianPizza:"); 

inferredSubclasses = vegetarianPizza.getInferredSubclasses(); 
for(Iterator it = inferredSubclasses.iterator(); it.hasNext();) { 
	OWLNamedClass curClass = (OWLNamedClass) it.next(); 
	System.out.println("\t" + curClass.getName()); 
}

System.out.println("Descendand classes of VegetarianPizza:"); 
inferredSubclasses = reasoner.getDescendantClasses(vegetarianPizza); 
for(Iterator it = inferredSubclasses.iterator(); it.hasNext();) { 
	OWLNamedClass curClass = (OWLNamedClass) it.next(); 
	System.out.println("\t" + curClass.getName()); 
}

Examples of other methods that update the OWLModel are computeInconsistentClasses, which queries the reasoner for the consistency of all classes in the ontology and the updates the OWLModel. Also, the computeInferredTypes method queries the reasoner for the inferred types of all individuals in the ontology and then updates the OWLModel.

Example

You can download the Java file for the example used in this page from here.

In order to compile and run this example, you will need to include on your Java classpath the protege.jar, all the jars from protege-owl plugins folder and also all jars from the edu.stanford.smi.protegex.owl.inference.pellet plugin folder.