Protégé Browser, v. 1.0
Warren Shen (whshen@cs.stanford.edu)
Table of Contents
I. Background
II. Overview
III. Installation
IV. The Components of the Browser
D. Query
VI. Using the Browser with Protégé
A. Annotation
B. Thumbnails
Protégé-2000 is an application developed in the Stanford Medical Informatics department that allows users to create and edit knowledge bases. Sometimes the user will work with several projects simultaneously, since separate knowledge bases may be related or dependent on each other.
The Browser was written to facilitate working with multiple projects. Working with many projects can be confusing and cumbersome to manage them since Protégé-2000 provides no mechanism to view them all at once. The Browser allows the user to view a library of projects in a number of different ways in order to make it easier to manage them.
The following document will describe how to use the Browser and how to extend it.
While the Browser is used primarily to manage a collection of Protégé projects, it can be easily extended to support other types of objects.
There are four main components to the Browser:
- Library Overview - This lists all the items in the library and displays a few summary details about each of them.
- Selection Summary - This view contains one window that lists all the details about a particular item, and another window that displays a thumbnail that gives a graphical summary of the item.
- Dependencies - This view shows a graph showing how each of the items in the library depends other items. For example, if one project includes another project, the graph will show a node for each project, and an arrow between them will indicate the dependence.
- Query - This component allow the user to perform queries on the items in the library.
The Browser theoretically should be able to work on any machine, although it has only been tested on Windows platforms. All the included .jar files should be in the same directory. The command to run the Browser is:
java -cp browser.jar;protege.jar;grappa1_2.jar;ontoviz.jar;pal.jar
browser.Browser
where in the place of "java" you may need to put
the path to your java program (e.g., "C:\jdk1.3\bin\java"). In one of the download versions, a JRE is
included so that you in place of "java" you can write ".\jre\bin\java".
If you are running the Browser on Windows, you can simply double click on Browser.bat to run the program. You may need to edit Browser.bat to enter in the correct path to your java program.
It is important to make sure the paths programs and directory that the Browser uses are correct. These can be changed in the configuration panel by going to “File” menu, selecting “Configure Browser”, and going to the “General” tab.
- Protégé Directory - The directory that Protégé is in
- Protégé Command - The command to run Protégé (i.e. the path of the Protégé executable)
- Graphviz Executable - The command line to execute the dot program included in graphviz. An executable for Windows should be included in the download. To read about graphviz or to download other versions of it, go to http://www.research.att.com/sw/tools/graphviz/
- Plugins
Directory - The directory
that contains the jar files of the various items that the browser
supports. See the section "Extending the Browser" for more details.
IV. The Components of the Browser
The Library Overview lists all the items in the library and displays some details about each item. Using the table, you can perform operations with the library, such as selecting which items you want to view in more detail, adding or removing items from the library, or launching other application such as Protégé.
Below we can see a sample view of the Library Overview. The table consists of several columns that list some attributes of each item; this table serves as a summary of the whole library that you can scan quickly. To select which attributes will be displayed in the table, go to File->Configure Browser. You can select choices from a list of attributes in the tab labeled "Library Overview".
Note that the available attributes that the table shows will be based on the item you add. If you add a Protégé project that has not been annotated, the only columns showing will be the file name. See the “Annotation” section for more information on how to annotate a project.
Below the main table is a list of included items. When you select an item, the window at the bottom will show a list of all the items that are included. To add one of the included items to the library, selected the item and click on the “up” button in the lower window.
Notes:
1. To select more than one item:
Use the CTRL or SHIFT key and click (on Windows)
Use the APPLE key and click (on Mac)
2. When adding items, you can select an individual file, select multiple files, or select a directory. For Protégé projects, if you select a directory, the Browser will add all the projects in the directory (non-recursively).
Figure 1 - The Library Overview lists the items in the library and displays selected attributes of those items.
When you select an item, the Selection Summary will give you a closer look at that item. On the top, there is a window that shows all the details of that item, and on the bottom, there is thumbnail of the item. In the screenshot below, the top window shows the values of certain slots in the Protégé project, and the bottom window displays a graph that shows the top three levels of the class structure of the knowledge base.
A more detailed description of how the slot values and thumbnail are retrieved is in the section "Using the Browser with Protégé".
Figure 2 - The selection summary gives a more detailed view a single item.
The Dependencies Lattice displays a graph that shows how each of the items in the library depend on each other. In the screenshot below, the graph shows how each Protégé project is included in other projects. For example, in this library, the Malaria4 project includes EST1, Clinical_Ontology, and LowLevel_TAMBIS_In_Work.
The green nodes indicate items that are in the library, and the gray nodes indicate items that are not explicitly in the library, but are related to items that are. You may click on the green nodes to select that item.
When you go to the Dependencies tab, you will not see a graph until you click on the update button. If you change the library (e.g., add or remove an item), click on the update button to redraw the graph.
In the Dependencies tab, the LibraryOverview has a column labeled “Active”. The graph that is generated will only show items that are checked as “active” except for the inactive items that are included by active items.
Figure 3 - The Dependencies Lattice shows a graph that displays how each item depends on other items.
The Query tab allows you to perform queries on all the items in the library. The query consists of two parts: the type, and the name. In the screenshot below, you can see a query that searches for classes of the Protégé project in the library. On the left is a pull-down menu that allows you to select the type of query, and on the right is the text field where you enter in the name of what you are looking for. For Protégé projects, you can simply query a part of a word, and the query tab will search for results that contain your query string, as illustrated below in the screenshot.
The Query tab will only perform searches over the items in the LibraryOverview table that are checked as “active”.
For this particular example, the types of queries allowed for a Protégé project are annotation (i.e., creator, timestamp, keywords), classes, or slots. The process for querying Protégé projects is described in more detail in the section "Using the Browser with Protégé".
Figure 4 - The Query panel allows the user to query each item in the library
A Browser library is simply a collection of items that you are browsing. The Browser allows you to save and load libraries so that you don’t have to keep on adding items manually every time you use the Browser. The “File” menu includes four actions related to using Browser libraries:
New Library – This will “reset” the browser by clearing all the current items so that you can start with an empty library.
Load Library – This will allow you to choose a library file to load.
Save Library – This will save the current library you are working with.
Save As – This will allow you to specify a name to save your current library as
Library files are stored with the extension “.plib”. The reason why they are not called Protégé libraries is because they can contain a mixture of different types of items, which will be explained more fully in the section, “Extending the Browser”.
VI. Using the Browser with Protégé
The primary purpose of the Browser is for managing a library of Protégé projects. This section describes how all the annotation (i.e., the information about the projects that the Browser displays) is retrieved, how the thumbnail (displayed in the Selection Summary tab) is generated, and how projects are queried.
Below is a screenshot of the annotation for a Protégé project. When you want to annotate your project, the information is actually part of the knowledge base itself, contained in an instance of the annotation class (which must be named ":SUMMARY"). The instance must be named ":SUMMARY_INSTANCE". The Browser will automatically extract the annotation from this instance in the project, so you may add or remove slots from the summary instance.
Figure 5 - When using the Browser to browse Protege projects, all the annotation is contained in the :SUMMARY_INSTANCE
Currently, there is no convenient way to create the :SUMMARY class or :SUMMARY_INSTANCE other than to manually create both of them or to include a project that has the summary class already. Included in this release is a Protégé project, Annotation.pprj, that contains the :SUMMARY class. You can include Annotation.pprj in the project you are working with, create the :SUMMARY_INSTANCE, and fill in the values.
Ideally, Protégé would provide an easy way for the user to annotate the project, and for the summary instance to be automatically filled in.
Besides retrieving annotation information, the Browser can also generate a graphical summary of what the project is about, which is displayed in the Thumbnail window. The Browser will first look in :SUMMARY_INSTANCE to see if there is a slot named :THUMBNAIL_FILE. If so, it will display the image file specified in the slot.
If there is no slot named :THUMBNAIL_FILE or if the slot does not have a value, the Browser will load the knowledge base and draw a graph showing the top three class levels. From this picture the user can quickly scan what types of classes are present to see if the knowledge base is of interest. At the top of the thumbnail is a text field that allows you to change how many levels of classes to display. The graph will have two types of nodes: the green nodes will represent classes defined in the selected project, and the gray nodes will represent classes that are defined in an included project.
C. Queries
The Browser offers a way to quickly query multiple Protégé projects. It is a simple query that allows you to search for the names of classes, slots, and annotation. In order to do a more detailed search, such as searching for slots with certain values, you need to use the Query tab in Protégé itself, which you can launch from the Browser.
As was mentioned in the section on the Query tab, you only need to type in part of a word when searching over Protégé projects. In other words, if the query were interpreted as a regular expression, the Browser will add “*” to the beginning and end of the query.
As was mentioned in the overview, the primary purpose of the Browser is to work with Protégé projects, although the Browser can be extended easily to support other types of items. If you wish to browse other types of items, such as instances in a Protégé project, you can write an extension.
To give you some idea of the potential capabilities, this download includes a sample extension that allows you to browse HTML files (Warning: this particular HTML extension is not complete or thoroughly tested. It is meant only to give an idea of what is possible). Below is a screenshot of a library of HTML files, where the thumbnail window displays the HTML documents. The window below the Library Overview shows the links in the webpage.
To select the type of items you want to add to the library, go the "File" menu and select "Configure Browser". The “Library Item Type” tab will allow you select the type you want.
Figure 6 - The Browser can be easily extended to browse anything. Here is an example of how you can browse HTML files.
You may notice that there is no annotation displayed about the HTML document above. The only functions that the class provides is the drawing of the HTML document, and keeping track of the links in the page. If you try to use the Dependencies Lattice, the Browser will draw a graph showing how each HTML document links to other documents. This shows that if you want to extend the Browser to support another type of item, but are only interested in certain features of the Browser, you can implement only the features you wish to take advantage of.
The Browser is designed to make it very easy for the user to extend. All you need to do is implement a single Java class in order to support a new type of item. The class is basically responsible for gathering the information for whatever it is that you are browsing, and the Browser will handle the rest.
To support a new type, create a subclass of LibraryItem, which is a template for the class you need to write. If you wish to support another type of item, implement the methods declared in LibraryItem in your new class. The source code for the HTML extension is included so that you can have an example of what and extension needs to implement.
Below is a copy of the class LibraryItem. Included in the code are comments that describe important implementation details:
/**
* Title:
LibraryItem.java<p>
* Description: This allows
you to browse a library of knowledge bases.<p>
* Copyright: Copyright
(c) Warren Shen<p>
* Company: Stanford
Medical Informatics<p>
* @author Warren Shen
* @version 1.0
*
* This is an abstract class whose subclasses handle different
types of
* library items. For
example, the subclass KBSummary handles working
* with Protege projects.
This class defines the set of methods that
* need to be implemented for the Browser to be able to manage the
* library item.
*/
package browser.model;
import java.util.*;
import javax.swing.*;
public abstract class
LibraryItem {
protected String _filePath = "", _name = "",
_identifier = "";
protected boolean _isActive = true, _isIncluded = false;
public static final String FIND_ANY = "Any";
/**
* Default constructor.
IMPORTANT: When writing a
* subclass of LibraryItem, do not write a constructor
* for it. The subclass
should not be instantiated
* directly, but will be instantiated via the
* createNewLibraryItems() and getUserLibraryItems()
* methods.
*/
public LibraryItem() {}
/**
* Will create new library items based on the
* identifiers given. An
identifier is a string
* which contains all the information needed to
* construct a new library item.
So, for example
* the identifier could be a filename if that is
* all that is needed to create a particular item.
* The subclass is
responsible for providing and
* interpreting its own identifiers.
*/
public abstract Collection createNewLibraryItems(Collection
identifiers, boolean isIncluded, boolean isActive);
/**
* Will prompt the user for input and return a
* Collection of the selected LibraryItems.
* This most likely will invoke a file chooser
* (supplied in BrowserManager.java) to let the user pick a file.
*/
public abstract Collection getUserLibraryItems();
/**
* Returns the name of this type. For example,
* if the LibraryItem were HTML documents,
* this could return "HTML".
*/
public abstract String getTypeName();
/**
* Returns an identifier that contains all the
* information that is needed to construct a
* new item. For example,
if you were representing
* a certain file, the identifier could simply
* be its file name. If
you were representing
* an instance in a protege project, the identifier
* would need to contain information about the file
* as well as the specific instance.
*/
public abstract String getIdentifier();
/**
* Returns a JComponent that displays a graphical
* view of the item. For
KBSummary which represents
* protege projects, it returns a JComponent containing
* a graph of the knowledge base. Another example could
* be displaying the HTML file if the items were web
* pages.
*/
public abstract JComponent getThumbnail();
/**
* Returns the names of various query types
* that this item supports.
For example, KBSummary
* returns {"Attributes", "Slots", and
"Classes"}.
* When the user performs a query, it can specifiy
* which type of query to perform. It is up to the
* subclass to perform the query based on the type
* selected.
*/
public abstract Collection getQueryTypeNames();
/**
* Returns the result from a query performed.
* The query is the actual text the user searched
* for, and the queryTypeName is one of the query
* types provided in getQueryTypeNames(). The
* parameter showIncluded indicates if the results
* should contain values that are not explicitly
* in an item but are present because the item
* includes another item.
For example, if a
* project does not contain a particular class
* but includes a project that does, the results
* will display that class only if showIncluded
* is true.
*/
public abstract Collection query(String query, String
queryTypeName, boolean showIncluded);
/**
* This returns a sorted collection of summary
* attribute names.
Summary attributes are a
* subset of the attributes, which will be used
* in the LibraryTable in the Library Overview tab.
*/
public ArrayList getSummaryAttributeNames() {
return new ArrayList();
}
/**
* Returns a sorted list of attributes. Attributes
* are aspects or meta-information about the item,
* such as filename, author, date, or subject.
*/
public ArrayList getAttributeNames() {
return new ArrayList();
}
/**
* Given one of the attribute names provided
* from getAttributeNames(), this returns the
* actual values associated with that name.
* So, if the attribute name was "file name",
* the result could be the name of the file.
*/
public Collection getAttributeValues(Object attributeName) {
return new ArrayList();
}
/**
* Returns a collection of Strings that are
* identifiers for other LibraryItems of the
* same type. For
example, for KBSummary, it would
* return the filenames of all the protege
* projects that were directly included in the protege
* project represented by the item.
*/
public Collection getDirectDependenciesIds() {
return new ArrayList();
}
/**
* Returns a collection of identifiers of all the
* included items. For
example, if A includes B,
* and B includes C, A would return B and C, as opposed
* to just B.
*/
public Collection getAllDependenciesIds() {
return new ArrayList();
}
/**
* Given and identifier, return the name of the item. For
* example, if the identifier was a file path of a file,
* this function could return the name of the file without
* the directory.
*/
public String getNameFromIdentifier(String id) {
return id;
}
/**
* An item that is active is processed in the Dependencies
* tab and the Query tab.
*/
public boolean isActive() {
return _isActive;
}
/**
* An item is included if it is in the library but
* the only it is there because another item includes it.
* For example, if an item was in the library but its
* dependencies were not, the dependencies would be hidden.
*/
public boolean isIncluded(){
return _isIncluded;
}
/**
* Setter for _isActive.
*/
public void setActive(boolean isActive) {
_isActive = isActive;
}
/**
* Setter for _isIncluded.
*/
public void setIncluded(boolean isIncluded) {
_isIncluded = isIncluded;
}
/**
* Returns the name of the item.
For example, if the
* item represented a protege project, the name would
* be the name of the .pprj file.
*/
public String getName() {
return _name;
}
/**
* Returns the file path of whatever it is this item
* represents.
*/
public String getFilePath() {
return _filePath;
}
}
Once you have implemented your subclass of LibraryItem, you now need to package it so that the Browser will use it.
1. First compile your class into a .class file using either your Java editing environment or the command line.
(Look at http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/javac.html for information on how to compile a class).
2. Now you need to make a manifest file. Create a text file in the same directory as your .class file with the following content. This will be the manifest file for the jar:
Manifest-Version: 1.0
LibraryItem: Name of your class here (e.g.,
LibraryItemSubclass)
Note that there needs to be an empty blank line at the end of the file. The text file may be named anything you want.
3. Now you need to create a jar file. From the command line, go to the directory of your class and manifest file, and type the command below. In the following command, assume your class name is YourItem.class and your manifest file is YourItem.txt. Also, you may need to change the file path of the jar program depending on where it is located.
C:\jdk1.3\bin\jar cfmv YourItem.jar YourItem.txt
YourItem.class
A file named YourItem.jar should appear in the directory of the .class and manifest file.
4. Now, all you need to do is copy the jar file into the plugins directory of the Browser as specified in the browser.properties file. The default directory is the plugins/ directory in the same folder where the Browser jar file (“browser.jar”) is located.