Implementation Details

This document is part of a series of documents describing the representation of metadata in BioPortal

---

Note: These notes are for BioPortal developers only and are not critical in understanding the BioPortal approach to metadata representation.

This page provides sample code for using the Protege API to access and edit the metadata instances. You can also download the code.

Dealing with instance data

Currently, BioPortal represents the class information in a ClassBean.You will probably need an InstanceBean, similar to the ClassBean, to pass around information about the instances. In fact, you can simply have a ResourceBean that does just that (unless there is special handling of superclass relation in the ClassBean). Perhaps, we will also need an AnnotationBean to encapsulate information about a particular marginal note or review.

Initializing variables that refer directly to BioPortal Metadata Ontology

At the time the server starts up, we should initialize variables of types OWLModel, OWLClass and RDFProperty corresponding to the BioPortal Metadata ontology and classes and properties in the Metadata ontology. Implementations of most API calls will refer to these variables and having them cached will speed up the queries significantly. Any time a metadata ontology is updated (doesn’t happen often of course), these will need to be re-initialized. The classes and properties that we initialize are the only ones that developers must keep intact when they custom-tailor metadata in their own BioPortal installation.

Accessing BioPortal Metadata Ontology

The knowledge base variable bioPortalMetadataKnowledgeBase that points to the Metadata ontology (with its instances). We create all new metadata instances in this ontology.

OWLModel bioPortalMetadataKnowledgeBase = new JenaOWLModel …  // however you initialize an OWL Model in BP

Classes to access ontology metadata

OWLClass virtualOntologyClass = bioPortalMetadataKnowledgeBase.getOWLNamedClass (“VirtualOntology”); // the class "Virtual Ontology"
OWLClass omvOntologyClass = bioPortalMetadataKnowledgeBase.getOWLNamedClass (“OMV:Ontology”); // the class "OMV:Ontology"
RDFProperty currentVersionProperty = bioPortalMetadataKnowledgeBase.getRDFProperty("currentVersion"); // the property pointing to the latest version of the ontology (attached to the individuals of the VirtualOntology class)
RDFProperty virtualURIProperty = bioPortalMetadataKnowledgeBase.getRDFProperty("virtualURI"); // the property "virtualURI" at the "Virtual Ontology" class

We need to list the core properties somewhere and access them. This list can be represented somewhere in the ontology, but for now, we can have it initialized statically in the code:

    public static final String [] CORE_PROPERTY_NAMES = new String [] {
          "OMV:name",
          "OMV:acronym",
          "OMV:creationDate",
          "OMV:description",
          "OMV:documentation",
          "OMV:endorsedBy",
          "OMV:domain",
          "OMV:ontologyLanguage",
          "OMV:keyClasses",
          "OMV:keywords"
    };

     public static final String [] SUMMARY_PROPERTY_NAMES = new String [] {
          "OMV:name",
          "OMV:creationDate"
    };

We can then use these lists to initialize the ordered list of RDFProperty objects to go through:

     coreProperties = new ArrayList<RDFProperty> ();
     for (int i = CORE_PROPERTY_NAMES.length - 1; i >= 0; i--) {
            String nextName = CORE_PROPERTY_NAMES [i];
            RDFProperty nextProperty = bioPortalMetadataKnowledgeBase.getRDFProperty(nextName);
            coreProperties.add (nextProperty);
     }

The same for summaryProperties

The properties versionsProperty and viewsProperty provide access from the instance of a VirtualOntology class to the instances representing its versions and views, respectively:

versionsProperty = bioPortalMetadataKnowledgeBase.getRDFProperty("hasVerisons"); viewsProperty = bioPortalMetadataKnowledgeBase.getRDFProperty("hasViews");

Classes and properties for marginal notes and reviews

The properties that link the annotations and the objects that they annotate:

annotatesByVirtualIdProperty = bioPortalMetadataKnowledgeBase.getRDFProperty(Names.ANNOTATES_BY_VIRTUAL_ID_PROPERTY); // property that links an annotations to the virtual id of an ontology ora conccept that it annotates
annotatesProperty = bioPortalMetadataKnowledgeBase.getRDFProperty(Names.ANNOTATES_PROPERTY); // property that links an annotations to the object that it annotates
associatedAnnotationsProperty = bioPortalMetadataKnowledgeBase.getRDFProperty(Names.ASSOCIATED_ANNOTATIONS_PROPERTY); // property that links from an ontology or a concept object to the list of corresponding annotations

Classes for the review and the values for the review:

