6.3. Deploying the EBI OLS¶
6.3.1. Main Objectives¶
This recipe is a step-by-step guide on how to deploy the EBI Ontology Lookup Service (OLS) 3, 1 on local machines. This demonstrates the workflow for deploying open source ontology service software in-house 2.
6.3.2. Introduction¶
With an increasing need for ontology infrastructure to improve the interoperability of information-based R&D activities, many pharmaceutical companies seek ontology management solutions and ontology services. Compared with developing local ontology services from scratch, reusing and redeveloping open-source ontology services save the time and cost. Recipe FCB003 identifies public open-source ontology services. In this recipe, we use the Ontology Lookup Service to demonstrate the workflow of deploying public ontology services in-house.
Ontology Lookup Service is an open-source ontology management service developed by EMBL-EBI.
It is a repository for biomedical ontologies, and serves as a single point of access to query, browse and navigate different ontologies.
OLS supports the Open Biological and Biomedical Ontology (OBO) Foundry guidelines and connects with other ontology services.
It provides both web interface and API to search and browser ontologies. Recipe FCB003 provides a detailed description of OLS.
A local OLS allows users to protect and control their ontology-related data, and make stable and fast access to ontology services possible.
It can serve as the hub of internal ontology eco-system, linking internal vocabulary, terminology management and data annotation activities together to improve the interoperability.
6.3.3. Requirements¶
This recipe is intended for bioinformaticians or developers who want to explore public ontologies and ontology services. The users are expected to be familiar with Unix-based OS and basic Bash programming syntax and commands. The users should also be comfortable with YAML or other data-serialization languages. Knowledge about Docker allows users to further customize their local service.
This recipe can also be applied by organizational users.
Warning
Make sure to comply with good cyber security practices and talk to local IT departments and support staff about specific policies regarding tool deployment the use of containerized applications, proxy settings, and firewalls.
6.3.5. Ingredients¶
6.3.6. Step-by-step guide¶
6.3.6.1. 1. Install dependencies¶
Software |
Description |
Version |
Installation |
|---|---|---|---|
Git |
Get the versioned source file |
2.17.1 |
|
Docker |
Deliver software in containers |
18.09.01 |
Software |
Description |
Version |
Installation |
|---|---|---|---|
Git |
Get the versioned source file |
2.26.2.windows.1 |
|
Docker Desktop |
Deliver software in containers |
2.2.0.5 (Engine v.19.03.8) |
|
PowerShell |
Execute commands |
5.1.17763(Desktop Edition) |
Note
This recipe was developed on a Unix-based environment and tested on Linux and macOS machines.
Minor modifications are required to run it on Windows machines.
6.3.6.2. 2. Load ontologies into OLS¶
Ontologies in both OBO and OWL formats can be loaded to OLS by adding ontology metadata to the configuration file, ols-config.yaml.
Three fields, id,url and ontology_purl are mandatory ontology metadata attributes.
Other fields are also recommended, especially for self-defined ontologies.
Below is an example configuration of the Experimental Factor Ontology (EFO) provided by OLS.
## EFO
# * are required fields
id: efo // short unique id for the ontology *
preferredPrefix: EFO // preferred display name for the ontology
title: Experimental Factor Ontology // Short title of the ontology
uri: http://www.ebi.ac.uk/efo // The ontology URI * description: "The Experimental Factor Ontology (EFO) provides a…" // Full ontology description
ontology_purl: http://www.ebi.ac.uk/efo/efo.owl // URL to get the ontology from *
homepage: http://www.ebi.ac.uk/efo // homepage of the ontology
mailing_list: efo-users@lists.sourceforge.net // assocaited mailing list
definition_property: // predicates that are used for term definitions
- http://www.ebi.ac.uk/efo/definition
synonym_property: // prediates used for synonyms
- http://www.ebi.ac.uk/efo/alternative_term
hierarchical_property: // predicates that are hierarchical (like part of) will be included in default tree view
- http://purl.obolibrary.org/obo/BFO_0000050
- http://purl.obolibrary.org/obo/RO_0002202
hidden_property: // any predicates that should be ignored when indexing
- http://www.ebi.ac.uk/efo/has_flag
base_uri: // base URIs for local terms
- http://www.ebi.ac.uk/efo/EFO_
reasoner: OWL2 // can be one of OWL2, EL, NONE - deafult is EL
oboSlims: false // contains OBO style slim annotations
The location of the target ontology shall be specified in the ontology_purl field in the `ols-config.yaml file.
Ontologies from both local files and online resources can be imported.
To add local ontologies, the ontology files need to be first copied to the OLS-docker directory.
By default, the ontology file location is specified as /opt/ols/example.owl.
For example, ontology_purl:file:///opt/ols/example.owl.
To add ontologies from online resources, ontology URLs are required.
Most reference ontologies use the OBO foundry Permanent URLs (PURLs).
The PURLs can be found here.
For example, the location of Data Usage Ontology (DUO) can be specified by adding:
ontology_purl: http://purl.obolibrary.org/obo/duo.owl
to the configuration file.
Ontology metadata for the configuration file can be written by users.
For common public ontologies, the ontology metadata can also be downloaded from either the EBI OLS or the OBO Foundry 5, 4 .
6.3.6.2.1. 2.1 Get ontology metadata from the EBI OLS¶
For ontologies included in the EBI OLS, the metadata can be downloaded directly using the EBI OLS endpoint,
https://www.ebi.ac.uk/ols/api/ols-config?ids=
Metadata of multiple ontologies can be downloaded at the same time.
Here is a list of all the ontologies available at OLS, along with their respective “short name” and other information.
For example, the following command downloads the ontology metadata of EFO and Adverse Event Reporting Ontology (AERO) and saves it as ols-config.yaml:
Warning
The command overwrites the original ols-config.yml file and removes pre-loaded ontologies.
On Windows systems, make sure to wrap the url with quotes, e.g.”
” .
wget -O ols-config.yaml https://www.ebi.ac.uk/ols/api/ols-config\?ids\=aero,efo
To avoid losing pre-loaded ontologies, the metadata of EFO and AERO can also be appended to the already existing ols-config.yml using:
wget -O - https://www.ebi.ac.uk/ols/api/ols-config\?ids\=efo,aero >> ols-config.yaml
Warning
:warning: The file needs to be manually edited by removing the header of the new metadata and adding proper indentation.
For ontologies that are in the OBO foundry, the metadata can also be downloaded from the OBO Foundry GitHub repository.
Additional formatting is required for metadata downloaded from the OBO foundry.
6.3.6.3. 3. Set up OLS in the local environment¶
First be sure the Docker daemon is up running. On Windows and MacOS set-ups, this requires starting the Docker Desktop app.
## Download OLS docker image
git clone https://github.com/EBISPOT/OLS-docker
cd OLS-docker
## Start docker
sudo snap services
sudo snap start docker
## Build OLS docker image
sudo docker build -t ols .
## Run OLS docker image at port 8080
sudo docker run -d -p 8080:8080 --name=OLS -t ols
The local OLS service can be accessed at http://localhost:8080/index
6.3.6.4. 4. Manage ontologies¶
OLS allows the addition, update, and removal of ontologies.
Such ontology management is achieved through editing the configuration file, ols-config.yaml.
The ontology changes can be loaded by rebuilding the image and restarting the service.
6.3.6.4.1. 4.1 Modify OLS configuration¶
To add or remove ontologies, modify corresponding sections in the configuration file.
Loaded ontologies will be updated to the latest version automatically by rebuilding the Docker image.
6.3.6.4.2. 4.2 Rebuild OLS image and restart OLS¶
Before rebuilding the Docker image, the existing container needs to be stopped and removed.
The OLS container can be stopped and removed by providing the container name.
According to the parameters presented on the previous Docker creation command block, the name of the OLS Docker container is “OLS”:
Warning
By rebuilding the OLS image, all loaded ontologies will be automatically updated to the latest version.
## Stop OLS container
docker stop OLS
## Remove OLS container
docker rm OLS
The Docker container can also be stopped and removed using the Docker image ID.
The previous Docker image shall also be removed before rebuilding the image.
## Remove previous docker image
sudo docker rmi ols
To rebuild the Docker image, repeat the commands in Step 3.
## Build OLS docker image
sudo docker build -t ols .
## Run OLS docker image at port 8080
sudo docker run -d -p 8080:8080 --name=OLS -t ols
6.3.6.5. Troubleshooting¶
Loading multiple ontologies from disk:
If more than one ontology are going to be loaded into OLS from disk, the Dockerfile needs modifying before building the Docker container again:
At Line 3 of the configuration file, replace ENV OLS_HOME /opt/ols with ENV OLS_HOME /opt/ols/
At Line 3 of the configuration file, replace
&& java -Dols.obofoundry.ontology.config=foo.yaml -Dols.ontology.config=file://${OLS_HOME}/ols-config.yaml -jar ${OLS_HOME}/ols-config-importer.jar
with:
&& java -Dols.obofoundry.ontology.config=foo.yaml -Dols.ontology.config=file://${OLS_HOME}ols-config.yaml -jar ${OLS_HOME}ols-config-importer.jar
6.3.7. Conclusion¶
The local OLS provides API endpoints for retrieving, submitting, updating, and querying ontology data, as well as a user interface for searching and browsing ontologies and ontology terms.
For example, all ontologies loaded can be queried through endpoint http://localhost:8080/api/ontologies.
A detailed description of OLS functions can be found in the built-in documentation page.
To customize the local OLS user interface, for example, adding corporate logos, please check the OLS source code here.
6.3.8. References¶
References
- 1
A new ontology lookup service at embl-ebi. 2015. URL: http://ceur-ws.org/Vol-1546/paper_29.pdf.
- 2
Ols installation guide. 2021. URL: https://www.ebi.ac.uk/ols/docs/installation-guide.
- 3
R. Côté, F. Reisinger, L. Martens, H. Barsnes, J. A. Vizcaino, and H. Hermjakob. The Ontology Lookup Service: bigger and better. Nucleic Acids Res, 38(Web Server issue):W155–160, Jul 2010.
- 4
R. Jackson, N. Matentzoglu, J. A. Overton, R. Vita, J. P. Balhoff, P. L. Buttigieg, S. Carbon, M. Courtot, A. D. Diehl, D. M. Dooley, W. D. Duncan, N. L. Harris, M. A. Haendel, S. E. Lewis, D. A. Natale, D. Osumi-Sutherland, A. Ruttenberg, L. M. Schriml, B. Smith, C. J. Stoeckert, N. A. Vasilevsky, R. L. Walls, J. Zheng, C. J. Mungall, and B. Peters. OBO Foundry in 2021: operationalizing open data principles to evaluate ontologies. Database (Oxford), 10 2021.
- 5
B. Smith, M. Ashburner, C. Rosse, J. Bard, W. Bug, W. Ceusters, L. J. Goldberg, K. Eilbeck, A. Ireland, C. J. Mungall, N. Leontis, P. Rocca-Serra, A. Ruttenberg, S. A. Sansone, R. H. Scheuermann, N. Shah, P. L. Whetzel, and S. Lewis. The OBO Foundry: coordinated evolution of ontologies to support biomedical data integration. Nat Biotechnol, 25(11):1251–1255, Nov 2007.
6.3.8.1. What to read next?¶
FAIRsharing records appearing in this recipe:
6.3.9. Authors¶
Authors
Name |
ORCID |
Affiliation |
Type |
ELIXIR Node |
Contribution |
|---|---|---|---|---|---|
EMBL-EBI |
|
Writing - Original Draft |
|||
Barcelona Supercomputing Centre |
|
Writing - Original Draft |
|||
Boehringer-Ingelheim AG |
Writing - Review & Editing |
||||
University of Oxford |
|
Writing - Review & Editing |
