Requirements

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

---

We discuss two types of requirements for handling metadata in BioPortal:

1. the functional requirements are the set of calls from the user-interface (and web services) that metadata must support;
2. the architectural requirements address the structure and evolution of metadata.

Functional requirements include support for all the current functionality for the metadata use in BioPortal and the future use that we are envisioning in various scenarios and use cases. Specific details on functional requirements are outlined here.

The following are the architectural requirements:

• Represent metadata as ontology instances
• Download metadata (and its various subsets) in RDF
• Be able to update the metadata ontologies “on the fly”
  • Incremental updates, such as adding new properties, should be a simple “swap” of the metadata schema (the metadata ontology), without having to change any of the instances
• Be flexible about which properties show up on the ontology metadata page and on the columns in the table on the “Browse” page (The metadata ontology itself will define the set of these metadata features. Thus, other groups that wish to install BioPortal locally will need to customize only the metadata ontology in order to custom-tailor their installations.)

Types of metadata in BioPortal

We represent the following types of metadata in BioPortal:

1. Ontology metadata (e.g., the ontology domain and coverage, provenance information, version information, additional references);
2. Ontology metrics (mostly computable metrics such as the number of classes, etc.)
3. Mappings between concepts in different ontologies;
4. Ontology reviews along different review dimensions (e.g., domain coverage, usability, quality of content, etc.);
5. Marginal notes on concepts and mappings in the ontologies containing users’ comments, questions, and discussions;
6. Projects that use ontologies in BioPortal
7. BioPortal Users

These different types of metadata are inter-linked. For example, each user is characterized by the metadata that they contribute; reviews can be created in the context of a particular projects; marginal notes can be attached to mappings.

Glossary

Virtual ontologies: the list of ontologies in the repository, with one entry per each “logical” ontology. Basically, the list that appears on the “Browse” page in BioPortal (see Figure).

Core metadata properties: metadata properties that appear on the "Ontology metadata” page. Not all properties associated with the ontology will generally appear there, as there are many minor ones that we don’t always want to display. Perhaps there can be a “more details” page that shows those.

Summary metadata properties: metadata properties that appear in the columns of the table on the “Browse” page and in the columns for versions and views on the metadata page for each ontology

---

Error creating thumbnail: /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 61: ulimit: cpu time: cannot modify limit: Permission denied /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 84: ulimit: virtual memory: cannot modify limit: Permission denied /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 90: ulimit: file size: cannot modify limit: Permission denied /bin/bash: /usr/bin/convert: No such file or directory Error code: 127

The "Browse" page in Bioportal

Error creating thumbnail: /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 61: ulimit: cpu time: cannot modify limit: Permission denied /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 84: ulimit: virtual memory: cannot modify limit: Permission denied /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 90: ulimit: file size: cannot modify limit: Permission denied /bin/bash: /usr/bin/convert: No such file or directory Error code: 127

The "Ontology metadata" page in Bioportal

Error creating thumbnail: /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 61: ulimit: cpu time: cannot modify limit: Permission denied /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 84: ulimit: virtual memory: cannot modify limit: Permission denied /srv/www/vhosts/www.bioontology.org/app/mediawiki-1.35.9/includes/shell/limit.sh: line 90: ulimit: file size: cannot modify limit: Permission denied /bin/bash: /usr/bin/convert: No such file or directory Error code: 127

The "Project and reviews" page in Bioportal

---

Functional Requirements

Metadata drives much of the BioPortal user interface, with the exception of the display of the ontologies themselves. The list below is not exhaustive and we expect it to grow. However, it does cover major categories of requirements and some details on each. In the section on Implementation Details, we provide details on the implementation for all these calls.

Browse ontologies (as in the “Browse” tab of BioPorta)

• get all virtual ontologies
• for each virtual ontology, get the summary properties to fill in the rest of the table:
  • name
  • version
  • author
  • uploaded on
  • url

Ontology metadata (in ontology metadata page)

• display property-value pairs for the core metadata properties
• get a list of all views for the ontology
  • for each view, get the summary properties, such as description, version number, status, url
