Example programs using Ortiz, Pellet 3.0's new native API for OWL

Example01_CreateOntology.java

package com.clarkparsia.pellet.examples;

import java.io.IOException;
import java.io.PrintWriter;

import com.clarkparsia.pellet.api.kb.Ontology;
import com.clarkparsia.pellet.api.kb.OntologyFactory;
import com.clarkparsia.pellet.api.kb.OntologySyntax;
import com.clarkparsia.pellet.api.term.TermFactory;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.api.term.entity.NamedIndividual;

/**
 * @author Evren Sirin
 */
public class Example01_CreateOntology {
  // Namespace for the primer ontology
  private static final String FAMILY = "http://example.com/owl/families/#";
  // Namespace for the test ontology
  private static final String NS = "http://example.com/test#";

  public static void main(String args[]) throws IOException {
    // Read the primer ontology into a fresh ontology instance
    Ontology primerOnt = OntologyFactory.readOntology("file:examples/data/primer.owl");

    // Create an empty ontology with the given name
    Ontology ont = OntologyFactory.createOntology(NS);
    // Add the primer ontology as an import to the test ontology
    ont.addImport(primerOnt);

    // Create a class and an individual
    NamedClass Person = TermFactory.namedClass(FAMILY + "Person");
    NamedIndividual evren = TermFactory.namedIndividual(NS + "evren");

    // Add a type assertion to the test ontology
    ont.add(evren.type(Person));

    // Write the contents of the test ontology in turtle format
    ont.write(new PrintWriter(System.out), OntologySyntax.TURTLE);
  }
}
~   

Example02_CreateKB.java

package com.clarkparsia.pellet.examples;

import java.io.IOException;

import com.clarkparsia.pellet.api.kb.KnowledgeBase;
import com.clarkparsia.pellet.api.kb.Ontology;
import com.clarkparsia.pellet.api.kb.OntologyFactory;
import com.clarkparsia.pellet.api.kb.impl.DefaultKnowledgeBaseFactory;
import com.clarkparsia.pellet.api.term.TermFactory;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.api.term.entity.NamedIndividual;

/**
 * @author Evren Sirin
 */
public class Example02_CreateKB {
	// Namespace for the primer ontology
	private static final String FAMILY = "http://example.com/owl/families/#";
	// Namespace for the test ontology
	private static final String NS = "http://example.com/test#";

	public static void main(String args[]) throws IOException {
		// create a KB using the factory
		KnowledgeBase kb = DefaultKnowledgeBaseFactory.getInstance().createKB();

		// Read the primer ontology into a fresh ontology instance
		Ontology primerOnt = OntologyFactory.readOntology("file:examples/data/primer.owl");

		// Loads the primer ontology to the KB
		kb.load(primerOnt);

		System.out.println("Number of axioms: " + kb.getAxioms().size());
		System.out.println("Number of ontologies: " + kb.getOntologies(true).size());

		// Create a class and an individual
		NamedClass Person = TermFactory.namedClass(FAMILY + "Person");
		NamedIndividual evren = TermFactory.namedIndividual(NS + "evren");

		// Add a type assertion to the KB (not the loaded ontology)
		kb.add(evren.type(Person));

		System.out.println("Number of axioms: " + kb.getAxioms().size());
		System.out.println("Number of ontologies: " + kb.getOntologies(true).size());

		// Unload the ontology from the KB
		kb.unload(primerOnt);

		System.out.println("Number of axioms: " + kb.getAxioms().size());
		System.out.println("Number of ontologies: " + kb.getOntologies(true).size());

		// Read contents of the ontology into the KB directly (number of axioms will change but number of ontologies will
		// stay same). As a result there will be no easy way to remove only the axiom from this ontology.
		kb.read("file:examples/data/primer.owl");

		System.out.println("Number of axioms: " + kb.getAxioms().size());
		System.out.println("Number of ontologies: " + kb.getOntologies(true).size());
	}
}

Example03_CreateAxioms.java

package com.clarkparsia.pellet.examples;

