The scripting language BeanShell (see http://beanshell.org) is embedded into Cogui application. This language was originally introduced because it is a good way to change the default behavior of the rules (see Scripted rules below). We finally decided to allow open use of this interpreter by introducing a new kind of objects in the Cogui projects : executable scripts. 
Scripts greatly enhance the user capabilities. For example, by providing a way to chain graph operations proposed by Cogui or include some new graph algorithms. More generally scripts can compensate the lack of a plugin architecture. Cogui Java classes and objects are exposed to the script language so that user can access on public members of existing objects and also instantiate classes to introduce new objects. 


Basics

BeanShell can dynamically execute full Java syntax, as well as loosely typed Java and additional scripting conveniences. Documentation about BeanShell can be found here. Two kinds of commands are available in cogui scripts.

  • Some native BeanShell commands are described further. All BeanShell commands are documented: BeanShell commands.
  • Cogui propose its own commands. See Cogui commands further.


Before script execution, 3 global variables are instantiated. These variables give access to the current objects loaded in Cogui. 

Global variables

Name

Description

_PRJ

represents the current project (an instance of fr.lirmm.graphik.cogui.edit.project.ICoguiProjectClass).

_KB

equivalent to _PRJ.getKnowledgeBase() return, it represents the current Knowledge Base (an instance of fr.lirmm.graphik.cogui.core.model.KnowledgeBase Class)

_VOC

equivalent to _PRJ.getVocabulary() return, it represents the current vocabulary (an instance of fr.lirmm.graphik.cogui.core.model.Vocabulary Class)


First use, the most natural, is to use scripts to access project existing objects in order to read, analyze or modify them. Global variables are pointing to objects containing all methods necessary to obtain such access. Once the concerned object is obtained, we can use the public methods as described in the API cogui.core.model. Suppose, for example that we want to visit all the vertices of a graph and count the individuals that it references.


nbGeneric=0;

g=getFact("set1/fact_1");

it=g.iteratorConcept();

while(it.hasNext())

        if(it.next().isGeneric())

               nbGeneric++;

print("graph "+g.getName()+" contains "+nbGeneric+" generic concept(s)");


Access to vocabulary elements


Element

How to obtain

The concept type hierarchy

_VOC.getConceptTypeHierarchy() or _VOC.getHierarchy(Vocabulary.CONCEPT_TYPE)

The relation type hierarchy

_VOC.getRelationTypeHierarchy() or _VOC.getHierarchy(Vocabulary.RELATION_TYPE)

The individuals

_VOC.getIndividuals()


Work with CoGui core package


Exploring graphs

CoGui propose several assistants for querying, applying rules, checking and analyzing graphs. All these operations are based on an homomorphism search provided by the CoGui solver (Solver5). 
CoGui provides a user friendly search command to explore graphs programmatically.
As an example, we will write a script which produce the list of the parents in a person relationship knowledge base. At first, user write a corresponding query.

listener()

{

      projectionFound(engine,proj)

         {

          print("coucou="+toto);

         } return this;

 };

myListener=listener();

search( getFact("set1/fact_1"), getQuery("set1/query_1"), myListener);


Work with the vocabulary

Vocabulary is a composite class containing  primarily a Hierarchy and some Translator(s)
Code below demonstrates how to define types in current vocabulary

/* 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

Translator class is a mapping between the type identifier and a pair (label,language) . 
Both labels and descriptions of each kind of types (concept, relation and nesting) are represented by instances of Translator class.
Translator can be defined to guarantee the uniqueness of labels. Unlike description translators, label translators use this option. So, for  the same language,  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)


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:

  • facts graphs
  • queries
  • rules
  • positive constraints
  • negative constraints

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");


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);


CoGui commands

Name

Description

applyRule(CGraph graph,Rule rule)
applyRule(CGraph graph,Rule rule,int limit)
applyRules(CGraph graph,ArrayList rules,int limit)
applyRules(CGraph graph,ArrayList rules,int limit,boolean scripted)

Apply the rule(s) on the graph until limit level and until saturation if limit==-1 (default).
Note: the graph is directly modified by the action of rules. Use cloning to preserve the original graph with CGraph.clone() function. 
If scripted is set to true then the scripts contained in scripted rules are called. See scripted rules for details.

CGraph getFact(String name)
CGraph getFact(String name,String set)

Return corresponding fact graph. 
Equivalent to _KB.getFactGraphSet().getByLabel(name,set) 
Example: getFact("set1/fact_1") or getFact("fact_1","set1").

CGraph getPConstraint(String name)
CGraph getPConstraint(String name,String set)

Return corresponding positive constraint. 
Equivalent to _KB.getPConstraintGraphSet().getByLabel(name,set) 
Example: getPConstraint("set1/pconstraint_1") or getPConstraint("pconstraint_1","set1").

CGraph getPrototypic(String name)
CGraph getPrototypic(String name,String set)

Return corresponding prototypic graph. 
Equivalent to _KB.getPrototypicGraphSet().getByLabel(name,set) 
Example: getPrototypic("set1/proto_1") or getPrototypic("proto_1","set1").

CGraph getQuery(String name)
CGraph getQuery(String name,String set)

Return corresponding query graph. 
Equivalent to _KB.getQueryGraphSet().getByLabel(name,set) 
Example: getQuery("set1/query_1") or getQuery("query_1","set1").

search(CGraph graph, CGraph query, bsh.This pListener)

pListener is scripted object containing a callback method: projectionFound(Solver solver,Projection proj).

Created with the Personal Edition of HelpNDoc: Free EPub and documentation generator