• get a list of all versions for the ontology
  • for each version, get the summary properties, such as description, version number, status, url

Submitting a new version of an ontology

• get a list of core properties and their ranges (the range determines the UI widget)
  • in order
• create a new metadata instance describing this ontology version
  • and set property values

Submitting a new ontology

• get a list of core properties and their ranges (the range determines the widget)
  • in order
• create a new metadata instance describing this ontology version
  • and set property values

Accessing the metrics of an ontology version

• get all available metrics for a specific ontology version
• the metrics should be computed when the ontology is loaded into BioPortal
  • Specific metrics are described on the Ontology Metrics page

Search

• get a list of virtual ontologies to provide filters for search

Recent items

• provide the list of recent ontology uploads
• provide the list of recent marginal notes, mappings, reviews, projects

Reviews

• get all reviews for an ontology, indicating which reviews where created for a current version, and which were created for old versions
• when presenting a review, show ratings and text along different dimensions (Figure 1)
• create a review for an ontology
  • in the context of a particular project
  • without a project context
• determine which ontology has the highest ratings for a particular dimension

Notes

• for each concept, given its URL (real or virtual?), get all marginal notes associated with this concept:
  • marginal notes attached directly to the current version of this concept
  • marginal notes attached to earlier versions
• the number of marginal notes for an ontology
  • over a period of time?
• the marginal notes created by a particular user
• the marginal notes of a particular type (e.g., new term proposals)
• any combination of the above (e.g., new term proposals from a user X)
• Create a marginal note and associate it with a version of a concept

Proposals

Proposals are a special kind of notes. Through proposals, the members of the community communicate with ontology developers, making suggestions for changes. The community here can be the biomedical-ontology community at large, the users of the ontology, or a distributed community of ontology developers who use the notes capability to reach consensus.

The main type of the proposal in the Bioportal context is the proposal to add a new term. Annotators often need new terms and the notes can serve as an issue tracker, of sorts. The new term proposal is usually attached to the class in the hierarchy that would become its superclass (as in "Add a new term here". When creating a proposals users must be able to:

• get an id for the new term right away so that they can use this id in their annotations.
• specify some information for the new term, such as:
  • preferred name
  • synonyms
  • definition
  • superclass for the new term (by default, the class to which the proposal is attached)
  • contact information (for contact during the curation process)
  • comment

All mappings

Each of the service should return both the full id and the short id of the mapped concepts and we should probably provide the lookup capability by both types of ids (but definitely by the full id)

• for each virtual ontology, get the number of mappings to and from that ontology
• for each ontology, get all the mappings (grouped by target ontology)
• remove all mappings for an ontology (or all mappings between two ontologies) -- to enable update of mappings when ontology evolves
  • optional parameter: restricted to mappings created by a specific user and/or algorithm
• process bulk mappings:
  • Given a tab-delimited file with mappings (source ontology id, source concept id, target ontology id, target concept id, mapping type) + provenance data, create the mappings
• search mappings:
  • find mappings by specific author and/or algorithm
  • grouped by ontology
  • essentially a query to restrict mappings by any piece of metadata about them
• possibly additional aggregated data that is required to present the tag cloud on the ontology metadata page

Mappings for a concept

• for each concept, given its URL (real or virtual?), get all mappings associated with this concept:
  • mappings attached directly to the current version of this concept
  • mappings attached to earlier versions
• create a new mapping and attach it to the current version of the concept

Views

• each view is itself an ontology and can have metadata, be explorable, etc.
• a view is defined on a specific version of an ontology
• there is a notion of a "virtual view" (cf. "virtual ontology"): for example, a view of Liver-related concepts in FMA created for a particular purpose
  • each virtual view will have at least one version, but can have several
  • a virtual view has some metadata attached to it (name, contact, etc.)
  • each version of the view also has its own metadata (inherited from ontology metadata, but with additional fields)
• we must be able to represent views on views
• we must be able to represent views that include more than one ontology

Projects

• get a list of projects
• for each project, get the property-value pairs:
  • name
  • description
  • people
  • institution
  • homepage
• project-specific page