Difference between revisions of "BioPortal Help"

From NCBO Wiki
Jump to navigation Jump to search
(→‎Submitting an ontology: add a minimum requirements section)
 
(69 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
== User Interface Guide ==
+
== User Interface ==
 
=== Home Page ===
 
=== Home Page ===
  
Line 8: Line 8:
 
* [[#Recommender Tab|receive recommendations]] on which ontologies are most relevant for a corpus
 
* [[#Recommender Tab|receive recommendations]] on which ontologies are most relevant for a corpus
 
* [[#Annotator Tab|annotate text]] with terms from ontologies
 
* [[#Annotator Tab|annotate text]] with terms from ontologies
−
* [[#Resource Index Tab|search biomedical resources]] for a term
 
 
* [[#Projects Tab|browse a selection of projects]] that use BioPortal resources
 
* [[#Projects Tab|browse a selection of projects]] that use BioPortal resources
  
−
All information available through the BioPortal Web site is also available through the NCBO Web service REST API. Please see [http://www.bioontology.org/wiki/index.php/NCBO_REST_services REST API documentation] for more information.
+
All information available through the BioPortal Web site is also available through the NCBO Web service REST API. Please see [http://data.bioontology.org/documentation REST API documentation] for more information.
  
 
=== Browse Tab ===
 
=== Browse Tab ===
  
−
Here you can browse our library of Biomedical ontologies and can also submit your own ontology. The system displays some summary information about each ontology. More detailed summary information is available on the ontology summary page for each ontology. You can reach this page by clicking on the ontology name link.
+
Browse our library of Biomedical ontologies and submit your own ontology. This page displays some summary information about each ontology. More detailed summary information is available on the ontology summary page for each ontology. You can reach this page by clicking on the ontology name link.
  
 
To '''find a particular ontology quickly''', begin typing the ontology name or abbreviation in the “Filter by Text” field.  You can also narrow the list of ontologies shown by selecting a specific “category” (a domain) or a “group” to which the ontology belongs. To '''submit an ontology''' press the “Submit New Ontology” button. You must be logged in to BioPortal to submit an ontology. You can subscribe to '''receive RSS updates''' when any ontology in the system changes by clicking the subscribe link. You can subscribe to updates for a particular ontology from the summary page for that ontology. To go to the summary page click on the ontology name link.
 
To '''find a particular ontology quickly''', begin typing the ontology name or abbreviation in the “Filter by Text” field.  You can also narrow the list of ontologies shown by selecting a specific “category” (a domain) or a “group” to which the ontology belongs. To '''submit an ontology''' press the “Submit New Ontology” button. You must be logged in to BioPortal to submit an ontology. You can subscribe to '''receive RSS updates''' when any ontology in the system changes by clicking the subscribe link. You can subscribe to updates for a particular ontology from the summary page for that ontology. To go to the summary page click on the ontology name link.
Line 24: Line 23:
 
For '''private ontologies''', the ontology submitter directly controls access to the ontology. Please contact the submitter to gain access to a private ontology. Contact information for the ontology is available on the ontology summary page. For '''licensed ontologies''', the submitter indirectly controls access to the ontology. When you attempt to access a licensed ontology, the system will prompt you to enter the license information required by the submitter. When you have entered the required information, the system will allow you to access the ontology. In addition, there are '''"summary only" ontologies'''. The terms for these ontologies are not available in BioPortal at all. Please contact the ontology submitter for more information about these ontologies.
 
For '''private ontologies''', the ontology submitter directly controls access to the ontology. Please contact the submitter to gain access to a private ontology. Contact information for the ontology is available on the ontology summary page. For '''licensed ontologies''', the submitter indirectly controls access to the ontology. When you attempt to access a licensed ontology, the system will prompt you to enter the license information required by the submitter. When you have entered the required information, the system will allow you to access the ontology. In addition, there are '''"summary only" ontologies'''. The terms for these ontologies are not available in BioPortal at all. Please contact the ontology submitter for more information about these ontologies.
  
−
To '''access ontologies programmatically''', see our [http://www.bioontology.org/wiki/index.php/NCBO_REST_services#Services_to_access_ontologies_and_ontology_versions Ontology REST API documentation].
+
==== Ontology Popularity ====
 +
 
 +
Ontologies on the Browse tab are ordered based on their popularity, which is measured using the number of Google Analytics page views from the previous month. The more page views an ontology receives, the higher it appears on the list.
 +
 
 +
==== Programmatic Access ====
 +
 
 +
To '''access ontologies programmatically''', see our [http://data.bioontology.org/documentation#nav_resource_endpoints Resources REST API documentation] (then look under Media Types).
  
 
=== Search Tab ===
 
=== Search Tab ===
  
−
The search capability allows you to enter some text and find terms across multiple terminologies that contain this text. The names, synonyms, properties for a term are searched for matches to the entered text.
+
Enter text and find terms across multiple terminologies that contain this text. The names, ids, synonyms, properties for a term are searched for matches to the entered text, and the best match (only) from each ontology is displayed.
  
−
To '''find a term in any ontology''' enter the full or partial name the term in the search box and simply hit the Search button. The system looks for matches in the term name, synonyms, term ids, and in property values. You can filter the returned values by ontology or by the type of match by selecting one of the filter links in the output table. If you want to '''search only in a subset of ontologies''' you can specify the desired ontologies in the Ontologies box. (Note that it is no faster to search a subset than to search all ontologies.) Simply type the ontology name or acronym to chose the desired ontology. You can also select a set of ontologies from a list of all ontologies using the “select from list” link.  
+
To '''find a term in any ontology''' enter the name of the term in the search box and simply hit the Search button. The system looks for matches in the term name, synonyms, term ids, and in property values. You can filter the returned values by ontology or by the type of match by selecting one of the filter links in the output table. If you want to '''search only in a subset of ontologies''' you can specify the desired ontologies in the Ontologies box. (Note that it is no faster to search a subset than to search all ontologies.) Simply type the ontology name or acronym to chose the desired ontology. You can also select a set of ontologies from a list of all ontologies using the “select from list” link.  
  
−
To '''search programmatically''' see our [http://www.bioontology.org/wiki/index.php/NCBO_REST_services#Search_services Search REST API documentation].
+
Note that, for performance reasons, only the top 100 matches (that is, matched ontologies) are returned. If one or more ontologies are specified in the Ontologies box, all matches are returned.
 +
 
 +
To '''search programmatically''' see our [http://data.bioontology.org/documentation#nav_search Search REST API documentation].
  
 
=== Mappings Tab ===
 
=== Mappings Tab ===
  
−
Mappings are associations between two or more terms in different ontologies. This association typically, but not always, represents a degree of similarity between the terms. The author of the mapping defines the semantics of a particular mapping. It is also usual for a mapping to be bi-directional, but again, this is not required. The mapping author defines directionality.
+
Mappings are associations between two or more terms in different ontologies. This association typically, but not always, represents a degree of similarity between the terms. The author of the mapping defines the semantics of a particular mapping. It is also usual for a mapping to be bi-directional, but again, this is not required. The mapping author defines directionality (for details, please see our [http://www.bioontology.org/wiki/index.php/BioPortal_Mappings Mapping Documentation]).
  
 
To '''browse mappings''' for an ontology, select the ontology from the drop-down list. You will then see a table showing all ontologies for which at least one mapping exists between that ontology and the ontology you selected. Select an ontology from this table to browse the mappings between the two ontologies.
 
To '''browse mappings''' for an ontology, select the ontology from the drop-down list. You will then see a table showing all ontologies for which at least one mapping exists between that ontology and the ontology you selected. Select an ontology from this table to browse the mappings between the two ontologies.
  
−
To '''access mappings programmatically''', please see our [http://www.bioontology.org/wiki/index.php/BioPortal_Mappings_Service Mappings REST API documentation].
+
To '''access mappings programmatically''', please see our [http://data.bioontology.org/documentation#Mapping Mappings REST API documentation].
  
 
=== Recommender Tab ===
 
=== Recommender Tab ===
  
−
The Ontology Recommender accepts a body of text and returns a ranked set of ontologies that most closely match the text. The ranking takes into account both how many terms from the text are in the ontology, and both the size of the ontology and its granularity with respect to the matched terms.  
+
The Recommender takes as input a text or a list of keywords and '''suggests appropriate ontologies''' for it.
 +
 
 +
The ontology ranking algorithm used by the Recommender evaluates the adequacy of each ontology to the input using a combination of four evaluation criteria:
 +
* '''Coverage''': At what extent the ontology represents the input? The Recommender invokes the NCBO Annotator service to obtain all the annotations for the input and then uses those annotations to compute a coverage score for each ontology.
 +
* '''Acceptance''': How well-known and trusted is the ontology by the biomedical community? The number of visits to the ontology page in BioPortal and the presence or absence of the ontology in UMLS are used to compute an acceptance score for each ontology.
 +
* '''Detail of knowledge''': What is the level of detail provided by the ontology for the input data? It is computed using the number of definitions, synonyms and properties of the ontology classes that cover the input data.
 +
* '''Specialization''': How specialized is the ontology to the input data’s domain? It is calculated using the number and type of the annotations done with the ontology and the position of each annotated class in the ontology hierarchy. The result is normalized by the size of the ontology, in order to identify small ontologies that are specialized to the input data.
 +
 
 +
For each of these four criteria, a score is computed. Then, the scores obtained are weighted and aggregated into a final score for the ontology. The default weights used to aggregate the scores can be changed at the advanced options section.
 +
 
 +
Note that besides the ontologies output, which returns a ranked list of ontologies, the Recommender also has an ontology sets output, which allows to find those ontology sets that improve the coverage provided by individual ontologies.
 +
 
 +
To '''retrieve ontology recommendations programmatically''', please see our [http://data.bioontology.org/documentation#nav_recommender Ontology Recommender REST API documentation].
  
−
The '''ontology ranking algorithm''' is described in the paper [http://bmir.stanford.edu/file_asset/index.php/1591/BMIR-2010-1432.pdf Building an Ontology Recommender Web Service].
+
To '''cite the NCBO Ontology Recommender''', please use:
  
−
To '''retrieve ontology recommendations programmatically''', please see our [http://www.bioontology.org/wiki/index.php/Ontology_Recommender_Web_service Ontology Recommender REST API documentation].
+
Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).
  
 
=== Annotator Tab ===
 
=== Annotator Tab ===
  
−
To '''annotate text directly with ontological terms''', simply enter text in the box and press the submit button. The system matches words in the text to terms in ontologies by doing an exact string comparison (a “direct” match) between the text and ontology term names, synonyms, and ids.  
+
To '''generate annotations for text''', simply enter text in the box and press the submit button. The system matches words in the text to terms in ontologies by doing an exact string comparison (a “direct” match) between the text and ontology term names, synonyms, and ids.  
  
 
In addition to the direct matches, the user may '''expand the set of matches''' by including matches from mapped terms and from hierarchical expansion. For most ontologies (OWL and UMLS RRF) the system performs the hierarchical expansion on the superclass (“is-a”) relationship. For OBO ontologies the hierarchical expansion also includes the part-of relationship.  You use the “number of levels” field to control the number of levels up the hierarchy for which the system will return terms for a given match.
 
In addition to the direct matches, the user may '''expand the set of matches''' by including matches from mapped terms and from hierarchical expansion. For most ontologies (OWL and UMLS RRF) the system performs the hierarchical expansion on the superclass (“is-a”) relationship. For OBO ontologies the hierarchical expansion also includes the part-of relationship.  You use the “number of levels” field to control the number of levels up the hierarchy for which the system will return terms for a given match.
  
  
−
To '''create annotations programmatically''' see the [http://www.bioontology.org/wiki/index.php/Annotator_Web_service Annotator REST API documentation].
+
To '''generate annotations programmatically''' see the [http://www.bioontology.org/wiki/index.php/Annotator_User_Guide REST API documentation].
 +
 
 +
Further information about the workings of the Annotator is available at [http://www.ncbi.nlm.nih.gov/pubmed/19761568 Shah et al BMC Bioinformatics. 2009 Sep 17;10 Suppl 9:S14]
 +
 
 +
=== Projects Tab ===
 +
 
 +
This page shows selected projects which make use of BioPortal technology. To '''add your project''' to this list press the "Create New Project" button. You must be logged in to BioPortal to create a new project.
 +
 
 +
== Common Tasks ==
 +
 
 +
=== Submitting an ontology ===
 +
 
 +
==== Minimum requirements ====
 +
 
 +
===== BioPortal account =====
 +
You need to create an account on BioPortal if you don’t already have one:
 +
 
 +
http://bioportal.bioontology.org/accounts/new
 +
 
 +
This will allow you to manage submissions and updates to your ontology.
 +
 
 +
===== Ontology formats =====
 +
BioPortal supports several standard formats for ontologies. Ensure that your ontology is in one of the following formats:
 +
 
 +
* [https://www.w3.org/OWL/ OWL] (Web Ontology Language)
 +
* [https://obofoundry.org/ OBO] (Open Biomedical Ontologies)
 +
* [https://www.w3.org/2004/02/skos/ SKOS] (Simple Knowledge Organization System)
 +
 
 +
For SKOS vocabularies, please note that BioPortal requires particular SKOS constructs to be present. Read more on our [[SKOSSupport|SKOS Support]] page.
 +
 
 +
===== File size =====
 +
The ontology file should not be excessively large (though there are no strict file size limits, smaller files are easier to process).
 +
 
 +
===== Metadata =====
 +
As part of the submission process, you’ll need to provide certain metadata attributes. Some of the key metadata fields include:
  
−
=== Resource Index Tab ===
+
* '''Name:''' the human-readable name of your ontology
 +
* '''Acronym:''' a unique identifier used to refer to your ontology in the system. The acronym is typically a short abbreviation of the ontology’s full name, often made up of capitalized initials or key terms. For example: '''SNOMEDCT''' (Systematized Nomenclature of Medicine – Clinical Terms). The acronym must be 17 characters or fewer.
 +
* '''Administrators:''' one or more BioPortal user accounts with administrative access to your ontology
 +
* '''Description:''' a short summary describing the purpose and scope of the ontology
 +
* '''Contact information:''' the names and email addresses of the ontology’s authors or maintainers
 +
* '''Format:''' the format of your ontology source file (OWL, OBO, or SKOS)
 +
* '''Status:''' alpha, beta, production, or retired
 +
* '''Release date:''' the release date of the ontology source file that you upload to BioPortal
  
−
The resource index is a pre-calculated set of annotations of selected biomedical resources.  We have annotated these resources with all terms in all BioPortal ontologies. To retrieve records for an ontology term, enter the term in the box and press the "Search" button.
+
==== Creating an ontology entry ====
  
−
To '''access annotations for resources programmatically''', please see our [http://www.bioontology.org/wiki/index.php/Resource_Index_REST_Web_Service_User_Guide Resource Index REST API documentation].
+
Once you have an account and are logged in, navigate to the Browse page:
  
−
=== Projects Tab ===
+
http://bioportal.bioontology.org/ontologies
 +
 
 +
… and click the "Submit New Ontology" button.
 +
 
 +
In the resulting form, you’ll be asked to fill out some metadata about your ontology. If you do not want the public to see your ontology, you can specify it as private, then indicate what accounts should have access to it.
 +
 
 +
Once you’ve filled out the form, click the "Create ontology" button. This will create the ontology summary page for your ontology.  Note that so far you are only describing the ontology in general terms, not submitting a specific file.
 +
 
 +
Finally on the summary page, you can click the "Add submission” link. This new submission form is where you’ll be able to specify your ontology file, as well as things like the description of this update, the version number, and so on.
 +
 
 +
Once you have created the ontology submission, usually right away you can access its basic information and possibly its classes, if there are not too many of them. More detailed indexing takes place asynchronously, often scheduled at night. All of that should be finished by the next day (Pacific Time); if not, send an email to the support list.
 +
 
 +
==== Updating an existing ontology submission ====
 +
If your ontology already is in BioPortal and you have a new version, it can be updated in one of two ways if you are logged in as a manager of the ontology.
 +
 
 +
If the original submission was set to automatically update from a source URL, you can learn the source URL using the Submissions edit icon (pencil icon to the right of the Submissions header on the Summary page). BioPortal examines the content at this URL nightly, and re-submits the content if it has changed in any way (determined by the checksum). If the updated submission does not parse, the ontology manager(s) should be notified via email.
 +
 
 +
If the original submission was not set to automatically update, or if you want to update the ontology immediately, you can upload the ontology directly from your computer. This will begin the upload process immediately, and schedule the ontology to be parsed shortly thereafter. (After the successful submission, don't forget to re-enter the URL and setting for the automatic update process, if you want that to be enabled.) Usually ontology parsing is complete within a a few minutes to an  hour, except for large ontologies; ontology indexing and automatic mappings occur overnight (Pacific Time).
 +
 
 +
To begin this process, click on the plus sign to the right of the Submissions header on the Summary page. This gives you a chance to update the metadata for the submission, and change the way it is uploaded to BioPortal (manually from a local file, or automatically from a URL).
  
−
This page shows selected projects which make use of BioPortal technology. To '''add your project''' to this list press the "Create New Project" button. You must be logged in to BioPortal to create a new project.
+
==== Updating metadata for your submission ====
 +
If you just want to change the metadata for your ontology's latest submission, use the Submissions edit (pencil) icon to the right of the Submissions header on the Summary page. Although the UI implies the new ontology will be downloaded, this should not occur if you do not change the download settings; only your metadata changes will be saved.
  
−
== Tasks ==
+
==== Update ontology settings ====
 +
To change the settings for the ontology—this includes things like name, administrators, viewing restrictions, categories, and whether the ontology is a View of another ontology—click on the edit (pencil) icon to the far right of the ontology name (at the top of the page).
  
−
=== Submitting an ontology to BioPortal ===
+
Note that you can not change the ontology acronym, because BioPortal uses this as a primary key and identifier for the ontology. If you want your ontology to have another acronym, you would need to resubmit it as a new ontology, using the new acronym, and then ask us to delete or deprecate the previous ontology.
−
Go to the "Browse" page and press the "Submit Ontology" button near the top of the page.
 
  
−
=== Viewing and editing notes ===
+
=== Requesting ontology changes ===
−
To view all notes for an ontology, chose the ontology from the Browse page and then select "Notes" from the drop-down list.
 
  
−
To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Notes" tab in the right-hand panel.
+
BioPortal offers the ability for users to request changes or extensions to an ontology when the ontology source file is maintained in GitHub. For more details, please refer to our [[Ontology Change Requests]] page.
  
 
=== Viewing and editing mappings ===
 
=== Viewing and editing mappings ===
Line 83: Line 162:
  
 
To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Mappings" tab in the right-hand panel.
 
To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Mappings" tab in the right-hand panel.
 +
 +
=== Viewing and editing notes ===
 +
To view all notes for an ontology, chose the ontology from the Browse page and then select "Notes" from the drop-down list.
 +
 +
To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Notes" tab in the right-hand panel.
  
 
=== Viewing and editing reviews ===
 
=== Viewing and editing reviews ===
 
Navigate to the ontology summary page by selecting the ontology name from the Browse tab. Create a review by pressing the "Create Review" button near the top of the page.
 
Navigate to the ontology summary page by selecting the ontology name from the Browse tab. Create a review by pressing the "Create Review" button near the top of the page.
  
−
== How to cite NCBO and BioPortal ==
+
=== Visualizing concepts and mappings ===
−
Noy NF, Shah NH, Whetzel PL, Dai B, Dorf M, Griffith N, Jonquet C, Rubin DL, Storey MA, Chute CG, Musen MA. BioPortal: ontologies and integrated data resources at the click of a mouse. Nucleic Acids Res. 2009 Jul 1;37(Web Server issue):W170-3. Epub 2009 May 29. PubMed PMID: 19483092; PubMed Central PMCID: PMC2703982.  
+
With the BioPortal user interface, you can [http://www.bioontology.org/wiki/index.php/Visualizing_Concepts_and_Mappings visualize ontology concepts and their mappings with other ontologies].
 +
 
 +
== Programming with the BioPortal API ==
 +
Documentation about how to use the BioPortal REST API to access information is available here:
 +
 
 +
http://data.bioontology.org/documentation
 +
 
 +
=== Getting an API key ===
 +
Use of the BioPortal REST API requires an API key. 
 +
 
 +
To retrieve your API key, log into your account on the [http://bioportal.bioontology.org BioPortal website]. If you don't have an account, you'll need to [http://bioportal.bioontology.org/accounts/new create one].
 +
 
 +
Your API key will be listed in plain text on your account page.
  
 
== Glossary ==
 
== Glossary ==
−
; class : A concept in the domain of the ontology. Used within BioPortal, class is a synonym for term or concept.  
+
; <span id="glossary_class">class</span>: A concept in the domain of the ontology. Used within BioPortal, class is a synonym for term or concept. Term is the preferred BioPortal label.
−
; concept : (from SKOS documentation) A concept is an idea or notion; a unit of thought. However, what constitutes a unit of thought is subjective, and this definition is meant to be suggestive, rather than restrictive. The notion of a concept is useful when describing the conceptual or intellectual structure of a ontology, and when referring to specific ideas or meanings established within an ontology.
+
; concept: (from SKOS documentation) A concept is an idea or notion; a unit of thought.  
−
; CUI :  Abbreviation for "Concept Unique Identifier" for UMLS ontologies. This is the unique identifier for a UMLS "concept". All terms in UMLS ontologies are identified with one or more CUIs.  
+
; CUI:  Abbreviation for "Concept Unique Identifier". These values that are assigned by UMLS for all terms in its ontologies. A CUI represents a "UMLS concept". An ontology term may be assigned to more than one CUI. The assignment of terms to CUI is intended to allow the creation of maps between terms in different ontologies.
−
; deprecated term : synonym for "obsolete term" in some ontologies.
+
; deprecated term: synonym for "obsolete term" in some ontologies.
−
; obsolete term : A term that the authors of the ontology have flagged as being "obsolete" and which they recommend that people not use. These terms are often left in ontologies (rather than removing them entirely) so that existing systems that depend on them will continue to function.
+
; group: a collection of ontologies that are typically associated with some outside group or organization.
−
; mapping : Asserted relationship between two terms in different ontologies. The nature of the exact relationship is left to the mapping author. The most common relationship for mappings between terms is "same as".
+
; <span id="glossary_obsolete_term">obsolete term</span>: A term that the authors of the ontology have flagged as being "obsolete" and which they recommend that people not use. These terms are often left in ontologies (rather than removing them entirely) so that existing systems that depend on them will continue to function.
 +
; mapping: Asserted relationship between two terms in different ontologies. The nature of the exact relationship is left to the mapping author. The most common relationship for mappings between terms is "same as".
 
; preferred name : Human readable label for a term that the authors of the ontology suggest be used when referring to the term. Alternate, non-preferred, names are synonyms.
 
; preferred name : Human readable label for a term that the authors of the ontology suggest be used when referring to the term. Alternate, non-preferred, names are synonyms.
−
; property : Named association between two entities. Examples are "definition" (a relation between a term and some text) and "part-of" (a relation between two terms).  
+
; <span id="glossary_property">property</span>: Named association between two entities. Examples are "definition" (a relation between a term and some text) and "part-of" (a relation between two terms).  
−
; resource : Biomedical resource (publication, database) that has been indexed with BioPortal ontologies.
+
; resource: Biomedical resource (publication, database) that has been indexed with the ontologies in BioPortal.
−
; synonym : Alternate name for a term. Every term has a single "preferred" name and may have any number of synonyms.
+
; <div id="slice_definition">slice</span>: An alternate entry point into BioPortal which has been configured to display and use a subset of the available ontologies. The slice is accessed via URL of the form http://<slice-name>.bioportal.bioontology.org . There is currently no way for an end user to create or configure slice. However, you may send a request to support@bioontology.org and request that a new slice be created for you.
−
; term : Concept in the domain of the ontology. Within BioPortal, term is a synonym for class or concept
+
; synonym: Alternate name for a term. Every term has a single "preferred" name and may have any number of synonyms.
−
; term mappings : Set of mappings for a given term to terms other ontologies.  
+
; term: Concept in the domain of the ontology. Within BioPortal, term is a synonym for class or concept. Term is the preferred label.
−
; term resources : Set of resources that contain annotations for a given term.
+
; term mappings: Set of mappings for a given term to terms other ontologies.  
 +
; term resources: Set of resources that contain annotations for a given term.
 +
 
 +
== BioPortal Frequently Asked Questions (FAQ) ==
 +
 
 +
Many specific questions are addressed at our [https://www.bioontology.org/wiki/BioPortal_FAQ FAQ for the BioPortal system].
 +
 +
== How to cite NCBO and BioPortal ==
 +
=== NCBO ===
 +
Musen MA, Noy NF, Shah NH, Whetzel PL, Chute CG, Story MA, Smith B; NCBO team. The National Center for Biomedical Ontology. J Am Med Inform Assoc. 2012 Mar-Apr;19(2):190-5. Epub 2011 Nov 10.
 +
 
 +
===NCBO Ontology Recommender===
 +
Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).
 +
 
 +
=== BioPortal ===
 +
Whetzel PL, Noy NF, Shah NH, Alexander PR, Nyulas C, Tudorache T, Musen MA. BioPortal: enhanced functionality via new Web services from the National Center for Biomedical Ontology to access and use ontologies in software applications. Nucleic Acids Res. 2011 Jul;39(Web Server issue):W541-5. Epub 2011 Jun 14.
 +
 
 +
=== SPARQL Endpoint ===
 +
Salvadores M, Horridge M, Alexander PR, Fergerson RW, Musen MA, and Noy NF. Using SPARQL to Query BioPortal Ontologies and Metadata. International Semantic Web Conference. Boston US. LNCS 7650, pp. 180195, 2012.

Latest revision as of 14:35, 27 September 2024

User Interface

Home Page

BioPortal provides access to commonly used biomedical ontologies and to tools for working with them. BioPortal allows you to

All information available through the BioPortal Web site is also available through the NCBO Web service REST API. Please see REST API documentation for more information.

Browse Tab

Browse our library of Biomedical ontologies and submit your own ontology. This page displays some summary information about each ontology. More detailed summary information is available on the ontology summary page for each ontology. You can reach this page by clicking on the ontology name link.

To find a particular ontology quickly, begin typing the ontology name or abbreviation in the “Filter by Text” field. You can also narrow the list of ontologies shown by selecting a specific “category” (a domain) or a “group” to which the ontology belongs. To submit an ontology press the “Submit New Ontology” button. You must be logged in to BioPortal to submit an ontology. You can subscribe to receive RSS updates when any ontology in the system changes by clicking the subscribe link. You can subscribe to updates for a particular ontology from the summary page for that ontology. To go to the summary page click on the ontology name link.

Some submitters want to control who can browse the terms in their ontology. These ontologies are marked with visibility “Private” or “Licensed”. To browse the terms in these ontologies you must be both

  • logged in to BioPortal
  • granted access to the ontology

For private ontologies, the ontology submitter directly controls access to the ontology. Please contact the submitter to gain access to a private ontology. Contact information for the ontology is available on the ontology summary page. For licensed ontologies, the submitter indirectly controls access to the ontology. When you attempt to access a licensed ontology, the system will prompt you to enter the license information required by the submitter. When you have entered the required information, the system will allow you to access the ontology. In addition, there are "summary only" ontologies. The terms for these ontologies are not available in BioPortal at all. Please contact the ontology submitter for more information about these ontologies.

Ontology Popularity

Ontologies on the Browse tab are ordered based on their popularity, which is measured using the number of Google Analytics page views from the previous month. The more page views an ontology receives, the higher it appears on the list.

Programmatic Access

To access ontologies programmatically, see our Resources REST API documentation (then look under Media Types).

Search Tab

Enter text and find terms across multiple terminologies that contain this text. The names, ids, synonyms, properties for a term are searched for matches to the entered text, and the best match (only) from each ontology is displayed.

To find a term in any ontology enter the name of the term in the search box and simply hit the Search button. The system looks for matches in the term name, synonyms, term ids, and in property values. You can filter the returned values by ontology or by the type of match by selecting one of the filter links in the output table. If you want to search only in a subset of ontologies you can specify the desired ontologies in the Ontologies box. (Note that it is no faster to search a subset than to search all ontologies.) Simply type the ontology name or acronym to chose the desired ontology. You can also select a set of ontologies from a list of all ontologies using the “select from list” link.

Note that, for performance reasons, only the top 100 matches (that is, matched ontologies) are returned. If one or more ontologies are specified in the Ontologies box, all matches are returned.

To search programmatically see our Search REST API documentation.

Mappings Tab

Mappings are associations between two or more terms in different ontologies. This association typically, but not always, represents a degree of similarity between the terms. The author of the mapping defines the semantics of a particular mapping. It is also usual for a mapping to be bi-directional, but again, this is not required. The mapping author defines directionality (for details, please see our Mapping Documentation).

To browse mappings for an ontology, select the ontology from the drop-down list. You will then see a table showing all ontologies for which at least one mapping exists between that ontology and the ontology you selected. Select an ontology from this table to browse the mappings between the two ontologies.

To access mappings programmatically, please see our Mappings REST API documentation.

Recommender Tab

The Recommender takes as input a text or a list of keywords and suggests appropriate ontologies for it.

The ontology ranking algorithm used by the Recommender evaluates the adequacy of each ontology to the input using a combination of four evaluation criteria:

  • Coverage: At what extent the ontology represents the input? The Recommender invokes the NCBO Annotator service to obtain all the annotations for the input and then uses those annotations to compute a coverage score for each ontology.
  • Acceptance: How well-known and trusted is the ontology by the biomedical community? The number of visits to the ontology page in BioPortal and the presence or absence of the ontology in UMLS are used to compute an acceptance score for each ontology.
  • Detail of knowledge: What is the level of detail provided by the ontology for the input data? It is computed using the number of definitions, synonyms and properties of the ontology classes that cover the input data.
  • Specialization: How specialized is the ontology to the input data’s domain? It is calculated using the number and type of the annotations done with the ontology and the position of each annotated class in the ontology hierarchy. The result is normalized by the size of the ontology, in order to identify small ontologies that are specialized to the input data.

For each of these four criteria, a score is computed. Then, the scores obtained are weighted and aggregated into a final score for the ontology. The default weights used to aggregate the scores can be changed at the advanced options section.

Note that besides the ontologies output, which returns a ranked list of ontologies, the Recommender also has an ontology sets output, which allows to find those ontology sets that improve the coverage provided by individual ontologies.

To retrieve ontology recommendations programmatically, please see our Ontology Recommender REST API documentation.

To cite the NCBO Ontology Recommender, please use:

Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

Annotator Tab

To generate annotations for text, simply enter text in the box and press the submit button. The system matches words in the text to terms in ontologies by doing an exact string comparison (a “direct” match) between the text and ontology term names, synonyms, and ids.

In addition to the direct matches, the user may expand the set of matches by including matches from mapped terms and from hierarchical expansion. For most ontologies (OWL and UMLS RRF) the system performs the hierarchical expansion on the superclass (“is-a”) relationship. For OBO ontologies the hierarchical expansion also includes the part-of relationship. You use the “number of levels” field to control the number of levels up the hierarchy for which the system will return terms for a given match.


To generate annotations programmatically see the REST API documentation.

Further information about the workings of the Annotator is available at Shah et al BMC Bioinformatics. 2009 Sep 17;10 Suppl 9:S14

Projects Tab

This page shows selected projects which make use of BioPortal technology. To add your project to this list press the "Create New Project" button. You must be logged in to BioPortal to create a new project.

Common Tasks

Submitting an ontology

Minimum requirements

BioPortal account

You need to create an account on BioPortal if you don’t already have one:

http://bioportal.bioontology.org/accounts/new

This will allow you to manage submissions and updates to your ontology.

Ontology formats

BioPortal supports several standard formats for ontologies. Ensure that your ontology is in one of the following formats:

  • OWL (Web Ontology Language)
  • OBO (Open Biomedical Ontologies)
  • SKOS (Simple Knowledge Organization System)

For SKOS vocabularies, please note that BioPortal requires particular SKOS constructs to be present. Read more on our SKOS Support page.

File size

The ontology file should not be excessively large (though there are no strict file size limits, smaller files are easier to process).

Metadata

As part of the submission process, you’ll need to provide certain metadata attributes. Some of the key metadata fields include:

  • Name: the human-readable name of your ontology
  • Acronym: a unique identifier used to refer to your ontology in the system. The acronym is typically a short abbreviation of the ontology’s full name, often made up of capitalized initials or key terms. For example: SNOMEDCT (Systematized Nomenclature of Medicine – Clinical Terms). The acronym must be 17 characters or fewer.
  • Administrators: one or more BioPortal user accounts with administrative access to your ontology
  • Description: a short summary describing the purpose and scope of the ontology
  • Contact information: the names and email addresses of the ontology’s authors or maintainers
  • Format: the format of your ontology source file (OWL, OBO, or SKOS)
  • Status: alpha, beta, production, or retired
  • Release date: the release date of the ontology source file that you upload to BioPortal

Creating an ontology entry

Once you have an account and are logged in, navigate to the Browse page:

http://bioportal.bioontology.org/ontologies

… and click the "Submit New Ontology" button.

In the resulting form, you’ll be asked to fill out some metadata about your ontology. If you do not want the public to see your ontology, you can specify it as private, then indicate what accounts should have access to it.

Once you’ve filled out the form, click the "Create ontology" button. This will create the ontology summary page for your ontology. Note that so far you are only describing the ontology in general terms, not submitting a specific file.

Finally on the summary page, you can click the "Add submission” link. This new submission form is where you’ll be able to specify your ontology file, as well as things like the description of this update, the version number, and so on.

Once you have created the ontology submission, usually right away you can access its basic information and possibly its classes, if there are not too many of them. More detailed indexing takes place asynchronously, often scheduled at night. All of that should be finished by the next day (Pacific Time); if not, send an email to the support list.

Updating an existing ontology submission

If your ontology already is in BioPortal and you have a new version, it can be updated in one of two ways if you are logged in as a manager of the ontology.

If the original submission was set to automatically update from a source URL, you can learn the source URL using the Submissions edit icon (pencil icon to the right of the Submissions header on the Summary page). BioPortal examines the content at this URL nightly, and re-submits the content if it has changed in any way (determined by the checksum). If the updated submission does not parse, the ontology manager(s) should be notified via email.

If the original submission was not set to automatically update, or if you want to update the ontology immediately, you can upload the ontology directly from your computer. This will begin the upload process immediately, and schedule the ontology to be parsed shortly thereafter. (After the successful submission, don't forget to re-enter the URL and setting for the automatic update process, if you want that to be enabled.) Usually ontology parsing is complete within a a few minutes to an hour, except for large ontologies; ontology indexing and automatic mappings occur overnight (Pacific Time).

To begin this process, click on the plus sign to the right of the Submissions header on the Summary page. This gives you a chance to update the metadata for the submission, and change the way it is uploaded to BioPortal (manually from a local file, or automatically from a URL).

Updating metadata for your submission

If you just want to change the metadata for your ontology's latest submission, use the Submissions edit (pencil) icon to the right of the Submissions header on the Summary page. Although the UI implies the new ontology will be downloaded, this should not occur if you do not change the download settings; only your metadata changes will be saved.

Update ontology settings

To change the settings for the ontology—this includes things like name, administrators, viewing restrictions, categories, and whether the ontology is a View of another ontology—click on the edit (pencil) icon to the far right of the ontology name (at the top of the page).

Note that you can not change the ontology acronym, because BioPortal uses this as a primary key and identifier for the ontology. If you want your ontology to have another acronym, you would need to resubmit it as a new ontology, using the new acronym, and then ask us to delete or deprecate the previous ontology.

Requesting ontology changes

BioPortal offers the ability for users to request changes or extensions to an ontology when the ontology source file is maintained in GitHub. For more details, please refer to our Ontology Change Requests page.

Viewing and editing mappings

To view all mappings for an ontology, chose the ontology from the Browse page and then select "Mappings" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Mappings" tab in the right-hand panel.

Viewing and editing notes

To view all notes for an ontology, chose the ontology from the Browse page and then select "Notes" from the drop-down list.

To view the notes for a particular term, navigate to the ontology and term (using the "Browse" tab and select the terms item from the dropdown) and then select the "Notes" tab in the right-hand panel.

Viewing and editing reviews

Navigate to the ontology summary page by selecting the ontology name from the Browse tab. Create a review by pressing the "Create Review" button near the top of the page.

Visualizing concepts and mappings

With the BioPortal user interface, you can visualize ontology concepts and their mappings with other ontologies.

Programming with the BioPortal API

Documentation about how to use the BioPortal REST API to access information is available here:

http://data.bioontology.org/documentation

Getting an API key

Use of the BioPortal REST API requires an API key.

To retrieve your API key, log into your account on the BioPortal website. If you don't have an account, you'll need to create one.

Your API key will be listed in plain text on your account page.

Glossary

class
A concept in the domain of the ontology. Used within BioPortal, class is a synonym for term or concept. Term is the preferred BioPortal label.
concept
(from SKOS documentation) A concept is an idea or notion; a unit of thought.
CUI
Abbreviation for "Concept Unique Identifier". These values that are assigned by UMLS for all terms in its ontologies. A CUI represents a "UMLS concept". An ontology term may be assigned to more than one CUI. The assignment of terms to CUI is intended to allow the creation of maps between terms in different ontologies.
deprecated term
synonym for "obsolete term" in some ontologies.
group
a collection of ontologies that are typically associated with some outside group or organization.
obsolete term
A term that the authors of the ontology have flagged as being "obsolete" and which they recommend that people not use. These terms are often left in ontologies (rather than removing them entirely) so that existing systems that depend on them will continue to function.
mapping
Asserted relationship between two terms in different ontologies. The nature of the exact relationship is left to the mapping author. The most common relationship for mappings between terms is "same as".
preferred name
Human readable label for a term that the authors of the ontology suggest be used when referring to the term. Alternate, non-preferred, names are synonyms.
property
Named association between two entities. Examples are "definition" (a relation between a term and some text) and "part-of" (a relation between two terms).
resource
Biomedical resource (publication, database) that has been indexed with the ontologies in BioPortal.
slice
An alternate entry point into BioPortal which has been configured to display and use a subset of the available ontologies. The slice is accessed via URL of the form http://<slice-name>.bioportal.bioontology.org . There is currently no way for an end user to create or configure slice. However, you may send a request to support@bioontology.org and request that a new slice be created for you.
synonym
Alternate name for a term. Every term has a single "preferred" name and may have any number of synonyms.
term
Concept in the domain of the ontology. Within BioPortal, term is a synonym for class or concept. Term is the preferred label.
term mappings
Set of mappings for a given term to terms other ontologies.
term resources
Set of resources that contain annotations for a given term.

BioPortal Frequently Asked Questions (FAQ)

Many specific questions are addressed at our FAQ for the BioPortal system.

How to cite NCBO and BioPortal

NCBO

Musen MA, Noy NF, Shah NH, Whetzel PL, Chute CG, Story MA, Smith B; NCBO team. The National Center for Biomedical Ontology. J Am Med Inform Assoc. 2012 Mar-Apr;19(2):190-5. Epub 2011 Nov 10.

NCBO Ontology Recommender

Martínez-Romero, M., Jonquet, C., O’Connor, M. J., Graybeal, J., Pazos, A., Musen, M. A. (2017). NCBO Ontology Recommender 2.0: An Enhanced Approach For Biomedical Ontology Recommendation. Journal of Biomedical Semantics, 8(21), 1-22 (https://jbiomedsem.biomedcentral.com/articles/10.1186/s13326-017-0128-y).

BioPortal

Whetzel PL, Noy NF, Shah NH, Alexander PR, Nyulas C, Tudorache T, Musen MA. BioPortal: enhanced functionality via new Web services from the National Center for Biomedical Ontology to access and use ontologies in software applications. Nucleic Acids Res. 2011 Jul;39(Web Server issue):W541-5. Epub 2011 Jun 14.

SPARQL Endpoint

Salvadores M, Horridge M, Alexander PR, Fergerson RW, Musen MA, and Noy NF. Using SPARQL to Query BioPortal Ontologies and Metadata. International Semantic Web Conference. Boston US. LNCS 7650, pp. 180195, 2012.

Retrieved from "https://www.bioontology.org//mediawiki/index.php?title=BioPortal_Help&oldid=13134"