import static com.clarkparsia.pellet.api.term.TermFactory.literal;
import static com.clarkparsia.pellet.api.term.TermFactory.namedClass;
import static com.clarkparsia.pellet.api.term.TermFactory.namedDataProperty;
import static com.clarkparsia.pellet.api.term.TermFactory.namedIndividual;
import static com.clarkparsia.pellet.api.term.TermFactory.namedObjectProperty;

import com.clarkparsia.pellet.api.kb.KnowledgeBase;
import com.clarkparsia.pellet.api.kb.impl.DefaultKnowledgeBaseFactory;
import com.clarkparsia.pellet.api.term.entity.DataProperty;
import com.clarkparsia.pellet.api.term.entity.Individual;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.api.term.entity.ObjectProperty;

/**
 * @author Evren Sirin
 */
public class Example03_CreateAxioms {
	private static final String NS = "http://example.org/test#";

	public static void main(String args[]) {
		// ===========================================================
		// Entity creation
		// ===========================================================

		// create classes
		NamedClass Person = namedClass(NS + "Person");
		NamedClass Man = namedClass(NS + "Male");
		NamedClass Woman = namedClass(NS + "Female");
		NamedClass Parent = namedClass(NS + "Parent");
		NamedClass Mother = namedClass(NS + "Mother");
		NamedClass Father = namedClass(NS + "Father");

		// create object properties
		ObjectProperty hasParent = namedObjectProperty(NS + "hasParent");
		ObjectProperty hasChild = namedObjectProperty(NS + "hasChild");
		ObjectProperty hasFather = namedObjectProperty(NS + "hasFather");
		ObjectProperty hasMother = namedObjectProperty(NS + "hasMother");

		// create data properties
		DataProperty hasName = namedDataProperty(NS + "hasName");
		DataProperty hasAge = namedDataProperty(NS + "hasAge");

		// create individuals
		Individual john = namedIndividual(NS + "john");
		Individual jack = namedIndividual(NS + "jack");

		// ===========================================================
		// KB creation and axiom addition
		// ===========================================================

		// create a KB using the factory
		KnowledgeBase kb = DefaultKnowledgeBaseFactory.getInstance().createKB();

		// add an annotation
		kb.add(Person.comment("Represents the set of all people."));
		// add simple axioms
		kb.add(Woman.subClassOf(Person));
		kb.add(Mother.subClassOf(Woman));
		kb.add(Man.disjointWith(Woman));
		// add axioms that contains class expressions
		kb.add(Parent.equivalentTo(hasChild.some(Person)));
		kb.add(Parent.equivalentTo(Mother.or(Father)));
		kb.add(Person.subClassOf(hasFather.some(Man)));
		kb.add(Person.subClassOf(hasMother.only(Woman)));
		kb.add(Person.subClassOf(hasMother.min(1)));
		kb.add(Person.subClassOf(hasParent.exactly(2, Parent)));

		// add property axioms
		kb.add(hasParent.domain(Person));
		kb.add(hasParent.range(Parent));
		kb.add(hasChild.inverseOf(hasParent));
		kb.add(hasFather.subPropertyOf(hasParent));
		kb.add(hasMother.subPropertyOf(hasParent));
		kb.add(hasAge.functional());

		// add type assertions
		kb.add(john.type(Man));
		// add property assertion
		kb.add(john.fact(hasParent, jack));
		// add a data property assertion with a plain literal
		kb.add(john.fact(hasName, literal("john")));
		// add a data property assertion with a typed literal (xsd:int)
		kb.add(john.fact(hasAge, literal(30)));

		// ===========================================================
		// Print statistics about the KB
		// ===========================================================

		System.out.println("Number of axioms: " + kb.getAxioms().size());
		System.out.println("Number of classes: " + kb.getClasses().size());
		System.out.println("Number of object properties: " + kb.getObjectProperties().size());
		System.out.println("Number of data properties: " + kb.getDataProperties().size());

		// ===========================================================
		// Axiom removal
		// ===========================================================

		// remove an assertion 
		kb.remove(john.type(Man));
		// remove will succeed as long as the given axiom is structurally equivalent to a contained axiom
		kb.remove(Parent.equivalentTo(Father.or(Mother)));
		// removal of inferences is not supported so the following call will not change the KB
		kb.remove(Person.subClassOf(hasFather.only(Woman)));
	}
}