reviewClass = bioPortalMetadataKnowledgeBase.getOWLNamedClass(Names.REVIEW_CLASS); // instances of this class represent reviews on ontologies
evaluationDimensionClass = bioPortalMetadataKnowledgeBase.getOWLNamedClass(Names.EVALUATION_DIMENSION_CLASS); // instances of this auxiliary class represent 
numericRatingProperty = bioPortalMetadataKnowledgeBase.getRDFProperty(Names.NUMERIC_RATING_PROPERTY); // property in Evaluation Dimension class that contains the numeric rating
textualReviewProperty = bioPortalMetadataKnowledgeBase.getRDFProperty(Names.TEXTUAL_REVIEW_PROPERTY); // property in Evaluation Dimension class that contains the numeric rating

We need to list the dimensions to specify the order in which review dimensions appear. This list can be represented somewhere in the ontology, but for now, we can have it initialized statically in the code:

public static final String QUALITY_OF_CONTENT_REVIEW = "qualityOfContentReview";
public static final String USABILITY_REVIEW = "usabilityReview";
public static final String CORRECTNESS_REVIEW = "correctnessReview";
public static final String DOMAIN_COVERAGE_REVIEW = "domainCoverageReview";
public static final String DOCUMENTATION_AND_SUPPORT_REVIEW = "documentationAndSupportReview";
public static final String DEGREE_OF_FORMALITY_REVIEW = "degreeOfFormalityReview";
public static final String [] REVIEW_DIMENSIONS = new String [] {
      QUALITY_OF_CONTENT_REVIEW,
      USABILITY_REVIEW,
      CORRECTNESS_REVIEW,
      DOMAIN_COVERAGE_REVIEW,
      DOCUMENTATION_AND_SUPPORT_REVIEW,
      DEGREE_OF_FORMALITY_REVIEW
};

Specifications for the API calls

For each call below, we provide the user cases, input, output, and pseudo-code for the implementation.

Calls for ontology metadata

Get the list of all virtual ontologies

Use cases: We need to access the list of all virtual ontologies in any place where we show the list of available ontologies in BioPortal: the main table on the “Browse” page; Search screen; ontology selection when defining a project.

Input: none

Output: a collection of OWL individuals, with each individual describing one virtual ontology (e.g., “BRO”)

Implementation: simply get a list of instances of the VirtualOntology class:

 virtualOntologyClass.getInstances(true)

Get the current (latest) version for a particular ontology

Use cases: providing the information about the ontology, for example, on the metadata page or to fill out the corresponding row in the table for the “Browse” page. This call will give you the URL for that version and you can then call the next service to get the details about that version.

Input: virtualOntologyURI: the name of the virtual ontology (or the Java object);

Output: the URL (name) for the instance representing the current version (or the Java object)

Implementation: There are two methods, depending on whether we have a Java object for the virtual ontology instance or its virtual URI.

/**
  * @param:   virtualOntologyURI  a virtual URI for the ontology
  */
public static OWLIndividual getCurrentVersion (URI virtualOntologyURI) throws Exception  {
         OWLIndividual virtualOntologyInstance = Util.getVirtualOntologyFromURI (virtualOntologyURI); // returns a virtual ontology instance correpsonding to this virtual URI
         return (OWLIndividual) virtualOntologyInstance.getPropertyValue(currentVersionProperty);
}

/**
  * @param:   virtualOntologyIndividual  an OWL individual representig a virtual ontology
  */	
public static OWLIndividual getCurrentVersion (OWLIndividual virtualOntologyInstance)  {
          return (OWLIndividual) virtualOntologyInstance.getPropertyValue(currentVersionProperty);
}

Get the latest metadata for the current ontology

Use cases: Provide either the limited metadata for the table on the “Browse” page; or the complete metadata for the “Ontology metadata” page. Another version of this call returns only summary properties – the ones that appear in the Browse table (summaryProperties collection)

Input: virtualOntologyURI: URI for the latest version (or the Java object)

Output: a list of property-value pairs for the core metadata properties

Implementation:

/**
  * @param:   virtualOntologyURI  a virtual URI for the ontology
  */
public static Collection<PropertyValue> getCoreMetadataForCurrentVersion (URI virtualOntologyURI) {
         OWLIndividual virtualOntologyInstance = Util.getVirtualOntologyFromURI (virtualOntologyURI); // returns a virtual ontology instance correpsonding to this virtual URI
        OWLIndividual currenVerisonInstance = (OWLIndividual) virtualOntologyInstance.getPropertyValue(Constants.currentVersionProperty); 
         Collection<PropertyValue> result = new ArrayList<PropertyValue> ();
         for (Iterator i = Constants.coreProperties.iterator(); i.hasNext(); ) {
                       RDFProperty nextCoreProperty = (RDFProperty)i.next();
                       PropertyValue nextPair = new PropertyValue ();
                       nextPair.property = nextCoreProperty.toString();
                       nextPair.value = currenVerisonInstance.getPropertyValue(nextCoreProperty).toString();
                       result.add(nextPair);
         }
         return result;
}

