Cogui - Core API  v2.0

Build a vocabulary Build a graph

Build a vocabulary

Code below demonstrates how to create a vocabulary and how to define types in it

/* create a vocabulary */
Vocabulary voc = new Vocabulary("my_vocabulary", false);

/* create a concept type */
voc.addConceptType("ct_1", "top", "the root type", "en");

/* create a binary relation type with the signature (top,top)
voc.addRelationType("rt_1","link","the root type for binary relation types","en");
voc.setSignature("rt_1",new String[]{"ct_1","ct_1"});

/* create a nesting type */
voc.addNestingType("nt_1","nesting","the root nesting type","en");

Translator

Vocabulary is a composite class containing  primarily a Hierarchy and some Translator(s)
Translator class is a mapping between the type identifier and a pair (label,langage) .
Both labels and descriptions of each kind of types (concept, relation and nesting) are represented by instances of Tranlator class.
Translator can be defined to guarantee the uniqueness of labels. Unlike description translators, label translators use this option. So, for  the same langage,  two different identifiers cannot be associated to the same label.
With this property the method getId ( String label , String language )  can be used to search id efficiently on a double map.

/* code below is equivalent to this Vocabulary call:
** voc.addConceptType("ct_1", "top", "the root type", "en");
*/
Translator labelTranslator=voc.getTranslator(Vocabulary.CONCEPT_TYPE);
Translator descrTranslator=voc.getDescriptionTranslator(Vocabulary.CONCEPT_TYPE);

labelTranslator.addLabel("ct_1", "top","en");
descrTranslator.addLabel("ct_1","the root type", "en");

/* id of types can be found with label */
System.out.println("id="+voc.getTranslator(Vocabulary.CONCEPT_TYPE).getId("top","en")+
	" label="+voc.getTranslator(Vocabulary.CONCEPT_TYPE).getLabel("ct_1","en"));

Use getDefaultLabel(String id) for monolingual vocabulary. Cogui also use monolingual Tranlator to store individuals.
Code below print labels of a type. Method getLanguage(String id) search every translations for a type.

for(String lang:labelTranslator.getLanguages("ct_1"))
	System.out.println("label="+labelTranslator.getLabel("ct_1",lang)+" lang="+lang);

Hierarchy

When Translator(s) store labels and other informations about types, Hierarchy complete the model with a directed graph representation of the kindOf relationShip between types.
Vocabulary give accessors for each Hierarchy instance:

• getConceptTypeHierarchy() equivalent to getHierarchy(Vocabulary.CONCEPT_TYPE)
• getRelationTypeHierarchy() equivalent to getHierarchy(Vocabulary.RELATION_TYPE)
• getNestingTypeHierarchy() equivalent to getHierarchy(Vocabulary.NESTING_TYPE)

Example below show how to access the hierarchy and add two concept types ct_1 and ct_2 where ct_2 is a kind of ct_1:

Hierarchy ctH=voc.getConceptTypeHierarchy();
ctH.addVertex("ct_1");
ctH.addVertex("ct_2");
ctH.addEdge("ct_2","ct_1");
System.out.println("ct_2 is kind of ct_1 ? "+ctH.isKindOf("ct_2","ct1"));

Hierarchy give efficient access to the graph to iterate vertices or incoming and outgoing edges.

• edgeSet() and iteratorEdge()to explore all edges
• edgeSet(String) and iteratorEdge(String) to access edges of a given vertex
• incomingEdgeSet(String) and iteratorIncomingEdge(String) to access incoming edges of a given vertex
• outgoingEdgeSet(String) and iteratorOutgoingEdge(String) to access outgoing edges of a given vertex
• vertexSet() and iteratorVertex() to explore all vertices

 
This is useful to write your own algorithm. But some graph algorithm are already implemented by Hierarchy class
most of them are wrapped from JGraphT library Hierarchy can be overloaded to access other algorithm not already used by Cogui.
Following tools are proposed by Hierarchy class:

• about transitivity: a closure and a transitive reduction
• a cycle detector and a method to iterate all connected components
• several methods to compare (isKindOf) and normalize sets of types (normalize(String[]) and isRedundant(String[]))

Build a fact graph

After defining a Vocabulary instance, we will programmatically build facts based on this vocabulary. For this purpose the KnowledgeBase class was designed to associate a vocabulary with a set of facts and possibly with rules, constraints, prototypics etc.

KnowledgeBase

KnowledgeBase is a composite class designed to associate a vocabulary with:

• a set of facts graphs
• a set of query graphs
• a set of rules
• a set of prototypic graphs
• a set of pattern graphs
• a set of individual graphs
• a set of positive constraints
• a set of negative constraints
• a set of individual graphs

A Knowledge instance is used to store and give access to the graphs directly or throw access to GraphSet instances

KnowledgeBase kb=new KnowledgeBase(voc);
/* this two instructions below are equivalent */
kb.getFactGraph("g_1");
kb.getFactGraphSet().get("g_1");

Now we will create and populate a fact graph to store it inside the knowledge base.

CGraph

Cgraph is composed by a set of Concept and a set of Relation mapped with their keys and a Multigraph instance represent the graph itself. Code below shows how to create and populate a CGraph instance.

/* create the graph */
CGraph graph=new CGraph("g_1", "my graph name", "my_facts", "fact");
/* create the concepts and a relation */
Concept c1=new Concept("c_1");
Concept c2=new Concept("c_2");
c1.setType("ct_1");
c2.setType("ct_2");
Relation r1=new Relation("r_1");
r1.setType("rt_1");
/* populate the graph with vertices */
graph.addVertex(c1);
graph.addVertex(c2);
graph.addVertex(r1);
/* add edges */
graph.addEdge(c1.getId(),r1.getId(),1);
graph.addEdge(c2.getId(),r1.getId(),2);
/* add the fact graph to the knowledge base */
kb.addGraph(graph);