Difference between revisions of "BioPortal Import Plugin"

From Protege Wiki
Jump to: navigation, search
(→‎How does it look like)
 
(70 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Plugin
 
{{Plugin
−
|Description=The BioPortal Import Plugin allows the user to import classes from external ontologies stored in BioPortal. The user can import entire trees of classes with a desired depth and choose which properties to import for each class.
+
|Description=The BioPortal Import Plugin allows users to import classes from external ontologies stored in the BioPortal ontology repository. The user can import entire trees of classes with a desired depth and choose which properties to import for each class. This plugin works with Protege 3.x releases, not Protege 4.x.
−
|PluginType=Slot Widget
+
|PluginType=Project
 
|ForApplication1=Protege-OWL
 
|ForApplication1=Protege-OWL
 +
|Screenshot=BPImportPlugin.png
 
|HomepageURL=http://protegewiki.stanford.edu/index.php/BioPortal_Import_Plugin
 
|HomepageURL=http://protegewiki.stanford.edu/index.php/BioPortal_Import_Plugin
 
|DeveloperID1=Jithun Nair
 
|DeveloperID1=Jithun Nair
 
|DeveloperID2=Tania Tudorache
 
|DeveloperID2=Tania Tudorache
−
|LastUpdated=April 12, 2011
+
|LastUpdated=July 15, 2011
−
|Topic1=Biomedical Informatics
+
|Topic1=Import
−
|Topic2=Search
+
|Topic2=Terminologies
−
|Topic3=Navigation
+
|Topic3=Biomedical Informatics
−
|Topic4=Terminologies
+
|License=Mozilla Public License (MPL)
−
|Topic5=Import
 
−
|License=MPL
 
 
|Affiliation1=Stanford Center for Biomedical Informatics Research
 
|Affiliation1=Stanford Center for Biomedical Informatics Research
 
}}
 
}}
 
<div style="display:block; float:left; width:100%;">
 
<div style="display:block; float:left; width:100%;">
  
−
`
+
 
 
= Overview =
 
= Overview =
  
−
The BioPortal Reference plugin is added as an action to the OWLClasses tab of the Protege-OWL user interface. The plugin allows a user to import classes from external BioPortal ontologies into a local ontology in Protege-OWL. The basic steps in using the plugin are to: a) browse through all the BioPortal ontologies (except remote ones) and select which one to import classes from; b) select one or more classes to import from the BioPortal ontology, and c) import them as subclasses of the selected class in the local ontology.
+
<div style="background: #FDECE7; border: 2px solid #AE5B08; padding: 10px 15px 10px 20px; margin: 30px 430px 0 0; ">
 +
 
 +
'''As of May 2014, the BioPortal Import plugin does not work anymore.'''
 +
 
 +
BioPortal has updated its [http://data.bioontology.org/documentation REST APIs] and the plugin has not been ported to the new API, yet. We plan to add this functionality to [[WebProtege]]. Follow [https://github.com/protegeproject/webprotege/issues/152 this GitHub issue] for updates.
 +
 
 +
As a work around for now, you may open the BioPortal ontology directly in Protege 5.x, and edit it (for example, extract branch by deleting the rest of the ontology, or by using the Refactor menu -> Copy/move/delete axioms). To open the BioPortal ontology in Protege 5.x, do these simple steps:
  
−
The plugin uses the RESTful services provided by BioPortal to allow the user to browse through the latest versions of all BioPortal ontologies. However, remote ontologies (identified by the value of their isRemote property) cannot be explored in the plugin, since BioPortal does not provide the information for these ontologies through its REST services. The user can view the classes of the selected ontology in an expandable tree format, and also view the properties of each class.
+
# Copy the download link of the ontology from the ontology summary view in BioPortal (e.g., right-click on the link -> Copy link address)
 +
# Start Protege 5.x
 +
# Go to File menu -> Open from URL, and paste the link in the box
  
−
The plugin is configurable and works with Protege-OWL. The configurations provide users with the ability to: a) import entire subtrees of classes from BioPortal ontologies; b) save the imported classes as a separate ontology and/or as a file to the local disk, and c) choose which (if any) property values to import for each class and assign an equivalent user property for each imported property, if desired.
+
</div>
  
−
= What does it look like =
+
The plugin allows a user to '''import classes from external ontologies and terminologies stored in the [http://bioportal.bioontology.org BioPortal ontology repository]''' into the local ontology.
 +
 
 +
'''This plugin works with the Protege 3.x releases, not Protege 4.x releases'''. We plan to have an implementation of this plugin also in Protege 4 as part of the future work. If you are using Protege 4 to develop your ontology, you can still use this plugin by opening the OWL file in Protege 3.x, make the import, save, and then continue to develop the ontology in Protege 4.
 +
 
 +
The basic '''steps''' in using the plugin are to:
 +
 
 +
# browse through the BioPortal ontologies (except remote ones) and select which one to import classes from
 +
# select one or more classes to import from the BioPortal ontology,
 +
# configure the import,
 +
# import them as subclasses of the selected class in the local ontology.
 +
 
 +
 
 +
The plugin uses the '''[http://www.bioontology.org/wiki/index.php/NCBO_REST_services BioPortal REST services]''' to access and import the content of BioPortal ontologies. However, ontologies denoted as ''remote'' in BioPortal cannot be explored in the plugin, since BioPortal does not provide the information for these ontologies through its REST services.
 +
 
 +
The BioPortal Import plugin is added as a button to the OWL Classes tab of the Protege-OWL 3.x user interface. The user can browse the class tree of the selected BioPortal ontology right from the Protege desktop interface, and also view the properties of each class.
 +
 
 +
 
 +
The plugin is configurable and works with Protege-OWL. The '''import configuration''' allows the user to customize the import and it includes:
 +
 
 +
* import entire subtrees of classes from BioPortal ontologies
 +
* save the imported classes as a separate ontology and/or as a file to the local disk
 +
* choose which (if any) property values to import for each class and assign an equivalent user property for each imported property, if desired
 +
* import metadata at the level of a class or the ontology (e.g. import author, timestamp, source ontology and version, etc.)
  
−
Like this:
 
  
 +
A related plugin to this one that allows users to create reference to classes in BioPortal (rather than importing them) is the '''[[BioPortal_Reference_Plugin|BioPortal Reference Plugin]]'''.
  
−
[[File:Import_classes_from_BioPortal.png]]
 
  
−
= Under the hood =
+
= What does it look like =
  
−
To store the internal representation of an external reference, the plugin creates by default an instance of a <code>ExternalReference</code> class. The plugin can be configured to create classes instead of instances for the external references. In OWL, the details of the external references are stored as values of predefined annotation properties (e.g., <code>conceptId</code>, <code>ontologyName</code>, <code>url</code> etc.).
+
This is a screenshot showing the NCI Thesaurus loaded in Protege, and the SNOMED CT terminology browsed in the BioPortal Import Panel.
  
−
An example of an external reference instance to class <code>Country</code> from the <code>Galen</code> ontology in BioPortal is shown below:
 
  
 +
[[File:BPImportPlugin.png]]
  
−
[[File:ExternalReferenceInstance.png]]
 
  
 +
= How to use it =
  
−
To search BioPortal, get the details of a reference, see a graph visualization, etc, the plugin invokes the [http://www.bioontology.org/wiki/index.php/NCBO_REST_services BioPortal Restful Services].
+
The BioPortal Import plugin can be invoked by selecting a class of a domain ontology in the ''OWL Classes Tab'' (that will serve as the superclass of the imported classes), and then clicking on the BioPortal Import icon as shown below:
  
 +
[[File:BioPortal_Import_Plugin_icon.png]]
  
−
= How does it work =
 
  
−
The usage of the plugin should be quite straightforward.
+
== Importing classes ==
  
−
'''To create a new external reference''' just click on the link ''Create a new reference from BioPortal''. After that you will see a popup window like this:
+
In the BioPortal import panel, '''select a BioPortal ontology''' from the drop-down list. You may also start typing words from ontology name, and an auto-complete feature will display suggestions.
  
  
−
[[File:BioPortalSearch.png]]
+
[[File:Select_Ontology.png]]
  
  
−
By default, the plugin will start a search in BioPortal using the selected class (or property, individual) name; in the case above, ''Heart''. The panel shows the list of search results for the term from BioPortal: You will see the term name and the ontology in which it was found.
+
The plugin will show the '''class tree of the selected BioPortal ontology''' in an expandable tree format in the left pane. Selecting one of the classes will show the '''properties for that class''' in the details pane on the right hand side. You may '''select one or more classes to import from the BioPortal ontology'''.
  
−
If you are not satisfied with the searched term or results, you may type in your own search term.
 
  
−
'''To import an external reference''' simply click on the ''Import'' link. A new external reference instance (or class, depending on your configuration) has been created for you.
+
[[File:Select_Class.png]]
  
−
Before importing, you also have the option of '''looking at the content of the term in BioPortal''', by clicking on the little File icon on a row. You will see the details of the term from BioPortal (this will not be imported):
 
  
 +
Next, '''configure the import settings''' by clicking on the ''1. Configure Import...'' button. More details about configuring the settings are provided in the section below.
  
−
[[File:BioPortalDetails.png]]
+
Once you have configured the import, '''click on the ''2. Import'' button to import''' all selected classes into the local ontology in Protege.  
  
 +
Below is an example of the class ''Brain part'' (Term ID 119235005) of the SNOMED CT ontology imported as a subclass of ''Body part'' class in the NCI Thesaurus ontology.
  
−
Alternatively, you may click on the little tree icon from a row to '''see a graph representation of the neighbourhood of the referenced term''' from BioPortal. A new window will open in your default web browser (e.g. Firefox, Safari, IE, etc.) showing the neighbourhood graph. You will need to have Flash installed to see the graph.
 
  
 +
[[File:Imported_Classes.png]]
  
−
[[File:BioPortalGraph.png]]
 
  
 +
== Import configuration ==
  
−
= How to use it =
+
There are two ways to configure the import process:
  
−
The BioPortalReference plugin is just a slot widget, which means that it can be attached to properties at classes (also metaclasses) to be used instances (or classes).
+
# Using the menu ''BioPortal -> Configure...'', or
 +
# Clicking on ''1. Configure Import...'' at the bottom of the BioPortal import panel.  
  
−
== Create a reference property ==
 
  
−
To use it with OWL projects, first decide on a property that will store as values the instances of external references. You can either choose from existing properties (''foaf:topicOf'', or others), or you can create your own annotation property, for example, ''externalReference''. You may also use object properties, or just plain RDF properties. If you don't already have this property defined in your ontology, please create it.
+
=== Importing a subtree of classes ===
  
−
== Configure the form ==
+
If the user wants to import an entire subtree of classes, the plugin provides an option to enable it, as well as to configure the number of levels down the tree to import, starting from the children of the selected class. This makes it very convenient to import entire parts of an ontology at once.
  
−
Second step is to configure the form of the class where you want to use the plugin. For example, if you would like to add external references to all classes (e.g., ''Pizza'' class, ''Heart'' class, etc.), then you will have to configure the form of the <code>owl:Class</code>. To configure the form, click on a class in your ontology and click on the little <code>F</code> icon at the top-right hand side of the ClassesTab. You will get a dialog whether to make owl:Class visible, click OK.
 
  
−
Then go to the ''Forms Tab'' (you may already be there after closing the dialog), make sure that owl:Class is selected, and double click on an empty spot. You will get a dialog with all properties and their attached widget. For the reference property from step 1 (e.g., ''externalReference'') associate the ''BioPortalReferenceWidget''.  
+
[[File:Importing_Subtree.png]]
  
−
'''Note''': The new widget will be created under the top widget (it's a bug), so just drag the top widget to right a little bit, and drag from underneath the BioPortalReference widget to a place of your choice in the UI.
 
  
 +
=== Importing into a separate ontology ===
  
−
== Configure the widget ==
+
Often, a user might want to import classes into a separate ontology, which can then be imported into the main ontology. One advantage of this is that the imported classes can be edited and maintained separately. It also makes removing all the imports altogether much easier. If so desired, the user can configure whether he/she wants to import the selected classes into an entirely new ontology (in which case the ontology name and the name of the file to save it to needs to be
 +
provided), or as part of an already imported ontology (for which he needs to select from a list of already imported ontologies which are writable).
  
−
Normally, you would not change the default configuration of the widget, but in case you need to customize it for your own project please read this section. Otherwise, you may just skip it.
 
  
−
You may configure the widget in the Forms Tab by double clicking on the BioPortalReference widget. In the '''Columns'' Tab, you may configure what columns and the width of each column that should show up:
+
[[File:Importing_Into_Separate_Ontology.png]]
  
 +
[[File:Importing_Into_Existing_Ontology.png]]
  
−
[[File:BioPortalColumns.png]]
 
  
 +
=== Configuring properties to be imported ===
  
−
For example, you may remove the ''url'' slot and this will be removed from the display of the BioPortalReferenceWidget, or you may add other column, or switch the order.
+
Apart from the classes, the user might also wish to import various properties of each class, along with their values. However, since the same property might not exist in the local ontology, the user can choose which property of the local ontology to assign it to. Currently, the plugin allows a user to import only the ''Label'', ''Definitions'' and ''Synonyms'' properties from BioPortal. However, this list might be extended in the future. The figure below depicts how to configure which properties to import for each class, and their equivalent properties in the local ontology.
  
−
In the '''Search Tab''', you may configure the search parameters for BioPortal:
+
The properties used for label, definition and synonyms are configured in BioPortal for each individual ontology, and they are read by the plugin using a REST service. If the corresponding properties are already part of the local ontology, then they will be by default selected in the configuration panel (the first option in the radio button).
  
 +
[[File:Configuring_Properties.png]]
  
−
[[File:BioPortalSearchConfig.png]]
 
  
 +
=== Configuring the metadata to import ===
  
−
== The result ==
+
The user may also specify which metadata to import at class or ontology level in the ''Configuration Panel -> Metadata Tab''. Examples of the metadata to import are: the source ontology name and version, the import author and timestamp, and the BioPortal ontology version Id. By default, no metadata is imported. Below is a screenshot of metadata configuration:
  
−
Below is a screenshot that shows the OWLClasses tab, for which we have configured using the steps above, the BioPortalReference widget:
+
[[File:BP_Imp_metadata_config.png]]
  
  
−
[[File:Pizza_with_BPRef.png]]
+
== Import example ==
  
 +
The screenshot below shows an example of an import into the ''Body Part'' subtree of the NCI Thesaurus (local ontology) of the ''Brain part'' subtree (first level of children) from the SNOMED-CT.
  
−
= Download =
+
We have used the following import configuration:
 +
* Import superclass in the local ontology: ''Body Part'' (NCI Thesaurus)
 +
* Import superclass from the source ontology: ''Brain part'' (SNOMED-CT)
 +
* Import also subclasses, set level to import to 1
 +
* Import properties: ''Label'' -> ''Preferred_Name'', ''Definitions'' -> ''DEFINITION'', ''Synonyms'' -> ''Synonym''. (the mapped properties are from the NCI Thesaurus)
 +
* Import class metadata: enabled all checkboxes for the class metadata.
  
−
The plugin is distributed with the Protege 3.4.2 release and newer. However, we might need to make changes to the plugin to keep in sync with the BioPortal releases. For this reason, we also provide separate downloads for the plugin.
+
Please note that we have also enabled the rendering by the ''Preferred_Name'' property from NCI Thesaurus from the OWL menu -> ''Preferences'' -> ''Rendering''. (See below more explanation on how to set the rendering property.)
  
−
We have a patch version of the plugin for Protege 3.4.3, that can be downloaded from [http://smi-protege.stanford.edu/collab-protege/tmp/bioportalReference.zip here]. Unzip it into your Protege 3.4.x plugin folder. (Make sure you override the old versions of the plugin.)
 
  
−
The source code of the plugin is available in our SVN: http://smi-protege.stanford.edu/svn/bioportal-reference-plugin/trunk/ and it is licensed under Mozilla Public License.
+
[[File:Import_Result1.png]]
  
  
−
= Developer's Guide =
+
'''Note:''' Notice that the highlighted class in the above example, ''Brain part'' (Full id: http://purl.bioontology.org/ontology/SNOMEDCT/119235005) that was imported from the SNOMED-CT ontology into the NCI Thesaurus, is displayed using the value of the ''Preferred_Name'' property. This is much more intuitive than displaying the default full URI of the class. To enable the rendering by a different property (default is the id of the class), go to the ''OWL menu -> Preferences -> Rendering'', and set the value of the ''Render entities in this ontology using property:'' drop-down to whichever property that you want to use to display the class (in this example, we show how to set ''rdfs:label'' as the rendering property).
  
−
This plugin is very easy to extend.
 
  
−
== Configure the classpath and Eclipse setup ==
+
[[File:Setting_Render_Property.png]]
  
−
First, you should get the sources of the plugin from the SVN repository, as explained in the above section. The plugin depends on:
 
−
* standard-extensions (get the one in the zip from [http://smi-protege.stanford.edu/collab-protege/tmp/bioportalReference.zip here])
 
−
* protege-owl
 
−
* xstream libs (get the binary version from [http://xstream.codehaus.org/download.html here], Libs needed in the classpath: xpp3_min_xyz.jar and xstream-xyz.jar)
 
  
−
If you would like to use Eclipse development environment, we have a guide of how to set it up for plugin development [[SetUpEclipseForPlugin|here]].
+
= Under the hood =
  
−
== Explanation of classes ==
+
The plugin creates instances of the <code>OWLNamedClass</code> class to store all the imported classes from BioPortal. If the user chooses to import any property of the imported classes, it is assigned to one of the <code>OWLAnnotationProperties</code> of the current <code>OWLModel</code>, as configured by the user.
  
−
The plugin is very simple. It has classes for UI and classes for accessing BioPortal through rest services.
+
The import metadata properties are defined in the ''provenance.owl'' ontology that is available from [http://protege.stanford.edu/ontologies/metadata/provenance.owl here]. The metadata properties defined in this ontology might change in future versions of the plugin based on the community feedback.
  
−
The slot plugin class (main UI) is: <code>edu.stanford.bmir.protegex.bp.ref.BioPortalReferenceWidget</code>
+
To display the list of ontologies in BioPortal, get the details of the classes and their properties etc., the plugin invokes the [http://www.bioontology.org/wiki/index.php/NCBO_REST_services BioPortal Restful Services].
  
−
The panel in which you can search and import from BioPortal is: <code>edu.stanford.bmir.protegex.bp.ref.SearchPanel</code>
 
  
−
The reference model class that creates the reference instances and makes the actual import is: <code>edu.stanford.bmir.protegex.bp.ref.ReferenceModel</code>
+
= Limitations and known issues =
  
−
If you would like to change the way that references are imported, change the method (or create your own):
+
The first version of this plugin is distributed with the Protege 3.4.7 release. As with any other plugin, this is work in progress, and we encourage the community to provide us feedback, and even get involved in the development of this plugin.
  
−
public Instance createReference(String bpBaseUrl, String conceptId, String ontologyVersionId, String preferredName, String ontologyName)
+
Some of the limitations and known issues are:
 +
* It is only possible to import the label, definition and synonym properties for a class. Future versions will allow the selection of arbitrary properties to import.
 +
* While an import is going on, the user interface is blocked, and it is not possible to cancel a long running import. (future enhancement)
 +
* It is not possible to persist an import configuration into a file to reuse for other ontologies. (future enhancements)
 +
* The plugin only works with Protege-OWL, and not with Protege Frames ontologies. If there is enough interest in the community, we will also support Frames.
  
−
The package <code>org.ncbo.stanford</code> contains the classes that can can invoke a rest service to BioPortal and that can read in the results. All you need to invoke the services is in the <code>org.ncbo.stanford.util</code> package.
 
  
 +
= Download =
  
−
== Invoke BioPortal Rest services ==
+
The plugin is distributed with the Protege 3.4.7 release and newer Protege 3.x releases. This plugin does not work with Protege 4.x releases. We plan to support this in the future.
  
−
The BioPortal Rest services are documented [http://www.bioontology.org/wiki/index.php/NCBO_REST_services here].
+
Even if the plugin is distributed with Protege 3.x release, we might need to make changes to the plugin to keep in sync with the BioPortal releases and to add enhancements and bug fixes. For this reason, we also provide separate download for the plugin.
  
−
For example, to invoke a search in BioPortal, you can use the utility class:
+
We have a patch version of the plugin that can be downloaded from [http://smi-protege.stanford.edu/collab-protege/bioportalReference.zip here]. Unzip it into your Protege 3.x plugin folder. (Make sure you override the old versions of the plugin.)
  
−
BioportalSearch sd = new BioportalSearch();
+
The plugin is open source and the source code is available in our SVN and it is licensed under Mozilla Public License (MPL).
−
String urlStr = "http://rest.bioontology.org/bioportal/search/Myocardial%20Infarct?pagesize=20&pagenum=1";
 
−
try {
 
−
    Page p = sd.getSearchResults(new URL(urlStr));
 
−
    SearchResultListBean data = p.getContents();
 
−
    for (SearchBean searchBean : data.getSearchResultList()) {
 
−
        System.out.println(searchBean.getPreferredName() + "\t" + searchBean.getOntologyDisplayLabel());
 
−
    }
 
−
  } catch (MalformedURLException e) {
 
−
    e.printStackTrace();
 
−
  } catch (IOException e) {
 
−
    e.printStackTrace();
 
−
  }
 
  
−
For an example implementation see: <code>edu.stanford.bmir.protegex.bp.ref.SearchPanel.getSearchResultsHtml()</code>
+
To browse the source code from our SVN, please visit: http://smi-protege.stanford.edu/svn/bioportal-reference-plugin/trunk/
  
 +
To check out the sources for the BioPortal Import Plugin, use the following command in a terminal:
  
−
To get all details of a concept, you can use the following code:
+
<pre>
 +
svn co https://smi-protege.stanford.edu/repos/protege/bioportal-reference-plugin/trunk bioportal-plugin
 +
</pre>
  
−
BioportalConcept c = new BioportalConcept();
+
The BioPortal import plugin also depends on a generic Java library for accessing BioPortal Web services (the lib is included as a jar file in the lib folder of the previous check out). The sources for this lib are available in:
−
String urlStr = "http://rest.bioontology.org/bioportal/concepts/39002/BRO:Resource";
 
−
try {
 
−
    ClassBean cb = c.getConceptProperties(new URL(urlStr));
 
−
    System.out.println(cb.getFullId() + " " + cb.getId() + " " + cb.getLabel());
 
−
    Map<Object, Object> relationsMap = cb.getRelations();
 
−
    for (Map.Entry<Object, Object> e : relationsMap.entrySet()) {
 
−
        System.out.println(e.getKey() + ": " + e.getValue());
 
−
    }
 
−
  } catch (MalformedURLException e) {
 
−
        e.printStackTrace();
 
−
  }
 
  
 +
<pre>
 +
svn co https://smi-protege.stanford.edu/repos/protege/bioportal-services-lib/trunk bioportal-plugin
 +
</pre>
  
 
= Where to get help and complain =
 
= Where to get help and complain =

Latest revision as of 13:34, June 13, 2014

BioPortal Import Plugin

by Jithun Nair, Tania Tudorache

Screenshot

Type Project
Author(s) Jithun Nair, Tania Tudorache
Last Update July 15, 2011
License Mozilla Public License (MPL)
Homepage BioPortal Import Plugin website
For Application
Topic(s)
Affiliation

The BioPortal Import Plugin allows users to import classes from external ontologies stored in the BioPortal ontology repository. The user can import entire trees of classes with a desired depth and choose which properties to import for each class. This plugin works with Protege 3.x releases, not Protege 4.x.

Versions & Compatibility

This section lists available versions of BioPortal Import Plugin.

No version information available.

If you click on the button below to add a new version of BioPortal Import Plugin, you will be asked to define a page title for the new version. Please adhere to the naming convention of BioPortal Import Plugin X.X.X when you define the new page!

Changelog

No version information available.



Overview

As of May 2014, the BioPortal Import plugin does not work anymore.

BioPortal has updated its REST APIs and the plugin has not been ported to the new API, yet. We plan to add this functionality to WebProtege. Follow this GitHub issue for updates.

As a work around for now, you may open the BioPortal ontology directly in Protege 5.x, and edit it (for example, extract branch by deleting the rest of the ontology, or by using the Refactor menu -> Copy/move/delete axioms). To open the BioPortal ontology in Protege 5.x, do these simple steps:

  1. Copy the download link of the ontology from the ontology summary view in BioPortal (e.g., right-click on the link -> Copy link address)
  2. Start Protege 5.x
  3. Go to File menu -> Open from URL, and paste the link in the box

The plugin allows a user to import classes from external ontologies and terminologies stored in the BioPortal ontology repository into the local ontology.

This plugin works with the Protege 3.x releases, not Protege 4.x releases. We plan to have an implementation of this plugin also in Protege 4 as part of the future work. If you are using Protege 4 to develop your ontology, you can still use this plugin by opening the OWL file in Protege 3.x, make the import, save, and then continue to develop the ontology in Protege 4.

The basic steps in using the plugin are to:

  1. browse through the BioPortal ontologies (except remote ones) and select which one to import classes from
  2. select one or more classes to import from the BioPortal ontology,
  3. configure the import,
  4. import them as subclasses of the selected class in the local ontology.


The plugin uses the BioPortal REST services to access and import the content of BioPortal ontologies. However, ontologies denoted as remote in BioPortal cannot be explored in the plugin, since BioPortal does not provide the information for these ontologies through its REST services.

The BioPortal Import plugin is added as a button to the OWL Classes tab of the Protege-OWL 3.x user interface. The user can browse the class tree of the selected BioPortal ontology right from the Protege desktop interface, and also view the properties of each class.


The plugin is configurable and works with Protege-OWL. The import configuration allows the user to customize the import and it includes:

  • import entire subtrees of classes from BioPortal ontologies
  • save the imported classes as a separate ontology and/or as a file to the local disk
  • choose which (if any) property values to import for each class and assign an equivalent user property for each imported property, if desired
  • import metadata at the level of a class or the ontology (e.g. import author, timestamp, source ontology and version, etc.)


A related plugin to this one that allows users to create reference to classes in BioPortal (rather than importing them) is the BioPortal Reference Plugin.


What does it look like

This is a screenshot showing the NCI Thesaurus loaded in Protege, and the SNOMED CT terminology browsed in the BioPortal Import Panel.


BPImportPlugin.png


How to use it

The BioPortal Import plugin can be invoked by selecting a class of a domain ontology in the OWL Classes Tab (that will serve as the superclass of the imported classes), and then clicking on the BioPortal Import icon as shown below:

BioPortal Import Plugin icon.png


Importing classes

In the BioPortal import panel, select a BioPortal ontology from the drop-down list. You may also start typing words from ontology name, and an auto-complete feature will display suggestions.


Select Ontology.png


The plugin will show the class tree of the selected BioPortal ontology in an expandable tree format in the left pane. Selecting one of the classes will show the properties for that class in the details pane on the right hand side. You may select one or more classes to import from the BioPortal ontology.


Select Class.png


Next, configure the import settings by clicking on the 1. Configure Import... button. More details about configuring the settings are provided in the section below.

Once you have configured the import, click on the 2. Import button to import all selected classes into the local ontology in Protege.

Below is an example of the class Brain part (Term ID 119235005) of the SNOMED CT ontology imported as a subclass of Body part class in the NCI Thesaurus ontology.


Imported Classes.png


Import configuration

There are two ways to configure the import process:

  1. Using the menu BioPortal -> Configure..., or
  2. Clicking on 1. Configure Import... at the bottom of the BioPortal import panel.


Importing a subtree of classes

If the user wants to import an entire subtree of classes, the plugin provides an option to enable it, as well as to configure the number of levels down the tree to import, starting from the children of the selected class. This makes it very convenient to import entire parts of an ontology at once.


Importing Subtree.png


Importing into a separate ontology

Often, a user might want to import classes into a separate ontology, which can then be imported into the main ontology. One advantage of this is that the imported classes can be edited and maintained separately. It also makes removing all the imports altogether much easier. If so desired, the user can configure whether he/she wants to import the selected classes into an entirely new ontology (in which case the ontology name and the name of the file to save it to needs to be provided), or as part of an already imported ontology (for which he needs to select from a list of already imported ontologies which are writable).


Importing Into Separate Ontology.png

Importing Into Existing Ontology.png


Configuring properties to be imported

Apart from the classes, the user might also wish to import various properties of each class, along with their values. However, since the same property might not exist in the local ontology, the user can choose which property of the local ontology to assign it to. Currently, the plugin allows a user to import only the Label, Definitions and Synonyms properties from BioPortal. However, this list might be extended in the future. The figure below depicts how to configure which properties to import for each class, and their equivalent properties in the local ontology.

The properties used for label, definition and synonyms are configured in BioPortal for each individual ontology, and they are read by the plugin using a REST service. If the corresponding properties are already part of the local ontology, then they will be by default selected in the configuration panel (the first option in the radio button).

Configuring Properties.png


Configuring the metadata to import

The user may also specify which metadata to import at class or ontology level in the Configuration Panel -> Metadata Tab. Examples of the metadata to import are: the source ontology name and version, the import author and timestamp, and the BioPortal ontology version Id. By default, no metadata is imported. Below is a screenshot of metadata configuration:

BP Imp metadata config.png


Import example

The screenshot below shows an example of an import into the Body Part subtree of the NCI Thesaurus (local ontology) of the Brain part subtree (first level of children) from the SNOMED-CT.

We have used the following import configuration:

  • Import superclass in the local ontology: Body Part (NCI Thesaurus)
  • Import superclass from the source ontology: Brain part (SNOMED-CT)
  • Import also subclasses, set level to import to 1
  • Import properties: Label -> Preferred_Name, Definitions -> DEFINITION, Synonyms -> Synonym. (the mapped properties are from the NCI Thesaurus)
  • Import class metadata: enabled all checkboxes for the class metadata.

Please note that we have also enabled the rendering by the Preferred_Name property from NCI Thesaurus from the OWL menu -> Preferences -> Rendering. (See below more explanation on how to set the rendering property.)


Import Result1.png


Note: Notice that the highlighted class in the above example, Brain part (Full id: http://purl.bioontology.org/ontology/SNOMEDCT/119235005) that was imported from the SNOMED-CT ontology into the NCI Thesaurus, is displayed using the value of the Preferred_Name property. This is much more intuitive than displaying the default full URI of the class. To enable the rendering by a different property (default is the id of the class), go to the OWL menu -> Preferences -> Rendering, and set the value of the Render entities in this ontology using property: drop-down to whichever property that you want to use to display the class (in this example, we show how to set rdfs:label as the rendering property).


Setting Render Property.png


Under the hood

The plugin creates instances of the OWLNamedClass class to store all the imported classes from BioPortal. If the user chooses to import any property of the imported classes, it is assigned to one of the OWLAnnotationProperties of the current OWLModel, as configured by the user.

The import metadata properties are defined in the provenance.owl ontology that is available from here. The metadata properties defined in this ontology might change in future versions of the plugin based on the community feedback.

To display the list of ontologies in BioPortal, get the details of the classes and their properties etc., the plugin invokes the BioPortal Restful Services.


Limitations and known issues

The first version of this plugin is distributed with the Protege 3.4.7 release. As with any other plugin, this is work in progress, and we encourage the community to provide us feedback, and even get involved in the development of this plugin.

Some of the limitations and known issues are:

  • It is only possible to import the label, definition and synonym properties for a class. Future versions will allow the selection of arbitrary properties to import.
  • While an import is going on, the user interface is blocked, and it is not possible to cancel a long running import. (future enhancement)
  • It is not possible to persist an import configuration into a file to reuse for other ontologies. (future enhancements)
  • The plugin only works with Protege-OWL, and not with Protege Frames ontologies. If there is enough interest in the community, we will also support Frames.


Download

The plugin is distributed with the Protege 3.4.7 release and newer Protege 3.x releases. This plugin does not work with Protege 4.x releases. We plan to support this in the future.

Even if the plugin is distributed with Protege 3.x release, we might need to make changes to the plugin to keep in sync with the BioPortal releases and to add enhancements and bug fixes. For this reason, we also provide separate download for the plugin.

We have a patch version of the plugin that can be downloaded from here. Unzip it into your Protege 3.x plugin folder. (Make sure you override the old versions of the plugin.)

The plugin is open source and the source code is available in our SVN and it is licensed under Mozilla Public License (MPL).

To browse the source code from our SVN, please visit: http://smi-protege.stanford.edu/svn/bioportal-reference-plugin/trunk/

To check out the sources for the BioPortal Import Plugin, use the following command in a terminal: 

 svn co https://smi-protege.stanford.edu/repos/protege/bioportal-reference-plugin/trunk bioportal-plugin

The BioPortal import plugin also depends on a generic Java library for accessing BioPortal Web services (the lib is included as a jar file in the lib folder of the previous check out). The sources for this lib are available in: 

 svn co https://smi-protege.stanford.edu/repos/protege/bioportal-services-lib/trunk bioportal-plugin

Where to get help and complain

If you have any problems with the plugin, please post a message on the protege mailing list (protege-owl for OWL ontologies, and protege-discussion for Protege frames ontologies). Instructions for posting on the lists are here:

http://protege.stanford.edu/community/lists.html

Before posting, please check the email list archives, whether the question has already been answered:

http://protege.stanford.edu/community/archives.html

Thank you!
Retrieved from "https://protegewiki.stanford.edu/index.php?title=BioPortal_Import_Plugin&oldid=12811"