Get the list of all versions and views for a particular virtual ontology

Use case: the tables on the Ontology-metadata page.

Input: the name of a virtual ontology

Output: the list of instances (or property-value pairs, describing each)

Implementation: see sample code

For each ontology instance and a specific property, get its values

Input: version-specific URI; property of interest (either as a URI, or a Java object)

Output: value for the property (represented as a string)

Use cases: web service inquiring about a specific property value (e.g., a date for a version)

Implementation: see sample code

Create a new metadata instance describing a newly submitted version

Use cases: The user submits a form for describing a new version of an ontology

Input: a version-specific URI; a set of property-value pairs

Output: none

Implementation: find the corresponding virtual ontology individual (create one, if it doesn't exist). Iterate through property-value pairs to set the values.

Other API calls for ontology access

• for each ontology instance, get all property-value pairs
• for each metadata property, get its documentation to show up as a tooltip
• …

Calls for ontology reviews

Get the list of reviews for an ontology

Use cases: On the Ontology Metadata page, we want to show reviews for that ontology

Input: ontology id (virtual)

Output: a collection of OWL individuals, with each individual describing one review

Implementation:

/**
  * @param:    virtualOntologyURI  a virtual URI for the ontology
  */
public static Collection<OWLIndividual> getReviewsForAnOntology (String virtualOntologyURI) {
       Collection<OWLIndividual> relevantAnnotations = Constants.bioPortalMetadataKnowledgeBase.getFramesWithValue(Constants.annotatesByVirtualIdProperty, null, false, virtualOntologyURI);
       return relevantAnnotations;
}

Get the list of only those reviews that apply to the current version of an ontology

Use cases: On the Ontology Metadata page, we want to distinguish visually the reviews that were created for the current version

Input: ontology id (virtual)

Output: a collection of OWL individuals, with each individual describing one review

Implementation:

/**
  * @param:    irtualOntologyIndividual  an OWL individual representing a virtual ontology
  */
public static Collection<OWLIndividual> getReviewsForCurrentVersion (OWLIndividual virtualOntologyInstance) {
       OWLIndividual currentVersionInstance = (OWLIndividual) virtualOntologyInstance.getPropertyValue(Constants.currentVersionProperty);
       Collection<OWLIndividual> relatedAnnotations = currentVersionInstance.getPropertyValues(Constants.associatedAnnotationsProperty);
       return relatedAnnotations;		
}

Create a review for the ontology

Use cases: User enters a review

Input: ontology id for the current version; (possibly) project; ratings and textual reviews for each of the dimensions (requires a list of the dimensions)

Output: the new Review object.

Implementation:

/**
    * @param:    currentOntologyIndividual  an OWL individual representing a virtual ontology
     * @param:	project is an optional reference to the project if the review is performed in the context of a project
     * @param:	reviewElements is a collection of the review rating and textual values
     */
public static OWLIndividual createReview (OWLIndividual currentOntologyIndividual, OWLIndividual project, Collection<EvaluationDimensionData> reviewElements) {
     OWLIndividual review = (OWLIndividual)Constants.reviewClass.createInstance(null);
     review.setPropertyValue(Constants.annotatesProperty, currentOntologyIndividual);
     String virtualID = (String) currentOntologyIndividual.getPropertyValue(Constants.virtualURIProperty);
     review.setPropertyValue(Constants.annotatesByVirtualIdProperty, virtualID);
     for (Iterator i = reviewElements.iterator(); i.hasNext(); ) {
           EvaluationDimensionData next = (EvaluationDimensionData)i.next();
           OWLIndividual nextElement = (OWLIndividual)Constants.evaluationDimensionClass.createInstance(null);
           if (next.rating != null)
                  nextElement.setPropertyValue(Constants.numericRatingProperty, next.rating.intValue());
           if (next.text != null)
                  nextElement.setPropertyValue(Constants.textualReviewProperty, next.text);
           review.setPropertyValue(next.dimension, nextElement);
      }
      return review;

}

Calls for marginal notes

Given a concept, get all top-level marginal notes associated with a concept

Use cases: Present marginal notes for a concept. Note that we need only the notes that are at the top level of the discussion threads.

Input: concept id

Output: A collection of OWL individuals with marginal notes.

Implementation: