Developer
Documentation about how to use the EcoPortal REST API to access information is available here:
-
http://ecoportal.lifewatch.eu:8080/documentation
-
There are several ways in which you can use the NCBO technology on your own Web site or in your application. For example, I can think of:
-
I have a list of terms that were used to annotate a data set, how can I see if any of these terms exist in standard semantic resources? Use the Search Web service to search for your term in all semantic resources in BioPortal. If you have a small list of terms, searching each term individually via the EcoPortal Search UI may be sufficient. Otherwise, for a long list of terms, use the Search Web service directly.
-
I would like to find all terms mapped from my semantic resource to other semantic resources in EcoPortal.
Use the Mapping web service to find terms in other EcoPortal semantic resources similar to terms in your semantic resource. These mappings include mapping generated manually (DbXrefs) and programatically (LOOM). -
I am the curator for a database and need to triage papers to identify which papers from DATACITE are most related to my database and a good source of new information to add to my database. Use the Annotator Web service to identify ontology terms in textual data
-
I have DATACITE abstracts and want to link information in the abstracts to my database of interest. Use the Annotator Web service. If your database of interest is included in the NCBO Resource Index you can search the database(s) for records that contain these terms. See https://github.com/lifewatch-eric/documentation/wiki/EcoTools#resource-index for more details on the Resource Index web service.
-
I have a web form with text fields I would like to populate with semantic resource terms, e.g. to select relevant terms from EcoPortal semantic resource. Use the Autocomplete widget. Select the "Get Code" button for the code and instructions on how to add this Javascript to your web form.
-
I would like to add the graph display of my semantic resource on my web site. Use the Visualization widget for your semantic resource of interest from the widgets page. Select the "Get Code" button for the code and instructions on how to add this Javascript to your web form.
-
I would like to get all terms from a semantic resource and re-format the data to use in my own system. Use the Get All Terms Web service to get all terms and properties for your ontology of interest.
-
I need to navigate through a semantic resource and traverse the semantic resource hierarchy for my software application, how can I use the Web services to do this? Use the Get All terms Web service.
-
How can I limit the selection of semantic resources used with the NCBO Annotator to a certain Category or Domain? Use the List all semantic resources and Get Groups/Domains Web service to identify the group/domain of interest
-
All the content that the NCBO EcoPortal uses (and more!) is available via REST services. You can use the NCBO REST Services:
- to access all EcoPortal semantic resources, their different versions, and metadata for those versions
- to access information about any semantic resource concept in EcoPortal (its definition, synonyms, and other properties)
- to search across all semantic resources in EcoPortal
- to get hierarchy information for EcoPortal semantic resources (such as parents, children, or siblings of a class, roots or leaves of a class hierarchy)
-
A service that identifies mentions of ecological semantic resource concepts in text that users submit. You can use the annotator service to tag automatically any item of interest with terms from UMLS and EcoPortal semantic resources.
-
-
Use of the EcoPortal REST API requires an API key. To retrieve your API key, log into your account on the EcoPortal website. Your API key will be listed in plain text on your account page. E.g.
If you don't have an account, you'll need to create one.
-
NCBO widgets are the HTML or Javascript code that you can put on your Web site or Web form to use EcoPortal functionality there. Using NCBO Widgets is just one of the ways in which you can use the NCBO technology directly on your Web site or in your application.
-
-
Term-selection field on a form: You can add a text field to your Web form that will let users enter a term from a controlled vocabulary (e.g., terms from a single semantic resource)
- Example use case: Suppose you are running a tissue microarray database and users upload sample descriptions to your database using a web form. There is usually a field for the user to enter the diagnosis for the tissue sample that she is entering. Usually, this field is a text-box or a drop down menu populated with a list of controlled terms. The free text-box is prone to errors, the drop-down gets too unwieldy with large terminologies. Using the NCBO term-selection widget to have users easily select a term from an ontology or controlled vocabulary (such as the NCI Thesaurus) to fill in the field. For example, when the user starts typing "fish", the term "fish traits" pops up.
-
What does the term-selection field get you:
- Look-ahead so that you don't need to type the whole term
- Controlled vocabulary provides consistency of the way different users use the term
- When a new version of your controlled vocabulary becomes available in EcoPortal, the widget will automatically use that new version.
-
Semantic resource search widget: You can add to your Web site a search box that searches a specific EcoPortal ontology. When the user selects the term of interest (with the help of the look-ahead feature), he can jump to the EcoPortal page for the corresponding concept in EcoPortal.
-
Semantic resource visualization widget: You can put a widget on your Web site that visualizes your entire semantic resource of interest, or some part of it, as on the "Visualize" tab in EcoPortal.
-
NCBO Ontology Tree Widget: You can put a widget on your Web site that displays the semantic resource tree, or some part of it, as on the "Visualize" tab in BioPortal.
-
-
The easiest way to add any NCBO widget to your HTML page or Web form is by following these steps:
- Find your ontology of interest in the list of EcoPortal semantic resources (e.g., Fish Traits Thesaurus)
- Click on the semantic resource name to get to the page with Details for that semantic resource (e.g., the Details for Fish Traits Thesaurus)
- On the Semantic resource Details page, go to Semantic resource Widgets tab
- Select the widget you want
- Click the button below the widgets to get instructions for the specific widget
-
To add a field to your form that lets the user fetch a term from your semantic resource of interest, do the following:
- Download the form_complete.js file and put it on your server
- in the header for the page where you want the form field, include the form_complete.js file
- On your form, for the fields where you want to use the term-selection widget, specify the field's class in the following format:
bp_form_complete-{semantic_resource_acronym_list}-{value}- For example,
bp_form_complete-FISHTRAITS-uriwill use FISH TRAITS Thesaurus (ontology acronym is FISHTRAITS) and will put the term URI in the field after the user selects the term from the pull-down list -
Note: In addition to single ontology ids, you can use a list:
bp_form_complete-FISHTRAITS, ENVTHES-uri -
OR use 'all' to search across all EcoPortal semantic resource:
bp_form_complete-all-uri
- For example,
- You can use the following parameters to select which value will be placed into the user-visible input field:
-
uri: put the complete URI of the term (e.g., [TODO](rename baseURI)); -
shortid: put the short id of the term, as used in EcoPortal (e.g., [TODO](rename local name)); -
name: put the preferred name of the term (e.g., "Trait");
-
-
Hidden form elements auto-generated In addition to the input element you defined, there are four hidden form elements that are created and then set when a user selects a term from the list. For example, if you create a field with this code:
<input type="text" name="a" class="bp_form_complete-all-uri" size="100"/>The 'name' attribute is used to create the four following fields (note how the 'a' from the name attribute is appended to the id attribute):
<input type="hidden" id="a_ecoportal_preferred_name"> <input type="hidden" id="a_ecoportal_concept_id"> <input type="hidden" id="a_ecoportal_ontology_id"> <input type="hidden" id="a_ecoportal_full_id">
-
Optional attributes
-
Include term definitions. Use
data-bp_include_definitions="true". This will display definitions with the list of terms that are returned. For example, use this code to display search results for 'heart' terms, with definitions, in the FISHTRAITS Thesaurus.<input type="text" name="m" data-bp_include_definitions="true" class="bp_form_complete-FISHTRAITS-name"/> -
Limit lookup to terms below a root term. Use data-bp_search_branch="{class_id}" (replace {class_id} with the class id for the term to use as the branch root). For example, use this code to limit the search for 'FISH' to terms within the 'Fish Trait' branch of the FISHTRAITS Thesaurus.
<input type="text" name="n" data-bp_search_branch="Fish Trait" class="bp_form_complete-FISHTRAITS-name"/> -
Object types:
-
Search 'class' and 'property' objects. Use
data-bp_objecttypes="class,property". For example, use this code to search for 'function' among both 'class' and 'property' objects from the "Adverse Event Reporting Ontology".<input type="text" name="o" data-bp_objecttypes="class,property" class="bp_form_complete-AERO-uri"/> -
Search only 'property' objects. Use data-bp_objecttypes="property". For example, use this code to search for 'function' among only 'property' objects from the "Adverse Event Reporting Ontology".
<input type="text" name="p" data-bp_objecttypes="property" class="bp_form_complete-AERO-uri"/> -
Search 'class' and 'individual' objects. Use
data-bp_objecttypes="class,individual". For example, use this code to search for 'seizure' among 'class' and 'individual' objects from the "Adverse Event Reporting Ontology".<input type="text" name="q" data-bp_objecttypes="class,individual" class="bp_form_complete-AERO-uri"/> -
Only search 'individual' objects. Use
data-bp_objecttypes="individual". For example, use this code to this search for 'seizure' only among 'individual' objects from the "Adverse Event Reporting Ontology".<input type="text" name="r" data-bp_objecttypes="individual" class="bp_form_complete-AERO-uri"/>
-
Search 'class' and 'property' objects. Use
-
Include term definitions. Use
-
To add a search widget to your HTML page that searches a specific ontology, do the following:
-
Download the quick_jump.js file and put it on your server
-
Copy the code below and paste it to your HTML page.
<div id="bp_quick_jump"></div> <script type="text/javascript"> var BP_ontology_id = "FISHTRAITS"; </div> <script src="quick_jump.js" type="text/javascript" charset="utf-8"></script> -
Note: If you would like to use Quick Jump across multiple semantic resources:
- You can enter a comma-separated list of semantic resource ids:
var BP_ontology_id = "FISHTRAITS,ENVTHES"; - You cans set the variable to 'all' to search all ontologies in EcoPortal:
var BP_ontology_id = "all";
- You can enter a comma-separated list of semantic resource ids:
-
In the code that you just pasted, make sure to change the path to the quick_jump.js file to point to the location where you put the file (relative to your HTML file). For example, if you put the quick_jump.js file in the same directory as your HTML file, this is the code you would use:
<script type="text/javascript"> var BP_ontology_id = "FISHTRAITS"; </div> <script src="quick_jump.js" type="text/javascript" charset="utf-8"></script> -
To limit the term lookup to a particular branch of a semantic resource, include the following Javascript in your page (replace conceptid with the id for the term which you would like to use as the root of your branch):
var BP_search_branch = "{class_id}"; -
To display definitions with the list of terms that are returned, include the following Javascript in your page:
var BP_include_definitions = true;
-
-
To add a widget visualizing your ontology to your HTML page, simple copy the code from the Ontology Widget page for your semantic resource of interest. Here is a sample:
<iframe src="http://ecoportal.lifewatchitaly.eu/widgets/visualization/?ontology=FISHTRAITS&class=SELECT_CLASS&apikey=YOUR_API_KEY"frameborder="0"> </iframe>
-
-
Copyright © 2021, LifeWatch ERIC. All rights reserved.