Example04_BasicQuery.java

package com.clarkparsia.pellet.examples;

import static com.clarkparsia.pellet.api.term.TermFactory.namedClass;
import static com.clarkparsia.pellet.api.term.TermFactory.namedDataProperty;
import static com.clarkparsia.pellet.api.term.TermFactory.namedObjectProperty;
import static com.clarkparsia.pellet.util.Vars.CLS;
import static com.clarkparsia.pellet.util.Vars.IND;
import static com.clarkparsia.pellet.util.Vars.LIT;

import java.io.IOException;
import java.util.Collection;

import com.clarkparsia.pellet.api.kb.KnowledgeBase;
import com.clarkparsia.pellet.api.kb.impl.DefaultKnowledgeBaseFactory;
import com.clarkparsia.pellet.api.term.entity.DataProperty;
import com.clarkparsia.pellet.api.term.entity.Individual;
import com.clarkparsia.pellet.api.term.entity.Literal;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.api.term.entity.ObjectProperty;
import com.clarkparsia.pellet.legacy.PelletLegacyKnowledgeBaseFactory;

/**
 * @author Evren Sirin
 */
public class Example04_BasicQuery {
	private static final String NS = "http://example.org/test#";

	public static KnowledgeBase createKB() {
		return PelletLegacyKnowledgeBaseFactory.getInstance().createKB();
	}

	public static void main(String args[]) throws IOException {
		// create a KB using the factory
		KnowledgeBase kb = DefaultKnowledgeBaseFactory.getInstance().createKB();

		// Read the primer ontology directly into the KB
		kb.read("file:examples/data/primer.owl");

		// ===========================================================
		// Entity creation
		// ===========================================================

		// create classes
		NamedClass Person = namedClass(NS + "Person");
		NamedClass Parent = namedClass(NS + "Parent");
		NamedClass Mother = namedClass(NS + "Mother");
		NamedClass Father = namedClass(NS + "Father");

		// create object properties
		ObjectProperty hasParent = namedObjectProperty(NS + "hasParent");

		// create data properties
		DataProperty hasAge = namedDataProperty(NS + "hasAge");

		// ===========================================================
		// Boolean queries
		// ===========================================================

		// check the consistency of the KB
		boolean consistent = kb.isConsistent();
		System.out.println("Consistent: " + consistent);

		// Check the satisfiability of a named class
		if (kb.isSatisfiable(Person)) {
			System.out.println("Satisfiable: Person");
		}

		// Check the satisfiability of a class expression
		if (!kb.isSatisfiable(Mother.and(Father))) {
			System.out.println("Unsatisfiable: Mother and Father");
		}

		// Check for a subclass inference. Any axiom that does not contain variables can be used as a boolean query.
		if (kb.ask(Father.subClassOf(Parent))) {
			System.out.println("Father is a subclass of PArent");
		}

		// ===========================================================
		// Retrieval queries
		// ===========================================================

		// Query the KB for direct subclasses of Person. The query is an axiom that contains a variable. We are using
		// a predefined variable Vars.CLS. We are specifying the variable for which the bindings will be returned.
		Iterable<NamedClass> subClasses = kb.select(CLS, CLS.directSubClassOf(Person));
		System.out.println("Class: " + Person);
		System.out.println("+ SubClasses: " + subClasses);

		// Any axiom can be used in retrieval queries as long as there is a variable in the axiom.
		Iterable<Individual> personInstances = kb.select(IND, IND.type(Person));
		for (Individual person : personInstances) {
			System.out.println("Person: " + person);

			// Get the values for hasAge property
			Collection<Literal> ages = kb.select(LIT, person.fact(hasAge, LIT));
			// Either we don't know the age or there is a single value we can print directly
			if (ages.isEmpty()) {
				System.out.println("+ Age: ?");
			}
			else {
				System.out.println("+ Age: " + ages.iterator().next());
			}

			// Print all the property values
			Collection<Individual> parents = kb.select(IND, person.fact(hasParent, IND));
			for (Individual p : parents) {
				System.out.println("+ Parent: " + p);
			}
		}
	}
}

Example05_SPARQL.java

package com.clarkparsia.pellet.examples;

import static com.clarkparsia.pellet.api.term.TermFactory.individualVariable;
import static com.clarkparsia.pellet.api.term.TermFactory.literalVariable;
import static com.clarkparsia.pellet.api.term.TermFactory.namedClass;
import static com.clarkparsia.pellet.api.term.TermFactory.namedDataProperty;
import static com.clarkparsia.pellet.api.term.TermFactory.namedIndividual;
import static com.clarkparsia.pellet.api.term.TermFactory.namedObjectProperty;
import static com.clarkparsia.pellet.api.term.TermFactory.objectPropertyVariable;

import java.io.IOException;

import com.clarkparsia.pellet.api.kb.KnowledgeBase;
import com.clarkparsia.pellet.api.kb.impl.DefaultKnowledgeBaseFactory;
import com.clarkparsia.pellet.api.query.Binding;
import com.clarkparsia.pellet.api.query.QueryEngine;
import com.clarkparsia.pellet.api.query.QueryEngineFactory;
import com.clarkparsia.pellet.api.query.QueryFactory;
import com.clarkparsia.pellet.api.query.ResultSet;
import com.clarkparsia.pellet.api.query.SelectQuery;
import com.clarkparsia.pellet.api.term.entity.DataProperty;
import com.clarkparsia.pellet.api.term.entity.Individual;
import com.clarkparsia.pellet.api.term.entity.IndividualVariable;
import com.clarkparsia.pellet.api.term.entity.LiteralVariable;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.api.term.entity.ObjectProperty;
import com.clarkparsia.pellet.api.term.entity.ObjectPropertyVariable;

/**
 * @author Evren Sirin
 */
public class Example05_SPARQL {
	private static final String NS = "http://example.org/test#";

	public static void main(String args[]) throws IOException {
		// create a KB using the factory
		KnowledgeBase kb = DefaultKnowledgeBaseFactory.getInstance().createKB();

		// Read the primer ontology directly into the KB
		kb.read("file:examples/data/primer.owl");

		// create variables and constants to use in the query
		ObjectPropertyVariable p = objectPropertyVariable("p");
		IndividualVariable v = individualVariable("v");
		Individual john = namedIndividual(NS + "john");
		
		// Create a select query to retrieve all the property values for individual john
		SelectQuery q = QueryFactory.select(p, v).where(john.fact(p, v)).build();
		// Create a query engine and execute it
		QueryEngine qe = QueryEngineFactory.createQueryEngine(kb);
		ResultSet propertyValues = qe.execute(q);
		System.out.println("All object property values for: " + john);
		// Print the results. In the results, p will be mapped to an object property and v to an individual
		for (Binding result : propertyValues) {
			System.out.println("+ Prop: " + result.apply(p) + " Value: " + result.apply(v));
		}


		// create variables and constants that will be used in the query.
		IndividualVariable child = individualVariable("child");
		IndividualVariable parent = individualVariable("parent");
		LiteralVariable age = literalVariable("age");
		ObjectProperty hasChild = namedObjectProperty(NS + "hasChild");
		DataProperty hasAge = namedDataProperty(NS + "hasAge");
		NamedClass Man = namedClass(NS + "Male");
		
		// create a query with multiple result variables and query atoms
		SelectQuery query = QueryFactory
			.select(parent, child, age)
			.where(parent.fact(hasChild, child),
					child.fact(hasAge, age),
					child.type(Man))
			.orderBy(age)		
		    .build(); 

		// execute the query and print results
		ResultSet results = qe.execute(query);
		System.out.println("Query: ");
		System.out.println(query);
		System.out.println("Result: ");
		for (Binding result : results) {
			System.out.println(result);
		}

		// Create the same query from a SPARQL string
		query = QueryFactory.parseSelect("PREFIX : " + NS + " "
		                            + "SELECT parent child age "
		                            + "WHERE { "
		                            + "		?parent :hasChild ?child . "
		                            + "		?child :hasAge ?age ."
		                            + "		?child a Male ."
		                            + "}");

		System.out.println("Query: " + query);
		for (Binding result : qe.execute(query)) {
			System.out.println(result);
		}
	}
}

Example06_Classification.java

package com.clarkparsia.pellet.examples;

import static com.clarkparsia.pellet.api.term.TermFactory.namedClass;

import java.io.IOException;
import java.util.Set;

import com.clarkparsia.pellet.api.kb.KnowledgeBase;
import com.clarkparsia.pellet.api.kb.ReasoningTask;
import com.clarkparsia.pellet.api.kb.impl.DefaultKnowledgeBaseFactory;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.hierarchy.Hierarchy;
import com.clarkparsia.pellet.hierarchy.HierarchyNode;

/**
 * @author Evren Sirin
 */
public class Example06_Classification {
	private static final String NS = "http://example.org/test#";

	public static void main(String args[]) throws IOException {
		// Create a KB using the factory
		KnowledgeBase kb = DefaultKnowledgeBaseFactory.getInstance().createKB();

		// Read the primer ontology directly into the KB
		kb.read("file:examples/data/primer.owl");

		// Optional call to force classification before any query. Performing classification will compute all the
		// subclasses and equivalences for named classes in the KB. Omitting this call will not change the query results
		// later on. This call is useful if classification for a KB is known to be long and it is desirable to do the
		// classification before a query comes in.
		kb.perform(ReasoningTask.CLASSIFICATION);

		// Gets the classification hierarchy. A hierarchy is composed of nodes where each node contains one or more
		// classes. Multiple classes in a node are equivalent to each other. Each node has at least one sub and one
		// super node except top which has no super node and bottom which has no sub node.
		//
		// A hierarchy is a utility class to make it easier to traverse the class hierarchy. The information provided by
		// a hierarchy can also be retrieved by querying the KB but the hierarchy provides the information in a more
		// structured way.
		Hierarchy<NamedClass> hierarchy = kb.getClassHiearchy();

		// Print the equivalents of Person class

		NamedClass Person = namedClass(NS + "Person");
		Set<NamedClass> equivalents = hierarchy.getEquivalents(Person);
		System.out.println(equivalents);

		// Print the sub classes of the  Person class
		Iterable<HierarchyNode<NamedClass>> subs = hierarchy.getSubs(Person);
		for (HierarchyNode<NamedClass> sub : subs) {
			// A hierarchy node is iterable so we can iterate through its elements
			for (NamedClass subClass : sub) {
				System.out.print(subClass + " ");
			}
			System.out.println();
		}
		// Direct sub classes can be retrieved in a similar way
		Iterable<HierarchyNode<NamedClass>> directSubs = hierarchy.getDirectSubs(Person);
		System.out.println(directSubs);

		// We can access the nodes directly as well. Get the top node in the class hierarchy. This node will contain
		// owl:Thing and all its equivalents.
		HierarchyNode<NamedClass> top = hierarchy.getTop();
		// This will print owl:Thing and its equivalents (if any)
		System.out.println(top.getElements());

	}
}

Example07_Explanation.java

package com.clarkparsia.pellet.examples;

import static com.clarkparsia.pellet.api.term.TermFactory.namedClass;

import java.io.IOException;
import java.util.Iterator;
import java.util.Set;

import com.clarkparsia.pellet.api.kb.KnowledgeBase;
import com.clarkparsia.pellet.api.kb.impl.DefaultKnowledgeBaseFactory;
import com.clarkparsia.pellet.api.term.axiom.Axiom;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.explanation.Explainer;
import com.clarkparsia.pellet.explanation.ExplainerFactory;

/**
 * @author Evren Sirin
 */
public class Example07_Explanation {
	private static final String NS = "http://example.org/test#";

	public static void main(String args[]) throws IOException {
		// create a KB using the factory
		KnowledgeBase kb = DefaultKnowledgeBaseFactory.getInstance().createKB();

		// Read the primer ontology directly into the KB
		kb.read("file:examples/data/primer.owl");

		// create classes
		NamedClass Parent = namedClass(NS + "Parent");
		NamedClass Mother = namedClass(NS + "Mother");
		NamedClass Father = namedClass(NS + "Father");

		// Create explainer
		Explainer explainer = ExplainerFactory.createExplainer(kb);

		// Get a single explanation for unsatisfiability and print it. An explanation is a minimal set of axioms that
		// causes an axiom to be inferred. 
		Set<Axiom> explanation = explainer.explainUnsatisfiable(Mother.and(Father)).next();
		System.out.println(explanation);

		// Note that the explanation iterator is guaranteed to contain at least one element so we don't need a hasNext()
		// check. In the case of satisfiable classes, the iterator will contain a single empty set
		System.out.println(explainer.explainUnsatisfiable(Parent));

		// Get all the explanations for an inference and print them all
		Iterator<Set<Axiom>> explanations = explainer.explain(Father.subClassOf(Parent));
		while (explanations.hasNext()) {
			System.out.println(explanations.next());
		}
		
		// If we are interested in retrieving a single explanation for an inference we can ask the KB directly 
		explanation = kb.explain(Mother.subClassOf(Parent));
		System.out.println(explanation);

	}
}

Example08_Rules.java

package com.clarkparsia.pellet.examples;

import static com.clarkparsia.pellet.api.term.TermFactory.individualVariable;
import static com.clarkparsia.pellet.api.term.TermFactory.namedClass;
import static com.clarkparsia.pellet.api.term.TermFactory.namedObjectProperty;

import java.io.IOException;

import com.clarkparsia.pellet.api.kb.KnowledgeBase;
import com.clarkparsia.pellet.api.kb.impl.DefaultKnowledgeBaseFactory;
import com.clarkparsia.pellet.api.query.Binding;
import com.clarkparsia.pellet.api.query.QueryEngine;
import com.clarkparsia.pellet.api.query.QueryEngineFactory;
import com.clarkparsia.pellet.api.query.QueryFactory;
import com.clarkparsia.pellet.api.query.ResultSet;
import com.clarkparsia.pellet.api.query.SelectQuery;
import com.clarkparsia.pellet.api.term.entity.IndividualVariable;
import com.clarkparsia.pellet.api.term.entity.NamedClass;
import com.clarkparsia.pellet.api.term.entity.ObjectProperty;
import com.clarkparsia.pellet.api.term.rule.Rule;
import com.clarkparsia.pellet.api.term.rule.RuleFactory;

/**
 * @author Evren Sirin
 */
public class Example08_Rules {
	private static final String NS = "http://example.org/test#";

	public static void main(String args[]) throws IOException {
		// create a KB using the factory
		KnowledgeBase kb = DefaultKnowledgeBaseFactory.getInstance().createKB();

		// Read the primer ontology directly into the KB
		kb.read("file:examples/data/primer.owl");

		// Create necessary entities
		NamedClass Male = namedClass(NS + "Male");
		ObjectProperty hasParent = namedObjectProperty(NS + "hasParent");
		ObjectProperty hasFather = namedObjectProperty(NS + "hasFather");

		// Create variables that will be used in the rule
		IndividualVariable child = individualVariable("child");
		IndividualVariable parent = individualVariable("parent");

		// Create the following rule	 
		// hasParent(?child, ?parent) ^ Male(?parent)
		// ->
		// hasFather(?child, ?parent)
		//
		Rule rule = RuleFactory
			.head(child.fact(hasFather, parent))
			.body(child.fact(hasParent, parent),
		          parent.type(Male))
		    .build();
		kb.add(rule);

		// Query to retrieve all child-father pairs
		SelectQuery query = QueryFactory.selectAll().where(child.fact(hasFather, parent)).build();

		// Execute the query and print the results
		QueryEngine qe = QueryEngineFactory.createQueryEngine(kb);
		ResultSet results = qe.execute(query);
		System.out.println("Result: ");
		for (Binding result : results) {
			System.out.println(result);
		}
	}
}